libc.info-2 299 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971397239733974397539763977397839793980398139823983398439853986398739883989399039913992399339943995399639973998399940004001400240034004400540064007400840094010401140124013401440154016401740184019402040214022402340244025402640274028402940304031403240334034403540364037403840394040404140424043404440454046404740484049405040514052405340544055405640574058405940604061406240634064406540664067406840694070407140724073407440754076407740784079408040814082408340844085408640874088408940904091409240934094409540964097409840994100410141024103410441054106410741084109411041114112411341144115411641174118411941204121412241234124412541264127412841294130413141324133413441354136413741384139414041414142414341444145414641474148414941504151415241534154415541564157415841594160416141624163416441654166416741684169417041714172417341744175417641774178417941804181418241834184418541864187418841894190419141924193419441954196419741984199420042014202420342044205420642074208420942104211421242134214421542164217421842194220422142224223422442254226422742284229423042314232423342344235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262426342644265426642674268426942704271427242734274427542764277427842794280428142824283428442854286428742884289429042914292429342944295429642974298429943004301430243034304430543064307430843094310431143124313431443154316431743184319432043214322432343244325432643274328432943304331433243334334433543364337433843394340434143424343434443454346434743484349435043514352435343544355435643574358435943604361436243634364436543664367436843694370437143724373437443754376437743784379438043814382438343844385438643874388438943904391439243934394439543964397439843994400440144024403440444054406440744084409441044114412441344144415441644174418441944204421442244234424442544264427442844294430443144324433443444354436443744384439444044414442444344444445444644474448444944504451445244534454445544564457445844594460446144624463446444654466446744684469447044714472447344744475447644774478447944804481448244834484448544864487448844894490449144924493449444954496449744984499450045014502450345044505450645074508450945104511451245134514451545164517451845194520452145224523452445254526452745284529453045314532453345344535453645374538453945404541454245434544454545464547454845494550455145524553455445554556455745584559456045614562456345644565456645674568456945704571457245734574457545764577457845794580458145824583458445854586458745884589459045914592459345944595459645974598459946004601460246034604460546064607460846094610461146124613461446154616461746184619462046214622462346244625462646274628462946304631463246334634463546364637463846394640464146424643464446454646464746484649465046514652465346544655465646574658465946604661466246634664466546664667466846694670467146724673467446754676467746784679468046814682468346844685468646874688468946904691469246934694469546964697469846994700470147024703470447054706470747084709471047114712471347144715471647174718471947204721472247234724472547264727472847294730473147324733473447354736473747384739474047414742474347444745474647474748474947504751475247534754475547564757475847594760476147624763476447654766476747684769477047714772477347744775477647774778477947804781478247834784478547864787478847894790479147924793479447954796479747984799480048014802480348044805480648074808480948104811481248134814481548164817481848194820482148224823482448254826482748284829483048314832483348344835483648374838483948404841484248434844484548464847484848494850485148524853485448554856485748584859486048614862486348644865486648674868486948704871487248734874487548764877487848794880488148824883488448854886488748884889489048914892489348944895489648974898489949004901490249034904490549064907490849094910491149124913491449154916491749184919492049214922492349244925492649274928492949304931493249334934493549364937493849394940494149424943494449454946494749484949495049514952495349544955495649574958495949604961496249634964496549664967496849694970497149724973497449754976497749784979498049814982498349844985498649874988498949904991499249934994499549964997499849995000500150025003500450055006500750085009501050115012501350145015501650175018501950205021502250235024502550265027502850295030503150325033503450355036503750385039504050415042504350445045504650475048504950505051505250535054505550565057505850595060506150625063506450655066506750685069507050715072507350745075507650775078507950805081508250835084508550865087508850895090509150925093509450955096509750985099510051015102510351045105510651075108510951105111511251135114511551165117511851195120512151225123512451255126512751285129513051315132513351345135513651375138513951405141514251435144514551465147514851495150515151525153515451555156515751585159516051615162516351645165516651675168516951705171517251735174517551765177517851795180518151825183518451855186518751885189519051915192519351945195519651975198519952005201520252035204520552065207520852095210521152125213521452155216521752185219522052215222522352245225522652275228522952305231523252335234523552365237523852395240524152425243524452455246524752485249525052515252525352545255525652575258525952605261526252635264526552665267526852695270527152725273527452755276527752785279528052815282528352845285528652875288528952905291529252935294529552965297529852995300530153025303530453055306530753085309531053115312531353145315531653175318531953205321532253235324532553265327532853295330533153325333533453355336533753385339534053415342534353445345534653475348534953505351535253535354535553565357535853595360536153625363536453655366536753685369537053715372537353745375537653775378537953805381538253835384538553865387538853895390539153925393539453955396539753985399540054015402540354045405540654075408540954105411541254135414541554165417541854195420542154225423542454255426542754285429543054315432543354345435543654375438543954405441544254435444544554465447544854495450545154525453545454555456545754585459546054615462546354645465546654675468546954705471547254735474547554765477547854795480548154825483548454855486548754885489549054915492549354945495549654975498549955005501550255035504550555065507550855095510551155125513551455155516551755185519552055215522552355245525552655275528552955305531553255335534553555365537553855395540554155425543554455455546554755485549555055515552555355545555555655575558555955605561556255635564556555665567556855695570557155725573557455755576557755785579558055815582558355845585558655875588558955905591559255935594559555965597559855995600560156025603560456055606560756085609561056115612561356145615561656175618561956205621562256235624562556265627562856295630563156325633563456355636563756385639564056415642564356445645564656475648564956505651565256535654565556565657565856595660566156625663566456655666566756685669567056715672567356745675567656775678567956805681568256835684568556865687568856895690569156925693569456955696569756985699570057015702570357045705570657075708570957105711571257135714571557165717571857195720572157225723572457255726572757285729573057315732573357345735573657375738573957405741574257435744574557465747574857495750575157525753575457555756575757585759576057615762576357645765576657675768576957705771577257735774577557765777577857795780578157825783578457855786578757885789579057915792579357945795579657975798579958005801580258035804580558065807580858095810581158125813581458155816581758185819582058215822582358245825582658275828582958305831583258335834583558365837583858395840584158425843584458455846584758485849585058515852585358545855585658575858585958605861586258635864586558665867586858695870587158725873587458755876587758785879588058815882588358845885588658875888588958905891589258935894589558965897589858995900590159025903590459055906590759085909591059115912591359145915591659175918591959205921592259235924592559265927592859295930593159325933593459355936593759385939594059415942594359445945594659475948594959505951595259535954595559565957595859595960596159625963596459655966596759685969597059715972597359745975597659775978597959805981598259835984598559865987598859895990599159925993599459955996599759985999600060016002600360046005600660076008600960106011601260136014601560166017601860196020602160226023602460256026602760286029603060316032603360346035603660376038603960406041604260436044604560466047604860496050605160526053605460556056605760586059606060616062606360646065606660676068606960706071607260736074607560766077607860796080608160826083608460856086608760886089609060916092609360946095609660976098609961006101610261036104610561066107610861096110611161126113611461156116611761186119612061216122612361246125612661276128612961306131613261336134613561366137613861396140614161426143614461456146614761486149615061516152615361546155615661576158615961606161616261636164616561666167616861696170617161726173617461756176617761786179618061816182618361846185618661876188618961906191619261936194619561966197619861996200620162026203620462056206620762086209621062116212621362146215621662176218621962206221622262236224622562266227622862296230623162326233623462356236623762386239624062416242624362446245624662476248624962506251625262536254625562566257625862596260626162626263626462656266626762686269627062716272627362746275627662776278627962806281628262836284628562866287628862896290629162926293629462956296629762986299630063016302630363046305630663076308630963106311631263136314631563166317631863196320632163226323632463256326632763286329633063316332633363346335633663376338633963406341634263436344634563466347634863496350635163526353635463556356635763586359636063616362636363646365636663676368636963706371637263736374637563766377637863796380638163826383638463856386638763886389639063916392639363946395639663976398639964006401640264036404640564066407640864096410641164126413641464156416641764186419642064216422642364246425642664276428642964306431643264336434643564366437643864396440644164426443644464456446644764486449645064516452645364546455645664576458645964606461646264636464646564666467646864696470647164726473647464756476647764786479648064816482648364846485648664876488648964906491649264936494649564966497649864996500650165026503650465056506650765086509651065116512651365146515651665176518651965206521652265236524652565266527652865296530653165326533653465356536653765386539654065416542654365446545654665476548654965506551655265536554655565566557655865596560656165626563656465656566656765686569657065716572657365746575657665776578657965806581658265836584658565866587658865896590659165926593659465956596659765986599660066016602660366046605660666076608660966106611661266136614661566166617661866196620662166226623662466256626662766286629663066316632663366346635663666376638663966406641664266436644664566466647664866496650665166526653665466556656665766586659666066616662666366646665666666676668666966706671667266736674667566766677667866796680668166826683668466856686668766886689669066916692669366946695669666976698669967006701670267036704670567066707670867096710671167126713671467156716671767186719672067216722672367246725672667276728672967306731673267336734673567366737673867396740674167426743674467456746674767486749675067516752675367546755675667576758675967606761676267636764676567666767676867696770677167726773677467756776677767786779678067816782678367846785678667876788678967906791679267936794679567966797679867996800680168026803680468056806680768086809681068116812681368146815681668176818681968206821682268236824682568266827682868296830683168326833683468356836683768386839684068416842684368446845684668476848684968506851685268536854685568566857685868596860686168626863686468656866686768686869687068716872687368746875687668776878687968806881688268836884688568866887688868896890689168926893689468956896689768986899690069016902690369046905690669076908690969106911691269136914691569166917691869196920692169226923692469256926692769286929693069316932693369346935693669376938693969406941694269436944694569466947694869496950695169526953695469556956695769586959696069616962696369646965696669676968696969706971697269736974697569766977697869796980698169826983698469856986698769886989699069916992699369946995699669976998699970007001700270037004700570067007700870097010701170127013701470157016701770187019702070217022702370247025702670277028702970307031703270337034703570367037703870397040704170427043704470457046704770487049705070517052705370547055705670577058705970607061706270637064706570667067706870697070707170727073707470757076707770787079708070817082708370847085708670877088708970907091709270937094709570967097709870997100710171027103710471057106710771087109711071117112711371147115711671177118711971207121712271237124712571267127712871297130713171327133713471357136713771387139714071417142714371447145714671477148714971507151715271537154715571567157715871597160716171627163716471657166716771687169717071717172717371747175717671777178717971807181718271837184718571867187718871897190719171927193719471957196719771987199720072017202720372047205720672077208720972107211721272137214721572167217721872197220722172227223722472257226722772287229723072317232723372347235723672377238723972407241724272437244724572467247724872497250725172527253725472557256725772587259726072617262726372647265726672677268726972707271727272737274727572767277727872797280728172827283728472857286728772887289729072917292729372947295729672977298729973007301730273037304730573067307730873097310731173127313731473157316731773187319732073217322732373247325732673277328732973307331
  1. This is libc.info, produced by makeinfo version 5.2 from libc.texinfo.
  2. This file documents the GNU C Library.
  3. This is ‘The GNU C Library Reference Manual’, for version 2.25.
  4. Copyright © 1993–2017 Free Software Foundation, Inc.
  5. Permission is granted to copy, distribute and/or modify this document
  6. under the terms of the GNU Free Documentation License, Version 1.3 or
  7. any later version published by the Free Software Foundation; with the
  8. Invariant Sections being “Free Software Needs Free Documentation” and
  9. “GNU Lesser General Public License”, the Front-Cover texts being “A GNU
  10. Manual”, and with the Back-Cover Texts as in (a) below. A copy of the
  11. license is included in the section entitled "GNU Free Documentation
  12. License".
  13. (a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
  14. modify this GNU manual. Buying copies from the FSF supports it in
  15. developing GNU and promoting software freedom.”
  16. INFO-DIR-SECTION Software libraries
  17. START-INFO-DIR-ENTRY
  18. * Libc: (libc). C library.
  19. END-INFO-DIR-ENTRY
  20. INFO-DIR-SECTION GNU C library functions and macros
  21. START-INFO-DIR-ENTRY
  22. * a64l: (libc)Encode Binary Data.
  23. * abort: (libc)Aborting a Program.
  24. * abs: (libc)Absolute Value.
  25. * accept: (libc)Accepting Connections.
  26. * access: (libc)Testing File Access.
  27. * acosf: (libc)Inverse Trig Functions.
  28. * acoshf: (libc)Hyperbolic Functions.
  29. * acosh: (libc)Hyperbolic Functions.
  30. * acoshl: (libc)Hyperbolic Functions.
  31. * acos: (libc)Inverse Trig Functions.
  32. * acosl: (libc)Inverse Trig Functions.
  33. * addmntent: (libc)mtab.
  34. * addseverity: (libc)Adding Severity Classes.
  35. * adjtime: (libc)High-Resolution Calendar.
  36. * adjtimex: (libc)High-Resolution Calendar.
  37. * aio_cancel64: (libc)Cancel AIO Operations.
  38. * aio_cancel: (libc)Cancel AIO Operations.
  39. * aio_error64: (libc)Status of AIO Operations.
  40. * aio_error: (libc)Status of AIO Operations.
  41. * aio_fsync64: (libc)Synchronizing AIO Operations.
  42. * aio_fsync: (libc)Synchronizing AIO Operations.
  43. * aio_init: (libc)Configuration of AIO.
  44. * aio_read64: (libc)Asynchronous Reads/Writes.
  45. * aio_read: (libc)Asynchronous Reads/Writes.
  46. * aio_return64: (libc)Status of AIO Operations.
  47. * aio_return: (libc)Status of AIO Operations.
  48. * aio_suspend64: (libc)Synchronizing AIO Operations.
  49. * aio_suspend: (libc)Synchronizing AIO Operations.
  50. * aio_write64: (libc)Asynchronous Reads/Writes.
  51. * aio_write: (libc)Asynchronous Reads/Writes.
  52. * alarm: (libc)Setting an Alarm.
  53. * aligned_alloc: (libc)Aligned Memory Blocks.
  54. * alloca: (libc)Variable Size Automatic.
  55. * alphasort64: (libc)Scanning Directory Content.
  56. * alphasort: (libc)Scanning Directory Content.
  57. * ALTWERASE: (libc)Local Modes.
  58. * ARG_MAX: (libc)General Limits.
  59. * argp_error: (libc)Argp Helper Functions.
  60. * ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions.
  61. * argp_failure: (libc)Argp Helper Functions.
  62. * argp_help: (libc)Argp Help.
  63. * argp_parse: (libc)Argp.
  64. * argp_state_help: (libc)Argp Helper Functions.
  65. * argp_usage: (libc)Argp Helper Functions.
  66. * argz_add: (libc)Argz Functions.
  67. * argz_add_sep: (libc)Argz Functions.
  68. * argz_append: (libc)Argz Functions.
  69. * argz_count: (libc)Argz Functions.
  70. * argz_create: (libc)Argz Functions.
  71. * argz_create_sep: (libc)Argz Functions.
  72. * argz_delete: (libc)Argz Functions.
  73. * argz_extract: (libc)Argz Functions.
  74. * argz_insert: (libc)Argz Functions.
  75. * argz_next: (libc)Argz Functions.
  76. * argz_replace: (libc)Argz Functions.
  77. * argz_stringify: (libc)Argz Functions.
  78. * asctime: (libc)Formatting Calendar Time.
  79. * asctime_r: (libc)Formatting Calendar Time.
  80. * asinf: (libc)Inverse Trig Functions.
  81. * asinhf: (libc)Hyperbolic Functions.
  82. * asinh: (libc)Hyperbolic Functions.
  83. * asinhl: (libc)Hyperbolic Functions.
  84. * asin: (libc)Inverse Trig Functions.
  85. * asinl: (libc)Inverse Trig Functions.
  86. * asprintf: (libc)Dynamic Output.
  87. * assert: (libc)Consistency Checking.
  88. * assert_perror: (libc)Consistency Checking.
  89. * atan2f: (libc)Inverse Trig Functions.
  90. * atan2: (libc)Inverse Trig Functions.
  91. * atan2l: (libc)Inverse Trig Functions.
  92. * atanf: (libc)Inverse Trig Functions.
  93. * atanhf: (libc)Hyperbolic Functions.
  94. * atanh: (libc)Hyperbolic Functions.
  95. * atanhl: (libc)Hyperbolic Functions.
  96. * atan: (libc)Inverse Trig Functions.
  97. * atanl: (libc)Inverse Trig Functions.
  98. * atexit: (libc)Cleanups on Exit.
  99. * atof: (libc)Parsing of Floats.
  100. * atoi: (libc)Parsing of Integers.
  101. * atol: (libc)Parsing of Integers.
  102. * atoll: (libc)Parsing of Integers.
  103. * backtrace: (libc)Backtraces.
  104. * backtrace_symbols_fd: (libc)Backtraces.
  105. * backtrace_symbols: (libc)Backtraces.
  106. * basename: (libc)Finding Tokens in a String.
  107. * basename: (libc)Finding Tokens in a String.
  108. * BC_BASE_MAX: (libc)Utility Limits.
  109. * BC_DIM_MAX: (libc)Utility Limits.
  110. * bcmp: (libc)String/Array Comparison.
  111. * bcopy: (libc)Copying Strings and Arrays.
  112. * BC_SCALE_MAX: (libc)Utility Limits.
  113. * BC_STRING_MAX: (libc)Utility Limits.
  114. * bind: (libc)Setting Address.
  115. * bind_textdomain_codeset: (libc)Charset conversion in gettext.
  116. * bindtextdomain: (libc)Locating gettext catalog.
  117. * BRKINT: (libc)Input Modes.
  118. * brk: (libc)Resizing the Data Segment.
  119. * bsearch: (libc)Array Search Function.
  120. * btowc: (libc)Converting a Character.
  121. * BUFSIZ: (libc)Controlling Buffering.
  122. * bzero: (libc)Copying Strings and Arrays.
  123. * cabsf: (libc)Absolute Value.
  124. * cabs: (libc)Absolute Value.
  125. * cabsl: (libc)Absolute Value.
  126. * cacosf: (libc)Inverse Trig Functions.
  127. * cacoshf: (libc)Hyperbolic Functions.
  128. * cacosh: (libc)Hyperbolic Functions.
  129. * cacoshl: (libc)Hyperbolic Functions.
  130. * cacos: (libc)Inverse Trig Functions.
  131. * cacosl: (libc)Inverse Trig Functions.
  132. * calloc: (libc)Allocating Cleared Space.
  133. * canonicalize_file_name: (libc)Symbolic Links.
  134. * canonicalizef: (libc)FP Bit Twiddling.
  135. * canonicalize: (libc)FP Bit Twiddling.
  136. * canonicalizel: (libc)FP Bit Twiddling.
  137. * cargf: (libc)Operations on Complex.
  138. * carg: (libc)Operations on Complex.
  139. * cargl: (libc)Operations on Complex.
  140. * casinf: (libc)Inverse Trig Functions.
  141. * casinhf: (libc)Hyperbolic Functions.
  142. * casinh: (libc)Hyperbolic Functions.
  143. * casinhl: (libc)Hyperbolic Functions.
  144. * casin: (libc)Inverse Trig Functions.
  145. * casinl: (libc)Inverse Trig Functions.
  146. * catanf: (libc)Inverse Trig Functions.
  147. * catanhf: (libc)Hyperbolic Functions.
  148. * catanh: (libc)Hyperbolic Functions.
  149. * catanhl: (libc)Hyperbolic Functions.
  150. * catan: (libc)Inverse Trig Functions.
  151. * catanl: (libc)Inverse Trig Functions.
  152. * catclose: (libc)The catgets Functions.
  153. * catgets: (libc)The catgets Functions.
  154. * catopen: (libc)The catgets Functions.
  155. * cbc_crypt: (libc)DES Encryption.
  156. * cbrtf: (libc)Exponents and Logarithms.
  157. * cbrt: (libc)Exponents and Logarithms.
  158. * cbrtl: (libc)Exponents and Logarithms.
  159. * ccosf: (libc)Trig Functions.
  160. * ccoshf: (libc)Hyperbolic Functions.
  161. * ccosh: (libc)Hyperbolic Functions.
  162. * ccoshl: (libc)Hyperbolic Functions.
  163. * ccos: (libc)Trig Functions.
  164. * ccosl: (libc)Trig Functions.
  165. * CCTS_OFLOW: (libc)Control Modes.
  166. * ceilf: (libc)Rounding Functions.
  167. * ceil: (libc)Rounding Functions.
  168. * ceill: (libc)Rounding Functions.
  169. * cexpf: (libc)Exponents and Logarithms.
  170. * cexp: (libc)Exponents and Logarithms.
  171. * cexpl: (libc)Exponents and Logarithms.
  172. * cfgetispeed: (libc)Line Speed.
  173. * cfgetospeed: (libc)Line Speed.
  174. * cfmakeraw: (libc)Noncanonical Input.
  175. * cfree: (libc)Freeing after Malloc.
  176. * cfsetispeed: (libc)Line Speed.
  177. * cfsetospeed: (libc)Line Speed.
  178. * cfsetspeed: (libc)Line Speed.
  179. * chdir: (libc)Working Directory.
  180. * CHILD_MAX: (libc)General Limits.
  181. * chmod: (libc)Setting Permissions.
  182. * chown: (libc)File Owner.
  183. * CIGNORE: (libc)Control Modes.
  184. * cimagf: (libc)Operations on Complex.
  185. * cimag: (libc)Operations on Complex.
  186. * cimagl: (libc)Operations on Complex.
  187. * clearenv: (libc)Environment Access.
  188. * clearerr: (libc)Error Recovery.
  189. * clearerr_unlocked: (libc)Error Recovery.
  190. * CLK_TCK: (libc)Processor Time.
  191. * CLOCAL: (libc)Control Modes.
  192. * clock: (libc)CPU Time.
  193. * CLOCKS_PER_SEC: (libc)CPU Time.
  194. * clog10f: (libc)Exponents and Logarithms.
  195. * clog10: (libc)Exponents and Logarithms.
  196. * clog10l: (libc)Exponents and Logarithms.
  197. * clogf: (libc)Exponents and Logarithms.
  198. * clog: (libc)Exponents and Logarithms.
  199. * clogl: (libc)Exponents and Logarithms.
  200. * closedir: (libc)Reading/Closing Directory.
  201. * close: (libc)Opening and Closing Files.
  202. * closelog: (libc)closelog.
  203. * COLL_WEIGHTS_MAX: (libc)Utility Limits.
  204. * _Complex_I: (libc)Complex Numbers.
  205. * confstr: (libc)String Parameters.
  206. * conjf: (libc)Operations on Complex.
  207. * conj: (libc)Operations on Complex.
  208. * conjl: (libc)Operations on Complex.
  209. * connect: (libc)Connecting.
  210. * copysignf: (libc)FP Bit Twiddling.
  211. * copysign: (libc)FP Bit Twiddling.
  212. * copysignl: (libc)FP Bit Twiddling.
  213. * cosf: (libc)Trig Functions.
  214. * coshf: (libc)Hyperbolic Functions.
  215. * cosh: (libc)Hyperbolic Functions.
  216. * coshl: (libc)Hyperbolic Functions.
  217. * cos: (libc)Trig Functions.
  218. * cosl: (libc)Trig Functions.
  219. * cpowf: (libc)Exponents and Logarithms.
  220. * cpow: (libc)Exponents and Logarithms.
  221. * cpowl: (libc)Exponents and Logarithms.
  222. * cprojf: (libc)Operations on Complex.
  223. * cproj: (libc)Operations on Complex.
  224. * cprojl: (libc)Operations on Complex.
  225. * CPU_CLR: (libc)CPU Affinity.
  226. * CPU_ISSET: (libc)CPU Affinity.
  227. * CPU_SET: (libc)CPU Affinity.
  228. * CPU_SETSIZE: (libc)CPU Affinity.
  229. * CPU_ZERO: (libc)CPU Affinity.
  230. * CREAD: (libc)Control Modes.
  231. * crealf: (libc)Operations on Complex.
  232. * creal: (libc)Operations on Complex.
  233. * creall: (libc)Operations on Complex.
  234. * creat64: (libc)Opening and Closing Files.
  235. * creat: (libc)Opening and Closing Files.
  236. * CRTS_IFLOW: (libc)Control Modes.
  237. * crypt: (libc)crypt.
  238. * crypt_r: (libc)crypt.
  239. * CS5: (libc)Control Modes.
  240. * CS6: (libc)Control Modes.
  241. * CS7: (libc)Control Modes.
  242. * CS8: (libc)Control Modes.
  243. * csinf: (libc)Trig Functions.
  244. * csinhf: (libc)Hyperbolic Functions.
  245. * csinh: (libc)Hyperbolic Functions.
  246. * csinhl: (libc)Hyperbolic Functions.
  247. * csin: (libc)Trig Functions.
  248. * csinl: (libc)Trig Functions.
  249. * CSIZE: (libc)Control Modes.
  250. * csqrtf: (libc)Exponents and Logarithms.
  251. * csqrt: (libc)Exponents and Logarithms.
  252. * csqrtl: (libc)Exponents and Logarithms.
  253. * CSTOPB: (libc)Control Modes.
  254. * ctanf: (libc)Trig Functions.
  255. * ctanhf: (libc)Hyperbolic Functions.
  256. * ctanh: (libc)Hyperbolic Functions.
  257. * ctanhl: (libc)Hyperbolic Functions.
  258. * ctan: (libc)Trig Functions.
  259. * ctanl: (libc)Trig Functions.
  260. * ctermid: (libc)Identifying the Terminal.
  261. * ctime: (libc)Formatting Calendar Time.
  262. * ctime_r: (libc)Formatting Calendar Time.
  263. * cuserid: (libc)Who Logged In.
  264. * dcgettext: (libc)Translation with gettext.
  265. * dcngettext: (libc)Advanced gettext functions.
  266. * DES_FAILED: (libc)DES Encryption.
  267. * des_setparity: (libc)DES Encryption.
  268. * dgettext: (libc)Translation with gettext.
  269. * difftime: (libc)Elapsed Time.
  270. * dirfd: (libc)Opening a Directory.
  271. * dirname: (libc)Finding Tokens in a String.
  272. * div: (libc)Integer Division.
  273. * dngettext: (libc)Advanced gettext functions.
  274. * drand48: (libc)SVID Random.
  275. * drand48_r: (libc)SVID Random.
  276. * dremf: (libc)Remainder Functions.
  277. * drem: (libc)Remainder Functions.
  278. * dreml: (libc)Remainder Functions.
  279. * DTTOIF: (libc)Directory Entries.
  280. * dup2: (libc)Duplicating Descriptors.
  281. * dup: (libc)Duplicating Descriptors.
  282. * E2BIG: (libc)Error Codes.
  283. * EACCES: (libc)Error Codes.
  284. * EADDRINUSE: (libc)Error Codes.
  285. * EADDRNOTAVAIL: (libc)Error Codes.
  286. * EADV: (libc)Error Codes.
  287. * EAFNOSUPPORT: (libc)Error Codes.
  288. * EAGAIN: (libc)Error Codes.
  289. * EALREADY: (libc)Error Codes.
  290. * EAUTH: (libc)Error Codes.
  291. * EBACKGROUND: (libc)Error Codes.
  292. * EBADE: (libc)Error Codes.
  293. * EBADFD: (libc)Error Codes.
  294. * EBADF: (libc)Error Codes.
  295. * EBADMSG: (libc)Error Codes.
  296. * EBADR: (libc)Error Codes.
  297. * EBADRPC: (libc)Error Codes.
  298. * EBADRQC: (libc)Error Codes.
  299. * EBADSLT: (libc)Error Codes.
  300. * EBFONT: (libc)Error Codes.
  301. * EBUSY: (libc)Error Codes.
  302. * ECANCELED: (libc)Error Codes.
  303. * ecb_crypt: (libc)DES Encryption.
  304. * ECHILD: (libc)Error Codes.
  305. * ECHOCTL: (libc)Local Modes.
  306. * ECHOE: (libc)Local Modes.
  307. * ECHOKE: (libc)Local Modes.
  308. * ECHOK: (libc)Local Modes.
  309. * ECHO: (libc)Local Modes.
  310. * ECHONL: (libc)Local Modes.
  311. * ECHOPRT: (libc)Local Modes.
  312. * ECHRNG: (libc)Error Codes.
  313. * ECOMM: (libc)Error Codes.
  314. * ECONNABORTED: (libc)Error Codes.
  315. * ECONNREFUSED: (libc)Error Codes.
  316. * ECONNRESET: (libc)Error Codes.
  317. * ecvt: (libc)System V Number Conversion.
  318. * ecvt_r: (libc)System V Number Conversion.
  319. * EDEADLK: (libc)Error Codes.
  320. * EDEADLOCK: (libc)Error Codes.
  321. * EDESTADDRREQ: (libc)Error Codes.
  322. * EDIED: (libc)Error Codes.
  323. * ED: (libc)Error Codes.
  324. * EDOM: (libc)Error Codes.
  325. * EDOTDOT: (libc)Error Codes.
  326. * EDQUOT: (libc)Error Codes.
  327. * EEXIST: (libc)Error Codes.
  328. * EFAULT: (libc)Error Codes.
  329. * EFBIG: (libc)Error Codes.
  330. * EFTYPE: (libc)Error Codes.
  331. * EGRATUITOUS: (libc)Error Codes.
  332. * EGREGIOUS: (libc)Error Codes.
  333. * EHOSTDOWN: (libc)Error Codes.
  334. * EHOSTUNREACH: (libc)Error Codes.
  335. * EHWPOISON: (libc)Error Codes.
  336. * EIDRM: (libc)Error Codes.
  337. * EIEIO: (libc)Error Codes.
  338. * EILSEQ: (libc)Error Codes.
  339. * EINPROGRESS: (libc)Error Codes.
  340. * EINTR: (libc)Error Codes.
  341. * EINVAL: (libc)Error Codes.
  342. * EIO: (libc)Error Codes.
  343. * EISCONN: (libc)Error Codes.
  344. * EISDIR: (libc)Error Codes.
  345. * EISNAM: (libc)Error Codes.
  346. * EKEYEXPIRED: (libc)Error Codes.
  347. * EKEYREJECTED: (libc)Error Codes.
  348. * EKEYREVOKED: (libc)Error Codes.
  349. * EL2HLT: (libc)Error Codes.
  350. * EL2NSYNC: (libc)Error Codes.
  351. * EL3HLT: (libc)Error Codes.
  352. * EL3RST: (libc)Error Codes.
  353. * ELIBACC: (libc)Error Codes.
  354. * ELIBBAD: (libc)Error Codes.
  355. * ELIBEXEC: (libc)Error Codes.
  356. * ELIBMAX: (libc)Error Codes.
  357. * ELIBSCN: (libc)Error Codes.
  358. * ELNRNG: (libc)Error Codes.
  359. * ELOOP: (libc)Error Codes.
  360. * EMEDIUMTYPE: (libc)Error Codes.
  361. * EMFILE: (libc)Error Codes.
  362. * EMLINK: (libc)Error Codes.
  363. * EMSGSIZE: (libc)Error Codes.
  364. * EMULTIHOP: (libc)Error Codes.
  365. * ENAMETOOLONG: (libc)Error Codes.
  366. * ENAVAIL: (libc)Error Codes.
  367. * encrypt: (libc)DES Encryption.
  368. * encrypt_r: (libc)DES Encryption.
  369. * endfsent: (libc)fstab.
  370. * endgrent: (libc)Scanning All Groups.
  371. * endhostent: (libc)Host Names.
  372. * endmntent: (libc)mtab.
  373. * endnetent: (libc)Networks Database.
  374. * endnetgrent: (libc)Lookup Netgroup.
  375. * endprotoent: (libc)Protocols Database.
  376. * endpwent: (libc)Scanning All Users.
  377. * endservent: (libc)Services Database.
  378. * endutent: (libc)Manipulating the Database.
  379. * endutxent: (libc)XPG Functions.
  380. * ENEEDAUTH: (libc)Error Codes.
  381. * ENETDOWN: (libc)Error Codes.
  382. * ENETRESET: (libc)Error Codes.
  383. * ENETUNREACH: (libc)Error Codes.
  384. * ENFILE: (libc)Error Codes.
  385. * ENOANO: (libc)Error Codes.
  386. * ENOBUFS: (libc)Error Codes.
  387. * ENOCSI: (libc)Error Codes.
  388. * ENODATA: (libc)Error Codes.
  389. * ENODEV: (libc)Error Codes.
  390. * ENOENT: (libc)Error Codes.
  391. * ENOEXEC: (libc)Error Codes.
  392. * ENOKEY: (libc)Error Codes.
  393. * ENOLCK: (libc)Error Codes.
  394. * ENOLINK: (libc)Error Codes.
  395. * ENOMEDIUM: (libc)Error Codes.
  396. * ENOMEM: (libc)Error Codes.
  397. * ENOMSG: (libc)Error Codes.
  398. * ENONET: (libc)Error Codes.
  399. * ENOPKG: (libc)Error Codes.
  400. * ENOPROTOOPT: (libc)Error Codes.
  401. * ENOSPC: (libc)Error Codes.
  402. * ENOSR: (libc)Error Codes.
  403. * ENOSTR: (libc)Error Codes.
  404. * ENOSYS: (libc)Error Codes.
  405. * ENOTBLK: (libc)Error Codes.
  406. * ENOTCONN: (libc)Error Codes.
  407. * ENOTDIR: (libc)Error Codes.
  408. * ENOTEMPTY: (libc)Error Codes.
  409. * ENOTNAM: (libc)Error Codes.
  410. * ENOTRECOVERABLE: (libc)Error Codes.
  411. * ENOTSOCK: (libc)Error Codes.
  412. * ENOTSUP: (libc)Error Codes.
  413. * ENOTTY: (libc)Error Codes.
  414. * ENOTUNIQ: (libc)Error Codes.
  415. * envz_add: (libc)Envz Functions.
  416. * envz_entry: (libc)Envz Functions.
  417. * envz_get: (libc)Envz Functions.
  418. * envz_merge: (libc)Envz Functions.
  419. * envz_remove: (libc)Envz Functions.
  420. * envz_strip: (libc)Envz Functions.
  421. * ENXIO: (libc)Error Codes.
  422. * EOF: (libc)EOF and Errors.
  423. * EOPNOTSUPP: (libc)Error Codes.
  424. * EOVERFLOW: (libc)Error Codes.
  425. * EOWNERDEAD: (libc)Error Codes.
  426. * EPERM: (libc)Error Codes.
  427. * EPFNOSUPPORT: (libc)Error Codes.
  428. * EPIPE: (libc)Error Codes.
  429. * EPROCLIM: (libc)Error Codes.
  430. * EPROCUNAVAIL: (libc)Error Codes.
  431. * EPROGMISMATCH: (libc)Error Codes.
  432. * EPROGUNAVAIL: (libc)Error Codes.
  433. * EPROTO: (libc)Error Codes.
  434. * EPROTONOSUPPORT: (libc)Error Codes.
  435. * EPROTOTYPE: (libc)Error Codes.
  436. * EQUIV_CLASS_MAX: (libc)Utility Limits.
  437. * erand48: (libc)SVID Random.
  438. * erand48_r: (libc)SVID Random.
  439. * ERANGE: (libc)Error Codes.
  440. * EREMCHG: (libc)Error Codes.
  441. * EREMOTEIO: (libc)Error Codes.
  442. * EREMOTE: (libc)Error Codes.
  443. * ERESTART: (libc)Error Codes.
  444. * erfcf: (libc)Special Functions.
  445. * erfc: (libc)Special Functions.
  446. * erfcl: (libc)Special Functions.
  447. * erff: (libc)Special Functions.
  448. * ERFKILL: (libc)Error Codes.
  449. * erf: (libc)Special Functions.
  450. * erfl: (libc)Special Functions.
  451. * EROFS: (libc)Error Codes.
  452. * ERPCMISMATCH: (libc)Error Codes.
  453. * err: (libc)Error Messages.
  454. * errno: (libc)Checking for Errors.
  455. * error_at_line: (libc)Error Messages.
  456. * error: (libc)Error Messages.
  457. * errx: (libc)Error Messages.
  458. * ESHUTDOWN: (libc)Error Codes.
  459. * ESOCKTNOSUPPORT: (libc)Error Codes.
  460. * ESPIPE: (libc)Error Codes.
  461. * ESRCH: (libc)Error Codes.
  462. * ESRMNT: (libc)Error Codes.
  463. * ESTALE: (libc)Error Codes.
  464. * ESTRPIPE: (libc)Error Codes.
  465. * ETIMEDOUT: (libc)Error Codes.
  466. * ETIME: (libc)Error Codes.
  467. * ETOOMANYREFS: (libc)Error Codes.
  468. * ETXTBSY: (libc)Error Codes.
  469. * EUCLEAN: (libc)Error Codes.
  470. * EUNATCH: (libc)Error Codes.
  471. * EUSERS: (libc)Error Codes.
  472. * EWOULDBLOCK: (libc)Error Codes.
  473. * EXDEV: (libc)Error Codes.
  474. * execle: (libc)Executing a File.
  475. * execl: (libc)Executing a File.
  476. * execlp: (libc)Executing a File.
  477. * execve: (libc)Executing a File.
  478. * execv: (libc)Executing a File.
  479. * execvp: (libc)Executing a File.
  480. * EXFULL: (libc)Error Codes.
  481. * EXIT_FAILURE: (libc)Exit Status.
  482. * exit: (libc)Normal Termination.
  483. * _exit: (libc)Termination Internals.
  484. * _Exit: (libc)Termination Internals.
  485. * EXIT_SUCCESS: (libc)Exit Status.
  486. * exp10f: (libc)Exponents and Logarithms.
  487. * exp10: (libc)Exponents and Logarithms.
  488. * exp10l: (libc)Exponents and Logarithms.
  489. * exp2f: (libc)Exponents and Logarithms.
  490. * exp2: (libc)Exponents and Logarithms.
  491. * exp2l: (libc)Exponents and Logarithms.
  492. * expf: (libc)Exponents and Logarithms.
  493. * exp: (libc)Exponents and Logarithms.
  494. * explicit_bzero: (libc)Erasing Sensitive Data.
  495. * expl: (libc)Exponents and Logarithms.
  496. * expm1f: (libc)Exponents and Logarithms.
  497. * expm1: (libc)Exponents and Logarithms.
  498. * expm1l: (libc)Exponents and Logarithms.
  499. * EXPR_NEST_MAX: (libc)Utility Limits.
  500. * fabsf: (libc)Absolute Value.
  501. * fabs: (libc)Absolute Value.
  502. * fabsl: (libc)Absolute Value.
  503. * __fbufsize: (libc)Controlling Buffering.
  504. * fchdir: (libc)Working Directory.
  505. * fchmod: (libc)Setting Permissions.
  506. * fchown: (libc)File Owner.
  507. * fcloseall: (libc)Closing Streams.
  508. * fclose: (libc)Closing Streams.
  509. * fcntl: (libc)Control Operations.
  510. * fcvt: (libc)System V Number Conversion.
  511. * fcvt_r: (libc)System V Number Conversion.
  512. * fdatasync: (libc)Synchronizing I/O.
  513. * FD_CLOEXEC: (libc)Descriptor Flags.
  514. * FD_CLR: (libc)Waiting for I/O.
  515. * fdimf: (libc)Misc FP Arithmetic.
  516. * fdim: (libc)Misc FP Arithmetic.
  517. * fdiml: (libc)Misc FP Arithmetic.
  518. * FD_ISSET: (libc)Waiting for I/O.
  519. * fdopendir: (libc)Opening a Directory.
  520. * fdopen: (libc)Descriptors and Streams.
  521. * FD_SET: (libc)Waiting for I/O.
  522. * FD_SETSIZE: (libc)Waiting for I/O.
  523. * F_DUPFD: (libc)Duplicating Descriptors.
  524. * FD_ZERO: (libc)Waiting for I/O.
  525. * feclearexcept: (libc)Status bit operations.
  526. * fedisableexcept: (libc)Control Functions.
  527. * feenableexcept: (libc)Control Functions.
  528. * fegetenv: (libc)Control Functions.
  529. * fegetexceptflag: (libc)Status bit operations.
  530. * fegetexcept: (libc)Control Functions.
  531. * fegetmode: (libc)Control Functions.
  532. * fegetround: (libc)Rounding.
  533. * feholdexcept: (libc)Control Functions.
  534. * feof: (libc)EOF and Errors.
  535. * feof_unlocked: (libc)EOF and Errors.
  536. * feraiseexcept: (libc)Status bit operations.
  537. * ferror: (libc)EOF and Errors.
  538. * ferror_unlocked: (libc)EOF and Errors.
  539. * fesetenv: (libc)Control Functions.
  540. * fesetexceptflag: (libc)Status bit operations.
  541. * fesetexcept: (libc)Status bit operations.
  542. * fesetmode: (libc)Control Functions.
  543. * fesetround: (libc)Rounding.
  544. * FE_SNANS_ALWAYS_SIGNAL: (libc)Infinity and NaN.
  545. * fetestexceptflag: (libc)Status bit operations.
  546. * fetestexcept: (libc)Status bit operations.
  547. * feupdateenv: (libc)Control Functions.
  548. * fflush: (libc)Flushing Buffers.
  549. * fflush_unlocked: (libc)Flushing Buffers.
  550. * fgetc: (libc)Character Input.
  551. * fgetc_unlocked: (libc)Character Input.
  552. * F_GETFD: (libc)Descriptor Flags.
  553. * F_GETFL: (libc)Getting File Status Flags.
  554. * fgetgrent: (libc)Scanning All Groups.
  555. * fgetgrent_r: (libc)Scanning All Groups.
  556. * F_GETLK: (libc)File Locks.
  557. * F_GETOWN: (libc)Interrupt Input.
  558. * fgetpos64: (libc)Portable Positioning.
  559. * fgetpos: (libc)Portable Positioning.
  560. * fgetpwent: (libc)Scanning All Users.
  561. * fgetpwent_r: (libc)Scanning All Users.
  562. * fgets: (libc)Line Input.
  563. * fgets_unlocked: (libc)Line Input.
  564. * fgetwc: (libc)Character Input.
  565. * fgetwc_unlocked: (libc)Character Input.
  566. * fgetws: (libc)Line Input.
  567. * fgetws_unlocked: (libc)Line Input.
  568. * FILENAME_MAX: (libc)Limits for Files.
  569. * fileno: (libc)Descriptors and Streams.
  570. * fileno_unlocked: (libc)Descriptors and Streams.
  571. * finitef: (libc)Floating Point Classes.
  572. * finite: (libc)Floating Point Classes.
  573. * finitel: (libc)Floating Point Classes.
  574. * __flbf: (libc)Controlling Buffering.
  575. * flockfile: (libc)Streams and Threads.
  576. * floorf: (libc)Rounding Functions.
  577. * floor: (libc)Rounding Functions.
  578. * floorl: (libc)Rounding Functions.
  579. * _flushlbf: (libc)Flushing Buffers.
  580. * FLUSHO: (libc)Local Modes.
  581. * fmaf: (libc)Misc FP Arithmetic.
  582. * fma: (libc)Misc FP Arithmetic.
  583. * fmal: (libc)Misc FP Arithmetic.
  584. * fmaxf: (libc)Misc FP Arithmetic.
  585. * fmax: (libc)Misc FP Arithmetic.
  586. * fmaxl: (libc)Misc FP Arithmetic.
  587. * fmaxmagf: (libc)Misc FP Arithmetic.
  588. * fmaxmag: (libc)Misc FP Arithmetic.
  589. * fmaxmagl: (libc)Misc FP Arithmetic.
  590. * fmemopen: (libc)String Streams.
  591. * fminf: (libc)Misc FP Arithmetic.
  592. * fmin: (libc)Misc FP Arithmetic.
  593. * fminl: (libc)Misc FP Arithmetic.
  594. * fminmagf: (libc)Misc FP Arithmetic.
  595. * fminmag: (libc)Misc FP Arithmetic.
  596. * fminmagl: (libc)Misc FP Arithmetic.
  597. * fmodf: (libc)Remainder Functions.
  598. * fmod: (libc)Remainder Functions.
  599. * fmodl: (libc)Remainder Functions.
  600. * fmtmsg: (libc)Printing Formatted Messages.
  601. * fnmatch: (libc)Wildcard Matching.
  602. * F_OFD_GETLK: (libc)Open File Description Locks.
  603. * F_OFD_SETLK: (libc)Open File Description Locks.
  604. * F_OFD_SETLKW: (libc)Open File Description Locks.
  605. * F_OK: (libc)Testing File Access.
  606. * fopen64: (libc)Opening Streams.
  607. * fopencookie: (libc)Streams and Cookies.
  608. * fopen: (libc)Opening Streams.
  609. * FOPEN_MAX: (libc)Opening Streams.
  610. * fork: (libc)Creating a Process.
  611. * forkpty: (libc)Pseudo-Terminal Pairs.
  612. * fpathconf: (libc)Pathconf.
  613. * fpclassify: (libc)Floating Point Classes.
  614. * __fpending: (libc)Controlling Buffering.
  615. * FP_ILOGB0: (libc)Exponents and Logarithms.
  616. * FP_ILOGBNAN: (libc)Exponents and Logarithms.
  617. * FP_LLOGB0: (libc)Exponents and Logarithms.
  618. * FP_LLOGBNAN: (libc)Exponents and Logarithms.
  619. * fprintf: (libc)Formatted Output Functions.
  620. * __fpurge: (libc)Flushing Buffers.
  621. * fputc: (libc)Simple Output.
  622. * fputc_unlocked: (libc)Simple Output.
  623. * fputs: (libc)Simple Output.
  624. * fputs_unlocked: (libc)Simple Output.
  625. * fputwc: (libc)Simple Output.
  626. * fputwc_unlocked: (libc)Simple Output.
  627. * fputws: (libc)Simple Output.
  628. * fputws_unlocked: (libc)Simple Output.
  629. * __freadable: (libc)Opening Streams.
  630. * __freading: (libc)Opening Streams.
  631. * fread: (libc)Block Input/Output.
  632. * fread_unlocked: (libc)Block Input/Output.
  633. * free: (libc)Freeing after Malloc.
  634. * freopen64: (libc)Opening Streams.
  635. * freopen: (libc)Opening Streams.
  636. * frexpf: (libc)Normalization Functions.
  637. * frexp: (libc)Normalization Functions.
  638. * frexpl: (libc)Normalization Functions.
  639. * fromfpf: (libc)Rounding Functions.
  640. * fromfp: (libc)Rounding Functions.
  641. * fromfpl: (libc)Rounding Functions.
  642. * fromfpxf: (libc)Rounding Functions.
  643. * fromfpx: (libc)Rounding Functions.
  644. * fromfpxl: (libc)Rounding Functions.
  645. * fscanf: (libc)Formatted Input Functions.
  646. * fseek: (libc)File Positioning.
  647. * fseeko64: (libc)File Positioning.
  648. * fseeko: (libc)File Positioning.
  649. * F_SETFD: (libc)Descriptor Flags.
  650. * F_SETFL: (libc)Getting File Status Flags.
  651. * F_SETLK: (libc)File Locks.
  652. * F_SETLKW: (libc)File Locks.
  653. * __fsetlocking: (libc)Streams and Threads.
  654. * F_SETOWN: (libc)Interrupt Input.
  655. * fsetpos64: (libc)Portable Positioning.
  656. * fsetpos: (libc)Portable Positioning.
  657. * fstat64: (libc)Reading Attributes.
  658. * fstat: (libc)Reading Attributes.
  659. * fsync: (libc)Synchronizing I/O.
  660. * ftell: (libc)File Positioning.
  661. * ftello64: (libc)File Positioning.
  662. * ftello: (libc)File Positioning.
  663. * ftruncate64: (libc)File Size.
  664. * ftruncate: (libc)File Size.
  665. * ftrylockfile: (libc)Streams and Threads.
  666. * ftw64: (libc)Working with Directory Trees.
  667. * ftw: (libc)Working with Directory Trees.
  668. * funlockfile: (libc)Streams and Threads.
  669. * futimes: (libc)File Times.
  670. * fwide: (libc)Streams and I18N.
  671. * fwprintf: (libc)Formatted Output Functions.
  672. * __fwritable: (libc)Opening Streams.
  673. * fwrite: (libc)Block Input/Output.
  674. * fwrite_unlocked: (libc)Block Input/Output.
  675. * __fwriting: (libc)Opening Streams.
  676. * fwscanf: (libc)Formatted Input Functions.
  677. * gammaf: (libc)Special Functions.
  678. * gamma: (libc)Special Functions.
  679. * gammal: (libc)Special Functions.
  680. * __gconv_end_fct: (libc)glibc iconv Implementation.
  681. * __gconv_fct: (libc)glibc iconv Implementation.
  682. * __gconv_init_fct: (libc)glibc iconv Implementation.
  683. * gcvt: (libc)System V Number Conversion.
  684. * getauxval: (libc)Auxiliary Vector.
  685. * get_avphys_pages: (libc)Query Memory Parameters.
  686. * getchar: (libc)Character Input.
  687. * getchar_unlocked: (libc)Character Input.
  688. * getc: (libc)Character Input.
  689. * getcontext: (libc)System V contexts.
  690. * getc_unlocked: (libc)Character Input.
  691. * get_current_dir_name: (libc)Working Directory.
  692. * getcwd: (libc)Working Directory.
  693. * getdate: (libc)General Time String Parsing.
  694. * getdate_r: (libc)General Time String Parsing.
  695. * getdelim: (libc)Line Input.
  696. * getdomainnname: (libc)Host Identification.
  697. * getegid: (libc)Reading Persona.
  698. * getentropy: (libc)Unpredictable Bytes.
  699. * getenv: (libc)Environment Access.
  700. * geteuid: (libc)Reading Persona.
  701. * getfsent: (libc)fstab.
  702. * getfsfile: (libc)fstab.
  703. * getfsspec: (libc)fstab.
  704. * getgid: (libc)Reading Persona.
  705. * getgrent: (libc)Scanning All Groups.
  706. * getgrent_r: (libc)Scanning All Groups.
  707. * getgrgid: (libc)Lookup Group.
  708. * getgrgid_r: (libc)Lookup Group.
  709. * getgrnam: (libc)Lookup Group.
  710. * getgrnam_r: (libc)Lookup Group.
  711. * getgrouplist: (libc)Setting Groups.
  712. * getgroups: (libc)Reading Persona.
  713. * gethostbyaddr: (libc)Host Names.
  714. * gethostbyaddr_r: (libc)Host Names.
  715. * gethostbyname2: (libc)Host Names.
  716. * gethostbyname2_r: (libc)Host Names.
  717. * gethostbyname: (libc)Host Names.
  718. * gethostbyname_r: (libc)Host Names.
  719. * gethostent: (libc)Host Names.
  720. * gethostid: (libc)Host Identification.
  721. * gethostname: (libc)Host Identification.
  722. * getitimer: (libc)Setting an Alarm.
  723. * getline: (libc)Line Input.
  724. * getloadavg: (libc)Processor Resources.
  725. * getlogin: (libc)Who Logged In.
  726. * getmntent: (libc)mtab.
  727. * getmntent_r: (libc)mtab.
  728. * getnetbyaddr: (libc)Networks Database.
  729. * getnetbyname: (libc)Networks Database.
  730. * getnetent: (libc)Networks Database.
  731. * getnetgrent: (libc)Lookup Netgroup.
  732. * getnetgrent_r: (libc)Lookup Netgroup.
  733. * get_nprocs_conf: (libc)Processor Resources.
  734. * get_nprocs: (libc)Processor Resources.
  735. * getopt: (libc)Using Getopt.
  736. * getopt_long: (libc)Getopt Long Options.
  737. * getopt_long_only: (libc)Getopt Long Options.
  738. * getpagesize: (libc)Query Memory Parameters.
  739. * getpass: (libc)getpass.
  740. * getpayloadf: (libc)FP Bit Twiddling.
  741. * getpayload: (libc)FP Bit Twiddling.
  742. * getpayloadl: (libc)FP Bit Twiddling.
  743. * getpeername: (libc)Who is Connected.
  744. * getpgid: (libc)Process Group Functions.
  745. * getpgrp: (libc)Process Group Functions.
  746. * get_phys_pages: (libc)Query Memory Parameters.
  747. * getpid: (libc)Process Identification.
  748. * getppid: (libc)Process Identification.
  749. * getpriority: (libc)Traditional Scheduling Functions.
  750. * getprotobyname: (libc)Protocols Database.
  751. * getprotobynumber: (libc)Protocols Database.
  752. * getprotoent: (libc)Protocols Database.
  753. * getpt: (libc)Allocation.
  754. * getpwent: (libc)Scanning All Users.
  755. * getpwent_r: (libc)Scanning All Users.
  756. * getpwnam: (libc)Lookup User.
  757. * getpwnam_r: (libc)Lookup User.
  758. * getpwuid: (libc)Lookup User.
  759. * getpwuid_r: (libc)Lookup User.
  760. * getrandom: (libc)Unpredictable Bytes.
  761. * getrlimit64: (libc)Limits on Resources.
  762. * getrlimit: (libc)Limits on Resources.
  763. * getrusage: (libc)Resource Usage.
  764. * getservbyname: (libc)Services Database.
  765. * getservbyport: (libc)Services Database.
  766. * getservent: (libc)Services Database.
  767. * getsid: (libc)Process Group Functions.
  768. * gets: (libc)Line Input.
  769. * getsockname: (libc)Reading Address.
  770. * getsockopt: (libc)Socket Option Functions.
  771. * getsubopt: (libc)Suboptions.
  772. * gettext: (libc)Translation with gettext.
  773. * gettimeofday: (libc)High-Resolution Calendar.
  774. * getuid: (libc)Reading Persona.
  775. * getumask: (libc)Setting Permissions.
  776. * getutent: (libc)Manipulating the Database.
  777. * getutent_r: (libc)Manipulating the Database.
  778. * getutid: (libc)Manipulating the Database.
  779. * getutid_r: (libc)Manipulating the Database.
  780. * getutline: (libc)Manipulating the Database.
  781. * getutline_r: (libc)Manipulating the Database.
  782. * getutmp: (libc)XPG Functions.
  783. * getutmpx: (libc)XPG Functions.
  784. * getutxent: (libc)XPG Functions.
  785. * getutxid: (libc)XPG Functions.
  786. * getutxline: (libc)XPG Functions.
  787. * getwchar: (libc)Character Input.
  788. * getwchar_unlocked: (libc)Character Input.
  789. * getwc: (libc)Character Input.
  790. * getwc_unlocked: (libc)Character Input.
  791. * getwd: (libc)Working Directory.
  792. * getw: (libc)Character Input.
  793. * glob64: (libc)Calling Glob.
  794. * globfree64: (libc)More Flags for Globbing.
  795. * globfree: (libc)More Flags for Globbing.
  796. * glob: (libc)Calling Glob.
  797. * gmtime: (libc)Broken-down Time.
  798. * gmtime_r: (libc)Broken-down Time.
  799. * grantpt: (libc)Allocation.
  800. * gsignal: (libc)Signaling Yourself.
  801. * gtty: (libc)BSD Terminal Modes.
  802. * hasmntopt: (libc)mtab.
  803. * hcreate: (libc)Hash Search Function.
  804. * hcreate_r: (libc)Hash Search Function.
  805. * hdestroy: (libc)Hash Search Function.
  806. * hdestroy_r: (libc)Hash Search Function.
  807. * hsearch: (libc)Hash Search Function.
  808. * hsearch_r: (libc)Hash Search Function.
  809. * htonl: (libc)Byte Order.
  810. * htons: (libc)Byte Order.
  811. * HUGE_VALF: (libc)Math Error Reporting.
  812. * HUGE_VAL: (libc)Math Error Reporting.
  813. * HUGE_VALL: (libc)Math Error Reporting.
  814. * HUPCL: (libc)Control Modes.
  815. * hypotf: (libc)Exponents and Logarithms.
  816. * hypot: (libc)Exponents and Logarithms.
  817. * hypotl: (libc)Exponents and Logarithms.
  818. * ICANON: (libc)Local Modes.
  819. * iconv_close: (libc)Generic Conversion Interface.
  820. * iconv: (libc)Generic Conversion Interface.
  821. * iconv_open: (libc)Generic Conversion Interface.
  822. * ICRNL: (libc)Input Modes.
  823. * IEXTEN: (libc)Local Modes.
  824. * if_freenameindex: (libc)Interface Naming.
  825. * if_indextoname: (libc)Interface Naming.
  826. * if_nameindex: (libc)Interface Naming.
  827. * if_nametoindex: (libc)Interface Naming.
  828. * IFNAMSIZ: (libc)Interface Naming.
  829. * IFTODT: (libc)Directory Entries.
  830. * IGNBRK: (libc)Input Modes.
  831. * IGNCR: (libc)Input Modes.
  832. * IGNPAR: (libc)Input Modes.
  833. * I: (libc)Complex Numbers.
  834. * ilogbf: (libc)Exponents and Logarithms.
  835. * ilogb: (libc)Exponents and Logarithms.
  836. * ilogbl: (libc)Exponents and Logarithms.
  837. * _Imaginary_I: (libc)Complex Numbers.
  838. * imaxabs: (libc)Absolute Value.
  839. * IMAXBEL: (libc)Input Modes.
  840. * imaxdiv: (libc)Integer Division.
  841. * in6addr_any: (libc)Host Address Data Type.
  842. * in6addr_loopback: (libc)Host Address Data Type.
  843. * INADDR_ANY: (libc)Host Address Data Type.
  844. * INADDR_BROADCAST: (libc)Host Address Data Type.
  845. * INADDR_LOOPBACK: (libc)Host Address Data Type.
  846. * INADDR_NONE: (libc)Host Address Data Type.
  847. * index: (libc)Search Functions.
  848. * inet_addr: (libc)Host Address Functions.
  849. * inet_aton: (libc)Host Address Functions.
  850. * inet_lnaof: (libc)Host Address Functions.
  851. * inet_makeaddr: (libc)Host Address Functions.
  852. * inet_netof: (libc)Host Address Functions.
  853. * inet_network: (libc)Host Address Functions.
  854. * inet_ntoa: (libc)Host Address Functions.
  855. * inet_ntop: (libc)Host Address Functions.
  856. * inet_pton: (libc)Host Address Functions.
  857. * INFINITY: (libc)Infinity and NaN.
  858. * initgroups: (libc)Setting Groups.
  859. * initstate: (libc)BSD Random.
  860. * initstate_r: (libc)BSD Random.
  861. * INLCR: (libc)Input Modes.
  862. * innetgr: (libc)Netgroup Membership.
  863. * INPCK: (libc)Input Modes.
  864. * ioctl: (libc)IOCTLs.
  865. * _IOFBF: (libc)Controlling Buffering.
  866. * _IOLBF: (libc)Controlling Buffering.
  867. * _IONBF: (libc)Controlling Buffering.
  868. * IPPORT_RESERVED: (libc)Ports.
  869. * IPPORT_USERRESERVED: (libc)Ports.
  870. * isalnum: (libc)Classification of Characters.
  871. * isalpha: (libc)Classification of Characters.
  872. * isascii: (libc)Classification of Characters.
  873. * isatty: (libc)Is It a Terminal.
  874. * isblank: (libc)Classification of Characters.
  875. * iscanonical: (libc)Floating Point Classes.
  876. * iscntrl: (libc)Classification of Characters.
  877. * isdigit: (libc)Classification of Characters.
  878. * iseqsig: (libc)FP Comparison Functions.
  879. * isfinite: (libc)Floating Point Classes.
  880. * isgraph: (libc)Classification of Characters.
  881. * isgreaterequal: (libc)FP Comparison Functions.
  882. * isgreater: (libc)FP Comparison Functions.
  883. * ISIG: (libc)Local Modes.
  884. * isinff: (libc)Floating Point Classes.
  885. * isinf: (libc)Floating Point Classes.
  886. * isinfl: (libc)Floating Point Classes.
  887. * islessequal: (libc)FP Comparison Functions.
  888. * islessgreater: (libc)FP Comparison Functions.
  889. * isless: (libc)FP Comparison Functions.
  890. * islower: (libc)Classification of Characters.
  891. * isnanf: (libc)Floating Point Classes.
  892. * isnan: (libc)Floating Point Classes.
  893. * isnan: (libc)Floating Point Classes.
  894. * isnanl: (libc)Floating Point Classes.
  895. * isnormal: (libc)Floating Point Classes.
  896. * isprint: (libc)Classification of Characters.
  897. * ispunct: (libc)Classification of Characters.
  898. * issignaling: (libc)Floating Point Classes.
  899. * isspace: (libc)Classification of Characters.
  900. * issubnormal: (libc)Floating Point Classes.
  901. * ISTRIP: (libc)Input Modes.
  902. * isunordered: (libc)FP Comparison Functions.
  903. * isupper: (libc)Classification of Characters.
  904. * iswalnum: (libc)Classification of Wide Characters.
  905. * iswalpha: (libc)Classification of Wide Characters.
  906. * iswblank: (libc)Classification of Wide Characters.
  907. * iswcntrl: (libc)Classification of Wide Characters.
  908. * iswctype: (libc)Classification of Wide Characters.
  909. * iswdigit: (libc)Classification of Wide Characters.
  910. * iswgraph: (libc)Classification of Wide Characters.
  911. * iswlower: (libc)Classification of Wide Characters.
  912. * iswprint: (libc)Classification of Wide Characters.
  913. * iswpunct: (libc)Classification of Wide Characters.
  914. * iswspace: (libc)Classification of Wide Characters.
  915. * iswupper: (libc)Classification of Wide Characters.
  916. * iswxdigit: (libc)Classification of Wide Characters.
  917. * isxdigit: (libc)Classification of Characters.
  918. * iszero: (libc)Floating Point Classes.
  919. * IXANY: (libc)Input Modes.
  920. * IXOFF: (libc)Input Modes.
  921. * IXON: (libc)Input Modes.
  922. * j0f: (libc)Special Functions.
  923. * j0: (libc)Special Functions.
  924. * j0l: (libc)Special Functions.
  925. * j1f: (libc)Special Functions.
  926. * j1: (libc)Special Functions.
  927. * j1l: (libc)Special Functions.
  928. * jnf: (libc)Special Functions.
  929. * jn: (libc)Special Functions.
  930. * jnl: (libc)Special Functions.
  931. * jrand48: (libc)SVID Random.
  932. * jrand48_r: (libc)SVID Random.
  933. * kill: (libc)Signaling Another Process.
  934. * killpg: (libc)Signaling Another Process.
  935. * l64a: (libc)Encode Binary Data.
  936. * labs: (libc)Absolute Value.
  937. * lcong48: (libc)SVID Random.
  938. * lcong48_r: (libc)SVID Random.
  939. * L_ctermid: (libc)Identifying the Terminal.
  940. * L_cuserid: (libc)Who Logged In.
  941. * ldexpf: (libc)Normalization Functions.
  942. * ldexp: (libc)Normalization Functions.
  943. * ldexpl: (libc)Normalization Functions.
  944. * ldiv: (libc)Integer Division.
  945. * lfind: (libc)Array Search Function.
  946. * lgammaf: (libc)Special Functions.
  947. * lgammaf_r: (libc)Special Functions.
  948. * lgamma: (libc)Special Functions.
  949. * lgammal: (libc)Special Functions.
  950. * lgammal_r: (libc)Special Functions.
  951. * lgamma_r: (libc)Special Functions.
  952. * LINE_MAX: (libc)Utility Limits.
  953. * link: (libc)Hard Links.
  954. * LINK_MAX: (libc)Limits for Files.
  955. * lio_listio64: (libc)Asynchronous Reads/Writes.
  956. * lio_listio: (libc)Asynchronous Reads/Writes.
  957. * listen: (libc)Listening.
  958. * llabs: (libc)Absolute Value.
  959. * lldiv: (libc)Integer Division.
  960. * llogbf: (libc)Exponents and Logarithms.
  961. * llogb: (libc)Exponents and Logarithms.
  962. * llogbl: (libc)Exponents and Logarithms.
  963. * llrintf: (libc)Rounding Functions.
  964. * llrint: (libc)Rounding Functions.
  965. * llrintl: (libc)Rounding Functions.
  966. * llroundf: (libc)Rounding Functions.
  967. * llround: (libc)Rounding Functions.
  968. * llroundl: (libc)Rounding Functions.
  969. * localeconv: (libc)The Lame Way to Locale Data.
  970. * localtime: (libc)Broken-down Time.
  971. * localtime_r: (libc)Broken-down Time.
  972. * log10f: (libc)Exponents and Logarithms.
  973. * log10: (libc)Exponents and Logarithms.
  974. * log10l: (libc)Exponents and Logarithms.
  975. * log1pf: (libc)Exponents and Logarithms.
  976. * log1p: (libc)Exponents and Logarithms.
  977. * log1pl: (libc)Exponents and Logarithms.
  978. * log2f: (libc)Exponents and Logarithms.
  979. * log2: (libc)Exponents and Logarithms.
  980. * log2l: (libc)Exponents and Logarithms.
  981. * logbf: (libc)Exponents and Logarithms.
  982. * logb: (libc)Exponents and Logarithms.
  983. * logbl: (libc)Exponents and Logarithms.
  984. * logf: (libc)Exponents and Logarithms.
  985. * login: (libc)Logging In and Out.
  986. * login_tty: (libc)Logging In and Out.
  987. * log: (libc)Exponents and Logarithms.
  988. * logl: (libc)Exponents and Logarithms.
  989. * logout: (libc)Logging In and Out.
  990. * logwtmp: (libc)Logging In and Out.
  991. * longjmp: (libc)Non-Local Details.
  992. * lrand48: (libc)SVID Random.
  993. * lrand48_r: (libc)SVID Random.
  994. * lrintf: (libc)Rounding Functions.
  995. * lrint: (libc)Rounding Functions.
  996. * lrintl: (libc)Rounding Functions.
  997. * lroundf: (libc)Rounding Functions.
  998. * lround: (libc)Rounding Functions.
  999. * lroundl: (libc)Rounding Functions.
  1000. * lsearch: (libc)Array Search Function.
  1001. * lseek64: (libc)File Position Primitive.
  1002. * lseek: (libc)File Position Primitive.
  1003. * lstat64: (libc)Reading Attributes.
  1004. * lstat: (libc)Reading Attributes.
  1005. * L_tmpnam: (libc)Temporary Files.
  1006. * lutimes: (libc)File Times.
  1007. * madvise: (libc)Memory-mapped I/O.
  1008. * makecontext: (libc)System V contexts.
  1009. * mallinfo: (libc)Statistics of Malloc.
  1010. * malloc: (libc)Basic Allocation.
  1011. * mallopt: (libc)Malloc Tunable Parameters.
  1012. * MAX_CANON: (libc)Limits for Files.
  1013. * MAX_INPUT: (libc)Limits for Files.
  1014. * MAXNAMLEN: (libc)Limits for Files.
  1015. * MAXSYMLINKS: (libc)Symbolic Links.
  1016. * MB_CUR_MAX: (libc)Selecting the Conversion.
  1017. * mblen: (libc)Non-reentrant Character Conversion.
  1018. * MB_LEN_MAX: (libc)Selecting the Conversion.
  1019. * mbrlen: (libc)Converting a Character.
  1020. * mbrtowc: (libc)Converting a Character.
  1021. * mbsinit: (libc)Keeping the state.
  1022. * mbsnrtowcs: (libc)Converting Strings.
  1023. * mbsrtowcs: (libc)Converting Strings.
  1024. * mbstowcs: (libc)Non-reentrant String Conversion.
  1025. * mbtowc: (libc)Non-reentrant Character Conversion.
  1026. * mcheck: (libc)Heap Consistency Checking.
  1027. * MDMBUF: (libc)Control Modes.
  1028. * memalign: (libc)Aligned Memory Blocks.
  1029. * memccpy: (libc)Copying Strings and Arrays.
  1030. * memchr: (libc)Search Functions.
  1031. * memcmp: (libc)String/Array Comparison.
  1032. * memcpy: (libc)Copying Strings and Arrays.
  1033. * memfrob: (libc)Trivial Encryption.
  1034. * memmem: (libc)Search Functions.
  1035. * memmove: (libc)Copying Strings and Arrays.
  1036. * mempcpy: (libc)Copying Strings and Arrays.
  1037. * memrchr: (libc)Search Functions.
  1038. * memset: (libc)Copying Strings and Arrays.
  1039. * mkdir: (libc)Creating Directories.
  1040. * mkdtemp: (libc)Temporary Files.
  1041. * mkfifo: (libc)FIFO Special Files.
  1042. * mknod: (libc)Making Special Files.
  1043. * mkstemp: (libc)Temporary Files.
  1044. * mktemp: (libc)Temporary Files.
  1045. * mktime: (libc)Broken-down Time.
  1046. * mlockall: (libc)Page Lock Functions.
  1047. * mlock: (libc)Page Lock Functions.
  1048. * mmap64: (libc)Memory-mapped I/O.
  1049. * mmap: (libc)Memory-mapped I/O.
  1050. * modff: (libc)Rounding Functions.
  1051. * modf: (libc)Rounding Functions.
  1052. * modfl: (libc)Rounding Functions.
  1053. * mount: (libc)Mount-Unmount-Remount.
  1054. * mprobe: (libc)Heap Consistency Checking.
  1055. * mrand48: (libc)SVID Random.
  1056. * mrand48_r: (libc)SVID Random.
  1057. * mremap: (libc)Memory-mapped I/O.
  1058. * MSG_DONTROUTE: (libc)Socket Data Options.
  1059. * MSG_OOB: (libc)Socket Data Options.
  1060. * MSG_PEEK: (libc)Socket Data Options.
  1061. * msync: (libc)Memory-mapped I/O.
  1062. * mtrace: (libc)Tracing malloc.
  1063. * munlockall: (libc)Page Lock Functions.
  1064. * munlock: (libc)Page Lock Functions.
  1065. * munmap: (libc)Memory-mapped I/O.
  1066. * muntrace: (libc)Tracing malloc.
  1067. * NAME_MAX: (libc)Limits for Files.
  1068. * nanf: (libc)FP Bit Twiddling.
  1069. * nan: (libc)FP Bit Twiddling.
  1070. * NAN: (libc)Infinity and NaN.
  1071. * nanl: (libc)FP Bit Twiddling.
  1072. * nanosleep: (libc)Sleeping.
  1073. * NCCS: (libc)Mode Data Types.
  1074. * nearbyintf: (libc)Rounding Functions.
  1075. * nearbyint: (libc)Rounding Functions.
  1076. * nearbyintl: (libc)Rounding Functions.
  1077. * nextafterf: (libc)FP Bit Twiddling.
  1078. * nextafter: (libc)FP Bit Twiddling.
  1079. * nextafterl: (libc)FP Bit Twiddling.
  1080. * nextdownf: (libc)FP Bit Twiddling.
  1081. * nextdown: (libc)FP Bit Twiddling.
  1082. * nextdownl: (libc)FP Bit Twiddling.
  1083. * nexttowardf: (libc)FP Bit Twiddling.
  1084. * nexttoward: (libc)FP Bit Twiddling.
  1085. * nexttowardl: (libc)FP Bit Twiddling.
  1086. * nextupf: (libc)FP Bit Twiddling.
  1087. * nextup: (libc)FP Bit Twiddling.
  1088. * nextupl: (libc)FP Bit Twiddling.
  1089. * nftw64: (libc)Working with Directory Trees.
  1090. * nftw: (libc)Working with Directory Trees.
  1091. * ngettext: (libc)Advanced gettext functions.
  1092. * NGROUPS_MAX: (libc)General Limits.
  1093. * nice: (libc)Traditional Scheduling Functions.
  1094. * nl_langinfo: (libc)The Elegant and Fast Way.
  1095. * NOFLSH: (libc)Local Modes.
  1096. * NOKERNINFO: (libc)Local Modes.
  1097. * nrand48: (libc)SVID Random.
  1098. * nrand48_r: (libc)SVID Random.
  1099. * NSIG: (libc)Standard Signals.
  1100. * ntohl: (libc)Byte Order.
  1101. * ntohs: (libc)Byte Order.
  1102. * ntp_adjtime: (libc)High Accuracy Clock.
  1103. * ntp_gettime: (libc)High Accuracy Clock.
  1104. * NULL: (libc)Null Pointer Constant.
  1105. * O_ACCMODE: (libc)Access Modes.
  1106. * O_APPEND: (libc)Operating Modes.
  1107. * O_ASYNC: (libc)Operating Modes.
  1108. * obstack_1grow_fast: (libc)Extra Fast Growing.
  1109. * obstack_1grow: (libc)Growing Objects.
  1110. * obstack_alignment_mask: (libc)Obstacks Data Alignment.
  1111. * obstack_alloc: (libc)Allocation in an Obstack.
  1112. * obstack_base: (libc)Status of an Obstack.
  1113. * obstack_blank_fast: (libc)Extra Fast Growing.
  1114. * obstack_blank: (libc)Growing Objects.
  1115. * obstack_chunk_size: (libc)Obstack Chunks.
  1116. * obstack_copy0: (libc)Allocation in an Obstack.
  1117. * obstack_copy: (libc)Allocation in an Obstack.
  1118. * obstack_finish: (libc)Growing Objects.
  1119. * obstack_free: (libc)Freeing Obstack Objects.
  1120. * obstack_grow0: (libc)Growing Objects.
  1121. * obstack_grow: (libc)Growing Objects.
  1122. * obstack_init: (libc)Preparing for Obstacks.
  1123. * obstack_int_grow_fast: (libc)Extra Fast Growing.
  1124. * obstack_int_grow: (libc)Growing Objects.
  1125. * obstack_next_free: (libc)Status of an Obstack.
  1126. * obstack_object_size: (libc)Growing Objects.
  1127. * obstack_object_size: (libc)Status of an Obstack.
  1128. * obstack_printf: (libc)Dynamic Output.
  1129. * obstack_ptr_grow_fast: (libc)Extra Fast Growing.
  1130. * obstack_ptr_grow: (libc)Growing Objects.
  1131. * obstack_room: (libc)Extra Fast Growing.
  1132. * obstack_vprintf: (libc)Variable Arguments Output.
  1133. * O_CREAT: (libc)Open-time Flags.
  1134. * O_EXCL: (libc)Open-time Flags.
  1135. * O_EXEC: (libc)Access Modes.
  1136. * O_EXLOCK: (libc)Open-time Flags.
  1137. * offsetof: (libc)Structure Measurement.
  1138. * O_FSYNC: (libc)Operating Modes.
  1139. * O_IGNORE_CTTY: (libc)Open-time Flags.
  1140. * O_NDELAY: (libc)Operating Modes.
  1141. * on_exit: (libc)Cleanups on Exit.
  1142. * ONLCR: (libc)Output Modes.
  1143. * O_NOATIME: (libc)Operating Modes.
  1144. * O_NOCTTY: (libc)Open-time Flags.
  1145. * ONOEOT: (libc)Output Modes.
  1146. * O_NOLINK: (libc)Open-time Flags.
  1147. * O_NONBLOCK: (libc)Open-time Flags.
  1148. * O_NONBLOCK: (libc)Operating Modes.
  1149. * O_NOTRANS: (libc)Open-time Flags.
  1150. * open64: (libc)Opening and Closing Files.
  1151. * opendir: (libc)Opening a Directory.
  1152. * open: (libc)Opening and Closing Files.
  1153. * openlog: (libc)openlog.
  1154. * OPEN_MAX: (libc)General Limits.
  1155. * open_memstream: (libc)String Streams.
  1156. * openpty: (libc)Pseudo-Terminal Pairs.
  1157. * OPOST: (libc)Output Modes.
  1158. * O_RDONLY: (libc)Access Modes.
  1159. * O_RDWR: (libc)Access Modes.
  1160. * O_READ: (libc)Access Modes.
  1161. * O_SHLOCK: (libc)Open-time Flags.
  1162. * O_SYNC: (libc)Operating Modes.
  1163. * O_TRUNC: (libc)Open-time Flags.
  1164. * O_WRITE: (libc)Access Modes.
  1165. * O_WRONLY: (libc)Access Modes.
  1166. * OXTABS: (libc)Output Modes.
  1167. * PA_FLAG_MASK: (libc)Parsing a Template String.
  1168. * PARENB: (libc)Control Modes.
  1169. * PARMRK: (libc)Input Modes.
  1170. * PARODD: (libc)Control Modes.
  1171. * parse_printf_format: (libc)Parsing a Template String.
  1172. * pathconf: (libc)Pathconf.
  1173. * PATH_MAX: (libc)Limits for Files.
  1174. * _PATH_UTMP: (libc)Manipulating the Database.
  1175. * _PATH_WTMP: (libc)Manipulating the Database.
  1176. * pause: (libc)Using Pause.
  1177. * pclose: (libc)Pipe to a Subprocess.
  1178. * PENDIN: (libc)Local Modes.
  1179. * perror: (libc)Error Messages.
  1180. * PF_FILE: (libc)Local Namespace Details.
  1181. * PF_INET6: (libc)Internet Namespace.
  1182. * PF_INET: (libc)Internet Namespace.
  1183. * PF_LOCAL: (libc)Local Namespace Details.
  1184. * PF_UNIX: (libc)Local Namespace Details.
  1185. * PIPE_BUF: (libc)Limits for Files.
  1186. * pipe: (libc)Creating a Pipe.
  1187. * popen: (libc)Pipe to a Subprocess.
  1188. * _POSIX2_C_DEV: (libc)System Options.
  1189. * _POSIX2_C_VERSION: (libc)Version Supported.
  1190. * _POSIX2_FORT_DEV: (libc)System Options.
  1191. * _POSIX2_FORT_RUN: (libc)System Options.
  1192. * _POSIX2_LOCALEDEF: (libc)System Options.
  1193. * _POSIX2_SW_DEV: (libc)System Options.
  1194. * _POSIX_CHOWN_RESTRICTED: (libc)Options for Files.
  1195. * posix_fallocate64: (libc)Storage Allocation.
  1196. * posix_fallocate: (libc)Storage Allocation.
  1197. * _POSIX_JOB_CONTROL: (libc)System Options.
  1198. * posix_memalign: (libc)Aligned Memory Blocks.
  1199. * _POSIX_NO_TRUNC: (libc)Options for Files.
  1200. * _POSIX_SAVED_IDS: (libc)System Options.
  1201. * _POSIX_VDISABLE: (libc)Options for Files.
  1202. * _POSIX_VERSION: (libc)Version Supported.
  1203. * pow10f: (libc)Exponents and Logarithms.
  1204. * pow10: (libc)Exponents and Logarithms.
  1205. * pow10l: (libc)Exponents and Logarithms.
  1206. * powf: (libc)Exponents and Logarithms.
  1207. * pow: (libc)Exponents and Logarithms.
  1208. * powl: (libc)Exponents and Logarithms.
  1209. * __ppc_get_timebase_freq: (libc)PowerPC.
  1210. * __ppc_get_timebase: (libc)PowerPC.
  1211. * __ppc_mdoio: (libc)PowerPC.
  1212. * __ppc_mdoom: (libc)PowerPC.
  1213. * __ppc_set_ppr_low: (libc)PowerPC.
  1214. * __ppc_set_ppr_med_high: (libc)PowerPC.
  1215. * __ppc_set_ppr_med: (libc)PowerPC.
  1216. * __ppc_set_ppr_med_low: (libc)PowerPC.
  1217. * __ppc_set_ppr_very_low: (libc)PowerPC.
  1218. * __ppc_yield: (libc)PowerPC.
  1219. * pread64: (libc)I/O Primitives.
  1220. * pread: (libc)I/O Primitives.
  1221. * printf: (libc)Formatted Output Functions.
  1222. * printf_size_info: (libc)Predefined Printf Handlers.
  1223. * printf_size: (libc)Predefined Printf Handlers.
  1224. * psignal: (libc)Signal Messages.
  1225. * pthread_getattr_default_np: (libc)Default Thread Attributes.
  1226. * pthread_getspecific: (libc)Thread-specific Data.
  1227. * pthread_key_create: (libc)Thread-specific Data.
  1228. * pthread_key_delete: (libc)Thread-specific Data.
  1229. * pthread_setattr_default_np: (libc)Default Thread Attributes.
  1230. * pthread_setspecific: (libc)Thread-specific Data.
  1231. * P_tmpdir: (libc)Temporary Files.
  1232. * ptsname: (libc)Allocation.
  1233. * ptsname_r: (libc)Allocation.
  1234. * putchar: (libc)Simple Output.
  1235. * putchar_unlocked: (libc)Simple Output.
  1236. * putc: (libc)Simple Output.
  1237. * putc_unlocked: (libc)Simple Output.
  1238. * putenv: (libc)Environment Access.
  1239. * putpwent: (libc)Writing a User Entry.
  1240. * puts: (libc)Simple Output.
  1241. * pututline: (libc)Manipulating the Database.
  1242. * pututxline: (libc)XPG Functions.
  1243. * putwchar: (libc)Simple Output.
  1244. * putwchar_unlocked: (libc)Simple Output.
  1245. * putwc: (libc)Simple Output.
  1246. * putwc_unlocked: (libc)Simple Output.
  1247. * putw: (libc)Simple Output.
  1248. * pwrite64: (libc)I/O Primitives.
  1249. * pwrite: (libc)I/O Primitives.
  1250. * qecvt: (libc)System V Number Conversion.
  1251. * qecvt_r: (libc)System V Number Conversion.
  1252. * qfcvt: (libc)System V Number Conversion.
  1253. * qfcvt_r: (libc)System V Number Conversion.
  1254. * qgcvt: (libc)System V Number Conversion.
  1255. * qsort: (libc)Array Sort Function.
  1256. * raise: (libc)Signaling Yourself.
  1257. * rand: (libc)ISO Random.
  1258. * RAND_MAX: (libc)ISO Random.
  1259. * random: (libc)BSD Random.
  1260. * random_r: (libc)BSD Random.
  1261. * rand_r: (libc)ISO Random.
  1262. * rawmemchr: (libc)Search Functions.
  1263. * readdir64: (libc)Reading/Closing Directory.
  1264. * readdir64_r: (libc)Reading/Closing Directory.
  1265. * readdir: (libc)Reading/Closing Directory.
  1266. * readdir_r: (libc)Reading/Closing Directory.
  1267. * read: (libc)I/O Primitives.
  1268. * readlink: (libc)Symbolic Links.
  1269. * readv: (libc)Scatter-Gather.
  1270. * realloc: (libc)Changing Block Size.
  1271. * realpath: (libc)Symbolic Links.
  1272. * recvfrom: (libc)Receiving Datagrams.
  1273. * recv: (libc)Receiving Data.
  1274. * recvmsg: (libc)Receiving Datagrams.
  1275. * RE_DUP_MAX: (libc)General Limits.
  1276. * regcomp: (libc)POSIX Regexp Compilation.
  1277. * regerror: (libc)Regexp Cleanup.
  1278. * regexec: (libc)Matching POSIX Regexps.
  1279. * regfree: (libc)Regexp Cleanup.
  1280. * register_printf_function: (libc)Registering New Conversions.
  1281. * remainderf: (libc)Remainder Functions.
  1282. * remainder: (libc)Remainder Functions.
  1283. * remainderl: (libc)Remainder Functions.
  1284. * remove: (libc)Deleting Files.
  1285. * rename: (libc)Renaming Files.
  1286. * rewinddir: (libc)Random Access Directory.
  1287. * rewind: (libc)File Positioning.
  1288. * rindex: (libc)Search Functions.
  1289. * rintf: (libc)Rounding Functions.
  1290. * rint: (libc)Rounding Functions.
  1291. * rintl: (libc)Rounding Functions.
  1292. * RLIM_INFINITY: (libc)Limits on Resources.
  1293. * rmdir: (libc)Deleting Files.
  1294. * R_OK: (libc)Testing File Access.
  1295. * roundevenf: (libc)Rounding Functions.
  1296. * roundeven: (libc)Rounding Functions.
  1297. * roundevenl: (libc)Rounding Functions.
  1298. * roundf: (libc)Rounding Functions.
  1299. * round: (libc)Rounding Functions.
  1300. * roundl: (libc)Rounding Functions.
  1301. * rpmatch: (libc)Yes-or-No Questions.
  1302. * SA_NOCLDSTOP: (libc)Flags for Sigaction.
  1303. * SA_ONSTACK: (libc)Flags for Sigaction.
  1304. * SA_RESTART: (libc)Flags for Sigaction.
  1305. * sbrk: (libc)Resizing the Data Segment.
  1306. * scalbf: (libc)Normalization Functions.
  1307. * scalb: (libc)Normalization Functions.
  1308. * scalbl: (libc)Normalization Functions.
  1309. * scalblnf: (libc)Normalization Functions.
  1310. * scalbln: (libc)Normalization Functions.
  1311. * scalblnl: (libc)Normalization Functions.
  1312. * scalbnf: (libc)Normalization Functions.
  1313. * scalbn: (libc)Normalization Functions.
  1314. * scalbnl: (libc)Normalization Functions.
  1315. * scandir64: (libc)Scanning Directory Content.
  1316. * scandir: (libc)Scanning Directory Content.
  1317. * scanf: (libc)Formatted Input Functions.
  1318. * sched_getaffinity: (libc)CPU Affinity.
  1319. * sched_getparam: (libc)Basic Scheduling Functions.
  1320. * sched_get_priority_max: (libc)Basic Scheduling Functions.
  1321. * sched_get_priority_min: (libc)Basic Scheduling Functions.
  1322. * sched_getscheduler: (libc)Basic Scheduling Functions.
  1323. * sched_rr_get_interval: (libc)Basic Scheduling Functions.
  1324. * sched_setaffinity: (libc)CPU Affinity.
  1325. * sched_setparam: (libc)Basic Scheduling Functions.
  1326. * sched_setscheduler: (libc)Basic Scheduling Functions.
  1327. * sched_yield: (libc)Basic Scheduling Functions.
  1328. * secure_getenv: (libc)Environment Access.
  1329. * seed48: (libc)SVID Random.
  1330. * seed48_r: (libc)SVID Random.
  1331. * SEEK_CUR: (libc)File Positioning.
  1332. * seekdir: (libc)Random Access Directory.
  1333. * SEEK_END: (libc)File Positioning.
  1334. * SEEK_SET: (libc)File Positioning.
  1335. * select: (libc)Waiting for I/O.
  1336. * sem_close: (libc)Semaphores.
  1337. * semctl: (libc)Semaphores.
  1338. * sem_destroy: (libc)Semaphores.
  1339. * semget: (libc)Semaphores.
  1340. * sem_getvalue: (libc)Semaphores.
  1341. * sem_init: (libc)Semaphores.
  1342. * sem_open: (libc)Semaphores.
  1343. * semop: (libc)Semaphores.
  1344. * sem_post: (libc)Semaphores.
  1345. * semtimedop: (libc)Semaphores.
  1346. * sem_timedwait: (libc)Semaphores.
  1347. * sem_trywait: (libc)Semaphores.
  1348. * sem_unlink: (libc)Semaphores.
  1349. * sem_wait: (libc)Semaphores.
  1350. * send: (libc)Sending Data.
  1351. * sendmsg: (libc)Receiving Datagrams.
  1352. * sendto: (libc)Sending Datagrams.
  1353. * setbuffer: (libc)Controlling Buffering.
  1354. * setbuf: (libc)Controlling Buffering.
  1355. * setcontext: (libc)System V contexts.
  1356. * setdomainname: (libc)Host Identification.
  1357. * setegid: (libc)Setting Groups.
  1358. * setenv: (libc)Environment Access.
  1359. * seteuid: (libc)Setting User ID.
  1360. * setfsent: (libc)fstab.
  1361. * setgid: (libc)Setting Groups.
  1362. * setgrent: (libc)Scanning All Groups.
  1363. * setgroups: (libc)Setting Groups.
  1364. * sethostent: (libc)Host Names.
  1365. * sethostid: (libc)Host Identification.
  1366. * sethostname: (libc)Host Identification.
  1367. * setitimer: (libc)Setting an Alarm.
  1368. * setjmp: (libc)Non-Local Details.
  1369. * setkey: (libc)DES Encryption.
  1370. * setkey_r: (libc)DES Encryption.
  1371. * setlinebuf: (libc)Controlling Buffering.
  1372. * setlocale: (libc)Setting the Locale.
  1373. * setlogmask: (libc)setlogmask.
  1374. * setmntent: (libc)mtab.
  1375. * setnetent: (libc)Networks Database.
  1376. * setnetgrent: (libc)Lookup Netgroup.
  1377. * setpayloadf: (libc)FP Bit Twiddling.
  1378. * setpayload: (libc)FP Bit Twiddling.
  1379. * setpayloadl: (libc)FP Bit Twiddling.
  1380. * setpayloadsigf: (libc)FP Bit Twiddling.
  1381. * setpayloadsig: (libc)FP Bit Twiddling.
  1382. * setpayloadsigl: (libc)FP Bit Twiddling.
  1383. * setpgid: (libc)Process Group Functions.
  1384. * setpgrp: (libc)Process Group Functions.
  1385. * setpriority: (libc)Traditional Scheduling Functions.
  1386. * setprotoent: (libc)Protocols Database.
  1387. * setpwent: (libc)Scanning All Users.
  1388. * setregid: (libc)Setting Groups.
  1389. * setreuid: (libc)Setting User ID.
  1390. * setrlimit64: (libc)Limits on Resources.
  1391. * setrlimit: (libc)Limits on Resources.
  1392. * setservent: (libc)Services Database.
  1393. * setsid: (libc)Process Group Functions.
  1394. * setsockopt: (libc)Socket Option Functions.
  1395. * setstate: (libc)BSD Random.
  1396. * setstate_r: (libc)BSD Random.
  1397. * settimeofday: (libc)High-Resolution Calendar.
  1398. * setuid: (libc)Setting User ID.
  1399. * setutent: (libc)Manipulating the Database.
  1400. * setutxent: (libc)XPG Functions.
  1401. * setvbuf: (libc)Controlling Buffering.
  1402. * shm_open: (libc)Memory-mapped I/O.
  1403. * shm_unlink: (libc)Memory-mapped I/O.
  1404. * shutdown: (libc)Closing a Socket.
  1405. * S_IFMT: (libc)Testing File Type.
  1406. * SIGABRT: (libc)Program Error Signals.
  1407. * sigaction: (libc)Advanced Signal Handling.
  1408. * sigaddset: (libc)Signal Sets.
  1409. * SIGALRM: (libc)Alarm Signals.
  1410. * sigaltstack: (libc)Signal Stack.
  1411. * sigblock: (libc)BSD Signal Handling.
  1412. * SIGBUS: (libc)Program Error Signals.
  1413. * SIGCHLD: (libc)Job Control Signals.
  1414. * SIGCLD: (libc)Job Control Signals.
  1415. * SIGCONT: (libc)Job Control Signals.
  1416. * sigdelset: (libc)Signal Sets.
  1417. * sigemptyset: (libc)Signal Sets.
  1418. * SIGEMT: (libc)Program Error Signals.
  1419. * SIG_ERR: (libc)Basic Signal Handling.
  1420. * sigfillset: (libc)Signal Sets.
  1421. * SIGFPE: (libc)Program Error Signals.
  1422. * SIGHUP: (libc)Termination Signals.
  1423. * SIGILL: (libc)Program Error Signals.
  1424. * SIGINFO: (libc)Miscellaneous Signals.
  1425. * siginterrupt: (libc)BSD Signal Handling.
  1426. * SIGINT: (libc)Termination Signals.
  1427. * SIGIO: (libc)Asynchronous I/O Signals.
  1428. * SIGIOT: (libc)Program Error Signals.
  1429. * sigismember: (libc)Signal Sets.
  1430. * SIGKILL: (libc)Termination Signals.
  1431. * siglongjmp: (libc)Non-Local Exits and Signals.
  1432. * SIGLOST: (libc)Operation Error Signals.
  1433. * sigmask: (libc)BSD Signal Handling.
  1434. * signal: (libc)Basic Signal Handling.
  1435. * signbit: (libc)FP Bit Twiddling.
  1436. * significandf: (libc)Normalization Functions.
  1437. * significand: (libc)Normalization Functions.
  1438. * significandl: (libc)Normalization Functions.
  1439. * sigpause: (libc)BSD Signal Handling.
  1440. * sigpending: (libc)Checking for Pending Signals.
  1441. * SIGPIPE: (libc)Operation Error Signals.
  1442. * SIGPOLL: (libc)Asynchronous I/O Signals.
  1443. * sigprocmask: (libc)Process Signal Mask.
  1444. * SIGPROF: (libc)Alarm Signals.
  1445. * SIGQUIT: (libc)Termination Signals.
  1446. * SIGSEGV: (libc)Program Error Signals.
  1447. * sigsetjmp: (libc)Non-Local Exits and Signals.
  1448. * sigsetmask: (libc)BSD Signal Handling.
  1449. * sigstack: (libc)Signal Stack.
  1450. * SIGSTOP: (libc)Job Control Signals.
  1451. * sigsuspend: (libc)Sigsuspend.
  1452. * SIGSYS: (libc)Program Error Signals.
  1453. * SIGTERM: (libc)Termination Signals.
  1454. * SIGTRAP: (libc)Program Error Signals.
  1455. * SIGTSTP: (libc)Job Control Signals.
  1456. * SIGTTIN: (libc)Job Control Signals.
  1457. * SIGTTOU: (libc)Job Control Signals.
  1458. * SIGURG: (libc)Asynchronous I/O Signals.
  1459. * SIGUSR1: (libc)Miscellaneous Signals.
  1460. * SIGUSR2: (libc)Miscellaneous Signals.
  1461. * SIGVTALRM: (libc)Alarm Signals.
  1462. * SIGWINCH: (libc)Miscellaneous Signals.
  1463. * SIGXCPU: (libc)Operation Error Signals.
  1464. * SIGXFSZ: (libc)Operation Error Signals.
  1465. * sincosf: (libc)Trig Functions.
  1466. * sincos: (libc)Trig Functions.
  1467. * sincosl: (libc)Trig Functions.
  1468. * sinf: (libc)Trig Functions.
  1469. * sinhf: (libc)Hyperbolic Functions.
  1470. * sinh: (libc)Hyperbolic Functions.
  1471. * sinhl: (libc)Hyperbolic Functions.
  1472. * sin: (libc)Trig Functions.
  1473. * sinl: (libc)Trig Functions.
  1474. * S_ISBLK: (libc)Testing File Type.
  1475. * S_ISCHR: (libc)Testing File Type.
  1476. * S_ISDIR: (libc)Testing File Type.
  1477. * S_ISFIFO: (libc)Testing File Type.
  1478. * S_ISLNK: (libc)Testing File Type.
  1479. * S_ISREG: (libc)Testing File Type.
  1480. * S_ISSOCK: (libc)Testing File Type.
  1481. * sleep: (libc)Sleeping.
  1482. * SNANF: (libc)Infinity and NaN.
  1483. * SNAN: (libc)Infinity and NaN.
  1484. * SNANL: (libc)Infinity and NaN.
  1485. * snprintf: (libc)Formatted Output Functions.
  1486. * SOCK_DGRAM: (libc)Communication Styles.
  1487. * socket: (libc)Creating a Socket.
  1488. * socketpair: (libc)Socket Pairs.
  1489. * SOCK_RAW: (libc)Communication Styles.
  1490. * SOCK_RDM: (libc)Communication Styles.
  1491. * SOCK_SEQPACKET: (libc)Communication Styles.
  1492. * SOCK_STREAM: (libc)Communication Styles.
  1493. * SOL_SOCKET: (libc)Socket-Level Options.
  1494. * sprintf: (libc)Formatted Output Functions.
  1495. * sqrtf: (libc)Exponents and Logarithms.
  1496. * sqrt: (libc)Exponents and Logarithms.
  1497. * sqrtl: (libc)Exponents and Logarithms.
  1498. * srand48: (libc)SVID Random.
  1499. * srand48_r: (libc)SVID Random.
  1500. * srand: (libc)ISO Random.
  1501. * srandom: (libc)BSD Random.
  1502. * srandom_r: (libc)BSD Random.
  1503. * sscanf: (libc)Formatted Input Functions.
  1504. * ssignal: (libc)Basic Signal Handling.
  1505. * SSIZE_MAX: (libc)General Limits.
  1506. * stat64: (libc)Reading Attributes.
  1507. * stat: (libc)Reading Attributes.
  1508. * stime: (libc)Simple Calendar Time.
  1509. * stpcpy: (libc)Copying Strings and Arrays.
  1510. * stpncpy: (libc)Truncating Strings.
  1511. * strcasecmp: (libc)String/Array Comparison.
  1512. * strcasestr: (libc)Search Functions.
  1513. * strcat: (libc)Concatenating Strings.
  1514. * strchr: (libc)Search Functions.
  1515. * strchrnul: (libc)Search Functions.
  1516. * strcmp: (libc)String/Array Comparison.
  1517. * strcoll: (libc)Collation Functions.
  1518. * strcpy: (libc)Copying Strings and Arrays.
  1519. * strcspn: (libc)Search Functions.
  1520. * strdupa: (libc)Copying Strings and Arrays.
  1521. * strdup: (libc)Copying Strings and Arrays.
  1522. * STREAM_MAX: (libc)General Limits.
  1523. * strerror: (libc)Error Messages.
  1524. * strerror_r: (libc)Error Messages.
  1525. * strfmon: (libc)Formatting Numbers.
  1526. * strfromd: (libc)Printing of Floats.
  1527. * strfromf: (libc)Printing of Floats.
  1528. * strfroml: (libc)Printing of Floats.
  1529. * strfry: (libc)strfry.
  1530. * strftime: (libc)Formatting Calendar Time.
  1531. * strlen: (libc)String Length.
  1532. * strncasecmp: (libc)String/Array Comparison.
  1533. * strncat: (libc)Truncating Strings.
  1534. * strncmp: (libc)String/Array Comparison.
  1535. * strncpy: (libc)Truncating Strings.
  1536. * strndupa: (libc)Truncating Strings.
  1537. * strndup: (libc)Truncating Strings.
  1538. * strnlen: (libc)String Length.
  1539. * strpbrk: (libc)Search Functions.
  1540. * strptime: (libc)Low-Level Time String Parsing.
  1541. * strrchr: (libc)Search Functions.
  1542. * strsep: (libc)Finding Tokens in a String.
  1543. * strsignal: (libc)Signal Messages.
  1544. * strspn: (libc)Search Functions.
  1545. * strstr: (libc)Search Functions.
  1546. * strtod: (libc)Parsing of Floats.
  1547. * strtof: (libc)Parsing of Floats.
  1548. * strtoimax: (libc)Parsing of Integers.
  1549. * strtok: (libc)Finding Tokens in a String.
  1550. * strtok_r: (libc)Finding Tokens in a String.
  1551. * strtold: (libc)Parsing of Floats.
  1552. * strtol: (libc)Parsing of Integers.
  1553. * strtoll: (libc)Parsing of Integers.
  1554. * strtoq: (libc)Parsing of Integers.
  1555. * strtoul: (libc)Parsing of Integers.
  1556. * strtoull: (libc)Parsing of Integers.
  1557. * strtoumax: (libc)Parsing of Integers.
  1558. * strtouq: (libc)Parsing of Integers.
  1559. * strverscmp: (libc)String/Array Comparison.
  1560. * strxfrm: (libc)Collation Functions.
  1561. * stty: (libc)BSD Terminal Modes.
  1562. * S_TYPEISMQ: (libc)Testing File Type.
  1563. * S_TYPEISSEM: (libc)Testing File Type.
  1564. * S_TYPEISSHM: (libc)Testing File Type.
  1565. * SUN_LEN: (libc)Local Namespace Details.
  1566. * swapcontext: (libc)System V contexts.
  1567. * swprintf: (libc)Formatted Output Functions.
  1568. * swscanf: (libc)Formatted Input Functions.
  1569. * symlink: (libc)Symbolic Links.
  1570. * sync: (libc)Synchronizing I/O.
  1571. * syscall: (libc)System Calls.
  1572. * sysconf: (libc)Sysconf Definition.
  1573. * sysctl: (libc)System Parameters.
  1574. * syslog: (libc)syslog; vsyslog.
  1575. * system: (libc)Running a Command.
  1576. * sysv_signal: (libc)Basic Signal Handling.
  1577. * tanf: (libc)Trig Functions.
  1578. * tanhf: (libc)Hyperbolic Functions.
  1579. * tanh: (libc)Hyperbolic Functions.
  1580. * tanhl: (libc)Hyperbolic Functions.
  1581. * tan: (libc)Trig Functions.
  1582. * tanl: (libc)Trig Functions.
  1583. * tcdrain: (libc)Line Control.
  1584. * tcflow: (libc)Line Control.
  1585. * tcflush: (libc)Line Control.
  1586. * tcgetattr: (libc)Mode Functions.
  1587. * tcgetpgrp: (libc)Terminal Access Functions.
  1588. * tcgetsid: (libc)Terminal Access Functions.
  1589. * tcsendbreak: (libc)Line Control.
  1590. * tcsetattr: (libc)Mode Functions.
  1591. * tcsetpgrp: (libc)Terminal Access Functions.
  1592. * tdelete: (libc)Tree Search Function.
  1593. * tdestroy: (libc)Tree Search Function.
  1594. * telldir: (libc)Random Access Directory.
  1595. * tempnam: (libc)Temporary Files.
  1596. * textdomain: (libc)Locating gettext catalog.
  1597. * tfind: (libc)Tree Search Function.
  1598. * tgammaf: (libc)Special Functions.
  1599. * tgamma: (libc)Special Functions.
  1600. * tgammal: (libc)Special Functions.
  1601. * timegm: (libc)Broken-down Time.
  1602. * time: (libc)Simple Calendar Time.
  1603. * timelocal: (libc)Broken-down Time.
  1604. * times: (libc)Processor Time.
  1605. * tmpfile64: (libc)Temporary Files.
  1606. * tmpfile: (libc)Temporary Files.
  1607. * TMP_MAX: (libc)Temporary Files.
  1608. * tmpnam: (libc)Temporary Files.
  1609. * tmpnam_r: (libc)Temporary Files.
  1610. * toascii: (libc)Case Conversion.
  1611. * _tolower: (libc)Case Conversion.
  1612. * tolower: (libc)Case Conversion.
  1613. * TOSTOP: (libc)Local Modes.
  1614. * totalorderf: (libc)FP Comparison Functions.
  1615. * totalorder: (libc)FP Comparison Functions.
  1616. * totalorderl: (libc)FP Comparison Functions.
  1617. * totalordermagf: (libc)FP Comparison Functions.
  1618. * totalordermag: (libc)FP Comparison Functions.
  1619. * totalordermagl: (libc)FP Comparison Functions.
  1620. * _toupper: (libc)Case Conversion.
  1621. * toupper: (libc)Case Conversion.
  1622. * towctrans: (libc)Wide Character Case Conversion.
  1623. * towlower: (libc)Wide Character Case Conversion.
  1624. * towupper: (libc)Wide Character Case Conversion.
  1625. * truncate64: (libc)File Size.
  1626. * truncate: (libc)File Size.
  1627. * truncf: (libc)Rounding Functions.
  1628. * trunc: (libc)Rounding Functions.
  1629. * truncl: (libc)Rounding Functions.
  1630. * tsearch: (libc)Tree Search Function.
  1631. * ttyname: (libc)Is It a Terminal.
  1632. * ttyname_r: (libc)Is It a Terminal.
  1633. * twalk: (libc)Tree Search Function.
  1634. * TZNAME_MAX: (libc)General Limits.
  1635. * tzset: (libc)Time Zone Functions.
  1636. * ufromfpf: (libc)Rounding Functions.
  1637. * ufromfp: (libc)Rounding Functions.
  1638. * ufromfpl: (libc)Rounding Functions.
  1639. * ufromfpxf: (libc)Rounding Functions.
  1640. * ufromfpx: (libc)Rounding Functions.
  1641. * ufromfpxl: (libc)Rounding Functions.
  1642. * ulimit: (libc)Limits on Resources.
  1643. * umask: (libc)Setting Permissions.
  1644. * umount2: (libc)Mount-Unmount-Remount.
  1645. * umount: (libc)Mount-Unmount-Remount.
  1646. * uname: (libc)Platform Type.
  1647. * ungetc: (libc)How Unread.
  1648. * ungetwc: (libc)How Unread.
  1649. * unlink: (libc)Deleting Files.
  1650. * unlockpt: (libc)Allocation.
  1651. * unsetenv: (libc)Environment Access.
  1652. * updwtmp: (libc)Manipulating the Database.
  1653. * utime: (libc)File Times.
  1654. * utimes: (libc)File Times.
  1655. * utmpname: (libc)Manipulating the Database.
  1656. * utmpxname: (libc)XPG Functions.
  1657. * va_arg: (libc)Argument Macros.
  1658. * __va_copy: (libc)Argument Macros.
  1659. * va_copy: (libc)Argument Macros.
  1660. * va_end: (libc)Argument Macros.
  1661. * valloc: (libc)Aligned Memory Blocks.
  1662. * vasprintf: (libc)Variable Arguments Output.
  1663. * va_start: (libc)Argument Macros.
  1664. * VDISCARD: (libc)Other Special.
  1665. * VDSUSP: (libc)Signal Characters.
  1666. * VEOF: (libc)Editing Characters.
  1667. * VEOL2: (libc)Editing Characters.
  1668. * VEOL: (libc)Editing Characters.
  1669. * VERASE: (libc)Editing Characters.
  1670. * verr: (libc)Error Messages.
  1671. * verrx: (libc)Error Messages.
  1672. * versionsort64: (libc)Scanning Directory Content.
  1673. * versionsort: (libc)Scanning Directory Content.
  1674. * vfork: (libc)Creating a Process.
  1675. * vfprintf: (libc)Variable Arguments Output.
  1676. * vfscanf: (libc)Variable Arguments Input.
  1677. * vfwprintf: (libc)Variable Arguments Output.
  1678. * vfwscanf: (libc)Variable Arguments Input.
  1679. * VINTR: (libc)Signal Characters.
  1680. * VKILL: (libc)Editing Characters.
  1681. * vlimit: (libc)Limits on Resources.
  1682. * VLNEXT: (libc)Other Special.
  1683. * VMIN: (libc)Noncanonical Input.
  1684. * vprintf: (libc)Variable Arguments Output.
  1685. * VQUIT: (libc)Signal Characters.
  1686. * VREPRINT: (libc)Editing Characters.
  1687. * vscanf: (libc)Variable Arguments Input.
  1688. * vsnprintf: (libc)Variable Arguments Output.
  1689. * vsprintf: (libc)Variable Arguments Output.
  1690. * vsscanf: (libc)Variable Arguments Input.
  1691. * VSTART: (libc)Start/Stop Characters.
  1692. * VSTATUS: (libc)Other Special.
  1693. * VSTOP: (libc)Start/Stop Characters.
  1694. * VSUSP: (libc)Signal Characters.
  1695. * vswprintf: (libc)Variable Arguments Output.
  1696. * vswscanf: (libc)Variable Arguments Input.
  1697. * vsyslog: (libc)syslog; vsyslog.
  1698. * VTIME: (libc)Noncanonical Input.
  1699. * vtimes: (libc)Resource Usage.
  1700. * vwarn: (libc)Error Messages.
  1701. * vwarnx: (libc)Error Messages.
  1702. * VWERASE: (libc)Editing Characters.
  1703. * vwprintf: (libc)Variable Arguments Output.
  1704. * vwscanf: (libc)Variable Arguments Input.
  1705. * wait3: (libc)BSD Wait Functions.
  1706. * wait4: (libc)Process Completion.
  1707. * wait: (libc)Process Completion.
  1708. * waitpid: (libc)Process Completion.
  1709. * warn: (libc)Error Messages.
  1710. * warnx: (libc)Error Messages.
  1711. * WCHAR_MAX: (libc)Extended Char Intro.
  1712. * WCHAR_MIN: (libc)Extended Char Intro.
  1713. * WCOREDUMP: (libc)Process Completion Status.
  1714. * wcpcpy: (libc)Copying Strings and Arrays.
  1715. * wcpncpy: (libc)Truncating Strings.
  1716. * wcrtomb: (libc)Converting a Character.
  1717. * wcscasecmp: (libc)String/Array Comparison.
  1718. * wcscat: (libc)Concatenating Strings.
  1719. * wcschr: (libc)Search Functions.
  1720. * wcschrnul: (libc)Search Functions.
  1721. * wcscmp: (libc)String/Array Comparison.
  1722. * wcscoll: (libc)Collation Functions.
  1723. * wcscpy: (libc)Copying Strings and Arrays.
  1724. * wcscspn: (libc)Search Functions.
  1725. * wcsdup: (libc)Copying Strings and Arrays.
  1726. * wcsftime: (libc)Formatting Calendar Time.
  1727. * wcslen: (libc)String Length.
  1728. * wcsncasecmp: (libc)String/Array Comparison.
  1729. * wcsncat: (libc)Truncating Strings.
  1730. * wcsncmp: (libc)String/Array Comparison.
  1731. * wcsncpy: (libc)Truncating Strings.
  1732. * wcsnlen: (libc)String Length.
  1733. * wcsnrtombs: (libc)Converting Strings.
  1734. * wcspbrk: (libc)Search Functions.
  1735. * wcsrchr: (libc)Search Functions.
  1736. * wcsrtombs: (libc)Converting Strings.
  1737. * wcsspn: (libc)Search Functions.
  1738. * wcsstr: (libc)Search Functions.
  1739. * wcstod: (libc)Parsing of Floats.
  1740. * wcstof: (libc)Parsing of Floats.
  1741. * wcstoimax: (libc)Parsing of Integers.
  1742. * wcstok: (libc)Finding Tokens in a String.
  1743. * wcstold: (libc)Parsing of Floats.
  1744. * wcstol: (libc)Parsing of Integers.
  1745. * wcstoll: (libc)Parsing of Integers.
  1746. * wcstombs: (libc)Non-reentrant String Conversion.
  1747. * wcstoq: (libc)Parsing of Integers.
  1748. * wcstoul: (libc)Parsing of Integers.
  1749. * wcstoull: (libc)Parsing of Integers.
  1750. * wcstoumax: (libc)Parsing of Integers.
  1751. * wcstouq: (libc)Parsing of Integers.
  1752. * wcswcs: (libc)Search Functions.
  1753. * wcsxfrm: (libc)Collation Functions.
  1754. * wctob: (libc)Converting a Character.
  1755. * wctomb: (libc)Non-reentrant Character Conversion.
  1756. * wctrans: (libc)Wide Character Case Conversion.
  1757. * wctype: (libc)Classification of Wide Characters.
  1758. * WEOF: (libc)EOF and Errors.
  1759. * WEOF: (libc)Extended Char Intro.
  1760. * WEXITSTATUS: (libc)Process Completion Status.
  1761. * WIFEXITED: (libc)Process Completion Status.
  1762. * WIFSIGNALED: (libc)Process Completion Status.
  1763. * WIFSTOPPED: (libc)Process Completion Status.
  1764. * wmemchr: (libc)Search Functions.
  1765. * wmemcmp: (libc)String/Array Comparison.
  1766. * wmemcpy: (libc)Copying Strings and Arrays.
  1767. * wmemmove: (libc)Copying Strings and Arrays.
  1768. * wmempcpy: (libc)Copying Strings and Arrays.
  1769. * wmemset: (libc)Copying Strings and Arrays.
  1770. * W_OK: (libc)Testing File Access.
  1771. * wordexp: (libc)Calling Wordexp.
  1772. * wordfree: (libc)Calling Wordexp.
  1773. * wprintf: (libc)Formatted Output Functions.
  1774. * write: (libc)I/O Primitives.
  1775. * writev: (libc)Scatter-Gather.
  1776. * wscanf: (libc)Formatted Input Functions.
  1777. * WSTOPSIG: (libc)Process Completion Status.
  1778. * WTERMSIG: (libc)Process Completion Status.
  1779. * X_OK: (libc)Testing File Access.
  1780. * y0f: (libc)Special Functions.
  1781. * y0: (libc)Special Functions.
  1782. * y0l: (libc)Special Functions.
  1783. * y1f: (libc)Special Functions.
  1784. * y1: (libc)Special Functions.
  1785. * y1l: (libc)Special Functions.
  1786. * ynf: (libc)Special Functions.
  1787. * yn: (libc)Special Functions.
  1788. * ynl: (libc)Special Functions.
  1789. END-INFO-DIR-ENTRY
  1790. 
  1791. File: libc.info, Node: Obstacks, Next: Variable Size Automatic, Prev: Allocation Debugging, Up: Memory Allocation
  1792. 3.2.5 Obstacks
  1793. --------------
  1794. An "obstack" is a pool of memory containing a stack of objects. You can
  1795. create any number of separate obstacks, and then allocate objects in
  1796. specified obstacks. Within each obstack, the last object allocated must
  1797. always be the first one freed, but distinct obstacks are independent of
  1798. each other.
  1799. Aside from this one constraint of order of freeing, obstacks are
  1800. totally general: an obstack can contain any number of objects of any
  1801. size. They are implemented with macros, so allocation is usually very
  1802. fast as long as the objects are usually small. And the only space
  1803. overhead per object is the padding needed to start each object on a
  1804. suitable boundary.
  1805. * Menu:
  1806. * Creating Obstacks:: How to declare an obstack in your program.
  1807. * Preparing for Obstacks:: Preparations needed before you can
  1808. use obstacks.
  1809. * Allocation in an Obstack:: Allocating objects in an obstack.
  1810. * Freeing Obstack Objects:: Freeing objects in an obstack.
  1811. * Obstack Functions:: The obstack functions are both
  1812. functions and macros.
  1813. * Growing Objects:: Making an object bigger by stages.
  1814. * Extra Fast Growing:: Extra-high-efficiency (though more
  1815. complicated) growing objects.
  1816. * Status of an Obstack:: Inquiries about the status of an obstack.
  1817. * Obstacks Data Alignment:: Controlling alignment of objects in obstacks.
  1818. * Obstack Chunks:: How obstacks obtain and release chunks;
  1819. efficiency considerations.
  1820. * Summary of Obstacks::
  1821. 
  1822. File: libc.info, Node: Creating Obstacks, Next: Preparing for Obstacks, Up: Obstacks
  1823. 3.2.5.1 Creating Obstacks
  1824. .........................
  1825. The utilities for manipulating obstacks are declared in the header file
  1826. ‘obstack.h’.
  1827. -- Data Type: struct obstack
  1828. An obstack is represented by a data structure of type ‘struct
  1829. obstack’. This structure has a small fixed size; it records the
  1830. status of the obstack and how to find the space in which objects
  1831. are allocated. It does not contain any of the objects themselves.
  1832. You should not try to access the contents of the structure
  1833. directly; use only the functions described in this chapter.
  1834. You can declare variables of type ‘struct obstack’ and use them as
  1835. obstacks, or you can allocate obstacks dynamically like any other kind
  1836. of object. Dynamic allocation of obstacks allows your program to have a
  1837. variable number of different stacks. (You can even allocate an obstack
  1838. structure in another obstack, but this is rarely useful.)
  1839. All the functions that work with obstacks require you to specify
  1840. which obstack to use. You do this with a pointer of type ‘struct
  1841. obstack *’. In the following, we often say “an obstack” when strictly
  1842. speaking the object at hand is such a pointer.
  1843. The objects in the obstack are packed into large blocks called
  1844. "chunks". The ‘struct obstack’ structure points to a chain of the
  1845. chunks currently in use.
  1846. The obstack library obtains a new chunk whenever you allocate an
  1847. object that won’t fit in the previous chunk. Since the obstack library
  1848. manages chunks automatically, you don’t need to pay much attention to
  1849. them, but you do need to supply a function which the obstack library
  1850. should use to get a chunk. Usually you supply a function which uses
  1851. ‘malloc’ directly or indirectly. You must also supply a function to
  1852. free a chunk. These matters are described in the following section.
  1853. 
  1854. File: libc.info, Node: Preparing for Obstacks, Next: Allocation in an Obstack, Prev: Creating Obstacks, Up: Obstacks
  1855. 3.2.5.2 Preparing for Using Obstacks
  1856. ....................................
  1857. Each source file in which you plan to use the obstack functions must
  1858. include the header file ‘obstack.h’, like this:
  1859. #include <obstack.h>
  1860. Also, if the source file uses the macro ‘obstack_init’, it must
  1861. declare or define two functions or macros that will be called by the
  1862. obstack library. One, ‘obstack_chunk_alloc’, is used to allocate the
  1863. chunks of memory into which objects are packed. The other,
  1864. ‘obstack_chunk_free’, is used to return chunks when the objects in them
  1865. are freed. These macros should appear before any use of obstacks in the
  1866. source file.
  1867. Usually these are defined to use ‘malloc’ via the intermediary
  1868. ‘xmalloc’ (*note Unconstrained Allocation::). This is done with the
  1869. following pair of macro definitions:
  1870. #define obstack_chunk_alloc xmalloc
  1871. #define obstack_chunk_free free
  1872. Though the memory you get using obstacks really comes from ‘malloc’,
  1873. using obstacks is faster because ‘malloc’ is called less often, for
  1874. larger blocks of memory. *Note Obstack Chunks::, for full details.
  1875. At run time, before the program can use a ‘struct obstack’ object as
  1876. an obstack, it must initialize the obstack by calling ‘obstack_init’.
  1877. -- Function: int obstack_init (struct obstack *OBSTACK-PTR)
  1878. Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe mem |
  1879. *Note POSIX Safety Concepts::.
  1880. Initialize obstack OBSTACK-PTR for allocation of objects. This
  1881. function calls the obstack’s ‘obstack_chunk_alloc’ function. If
  1882. allocation of memory fails, the function pointed to by
  1883. ‘obstack_alloc_failed_handler’ is called. The ‘obstack_init’
  1884. function always returns 1 (Compatibility notice: Former versions of
  1885. obstack returned 0 if allocation failed).
  1886. Here are two examples of how to allocate the space for an obstack and
  1887. initialize it. First, an obstack that is a static variable:
  1888. static struct obstack myobstack;
  1889. obstack_init (&myobstack);
  1890. Second, an obstack that is itself dynamically allocated:
  1891. struct obstack *myobstack_ptr
  1892. = (struct obstack *) xmalloc (sizeof (struct obstack));
  1893. obstack_init (myobstack_ptr);
  1894. -- Variable: obstack_alloc_failed_handler
  1895. The value of this variable is a pointer to a function that
  1896. ‘obstack’ uses when ‘obstack_chunk_alloc’ fails to allocate memory.
  1897. The default action is to print a message and abort. You should
  1898. supply a function that either calls ‘exit’ (*note Program
  1899. Termination::) or ‘longjmp’ (*note Non-Local Exits::) and doesn’t
  1900. return.
  1901. void my_obstack_alloc_failed (void)
  1902. obstack_alloc_failed_handler = &my_obstack_alloc_failed;
  1903. 
  1904. File: libc.info, Node: Allocation in an Obstack, Next: Freeing Obstack Objects, Prev: Preparing for Obstacks, Up: Obstacks
  1905. 3.2.5.3 Allocation in an Obstack
  1906. ................................
  1907. The most direct way to allocate an object in an obstack is with
  1908. ‘obstack_alloc’, which is invoked almost like ‘malloc’.
  1909. -- Function: void * obstack_alloc (struct obstack *OBSTACK-PTR, int
  1910. SIZE)
  1911. Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
  1912. corrupt mem | *Note POSIX Safety Concepts::.
  1913. This allocates an uninitialized block of SIZE bytes in an obstack
  1914. and returns its address. Here OBSTACK-PTR specifies which obstack
  1915. to allocate the block in; it is the address of the ‘struct obstack’
  1916. object which represents the obstack. Each obstack function or
  1917. macro requires you to specify an OBSTACK-PTR as the first argument.
  1918. This function calls the obstack’s ‘obstack_chunk_alloc’ function if
  1919. it needs to allocate a new chunk of memory; it calls
  1920. ‘obstack_alloc_failed_handler’ if allocation of memory by
  1921. ‘obstack_chunk_alloc’ failed.
  1922. For example, here is a function that allocates a copy of a string STR
  1923. in a specific obstack, which is in the variable ‘string_obstack’:
  1924. struct obstack string_obstack;
  1925. char *
  1926. copystring (char *string)
  1927. {
  1928. size_t len = strlen (string) + 1;
  1929. char *s = (char *) obstack_alloc (&string_obstack, len);
  1930. memcpy (s, string, len);
  1931. return s;
  1932. }
  1933. To allocate a block with specified contents, use the function
  1934. ‘obstack_copy’, declared like this:
  1935. -- Function: void * obstack_copy (struct obstack *OBSTACK-PTR, void
  1936. *ADDRESS, int SIZE)
  1937. Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
  1938. corrupt mem | *Note POSIX Safety Concepts::.
  1939. This allocates a block and initializes it by copying SIZE bytes of
  1940. data starting at ADDRESS. It calls ‘obstack_alloc_failed_handler’
  1941. if allocation of memory by ‘obstack_chunk_alloc’ failed.
  1942. -- Function: void * obstack_copy0 (struct obstack *OBSTACK-PTR, void
  1943. *ADDRESS, int SIZE)
  1944. Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
  1945. corrupt mem | *Note POSIX Safety Concepts::.
  1946. Like ‘obstack_copy’, but appends an extra byte containing a null
  1947. character. This extra byte is not counted in the argument SIZE.
  1948. The ‘obstack_copy0’ function is convenient for copying a sequence of
  1949. characters into an obstack as a null-terminated string. Here is an
  1950. example of its use:
  1951. char *
  1952. obstack_savestring (char *addr, int size)
  1953. {
  1954. return obstack_copy0 (&myobstack, addr, size);
  1955. }
  1956. Contrast this with the previous example of ‘savestring’ using ‘malloc’
  1957. (*note Basic Allocation::).
  1958. 
  1959. File: libc.info, Node: Freeing Obstack Objects, Next: Obstack Functions, Prev: Allocation in an Obstack, Up: Obstacks
  1960. 3.2.5.4 Freeing Objects in an Obstack
  1961. .....................................
  1962. To free an object allocated in an obstack, use the function
  1963. ‘obstack_free’. Since the obstack is a stack of objects, freeing one
  1964. object automatically frees all other objects allocated more recently in
  1965. the same obstack.
  1966. -- Function: void obstack_free (struct obstack *OBSTACK-PTR, void
  1967. *OBJECT)
  1968. Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
  1969. corrupt | *Note POSIX Safety Concepts::.
  1970. If OBJECT is a null pointer, everything allocated in the obstack is
  1971. freed. Otherwise, OBJECT must be the address of an object
  1972. allocated in the obstack. Then OBJECT is freed, along with
  1973. everything allocated in OBSTACK-PTR since OBJECT.
  1974. Note that if OBJECT is a null pointer, the result is an uninitialized
  1975. obstack. To free all memory in an obstack but leave it valid for
  1976. further allocation, call ‘obstack_free’ with the address of the first
  1977. object allocated on the obstack:
  1978. obstack_free (obstack_ptr, first_object_allocated_ptr);
  1979. Recall that the objects in an obstack are grouped into chunks. When
  1980. all the objects in a chunk become free, the obstack library
  1981. automatically frees the chunk (*note Preparing for Obstacks::). Then
  1982. other obstacks, or non-obstack allocation, can reuse the space of the
  1983. chunk.
  1984. 
  1985. File: libc.info, Node: Obstack Functions, Next: Growing Objects, Prev: Freeing Obstack Objects, Up: Obstacks
  1986. 3.2.5.5 Obstack Functions and Macros
  1987. ....................................
  1988. The interfaces for using obstacks may be defined either as functions or
  1989. as macros, depending on the compiler. The obstack facility works with
  1990. all C compilers, including both ISO C and traditional C, but there are
  1991. precautions you must take if you plan to use compilers other than GNU C.
  1992. If you are using an old-fashioned non-ISO C compiler, all the obstack
  1993. “functions” are actually defined only as macros. You can call these
  1994. macros like functions, but you cannot use them in any other way (for
  1995. example, you cannot take their address).
  1996. Calling the macros requires a special precaution: namely, the first
  1997. operand (the obstack pointer) may not contain any side effects, because
  1998. it may be computed more than once. For example, if you write this:
  1999. obstack_alloc (get_obstack (), 4);
  2000. you will find that ‘get_obstack’ may be called several times. If you
  2001. use ‘*obstack_list_ptr++’ as the obstack pointer argument, you will get
  2002. very strange results since the incrementation may occur several times.
  2003. In ISO C, each function has both a macro definition and a function
  2004. definition. The function definition is used if you take the address of
  2005. the function without calling it. An ordinary call uses the macro
  2006. definition by default, but you can request the function definition
  2007. instead by writing the function name in parentheses, as shown here:
  2008. char *x;
  2009. void *(*funcp) ();
  2010. /* Use the macro. */
  2011. x = (char *) obstack_alloc (obptr, size);
  2012. /* Call the function. */
  2013. x = (char *) (obstack_alloc) (obptr, size);
  2014. /* Take the address of the function. */
  2015. funcp = obstack_alloc;
  2016. This is the same situation that exists in ISO C for the standard library
  2017. functions. *Note Macro Definitions::.
  2018. *Warning:* When you do use the macros, you must observe the
  2019. precaution of avoiding side effects in the first operand, even in ISO C.
  2020. If you use the GNU C compiler, this precaution is not necessary,
  2021. because various language extensions in GNU C permit defining the macros
  2022. so as to compute each argument only once.
  2023. 
  2024. File: libc.info, Node: Growing Objects, Next: Extra Fast Growing, Prev: Obstack Functions, Up: Obstacks
  2025. 3.2.5.6 Growing Objects
  2026. .......................
  2027. Because memory in obstack chunks is used sequentially, it is possible to
  2028. build up an object step by step, adding one or more bytes at a time to
  2029. the end of the object. With this technique, you do not need to know how
  2030. much data you will put in the object until you come to the end of it.
  2031. We call this the technique of "growing objects". The special functions
  2032. for adding data to the growing object are described in this section.
  2033. You don’t need to do anything special when you start to grow an
  2034. object. Using one of the functions to add data to the object
  2035. automatically starts it. However, it is necessary to say explicitly
  2036. when the object is finished. This is done with the function
  2037. ‘obstack_finish’.
  2038. The actual address of the object thus built up is not known until the
  2039. object is finished. Until then, it always remains possible that you
  2040. will add so much data that the object must be copied into a new chunk.
  2041. While the obstack is in use for a growing object, you cannot use it
  2042. for ordinary allocation of another object. If you try to do so, the
  2043. space already added to the growing object will become part of the other
  2044. object.
  2045. -- Function: void obstack_blank (struct obstack *OBSTACK-PTR, int SIZE)
  2046. Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
  2047. corrupt mem | *Note POSIX Safety Concepts::.
  2048. The most basic function for adding to a growing object is
  2049. ‘obstack_blank’, which adds space without initializing it.
  2050. -- Function: void obstack_grow (struct obstack *OBSTACK-PTR, void
  2051. *DATA, int SIZE)
  2052. Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
  2053. corrupt mem | *Note POSIX Safety Concepts::.
  2054. To add a block of initialized space, use ‘obstack_grow’, which is
  2055. the growing-object analogue of ‘obstack_copy’. It adds SIZE bytes
  2056. of data to the growing object, copying the contents from DATA.
  2057. -- Function: void obstack_grow0 (struct obstack *OBSTACK-PTR, void
  2058. *DATA, int SIZE)
  2059. Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
  2060. corrupt mem | *Note POSIX Safety Concepts::.
  2061. This is the growing-object analogue of ‘obstack_copy0’. It adds
  2062. SIZE bytes copied from DATA, followed by an additional null
  2063. character.
  2064. -- Function: void obstack_1grow (struct obstack *OBSTACK-PTR, char C)
  2065. Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
  2066. corrupt mem | *Note POSIX Safety Concepts::.
  2067. To add one character at a time, use the function ‘obstack_1grow’.
  2068. It adds a single byte containing C to the growing object.
  2069. -- Function: void obstack_ptr_grow (struct obstack *OBSTACK-PTR, void
  2070. *DATA)
  2071. Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
  2072. corrupt mem | *Note POSIX Safety Concepts::.
  2073. Adding the value of a pointer one can use the function
  2074. ‘obstack_ptr_grow’. It adds ‘sizeof (void *)’ bytes containing the
  2075. value of DATA.
  2076. -- Function: void obstack_int_grow (struct obstack *OBSTACK-PTR, int
  2077. DATA)
  2078. Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
  2079. corrupt mem | *Note POSIX Safety Concepts::.
  2080. A single value of type ‘int’ can be added by using the
  2081. ‘obstack_int_grow’ function. It adds ‘sizeof (int)’ bytes to the
  2082. growing object and initializes them with the value of DATA.
  2083. -- Function: void * obstack_finish (struct obstack *OBSTACK-PTR)
  2084. Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
  2085. corrupt | *Note POSIX Safety Concepts::.
  2086. When you are finished growing the object, use the function
  2087. ‘obstack_finish’ to close it off and return its final address.
  2088. Once you have finished the object, the obstack is available for
  2089. ordinary allocation or for growing another object.
  2090. This function can return a null pointer under the same conditions
  2091. as ‘obstack_alloc’ (*note Allocation in an Obstack::).
  2092. When you build an object by growing it, you will probably need to
  2093. know afterward how long it became. You need not keep track of this as
  2094. you grow the object, because you can find out the length from the
  2095. obstack just before finishing the object with the function
  2096. ‘obstack_object_size’, declared as follows:
  2097. -- Function: int obstack_object_size (struct obstack *OBSTACK-PTR)
  2098. Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | *Note
  2099. POSIX Safety Concepts::.
  2100. This function returns the current size of the growing object, in
  2101. bytes. Remember to call this function _before_ finishing the
  2102. object. After it is finished, ‘obstack_object_size’ will return
  2103. zero.
  2104. If you have started growing an object and wish to cancel it, you
  2105. should finish it and then free it, like this:
  2106. obstack_free (obstack_ptr, obstack_finish (obstack_ptr));
  2107. This has no effect if no object was growing.
  2108. You can use ‘obstack_blank’ with a negative size argument to make the
  2109. current object smaller. Just don’t try to shrink it beyond zero
  2110. length—there’s no telling what will happen if you do that.
  2111. 
  2112. File: libc.info, Node: Extra Fast Growing, Next: Status of an Obstack, Prev: Growing Objects, Up: Obstacks
  2113. 3.2.5.7 Extra Fast Growing Objects
  2114. ..................................
  2115. The usual functions for growing objects incur overhead for checking
  2116. whether there is room for the new growth in the current chunk. If you
  2117. are frequently constructing objects in small steps of growth, this
  2118. overhead can be significant.
  2119. You can reduce the overhead by using special “fast growth” functions
  2120. that grow the object without checking. In order to have a robust
  2121. program, you must do the checking yourself. If you do this checking in
  2122. the simplest way each time you are about to add data to the object, you
  2123. have not saved anything, because that is what the ordinary growth
  2124. functions do. But if you can arrange to check less often, or check more
  2125. efficiently, then you make the program faster.
  2126. The function ‘obstack_room’ returns the amount of room available in
  2127. the current chunk. It is declared as follows:
  2128. -- Function: int obstack_room (struct obstack *OBSTACK-PTR)
  2129. Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | *Note
  2130. POSIX Safety Concepts::.
  2131. This returns the number of bytes that can be added safely to the
  2132. current growing object (or to an object about to be started) in
  2133. obstack OBSTACK-PTR using the fast growth functions.
  2134. While you know there is room, you can use these fast growth functions
  2135. for adding data to a growing object:
  2136. -- Function: void obstack_1grow_fast (struct obstack *OBSTACK-PTR, char
  2137. C)
  2138. Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Unsafe
  2139. corrupt mem | *Note POSIX Safety Concepts::.
  2140. The function ‘obstack_1grow_fast’ adds one byte containing the
  2141. character C to the growing object in obstack OBSTACK-PTR.
  2142. -- Function: void obstack_ptr_grow_fast (struct obstack *OBSTACK-PTR,
  2143. void *DATA)
  2144. Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | *Note
  2145. POSIX Safety Concepts::.
  2146. The function ‘obstack_ptr_grow_fast’ adds ‘sizeof (void *)’ bytes
  2147. containing the value of DATA to the growing object in obstack
  2148. OBSTACK-PTR.
  2149. -- Function: void obstack_int_grow_fast (struct obstack *OBSTACK-PTR,
  2150. int DATA)
  2151. Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | *Note
  2152. POSIX Safety Concepts::.
  2153. The function ‘obstack_int_grow_fast’ adds ‘sizeof (int)’ bytes
  2154. containing the value of DATA to the growing object in obstack
  2155. OBSTACK-PTR.
  2156. -- Function: void obstack_blank_fast (struct obstack *OBSTACK-PTR, int
  2157. SIZE)
  2158. Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | *Note
  2159. POSIX Safety Concepts::.
  2160. The function ‘obstack_blank_fast’ adds SIZE bytes to the growing
  2161. object in obstack OBSTACK-PTR without initializing them.
  2162. When you check for space using ‘obstack_room’ and there is not enough
  2163. room for what you want to add, the fast growth functions are not safe.
  2164. In this case, simply use the corresponding ordinary growth function
  2165. instead. Very soon this will copy the object to a new chunk; then there
  2166. will be lots of room available again.
  2167. So, each time you use an ordinary growth function, check afterward
  2168. for sufficient space using ‘obstack_room’. Once the object is copied to
  2169. a new chunk, there will be plenty of space again, so the program will
  2170. start using the fast growth functions again.
  2171. Here is an example:
  2172. void
  2173. add_string (struct obstack *obstack, const char *ptr, int len)
  2174. {
  2175. while (len > 0)
  2176. {
  2177. int room = obstack_room (obstack);
  2178. if (room == 0)
  2179. {
  2180. /* Not enough room. Add one character slowly,
  2181. which may copy to a new chunk and make room. */
  2182. obstack_1grow (obstack, *ptr++);
  2183. len--;
  2184. }
  2185. else
  2186. {
  2187. if (room > len)
  2188. room = len;
  2189. /* Add fast as much as we have room for. */
  2190. len -= room;
  2191. while (room-- > 0)
  2192. obstack_1grow_fast (obstack, *ptr++);
  2193. }
  2194. }
  2195. }
  2196. 
  2197. File: libc.info, Node: Status of an Obstack, Next: Obstacks Data Alignment, Prev: Extra Fast Growing, Up: Obstacks
  2198. 3.2.5.8 Status of an Obstack
  2199. ............................
  2200. Here are functions that provide information on the current status of
  2201. allocation in an obstack. You can use them to learn about an object
  2202. while still growing it.
  2203. -- Function: void * obstack_base (struct obstack *OBSTACK-PTR)
  2204. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Safe | *Note POSIX
  2205. Safety Concepts::.
  2206. This function returns the tentative address of the beginning of the
  2207. currently growing object in OBSTACK-PTR. If you finish the object
  2208. immediately, it will have that address. If you make it larger
  2209. first, it may outgrow the current chunk—then its address will
  2210. change!
  2211. If no object is growing, this value says where the next object you
  2212. allocate will start (once again assuming it fits in the current
  2213. chunk).
  2214. -- Function: void * obstack_next_free (struct obstack *OBSTACK-PTR)
  2215. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Safe | *Note POSIX
  2216. Safety Concepts::.
  2217. This function returns the address of the first free byte in the
  2218. current chunk of obstack OBSTACK-PTR. This is the end of the
  2219. currently growing object. If no object is growing,
  2220. ‘obstack_next_free’ returns the same value as ‘obstack_base’.
  2221. -- Function: int obstack_object_size (struct obstack *OBSTACK-PTR)
  2222. Preliminary: | MT-Safe race:obstack-ptr | AS-Safe | AC-Safe | *Note
  2223. POSIX Safety Concepts::.
  2224. This function returns the size in bytes of the currently growing
  2225. object. This is equivalent to
  2226. obstack_next_free (OBSTACK-PTR) - obstack_base (OBSTACK-PTR)
  2227. 
  2228. File: libc.info, Node: Obstacks Data Alignment, Next: Obstack Chunks, Prev: Status of an Obstack, Up: Obstacks
  2229. 3.2.5.9 Alignment of Data in Obstacks
  2230. .....................................
  2231. Each obstack has an "alignment boundary"; each object allocated in the
  2232. obstack automatically starts on an address that is a multiple of the
  2233. specified boundary. By default, this boundary is aligned so that the
  2234. object can hold any type of data.
  2235. To access an obstack’s alignment boundary, use the macro
  2236. ‘obstack_alignment_mask’, whose function prototype looks like this:
  2237. -- Macro: int obstack_alignment_mask (struct obstack *OBSTACK-PTR)
  2238. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2239. Concepts::.
  2240. The value is a bit mask; a bit that is 1 indicates that the
  2241. corresponding bit in the address of an object should be 0. The
  2242. mask value should be one less than a power of 2; the effect is that
  2243. all object addresses are multiples of that power of 2. The default
  2244. value of the mask is a value that allows aligned objects to hold
  2245. any type of data: for example, if its value is 3, any type of data
  2246. can be stored at locations whose addresses are multiples of 4. A
  2247. mask value of 0 means an object can start on any multiple of 1
  2248. (that is, no alignment is required).
  2249. The expansion of the macro ‘obstack_alignment_mask’ is an lvalue,
  2250. so you can alter the mask by assignment. For example, this
  2251. statement:
  2252. obstack_alignment_mask (obstack_ptr) = 0;
  2253. has the effect of turning off alignment processing in the specified
  2254. obstack.
  2255. Note that a change in alignment mask does not take effect until
  2256. _after_ the next time an object is allocated or finished in the obstack.
  2257. If you are not growing an object, you can make the new alignment mask
  2258. take effect immediately by calling ‘obstack_finish’. This will finish a
  2259. zero-length object and then do proper alignment for the next object.
  2260. 
  2261. File: libc.info, Node: Obstack Chunks, Next: Summary of Obstacks, Prev: Obstacks Data Alignment, Up: Obstacks
  2262. 3.2.5.10 Obstack Chunks
  2263. .......................
  2264. Obstacks work by allocating space for themselves in large chunks, and
  2265. then parceling out space in the chunks to satisfy your requests. Chunks
  2266. are normally 4096 bytes long unless you specify a different chunk size.
  2267. The chunk size includes 8 bytes of overhead that are not actually used
  2268. for storing objects. Regardless of the specified size, longer chunks
  2269. will be allocated when necessary for long objects.
  2270. The obstack library allocates chunks by calling the function
  2271. ‘obstack_chunk_alloc’, which you must define. When a chunk is no longer
  2272. needed because you have freed all the objects in it, the obstack library
  2273. frees the chunk by calling ‘obstack_chunk_free’, which you must also
  2274. define.
  2275. These two must be defined (as macros) or declared (as functions) in
  2276. each source file that uses ‘obstack_init’ (*note Creating Obstacks::).
  2277. Most often they are defined as macros like this:
  2278. #define obstack_chunk_alloc malloc
  2279. #define obstack_chunk_free free
  2280. Note that these are simple macros (no arguments). Macro definitions
  2281. with arguments will not work! It is necessary that
  2282. ‘obstack_chunk_alloc’ or ‘obstack_chunk_free’, alone, expand into a
  2283. function name if it is not itself a function name.
  2284. If you allocate chunks with ‘malloc’, the chunk size should be a
  2285. power of 2. The default chunk size, 4096, was chosen because it is long
  2286. enough to satisfy many typical requests on the obstack yet short enough
  2287. not to waste too much memory in the portion of the last chunk not yet
  2288. used.
  2289. -- Macro: int obstack_chunk_size (struct obstack *OBSTACK-PTR)
  2290. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2291. Concepts::.
  2292. This returns the chunk size of the given obstack.
  2293. Since this macro expands to an lvalue, you can specify a new chunk
  2294. size by assigning it a new value. Doing so does not affect the chunks
  2295. already allocated, but will change the size of chunks allocated for that
  2296. particular obstack in the future. It is unlikely to be useful to make
  2297. the chunk size smaller, but making it larger might improve efficiency if
  2298. you are allocating many objects whose size is comparable to the chunk
  2299. size. Here is how to do so cleanly:
  2300. if (obstack_chunk_size (obstack_ptr) < NEW-CHUNK-SIZE)
  2301. obstack_chunk_size (obstack_ptr) = NEW-CHUNK-SIZE;
  2302. 
  2303. File: libc.info, Node: Summary of Obstacks, Prev: Obstack Chunks, Up: Obstacks
  2304. 3.2.5.11 Summary of Obstack Functions
  2305. .....................................
  2306. Here is a summary of all the functions associated with obstacks. Each
  2307. takes the address of an obstack (‘struct obstack *’) as its first
  2308. argument.
  2309. ‘void obstack_init (struct obstack *OBSTACK-PTR)’
  2310. Initialize use of an obstack. *Note Creating Obstacks::.
  2311. ‘void *obstack_alloc (struct obstack *OBSTACK-PTR, int SIZE)’
  2312. Allocate an object of SIZE uninitialized bytes. *Note Allocation
  2313. in an Obstack::.
  2314. ‘void *obstack_copy (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)’
  2315. Allocate an object of SIZE bytes, with contents copied from
  2316. ADDRESS. *Note Allocation in an Obstack::.
  2317. ‘void *obstack_copy0 (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)’
  2318. Allocate an object of SIZE+1 bytes, with SIZE of them copied from
  2319. ADDRESS, followed by a null character at the end. *Note Allocation
  2320. in an Obstack::.
  2321. ‘void obstack_free (struct obstack *OBSTACK-PTR, void *OBJECT)’
  2322. Free OBJECT (and everything allocated in the specified obstack more
  2323. recently than OBJECT). *Note Freeing Obstack Objects::.
  2324. ‘void obstack_blank (struct obstack *OBSTACK-PTR, int SIZE)’
  2325. Add SIZE uninitialized bytes to a growing object. *Note Growing
  2326. Objects::.
  2327. ‘void obstack_grow (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)’
  2328. Add SIZE bytes, copied from ADDRESS, to a growing object. *Note
  2329. Growing Objects::.
  2330. ‘void obstack_grow0 (struct obstack *OBSTACK-PTR, void *ADDRESS, int SIZE)’
  2331. Add SIZE bytes, copied from ADDRESS, to a growing object, and then
  2332. add another byte containing a null character. *Note Growing
  2333. Objects::.
  2334. ‘void obstack_1grow (struct obstack *OBSTACK-PTR, char DATA-CHAR)’
  2335. Add one byte containing DATA-CHAR to a growing object. *Note
  2336. Growing Objects::.
  2337. ‘void *obstack_finish (struct obstack *OBSTACK-PTR)’
  2338. Finalize the object that is growing and return its permanent
  2339. address. *Note Growing Objects::.
  2340. ‘int obstack_object_size (struct obstack *OBSTACK-PTR)’
  2341. Get the current size of the currently growing object. *Note
  2342. Growing Objects::.
  2343. ‘void obstack_blank_fast (struct obstack *OBSTACK-PTR, int SIZE)’
  2344. Add SIZE uninitialized bytes to a growing object without checking
  2345. that there is enough room. *Note Extra Fast Growing::.
  2346. ‘void obstack_1grow_fast (struct obstack *OBSTACK-PTR, char DATA-CHAR)’
  2347. Add one byte containing DATA-CHAR to a growing object without
  2348. checking that there is enough room. *Note Extra Fast Growing::.
  2349. ‘int obstack_room (struct obstack *OBSTACK-PTR)’
  2350. Get the amount of room now available for growing the current
  2351. object. *Note Extra Fast Growing::.
  2352. ‘int obstack_alignment_mask (struct obstack *OBSTACK-PTR)’
  2353. The mask used for aligning the beginning of an object. This is an
  2354. lvalue. *Note Obstacks Data Alignment::.
  2355. ‘int obstack_chunk_size (struct obstack *OBSTACK-PTR)’
  2356. The size for allocating chunks. This is an lvalue. *Note Obstack
  2357. Chunks::.
  2358. ‘void *obstack_base (struct obstack *OBSTACK-PTR)’
  2359. Tentative starting address of the currently growing object. *Note
  2360. Status of an Obstack::.
  2361. ‘void *obstack_next_free (struct obstack *OBSTACK-PTR)’
  2362. Address just after the end of the currently growing object. *Note
  2363. Status of an Obstack::.
  2364. 
  2365. File: libc.info, Node: Variable Size Automatic, Prev: Obstacks, Up: Memory Allocation
  2366. 3.2.6 Automatic Storage with Variable Size
  2367. ------------------------------------------
  2368. The function ‘alloca’ supports a kind of half-dynamic allocation in
  2369. which blocks are allocated dynamically but freed automatically.
  2370. Allocating a block with ‘alloca’ is an explicit action; you can
  2371. allocate as many blocks as you wish, and compute the size at run time.
  2372. But all the blocks are freed when you exit the function that ‘alloca’
  2373. was called from, just as if they were automatic variables declared in
  2374. that function. There is no way to free the space explicitly.
  2375. The prototype for ‘alloca’ is in ‘stdlib.h’. This function is a BSD
  2376. extension.
  2377. -- Function: void * alloca (size_t SIZE)
  2378. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2379. Concepts::.
  2380. The return value of ‘alloca’ is the address of a block of SIZE
  2381. bytes of memory, allocated in the stack frame of the calling
  2382. function.
  2383. Do not use ‘alloca’ inside the arguments of a function call—you will
  2384. get unpredictable results, because the stack space for the ‘alloca’
  2385. would appear on the stack in the middle of the space for the function
  2386. arguments. An example of what to avoid is ‘foo (x, alloca (4), y)’.
  2387. * Menu:
  2388. * Alloca Example:: Example of using ‘alloca’.
  2389. * Advantages of Alloca:: Reasons to use ‘alloca’.
  2390. * Disadvantages of Alloca:: Reasons to avoid ‘alloca’.
  2391. * GNU C Variable-Size Arrays:: Only in GNU C, here is an alternative
  2392. method of allocating dynamically and
  2393. freeing automatically.
  2394. 
  2395. File: libc.info, Node: Alloca Example, Next: Advantages of Alloca, Up: Variable Size Automatic
  2396. 3.2.6.1 ‘alloca’ Example
  2397. ........................
  2398. As an example of the use of ‘alloca’, here is a function that opens a
  2399. file name made from concatenating two argument strings, and returns a
  2400. file descriptor or minus one signifying failure:
  2401. int
  2402. open2 (char *str1, char *str2, int flags, int mode)
  2403. {
  2404. char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
  2405. stpcpy (stpcpy (name, str1), str2);
  2406. return open (name, flags, mode);
  2407. }
  2408. Here is how you would get the same results with ‘malloc’ and ‘free’:
  2409. int
  2410. open2 (char *str1, char *str2, int flags, int mode)
  2411. {
  2412. char *name = (char *) malloc (strlen (str1) + strlen (str2) + 1);
  2413. int desc;
  2414. if (name == 0)
  2415. fatal ("virtual memory exceeded");
  2416. stpcpy (stpcpy (name, str1), str2);
  2417. desc = open (name, flags, mode);
  2418. free (name);
  2419. return desc;
  2420. }
  2421. As you can see, it is simpler with ‘alloca’. But ‘alloca’ has other,
  2422. more important advantages, and some disadvantages.
  2423. 
  2424. File: libc.info, Node: Advantages of Alloca, Next: Disadvantages of Alloca, Prev: Alloca Example, Up: Variable Size Automatic
  2425. 3.2.6.2 Advantages of ‘alloca’
  2426. ..............................
  2427. Here are the reasons why ‘alloca’ may be preferable to ‘malloc’:
  2428. • Using ‘alloca’ wastes very little space and is very fast. (It is
  2429. open-coded by the GNU C compiler.)
  2430. • Since ‘alloca’ does not have separate pools for different sizes of
  2431. blocks, space used for any size block can be reused for any other
  2432. size. ‘alloca’ does not cause memory fragmentation.
  2433. • Nonlocal exits done with ‘longjmp’ (*note Non-Local Exits::)
  2434. automatically free the space allocated with ‘alloca’ when they exit
  2435. through the function that called ‘alloca’. This is the most
  2436. important reason to use ‘alloca’.
  2437. To illustrate this, suppose you have a function
  2438. ‘open_or_report_error’ which returns a descriptor, like ‘open’, if
  2439. it succeeds, but does not return to its caller if it fails. If the
  2440. file cannot be opened, it prints an error message and jumps out to
  2441. the command level of your program using ‘longjmp’. Let’s change
  2442. ‘open2’ (*note Alloca Example::) to use this subroutine:
  2443. int
  2444. open2 (char *str1, char *str2, int flags, int mode)
  2445. {
  2446. char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
  2447. stpcpy (stpcpy (name, str1), str2);
  2448. return open_or_report_error (name, flags, mode);
  2449. }
  2450. Because of the way ‘alloca’ works, the memory it allocates is freed
  2451. even when an error occurs, with no special effort required.
  2452. By contrast, the previous definition of ‘open2’ (which uses
  2453. ‘malloc’ and ‘free’) would develop a memory leak if it were changed
  2454. in this way. Even if you are willing to make more changes to fix
  2455. it, there is no easy way to do so.
  2456. 
  2457. File: libc.info, Node: Disadvantages of Alloca, Next: GNU C Variable-Size Arrays, Prev: Advantages of Alloca, Up: Variable Size Automatic
  2458. 3.2.6.3 Disadvantages of ‘alloca’
  2459. .................................
  2460. These are the disadvantages of ‘alloca’ in comparison with ‘malloc’:
  2461. • If you try to allocate more memory than the machine can provide,
  2462. you don’t get a clean error message. Instead you get a fatal
  2463. signal like the one you would get from an infinite recursion;
  2464. probably a segmentation violation (*note Program Error Signals::).
  2465. • Some non-GNU systems fail to support ‘alloca’, so it is less
  2466. portable. However, a slower emulation of ‘alloca’ written in C is
  2467. available for use on systems with this deficiency.
  2468. 
  2469. File: libc.info, Node: GNU C Variable-Size Arrays, Prev: Disadvantages of Alloca, Up: Variable Size Automatic
  2470. 3.2.6.4 GNU C Variable-Size Arrays
  2471. ..................................
  2472. In GNU C, you can replace most uses of ‘alloca’ with an array of
  2473. variable size. Here is how ‘open2’ would look then:
  2474. int open2 (char *str1, char *str2, int flags, int mode)
  2475. {
  2476. char name[strlen (str1) + strlen (str2) + 1];
  2477. stpcpy (stpcpy (name, str1), str2);
  2478. return open (name, flags, mode);
  2479. }
  2480. But ‘alloca’ is not always equivalent to a variable-sized array, for
  2481. several reasons:
  2482. • A variable size array’s space is freed at the end of the scope of
  2483. the name of the array. The space allocated with ‘alloca’ remains
  2484. until the end of the function.
  2485. • It is possible to use ‘alloca’ within a loop, allocating an
  2486. additional block on each iteration. This is impossible with
  2487. variable-sized arrays.
  2488. *NB:* If you mix use of ‘alloca’ and variable-sized arrays within one
  2489. function, exiting a scope in which a variable-sized array was declared
  2490. frees all blocks allocated with ‘alloca’ during the execution of that
  2491. scope.
  2492. 
  2493. File: libc.info, Node: Resizing the Data Segment, Next: Locking Pages, Prev: Memory Allocation, Up: Memory
  2494. 3.3 Resizing the Data Segment
  2495. =============================
  2496. The symbols in this section are declared in ‘unistd.h’.
  2497. You will not normally use the functions in this section, because the
  2498. functions described in *note Memory Allocation:: are easier to use.
  2499. Those are interfaces to a GNU C Library memory allocator that uses the
  2500. functions below itself. The functions below are simple interfaces to
  2501. system calls.
  2502. -- Function: int brk (void *ADDR)
  2503. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2504. Concepts::.
  2505. ‘brk’ sets the high end of the calling process’ data segment to
  2506. ADDR.
  2507. The address of the end of a segment is defined to be the address of
  2508. the last byte in the segment plus 1.
  2509. The function has no effect if ADDR is lower than the low end of the
  2510. data segment. (This is considered success, by the way.)
  2511. The function fails if it would cause the data segment to overlap
  2512. another segment or exceed the process’ data storage limit (*note
  2513. Limits on Resources::).
  2514. The function is named for a common historical case where data
  2515. storage and the stack are in the same segment. Data storage
  2516. allocation grows upward from the bottom of the segment while the
  2517. stack grows downward toward it from the top of the segment and the
  2518. curtain between them is called the "break".
  2519. The return value is zero on success. On failure, the return value
  2520. is ‘-1’ and ‘errno’ is set accordingly. The following ‘errno’
  2521. values are specific to this function:
  2522. ‘ENOMEM’
  2523. The request would cause the data segment to overlap another
  2524. segment or exceed the process’ data storage limit.
  2525. -- Function: void *sbrk (ptrdiff_t DELTA)
  2526. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2527. Concepts::.
  2528. This function is the same as ‘brk’ except that you specify the new
  2529. end of the data segment as an offset DELTA from the current end and
  2530. on success the return value is the address of the resulting end of
  2531. the data segment instead of zero.
  2532. This means you can use ‘sbrk(0)’ to find out what the current end
  2533. of the data segment is.
  2534. 
  2535. File: libc.info, Node: Locking Pages, Prev: Resizing the Data Segment, Up: Memory
  2536. 3.4 Locking Pages
  2537. =================
  2538. You can tell the system to associate a particular virtual memory page
  2539. with a real page frame and keep it that way — i.e., cause the page to be
  2540. paged in if it isn’t already and mark it so it will never be paged out
  2541. and consequently will never cause a page fault. This is called
  2542. "locking" a page.
  2543. The functions in this chapter lock and unlock the calling process’
  2544. pages.
  2545. * Menu:
  2546. * Why Lock Pages:: Reasons to read this section.
  2547. * Locked Memory Details:: Everything you need to know locked
  2548. memory
  2549. * Page Lock Functions:: Here’s how to do it.
  2550. 
  2551. File: libc.info, Node: Why Lock Pages, Next: Locked Memory Details, Up: Locking Pages
  2552. 3.4.1 Why Lock Pages
  2553. --------------------
  2554. Because page faults cause paged out pages to be paged in transparently,
  2555. a process rarely needs to be concerned about locking pages. However,
  2556. there are two reasons people sometimes are:
  2557. • Speed. A page fault is transparent only insofar as the process is
  2558. not sensitive to how long it takes to do a simple memory access.
  2559. Time-critical processes, especially realtime processes, may not be
  2560. able to wait or may not be able to tolerate variance in execution
  2561. speed.
  2562. A process that needs to lock pages for this reason probably also
  2563. needs priority among other processes for use of the CPU. *Note
  2564. Priority::.
  2565. In some cases, the programmer knows better than the system’s demand
  2566. paging allocator which pages should remain in real memory to
  2567. optimize system performance. In this case, locking pages can help.
  2568. • Privacy. If you keep secrets in virtual memory and that virtual
  2569. memory gets paged out, that increases the chance that the secrets
  2570. will get out. If a password gets written out to disk swap space,
  2571. for example, it might still be there long after virtual and real
  2572. memory have been wiped clean.
  2573. Be aware that when you lock a page, that’s one fewer page frame that
  2574. can be used to back other virtual memory (by the same or other
  2575. processes), which can mean more page faults, which means the system runs
  2576. more slowly. In fact, if you lock enough memory, some programs may not
  2577. be able to run at all for lack of real memory.
  2578. 
  2579. File: libc.info, Node: Locked Memory Details, Next: Page Lock Functions, Prev: Why Lock Pages, Up: Locking Pages
  2580. 3.4.2 Locked Memory Details
  2581. ---------------------------
  2582. A memory lock is associated with a virtual page, not a real frame. The
  2583. paging rule is: If a frame backs at least one locked page, don’t page it
  2584. out.
  2585. Memory locks do not stack. I.e., you can’t lock a particular page
  2586. twice so that it has to be unlocked twice before it is truly unlocked.
  2587. It is either locked or it isn’t.
  2588. A memory lock persists until the process that owns the memory
  2589. explicitly unlocks it. (But process termination and exec cause the
  2590. virtual memory to cease to exist, which you might say means it isn’t
  2591. locked any more).
  2592. Memory locks are not inherited by child processes. (But note that on
  2593. a modern Unix system, immediately after a fork, the parent’s and the
  2594. child’s virtual address space are backed by the same real page frames,
  2595. so the child enjoys the parent’s locks). *Note Creating a Process::.
  2596. Because of its ability to impact other processes, only the superuser
  2597. can lock a page. Any process can unlock its own page.
  2598. The system sets limits on the amount of memory a process can have
  2599. locked and the amount of real memory it can have dedicated to it. *Note
  2600. Limits on Resources::.
  2601. In Linux, locked pages aren’t as locked as you might think. Two
  2602. virtual pages that are not shared memory can nonetheless be backed by
  2603. the same real frame. The kernel does this in the name of efficiency
  2604. when it knows both virtual pages contain identical data, and does it
  2605. even if one or both of the virtual pages are locked.
  2606. But when a process modifies one of those pages, the kernel must get
  2607. it a separate frame and fill it with the page’s data. This is known as
  2608. a "copy-on-write page fault". It takes a small amount of time and in a
  2609. pathological case, getting that frame may require I/O.
  2610. To make sure this doesn’t happen to your program, don’t just lock the
  2611. pages. Write to them as well, unless you know you won’t write to them
  2612. ever. And to make sure you have pre-allocated frames for your stack,
  2613. enter a scope that declares a C automatic variable larger than the
  2614. maximum stack size you will need, set it to something, then return from
  2615. its scope.
  2616. 
  2617. File: libc.info, Node: Page Lock Functions, Prev: Locked Memory Details, Up: Locking Pages
  2618. 3.4.3 Functions To Lock And Unlock Pages
  2619. ----------------------------------------
  2620. The symbols in this section are declared in ‘sys/mman.h’. These
  2621. functions are defined by POSIX.1b, but their availability depends on
  2622. your kernel. If your kernel doesn’t allow these functions, they exist
  2623. but always fail. They _are_ available with a Linux kernel.
  2624. *Portability Note:* POSIX.1b requires that when the ‘mlock’ and
  2625. ‘munlock’ functions are available, the file ‘unistd.h’ define the macro
  2626. ‘_POSIX_MEMLOCK_RANGE’ and the file ‘limits.h’ define the macro
  2627. ‘PAGESIZE’ to be the size of a memory page in bytes. It requires that
  2628. when the ‘mlockall’ and ‘munlockall’ functions are available, the
  2629. ‘unistd.h’ file define the macro ‘_POSIX_MEMLOCK’. The GNU C Library
  2630. conforms to this requirement.
  2631. -- Function: int mlock (const void *ADDR, size_t LEN)
  2632. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2633. Concepts::.
  2634. ‘mlock’ locks a range of the calling process’ virtual pages.
  2635. The range of memory starts at address ADDR and is LEN bytes long.
  2636. Actually, since you must lock whole pages, it is the range of pages
  2637. that include any part of the specified range.
  2638. When the function returns successfully, each of those pages is
  2639. backed by (connected to) a real frame (is resident) and is marked
  2640. to stay that way. This means the function may cause page-ins and
  2641. have to wait for them.
  2642. When the function fails, it does not affect the lock status of any
  2643. pages.
  2644. The return value is zero if the function succeeds. Otherwise, it
  2645. is ‘-1’ and ‘errno’ is set accordingly. ‘errno’ values specific to
  2646. this function are:
  2647. ‘ENOMEM’
  2648. • At least some of the specified address range does not
  2649. exist in the calling process’ virtual address space.
  2650. • The locking would cause the process to exceed its locked
  2651. page limit.
  2652. ‘EPERM’
  2653. The calling process is not superuser.
  2654. ‘EINVAL’
  2655. LEN is not positive.
  2656. ‘ENOSYS’
  2657. The kernel does not provide ‘mlock’ capability.
  2658. You can lock _all_ a process’ memory with ‘mlockall’. You unlock
  2659. memory with ‘munlock’ or ‘munlockall’.
  2660. To avoid all page faults in a C program, you have to use
  2661. ‘mlockall’, because some of the memory a program uses is hidden
  2662. from the C code, e.g. the stack and automatic variables, and you
  2663. wouldn’t know what address to tell ‘mlock’.
  2664. -- Function: int munlock (const void *ADDR, size_t LEN)
  2665. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2666. Concepts::.
  2667. ‘munlock’ unlocks a range of the calling process’ virtual pages.
  2668. ‘munlock’ is the inverse of ‘mlock’ and functions completely
  2669. analogously to ‘mlock’, except that there is no ‘EPERM’ failure.
  2670. -- Function: int mlockall (int FLAGS)
  2671. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2672. Concepts::.
  2673. ‘mlockall’ locks all the pages in a process’ virtual memory address
  2674. space, and/or any that are added to it in the future. This
  2675. includes the pages of the code, data and stack segment, as well as
  2676. shared libraries, user space kernel data, shared memory, and memory
  2677. mapped files.
  2678. FLAGS is a string of single bit flags represented by the following
  2679. macros. They tell ‘mlockall’ which of its functions you want. All
  2680. other bits must be zero.
  2681. ‘MCL_CURRENT’
  2682. Lock all pages which currently exist in the calling process’
  2683. virtual address space.
  2684. ‘MCL_FUTURE’
  2685. Set a mode such that any pages added to the process’ virtual
  2686. address space in the future will be locked from birth. This
  2687. mode does not affect future address spaces owned by the same
  2688. process so exec, which replaces a process’ address space,
  2689. wipes out ‘MCL_FUTURE’. *Note Executing a File::.
  2690. When the function returns successfully, and you specified
  2691. ‘MCL_CURRENT’, all of the process’ pages are backed by (connected
  2692. to) real frames (they are resident) and are marked to stay that
  2693. way. This means the function may cause page-ins and have to wait
  2694. for them.
  2695. When the process is in ‘MCL_FUTURE’ mode because it successfully
  2696. executed this function and specified ‘MCL_CURRENT’, any system call
  2697. by the process that requires space be added to its virtual address
  2698. space fails with ‘errno’ = ‘ENOMEM’ if locking the additional space
  2699. would cause the process to exceed its locked page limit. In the
  2700. case that the address space addition that can’t be accommodated is
  2701. stack expansion, the stack expansion fails and the kernel sends a
  2702. ‘SIGSEGV’ signal to the process.
  2703. When the function fails, it does not affect the lock status of any
  2704. pages or the future locking mode.
  2705. The return value is zero if the function succeeds. Otherwise, it
  2706. is ‘-1’ and ‘errno’ is set accordingly. ‘errno’ values specific to
  2707. this function are:
  2708. ‘ENOMEM’
  2709. • At least some of the specified address range does not
  2710. exist in the calling process’ virtual address space.
  2711. • The locking would cause the process to exceed its locked
  2712. page limit.
  2713. ‘EPERM’
  2714. The calling process is not superuser.
  2715. ‘EINVAL’
  2716. Undefined bits in FLAGS are not zero.
  2717. ‘ENOSYS’
  2718. The kernel does not provide ‘mlockall’ capability.
  2719. You can lock just specific pages with ‘mlock’. You unlock pages
  2720. with ‘munlockall’ and ‘munlock’.
  2721. -- Function: int munlockall (void)
  2722. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2723. Concepts::.
  2724. ‘munlockall’ unlocks every page in the calling process’ virtual
  2725. address space and turns off ‘MCL_FUTURE’ future locking mode.
  2726. The return value is zero if the function succeeds. Otherwise, it
  2727. is ‘-1’ and ‘errno’ is set accordingly. The only way this function
  2728. can fail is for generic reasons that all functions and system calls
  2729. can fail, so there are no specific ‘errno’ values.
  2730. 
  2731. File: libc.info, Node: Character Handling, Next: String and Array Utilities, Prev: Memory, Up: Top
  2732. 4 Character Handling
  2733. ********************
  2734. Programs that work with characters and strings often need to classify a
  2735. character—is it alphabetic, is it a digit, is it whitespace, and so
  2736. on—and perform case conversion operations on characters. The functions
  2737. in the header file ‘ctype.h’ are provided for this purpose.
  2738. Since the choice of locale and character set can alter the
  2739. classifications of particular character codes, all of these functions
  2740. are affected by the current locale. (More precisely, they are affected
  2741. by the locale currently selected for character classification—the
  2742. ‘LC_CTYPE’ category; see *note Locale Categories::.)
  2743. The ISO C standard specifies two different sets of functions. The
  2744. one set works on ‘char’ type characters, the other one on ‘wchar_t’ wide
  2745. characters (*note Extended Char Intro::).
  2746. * Menu:
  2747. * Classification of Characters:: Testing whether characters are
  2748. letters, digits, punctuation, etc.
  2749. * Case Conversion:: Case mapping, and the like.
  2750. * Classification of Wide Characters:: Character class determination for
  2751. wide characters.
  2752. * Using Wide Char Classes:: Notes on using the wide character
  2753. classes.
  2754. * Wide Character Case Conversion:: Mapping of wide characters.
  2755. 
  2756. File: libc.info, Node: Classification of Characters, Next: Case Conversion, Up: Character Handling
  2757. 4.1 Classification of Characters
  2758. ================================
  2759. This section explains the library functions for classifying characters.
  2760. For example, ‘isalpha’ is the function to test for an alphabetic
  2761. character. It takes one argument, the character to test, and returns a
  2762. nonzero integer if the character is alphabetic, and zero otherwise. You
  2763. would use it like this:
  2764. if (isalpha (c))
  2765. printf ("The character `%c' is alphabetic.\n", c);
  2766. Each of the functions in this section tests for membership in a
  2767. particular class of characters; each has a name starting with ‘is’.
  2768. Each of them takes one argument, which is a character to test, and
  2769. returns an ‘int’ which is treated as a boolean value. The character
  2770. argument is passed as an ‘int’, and it may be the constant value ‘EOF’
  2771. instead of a real character.
  2772. The attributes of any given character can vary between locales.
  2773. *Note Locales::, for more information on locales.
  2774. These functions are declared in the header file ‘ctype.h’.
  2775. -- Function: int islower (int C)
  2776. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2777. Concepts::.
  2778. Returns true if C is a lower-case letter. The letter need not be
  2779. from the Latin alphabet, any alphabet representable is valid.
  2780. -- Function: int isupper (int C)
  2781. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2782. Concepts::.
  2783. Returns true if C is an upper-case letter. The letter need not be
  2784. from the Latin alphabet, any alphabet representable is valid.
  2785. -- Function: int isalpha (int C)
  2786. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2787. Concepts::.
  2788. Returns true if C is an alphabetic character (a letter). If
  2789. ‘islower’ or ‘isupper’ is true of a character, then ‘isalpha’ is
  2790. also true.
  2791. In some locales, there may be additional characters for which
  2792. ‘isalpha’ is true—letters which are neither upper case nor lower
  2793. case. But in the standard ‘"C"’ locale, there are no such
  2794. additional characters.
  2795. -- Function: int isdigit (int C)
  2796. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2797. Concepts::.
  2798. Returns true if C is a decimal digit (‘0’ through ‘9’).
  2799. -- Function: int isalnum (int C)
  2800. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2801. Concepts::.
  2802. Returns true if C is an alphanumeric character (a letter or
  2803. number); in other words, if either ‘isalpha’ or ‘isdigit’ is true
  2804. of a character, then ‘isalnum’ is also true.
  2805. -- Function: int isxdigit (int C)
  2806. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2807. Concepts::.
  2808. Returns true if C is a hexadecimal digit. Hexadecimal digits
  2809. include the normal decimal digits ‘0’ through ‘9’ and the letters
  2810. ‘A’ through ‘F’ and ‘a’ through ‘f’.
  2811. -- Function: int ispunct (int C)
  2812. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2813. Concepts::.
  2814. Returns true if C is a punctuation character. This means any
  2815. printing character that is not alphanumeric or a space character.
  2816. -- Function: int isspace (int C)
  2817. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2818. Concepts::.
  2819. Returns true if C is a "whitespace" character. In the standard
  2820. ‘"C"’ locale, ‘isspace’ returns true for only the standard
  2821. whitespace characters:
  2822. ‘' '’
  2823. space
  2824. ‘'\f'’
  2825. formfeed
  2826. ‘'\n'’
  2827. newline
  2828. ‘'\r'’
  2829. carriage return
  2830. ‘'\t'’
  2831. horizontal tab
  2832. ‘'\v'’
  2833. vertical tab
  2834. -- Function: int isblank (int C)
  2835. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2836. Concepts::.
  2837. Returns true if C is a blank character; that is, a space or a tab.
  2838. This function was originally a GNU extension, but was added in
  2839. ISO C99.
  2840. -- Function: int isgraph (int C)
  2841. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2842. Concepts::.
  2843. Returns true if C is a graphic character; that is, a character that
  2844. has a glyph associated with it. The whitespace characters are not
  2845. considered graphic.
  2846. -- Function: int isprint (int C)
  2847. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2848. Concepts::.
  2849. Returns true if C is a printing character. Printing characters
  2850. include all the graphic characters, plus the space (‘ ’) character.
  2851. -- Function: int iscntrl (int C)
  2852. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2853. Concepts::.
  2854. Returns true if C is a control character (that is, a character that
  2855. is not a printing character).
  2856. -- Function: int isascii (int C)
  2857. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2858. Concepts::.
  2859. Returns true if C is a 7-bit ‘unsigned char’ value that fits into
  2860. the US/UK ASCII character set. This function is a BSD extension
  2861. and is also an SVID extension.
  2862. 
  2863. File: libc.info, Node: Case Conversion, Next: Classification of Wide Characters, Prev: Classification of Characters, Up: Character Handling
  2864. 4.2 Case Conversion
  2865. ===================
  2866. This section explains the library functions for performing conversions
  2867. such as case mappings on characters. For example, ‘toupper’ converts
  2868. any character to upper case if possible. If the character can’t be
  2869. converted, ‘toupper’ returns it unchanged.
  2870. These functions take one argument of type ‘int’, which is the
  2871. character to convert, and return the converted character as an ‘int’.
  2872. If the conversion is not applicable to the argument given, the argument
  2873. is returned unchanged.
  2874. *Compatibility Note:* In pre-ISO C dialects, instead of returning the
  2875. argument unchanged, these functions may fail when the argument is not
  2876. suitable for the conversion. Thus for portability, you may need to
  2877. write ‘islower(c) ? toupper(c) : c’ rather than just ‘toupper(c)’.
  2878. These functions are declared in the header file ‘ctype.h’.
  2879. -- Function: int tolower (int C)
  2880. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2881. Concepts::.
  2882. If C is an upper-case letter, ‘tolower’ returns the corresponding
  2883. lower-case letter. If C is not an upper-case letter, C is returned
  2884. unchanged.
  2885. -- Function: int toupper (int C)
  2886. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2887. Concepts::.
  2888. If C is a lower-case letter, ‘toupper’ returns the corresponding
  2889. upper-case letter. Otherwise C is returned unchanged.
  2890. -- Function: int toascii (int C)
  2891. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2892. Concepts::.
  2893. This function converts C to a 7-bit ‘unsigned char’ value that fits
  2894. into the US/UK ASCII character set, by clearing the high-order
  2895. bits. This function is a BSD extension and is also an SVID
  2896. extension.
  2897. -- Function: int _tolower (int C)
  2898. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2899. Concepts::.
  2900. This is identical to ‘tolower’, and is provided for compatibility
  2901. with the SVID. *Note SVID::.
  2902. -- Function: int _toupper (int C)
  2903. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2904. Concepts::.
  2905. This is identical to ‘toupper’, and is provided for compatibility
  2906. with the SVID.
  2907. 
  2908. File: libc.info, Node: Classification of Wide Characters, Next: Using Wide Char Classes, Prev: Case Conversion, Up: Character Handling
  2909. 4.3 Character class determination for wide characters
  2910. =====================================================
  2911. Amendment 1 to ISO C90 defines functions to classify wide characters.
  2912. Although the original ISO C90 standard already defined the type
  2913. ‘wchar_t’, no functions operating on them were defined.
  2914. The general design of the classification functions for wide
  2915. characters is more general. It allows extensions to the set of
  2916. available classifications, beyond those which are always available. The
  2917. POSIX standard specifies how extensions can be made, and this is already
  2918. implemented in the GNU C Library implementation of the ‘localedef’
  2919. program.
  2920. The character class functions are normally implemented with bitsets,
  2921. with a bitset per character. For a given character, the appropriate
  2922. bitset is read from a table and a test is performed as to whether a
  2923. certain bit is set. Which bit is tested for is determined by the class.
  2924. For the wide character classification functions this is made visible.
  2925. There is a type classification type defined, a function to retrieve this
  2926. value for a given class, and a function to test whether a given
  2927. character is in this class, using the classification value. On top of
  2928. this the normal character classification functions as used for ‘char’
  2929. objects can be defined.
  2930. -- Data type: wctype_t
  2931. The ‘wctype_t’ can hold a value which represents a character class.
  2932. The only defined way to generate such a value is by using the
  2933. ‘wctype’ function.
  2934. This type is defined in ‘wctype.h’.
  2935. -- Function: wctype_t wctype (const char *PROPERTY)
  2936. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  2937. Safety Concepts::.
  2938. ‘wctype’ returns a value representing a class of wide characters
  2939. which is identified by the string PROPERTY. Besides some standard
  2940. properties each locale can define its own ones. In case no
  2941. property with the given name is known for the current locale
  2942. selected for the ‘LC_CTYPE’ category, the function returns zero.
  2943. The properties known in every locale are:
  2944. ‘"alnum"’ ‘"alpha"’ ‘"cntrl"’ ‘"digit"’
  2945. ‘"graph"’ ‘"lower"’ ‘"print"’ ‘"punct"’
  2946. ‘"space"’ ‘"upper"’ ‘"xdigit"’
  2947. This function is declared in ‘wctype.h’.
  2948. To test the membership of a character to one of the non-standard
  2949. classes the ISO C standard defines a completely new function.
  2950. -- Function: int iswctype (wint_t WC, wctype_t DESC)
  2951. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2952. Concepts::.
  2953. This function returns a nonzero value if WC is in the character
  2954. class specified by DESC. DESC must previously be returned by a
  2955. successful call to ‘wctype’.
  2956. This function is declared in ‘wctype.h’.
  2957. To make it easier to use the commonly-used classification functions,
  2958. they are defined in the C library. There is no need to use ‘wctype’ if
  2959. the property string is one of the known character classes. In some
  2960. situations it is desirable to construct the property strings, and then
  2961. it is important that ‘wctype’ can also handle the standard classes.
  2962. -- Function: int iswalnum (wint_t WC)
  2963. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  2964. Safety Concepts::.
  2965. This function returns a nonzero value if WC is an alphanumeric
  2966. character (a letter or number); in other words, if either
  2967. ‘iswalpha’ or ‘iswdigit’ is true of a character, then ‘iswalnum’ is
  2968. also true.
  2969. This function can be implemented using
  2970. iswctype (wc, wctype ("alnum"))
  2971. It is declared in ‘wctype.h’.
  2972. -- Function: int iswalpha (wint_t WC)
  2973. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  2974. Safety Concepts::.
  2975. Returns true if WC is an alphabetic character (a letter). If
  2976. ‘iswlower’ or ‘iswupper’ is true of a character, then ‘iswalpha’ is
  2977. also true.
  2978. In some locales, there may be additional characters for which
  2979. ‘iswalpha’ is true—letters which are neither upper case nor lower
  2980. case. But in the standard ‘"C"’ locale, there are no such
  2981. additional characters.
  2982. This function can be implemented using
  2983. iswctype (wc, wctype ("alpha"))
  2984. It is declared in ‘wctype.h’.
  2985. -- Function: int iswcntrl (wint_t WC)
  2986. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  2987. Safety Concepts::.
  2988. Returns true if WC is a control character (that is, a character
  2989. that is not a printing character).
  2990. This function can be implemented using
  2991. iswctype (wc, wctype ("cntrl"))
  2992. It is declared in ‘wctype.h’.
  2993. -- Function: int iswdigit (wint_t WC)
  2994. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  2995. Safety Concepts::.
  2996. Returns true if WC is a digit (e.g., ‘0’ through ‘9’). Please note
  2997. that this function does not only return a nonzero value for
  2998. _decimal_ digits, but for all kinds of digits. A consequence is
  2999. that code like the following will *not* work unconditionally for
  3000. wide characters:
  3001. n = 0;
  3002. while (iswdigit (*wc))
  3003. {
  3004. n *= 10;
  3005. n += *wc++ - L'0';
  3006. }
  3007. This function can be implemented using
  3008. iswctype (wc, wctype ("digit"))
  3009. It is declared in ‘wctype.h’.
  3010. -- Function: int iswgraph (wint_t WC)
  3011. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  3012. Safety Concepts::.
  3013. Returns true if WC is a graphic character; that is, a character
  3014. that has a glyph associated with it. The whitespace characters are
  3015. not considered graphic.
  3016. This function can be implemented using
  3017. iswctype (wc, wctype ("graph"))
  3018. It is declared in ‘wctype.h’.
  3019. -- Function: int iswlower (wint_t WC)
  3020. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  3021. Safety Concepts::.
  3022. Returns true if WC is a lower-case letter. The letter need not be
  3023. from the Latin alphabet, any alphabet representable is valid.
  3024. This function can be implemented using
  3025. iswctype (wc, wctype ("lower"))
  3026. It is declared in ‘wctype.h’.
  3027. -- Function: int iswprint (wint_t WC)
  3028. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  3029. Safety Concepts::.
  3030. Returns true if WC is a printing character. Printing characters
  3031. include all the graphic characters, plus the space (‘ ’) character.
  3032. This function can be implemented using
  3033. iswctype (wc, wctype ("print"))
  3034. It is declared in ‘wctype.h’.
  3035. -- Function: int iswpunct (wint_t WC)
  3036. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  3037. Safety Concepts::.
  3038. Returns true if WC is a punctuation character. This means any
  3039. printing character that is not alphanumeric or a space character.
  3040. This function can be implemented using
  3041. iswctype (wc, wctype ("punct"))
  3042. It is declared in ‘wctype.h’.
  3043. -- Function: int iswspace (wint_t WC)
  3044. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  3045. Safety Concepts::.
  3046. Returns true if WC is a "whitespace" character. In the standard
  3047. ‘"C"’ locale, ‘iswspace’ returns true for only the standard
  3048. whitespace characters:
  3049. ‘L' '’
  3050. space
  3051. ‘L'\f'’
  3052. formfeed
  3053. ‘L'\n'’
  3054. newline
  3055. ‘L'\r'’
  3056. carriage return
  3057. ‘L'\t'’
  3058. horizontal tab
  3059. ‘L'\v'’
  3060. vertical tab
  3061. This function can be implemented using
  3062. iswctype (wc, wctype ("space"))
  3063. It is declared in ‘wctype.h’.
  3064. -- Function: int iswupper (wint_t WC)
  3065. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  3066. Safety Concepts::.
  3067. Returns true if WC is an upper-case letter. The letter need not be
  3068. from the Latin alphabet, any alphabet representable is valid.
  3069. This function can be implemented using
  3070. iswctype (wc, wctype ("upper"))
  3071. It is declared in ‘wctype.h’.
  3072. -- Function: int iswxdigit (wint_t WC)
  3073. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  3074. Safety Concepts::.
  3075. Returns true if WC is a hexadecimal digit. Hexadecimal digits
  3076. include the normal decimal digits ‘0’ through ‘9’ and the letters
  3077. ‘A’ through ‘F’ and ‘a’ through ‘f’.
  3078. This function can be implemented using
  3079. iswctype (wc, wctype ("xdigit"))
  3080. It is declared in ‘wctype.h’.
  3081. The GNU C Library also provides a function which is not defined in
  3082. the ISO C standard but which is available as a version for single byte
  3083. characters as well.
  3084. -- Function: int iswblank (wint_t WC)
  3085. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  3086. Safety Concepts::.
  3087. Returns true if WC is a blank character; that is, a space or a tab.
  3088. This function was originally a GNU extension, but was added in
  3089. ISO C99. It is declared in ‘wchar.h’.
  3090. 
  3091. File: libc.info, Node: Using Wide Char Classes, Next: Wide Character Case Conversion, Prev: Classification of Wide Characters, Up: Character Handling
  3092. 4.4 Notes on using the wide character classes
  3093. =============================================
  3094. The first note is probably not astonishing but still occasionally a
  3095. cause of problems. The ‘iswXXX’ functions can be implemented using
  3096. macros and in fact, the GNU C Library does this. They are still
  3097. available as real functions but when the ‘wctype.h’ header is included
  3098. the macros will be used. This is the same as the ‘char’ type versions
  3099. of these functions.
  3100. The second note covers something new. It can be best illustrated by
  3101. a (real-world) example. The first piece of code is an excerpt from the
  3102. original code. It is truncated a bit but the intention should be clear.
  3103. int
  3104. is_in_class (int c, const char *class)
  3105. {
  3106. if (strcmp (class, "alnum") == 0)
  3107. return isalnum (c);
  3108. if (strcmp (class, "alpha") == 0)
  3109. return isalpha (c);
  3110. if (strcmp (class, "cntrl") == 0)
  3111. return iscntrl (c);
  3112. return 0;
  3113. }
  3114. Now, with the ‘wctype’ and ‘iswctype’ you can avoid the ‘if’
  3115. cascades, but rewriting the code as follows is wrong:
  3116. int
  3117. is_in_class (int c, const char *class)
  3118. {
  3119. wctype_t desc = wctype (class);
  3120. return desc ? iswctype ((wint_t) c, desc) : 0;
  3121. }
  3122. The problem is that it is not guaranteed that the wide character
  3123. representation of a single-byte character can be found using casting.
  3124. In fact, usually this fails miserably. The correct solution to this
  3125. problem is to write the code as follows:
  3126. int
  3127. is_in_class (int c, const char *class)
  3128. {
  3129. wctype_t desc = wctype (class);
  3130. return desc ? iswctype (btowc (c), desc) : 0;
  3131. }
  3132. *Note Converting a Character::, for more information on ‘btowc’.
  3133. Note that this change probably does not improve the performance of the
  3134. program a lot since the ‘wctype’ function still has to make the string
  3135. comparisons. It gets really interesting if the ‘is_in_class’ function
  3136. is called more than once for the same class name. In this case the
  3137. variable DESC could be computed once and reused for all the calls.
  3138. Therefore the above form of the function is probably not the final one.
  3139. 
  3140. File: libc.info, Node: Wide Character Case Conversion, Prev: Using Wide Char Classes, Up: Character Handling
  3141. 4.5 Mapping of wide characters.
  3142. ===============================
  3143. The classification functions are also generalized by the ISO C standard.
  3144. Instead of just allowing the two standard mappings, a locale can contain
  3145. others. Again, the ‘localedef’ program already supports generating such
  3146. locale data files.
  3147. -- Data Type: wctrans_t
  3148. This data type is defined as a scalar type which can hold a value
  3149. representing the locale-dependent character mapping. There is no
  3150. way to construct such a value apart from using the return value of
  3151. the ‘wctrans’ function.
  3152. This type is defined in ‘wctype.h’.
  3153. -- Function: wctrans_t wctrans (const char *PROPERTY)
  3154. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  3155. Safety Concepts::.
  3156. The ‘wctrans’ function has to be used to find out whether a named
  3157. mapping is defined in the current locale selected for the
  3158. ‘LC_CTYPE’ category. If the returned value is non-zero, you can
  3159. use it afterwards in calls to ‘towctrans’. If the return value is
  3160. zero no such mapping is known in the current locale.
  3161. Beside locale-specific mappings there are two mappings which are
  3162. guaranteed to be available in every locale:
  3163. ‘"tolower"’ ‘"toupper"’
  3164. These functions are declared in ‘wctype.h’.
  3165. -- Function: wint_t towctrans (wint_t WC, wctrans_t DESC)
  3166. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3167. Concepts::.
  3168. ‘towctrans’ maps the input character WC according to the rules of
  3169. the mapping for which DESC is a descriptor, and returns the value
  3170. it finds. DESC must be obtained by a successful call to ‘wctrans’.
  3171. This function is declared in ‘wctype.h’.
  3172. For the generally available mappings, the ISO C standard defines
  3173. convenient shortcuts so that it is not necessary to call ‘wctrans’ for
  3174. them.
  3175. -- Function: wint_t towlower (wint_t WC)
  3176. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  3177. Safety Concepts::.
  3178. If WC is an upper-case letter, ‘towlower’ returns the corresponding
  3179. lower-case letter. If WC is not an upper-case letter, WC is
  3180. returned unchanged.
  3181. ‘towlower’ can be implemented using
  3182. towctrans (wc, wctrans ("tolower"))
  3183. This function is declared in ‘wctype.h’.
  3184. -- Function: wint_t towupper (wint_t WC)
  3185. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  3186. Safety Concepts::.
  3187. If WC is a lower-case letter, ‘towupper’ returns the corresponding
  3188. upper-case letter. Otherwise WC is returned unchanged.
  3189. ‘towupper’ can be implemented using
  3190. towctrans (wc, wctrans ("toupper"))
  3191. This function is declared in ‘wctype.h’.
  3192. The same warnings given in the last section for the use of the wide
  3193. character classification functions apply here. It is not possible to
  3194. simply cast a ‘char’ type value to a ‘wint_t’ and use it as an argument
  3195. to ‘towctrans’ calls.
  3196. 
  3197. File: libc.info, Node: String and Array Utilities, Next: Character Set Handling, Prev: Character Handling, Up: Top
  3198. 5 String and Array Utilities
  3199. ****************************
  3200. Operations on strings (null-terminated byte sequences) are an important
  3201. part of many programs. The GNU C Library provides an extensive set of
  3202. string utility functions, including functions for copying,
  3203. concatenating, comparing, and searching strings. Many of these
  3204. functions can also operate on arbitrary regions of storage; for example,
  3205. the ‘memcpy’ function can be used to copy the contents of any kind of
  3206. array.
  3207. It’s fairly common for beginning C programmers to “reinvent the
  3208. wheel” by duplicating this functionality in their own code, but it pays
  3209. to become familiar with the library functions and to make use of them,
  3210. since this offers benefits in maintenance, efficiency, and portability.
  3211. For instance, you could easily compare one string to another in two
  3212. lines of C code, but if you use the built-in ‘strcmp’ function, you’re
  3213. less likely to make a mistake. And, since these library functions are
  3214. typically highly optimized, your program may run faster too.
  3215. * Menu:
  3216. * Representation of Strings:: Introduction to basic concepts.
  3217. * String/Array Conventions:: Whether to use a string function or an
  3218. arbitrary array function.
  3219. * String Length:: Determining the length of a string.
  3220. * Copying Strings and Arrays:: Functions to copy strings and arrays.
  3221. * Concatenating Strings:: Functions to concatenate strings while copying.
  3222. * Truncating Strings:: Functions to truncate strings while copying.
  3223. * String/Array Comparison:: Functions for byte-wise and character-wise
  3224. comparison.
  3225. * Collation Functions:: Functions for collating strings.
  3226. * Search Functions:: Searching for a specific element or substring.
  3227. * Finding Tokens in a String:: Splitting a string into tokens by looking
  3228. for delimiters.
  3229. * Erasing Sensitive Data:: Clearing memory which contains sensitive
  3230. data, after it’s no longer needed.
  3231. * strfry:: Function for flash-cooking a string.
  3232. * Trivial Encryption:: Obscuring data.
  3233. * Encode Binary Data:: Encoding and Decoding of Binary Data.
  3234. * Argz and Envz Vectors:: Null-separated string vectors.
  3235. 
  3236. File: libc.info, Node: Representation of Strings, Next: String/Array Conventions, Up: String and Array Utilities
  3237. 5.1 Representation of Strings
  3238. =============================
  3239. This section is a quick summary of string concepts for beginning C
  3240. programmers. It describes how strings are represented in C and some
  3241. common pitfalls. If you are already familiar with this material, you
  3242. can skip this section.
  3243. A "string" is a null-terminated array of bytes of type ‘char’,
  3244. including the terminating null byte. String-valued variables are
  3245. usually declared to be pointers of type ‘char *’. Such variables do not
  3246. include space for the text of a string; that has to be stored somewhere
  3247. else—in an array variable, a string constant, or dynamically allocated
  3248. memory (*note Memory Allocation::). It’s up to you to store the address
  3249. of the chosen memory space into the pointer variable. Alternatively you
  3250. can store a "null pointer" in the pointer variable. The null pointer
  3251. does not point anywhere, so attempting to reference the string it points
  3252. to gets an error.
  3253. A "multibyte character" is a sequence of one or more bytes that
  3254. represents a single character using the locale’s encoding scheme; a null
  3255. byte always represents the null character. A "multibyte string" is a
  3256. string that consists entirely of multibyte characters. In contrast, a
  3257. "wide string" is a null-terminated sequence of ‘wchar_t’ objects. A
  3258. wide-string variable is usually declared to be a pointer of type
  3259. ‘wchar_t *’, by analogy with string variables and ‘char *’. *Note
  3260. Extended Char Intro::.
  3261. By convention, the "null byte", ‘'\0'’, marks the end of a string and
  3262. the "null wide character", ‘L'\0'’, marks the end of a wide string. For
  3263. example, in testing to see whether the ‘char *’ variable P points to a
  3264. null byte marking the end of a string, you can write ‘!*P’ or ‘*P ==
  3265. '\0'’.
  3266. A null byte is quite different conceptually from a null pointer,
  3267. although both are represented by the integer constant ‘0’.
  3268. A "string literal" appears in C program source as a multibyte string
  3269. between double-quote characters (‘"’). If the initial double-quote
  3270. character is immediately preceded by a capital ‘L’ (ell) character (as
  3271. in ‘L"foo"’), it is a wide string literal. String literals can also
  3272. contribute to "string concatenation": ‘"a" "b"’ is the same as ‘"ab"’.
  3273. For wide strings one can use either ‘L"a" L"b"’ or ‘L"a" "b"’.
  3274. Modification of string literals is not allowed by the GNU C compiler,
  3275. because literals are placed in read-only storage.
  3276. Arrays that are declared ‘const’ cannot be modified either. It’s
  3277. generally good style to declare non-modifiable string pointers to be of
  3278. type ‘const char *’, since this often allows the C compiler to detect
  3279. accidental modifications as well as providing some amount of
  3280. documentation about what your program intends to do with the string.
  3281. The amount of memory allocated for a byte array may extend past the
  3282. null byte that marks the end of the string that the array contains. In
  3283. this document, the term "allocated size" is always used to refer to the
  3284. total amount of memory allocated for an array, while the term "length"
  3285. refers to the number of bytes up to (but not including) the terminating
  3286. null byte. Wide strings are similar, except their sizes and lengths
  3287. count wide characters, not bytes.
  3288. A notorious source of program bugs is trying to put more bytes into a
  3289. string than fit in its allocated size. When writing code that extends
  3290. strings or moves bytes into a pre-allocated array, you should be very
  3291. careful to keep track of the length of the text and make explicit checks
  3292. for overflowing the array. Many of the library functions _do not_ do
  3293. this for you! Remember also that you need to allocate an extra byte to
  3294. hold the null byte that marks the end of the string.
  3295. Originally strings were sequences of bytes where each byte
  3296. represented a single character. This is still true today if the strings
  3297. are encoded using a single-byte character encoding. Things are
  3298. different if the strings are encoded using a multibyte encoding (for
  3299. more information on encodings see *note Extended Char Intro::). There
  3300. is no difference in the programming interface for these two kind of
  3301. strings; the programmer has to be aware of this and interpret the byte
  3302. sequences accordingly.
  3303. But since there is no separate interface taking care of these
  3304. differences the byte-based string functions are sometimes hard to use.
  3305. Since the count parameters of these functions specify bytes a call to
  3306. ‘memcpy’ could cut a multibyte character in the middle and put an
  3307. incomplete (and therefore unusable) byte sequence in the target buffer.
  3308. To avoid these problems later versions of the ISO C standard
  3309. introduce a second set of functions which are operating on "wide
  3310. characters" (*note Extended Char Intro::). These functions don’t have
  3311. the problems the single-byte versions have since every wide character is
  3312. a legal, interpretable value. This does not mean that cutting wide
  3313. strings at arbitrary points is without problems. It normally is for
  3314. alphabet-based languages (except for non-normalized text) but languages
  3315. based on syllables still have the problem that more than one wide
  3316. character is necessary to complete a logical unit. This is a higher
  3317. level problem which the C library functions are not designed to solve.
  3318. But it is at least good that no invalid byte sequences can be created.
  3319. Also, the higher level functions can also much more easily operate on
  3320. wide characters than on multibyte characters so that a common strategy
  3321. is to use wide characters internally whenever text is more than simply
  3322. copied.
  3323. The remaining of this chapter will discuss the functions for handling
  3324. wide strings in parallel with the discussion of strings since there is
  3325. almost always an exact equivalent available.
  3326. 
  3327. File: libc.info, Node: String/Array Conventions, Next: String Length, Prev: Representation of Strings, Up: String and Array Utilities
  3328. 5.2 String and Array Conventions
  3329. ================================
  3330. This chapter describes both functions that work on arbitrary arrays or
  3331. blocks of memory, and functions that are specific to strings and wide
  3332. strings.
  3333. Functions that operate on arbitrary blocks of memory have names
  3334. beginning with ‘mem’ and ‘wmem’ (such as ‘memcpy’ and ‘wmemcpy’) and
  3335. invariably take an argument which specifies the size (in bytes and wide
  3336. characters respectively) of the block of memory to operate on. The
  3337. array arguments and return values for these functions have type ‘void *’
  3338. or ‘wchar_t’. As a matter of style, the elements of the arrays used
  3339. with the ‘mem’ functions are referred to as “bytes”. You can pass any
  3340. kind of pointer to these functions, and the ‘sizeof’ operator is useful
  3341. in computing the value for the size argument. Parameters to the ‘wmem’
  3342. functions must be of type ‘wchar_t *’. These functions are not really
  3343. usable with anything but arrays of this type.
  3344. In contrast, functions that operate specifically on strings and wide
  3345. strings have names beginning with ‘str’ and ‘wcs’ respectively (such as
  3346. ‘strcpy’ and ‘wcscpy’) and look for a terminating null byte or null wide
  3347. character instead of requiring an explicit size argument to be passed.
  3348. (Some of these functions accept a specified maximum length, but they
  3349. also check for premature termination.) The array arguments and return
  3350. values for these functions have type ‘char *’ and ‘wchar_t *’
  3351. respectively, and the array elements are referred to as “bytes” and
  3352. “wide characters”.
  3353. In many cases, there are both ‘mem’ and ‘str’/‘wcs’ versions of a
  3354. function. The one that is more appropriate to use depends on the exact
  3355. situation. When your program is manipulating arbitrary arrays or blocks
  3356. of storage, then you should always use the ‘mem’ functions. On the
  3357. other hand, when you are manipulating strings it is usually more
  3358. convenient to use the ‘str’/‘wcs’ functions, unless you already know the
  3359. length of the string in advance. The ‘wmem’ functions should be used
  3360. for wide character arrays with known size.
  3361. Some of the memory and string functions take single characters as
  3362. arguments. Since a value of type ‘char’ is automatically promoted into
  3363. a value of type ‘int’ when used as a parameter, the functions are
  3364. declared with ‘int’ as the type of the parameter in question. In case
  3365. of the wide character functions the situation is similar: the parameter
  3366. type for a single wide character is ‘wint_t’ and not ‘wchar_t’. This
  3367. would for many implementations not be necessary since ‘wchar_t’ is large
  3368. enough to not be automatically promoted, but since the ISO C standard
  3369. does not require such a choice of types the ‘wint_t’ type is used.
  3370. 
  3371. File: libc.info, Node: String Length, Next: Copying Strings and Arrays, Prev: String/Array Conventions, Up: String and Array Utilities
  3372. 5.3 String Length
  3373. =================
  3374. You can get the length of a string using the ‘strlen’ function. This
  3375. function is declared in the header file ‘string.h’.
  3376. -- Function: size_t strlen (const char *S)
  3377. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3378. Concepts::.
  3379. The ‘strlen’ function returns the length of the string S in bytes.
  3380. (In other words, it returns the offset of the terminating null byte
  3381. within the array.)
  3382. For example,
  3383. strlen ("hello, world")
  3384. ⇒ 12
  3385. When applied to an array, the ‘strlen’ function returns the length
  3386. of the string stored there, not its allocated size. You can get
  3387. the allocated size of the array that holds a string using the
  3388. ‘sizeof’ operator:
  3389. char string[32] = "hello, world";
  3390. sizeof (string)
  3391. ⇒ 32
  3392. strlen (string)
  3393. ⇒ 12
  3394. But beware, this will not work unless STRING is the array itself,
  3395. not a pointer to it. For example:
  3396. char string[32] = "hello, world";
  3397. char *ptr = string;
  3398. sizeof (string)
  3399. ⇒ 32
  3400. sizeof (ptr)
  3401. ⇒ 4 /* (on a machine with 4 byte pointers) */
  3402. This is an easy mistake to make when you are working with functions
  3403. that take string arguments; those arguments are always pointers,
  3404. not arrays.
  3405. It must also be noted that for multibyte encoded strings the return
  3406. value does not have to correspond to the number of characters in
  3407. the string. To get this value the string can be converted to wide
  3408. characters and ‘wcslen’ can be used or something like the following
  3409. code can be used:
  3410. /* The input is in ‘string’.
  3411. The length is expected in ‘n’. */
  3412. {
  3413. mbstate_t t;
  3414. char *scopy = string;
  3415. /* In initial state. */
  3416. memset (&t, '\0', sizeof (t));
  3417. /* Determine number of characters. */
  3418. n = mbsrtowcs (NULL, &scopy, strlen (scopy), &t);
  3419. }
  3420. This is cumbersome to do so if the number of characters (as opposed
  3421. to bytes) is needed often it is better to work with wide
  3422. characters.
  3423. The wide character equivalent is declared in ‘wchar.h’.
  3424. -- Function: size_t wcslen (const wchar_t *WS)
  3425. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3426. Concepts::.
  3427. The ‘wcslen’ function is the wide character equivalent to ‘strlen’.
  3428. The return value is the number of wide characters in the wide
  3429. string pointed to by WS (this is also the offset of the terminating
  3430. null wide character of WS).
  3431. Since there are no multi wide character sequences making up one
  3432. wide character the return value is not only the offset in the
  3433. array, it is also the number of wide characters.
  3434. This function was introduced in Amendment 1 to ISO C90.
  3435. -- Function: size_t strnlen (const char *S, size_t MAXLEN)
  3436. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3437. Concepts::.
  3438. If the array S of size MAXLEN contains a null byte, the ‘strnlen’
  3439. function returns the length of the string S in bytes. Otherwise it
  3440. returns MAXLEN. Therefore this function is equivalent to ‘(strlen
  3441. (S) < MAXLEN ? strlen (S) : MAXLEN)’ but it is more efficient and
  3442. works even if S is not null-terminated so long as MAXLEN does not
  3443. exceed the size of S’s array.
  3444. char string[32] = "hello, world";
  3445. strnlen (string, 32)
  3446. ⇒ 12
  3447. strnlen (string, 5)
  3448. ⇒ 5
  3449. This function is a GNU extension and is declared in ‘string.h’.
  3450. -- Function: size_t wcsnlen (const wchar_t *WS, size_t MAXLEN)
  3451. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3452. Concepts::.
  3453. ‘wcsnlen’ is the wide character equivalent to ‘strnlen’. The
  3454. MAXLEN parameter specifies the maximum number of wide characters.
  3455. This function is a GNU extension and is declared in ‘wchar.h’.
  3456. 
  3457. File: libc.info, Node: Copying Strings and Arrays, Next: Concatenating Strings, Prev: String Length, Up: String and Array Utilities
  3458. 5.4 Copying Strings and Arrays
  3459. ==============================
  3460. You can use the functions described in this section to copy the contents
  3461. of strings, wide strings, and arrays. The ‘str’ and ‘mem’ functions are
  3462. declared in ‘string.h’ while the ‘w’ functions are declared in
  3463. ‘wchar.h’.
  3464. A helpful way to remember the ordering of the arguments to the
  3465. functions in this section is that it corresponds to an assignment
  3466. expression, with the destination array specified to the left of the
  3467. source array. Most of these functions return the address of the
  3468. destination array; a few return the address of the destination’s
  3469. terminating null, or of just past the destination.
  3470. Most of these functions do not work properly if the source and
  3471. destination arrays overlap. For example, if the beginning of the
  3472. destination array overlaps the end of the source array, the original
  3473. contents of that part of the source array may get overwritten before it
  3474. is copied. Even worse, in the case of the string functions, the null
  3475. byte marking the end of the string may be lost, and the copy function
  3476. might get stuck in a loop trashing all the memory allocated to your
  3477. program.
  3478. All functions that have problems copying between overlapping arrays
  3479. are explicitly identified in this manual. In addition to functions in
  3480. this section, there are a few others like ‘sprintf’ (*note Formatted
  3481. Output Functions::) and ‘scanf’ (*note Formatted Input Functions::).
  3482. -- Function: void * memcpy (void *restrict TO, const void *restrict
  3483. FROM, size_t SIZE)
  3484. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3485. Concepts::.
  3486. The ‘memcpy’ function copies SIZE bytes from the object beginning
  3487. at FROM into the object beginning at TO. The behavior of this
  3488. function is undefined if the two arrays TO and FROM overlap; use
  3489. ‘memmove’ instead if overlapping is possible.
  3490. The value returned by ‘memcpy’ is the value of TO.
  3491. Here is an example of how you might use ‘memcpy’ to copy the
  3492. contents of an array:
  3493. struct foo *oldarray, *newarray;
  3494. int arraysize;
  3495. memcpy (new, old, arraysize * sizeof (struct foo));
  3496. -- Function: wchar_t * wmemcpy (wchar_t *restrict WTO, const wchar_t
  3497. *restrict WFROM, size_t SIZE)
  3498. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3499. Concepts::.
  3500. The ‘wmemcpy’ function copies SIZE wide characters from the object
  3501. beginning at WFROM into the object beginning at WTO. The behavior
  3502. of this function is undefined if the two arrays WTO and WFROM
  3503. overlap; use ‘wmemmove’ instead if overlapping is possible.
  3504. The following is a possible implementation of ‘wmemcpy’ but there
  3505. are more optimizations possible.
  3506. wchar_t *
  3507. wmemcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom,
  3508. size_t size)
  3509. {
  3510. return (wchar_t *) memcpy (wto, wfrom, size * sizeof (wchar_t));
  3511. }
  3512. The value returned by ‘wmemcpy’ is the value of WTO.
  3513. This function was introduced in Amendment 1 to ISO C90.
  3514. -- Function: void * mempcpy (void *restrict TO, const void *restrict
  3515. FROM, size_t SIZE)
  3516. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3517. Concepts::.
  3518. The ‘mempcpy’ function is nearly identical to the ‘memcpy’
  3519. function. It copies SIZE bytes from the object beginning at ‘from’
  3520. into the object pointed to by TO. But instead of returning the
  3521. value of TO it returns a pointer to the byte following the last
  3522. written byte in the object beginning at TO. I.e., the value is
  3523. ‘((void *) ((char *) TO + SIZE))’.
  3524. This function is useful in situations where a number of objects
  3525. shall be copied to consecutive memory positions.
  3526. void *
  3527. combine (void *o1, size_t s1, void *o2, size_t s2)
  3528. {
  3529. void *result = malloc (s1 + s2);
  3530. if (result != NULL)
  3531. mempcpy (mempcpy (result, o1, s1), o2, s2);
  3532. return result;
  3533. }
  3534. This function is a GNU extension.
  3535. -- Function: wchar_t * wmempcpy (wchar_t *restrict WTO, const wchar_t
  3536. *restrict WFROM, size_t SIZE)
  3537. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3538. Concepts::.
  3539. The ‘wmempcpy’ function is nearly identical to the ‘wmemcpy’
  3540. function. It copies SIZE wide characters from the object beginning
  3541. at ‘wfrom’ into the object pointed to by WTO. But instead of
  3542. returning the value of WTO it returns a pointer to the wide
  3543. character following the last written wide character in the object
  3544. beginning at WTO. I.e., the value is ‘WTO + SIZE’.
  3545. This function is useful in situations where a number of objects
  3546. shall be copied to consecutive memory positions.
  3547. The following is a possible implementation of ‘wmemcpy’ but there
  3548. are more optimizations possible.
  3549. wchar_t *
  3550. wmempcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom,
  3551. size_t size)
  3552. {
  3553. return (wchar_t *) mempcpy (wto, wfrom, size * sizeof (wchar_t));
  3554. }
  3555. This function is a GNU extension.
  3556. -- Function: void * memmove (void *TO, const void *FROM, size_t SIZE)
  3557. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3558. Concepts::.
  3559. ‘memmove’ copies the SIZE bytes at FROM into the SIZE bytes at TO,
  3560. even if those two blocks of space overlap. In the case of overlap,
  3561. ‘memmove’ is careful to copy the original values of the bytes in
  3562. the block at FROM, including those bytes which also belong to the
  3563. block at TO.
  3564. The value returned by ‘memmove’ is the value of TO.
  3565. -- Function: wchar_t * wmemmove (wchar_t *WTO, const wchar_t *WFROM,
  3566. size_t SIZE)
  3567. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3568. Concepts::.
  3569. ‘wmemmove’ copies the SIZE wide characters at WFROM into the SIZE
  3570. wide characters at WTO, even if those two blocks of space overlap.
  3571. In the case of overlap, ‘wmemmove’ is careful to copy the original
  3572. values of the wide characters in the block at WFROM, including
  3573. those wide characters which also belong to the block at WTO.
  3574. The following is a possible implementation of ‘wmemcpy’ but there
  3575. are more optimizations possible.
  3576. wchar_t *
  3577. wmempcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom,
  3578. size_t size)
  3579. {
  3580. return (wchar_t *) mempcpy (wto, wfrom, size * sizeof (wchar_t));
  3581. }
  3582. The value returned by ‘wmemmove’ is the value of WTO.
  3583. This function is a GNU extension.
  3584. -- Function: void * memccpy (void *restrict TO, const void *restrict
  3585. FROM, int C, size_t SIZE)
  3586. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3587. Concepts::.
  3588. This function copies no more than SIZE bytes from FROM to TO,
  3589. stopping if a byte matching C is found. The return value is a
  3590. pointer into TO one byte past where C was copied, or a null pointer
  3591. if no byte matching C appeared in the first SIZE bytes of FROM.
  3592. -- Function: void * memset (void *BLOCK, int C, size_t SIZE)
  3593. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3594. Concepts::.
  3595. This function copies the value of C (converted to an ‘unsigned
  3596. char’) into each of the first SIZE bytes of the object beginning at
  3597. BLOCK. It returns the value of BLOCK.
  3598. -- Function: wchar_t * wmemset (wchar_t *BLOCK, wchar_t WC, size_t
  3599. SIZE)
  3600. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3601. Concepts::.
  3602. This function copies the value of WC into each of the first SIZE
  3603. wide characters of the object beginning at BLOCK. It returns the
  3604. value of BLOCK.
  3605. -- Function: char * strcpy (char *restrict TO, const char *restrict
  3606. FROM)
  3607. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3608. Concepts::.
  3609. This copies bytes from the string FROM (up to and including the
  3610. terminating null byte) into the string TO. Like ‘memcpy’, this
  3611. function has undefined results if the strings overlap. The return
  3612. value is the value of TO.
  3613. -- Function: wchar_t * wcscpy (wchar_t *restrict WTO, const wchar_t
  3614. *restrict WFROM)
  3615. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3616. Concepts::.
  3617. This copies wide characters from the wide string WFROM (up to and
  3618. including the terminating null wide character) into the string WTO.
  3619. Like ‘wmemcpy’, this function has undefined results if the strings
  3620. overlap. The return value is the value of WTO.
  3621. -- Function: char * strdup (const char *S)
  3622. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  3623. POSIX Safety Concepts::.
  3624. This function copies the string S into a newly allocated string.
  3625. The string is allocated using ‘malloc’; see *note Unconstrained
  3626. Allocation::. If ‘malloc’ cannot allocate space for the new
  3627. string, ‘strdup’ returns a null pointer. Otherwise it returns a
  3628. pointer to the new string.
  3629. -- Function: wchar_t * wcsdup (const wchar_t *WS)
  3630. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  3631. POSIX Safety Concepts::.
  3632. This function copies the wide string WS into a newly allocated
  3633. string. The string is allocated using ‘malloc’; see *note
  3634. Unconstrained Allocation::. If ‘malloc’ cannot allocate space for
  3635. the new string, ‘wcsdup’ returns a null pointer. Otherwise it
  3636. returns a pointer to the new wide string.
  3637. This function is a GNU extension.
  3638. -- Function: char * stpcpy (char *restrict TO, const char *restrict
  3639. FROM)
  3640. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3641. Concepts::.
  3642. This function is like ‘strcpy’, except that it returns a pointer to
  3643. the end of the string TO (that is, the address of the terminating
  3644. null byte ‘to + strlen (from)’) rather than the beginning.
  3645. For example, this program uses ‘stpcpy’ to concatenate ‘foo’ and
  3646. ‘bar’ to produce ‘foobar’, which it then prints.
  3647. #include <string.h>
  3648. #include <stdio.h>
  3649. int
  3650. main (void)
  3651. {
  3652. char buffer[10];
  3653. char *to = buffer;
  3654. to = stpcpy (to, "foo");
  3655. to = stpcpy (to, "bar");
  3656. puts (buffer);
  3657. return 0;
  3658. }
  3659. This function is part of POSIX.1-2008 and later editions, but was
  3660. available in the GNU C Library and other systems as an extension
  3661. long before it was standardized.
  3662. Its behavior is undefined if the strings overlap. The function is
  3663. declared in ‘string.h’.
  3664. -- Function: wchar_t * wcpcpy (wchar_t *restrict WTO, const wchar_t
  3665. *restrict WFROM)
  3666. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3667. Concepts::.
  3668. This function is like ‘wcscpy’, except that it returns a pointer to
  3669. the end of the string WTO (that is, the address of the terminating
  3670. null wide character ‘wto + wcslen (wfrom)’) rather than the
  3671. beginning.
  3672. This function is not part of ISO or POSIX but was found useful
  3673. while developing the GNU C Library itself.
  3674. The behavior of ‘wcpcpy’ is undefined if the strings overlap.
  3675. ‘wcpcpy’ is a GNU extension and is declared in ‘wchar.h’.
  3676. -- Macro: char * strdupa (const char *S)
  3677. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3678. Concepts::.
  3679. This macro is similar to ‘strdup’ but allocates the new string
  3680. using ‘alloca’ instead of ‘malloc’ (*note Variable Size
  3681. Automatic::). This means of course the returned string has the
  3682. same limitations as any block of memory allocated using ‘alloca’.
  3683. For obvious reasons ‘strdupa’ is implemented only as a macro; you
  3684. cannot get the address of this function. Despite this limitation
  3685. it is a useful function. The following code shows a situation
  3686. where using ‘malloc’ would be a lot more expensive.
  3687. #include <paths.h>
  3688. #include <string.h>
  3689. #include <stdio.h>
  3690. const char path[] = _PATH_STDPATH;
  3691. int
  3692. main (void)
  3693. {
  3694. char *wr_path = strdupa (path);
  3695. char *cp = strtok (wr_path, ":");
  3696. while (cp != NULL)
  3697. {
  3698. puts (cp);
  3699. cp = strtok (NULL, ":");
  3700. }
  3701. return 0;
  3702. }
  3703. Please note that calling ‘strtok’ using PATH directly is invalid.
  3704. It is also not allowed to call ‘strdupa’ in the argument list of
  3705. ‘strtok’ since ‘strdupa’ uses ‘alloca’ (*note Variable Size
  3706. Automatic::) can interfere with the parameter passing.
  3707. This function is only available if GNU CC is used.
  3708. -- Function: void bcopy (const void *FROM, void *TO, size_t SIZE)
  3709. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3710. Concepts::.
  3711. This is a partially obsolete alternative for ‘memmove’, derived
  3712. from BSD. Note that it is not quite equivalent to ‘memmove’,
  3713. because the arguments are not in the same order and there is no
  3714. return value.
  3715. -- Function: void bzero (void *BLOCK, size_t SIZE)
  3716. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3717. Concepts::.
  3718. This is a partially obsolete alternative for ‘memset’, derived from
  3719. BSD. Note that it is not as general as ‘memset’, because the only
  3720. value it can store is zero.
  3721. 
  3722. File: libc.info, Node: Concatenating Strings, Next: Truncating Strings, Prev: Copying Strings and Arrays, Up: String and Array Utilities
  3723. 5.5 Concatenating Strings
  3724. =========================
  3725. The functions described in this section concatenate the contents of a
  3726. string or wide string to another. They follow the string-copying
  3727. functions in their conventions. *Note Copying Strings and Arrays::.
  3728. ‘strcat’ is declared in the header file ‘string.h’ while ‘wcscat’ is
  3729. declared in ‘wchar.h’.
  3730. -- Function: char * strcat (char *restrict TO, const char *restrict
  3731. FROM)
  3732. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3733. Concepts::.
  3734. The ‘strcat’ function is similar to ‘strcpy’, except that the bytes
  3735. from FROM are concatenated or appended to the end of TO, instead of
  3736. overwriting it. That is, the first byte from FROM overwrites the
  3737. null byte marking the end of TO.
  3738. An equivalent definition for ‘strcat’ would be:
  3739. char *
  3740. strcat (char *restrict to, const char *restrict from)
  3741. {
  3742. strcpy (to + strlen (to), from);
  3743. return to;
  3744. }
  3745. This function has undefined results if the strings overlap.
  3746. As noted below, this function has significant performance issues.
  3747. -- Function: wchar_t * wcscat (wchar_t *restrict WTO, const wchar_t
  3748. *restrict WFROM)
  3749. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3750. Concepts::.
  3751. The ‘wcscat’ function is similar to ‘wcscpy’, except that the wide
  3752. characters from WFROM are concatenated or appended to the end of
  3753. WTO, instead of overwriting it. That is, the first wide character
  3754. from WFROM overwrites the null wide character marking the end of
  3755. WTO.
  3756. An equivalent definition for ‘wcscat’ would be:
  3757. wchar_t *
  3758. wcscat (wchar_t *wto, const wchar_t *wfrom)
  3759. {
  3760. wcscpy (wto + wcslen (wto), wfrom);
  3761. return wto;
  3762. }
  3763. This function has undefined results if the strings overlap.
  3764. As noted below, this function has significant performance issues.
  3765. Programmers using the ‘strcat’ or ‘wcscat’ function (or the ‘strncat’
  3766. or ‘wcsncat’ functions defined in a later section, for that matter) can
  3767. easily be recognized as lazy and reckless. In almost all situations the
  3768. lengths of the participating strings are known (it better should be
  3769. since how can one otherwise ensure the allocated size of the buffer is
  3770. sufficient?) Or at least, one could know them if one keeps track of the
  3771. results of the various function calls. But then it is very inefficient
  3772. to use ‘strcat’/‘wcscat’. A lot of time is wasted finding the end of
  3773. the destination string so that the actual copying can start. This is a
  3774. common example:
  3775. /* This function concatenates arbitrarily many strings. The last
  3776. parameter must be ‘NULL’. */
  3777. char *
  3778. concat (const char *str, …)
  3779. {
  3780. va_list ap, ap2;
  3781. size_t total = 1;
  3782. const char *s;
  3783. char *result;
  3784. va_start (ap, str);
  3785. va_copy (ap2, ap);
  3786. /* Determine how much space we need. */
  3787. for (s = str; s != NULL; s = va_arg (ap, const char *))
  3788. total += strlen (s);
  3789. va_end (ap);
  3790. result = (char *) malloc (total);
  3791. if (result != NULL)
  3792. {
  3793. result[0] = '\0';
  3794. /* Copy the strings. */
  3795. for (s = str; s != NULL; s = va_arg (ap2, const char *))
  3796. strcat (result, s);
  3797. }
  3798. va_end (ap2);
  3799. return result;
  3800. }
  3801. This looks quite simple, especially the second loop where the strings
  3802. are actually copied. But these innocent lines hide a major performance
  3803. penalty. Just imagine that ten strings of 100 bytes each have to be
  3804. concatenated. For the second string we search the already stored 100
  3805. bytes for the end of the string so that we can append the next string.
  3806. For all strings in total the comparisons necessary to find the end of
  3807. the intermediate results sums up to 5500! If we combine the copying
  3808. with the search for the allocation we can write this function more
  3809. efficiently:
  3810. char *
  3811. concat (const char *str, …)
  3812. {
  3813. va_list ap;
  3814. size_t allocated = 100;
  3815. char *result = (char *) malloc (allocated);
  3816. if (result != NULL)
  3817. {
  3818. char *newp;
  3819. char *wp;
  3820. const char *s;
  3821. va_start (ap, str);
  3822. wp = result;
  3823. for (s = str; s != NULL; s = va_arg (ap, const char *))
  3824. {
  3825. size_t len = strlen (s);
  3826. /* Resize the allocated memory if necessary. */
  3827. if (wp + len + 1 > result + allocated)
  3828. {
  3829. allocated = (allocated + len) * 2;
  3830. newp = (char *) realloc (result, allocated);
  3831. if (newp == NULL)
  3832. {
  3833. free (result);
  3834. return NULL;
  3835. }
  3836. wp = newp + (wp - result);
  3837. result = newp;
  3838. }
  3839. wp = mempcpy (wp, s, len);
  3840. }
  3841. /* Terminate the result string. */
  3842. *wp++ = '\0';
  3843. /* Resize memory to the optimal size. */
  3844. newp = realloc (result, wp - result);
  3845. if (newp != NULL)
  3846. result = newp;
  3847. va_end (ap);
  3848. }
  3849. return result;
  3850. }
  3851. With a bit more knowledge about the input strings one could fine-tune
  3852. the memory allocation. The difference we are pointing to here is that
  3853. we don’t use ‘strcat’ anymore. We always keep track of the length of
  3854. the current intermediate result so we can save ourselves the search for
  3855. the end of the string and use ‘mempcpy’. Please note that we also don’t
  3856. use ‘stpcpy’ which might seem more natural since we are handling
  3857. strings. But this is not necessary since we already know the length of
  3858. the string and therefore can use the faster memory copying function.
  3859. The example would work for wide characters the same way.
  3860. Whenever a programmer feels the need to use ‘strcat’ she or he should
  3861. think twice and look through the program to see whether the code cannot
  3862. be rewritten to take advantage of already calculated results. Again: it
  3863. is almost always unnecessary to use ‘strcat’.
  3864. 
  3865. File: libc.info, Node: Truncating Strings, Next: String/Array Comparison, Prev: Concatenating Strings, Up: String and Array Utilities
  3866. 5.6 Truncating Strings while Copying
  3867. ====================================
  3868. The functions described in this section copy or concatenate the
  3869. possibly-truncated contents of a string or array to another, and
  3870. similarly for wide strings. They follow the string-copying functions in
  3871. their header conventions. *Note Copying Strings and Arrays::. The
  3872. ‘str’ functions are declared in the header file ‘string.h’ and the ‘wc’
  3873. functions are declared in the file ‘wchar.h’.
  3874. -- Function: char * strncpy (char *restrict TO, const char *restrict
  3875. FROM, size_t SIZE)
  3876. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3877. Concepts::.
  3878. This function is similar to ‘strcpy’ but always copies exactly SIZE
  3879. bytes into TO.
  3880. If FROM does not contain a null byte in its first SIZE bytes,
  3881. ‘strncpy’ copies just the first SIZE bytes. In this case no null
  3882. terminator is written into TO.
  3883. Otherwise FROM must be a string with length less than SIZE. In
  3884. this case ‘strncpy’ copies all of FROM, followed by enough null
  3885. bytes to add up to SIZE bytes in all.
  3886. The behavior of ‘strncpy’ is undefined if the strings overlap.
  3887. This function was designed for now-rarely-used arrays consisting of
  3888. non-null bytes followed by zero or more null bytes. It needs to
  3889. set all SIZE bytes of the destination, even when SIZE is much
  3890. greater than the length of FROM. As noted below, this function is
  3891. generally a poor choice for processing text.
  3892. -- Function: wchar_t * wcsncpy (wchar_t *restrict WTO, const wchar_t
  3893. *restrict WFROM, size_t SIZE)
  3894. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3895. Concepts::.
  3896. This function is similar to ‘wcscpy’ but always copies exactly SIZE
  3897. wide characters into WTO.
  3898. If WFROM does not contain a null wide character in its first SIZE
  3899. wide characters, then ‘wcsncpy’ copies just the first SIZE wide
  3900. characters. In this case no null terminator is written into WTO.
  3901. Otherwise WFROM must be a wide string with length less than SIZE.
  3902. In this case ‘wcsncpy’ copies all of WFROM, followed by enough null
  3903. wide characters to add up to SIZE wide characters in all.
  3904. The behavior of ‘wcsncpy’ is undefined if the strings overlap.
  3905. This function is the wide-character counterpart of ‘strncpy’ and
  3906. suffers from most of the problems that ‘strncpy’ does. For
  3907. example, as noted below, this function is generally a poor choice
  3908. for processing text.
  3909. -- Function: char * strndup (const char *S, size_t SIZE)
  3910. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  3911. POSIX Safety Concepts::.
  3912. This function is similar to ‘strdup’ but always copies at most SIZE
  3913. bytes into the newly allocated string.
  3914. If the length of S is more than SIZE, then ‘strndup’ copies just
  3915. the first SIZE bytes and adds a closing null byte. Otherwise all
  3916. bytes are copied and the string is terminated.
  3917. This function differs from ‘strncpy’ in that it always terminates
  3918. the destination string.
  3919. As noted below, this function is generally a poor choice for
  3920. processing text.
  3921. ‘strndup’ is a GNU extension.
  3922. -- Macro: char * strndupa (const char *S, size_t SIZE)
  3923. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3924. Concepts::.
  3925. This function is similar to ‘strndup’ but like ‘strdupa’ it
  3926. allocates the new string using ‘alloca’ *note Variable Size
  3927. Automatic::. The same advantages and limitations of ‘strdupa’ are
  3928. valid for ‘strndupa’, too.
  3929. This function is implemented only as a macro, just like ‘strdupa’.
  3930. Just as ‘strdupa’ this macro also must not be used inside the
  3931. parameter list in a function call.
  3932. As noted below, this function is generally a poor choice for
  3933. processing text.
  3934. ‘strndupa’ is only available if GNU CC is used.
  3935. -- Function: char * stpncpy (char *restrict TO, const char *restrict
  3936. FROM, size_t SIZE)
  3937. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3938. Concepts::.
  3939. This function is similar to ‘stpcpy’ but copies always exactly SIZE
  3940. bytes into TO.
  3941. If the length of FROM is more than SIZE, then ‘stpncpy’ copies just
  3942. the first SIZE bytes and returns a pointer to the byte directly
  3943. following the one which was copied last. Note that in this case
  3944. there is no null terminator written into TO.
  3945. If the length of FROM is less than SIZE, then ‘stpncpy’ copies all
  3946. of FROM, followed by enough null bytes to add up to SIZE bytes in
  3947. all. This behavior is rarely useful, but it is implemented to be
  3948. useful in contexts where this behavior of the ‘strncpy’ is used.
  3949. ‘stpncpy’ returns a pointer to the _first_ written null byte.
  3950. This function is not part of ISO or POSIX but was found useful
  3951. while developing the GNU C Library itself.
  3952. Its behavior is undefined if the strings overlap. The function is
  3953. declared in ‘string.h’.
  3954. As noted below, this function is generally a poor choice for
  3955. processing text.
  3956. -- Function: wchar_t * wcpncpy (wchar_t *restrict WTO, const wchar_t
  3957. *restrict WFROM, size_t SIZE)
  3958. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3959. Concepts::.
  3960. This function is similar to ‘wcpcpy’ but copies always exactly
  3961. WSIZE wide characters into WTO.
  3962. If the length of WFROM is more than SIZE, then ‘wcpncpy’ copies
  3963. just the first SIZE wide characters and returns a pointer to the
  3964. wide character directly following the last non-null wide character
  3965. which was copied last. Note that in this case there is no null
  3966. terminator written into WTO.
  3967. If the length of WFROM is less than SIZE, then ‘wcpncpy’ copies all
  3968. of WFROM, followed by enough null wide characters to add up to SIZE
  3969. wide characters in all. This behavior is rarely useful, but it is
  3970. implemented to be useful in contexts where this behavior of the
  3971. ‘wcsncpy’ is used. ‘wcpncpy’ returns a pointer to the _first_
  3972. written null wide character.
  3973. This function is not part of ISO or POSIX but was found useful
  3974. while developing the GNU C Library itself.
  3975. Its behavior is undefined if the strings overlap.
  3976. As noted below, this function is generally a poor choice for
  3977. processing text.
  3978. ‘wcpncpy’ is a GNU extension.
  3979. -- Function: char * strncat (char *restrict TO, const char *restrict
  3980. FROM, size_t SIZE)
  3981. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3982. Concepts::.
  3983. This function is like ‘strcat’ except that not more than SIZE bytes
  3984. from FROM are appended to the end of TO, and FROM need not be
  3985. null-terminated. A single null byte is also always appended to TO,
  3986. so the total allocated size of TO must be at least ‘SIZE + 1’ bytes
  3987. longer than its initial length.
  3988. The ‘strncat’ function could be implemented like this:
  3989. char *
  3990. strncat (char *to, const char *from, size_t size)
  3991. {
  3992. size_t len = strlen (to);
  3993. memcpy (to + len, from, strnlen (from, size));
  3994. to[len + strnlen (from, size)] = '\0';
  3995. return to;
  3996. }
  3997. The behavior of ‘strncat’ is undefined if the strings overlap.
  3998. As a companion to ‘strncpy’, ‘strncat’ was designed for
  3999. now-rarely-used arrays consisting of non-null bytes followed by
  4000. zero or more null bytes. As noted below, this function is
  4001. generally a poor choice for processing text. Also, this function
  4002. has significant performance issues. *Note Concatenating Strings::.
  4003. -- Function: wchar_t * wcsncat (wchar_t *restrict WTO, const wchar_t
  4004. *restrict WFROM, size_t SIZE)
  4005. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4006. Concepts::.
  4007. This function is like ‘wcscat’ except that not more than SIZE wide
  4008. characters from FROM are appended to the end of TO, and FROM need
  4009. not be null-terminated. A single null wide character is also
  4010. always appended to TO, so the total allocated size of TO must be at
  4011. least ‘wcsnlen (WFROM, SIZE) + 1’ wide characters longer than its
  4012. initial length.
  4013. The ‘wcsncat’ function could be implemented like this:
  4014. wchar_t *
  4015. wcsncat (wchar_t *restrict wto, const wchar_t *restrict wfrom,
  4016. size_t size)
  4017. {
  4018. size_t len = wcslen (wto);
  4019. memcpy (wto + len, wfrom, wcsnlen (wfrom, size) * sizeof (wchar_t));
  4020. wto[len + wcsnlen (wfrom, size)] = L'\0';
  4021. return wto;
  4022. }
  4023. The behavior of ‘wcsncat’ is undefined if the strings overlap.
  4024. As noted below, this function is generally a poor choice for
  4025. processing text. Also, this function has significant performance
  4026. issues. *Note Concatenating Strings::.
  4027. Because these functions can abruptly truncate strings or wide
  4028. strings, they are generally poor choices for processing text. When
  4029. coping or concatening multibyte strings, they can truncate within a
  4030. multibyte character so that the result is not a valid multibyte string.
  4031. When combining or concatenating multibyte or wide strings, they may
  4032. truncate the output after a combining character, resulting in a
  4033. corrupted grapheme. They can cause bugs even when processing
  4034. single-byte strings: for example, when calculating an ASCII-only user
  4035. name, a truncated name can identify the wrong user.
  4036. Although some buffer overruns can be prevented by manually replacing
  4037. calls to copying functions with calls to truncation functions, there are
  4038. often easier and safer automatic techniques that cause buffer overruns
  4039. to reliably terminate a program, such as GCC’s ‘-fcheck-pointer-bounds’
  4040. and ‘-fsanitize=address’ options. *Note Options for Debugging Your
  4041. Program or GCC: (gcc.info)Debugging Options. Because truncation
  4042. functions can mask application bugs that would otherwise be caught by
  4043. the automatic techniques, these functions should be used only when the
  4044. application’s underlying logic requires truncation.
  4045. *Note:* GNU programs should not truncate strings or wide strings to
  4046. fit arbitrary size limits. *Note Writing Robust Programs:
  4047. (standards)Semantics. Instead of string-truncation functions, it is
  4048. usually better to use dynamic memory allocation (*note Unconstrained
  4049. Allocation::) and functions such as ‘strdup’ or ‘asprintf’ to construct
  4050. strings.
  4051. 
  4052. File: libc.info, Node: String/Array Comparison, Next: Collation Functions, Prev: Truncating Strings, Up: String and Array Utilities
  4053. 5.7 String/Array Comparison
  4054. ===========================
  4055. You can use the functions in this section to perform comparisons on the
  4056. contents of strings and arrays. As well as checking for equality, these
  4057. functions can also be used as the ordering functions for sorting
  4058. operations. *Note Searching and Sorting::, for an example of this.
  4059. Unlike most comparison operations in C, the string comparison
  4060. functions return a nonzero value if the strings are _not_ equivalent
  4061. rather than if they are. The sign of the value indicates the relative
  4062. ordering of the first part of the strings that are not equivalent: a
  4063. negative value indicates that the first string is “less” than the
  4064. second, while a positive value indicates that the first string is
  4065. “greater”.
  4066. The most common use of these functions is to check only for equality.
  4067. This is canonically done with an expression like ‘! strcmp (s1, s2)’.
  4068. All of these functions are declared in the header file ‘string.h’.
  4069. -- Function: int memcmp (const void *A1, const void *A2, size_t SIZE)
  4070. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4071. Concepts::.
  4072. The function ‘memcmp’ compares the SIZE bytes of memory beginning
  4073. at A1 against the SIZE bytes of memory beginning at A2. The value
  4074. returned has the same sign as the difference between the first
  4075. differing pair of bytes (interpreted as ‘unsigned char’ objects,
  4076. then promoted to ‘int’).
  4077. If the contents of the two blocks are equal, ‘memcmp’ returns ‘0’.
  4078. -- Function: int wmemcmp (const wchar_t *A1, const wchar_t *A2, size_t
  4079. SIZE)
  4080. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4081. Concepts::.
  4082. The function ‘wmemcmp’ compares the SIZE wide characters beginning
  4083. at A1 against the SIZE wide characters beginning at A2. The value
  4084. returned is smaller than or larger than zero depending on whether
  4085. the first differing wide character is A1 is smaller or larger than
  4086. the corresponding wide character in A2.
  4087. If the contents of the two blocks are equal, ‘wmemcmp’ returns ‘0’.
  4088. On arbitrary arrays, the ‘memcmp’ function is mostly useful for
  4089. testing equality. It usually isn’t meaningful to do byte-wise ordering
  4090. comparisons on arrays of things other than bytes. For example, a
  4091. byte-wise comparison on the bytes that make up floating-point numbers
  4092. isn’t likely to tell you anything about the relationship between the
  4093. values of the floating-point numbers.
  4094. ‘wmemcmp’ is really only useful to compare arrays of type ‘wchar_t’
  4095. since the function looks at ‘sizeof (wchar_t)’ bytes at a time and this
  4096. number of bytes is system dependent.
  4097. You should also be careful about using ‘memcmp’ to compare objects
  4098. that can contain “holes”, such as the padding inserted into structure
  4099. objects to enforce alignment requirements, extra space at the end of
  4100. unions, and extra bytes at the ends of strings whose length is less than
  4101. their allocated size. The contents of these “holes” are indeterminate
  4102. and may cause strange behavior when performing byte-wise comparisons.
  4103. For more predictable results, perform an explicit component-wise
  4104. comparison.
  4105. For example, given a structure type definition like:
  4106. struct foo
  4107. {
  4108. unsigned char tag;
  4109. union
  4110. {
  4111. double f;
  4112. long i;
  4113. char *p;
  4114. } value;
  4115. };
  4116. you are better off writing a specialized comparison function to compare
  4117. ‘struct foo’ objects instead of comparing them with ‘memcmp’.
  4118. -- Function: int strcmp (const char *S1, const char *S2)
  4119. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4120. Concepts::.
  4121. The ‘strcmp’ function compares the string S1 against S2, returning
  4122. a value that has the same sign as the difference between the first
  4123. differing pair of bytes (interpreted as ‘unsigned char’ objects,
  4124. then promoted to ‘int’).
  4125. If the two strings are equal, ‘strcmp’ returns ‘0’.
  4126. A consequence of the ordering used by ‘strcmp’ is that if S1 is an
  4127. initial substring of S2, then S1 is considered to be “less than”
  4128. S2.
  4129. ‘strcmp’ does not take sorting conventions of the language the
  4130. strings are written in into account. To get that one has to use
  4131. ‘strcoll’.
  4132. -- Function: int wcscmp (const wchar_t *WS1, const wchar_t *WS2)
  4133. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4134. Concepts::.
  4135. The ‘wcscmp’ function compares the wide string WS1 against WS2.
  4136. The value returned is smaller than or larger than zero depending on
  4137. whether the first differing wide character is WS1 is smaller or
  4138. larger than the corresponding wide character in WS2.
  4139. If the two strings are equal, ‘wcscmp’ returns ‘0’.
  4140. A consequence of the ordering used by ‘wcscmp’ is that if WS1 is an
  4141. initial substring of WS2, then WS1 is considered to be “less than”
  4142. WS2.
  4143. ‘wcscmp’ does not take sorting conventions of the language the
  4144. strings are written in into account. To get that one has to use
  4145. ‘wcscoll’.
  4146. -- Function: int strcasecmp (const char *S1, const char *S2)
  4147. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  4148. Safety Concepts::.
  4149. This function is like ‘strcmp’, except that differences in case are
  4150. ignored, and its arguments must be multibyte strings. How
  4151. uppercase and lowercase characters are related is determined by the
  4152. currently selected locale. In the standard ‘"C"’ locale the
  4153. characters Ä and ä do not match but in a locale which regards these
  4154. characters as parts of the alphabet they do match.
  4155. ‘strcasecmp’ is derived from BSD.
  4156. -- Function: int wcscasecmp (const wchar_t *WS1, const wchar_t *WS2)
  4157. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  4158. Safety Concepts::.
  4159. This function is like ‘wcscmp’, except that differences in case are
  4160. ignored. How uppercase and lowercase characters are related is
  4161. determined by the currently selected locale. In the standard ‘"C"’
  4162. locale the characters Ä and ä do not match but in a locale which
  4163. regards these characters as parts of the alphabet they do match.
  4164. ‘wcscasecmp’ is a GNU extension.
  4165. -- Function: int strncmp (const char *S1, const char *S2, size_t SIZE)
  4166. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4167. Concepts::.
  4168. This function is the similar to ‘strcmp’, except that no more than
  4169. SIZE bytes are compared. In other words, if the two strings are
  4170. the same in their first SIZE bytes, the return value is zero.
  4171. -- Function: int wcsncmp (const wchar_t *WS1, const wchar_t *WS2,
  4172. size_t SIZE)
  4173. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4174. Concepts::.
  4175. This function is similar to ‘wcscmp’, except that no more than SIZE
  4176. wide characters are compared. In other words, if the two strings
  4177. are the same in their first SIZE wide characters, the return value
  4178. is zero.
  4179. -- Function: int strncasecmp (const char *S1, const char *S2, size_t N)
  4180. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  4181. Safety Concepts::.
  4182. This function is like ‘strncmp’, except that differences in case
  4183. are ignored, and the compared parts of the arguments should consist
  4184. of valid multibyte characters. Like ‘strcasecmp’, it is locale
  4185. dependent how uppercase and lowercase characters are related.
  4186. ‘strncasecmp’ is a GNU extension.
  4187. -- Function: int wcsncasecmp (const wchar_t *WS1, const wchar_t *S2,
  4188. size_t N)
  4189. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  4190. Safety Concepts::.
  4191. This function is like ‘wcsncmp’, except that differences in case
  4192. are ignored. Like ‘wcscasecmp’, it is locale dependent how
  4193. uppercase and lowercase characters are related.
  4194. ‘wcsncasecmp’ is a GNU extension.
  4195. Here are some examples showing the use of ‘strcmp’ and ‘strncmp’
  4196. (equivalent examples can be constructed for the wide character
  4197. functions). These examples assume the use of the ASCII character set.
  4198. (If some other character set—say, EBCDIC—is used instead, then the
  4199. glyphs are associated with different numeric codes, and the return
  4200. values and ordering may differ.)
  4201. strcmp ("hello", "hello")
  4202. ⇒ 0 /* These two strings are the same. */
  4203. strcmp ("hello", "Hello")
  4204. ⇒ 32 /* Comparisons are case-sensitive. */
  4205. strcmp ("hello", "world")
  4206. ⇒ -15 /* The byte ‘'h'’ comes before ‘'w'’. */
  4207. strcmp ("hello", "hello, world")
  4208. ⇒ -44 /* Comparing a null byte against a comma. */
  4209. strncmp ("hello", "hello, world", 5)
  4210. ⇒ 0 /* The initial 5 bytes are the same. */
  4211. strncmp ("hello, world", "hello, stupid world!!!", 5)
  4212. ⇒ 0 /* The initial 5 bytes are the same. */
  4213. -- Function: int strverscmp (const char *S1, const char *S2)
  4214. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  4215. Safety Concepts::.
  4216. The ‘strverscmp’ function compares the string S1 against S2,
  4217. considering them as holding indices/version numbers. The return
  4218. value follows the same conventions as found in the ‘strcmp’
  4219. function. In fact, if S1 and S2 contain no digits, ‘strverscmp’
  4220. behaves like ‘strcmp’ (in the sense that the sign of the result is
  4221. the same).
  4222. The comparison algorithm which the ‘strverscmp’ function implements
  4223. differs slightly from other version-comparison algorithms. The
  4224. implementation is based on a finite-state machine, whose behavior
  4225. is approximated below.
  4226. • The input strings are each split into sequences of non-digits
  4227. and digits. These sequences can be empty at the beginning and
  4228. end of the string. Digits are determined by the ‘isdigit’
  4229. function and are thus subject to the current locale.
  4230. • Comparison starts with a (possibly empty) non-digit sequence.
  4231. The first non-equal sequences of non-digits or digits
  4232. determines the outcome of the comparison.
  4233. • Corresponding non-digit sequences in both strings are compared
  4234. lexicographically if their lengths are equal. If the lengths
  4235. differ, the shorter non-digit sequence is extended with the
  4236. input string character immediately following it (which may be
  4237. the null terminator), the other sequence is truncated to be of
  4238. the same (extended) length, and these two sequences are
  4239. compared lexicographically. In the last case, the sequence
  4240. comparison determines the result of the function because the
  4241. extension character (or some character before it) is
  4242. necessarily different from the character at the same offset in
  4243. the other input string.
  4244. • For two sequences of digits, the number of leading zeros is
  4245. counted (which can be zero). If the count differs, the string
  4246. with more leading zeros in the digit sequence is considered
  4247. smaller than the other string.
  4248. • If the two sequences of digits have no leading zeros, they are
  4249. compared as integers, that is, the string with the longer
  4250. digit sequence is deemed larger, and if both sequences are of
  4251. equal length, they are compared lexicographically.
  4252. • If both digit sequences start with a zero and have an equal
  4253. number of leading zeros, they are compared lexicographically
  4254. if their lengths are the same. If the lengths differ, the
  4255. shorter sequence is extended with the following character in
  4256. its input string, and the other sequence is truncated to the
  4257. same length, and both sequences are compared lexicographically
  4258. (similar to the non-digit sequence case above).
  4259. The treatment of leading zeros and the tie-breaking extension
  4260. characters (which in effect propagate across non-digit/digit
  4261. sequence boundaries) differs from other version-comparison
  4262. algorithms.
  4263. strverscmp ("no digit", "no digit")
  4264. ⇒ 0 /* same behavior as strcmp. */
  4265. strverscmp ("item#99", "item#100")
  4266. ⇒ <0 /* same prefix, but 99 < 100. */
  4267. strverscmp ("alpha1", "alpha001")
  4268. ⇒ >0 /* different number of leading zeros (0 and 2). */
  4269. strverscmp ("part1_f012", "part1_f01")
  4270. ⇒ >0 /* lexicographical comparison with leading zeros. */
  4271. strverscmp ("foo.009", "foo.0")
  4272. ⇒ <0 /* different number of leading zeros (2 and 1). */
  4273. ‘strverscmp’ is a GNU extension.
  4274. -- Function: int bcmp (const void *A1, const void *A2, size_t SIZE)
  4275. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4276. Concepts::.
  4277. This is an obsolete alias for ‘memcmp’, derived from BSD.
  4278. 
  4279. File: libc.info, Node: Collation Functions, Next: Search Functions, Prev: String/Array Comparison, Up: String and Array Utilities
  4280. 5.8 Collation Functions
  4281. =======================
  4282. In some locales, the conventions for lexicographic ordering differ from
  4283. the strict numeric ordering of character codes. For example, in Spanish
  4284. most glyphs with diacritical marks such as accents are not considered
  4285. distinct letters for the purposes of collation. On the other hand, the
  4286. two-character sequence ‘ll’ is treated as a single letter that is
  4287. collated immediately after ‘l’.
  4288. You can use the functions ‘strcoll’ and ‘strxfrm’ (declared in the
  4289. headers file ‘string.h’) and ‘wcscoll’ and ‘wcsxfrm’ (declared in the
  4290. headers file ‘wchar’) to compare strings using a collation ordering
  4291. appropriate for the current locale. The locale used by these functions
  4292. in particular can be specified by setting the locale for the
  4293. ‘LC_COLLATE’ category; see *note Locales::.
  4294. In the standard C locale, the collation sequence for ‘strcoll’ is the
  4295. same as that for ‘strcmp’. Similarly, ‘wcscoll’ and ‘wcscmp’ are the
  4296. same in this situation.
  4297. Effectively, the way these functions work is by applying a mapping to
  4298. transform the characters in a multibyte string to a byte sequence that
  4299. represents the string’s position in the collating sequence of the
  4300. current locale. Comparing two such byte sequences in a simple fashion
  4301. is equivalent to comparing the strings with the locale’s collating
  4302. sequence.
  4303. The functions ‘strcoll’ and ‘wcscoll’ perform this translation
  4304. implicitly, in order to do one comparison. By contrast, ‘strxfrm’ and
  4305. ‘wcsxfrm’ perform the mapping explicitly. If you are making multiple
  4306. comparisons using the same string or set of strings, it is likely to be
  4307. more efficient to use ‘strxfrm’ or ‘wcsxfrm’ to transform all the
  4308. strings just once, and subsequently compare the transformed strings with
  4309. ‘strcmp’ or ‘wcscmp’.
  4310. -- Function: int strcoll (const char *S1, const char *S2)
  4311. Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
  4312. *Note POSIX Safety Concepts::.
  4313. The ‘strcoll’ function is similar to ‘strcmp’ but uses the
  4314. collating sequence of the current locale for collation (the
  4315. ‘LC_COLLATE’ locale). The arguments are multibyte strings.
  4316. -- Function: int wcscoll (const wchar_t *WS1, const wchar_t *WS2)
  4317. Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
  4318. *Note POSIX Safety Concepts::.
  4319. The ‘wcscoll’ function is similar to ‘wcscmp’ but uses the
  4320. collating sequence of the current locale for collation (the
  4321. ‘LC_COLLATE’ locale).
  4322. Here is an example of sorting an array of strings, using ‘strcoll’ to
  4323. compare them. The actual sort algorithm is not written here; it comes
  4324. from ‘qsort’ (*note Array Sort Function::). The job of the code shown
  4325. here is to say how to compare the strings while sorting them. (Later on
  4326. in this section, we will show a way to do this more efficiently using
  4327. ‘strxfrm’.)
  4328. /* This is the comparison function used with ‘qsort’. */
  4329. int
  4330. compare_elements (const void *v1, const void *v2)
  4331. {
  4332. char * const *p1 = v1;
  4333. char * const *p2 = v2;
  4334. return strcoll (*p1, *p2);
  4335. }
  4336. /* This is the entry point—the function to sort
  4337. strings using the locale’s collating sequence. */
  4338. void
  4339. sort_strings (char **array, int nstrings)
  4340. {
  4341. /* Sort ‘temp_array’ by comparing the strings. */
  4342. qsort (array, nstrings,
  4343. sizeof (char *), compare_elements);
  4344. }
  4345. -- Function: size_t strxfrm (char *restrict TO, const char *restrict
  4346. FROM, size_t SIZE)
  4347. Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
  4348. *Note POSIX Safety Concepts::.
  4349. The function ‘strxfrm’ transforms the multibyte string FROM using
  4350. the collation transformation determined by the locale currently
  4351. selected for collation, and stores the transformed string in the
  4352. array TO. Up to SIZE bytes (including a terminating null byte) are
  4353. stored.
  4354. The behavior is undefined if the strings TO and FROM overlap; see
  4355. *note Copying Strings and Arrays::.
  4356. The return value is the length of the entire transformed string.
  4357. This value is not affected by the value of SIZE, but if it is
  4358. greater or equal than SIZE, it means that the transformed string
  4359. did not entirely fit in the array TO. In this case, only as much
  4360. of the string as actually fits was stored. To get the whole
  4361. transformed string, call ‘strxfrm’ again with a bigger output
  4362. array.
  4363. The transformed string may be longer than the original string, and
  4364. it may also be shorter.
  4365. If SIZE is zero, no bytes are stored in TO. In this case,
  4366. ‘strxfrm’ simply returns the number of bytes that would be the
  4367. length of the transformed string. This is useful for determining
  4368. what size the allocated array should be. It does not matter what
  4369. TO is if SIZE is zero; TO may even be a null pointer.
  4370. -- Function: size_t wcsxfrm (wchar_t *restrict WTO, const wchar_t
  4371. *WFROM, size_t SIZE)
  4372. Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
  4373. *Note POSIX Safety Concepts::.
  4374. The function ‘wcsxfrm’ transforms wide string WFROM using the
  4375. collation transformation determined by the locale currently
  4376. selected for collation, and stores the transformed string in the
  4377. array WTO. Up to SIZE wide characters (including a terminating
  4378. null wide character) are stored.
  4379. The behavior is undefined if the strings WTO and WFROM overlap; see
  4380. *note Copying Strings and Arrays::.
  4381. The return value is the length of the entire transformed wide
  4382. string. This value is not affected by the value of SIZE, but if it
  4383. is greater or equal than SIZE, it means that the transformed wide
  4384. string did not entirely fit in the array WTO. In this case, only
  4385. as much of the wide string as actually fits was stored. To get the
  4386. whole transformed wide string, call ‘wcsxfrm’ again with a bigger
  4387. output array.
  4388. The transformed wide string may be longer than the original wide
  4389. string, and it may also be shorter.
  4390. If SIZE is zero, no wide characters are stored in TO. In this
  4391. case, ‘wcsxfrm’ simply returns the number of wide characters that
  4392. would be the length of the transformed wide string. This is useful
  4393. for determining what size the allocated array should be (remember
  4394. to multiply with ‘sizeof (wchar_t)’). It does not matter what WTO
  4395. is if SIZE is zero; WTO may even be a null pointer.
  4396. Here is an example of how you can use ‘strxfrm’ when you plan to do
  4397. many comparisons. It does the same thing as the previous example, but
  4398. much faster, because it has to transform each string only once, no
  4399. matter how many times it is compared with other strings. Even the time
  4400. needed to allocate and free storage is much less than the time we save,
  4401. when there are many strings.
  4402. struct sorter { char *input; char *transformed; };
  4403. /* This is the comparison function used with ‘qsort’
  4404. to sort an array of ‘struct sorter’. */
  4405. int
  4406. compare_elements (const void *v1, const void *v2)
  4407. {
  4408. const struct sorter *p1 = v1;
  4409. const struct sorter *p2 = v2;
  4410. return strcmp (p1->transformed, p2->transformed);
  4411. }
  4412. /* This is the entry point—the function to sort
  4413. strings using the locale’s collating sequence. */
  4414. void
  4415. sort_strings_fast (char **array, int nstrings)
  4416. {
  4417. struct sorter temp_array[nstrings];
  4418. int i;
  4419. /* Set up ‘temp_array’. Each element contains
  4420. one input string and its transformed string. */
  4421. for (i = 0; i < nstrings; i++)
  4422. {
  4423. size_t length = strlen (array[i]) * 2;
  4424. char *transformed;
  4425. size_t transformed_length;
  4426. temp_array[i].input = array[i];
  4427. /* First try a buffer perhaps big enough. */
  4428. transformed = (char *) xmalloc (length);
  4429. /* Transform ‘array[i]’. */
  4430. transformed_length = strxfrm (transformed, array[i], length);
  4431. /* If the buffer was not large enough, resize it
  4432. and try again. */
  4433. if (transformed_length >= length)
  4434. {
  4435. /* Allocate the needed space. +1 for terminating
  4436. ‘'\0'’ byte. */
  4437. transformed = (char *) xrealloc (transformed,
  4438. transformed_length + 1);
  4439. /* The return value is not interesting because we know
  4440. how long the transformed string is. */
  4441. (void) strxfrm (transformed, array[i],
  4442. transformed_length + 1);
  4443. }
  4444. temp_array[i].transformed = transformed;
  4445. }
  4446. /* Sort ‘temp_array’ by comparing transformed strings. */
  4447. qsort (temp_array, nstrings,
  4448. sizeof (struct sorter), compare_elements);
  4449. /* Put the elements back in the permanent array
  4450. in their sorted order. */
  4451. for (i = 0; i < nstrings; i++)
  4452. array[i] = temp_array[i].input;
  4453. /* Free the strings we allocated. */
  4454. for (i = 0; i < nstrings; i++)
  4455. free (temp_array[i].transformed);
  4456. }
  4457. The interesting part of this code for the wide character version
  4458. would look like this:
  4459. void
  4460. sort_strings_fast (wchar_t **array, int nstrings)
  4461. {
  4462. /* Transform ‘array[i]’. */
  4463. transformed_length = wcsxfrm (transformed, array[i], length);
  4464. /* If the buffer was not large enough, resize it
  4465. and try again. */
  4466. if (transformed_length >= length)
  4467. {
  4468. /* Allocate the needed space. +1 for terminating
  4469. ‘L'\0'’ wide character. */
  4470. transformed = (wchar_t *) xrealloc (transformed,
  4471. (transformed_length + 1)
  4472. * sizeof (wchar_t));
  4473. /* The return value is not interesting because we know
  4474. how long the transformed string is. */
  4475. (void) wcsxfrm (transformed, array[i],
  4476. transformed_length + 1);
  4477. }
  4478. Note the additional multiplication with ‘sizeof (wchar_t)’ in the
  4479. ‘realloc’ call.
  4480. *Compatibility Note:* The string collation functions are a new
  4481. feature of ISO C90. Older C dialects have no equivalent feature. The
  4482. wide character versions were introduced in Amendment 1 to ISO C90.
  4483. 
  4484. File: libc.info, Node: Search Functions, Next: Finding Tokens in a String, Prev: Collation Functions, Up: String and Array Utilities
  4485. 5.9 Search Functions
  4486. ====================
  4487. This section describes library functions which perform various kinds of
  4488. searching operations on strings and arrays. These functions are
  4489. declared in the header file ‘string.h’.
  4490. -- Function: void * memchr (const void *BLOCK, int C, size_t SIZE)
  4491. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4492. Concepts::.
  4493. This function finds the first occurrence of the byte C (converted
  4494. to an ‘unsigned char’) in the initial SIZE bytes of the object
  4495. beginning at BLOCK. The return value is a pointer to the located
  4496. byte, or a null pointer if no match was found.
  4497. -- Function: wchar_t * wmemchr (const wchar_t *BLOCK, wchar_t WC,
  4498. size_t SIZE)
  4499. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4500. Concepts::.
  4501. This function finds the first occurrence of the wide character WC
  4502. in the initial SIZE wide characters of the object beginning at
  4503. BLOCK. The return value is a pointer to the located wide
  4504. character, or a null pointer if no match was found.
  4505. -- Function: void * rawmemchr (const void *BLOCK, int C)
  4506. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4507. Concepts::.
  4508. Often the ‘memchr’ function is used with the knowledge that the
  4509. byte C is available in the memory block specified by the
  4510. parameters. But this means that the SIZE parameter is not really
  4511. needed and that the tests performed with it at runtime (to check
  4512. whether the end of the block is reached) are not needed.
  4513. The ‘rawmemchr’ function exists for just this situation which is
  4514. surprisingly frequent. The interface is similar to ‘memchr’ except
  4515. that the SIZE parameter is missing. The function will look beyond
  4516. the end of the block pointed to by BLOCK in case the programmer
  4517. made an error in assuming that the byte C is present in the block.
  4518. In this case the result is unspecified. Otherwise the return value
  4519. is a pointer to the located byte.
  4520. This function is of special interest when looking for the end of a
  4521. string. Since all strings are terminated by a null byte a call
  4522. like
  4523. rawmemchr (str, '\0')
  4524. will never go beyond the end of the string.
  4525. This function is a GNU extension.
  4526. -- Function: void * memrchr (const void *BLOCK, int C, size_t SIZE)
  4527. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4528. Concepts::.
  4529. The function ‘memrchr’ is like ‘memchr’, except that it searches
  4530. backwards from the end of the block defined by BLOCK and SIZE
  4531. (instead of forwards from the front).
  4532. This function is a GNU extension.
  4533. -- Function: char * strchr (const char *STRING, int C)
  4534. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4535. Concepts::.
  4536. The ‘strchr’ function finds the first occurrence of the byte C
  4537. (converted to a ‘char’) in the string beginning at STRING. The
  4538. return value is a pointer to the located byte, or a null pointer if
  4539. no match was found.
  4540. For example,
  4541. strchr ("hello, world", 'l')
  4542. ⇒ "llo, world"
  4543. strchr ("hello, world", '?')
  4544. ⇒ NULL
  4545. The terminating null byte is considered to be part of the string,
  4546. so you can use this function get a pointer to the end of a string
  4547. by specifying zero as the value of the C argument.
  4548. When ‘strchr’ returns a null pointer, it does not let you know the
  4549. position of the terminating null byte it has found. If you need
  4550. that information, it is better (but less portable) to use
  4551. ‘strchrnul’ than to search for it a second time.
  4552. -- Function: wchar_t * wcschr (const wchar_t *WSTRING, int WC)
  4553. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4554. Concepts::.
  4555. The ‘wcschr’ function finds the first occurrence of the wide
  4556. character WC in the wide string beginning at WSTRING. The return
  4557. value is a pointer to the located wide character, or a null pointer
  4558. if no match was found.
  4559. The terminating null wide character is considered to be part of the
  4560. wide string, so you can use this function get a pointer to the end
  4561. of a wide string by specifying a null wide character as the value
  4562. of the WC argument. It would be better (but less portable) to use
  4563. ‘wcschrnul’ in this case, though.
  4564. -- Function: char * strchrnul (const char *STRING, int C)
  4565. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4566. Concepts::.
  4567. ‘strchrnul’ is the same as ‘strchr’ except that if it does not find
  4568. the byte, it returns a pointer to string’s terminating null byte
  4569. rather than a null pointer.
  4570. This function is a GNU extension.
  4571. -- Function: wchar_t * wcschrnul (const wchar_t *WSTRING, wchar_t WC)
  4572. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4573. Concepts::.
  4574. ‘wcschrnul’ is the same as ‘wcschr’ except that if it does not find
  4575. the wide character, it returns a pointer to the wide string’s
  4576. terminating null wide character rather than a null pointer.
  4577. This function is a GNU extension.
  4578. One useful, but unusual, use of the ‘strchr’ function is when one
  4579. wants to have a pointer pointing to the null byte terminating a string.
  4580. This is often written in this way:
  4581. s += strlen (s);
  4582. This is almost optimal but the addition operation duplicated a bit of
  4583. the work already done in the ‘strlen’ function. A better solution is
  4584. this:
  4585. s = strchr (s, '\0');
  4586. There is no restriction on the second parameter of ‘strchr’ so it
  4587. could very well also be zero. Those readers thinking very hard about
  4588. this might now point out that the ‘strchr’ function is more expensive
  4589. than the ‘strlen’ function since we have two abort criteria. This is
  4590. right. But in the GNU C Library the implementation of ‘strchr’ is
  4591. optimized in a special way so that ‘strchr’ actually is faster.
  4592. -- Function: char * strrchr (const char *STRING, int C)
  4593. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4594. Concepts::.
  4595. The function ‘strrchr’ is like ‘strchr’, except that it searches
  4596. backwards from the end of the string STRING (instead of forwards
  4597. from the front).
  4598. For example,
  4599. strrchr ("hello, world", 'l')
  4600. ⇒ "ld"
  4601. -- Function: wchar_t * wcsrchr (const wchar_t *WSTRING, wchar_t C)
  4602. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4603. Concepts::.
  4604. The function ‘wcsrchr’ is like ‘wcschr’, except that it searches
  4605. backwards from the end of the string WSTRING (instead of forwards
  4606. from the front).
  4607. -- Function: char * strstr (const char *HAYSTACK, const char *NEEDLE)
  4608. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4609. Concepts::.
  4610. This is like ‘strchr’, except that it searches HAYSTACK for a
  4611. substring NEEDLE rather than just a single byte. It returns a
  4612. pointer into the string HAYSTACK that is the first byte of the
  4613. substring, or a null pointer if no match was found. If NEEDLE is
  4614. an empty string, the function returns HAYSTACK.
  4615. For example,
  4616. strstr ("hello, world", "l")
  4617. ⇒ "llo, world"
  4618. strstr ("hello, world", "wo")
  4619. ⇒ "world"
  4620. -- Function: wchar_t * wcsstr (const wchar_t *HAYSTACK, const wchar_t
  4621. *NEEDLE)
  4622. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4623. Concepts::.
  4624. This is like ‘wcschr’, except that it searches HAYSTACK for a
  4625. substring NEEDLE rather than just a single wide character. It
  4626. returns a pointer into the string HAYSTACK that is the first wide
  4627. character of the substring, or a null pointer if no match was
  4628. found. If NEEDLE is an empty string, the function returns
  4629. HAYSTACK.
  4630. -- Function: wchar_t * wcswcs (const wchar_t *HAYSTACK, const wchar_t
  4631. *NEEDLE)
  4632. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4633. Concepts::.
  4634. ‘wcswcs’ is a deprecated alias for ‘wcsstr’. This is the name
  4635. originally used in the X/Open Portability Guide before the Amendment 1
  4636. to ISO C90 was published.
  4637. -- Function: char * strcasestr (const char *HAYSTACK, const char
  4638. *NEEDLE)
  4639. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  4640. Safety Concepts::.
  4641. This is like ‘strstr’, except that it ignores case in searching for
  4642. the substring. Like ‘strcasecmp’, it is locale dependent how
  4643. uppercase and lowercase characters are related, and arguments are
  4644. multibyte strings.
  4645. For example,
  4646. strcasestr ("hello, world", "L")
  4647. ⇒ "llo, world"
  4648. strcasestr ("hello, World", "wo")
  4649. ⇒ "World"
  4650. -- Function: void * memmem (const void *HAYSTACK, size_t HAYSTACK-LEN,
  4651. const void *NEEDLE, size_t NEEDLE-LEN)
  4652. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4653. Concepts::.
  4654. This is like ‘strstr’, but NEEDLE and HAYSTACK are byte arrays
  4655. rather than strings. NEEDLE-LEN is the length of NEEDLE and
  4656. HAYSTACK-LEN is the length of HAYSTACK.
  4657. This function is a GNU extension.
  4658. -- Function: size_t strspn (const char *STRING, const char *SKIPSET)
  4659. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4660. Concepts::.
  4661. The ‘strspn’ (“string span”) function returns the length of the
  4662. initial substring of STRING that consists entirely of bytes that
  4663. are members of the set specified by the string SKIPSET. The order
  4664. of the bytes in SKIPSET is not important.
  4665. For example,
  4666. strspn ("hello, world", "abcdefghijklmnopqrstuvwxyz")
  4667. ⇒ 5
  4668. In a multibyte string, characters consisting of more than one byte
  4669. are not treated as single entities. Each byte is treated
  4670. separately. The function is not locale-dependent.
  4671. -- Function: size_t wcsspn (const wchar_t *WSTRING, const wchar_t
  4672. *SKIPSET)
  4673. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4674. Concepts::.
  4675. The ‘wcsspn’ (“wide character string span”) function returns the
  4676. length of the initial substring of WSTRING that consists entirely
  4677. of wide characters that are members of the set specified by the
  4678. string SKIPSET. The order of the wide characters in SKIPSET is not
  4679. important.
  4680. -- Function: size_t strcspn (const char *STRING, const char *STOPSET)
  4681. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4682. Concepts::.
  4683. The ‘strcspn’ (“string complement span”) function returns the
  4684. length of the initial substring of STRING that consists entirely of
  4685. bytes that are _not_ members of the set specified by the string
  4686. STOPSET. (In other words, it returns the offset of the first byte
  4687. in STRING that is a member of the set STOPSET.)
  4688. For example,
  4689. strcspn ("hello, world", " \t\n,.;!?")
  4690. ⇒ 5
  4691. In a multibyte string, characters consisting of more than one byte
  4692. are not treated as a single entities. Each byte is treated
  4693. separately. The function is not locale-dependent.
  4694. -- Function: size_t wcscspn (const wchar_t *WSTRING, const wchar_t
  4695. *STOPSET)
  4696. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4697. Concepts::.
  4698. The ‘wcscspn’ (“wide character string complement span”) function
  4699. returns the length of the initial substring of WSTRING that
  4700. consists entirely of wide characters that are _not_ members of the
  4701. set specified by the string STOPSET. (In other words, it returns
  4702. the offset of the first wide character in STRING that is a member
  4703. of the set STOPSET.)
  4704. -- Function: char * strpbrk (const char *STRING, const char *STOPSET)
  4705. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4706. Concepts::.
  4707. The ‘strpbrk’ (“string pointer break”) function is related to
  4708. ‘strcspn’, except that it returns a pointer to the first byte in
  4709. STRING that is a member of the set STOPSET instead of the length of
  4710. the initial substring. It returns a null pointer if no such byte
  4711. from STOPSET is found.
  4712. For example,
  4713. strpbrk ("hello, world", " \t\n,.;!?")
  4714. ⇒ ", world"
  4715. In a multibyte string, characters consisting of more than one byte
  4716. are not treated as single entities. Each byte is treated
  4717. separately. The function is not locale-dependent.
  4718. -- Function: wchar_t * wcspbrk (const wchar_t *WSTRING, const wchar_t
  4719. *STOPSET)
  4720. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4721. Concepts::.
  4722. The ‘wcspbrk’ (“wide character string pointer break”) function is
  4723. related to ‘wcscspn’, except that it returns a pointer to the first
  4724. wide character in WSTRING that is a member of the set STOPSET
  4725. instead of the length of the initial substring. It returns a null
  4726. pointer if no such wide character from STOPSET is found.
  4727. 5.9.1 Compatibility String Search Functions
  4728. -------------------------------------------
  4729. -- Function: char * index (const char *STRING, int C)
  4730. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4731. Concepts::.
  4732. ‘index’ is another name for ‘strchr’; they are exactly the same.
  4733. New code should always use ‘strchr’ since this name is defined in ISO C
  4734. while ‘index’ is a BSD invention which never was available on System V
  4735. derived systems.
  4736. -- Function: char * rindex (const char *STRING, int C)
  4737. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4738. Concepts::.
  4739. ‘rindex’ is another name for ‘strrchr’; they are exactly the same.
  4740. New code should always use ‘strrchr’ since this name is defined in ISO C
  4741. while ‘rindex’ is a BSD invention which never was available on System V
  4742. derived systems.
  4743. 
  4744. File: libc.info, Node: Finding Tokens in a String, Next: Erasing Sensitive Data, Prev: Search Functions, Up: String and Array Utilities
  4745. 5.10 Finding Tokens in a String
  4746. ===============================
  4747. It’s fairly common for programs to have a need to do some simple kinds
  4748. of lexical analysis and parsing, such as splitting a command string up
  4749. into tokens. You can do this with the ‘strtok’ function, declared in
  4750. the header file ‘string.h’.
  4751. -- Function: char * strtok (char *restrict NEWSTRING, const char
  4752. *restrict DELIMITERS)
  4753. Preliminary: | MT-Unsafe race:strtok | AS-Unsafe | AC-Safe | *Note
  4754. POSIX Safety Concepts::.
  4755. A string can be split into tokens by making a series of calls to
  4756. the function ‘strtok’.
  4757. The string to be split up is passed as the NEWSTRING argument on
  4758. the first call only. The ‘strtok’ function uses this to set up
  4759. some internal state information. Subsequent calls to get
  4760. additional tokens from the same string are indicated by passing a
  4761. null pointer as the NEWSTRING argument. Calling ‘strtok’ with
  4762. another non-null NEWSTRING argument reinitializes the state
  4763. information. It is guaranteed that no other library function ever
  4764. calls ‘strtok’ behind your back (which would mess up this internal
  4765. state information).
  4766. The DELIMITERS argument is a string that specifies a set of
  4767. delimiters that may surround the token being extracted. All the
  4768. initial bytes that are members of this set are discarded. The
  4769. first byte that is _not_ a member of this set of delimiters marks
  4770. the beginning of the next token. The end of the token is found by
  4771. looking for the next byte that is a member of the delimiter set.
  4772. This byte in the original string NEWSTRING is overwritten by a null
  4773. byte, and the pointer to the beginning of the token in NEWSTRING is
  4774. returned.
  4775. On the next call to ‘strtok’, the searching begins at the next byte
  4776. beyond the one that marked the end of the previous token. Note
  4777. that the set of delimiters DELIMITERS do not have to be the same on
  4778. every call in a series of calls to ‘strtok’.
  4779. If the end of the string NEWSTRING is reached, or if the remainder
  4780. of string consists only of delimiter bytes, ‘strtok’ returns a null
  4781. pointer.
  4782. In a multibyte string, characters consisting of more than one byte
  4783. are not treated as single entities. Each byte is treated
  4784. separately. The function is not locale-dependent.
  4785. -- Function: wchar_t * wcstok (wchar_t *NEWSTRING, const wchar_t
  4786. *DELIMITERS, wchar_t **SAVE_PTR)
  4787. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4788. Concepts::.
  4789. A string can be split into tokens by making a series of calls to
  4790. the function ‘wcstok’.
  4791. The string to be split up is passed as the NEWSTRING argument on
  4792. the first call only. The ‘wcstok’ function uses this to set up
  4793. some internal state information. Subsequent calls to get
  4794. additional tokens from the same wide string are indicated by
  4795. passing a null pointer as the NEWSTRING argument, which causes the
  4796. pointer previously stored in SAVE_PTR to be used instead.
  4797. The DELIMITERS argument is a wide string that specifies a set of
  4798. delimiters that may surround the token being extracted. All the
  4799. initial wide characters that are members of this set are discarded.
  4800. The first wide character that is _not_ a member of this set of
  4801. delimiters marks the beginning of the next token. The end of the
  4802. token is found by looking for the next wide character that is a
  4803. member of the delimiter set. This wide character in the original
  4804. wide string NEWSTRING is overwritten by a null wide character, the
  4805. pointer past the overwritten wide character is saved in SAVE_PTR,
  4806. and the pointer to the beginning of the token in NEWSTRING is
  4807. returned.
  4808. On the next call to ‘wcstok’, the searching begins at the next wide
  4809. character beyond the one that marked the end of the previous token.
  4810. Note that the set of delimiters DELIMITERS do not have to be the
  4811. same on every call in a series of calls to ‘wcstok’.
  4812. If the end of the wide string NEWSTRING is reached, or if the
  4813. remainder of string consists only of delimiter wide characters,
  4814. ‘wcstok’ returns a null pointer.
  4815. *Warning:* Since ‘strtok’ and ‘wcstok’ alter the string they is
  4816. parsing, you should always copy the string to a temporary buffer before
  4817. parsing it with ‘strtok’/‘wcstok’ (*note Copying Strings and Arrays::).
  4818. If you allow ‘strtok’ or ‘wcstok’ to modify a string that came from
  4819. another part of your program, you are asking for trouble; that string
  4820. might be used for other purposes after ‘strtok’ or ‘wcstok’ has modified
  4821. it, and it would not have the expected value.
  4822. The string that you are operating on might even be a constant. Then
  4823. when ‘strtok’ or ‘wcstok’ tries to modify it, your program will get a
  4824. fatal signal for writing in read-only memory. *Note Program Error
  4825. Signals::. Even if the operation of ‘strtok’ or ‘wcstok’ would not
  4826. require a modification of the string (e.g., if there is exactly one
  4827. token) the string can (and in the GNU C Library case will) be modified.
  4828. This is a special case of a general principle: if a part of a program
  4829. does not have as its purpose the modification of a certain data
  4830. structure, then it is error-prone to modify the data structure
  4831. temporarily.
  4832. The function ‘strtok’ is not reentrant, whereas ‘wcstok’ is. *Note
  4833. Nonreentrancy::, for a discussion of where and why reentrancy is
  4834. important.
  4835. Here is a simple example showing the use of ‘strtok’.
  4836. #include <string.h>
  4837. #include <stddef.h>
  4838. const char string[] = "words separated by spaces -- and, punctuation!";
  4839. const char delimiters[] = " .,;:!-";
  4840. char *token, *cp;
  4841. cp = strdupa (string); /* Make writable copy. */
  4842. token = strtok (cp, delimiters); /* token => "words" */
  4843. token = strtok (NULL, delimiters); /* token => "separated" */
  4844. token = strtok (NULL, delimiters); /* token => "by" */
  4845. token = strtok (NULL, delimiters); /* token => "spaces" */
  4846. token = strtok (NULL, delimiters); /* token => "and" */
  4847. token = strtok (NULL, delimiters); /* token => "punctuation" */
  4848. token = strtok (NULL, delimiters); /* token => NULL */
  4849. The GNU C Library contains two more functions for tokenizing a string
  4850. which overcome the limitation of non-reentrancy. They are not available
  4851. available for wide strings.
  4852. -- Function: char * strtok_r (char *NEWSTRING, const char *DELIMITERS,
  4853. char **SAVE_PTR)
  4854. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4855. Concepts::.
  4856. Just like ‘strtok’, this function splits the string into several
  4857. tokens which can be accessed by successive calls to ‘strtok_r’.
  4858. The difference is that, as in ‘wcstok’, the information about the
  4859. next token is stored in the space pointed to by the third argument,
  4860. SAVE_PTR, which is a pointer to a string pointer. Calling
  4861. ‘strtok_r’ with a null pointer for NEWSTRING and leaving SAVE_PTR
  4862. between the calls unchanged does the job without hindering
  4863. reentrancy.
  4864. This function is defined in POSIX.1 and can be found on many
  4865. systems which support multi-threading.
  4866. -- Function: char * strsep (char **STRING_PTR, const char *DELIMITER)
  4867. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4868. Concepts::.
  4869. This function has a similar functionality as ‘strtok_r’ with the
  4870. NEWSTRING argument replaced by the SAVE_PTR argument. The
  4871. initialization of the moving pointer has to be done by the user.
  4872. Successive calls to ‘strsep’ move the pointer along the tokens
  4873. separated by DELIMITER, returning the address of the next token and
  4874. updating STRING_PTR to point to the beginning of the next token.
  4875. One difference between ‘strsep’ and ‘strtok_r’ is that if the input
  4876. string contains more than one byte from DELIMITER in a row ‘strsep’
  4877. returns an empty string for each pair of bytes from DELIMITER.
  4878. This means that a program normally should test for ‘strsep’
  4879. returning an empty string before processing it.
  4880. This function was introduced in 4.3BSD and therefore is widely
  4881. available.
  4882. Here is how the above example looks like when ‘strsep’ is used.
  4883. #include <string.h>
  4884. #include <stddef.h>
  4885. const char string[] = "words separated by spaces -- and, punctuation!";
  4886. const char delimiters[] = " .,;:!-";
  4887. char *running;
  4888. char *token;
  4889. running = strdupa (string);
  4890. token = strsep (&running, delimiters); /* token => "words" */
  4891. token = strsep (&running, delimiters); /* token => "separated" */
  4892. token = strsep (&running, delimiters); /* token => "by" */
  4893. token = strsep (&running, delimiters); /* token => "spaces" */
  4894. token = strsep (&running, delimiters); /* token => "" */
  4895. token = strsep (&running, delimiters); /* token => "" */
  4896. token = strsep (&running, delimiters); /* token => "" */
  4897. token = strsep (&running, delimiters); /* token => "and" */
  4898. token = strsep (&running, delimiters); /* token => "" */
  4899. token = strsep (&running, delimiters); /* token => "punctuation" */
  4900. token = strsep (&running, delimiters); /* token => "" */
  4901. token = strsep (&running, delimiters); /* token => NULL */
  4902. -- Function: char * basename (const char *FILENAME)
  4903. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4904. Concepts::.
  4905. The GNU version of the ‘basename’ function returns the last
  4906. component of the path in FILENAME. This function is the preferred
  4907. usage, since it does not modify the argument, FILENAME, and
  4908. respects trailing slashes. The prototype for ‘basename’ can be
  4909. found in ‘string.h’. Note, this function is overridden by the XPG
  4910. version, if ‘libgen.h’ is included.
  4911. Example of using GNU ‘basename’:
  4912. #include <string.h>
  4913. int
  4914. main (int argc, char *argv[])
  4915. {
  4916. char *prog = basename (argv[0]);
  4917. if (argc < 2)
  4918. {
  4919. fprintf (stderr, "Usage %s <arg>\n", prog);
  4920. exit (1);
  4921. }
  4922. }
  4923. *Portability Note:* This function may produce different results on
  4924. different systems.
  4925. -- Function: char * basename (char *PATH)
  4926. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4927. Concepts::.
  4928. This is the standard XPG defined ‘basename’. It is similar in
  4929. spirit to the GNU version, but may modify the PATH by removing
  4930. trailing ’/’ bytes. If the PATH is made up entirely of ’/’ bytes,
  4931. then "/" will be returned. Also, if PATH is ‘NULL’ or an empty
  4932. string, then "." is returned. The prototype for the XPG version
  4933. can be found in ‘libgen.h’.
  4934. Example of using XPG ‘basename’:
  4935. #include <libgen.h>
  4936. int
  4937. main (int argc, char *argv[])
  4938. {
  4939. char *prog;
  4940. char *path = strdupa (argv[0]);
  4941. prog = basename (path);
  4942. if (argc < 2)
  4943. {
  4944. fprintf (stderr, "Usage %s <arg>\n", prog);
  4945. exit (1);
  4946. }
  4947. }
  4948. -- Function: char * dirname (char *PATH)
  4949. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4950. Concepts::.
  4951. The ‘dirname’ function is the compliment to the XPG version of
  4952. ‘basename’. It returns the parent directory of the file specified
  4953. by PATH. If PATH is ‘NULL’, an empty string, or contains no ’/’
  4954. bytes, then "." is returned. The prototype for this function can
  4955. be found in ‘libgen.h’.
  4956. 
  4957. File: libc.info, Node: Erasing Sensitive Data, Next: strfry, Prev: Finding Tokens in a String, Up: String and Array Utilities
  4958. 5.11 Erasing Sensitive Data
  4959. ===========================
  4960. Sensitive data, such as cryptographic keys, should be erased from memory
  4961. after use, to reduce the risk that a bug will expose it to the outside
  4962. world. However, compiler optimizations may determine that an erasure
  4963. operation is “unnecessary,” and remove it from the generated code,
  4964. because no _correct_ program could access the variable or heap object
  4965. containing the sensitive data after it’s deallocated. Since erasure is
  4966. a precaution against bugs, this optimization is inappropriate.
  4967. The function ‘explicit_bzero’ erases a block of memory, and
  4968. guarantees that the compiler will not remove the erasure as
  4969. “unnecessary.”
  4970. #include <string.h>
  4971. extern void encrypt (const char *key, const char *in,
  4972. char *out, size_t n);
  4973. extern void genkey (const char *phrase, char *key);
  4974. void encrypt_with_phrase (const char *phrase, const char *in,
  4975. char *out, size_t n)
  4976. {
  4977. char key[16];
  4978. genkey (phrase, key);
  4979. encrypt (key, in, out, n);
  4980. explicit_bzero (key, 16);
  4981. }
  4982. In this example, if ‘memset’, ‘bzero’, or a hand-written loop had been
  4983. used, the compiler might remove them as “unnecessary.”
  4984. *Warning:* ‘explicit_bzero’ does not guarantee that sensitive data is
  4985. _completely_ erased from the computer’s memory. There may be copies in
  4986. temporary storage areas, such as registers and “scratch” stack space;
  4987. since these are invisible to the source code, a library function cannot
  4988. erase them.
  4989. Also, ‘explicit_bzero’ only operates on RAM. If a sensitive data
  4990. object never needs to have its address taken other than to call
  4991. ‘explicit_bzero’, it might be stored entirely in CPU registers _until_
  4992. the call to ‘explicit_bzero’. Then it will be copied into RAM, the copy
  4993. will be erased, and the original will remain intact. Data in RAM is
  4994. more likely to be exposed by a bug than data in registers, so this
  4995. creates a brief window where the data is at greater risk of exposure
  4996. than it would have been if the program didn’t try to erase it at all.
  4997. Declaring sensitive variables as ‘volatile’ will make both the above
  4998. problems _worse_; a ‘volatile’ variable will be stored in memory for its
  4999. entire lifetime, and the compiler will make _more_ copies of it than it
  5000. would otherwise have. Attempting to erase a normal variable “by hand”
  5001. through a ‘volatile’-qualified pointer doesn’t work at all—because the
  5002. variable itself is not ‘volatile’, some compilers will ignore the
  5003. qualification on the pointer and remove the erasure anyway.
  5004. Having said all that, in most situations, using ‘explicit_bzero’ is
  5005. better than not using it. At present, the only way to do a more
  5006. thorough job is to write the entire sensitive operation in assembly
  5007. language. We anticipate that future compilers will recognize calls to
  5008. ‘explicit_bzero’ and take appropriate steps to erase all the copies of
  5009. the affected data, whereever they may be.
  5010. -- Function: void explicit_bzero (void *BLOCK, size_t LEN)
  5011. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  5012. Concepts::.
  5013. ‘explicit_bzero’ writes zero into LEN bytes of memory beginning at
  5014. BLOCK, just as ‘bzero’ would. The zeroes are always written, even
  5015. if the compiler could determine that this is “unnecessary” because
  5016. no correct program could read them back.
  5017. *Note:* The _only_ optimization that ‘explicit_bzero’ disables is
  5018. removal of “unnecessary” writes to memory. The compiler can
  5019. perform all the other optimizations that it could for a call to
  5020. ‘memset’. For instance, it may replace the function call with
  5021. inline memory writes, and it may assume that BLOCK cannot be a null
  5022. pointer.
  5023. *Portability Note:* This function first appeared in OpenBSD 5.5 and
  5024. has not been standardized. Other systems may provide the same
  5025. functionality under a different name, such as ‘explicit_memset’,
  5026. ‘memset_s’, or ‘SecureZeroMemory’.
  5027. The GNU C Library declares this function in ‘string.h’, but on
  5028. other systems it may be in ‘strings.h’ instead.
  5029. 
  5030. File: libc.info, Node: strfry, Next: Trivial Encryption, Prev: Erasing Sensitive Data, Up: String and Array Utilities
  5031. 5.12 strfry
  5032. ===========
  5033. The function below addresses the perennial programming quandary: “How do
  5034. I take good data in string form and painlessly turn it into garbage?”
  5035. This is actually a fairly simple task for C programmers who do not use
  5036. the GNU C Library string functions, but for programs based on the GNU C
  5037. Library, the ‘strfry’ function is the preferred method for destroying
  5038. string data.
  5039. The prototype for this function is in ‘string.h’.
  5040. -- Function: char * strfry (char *STRING)
  5041. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  5042. Concepts::.
  5043. ‘strfry’ creates a pseudorandom anagram of a string, replacing the
  5044. input with the anagram in place. For each position in the string,
  5045. ‘strfry’ swaps it with a position in the string selected at random
  5046. (from a uniform distribution). The two positions may be the same.
  5047. The return value of ‘strfry’ is always STRING.
  5048. *Portability Note:* This function is unique to the GNU C Library.
  5049. 
  5050. File: libc.info, Node: Trivial Encryption, Next: Encode Binary Data, Prev: strfry, Up: String and Array Utilities
  5051. 5.13 Trivial Encryption
  5052. =======================
  5053. The ‘memfrob’ function converts an array of data to something
  5054. unrecognizable and back again. It is not encryption in its usual sense
  5055. since it is easy for someone to convert the encrypted data back to clear
  5056. text. The transformation is analogous to Usenet’s “Rot13” encryption
  5057. method for obscuring offensive jokes from sensitive eyes and such.
  5058. Unlike Rot13, ‘memfrob’ works on arbitrary binary data, not just text.
  5059. For true encryption, *Note Cryptographic Functions::.
  5060. This function is declared in ‘string.h’.
  5061. -- Function: void * memfrob (void *MEM, size_t LENGTH)
  5062. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  5063. Concepts::.
  5064. ‘memfrob’ transforms (frobnicates) each byte of the data structure
  5065. at MEM, which is LENGTH bytes long, by bitwise exclusive oring it
  5066. with binary 00101010. It does the transformation in place and its
  5067. return value is always MEM.
  5068. Note that ‘memfrob’ a second time on the same data structure
  5069. returns it to its original state.
  5070. This is a good function for hiding information from someone who
  5071. doesn’t want to see it or doesn’t want to see it very much. To
  5072. really prevent people from retrieving the information, use stronger
  5073. encryption such as that described in *Note Cryptographic
  5074. Functions::.
  5075. *Portability Note:* This function is unique to the GNU C Library.
  5076. 
  5077. File: libc.info, Node: Encode Binary Data, Next: Argz and Envz Vectors, Prev: Trivial Encryption, Up: String and Array Utilities
  5078. 5.14 Encode Binary Data
  5079. =======================
  5080. To store or transfer binary data in environments which only support text
  5081. one has to encode the binary data by mapping the input bytes to bytes in
  5082. the range allowed for storing or transferring. SVID systems (and
  5083. nowadays XPG compliant systems) provide minimal support for this task.
  5084. -- Function: char * l64a (long int N)
  5085. Preliminary: | MT-Unsafe race:l64a | AS-Unsafe | AC-Safe | *Note
  5086. POSIX Safety Concepts::.
  5087. This function encodes a 32-bit input value using bytes from the
  5088. basic character set. It returns a pointer to a 7 byte buffer which
  5089. contains an encoded version of N. To encode a series of bytes the
  5090. user must copy the returned string to a destination buffer. It
  5091. returns the empty string if N is zero, which is somewhat bizarre
  5092. but mandated by the standard.
  5093. *Warning:* Since a static buffer is used this function should not
  5094. be used in multi-threaded programs. There is no thread-safe
  5095. alternative to this function in the C library.
  5096. *Compatibility Note:* The XPG standard states that the return value
  5097. of ‘l64a’ is undefined if N is negative. In the GNU
  5098. implementation, ‘l64a’ treats its argument as unsigned, so it will
  5099. return a sensible encoding for any nonzero N; however, portable
  5100. programs should not rely on this.
  5101. To encode a large buffer ‘l64a’ must be called in a loop, once for
  5102. each 32-bit word of the buffer. For example, one could do
  5103. something like this:
  5104. char *
  5105. encode (const void *buf, size_t len)
  5106. {
  5107. /* We know in advance how long the buffer has to be. */
  5108. unsigned char *in = (unsigned char *) buf;
  5109. char *out = malloc (6 + ((len + 3) / 4) * 6 + 1);
  5110. char *cp = out, *p;
  5111. /* Encode the length. */
  5112. /* Using ‘htonl’ is necessary so that the data can be
  5113. decoded even on machines with different byte order.
  5114. ‘l64a’ can return a string shorter than 6 bytes, so
  5115. we pad it with encoding of 0 ('.') at the end by
  5116. hand. */
  5117. p = stpcpy (cp, l64a (htonl (len)));
  5118. cp = mempcpy (p, "......", 6 - (p - cp));
  5119. while (len > 3)
  5120. {
  5121. unsigned long int n = *in++;
  5122. n = (n << 8) | *in++;
  5123. n = (n << 8) | *in++;
  5124. n = (n << 8) | *in++;
  5125. len -= 4;
  5126. p = stpcpy (cp, l64a (htonl (n)));
  5127. cp = mempcpy (p, "......", 6 - (p - cp));
  5128. }
  5129. if (len > 0)
  5130. {
  5131. unsigned long int n = *in++;
  5132. if (--len > 0)
  5133. {
  5134. n = (n << 8) | *in++;
  5135. if (--len > 0)
  5136. n = (n << 8) | *in;
  5137. }
  5138. cp = stpcpy (cp, l64a (htonl (n)));
  5139. }
  5140. *cp = '\0';
  5141. return out;
  5142. }
  5143. It is strange that the library does not provide the complete
  5144. functionality needed but so be it.
  5145. To decode data produced with ‘l64a’ the following function should be
  5146. used.
  5147. -- Function: long int a64l (const char *STRING)
  5148. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  5149. Concepts::.
  5150. The parameter STRING should contain a string which was produced by
  5151. a call to ‘l64a’. The function processes at least 6 bytes of this
  5152. string, and decodes the bytes it finds according to the table
  5153. below. It stops decoding when it finds a byte not in the table,
  5154. rather like ‘atoi’; if you have a buffer which has been broken into
  5155. lines, you must be careful to skip over the end-of-line bytes.
  5156. The decoded number is returned as a ‘long int’ value.
  5157. The ‘l64a’ and ‘a64l’ functions use a base 64 encoding, in which each
  5158. byte of an encoded string represents six bits of an input word. These
  5159. symbols are used for the base 64 digits:
  5160. 0 1 2 3 4 5 6 7
  5161. 0 ‘.’ ‘/’ ‘0’ ‘1’ ‘2’ ‘3’ ‘4’ ‘5’
  5162. 8 ‘6’ ‘7’ ‘8’ ‘9’ ‘A’ ‘B’ ‘C’ ‘D’
  5163. 16 ‘E’ ‘F’ ‘G’ ‘H’ ‘I’ ‘J’ ‘K’ ‘L’
  5164. 24 ‘M’ ‘N’ ‘O’ ‘P’ ‘Q’ ‘R’ ‘S’ ‘T’
  5165. 32 ‘U’ ‘V’ ‘W’ ‘X’ ‘Y’ ‘Z’ ‘a’ ‘b’
  5166. 40 ‘c’ ‘d’ ‘e’ ‘f’ ‘g’ ‘h’ ‘i’ ‘j’
  5167. 48 ‘k’ ‘l’ ‘m’ ‘n’ ‘o’ ‘p’ ‘q’ ‘r’
  5168. 56 ‘s’ ‘t’ ‘u’ ‘v’ ‘w’ ‘x’ ‘y’ ‘z’
  5169. This encoding scheme is not standard. There are some other encoding
  5170. methods which are much more widely used (UU encoding, MIME encoding).
  5171. Generally, it is better to use one of these encodings.
  5172. 
  5173. File: libc.info, Node: Argz and Envz Vectors, Prev: Encode Binary Data, Up: String and Array Utilities
  5174. 5.15 Argz and Envz Vectors
  5175. ==========================
  5176. "argz vectors" are vectors of strings in a contiguous block of memory,
  5177. each element separated from its neighbors by null bytes (‘'\0'’).
  5178. "Envz vectors" are an extension of argz vectors where each element is
  5179. a name-value pair, separated by a ‘'='’ byte (as in a Unix environment).
  5180. * Menu:
  5181. * Argz Functions:: Operations on argz vectors.
  5182. * Envz Functions:: Additional operations on environment vectors.
  5183. 
  5184. File: libc.info, Node: Argz Functions, Next: Envz Functions, Up: Argz and Envz Vectors
  5185. 5.15.1 Argz Functions
  5186. ---------------------
  5187. Each argz vector is represented by a pointer to the first element, of
  5188. type ‘char *’, and a size, of type ‘size_t’, both of which can be
  5189. initialized to ‘0’ to represent an empty argz vector. All argz
  5190. functions accept either a pointer and a size argument, or pointers to
  5191. them, if they will be modified.
  5192. The argz functions use ‘malloc’/‘realloc’ to allocate/grow argz
  5193. vectors, and so any argz vector created using these functions may be
  5194. freed by using ‘free’; conversely, any argz function that may grow a
  5195. string expects that string to have been allocated using ‘malloc’ (those
  5196. argz functions that only examine their arguments or modify them in place
  5197. will work on any sort of memory). *Note Unconstrained Allocation::.
  5198. All argz functions that do memory allocation have a return type of
  5199. ‘error_t’, and return ‘0’ for success, and ‘ENOMEM’ if an allocation
  5200. error occurs.
  5201. These functions are declared in the standard include file ‘argz.h’.
  5202. -- Function: error_t argz_create (char *const ARGV[], char **ARGZ,
  5203. size_t *ARGZ_LEN)
  5204. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  5205. POSIX Safety Concepts::.
  5206. The ‘argz_create’ function converts the Unix-style argument vector
  5207. ARGV (a vector of pointers to normal C strings, terminated by
  5208. ‘(char *)0’; *note Program Arguments::) into an argz vector with
  5209. the same elements, which is returned in ARGZ and ARGZ_LEN.
  5210. -- Function: error_t argz_create_sep (const char *STRING, int SEP, char
  5211. **ARGZ, size_t *ARGZ_LEN)
  5212. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  5213. POSIX Safety Concepts::.
  5214. The ‘argz_create_sep’ function converts the string STRING into an
  5215. argz vector (returned in ARGZ and ARGZ_LEN) by splitting it into
  5216. elements at every occurrence of the byte SEP.
  5217. -- Function: size_t argz_count (const char *ARGZ, size_t ARGZ_LEN)
  5218. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  5219. Concepts::.
  5220. Returns the number of elements in the argz vector ARGZ and
  5221. ARGZ_LEN.
  5222. -- Function: void argz_extract (const char *ARGZ, size_t ARGZ_LEN, char
  5223. **ARGV)
  5224. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  5225. Concepts::.
  5226. The ‘argz_extract’ function converts the argz vector ARGZ and
  5227. ARGZ_LEN into a Unix-style argument vector stored in ARGV, by
  5228. putting pointers to every element in ARGZ into successive positions
  5229. in ARGV, followed by a terminator of ‘0’. ARGV must be
  5230. pre-allocated with enough space to hold all the elements in ARGZ
  5231. plus the terminating ‘(char *)0’ (‘(argz_count (ARGZ, ARGZ_LEN) +
  5232. 1) * sizeof (char *)’ bytes should be enough). Note that the
  5233. string pointers stored into ARGV point into ARGZ—they are not
  5234. copies—and so ARGZ must be copied if it will be changed while ARGV
  5235. is still active. This function is useful for passing the elements
  5236. in ARGZ to an exec function (*note Executing a File::).
  5237. -- Function: void argz_stringify (char *ARGZ, size_t LEN, int SEP)
  5238. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  5239. Concepts::.
  5240. The ‘argz_stringify’ converts ARGZ into a normal string with the
  5241. elements separated by the byte SEP, by replacing each ‘'\0'’ inside
  5242. ARGZ (except the last one, which terminates the string) with SEP.
  5243. This is handy for printing ARGZ in a readable manner.
  5244. -- Function: error_t argz_add (char **ARGZ, size_t *ARGZ_LEN, const
  5245. char *STR)
  5246. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  5247. POSIX Safety Concepts::.
  5248. The ‘argz_add’ function adds the string STR to the end of the argz
  5249. vector ‘*ARGZ’, and updates ‘*ARGZ’ and ‘*ARGZ_LEN’ accordingly.
  5250. -- Function: error_t argz_add_sep (char **ARGZ, size_t *ARGZ_LEN, const
  5251. char *STR, int DELIM)
  5252. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  5253. POSIX Safety Concepts::.
  5254. The ‘argz_add_sep’ function is similar to ‘argz_add’, but STR is
  5255. split into separate elements in the result at occurrences of the
  5256. byte DELIM. This is useful, for instance, for adding the
  5257. components of a Unix search path to an argz vector, by using a
  5258. value of ‘':'’ for DELIM.
  5259. -- Function: error_t argz_append (char **ARGZ, size_t *ARGZ_LEN, const
  5260. char *BUF, size_t BUF_LEN)
  5261. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  5262. POSIX Safety Concepts::.
  5263. The ‘argz_append’ function appends BUF_LEN bytes starting at BUF to
  5264. the argz vector ‘*ARGZ’, reallocating ‘*ARGZ’ to accommodate it,
  5265. and adding BUF_LEN to ‘*ARGZ_LEN’.
  5266. -- Function: void argz_delete (char **ARGZ, size_t *ARGZ_LEN, char
  5267. *ENTRY)
  5268. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  5269. POSIX Safety Concepts::.
  5270. If ENTRY points to the beginning of one of the elements in the argz
  5271. vector ‘*ARGZ’, the ‘argz_delete’ function will remove this entry
  5272. and reallocate ‘*ARGZ’, modifying ‘*ARGZ’ and ‘*ARGZ_LEN’
  5273. accordingly. Note that as destructive argz functions usually
  5274. reallocate their argz argument, pointers into argz vectors such as
  5275. ENTRY will then become invalid.
  5276. -- Function: error_t argz_insert (char **ARGZ, size_t *ARGZ_LEN, char
  5277. *BEFORE, const char *ENTRY)
  5278. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  5279. POSIX Safety Concepts::.
  5280. The ‘argz_insert’ function inserts the string ENTRY into the argz
  5281. vector ‘*ARGZ’ at a point just before the existing element pointed
  5282. to by BEFORE, reallocating ‘*ARGZ’ and updating ‘*ARGZ’ and
  5283. ‘*ARGZ_LEN’. If BEFORE is ‘0’, ENTRY is added to the end instead
  5284. (as if by ‘argz_add’). Since the first element is in fact the same
  5285. as ‘*ARGZ’, passing in ‘*ARGZ’ as the value of BEFORE will result
  5286. in ENTRY being inserted at the beginning.
  5287. -- Function: char * argz_next (const char *ARGZ, size_t ARGZ_LEN, const
  5288. char *ENTRY)
  5289. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  5290. Concepts::.
  5291. The ‘argz_next’ function provides a convenient way of iterating
  5292. over the elements in the argz vector ARGZ. It returns a pointer to
  5293. the next element in ARGZ after the element ENTRY, or ‘0’ if there
  5294. are no elements following ENTRY. If ENTRY is ‘0’, the first
  5295. element of ARGZ is returned.
  5296. This behavior suggests two styles of iteration:
  5297. char *entry = 0;
  5298. while ((entry = argz_next (ARGZ, ARGZ_LEN, entry)))
  5299. ACTION;
  5300. (the double parentheses are necessary to make some C compilers shut
  5301. up about what they consider a questionable ‘while’-test) and:
  5302. char *entry;
  5303. for (entry = ARGZ;
  5304. entry;
  5305. entry = argz_next (ARGZ, ARGZ_LEN, entry))
  5306. ACTION;
  5307. Note that the latter depends on ARGZ having a value of ‘0’ if it is
  5308. empty (rather than a pointer to an empty block of memory); this
  5309. invariant is maintained for argz vectors created by the functions
  5310. here.
  5311. -- Function: error_t argz_replace (char **ARGZ, size_t *ARGZ_LEN,
  5312. const char *STR, const char *WITH, unsigned *REPLACE_COUNT)
  5313. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  5314. POSIX Safety Concepts::.
  5315. Replace any occurrences of the string STR in ARGZ with WITH,
  5316. reallocating ARGZ as necessary. If REPLACE_COUNT is non-zero,
  5317. ‘*REPLACE_COUNT’ will be incremented by the number of replacements
  5318. performed.
  5319. 
  5320. File: libc.info, Node: Envz Functions, Prev: Argz Functions, Up: Argz and Envz Vectors
  5321. 5.15.2 Envz Functions
  5322. ---------------------
  5323. Envz vectors are just argz vectors with additional constraints on the
  5324. form of each element; as such, argz functions can also be used on them,
  5325. where it makes sense.
  5326. Each element in an envz vector is a name-value pair, separated by a
  5327. ‘'='’ byte; if multiple ‘'='’ bytes are present in an element, those
  5328. after the first are considered part of the value, and treated like all
  5329. other non-‘'\0'’ bytes.
  5330. If _no_ ‘'='’ bytes are present in an element, that element is
  5331. considered the name of a “null” entry, as distinct from an entry with an
  5332. empty value: ‘envz_get’ will return ‘0’ if given the name of null entry,
  5333. whereas an entry with an empty value would result in a value of ‘""’;
  5334. ‘envz_entry’ will still find such entries, however. Null entries can be
  5335. removed with the ‘envz_strip’ function.
  5336. As with argz functions, envz functions that may allocate memory (and
  5337. thus fail) have a return type of ‘error_t’, and return either ‘0’ or
  5338. ‘ENOMEM’.
  5339. These functions are declared in the standard include file ‘envz.h’.
  5340. -- Function: char * envz_entry (const char *ENVZ, size_t ENVZ_LEN,
  5341. const char *NAME)
  5342. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  5343. Concepts::.
  5344. The ‘envz_entry’ function finds the entry in ENVZ with the name
  5345. NAME, and returns a pointer to the whole entry—that is, the argz
  5346. element which begins with NAME followed by a ‘'='’ byte. If there
  5347. is no entry with that name, ‘0’ is returned.
  5348. -- Function: char * envz_get (const char *ENVZ, size_t ENVZ_LEN, const
  5349. char *NAME)
  5350. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  5351. Concepts::.
  5352. The ‘envz_get’ function finds the entry in ENVZ with the name NAME
  5353. (like ‘envz_entry’), and returns a pointer to the value portion of
  5354. that entry (following the ‘'='’). If there is no entry with that
  5355. name (or only a null entry), ‘0’ is returned.
  5356. -- Function: error_t envz_add (char **ENVZ, size_t *ENVZ_LEN, const
  5357. char *NAME, const char *VALUE)
  5358. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  5359. POSIX Safety Concepts::.
  5360. The ‘envz_add’ function adds an entry to ‘*ENVZ’ (updating ‘*ENVZ’
  5361. and ‘*ENVZ_LEN’) with the name NAME, and value VALUE. If an entry
  5362. with the same name already exists in ENVZ, it is removed first. If
  5363. VALUE is ‘0’, then the new entry will be the special null type of
  5364. entry (mentioned above).
  5365. -- Function: error_t envz_merge (char **ENVZ, size_t *ENVZ_LEN, const
  5366. char *ENVZ2, size_t ENVZ2_LEN, int OVERRIDE)
  5367. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  5368. POSIX Safety Concepts::.
  5369. The ‘envz_merge’ function adds each entry in ENVZ2 to ENVZ, as if
  5370. with ‘envz_add’, updating ‘*ENVZ’ and ‘*ENVZ_LEN’. If OVERRIDE is
  5371. true, then values in ENVZ2 will supersede those with the same name
  5372. in ENVZ, otherwise not.
  5373. Null entries are treated just like other entries in this respect,
  5374. so a null entry in ENVZ can prevent an entry of the same name in
  5375. ENVZ2 from being added to ENVZ, if OVERRIDE is false.
  5376. -- Function: void envz_strip (char **ENVZ, size_t *ENVZ_LEN)
  5377. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  5378. Concepts::.
  5379. The ‘envz_strip’ function removes any null entries from ENVZ,
  5380. updating ‘*ENVZ’ and ‘*ENVZ_LEN’.
  5381. -- Function: void envz_remove (char **ENVZ, size_t *ENVZ_LEN, const
  5382. char *NAME)
  5383. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  5384. POSIX Safety Concepts::.
  5385. The ‘envz_remove’ function removes an entry named NAME from ENVZ,
  5386. updating ‘*ENVZ’ and ‘*ENVZ_LEN’.
  5387. 
  5388. File: libc.info, Node: Character Set Handling, Next: Locales, Prev: String and Array Utilities, Up: Top
  5389. 6 Character Set Handling
  5390. ************************
  5391. Character sets used in the early days of computing had only six, seven,
  5392. or eight bits for each character: there was never a case where more than
  5393. eight bits (one byte) were used to represent a single character. The
  5394. limitations of this approach became more apparent as more people
  5395. grappled with non-Roman character sets, where not all the characters
  5396. that make up a language’s character set can be represented by 2^8
  5397. choices. This chapter shows the functionality that was added to the C
  5398. library to support multiple character sets.
  5399. * Menu:
  5400. * Extended Char Intro:: Introduction to Extended Characters.
  5401. * Charset Function Overview:: Overview about Character Handling
  5402. Functions.
  5403. * Restartable multibyte conversion:: Restartable multibyte conversion
  5404. Functions.
  5405. * Non-reentrant Conversion:: Non-reentrant Conversion Function.
  5406. * Generic Charset Conversion:: Generic Charset Conversion.
  5407. 
  5408. File: libc.info, Node: Extended Char Intro, Next: Charset Function Overview, Up: Character Set Handling
  5409. 6.1 Introduction to Extended Characters
  5410. =======================================
  5411. A variety of solutions are available to overcome the differences between
  5412. character sets with a 1:1 relation between bytes and characters and
  5413. character sets with ratios of 2:1 or 4:1. The remainder of this section
  5414. gives a few examples to help understand the design decisions made while
  5415. developing the functionality of the C library.
  5416. A distinction we have to make right away is between internal and
  5417. external representation. "Internal representation" means the
  5418. representation used by a program while keeping the text in memory.
  5419. External representations are used when text is stored or transmitted
  5420. through some communication channel. Examples of external
  5421. representations include files waiting in a directory to be read and
  5422. parsed.
  5423. Traditionally there has been no difference between the two
  5424. representations. It was equally comfortable and useful to use the same
  5425. single-byte representation internally and externally. This comfort
  5426. level decreases with more and larger character sets.
  5427. One of the problems to overcome with the internal representation is
  5428. handling text that is externally encoded using different character sets.
  5429. Assume a program that reads two texts and compares them using some
  5430. metric. The comparison can be usefully done only if the texts are
  5431. internally kept in a common format.
  5432. For such a common format (= character set) eight bits are certainly
  5433. no longer enough. So the smallest entity will have to grow: "wide
  5434. characters" will now be used. Instead of one byte per character, two or
  5435. four will be used instead. (Three are not good to address in memory and
  5436. more than four bytes seem not to be necessary).
  5437. As shown in some other part of this manual, a completely new family
  5438. has been created of functions that can handle wide character texts in
  5439. memory. The most commonly used character sets for such internal wide
  5440. character representations are Unicode and ISO 10646 (also known as UCS
  5441. for Universal Character Set). Unicode was originally planned as a
  5442. 16-bit character set; whereas, ISO 10646 was designed to be a 31-bit
  5443. large code space. The two standards are practically identical. They
  5444. have the same character repertoire and code table, but Unicode specifies
  5445. added semantics. At the moment, only characters in the first ‘0x10000’
  5446. code positions (the so-called Basic Multilingual Plane, BMP) have been
  5447. assigned, but the assignment of more specialized characters outside this
  5448. 16-bit space is already in progress. A number of encodings have been
  5449. defined for Unicode and ISO 10646 characters: UCS-2 is a 16-bit word
  5450. that can only represent characters from the BMP, UCS-4 is a 32-bit word
  5451. than can represent any Unicode and ISO 10646 character, UTF-8 is an
  5452. ASCII compatible encoding where ASCII characters are represented by
  5453. ASCII bytes and non-ASCII characters by sequences of 2-6 non-ASCII
  5454. bytes, and finally UTF-16 is an extension of UCS-2 in which pairs of
  5455. certain UCS-2 words can be used to encode non-BMP characters up to
  5456. ‘0x10ffff’.
  5457. To represent wide characters the ‘char’ type is not suitable. For
  5458. this reason the ISO C standard introduces a new type that is designed to
  5459. keep one character of a wide character string. To maintain the
  5460. similarity there is also a type corresponding to ‘int’ for those
  5461. functions that take a single wide character.
  5462. -- Data type: wchar_t
  5463. This data type is used as the base type for wide character strings.
  5464. In other words, arrays of objects of this type are the equivalent
  5465. of ‘char[]’ for multibyte character strings. The type is defined
  5466. in ‘stddef.h’.
  5467. The ISO C90 standard, where ‘wchar_t’ was introduced, does not say
  5468. anything specific about the representation. It only requires that
  5469. this type is capable of storing all elements of the basic character
  5470. set. Therefore it would be legitimate to define ‘wchar_t’ as
  5471. ‘char’, which might make sense for embedded systems.
  5472. But in the GNU C Library ‘wchar_t’ is always 32 bits wide and,
  5473. therefore, capable of representing all UCS-4 values and, therefore,
  5474. covering all of ISO 10646. Some Unix systems define ‘wchar_t’ as a
  5475. 16-bit type and thereby follow Unicode very strictly. This
  5476. definition is perfectly fine with the standard, but it also means
  5477. that to represent all characters from Unicode and ISO 10646 one has
  5478. to use UTF-16 surrogate characters, which is in fact a
  5479. multi-wide-character encoding. But resorting to
  5480. multi-wide-character encoding contradicts the purpose of the
  5481. ‘wchar_t’ type.
  5482. -- Data type: wint_t
  5483. ‘wint_t’ is a data type used for parameters and variables that
  5484. contain a single wide character. As the name suggests this type is
  5485. the equivalent of ‘int’ when using the normal ‘char’ strings. The
  5486. types ‘wchar_t’ and ‘wint_t’ often have the same representation if
  5487. their size is 32 bits wide but if ‘wchar_t’ is defined as ‘char’
  5488. the type ‘wint_t’ must be defined as ‘int’ due to the parameter
  5489. promotion.
  5490. This type is defined in ‘wchar.h’ and was introduced in Amendment 1
  5491. to ISO C90.
  5492. As there are for the ‘char’ data type macros are available for
  5493. specifying the minimum and maximum value representable in an object of
  5494. type ‘wchar_t’.
  5495. -- Macro: wint_t WCHAR_MIN
  5496. The macro ‘WCHAR_MIN’ evaluates to the minimum value representable
  5497. by an object of type ‘wint_t’.
  5498. This macro was introduced in Amendment 1 to ISO C90.
  5499. -- Macro: wint_t WCHAR_MAX
  5500. The macro ‘WCHAR_MAX’ evaluates to the maximum value representable
  5501. by an object of type ‘wint_t’.
  5502. This macro was introduced in Amendment 1 to ISO C90.
  5503. Another special wide character value is the equivalent to ‘EOF’.
  5504. -- Macro: wint_t WEOF
  5505. The macro ‘WEOF’ evaluates to a constant expression of type
  5506. ‘wint_t’ whose value is different from any member of the extended
  5507. character set.
  5508. ‘WEOF’ need not be the same value as ‘EOF’ and unlike ‘EOF’ it also
  5509. need _not_ be negative. In other words, sloppy code like
  5510. {
  5511. int c;
  5512. while ((c = getc (fp)) < 0)
  5513. }
  5514. has to be rewritten to use ‘WEOF’ explicitly when wide characters
  5515. are used:
  5516. {
  5517. wint_t c;
  5518. while ((c = wgetc (fp)) != WEOF)
  5519. }
  5520. This macro was introduced in Amendment 1 to ISO C90 and is defined
  5521. in ‘wchar.h’.
  5522. These internal representations present problems when it comes to
  5523. storage and transmittal. Because each single wide character consists of
  5524. more than one byte, they are affected by byte-ordering. Thus, machines
  5525. with different endianesses would see different values when accessing the
  5526. same data. This byte ordering concern also applies for communication
  5527. protocols that are all byte-based and therefore require that the sender
  5528. has to decide about splitting the wide character in bytes. A last (but
  5529. not least important) point is that wide characters often require more
  5530. storage space than a customized byte-oriented character set.
  5531. For all the above reasons, an external encoding that is different
  5532. from the internal encoding is often used if the latter is UCS-2 or
  5533. UCS-4. The external encoding is byte-based and can be chosen
  5534. appropriately for the environment and for the texts to be handled. A
  5535. variety of different character sets can be used for this external
  5536. encoding (information that will not be exhaustively presented
  5537. here–instead, a description of the major groups will suffice). All of
  5538. the ASCII-based character sets fulfill one requirement: they are
  5539. "filesystem safe." This means that the character ‘'/'’ is used in the
  5540. encoding _only_ to represent itself. Things are a bit different for
  5541. character sets like EBCDIC (Extended Binary Coded Decimal Interchange
  5542. Code, a character set family used by IBM), but if the operating system
  5543. does not understand EBCDIC directly the parameters-to-system calls have
  5544. to be converted first anyhow.
  5545. • The simplest character sets are single-byte character sets. There
  5546. can be only up to 256 characters (for 8 bit character sets), which
  5547. is not sufficient to cover all languages but might be sufficient to
  5548. handle a specific text. Handling of a 8 bit character sets is
  5549. simple. This is not true for other kinds presented later, and
  5550. therefore, the application one uses might require the use of 8 bit
  5551. character sets.
  5552. • The ISO 2022 standard defines a mechanism for extended character
  5553. sets where one character _can_ be represented by more than one
  5554. byte. This is achieved by associating a state with the text.
  5555. Characters that can be used to change the state can be embedded in
  5556. the text. Each byte in the text might have a different
  5557. interpretation in each state. The state might even influence
  5558. whether a given byte stands for a character on its own or whether
  5559. it has to be combined with some more bytes.
  5560. In most uses of ISO 2022 the defined character sets do not allow
  5561. state changes that cover more than the next character. This has
  5562. the big advantage that whenever one can identify the beginning of
  5563. the byte sequence of a character one can interpret a text
  5564. correctly. Examples of character sets using this policy are the
  5565. various EUC character sets (used by Sun’s operating systems,
  5566. EUC-JP, EUC-KR, EUC-TW, and EUC-CN) or Shift_JIS (SJIS, a Japanese
  5567. encoding).
  5568. But there are also character sets using a state that is valid for
  5569. more than one character and has to be changed by another byte
  5570. sequence. Examples for this are ISO-2022-JP, ISO-2022-KR, and
  5571. ISO-2022-CN.
  5572. • Early attempts to fix 8 bit character sets for other languages
  5573. using the Roman alphabet lead to character sets like ISO 6937.
  5574. Here bytes representing characters like the acute accent do not
  5575. produce output themselves: one has to combine them with other
  5576. characters to get the desired result. For example, the byte
  5577. sequence ‘0xc2 0x61’ (non-spacing acute accent, followed by
  5578. lower-case ‘a’) to get the “small a with acute” character. To get
  5579. the acute accent character on its own, one has to write ‘0xc2 0x20’
  5580. (the non-spacing acute followed by a space).
  5581. Character sets like ISO 6937 are used in some embedded systems such
  5582. as teletex.
  5583. • Instead of converting the Unicode or ISO 10646 text used
  5584. internally, it is often also sufficient to simply use an encoding
  5585. different than UCS-2/UCS-4. The Unicode and ISO 10646 standards
  5586. even specify such an encoding: UTF-8. This encoding is able to
  5587. represent all of ISO 10646 31 bits in a byte string of length one
  5588. to six.
  5589. There were a few other attempts to encode ISO 10646 such as UTF-7,
  5590. but UTF-8 is today the only encoding that should be used. In fact,
  5591. with any luck UTF-8 will soon be the only external encoding that
  5592. has to be supported. It proves to be universally usable and its
  5593. only disadvantage is that it favors Roman languages by making the
  5594. byte string representation of other scripts (Cyrillic, Greek, Asian
  5595. scripts) longer than necessary if using a specific character set
  5596. for these scripts. Methods like the Unicode compression scheme can
  5597. alleviate these problems.
  5598. The question remaining is: how to select the character set or
  5599. encoding to use. The answer: you cannot decide about it yourself, it is
  5600. decided by the developers of the system or the majority of the users.
  5601. Since the goal is interoperability one has to use whatever the other
  5602. people one works with use. If there are no constraints, the selection
  5603. is based on the requirements the expected circle of users will have. In
  5604. other words, if a project is expected to be used in only, say, Russia it
  5605. is fine to use KOI8-R or a similar character set. But if at the same
  5606. time people from, say, Greece are participating one should use a
  5607. character set that allows all people to collaborate.
  5608. The most widely useful solution seems to be: go with the most general
  5609. character set, namely ISO 10646. Use UTF-8 as the external encoding and
  5610. problems about users not being able to use their own language adequately
  5611. are a thing of the past.
  5612. One final comment about the choice of the wide character
  5613. representation is necessary at this point. We have said above that the
  5614. natural choice is using Unicode or ISO 10646. This is not required, but
  5615. at least encouraged, by the ISO C standard. The standard defines at
  5616. least a macro ‘__STDC_ISO_10646__’ that is only defined on systems where
  5617. the ‘wchar_t’ type encodes ISO 10646 characters. If this symbol is not
  5618. defined one should avoid making assumptions about the wide character
  5619. representation. If the programmer uses only the functions provided by
  5620. the C library to handle wide character strings there should be no
  5621. compatibility problems with other systems.
  5622. 
  5623. File: libc.info, Node: Charset Function Overview, Next: Restartable multibyte conversion, Prev: Extended Char Intro, Up: Character Set Handling
  5624. 6.2 Overview about Character Handling Functions
  5625. ===============================================
  5626. A Unix C library contains three different sets of functions in two
  5627. families to handle character set conversion. One of the function
  5628. families (the most commonly used) is specified in the ISO C90 standard
  5629. and, therefore, is portable even beyond the Unix world. Unfortunately
  5630. this family is the least useful one. These functions should be avoided
  5631. whenever possible, especially when developing libraries (as opposed to
  5632. applications).
  5633. The second family of functions got introduced in the early Unix
  5634. standards (XPG2) and is still part of the latest and greatest Unix
  5635. standard: Unix 98. It is also the most powerful and useful set of
  5636. functions. But we will start with the functions defined in Amendment 1
  5637. to ISO C90.
  5638. 
  5639. File: libc.info, Node: Restartable multibyte conversion, Next: Non-reentrant Conversion, Prev: Charset Function Overview, Up: Character Set Handling
  5640. 6.3 Restartable Multibyte Conversion Functions
  5641. ==============================================
  5642. The ISO C standard defines functions to convert strings from a multibyte
  5643. representation to wide character strings. There are a number of
  5644. peculiarities:
  5645. • The character set assumed for the multibyte encoding is not
  5646. specified as an argument to the functions. Instead the character
  5647. set specified by the ‘LC_CTYPE’ category of the current locale is
  5648. used; see *note Locale Categories::.
  5649. • The functions handling more than one character at a time require
  5650. NUL terminated strings as the argument (i.e., converting blocks of
  5651. text does not work unless one can add a NUL byte at an appropriate
  5652. place). The GNU C Library contains some extensions to the standard
  5653. that allow specifying a size, but basically they also expect
  5654. terminated strings.
  5655. Despite these limitations the ISO C functions can be used in many
  5656. contexts. In graphical user interfaces, for instance, it is not
  5657. uncommon to have functions that require text to be displayed in a wide
  5658. character string if the text is not simple ASCII. The text itself might
  5659. come from a file with translations and the user should decide about the
  5660. current locale, which determines the translation and therefore also the
  5661. external encoding used. In such a situation (and many others) the
  5662. functions described here are perfect. If more freedom while performing
  5663. the conversion is necessary take a look at the ‘iconv’ functions (*note
  5664. Generic Charset Conversion::).
  5665. * Menu:
  5666. * Selecting the Conversion:: Selecting the conversion and its properties.
  5667. * Keeping the state:: Representing the state of the conversion.
  5668. * Converting a Character:: Converting Single Characters.
  5669. * Converting Strings:: Converting Multibyte and Wide Character
  5670. Strings.
  5671. * Multibyte Conversion Example:: A Complete Multibyte Conversion Example.
  5672. 
  5673. File: libc.info, Node: Selecting the Conversion, Next: Keeping the state, Up: Restartable multibyte conversion
  5674. 6.3.1 Selecting the conversion and its properties
  5675. -------------------------------------------------
  5676. We already said above that the currently selected locale for the
  5677. ‘LC_CTYPE’ category decides the conversion that is performed by the
  5678. functions we are about to describe. Each locale uses its own character
  5679. set (given as an argument to ‘localedef’) and this is the one assumed as
  5680. the external multibyte encoding. The wide character set is always UCS-4
  5681. in the GNU C Library.
  5682. A characteristic of each multibyte character set is the maximum
  5683. number of bytes that can be necessary to represent one character. This
  5684. information is quite important when writing code that uses the
  5685. conversion functions (as shown in the examples below). The ISO C
  5686. standard defines two macros that provide this information.
  5687. -- Macro: int MB_LEN_MAX
  5688. ‘MB_LEN_MAX’ specifies the maximum number of bytes in the multibyte
  5689. sequence for a single character in any of the supported locales.
  5690. It is a compile-time constant and is defined in ‘limits.h’.
  5691. -- Macro: int MB_CUR_MAX
  5692. ‘MB_CUR_MAX’ expands into a positive integer expression that is the
  5693. maximum number of bytes in a multibyte character in the current
  5694. locale. The value is never greater than ‘MB_LEN_MAX’. Unlike
  5695. ‘MB_LEN_MAX’ this macro need not be a compile-time constant, and in
  5696. the GNU C Library it is not.
  5697. ‘MB_CUR_MAX’ is defined in ‘stdlib.h’.
  5698. Two different macros are necessary since strictly ISO C90 compilers
  5699. do not allow variable length array definitions, but still it is
  5700. desirable to avoid dynamic allocation. This incomplete piece of code
  5701. shows the problem:
  5702. {
  5703. char buf[MB_LEN_MAX];
  5704. ssize_t len = 0;
  5705. while (! feof (fp))
  5706. {
  5707. fread (&buf[len], 1, MB_CUR_MAX - len, fp);
  5708. /* … process buf */
  5709. len -= used;
  5710. }
  5711. }
  5712. The code in the inner loop is expected to have always enough bytes in
  5713. the array BUF to convert one multibyte character. The array BUF has to
  5714. be sized statically since many compilers do not allow a variable size.
  5715. The ‘fread’ call makes sure that ‘MB_CUR_MAX’ bytes are always available
  5716. in BUF. Note that it isn’t a problem if ‘MB_CUR_MAX’ is not a
  5717. compile-time constant.
  5718. 
  5719. File: libc.info, Node: Keeping the state, Next: Converting a Character, Prev: Selecting the Conversion, Up: Restartable multibyte conversion
  5720. 6.3.2 Representing the state of the conversion
  5721. ----------------------------------------------
  5722. In the introduction of this chapter it was said that certain character
  5723. sets use a "stateful" encoding. That is, the encoded values depend in
  5724. some way on the previous bytes in the text.
  5725. Since the conversion functions allow converting a text in more than
  5726. one step we must have a way to pass this information from one call of
  5727. the functions to another.
  5728. -- Data type: mbstate_t
  5729. A variable of type ‘mbstate_t’ can contain all the information
  5730. about the "shift state" needed from one call to a conversion
  5731. function to another.
  5732. ‘mbstate_t’ is defined in ‘wchar.h’. It was introduced in Amendment 1
  5733. to ISO C90.
  5734. To use objects of type ‘mbstate_t’ the programmer has to define such
  5735. objects (normally as local variables on the stack) and pass a pointer to
  5736. the object to the conversion functions. This way the conversion
  5737. function can update the object if the current multibyte character set is
  5738. stateful.
  5739. There is no specific function or initializer to put the state object
  5740. in any specific state. The rules are that the object should always
  5741. represent the initial state before the first use, and this is achieved
  5742. by clearing the whole variable with code such as follows:
  5743. {
  5744. mbstate_t state;
  5745. memset (&state, '\0', sizeof (state));
  5746. /* from now on STATE can be used. */
  5747. }
  5748. When using the conversion functions to generate output it is often
  5749. necessary to test whether the current state corresponds to the initial
  5750. state. This is necessary, for example, to decide whether to emit escape
  5751. sequences to set the state to the initial state at certain sequence
  5752. points. Communication protocols often require this.
  5753. -- Function: int mbsinit (const mbstate_t *PS)
  5754. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  5755. Concepts::.
  5756. The ‘mbsinit’ function determines whether the state object pointed
  5757. to by PS is in the initial state. If PS is a null pointer or the
  5758. object is in the initial state the return value is nonzero.
  5759. Otherwise it is zero.
  5760. ‘mbsinit’ was introduced in Amendment 1 to ISO C90 and is declared
  5761. in ‘wchar.h’.
  5762. Code using ‘mbsinit’ often looks similar to this:
  5763. {
  5764. mbstate_t state;
  5765. memset (&state, '\0', sizeof (state));
  5766. /* Use STATE. */
  5767. if (! mbsinit (&state))
  5768. {
  5769. /* Emit code to return to initial state. */
  5770. const wchar_t empty[] = L"";
  5771. const wchar_t *srcp = empty;
  5772. wcsrtombs (outbuf, &srcp, outbuflen, &state);
  5773. }
  5774. }
  5775. The code to emit the escape sequence to get back to the initial state
  5776. is interesting. The ‘wcsrtombs’ function can be used to determine the
  5777. necessary output code (*note Converting Strings::). Please note that
  5778. with the GNU C Library it is not necessary to perform this extra action
  5779. for the conversion from multibyte text to wide character text since the
  5780. wide character encoding is not stateful. But there is nothing mentioned
  5781. in any standard that prohibits making ‘wchar_t’ use a stateful encoding.
  5782. 
  5783. File: libc.info, Node: Converting a Character, Next: Converting Strings, Prev: Keeping the state, Up: Restartable multibyte conversion
  5784. 6.3.3 Converting Single Characters
  5785. ----------------------------------
  5786. The most fundamental of the conversion functions are those dealing with
  5787. single characters. Please note that this does not always mean single
  5788. bytes. But since there is very often a subset of the multibyte
  5789. character set that consists of single byte sequences, there are
  5790. functions to help with converting bytes. Frequently, ASCII is a subset
  5791. of the multibyte character set. In such a scenario, each ASCII
  5792. character stands for itself, and all other characters have at least a
  5793. first byte that is beyond the range 0 to 127.
  5794. -- Function: wint_t btowc (int C)
  5795. Preliminary: | MT-Safe | AS-Unsafe corrupt heap lock dlopen |
  5796. AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
  5797. The ‘btowc’ function (“byte to wide character”) converts a valid
  5798. single byte character C in the initial shift state into the wide
  5799. character equivalent using the conversion rules from the currently
  5800. selected locale of the ‘LC_CTYPE’ category.
  5801. If ‘(unsigned char) C’ is no valid single byte multibyte character
  5802. or if C is ‘EOF’, the function returns ‘WEOF’.
  5803. Please note the restriction of C being tested for validity only in
  5804. the initial shift state. No ‘mbstate_t’ object is used from which
  5805. the state information is taken, and the function also does not use
  5806. any static state.
  5807. The ‘btowc’ function was introduced in Amendment 1 to ISO C90 and
  5808. is declared in ‘wchar.h’.
  5809. Despite the limitation that the single byte value is always
  5810. interpreted in the initial state, this function is actually useful most
  5811. of the time. Most characters are either entirely single-byte character
  5812. sets or they are extensions to ASCII. But then it is possible to write
  5813. code like this (not that this specific example is very useful):
  5814. wchar_t *
  5815. itow (unsigned long int val)
  5816. {
  5817. static wchar_t buf[30];
  5818. wchar_t *wcp = &buf[29];
  5819. *wcp = L'\0';
  5820. while (val != 0)
  5821. {
  5822. *--wcp = btowc ('0' + val % 10);
  5823. val /= 10;
  5824. }
  5825. if (wcp == &buf[29])
  5826. *--wcp = L'0';
  5827. return wcp;
  5828. }
  5829. Why is it necessary to use such a complicated implementation and not
  5830. simply cast ‘'0' + val % 10’ to a wide character? The answer is that
  5831. there is no guarantee that one can perform this kind of arithmetic on
  5832. the character of the character set used for ‘wchar_t’ representation.
  5833. In other situations the bytes are not constant at compile time and so
  5834. the compiler cannot do the work. In situations like this, using ‘btowc’
  5835. is required.
  5836. There is also a function for the conversion in the other direction.
  5837. -- Function: int wctob (wint_t C)
  5838. Preliminary: | MT-Safe | AS-Unsafe corrupt heap lock dlopen |
  5839. AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
  5840. The ‘wctob’ function (“wide character to byte”) takes as the
  5841. parameter a valid wide character. If the multibyte representation
  5842. for this character in the initial state is exactly one byte long,
  5843. the return value of this function is this character. Otherwise the
  5844. return value is ‘EOF’.
  5845. ‘wctob’ was introduced in Amendment 1 to ISO C90 and is declared in
  5846. ‘wchar.h’.
  5847. There are more general functions to convert single characters from
  5848. multibyte representation to wide characters and vice versa. These
  5849. functions pose no limit on the length of the multibyte representation
  5850. and they also do not require it to be in the initial state.
  5851. -- Function: size_t mbrtowc (wchar_t *restrict PWC, const char
  5852. *restrict S, size_t N, mbstate_t *restrict PS)
  5853. Preliminary: | MT-Unsafe race:mbrtowc/!ps | AS-Unsafe corrupt heap
  5854. lock dlopen | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety
  5855. Concepts::.
  5856. The ‘mbrtowc’ function (“multibyte restartable to wide character”)
  5857. converts the next multibyte character in the string pointed to by S
  5858. into a wide character and stores it in the wide character string
  5859. pointed to by PWC. The conversion is performed according to the
  5860. locale currently selected for the ‘LC_CTYPE’ category. If the
  5861. conversion for the character set used in the locale requires a
  5862. state, the multibyte string is interpreted in the state represented
  5863. by the object pointed to by PS. If PS is a null pointer, a static,
  5864. internal state variable used only by the ‘mbrtowc’ function is
  5865. used.
  5866. If the next multibyte character corresponds to the NUL wide
  5867. character, the return value of the function is 0 and the state
  5868. object is afterwards in the initial state. If the next N or fewer
  5869. bytes form a correct multibyte character, the return value is the
  5870. number of bytes starting from S that form the multibyte character.
  5871. The conversion state is updated according to the bytes consumed in
  5872. the conversion. In both cases the wide character (either the
  5873. ‘L'\0'’ or the one found in the conversion) is stored in the string
  5874. pointed to by PWC if PWC is not null.
  5875. If the first N bytes of the multibyte string possibly form a valid
  5876. multibyte character but there are more than N bytes needed to
  5877. complete it, the return value of the function is ‘(size_t) -2’ and
  5878. no value is stored. Please note that this can happen even if N has
  5879. a value greater than or equal to ‘MB_CUR_MAX’ since the input might
  5880. contain redundant shift sequences.
  5881. If the first ‘n’ bytes of the multibyte string cannot possibly form
  5882. a valid multibyte character, no value is stored, the global
  5883. variable ‘errno’ is set to the value ‘EILSEQ’, and the function
  5884. returns ‘(size_t) -1’. The conversion state is afterwards
  5885. undefined.
  5886. ‘mbrtowc’ was introduced in Amendment 1 to ISO C90 and is declared
  5887. in ‘wchar.h’.
  5888. Use of ‘mbrtowc’ is straightforward. A function that copies a
  5889. multibyte string into a wide character string while at the same time
  5890. converting all lowercase characters into uppercase could look like this
  5891. (this is not the final version, just an example; it has no error
  5892. checking, and sometimes leaks memory):
  5893. wchar_t *
  5894. mbstouwcs (const char *s)
  5895. {
  5896. size_t len = strlen (s);
  5897. wchar_t *result = malloc ((len + 1) * sizeof (wchar_t));
  5898. wchar_t *wcp = result;
  5899. wchar_t tmp[1];
  5900. mbstate_t state;
  5901. size_t nbytes;
  5902. memset (&state, '\0', sizeof (state));
  5903. while ((nbytes = mbrtowc (tmp, s, len, &state)) > 0)
  5904. {
  5905. if (nbytes >= (size_t) -2)
  5906. /* Invalid input string. */
  5907. return NULL;
  5908. *wcp++ = towupper (tmp[0]);
  5909. len -= nbytes;
  5910. s += nbytes;
  5911. }
  5912. return result;
  5913. }
  5914. The use of ‘mbrtowc’ should be clear. A single wide character is
  5915. stored in ‘TMP[0]’, and the number of consumed bytes is stored in the
  5916. variable NBYTES. If the conversion is successful, the uppercase variant
  5917. of the wide character is stored in the RESULT array and the pointer to
  5918. the input string and the number of available bytes is adjusted.
  5919. The only non-obvious thing about ‘mbrtowc’ might be the way memory is
  5920. allocated for the result. The above code uses the fact that there can
  5921. never be more wide characters in the converted result than there are
  5922. bytes in the multibyte input string. This method yields a pessimistic
  5923. guess about the size of the result, and if many wide character strings
  5924. have to be constructed this way or if the strings are long, the extra
  5925. memory required to be allocated because the input string contains
  5926. multibyte characters might be significant. The allocated memory block
  5927. can be resized to the correct size before returning it, but a better
  5928. solution might be to allocate just the right amount of space for the
  5929. result right away. Unfortunately there is no function to compute the
  5930. length of the wide character string directly from the multibyte string.
  5931. There is, however, a function that does part of the work.
  5932. -- Function: size_t mbrlen (const char *restrict S, size_t N, mbstate_t
  5933. *PS)
  5934. Preliminary: | MT-Unsafe race:mbrlen/!ps | AS-Unsafe corrupt heap
  5935. lock dlopen | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety
  5936. Concepts::.
  5937. The ‘mbrlen’ function (“multibyte restartable length”) computes the
  5938. number of at most N bytes starting at S, which form the next valid
  5939. and complete multibyte character.
  5940. If the next multibyte character corresponds to the NUL wide
  5941. character, the return value is 0. If the next N bytes form a valid
  5942. multibyte character, the number of bytes belonging to this
  5943. multibyte character byte sequence is returned.
  5944. If the first N bytes possibly form a valid multibyte character but
  5945. the character is incomplete, the return value is ‘(size_t) -2’.
  5946. Otherwise the multibyte character sequence is invalid and the
  5947. return value is ‘(size_t) -1’.
  5948. The multibyte sequence is interpreted in the state represented by
  5949. the object pointed to by PS. If PS is a null pointer, a state
  5950. object local to ‘mbrlen’ is used.
  5951. ‘mbrlen’ was introduced in Amendment 1 to ISO C90 and is declared
  5952. in ‘wchar.h’.
  5953. The attentive reader now will note that ‘mbrlen’ can be implemented
  5954. as
  5955. mbrtowc (NULL, s, n, ps != NULL ? ps : &internal)
  5956. This is true and in fact is mentioned in the official specification.
  5957. How can this function be used to determine the length of the wide
  5958. character string created from a multibyte character string? It is not
  5959. directly usable, but we can define a function ‘mbslen’ using it:
  5960. size_t
  5961. mbslen (const char *s)
  5962. {
  5963. mbstate_t state;
  5964. size_t result = 0;
  5965. size_t nbytes;
  5966. memset (&state, '\0', sizeof (state));
  5967. while ((nbytes = mbrlen (s, MB_LEN_MAX, &state)) > 0)
  5968. {
  5969. if (nbytes >= (size_t) -2)
  5970. /* Something is wrong. */
  5971. return (size_t) -1;
  5972. s += nbytes;
  5973. ++result;
  5974. }
  5975. return result;
  5976. }
  5977. This function simply calls ‘mbrlen’ for each multibyte character in
  5978. the string and counts the number of function calls. Please note that we
  5979. here use ‘MB_LEN_MAX’ as the size argument in the ‘mbrlen’ call. This
  5980. is acceptable since a) this value is larger than the length of the
  5981. longest multibyte character sequence and b) we know that the string S
  5982. ends with a NUL byte, which cannot be part of any other multibyte
  5983. character sequence but the one representing the NUL wide character.
  5984. Therefore, the ‘mbrlen’ function will never read invalid memory.
  5985. Now that this function is available (just to make this clear, this
  5986. function is _not_ part of the GNU C Library) we can compute the number
  5987. of wide characters required to store the converted multibyte character
  5988. string S using
  5989. wcs_bytes = (mbslen (s) + 1) * sizeof (wchar_t);
  5990. Please note that the ‘mbslen’ function is quite inefficient. The
  5991. implementation of ‘mbstouwcs’ with ‘mbslen’ would have to perform the
  5992. conversion of the multibyte character input string twice, and this
  5993. conversion might be quite expensive. So it is necessary to think about
  5994. the consequences of using the easier but imprecise method before doing
  5995. the work twice.
  5996. -- Function: size_t wcrtomb (char *restrict S, wchar_t WC, mbstate_t
  5997. *restrict PS)
  5998. Preliminary: | MT-Unsafe race:wcrtomb/!ps | AS-Unsafe corrupt heap
  5999. lock dlopen | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety
  6000. Concepts::.
  6001. The ‘wcrtomb’ function (“wide character restartable to multibyte”)
  6002. converts a single wide character into a multibyte string
  6003. corresponding to that wide character.
  6004. If S is a null pointer, the function resets the state stored in the
  6005. object pointed to by PS (or the internal ‘mbstate_t’ object) to the
  6006. initial state. This can also be achieved by a call like this:
  6007. wcrtombs (temp_buf, L'\0', ps)
  6008. since, if S is a null pointer, ‘wcrtomb’ performs as if it writes
  6009. into an internal buffer, which is guaranteed to be large enough.
  6010. If WC is the NUL wide character, ‘wcrtomb’ emits, if necessary, a
  6011. shift sequence to get the state PS into the initial state followed
  6012. by a single NUL byte, which is stored in the string S.
  6013. Otherwise a byte sequence (possibly including shift sequences) is
  6014. written into the string S. This only happens if WC is a valid wide
  6015. character (i.e., it has a multibyte representation in the character
  6016. set selected by locale of the ‘LC_CTYPE’ category). If WC is no
  6017. valid wide character, nothing is stored in the strings S, ‘errno’
  6018. is set to ‘EILSEQ’, the conversion state in PS is undefined and the
  6019. return value is ‘(size_t) -1’.
  6020. If no error occurred the function returns the number of bytes
  6021. stored in the string S. This includes all bytes representing shift
  6022. sequences.
  6023. One word about the interface of the function: there is no parameter
  6024. specifying the length of the array S. Instead the function assumes
  6025. that there are at least ‘MB_CUR_MAX’ bytes available since this is
  6026. the maximum length of any byte sequence representing a single
  6027. character. So the caller has to make sure that there is enough
  6028. space available, otherwise buffer overruns can occur.
  6029. ‘wcrtomb’ was introduced in Amendment 1 to ISO C90 and is declared
  6030. in ‘wchar.h’.
  6031. Using ‘wcrtomb’ is as easy as using ‘mbrtowc’. The following example
  6032. appends a wide character string to a multibyte character string. Again,
  6033. the code is not really useful (or correct), it is simply here to
  6034. demonstrate the use and some problems.
  6035. char *
  6036. mbscatwcs (char *s, size_t len, const wchar_t *ws)
  6037. {
  6038. mbstate_t state;
  6039. /* Find the end of the existing string. */
  6040. char *wp = strchr (s, '\0');
  6041. len -= wp - s;
  6042. memset (&state, '\0', sizeof (state));
  6043. do
  6044. {
  6045. size_t nbytes;
  6046. if (len < MB_CUR_LEN)
  6047. {
  6048. /* We cannot guarantee that the next
  6049. character fits into the buffer, so
  6050. return an error. */
  6051. errno = E2BIG;
  6052. return NULL;
  6053. }
  6054. nbytes = wcrtomb (wp, *ws, &state);
  6055. if (nbytes == (size_t) -1)
  6056. /* Error in the conversion. */
  6057. return NULL;
  6058. len -= nbytes;
  6059. wp += nbytes;
  6060. }
  6061. while (*ws++ != L'\0');
  6062. return s;
  6063. }
  6064. First the function has to find the end of the string currently in the
  6065. array S. The ‘strchr’ call does this very efficiently since a
  6066. requirement for multibyte character representations is that the NUL byte
  6067. is never used except to represent itself (and in this context, the end
  6068. of the string).
  6069. After initializing the state object the loop is entered where the
  6070. first task is to make sure there is enough room in the array S. We
  6071. abort if there are not at least ‘MB_CUR_LEN’ bytes available. This is
  6072. not always optimal but we have no other choice. We might have less than
  6073. ‘MB_CUR_LEN’ bytes available but the next multibyte character might also
  6074. be only one byte long. At the time the ‘wcrtomb’ call returns it is too
  6075. late to decide whether the buffer was large enough. If this solution is
  6076. unsuitable, there is a very slow but more accurate solution.
  6077. if (len < MB_CUR_LEN)
  6078. {
  6079. mbstate_t temp_state;
  6080. memcpy (&temp_state, &state, sizeof (state));
  6081. if (wcrtomb (NULL, *ws, &temp_state) > len)
  6082. {
  6083. /* We cannot guarantee that the next
  6084. character fits into the buffer, so
  6085. return an error. */
  6086. errno = E2BIG;
  6087. return NULL;
  6088. }
  6089. }
  6090. Here we perform the conversion that might overflow the buffer so that
  6091. we are afterwards in the position to make an exact decision about the
  6092. buffer size. Please note the ‘NULL’ argument for the destination buffer
  6093. in the new ‘wcrtomb’ call; since we are not interested in the converted
  6094. text at this point, this is a nice way to express this. The most
  6095. unusual thing about this piece of code certainly is the duplication of
  6096. the conversion state object, but if a change of the state is necessary
  6097. to emit the next multibyte character, we want to have the same shift
  6098. state change performed in the real conversion. Therefore, we have to
  6099. preserve the initial shift state information.
  6100. There are certainly many more and even better solutions to this
  6101. problem. This example is only provided for educational purposes.