libc.info-4 295 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185418641874188418941904191419241934194419541964197419841994200420142024203420442054206420742084209421042114212421342144215421642174218421942204221422242234224422542264227422842294230423142324233423442354236423742384239424042414242424342444245424642474248424942504251425242534254425542564257425842594260426142624263426442654266426742684269427042714272427342744275427642774278427942804281428242834284428542864287428842894290429142924293429442954296429742984299430043014302430343044305430643074308430943104311431243134314431543164317431843194320432143224323432443254326432743284329433043314332433343344335433643374338433943404341434243434344434543464347434843494350435143524353435443554356435743584359436043614362436343644365436643674368436943704371437243734374437543764377437843794380438143824383438443854386438743884389439043914392439343944395439643974398439944004401440244034404440544064407440844094410441144124413441444154416441744184419442044214422442344244425442644274428442944304431443244334434443544364437443844394440444144424443444444454446444744484449445044514452445344544455445644574458445944604461446244634464446544664467446844694470447144724473447444754476447744784479448044814482448344844485448644874488448944904491449244934494449544964497449844994500450145024503450445054506450745084509451045114512451345144515451645174518451945204521452245234524452545264527452845294530453145324533453445354536453745384539454045414542454345444545454645474548454945504551455245534554455545564557455845594560456145624563456445654566456745684569457045714572457345744575457645774578457945804581458245834584458545864587458845894590459145924593459445954596459745984599460046014602460346044605460646074608460946104611461246134614461546164617461846194620462146224623462446254626462746284629463046314632463346344635463646374638463946404641464246434644464546464647464846494650465146524653465446554656465746584659466046614662466346644665466646674668466946704671467246734674467546764677467846794680468146824683468446854686468746884689469046914692469346944695469646974698469947004701470247034704470547064707470847094710471147124713471447154716471747184719472047214722472347244725472647274728472947304731473247334734473547364737473847394740474147424743474447454746474747484749475047514752475347544755475647574758475947604761476247634764476547664767476847694770477147724773477447754776477747784779478047814782478347844785478647874788478947904791479247934794479547964797479847994800480148024803480448054806480748084809481048114812481348144815481648174818481948204821482248234824482548264827482848294830483148324833483448354836483748384839484048414842484348444845484648474848484948504851485248534854485548564857485848594860486148624863486448654866486748684869487048714872487348744875487648774878487948804881488248834884488548864887488848894890489148924893489448954896489748984899490049014902490349044905490649074908490949104911491249134914491549164917491849194920492149224923492449254926492749284929493049314932493349344935493649374938493949404941494249434944494549464947494849494950495149524953495449554956495749584959496049614962496349644965496649674968496949704971497249734974497549764977497849794980498149824983498449854986498749884989499049914992499349944995499649974998499950005001500250035004500550065007500850095010501150125013501450155016501750185019502050215022502350245025502650275028502950305031503250335034503550365037503850395040504150425043504450455046504750485049505050515052505350545055505650575058505950605061506250635064506550665067506850695070507150725073507450755076507750785079508050815082508350845085508650875088508950905091509250935094509550965097509850995100510151025103510451055106510751085109511051115112511351145115511651175118511951205121512251235124512551265127512851295130513151325133513451355136513751385139514051415142514351445145514651475148514951505151515251535154515551565157515851595160516151625163516451655166516751685169517051715172517351745175517651775178517951805181518251835184518551865187518851895190519151925193519451955196519751985199520052015202520352045205520652075208520952105211521252135214521552165217521852195220522152225223522452255226522752285229523052315232523352345235523652375238523952405241524252435244524552465247524852495250525152525253525452555256525752585259526052615262526352645265526652675268526952705271527252735274527552765277527852795280528152825283528452855286528752885289529052915292529352945295529652975298529953005301530253035304530553065307530853095310531153125313531453155316531753185319532053215322532353245325532653275328532953305331533253335334533553365337533853395340534153425343534453455346534753485349535053515352535353545355535653575358535953605361536253635364536553665367536853695370537153725373537453755376537753785379538053815382538353845385538653875388538953905391539253935394539553965397539853995400540154025403540454055406540754085409541054115412541354145415541654175418541954205421542254235424542554265427542854295430543154325433543454355436543754385439544054415442544354445445544654475448544954505451545254535454545554565457545854595460546154625463546454655466546754685469547054715472547354745475547654775478547954805481548254835484548554865487548854895490549154925493549454955496549754985499550055015502550355045505550655075508550955105511551255135514551555165517551855195520552155225523552455255526552755285529553055315532553355345535553655375538553955405541554255435544554555465547554855495550555155525553555455555556555755585559556055615562556355645565556655675568556955705571557255735574557555765577557855795580558155825583558455855586558755885589559055915592559355945595559655975598559956005601560256035604560556065607560856095610561156125613561456155616561756185619562056215622562356245625562656275628562956305631563256335634563556365637563856395640564156425643564456455646564756485649565056515652565356545655565656575658565956605661566256635664566556665667566856695670567156725673567456755676567756785679568056815682568356845685568656875688568956905691569256935694569556965697569856995700570157025703570457055706570757085709571057115712571357145715571657175718571957205721572257235724572557265727572857295730573157325733573457355736573757385739574057415742574357445745574657475748574957505751575257535754575557565757575857595760576157625763576457655766576757685769577057715772577357745775577657775778577957805781578257835784578557865787578857895790579157925793579457955796579757985799580058015802580358045805580658075808580958105811581258135814581558165817581858195820582158225823582458255826582758285829583058315832583358345835583658375838583958405841584258435844584558465847584858495850585158525853585458555856585758585859586058615862586358645865586658675868586958705871587258735874587558765877587858795880588158825883588458855886588758885889589058915892589358945895589658975898589959005901590259035904590559065907590859095910591159125913591459155916591759185919592059215922592359245925592659275928592959305931593259335934593559365937593859395940594159425943594459455946594759485949595059515952595359545955595659575958595959605961596259635964596559665967596859695970597159725973597459755976597759785979598059815982598359845985598659875988598959905991599259935994599559965997599859996000600160026003600460056006600760086009601060116012601360146015601660176018601960206021602260236024602560266027602860296030603160326033603460356036603760386039604060416042604360446045604660476048604960506051605260536054605560566057605860596060606160626063606460656066606760686069607060716072607360746075607660776078607960806081608260836084608560866087608860896090609160926093609460956096609760986099610061016102610361046105610661076108610961106111611261136114611561166117611861196120612161226123612461256126612761286129613061316132613361346135613661376138613961406141614261436144614561466147614861496150615161526153615461556156615761586159616061616162616361646165616661676168616961706171617261736174617561766177617861796180618161826183618461856186618761886189619061916192619361946195619661976198619962006201620262036204620562066207620862096210621162126213621462156216621762186219622062216222622362246225622662276228622962306231623262336234623562366237623862396240624162426243624462456246624762486249625062516252625362546255625662576258625962606261626262636264626562666267626862696270627162726273627462756276627762786279628062816282628362846285628662876288628962906291629262936294629562966297629862996300630163026303630463056306630763086309631063116312631363146315631663176318631963206321632263236324632563266327632863296330633163326333633463356336633763386339634063416342634363446345634663476348634963506351635263536354635563566357635863596360636163626363636463656366636763686369637063716372637363746375637663776378637963806381638263836384638563866387638863896390639163926393639463956396639763986399640064016402640364046405640664076408640964106411641264136414641564166417641864196420642164226423642464256426642764286429643064316432643364346435643664376438643964406441644264436444644564466447644864496450645164526453645464556456645764586459646064616462646364646465646664676468646964706471647264736474647564766477647864796480648164826483648464856486648764886489649064916492649364946495649664976498649965006501650265036504650565066507650865096510651165126513651465156516651765186519652065216522652365246525652665276528652965306531653265336534653565366537653865396540654165426543654465456546654765486549655065516552655365546555655665576558655965606561656265636564656565666567656865696570657165726573657465756576657765786579658065816582658365846585658665876588658965906591659265936594659565966597659865996600660166026603660466056606660766086609661066116612661366146615661666176618661966206621662266236624662566266627662866296630663166326633663466356636663766386639664066416642664366446645664666476648664966506651665266536654665566566657665866596660666166626663666466656666666766686669667066716672667366746675667666776678667966806681668266836684668566866687668866896690669166926693669466956696669766986699670067016702670367046705670667076708670967106711671267136714671567166717671867196720672167226723672467256726672767286729673067316732673367346735673667376738673967406741674267436744674567466747674867496750675167526753675467556756675767586759676067616762676367646765676667676768676967706771677267736774677567766777677867796780678167826783678467856786678767886789679067916792679367946795679667976798679968006801680268036804680568066807680868096810681168126813681468156816681768186819682068216822682368246825682668276828682968306831683268336834683568366837683868396840684168426843684468456846684768486849685068516852685368546855685668576858685968606861686268636864686568666867686868696870687168726873687468756876687768786879688068816882688368846885688668876888688968906891689268936894689568966897689868996900690169026903690469056906690769086909691069116912691369146915691669176918691969206921692269236924692569266927692869296930693169326933693469356936693769386939694069416942694369446945694669476948694969506951695269536954695569566957695869596960696169626963696469656966696769686969697069716972697369746975697669776978697969806981698269836984698569866987698869896990699169926993699469956996699769986999700070017002700370047005700670077008700970107011701270137014701570167017701870197020702170227023702470257026702770287029703070317032703370347035703670377038703970407041704270437044704570467047704870497050705170527053705470557056705770587059706070617062706370647065706670677068706970707071707270737074707570767077707870797080708170827083708470857086708770887089709070917092709370947095709670977098709971007101710271037104710571067107710871097110711171127113711471157116711771187119712071217122712371247125712671277128712971307131
  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: Searching and Sorting, Next: Pattern Matching, Prev: Message Translation, Up: Top
  1792. 9 Searching and Sorting
  1793. ***********************
  1794. This chapter describes functions for searching and sorting arrays of
  1795. arbitrary objects. You pass the appropriate comparison function to be
  1796. applied as an argument, along with the size of the objects in the array
  1797. and the total number of elements.
  1798. * Menu:
  1799. * Comparison Functions:: Defining how to compare two objects.
  1800. Since the sort and search facilities
  1801. are general, you have to specify the
  1802. ordering.
  1803. * Array Search Function:: The ‘bsearch’ function.
  1804. * Array Sort Function:: The ‘qsort’ function.
  1805. * Search/Sort Example:: An example program.
  1806. * Hash Search Function:: The ‘hsearch’ function.
  1807. * Tree Search Function:: The ‘tsearch’ function.
  1808. 
  1809. File: libc.info, Node: Comparison Functions, Next: Array Search Function, Up: Searching and Sorting
  1810. 9.1 Defining the Comparison Function
  1811. ====================================
  1812. In order to use the sorted array library functions, you have to describe
  1813. how to compare the elements of the array.
  1814. To do this, you supply a comparison function to compare two elements
  1815. of the array. The library will call this function, passing as arguments
  1816. pointers to two array elements to be compared. Your comparison function
  1817. should return a value the way ‘strcmp’ (*note String/Array Comparison::)
  1818. does: negative if the first argument is “less” than the second, zero if
  1819. they are “equal”, and positive if the first argument is “greater”.
  1820. Here is an example of a comparison function which works with an array
  1821. of numbers of type ‘double’:
  1822. int
  1823. compare_doubles (const void *a, const void *b)
  1824. {
  1825. const double *da = (const double *) a;
  1826. const double *db = (const double *) b;
  1827. return (*da > *db) - (*da < *db);
  1828. }
  1829. The header file ‘stdlib.h’ defines a name for the data type of
  1830. comparison functions. This type is a GNU extension.
  1831. int comparison_fn_t (const void *, const void *);
  1832. 
  1833. File: libc.info, Node: Array Search Function, Next: Array Sort Function, Prev: Comparison Functions, Up: Searching and Sorting
  1834. 9.2 Array Search Function
  1835. =========================
  1836. Generally searching for a specific element in an array means that
  1837. potentially all elements must be checked. The GNU C Library contains
  1838. functions to perform linear search. The prototypes for the following
  1839. two functions can be found in ‘search.h’.
  1840. -- Function: void * lfind (const void *KEY, const void *BASE, size_t
  1841. *NMEMB, size_t SIZE, comparison_fn_t COMPAR)
  1842. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  1843. Concepts::.
  1844. The ‘lfind’ function searches in the array with ‘*NMEMB’ elements
  1845. of SIZE bytes pointed to by BASE for an element which matches the
  1846. one pointed to by KEY. The function pointed to by COMPAR is used
  1847. to decide whether two elements match.
  1848. The return value is a pointer to the matching element in the array
  1849. starting at BASE if it is found. If no matching element is
  1850. available ‘NULL’ is returned.
  1851. The mean runtime of this function is ‘*NMEMB’/2. This function
  1852. should only be used if elements often get added to or deleted from
  1853. the array in which case it might not be useful to sort the array
  1854. before searching.
  1855. -- Function: void * lsearch (const void *KEY, void *BASE, size_t
  1856. *NMEMB, size_t SIZE, comparison_fn_t COMPAR)
  1857. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  1858. Concepts::.
  1859. The ‘lsearch’ function is similar to the ‘lfind’ function. It
  1860. searches the given array for an element and returns it if found.
  1861. The difference is that if no matching element is found the
  1862. ‘lsearch’ function adds the object pointed to by KEY (with a size
  1863. of SIZE bytes) at the end of the array and it increments the value
  1864. of ‘*NMEMB’ to reflect this addition.
  1865. This means for the caller that if it is not sure that the array
  1866. contains the element one is searching for the memory allocated for
  1867. the array starting at BASE must have room for at least SIZE more
  1868. bytes. If one is sure the element is in the array it is better to
  1869. use ‘lfind’ so having more room in the array is always necessary
  1870. when calling ‘lsearch’.
  1871. To search a sorted array for an element matching the key, use the
  1872. ‘bsearch’ function. The prototype for this function is in the header
  1873. file ‘stdlib.h’.
  1874. -- Function: void * bsearch (const void *KEY, const void *ARRAY, size_t
  1875. COUNT, size_t SIZE, comparison_fn_t COMPARE)
  1876. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  1877. Concepts::.
  1878. The ‘bsearch’ function searches the sorted array ARRAY for an
  1879. object that is equivalent to KEY. The array contains COUNT
  1880. elements, each of which is of size SIZE bytes.
  1881. The COMPARE function is used to perform the comparison. This
  1882. function is called with two pointer arguments and should return an
  1883. integer less than, equal to, or greater than zero corresponding to
  1884. whether its first argument is considered less than, equal to, or
  1885. greater than its second argument. The elements of the ARRAY must
  1886. already be sorted in ascending order according to this comparison
  1887. function.
  1888. The return value is a pointer to the matching array element, or a
  1889. null pointer if no match is found. If the array contains more than
  1890. one element that matches, the one that is returned is unspecified.
  1891. This function derives its name from the fact that it is implemented
  1892. using the binary search algorithm.
  1893. 
  1894. File: libc.info, Node: Array Sort Function, Next: Search/Sort Example, Prev: Array Search Function, Up: Searching and Sorting
  1895. 9.3 Array Sort Function
  1896. =======================
  1897. To sort an array using an arbitrary comparison function, use the ‘qsort’
  1898. function. The prototype for this function is in ‘stdlib.h’.
  1899. -- Function: void qsort (void *ARRAY, size_t COUNT, size_t SIZE,
  1900. comparison_fn_t COMPARE)
  1901. Preliminary: | MT-Safe | AS-Safe | AC-Unsafe corrupt | *Note POSIX
  1902. Safety Concepts::.
  1903. The ‘qsort’ function sorts the array ARRAY. The array contains
  1904. COUNT elements, each of which is of size SIZE.
  1905. The COMPARE function is used to perform the comparison on the array
  1906. elements. This function is called with two pointer arguments and
  1907. should return an integer less than, equal to, or greater than zero
  1908. corresponding to whether its first argument is considered less
  1909. than, equal to, or greater than its second argument.
  1910. *Warning:* If two objects compare as equal, their order after
  1911. sorting is unpredictable. That is to say, the sorting is not
  1912. stable. This can make a difference when the comparison considers
  1913. only part of the elements. Two elements with the same sort key may
  1914. differ in other respects.
  1915. Although the object addresses passed to the comparison function lie
  1916. within the array, they need not correspond with the original
  1917. locations of those objects because the sorting algorithm may swap
  1918. around objects in the array before making some comparisons. The
  1919. only way to perform a stable sort with ‘qsort’ is to first augment
  1920. the objects with a monotonic counter of some kind.
  1921. Here is a simple example of sorting an array of doubles in
  1922. numerical order, using the comparison function defined above (*note
  1923. Comparison Functions::):
  1924. {
  1925. double *array;
  1926. int size;
  1927. qsort (array, size, sizeof (double), compare_doubles);
  1928. }
  1929. The ‘qsort’ function derives its name from the fact that it was
  1930. originally implemented using the “quick sort” algorithm.
  1931. The implementation of ‘qsort’ in this library might not be an
  1932. in-place sort and might thereby use an extra amount of memory to
  1933. store the array.
  1934. 
  1935. File: libc.info, Node: Search/Sort Example, Next: Hash Search Function, Prev: Array Sort Function, Up: Searching and Sorting
  1936. 9.4 Searching and Sorting Example
  1937. =================================
  1938. Here is an example showing the use of ‘qsort’ and ‘bsearch’ with an
  1939. array of structures. The objects in the array are sorted by comparing
  1940. their ‘name’ fields with the ‘strcmp’ function. Then, we can look up
  1941. individual objects based on their names.
  1942. #include <stdlib.h>
  1943. #include <stdio.h>
  1944. #include <string.h>
  1945. /* Define an array of critters to sort. */
  1946. struct critter
  1947. {
  1948. const char *name;
  1949. const char *species;
  1950. };
  1951. struct critter muppets[] =
  1952. {
  1953. {"Kermit", "frog"},
  1954. {"Piggy", "pig"},
  1955. {"Gonzo", "whatever"},
  1956. {"Fozzie", "bear"},
  1957. {"Sam", "eagle"},
  1958. {"Robin", "frog"},
  1959. {"Animal", "animal"},
  1960. {"Camilla", "chicken"},
  1961. {"Sweetums", "monster"},
  1962. {"Dr. Strangepork", "pig"},
  1963. {"Link Hogthrob", "pig"},
  1964. {"Zoot", "human"},
  1965. {"Dr. Bunsen Honeydew", "human"},
  1966. {"Beaker", "human"},
  1967. {"Swedish Chef", "human"}
  1968. };
  1969. int count = sizeof (muppets) / sizeof (struct critter);
  1970. /* This is the comparison function used for sorting and searching. */
  1971. int
  1972. critter_cmp (const void *v1, const void *v2)
  1973. {
  1974. const struct critter *c1 = v1;
  1975. const struct critter *c2 = v2;
  1976. return strcmp (c1->name, c2->name);
  1977. }
  1978. /* Print information about a critter. */
  1979. void
  1980. print_critter (const struct critter *c)
  1981. {
  1982. printf ("%s, the %s\n", c->name, c->species);
  1983. }
  1984. /* Do the lookup into the sorted array. */
  1985. void
  1986. find_critter (const char *name)
  1987. {
  1988. struct critter target, *result;
  1989. target.name = name;
  1990. result = bsearch (&target, muppets, count, sizeof (struct critter),
  1991. critter_cmp);
  1992. if (result)
  1993. print_critter (result);
  1994. else
  1995. printf ("Couldn't find %s.\n", name);
  1996. }
  1997. /* Main program. */
  1998. int
  1999. main (void)
  2000. {
  2001. int i;
  2002. for (i = 0; i < count; i++)
  2003. print_critter (&muppets[i]);
  2004. printf ("\n");
  2005. qsort (muppets, count, sizeof (struct critter), critter_cmp);
  2006. for (i = 0; i < count; i++)
  2007. print_critter (&muppets[i]);
  2008. printf ("\n");
  2009. find_critter ("Kermit");
  2010. find_critter ("Gonzo");
  2011. find_critter ("Janice");
  2012. return 0;
  2013. }
  2014. The output from this program looks like:
  2015. Kermit, the frog
  2016. Piggy, the pig
  2017. Gonzo, the whatever
  2018. Fozzie, the bear
  2019. Sam, the eagle
  2020. Robin, the frog
  2021. Animal, the animal
  2022. Camilla, the chicken
  2023. Sweetums, the monster
  2024. Dr. Strangepork, the pig
  2025. Link Hogthrob, the pig
  2026. Zoot, the human
  2027. Dr. Bunsen Honeydew, the human
  2028. Beaker, the human
  2029. Swedish Chef, the human
  2030. Animal, the animal
  2031. Beaker, the human
  2032. Camilla, the chicken
  2033. Dr. Bunsen Honeydew, the human
  2034. Dr. Strangepork, the pig
  2035. Fozzie, the bear
  2036. Gonzo, the whatever
  2037. Kermit, the frog
  2038. Link Hogthrob, the pig
  2039. Piggy, the pig
  2040. Robin, the frog
  2041. Sam, the eagle
  2042. Swedish Chef, the human
  2043. Sweetums, the monster
  2044. Zoot, the human
  2045. Kermit, the frog
  2046. Gonzo, the whatever
  2047. Couldn't find Janice.
  2048. 
  2049. File: libc.info, Node: Hash Search Function, Next: Tree Search Function, Prev: Search/Sort Example, Up: Searching and Sorting
  2050. 9.5 The ‘hsearch’ function.
  2051. ===========================
  2052. The functions mentioned so far in this chapter are for searching in a
  2053. sorted or unsorted array. There are other methods to organize
  2054. information which later should be searched. The costs of insert, delete
  2055. and search differ. One possible implementation is using hashing tables.
  2056. The following functions are declared in the header file ‘search.h’.
  2057. -- Function: int hcreate (size_t NEL)
  2058. Preliminary: | MT-Unsafe race:hsearch | AS-Unsafe heap | AC-Unsafe
  2059. corrupt mem | *Note POSIX Safety Concepts::.
  2060. The ‘hcreate’ function creates a hashing table which can contain at
  2061. least NEL elements. There is no possibility to grow this table so
  2062. it is necessary to choose the value for NEL wisely. The method
  2063. used to implement this function might make it necessary to make the
  2064. number of elements in the hashing table larger than the expected
  2065. maximal number of elements. Hashing tables usually work
  2066. inefficiently if they are filled 80% or more. The constant access
  2067. time guaranteed by hashing can only be achieved if few collisions
  2068. exist. See Knuth’s “The Art of Computer Programming, Part 3:
  2069. Searching and Sorting” for more information.
  2070. The weakest aspect of this function is that there can be at most
  2071. one hashing table used through the whole program. The table is
  2072. allocated in local memory out of control of the programmer. As an
  2073. extension the GNU C Library provides an additional set of functions
  2074. with a reentrant interface which provides a similar interface but
  2075. which allows keeping arbitrarily many hashing tables.
  2076. It is possible to use more than one hashing table in the program
  2077. run if the former table is first destroyed by a call to ‘hdestroy’.
  2078. The function returns a non-zero value if successful. If it returns
  2079. zero, something went wrong. This could either mean there is
  2080. already a hashing table in use or the program ran out of memory.
  2081. -- Function: void hdestroy (void)
  2082. Preliminary: | MT-Unsafe race:hsearch | AS-Unsafe heap | AC-Unsafe
  2083. corrupt mem | *Note POSIX Safety Concepts::.
  2084. The ‘hdestroy’ function can be used to free all the resources
  2085. allocated in a previous call of ‘hcreate’. After a call to this
  2086. function it is again possible to call ‘hcreate’ and allocate a new
  2087. table with possibly different size.
  2088. It is important to remember that the elements contained in the
  2089. hashing table at the time ‘hdestroy’ is called are _not_ freed by
  2090. this function. It is the responsibility of the program code to
  2091. free those strings (if necessary at all). Freeing all the element
  2092. memory is not possible without extra, separately kept information
  2093. since there is no function to iterate through all available
  2094. elements in the hashing table. If it is really necessary to free a
  2095. table and all elements the programmer has to keep a list of all
  2096. table elements and before calling ‘hdestroy’ s/he has to free all
  2097. element’s data using this list. This is a very unpleasant
  2098. mechanism and it also shows that this kind of hashing table is
  2099. mainly meant for tables which are created once and used until the
  2100. end of the program run.
  2101. Entries of the hashing table and keys for the search are defined
  2102. using this type:
  2103. -- Data type: struct ENTRY
  2104. Both elements of this structure are pointers to zero-terminated
  2105. strings. This is a limiting restriction of the functionality of
  2106. the ‘hsearch’ functions. They can only be used for data sets which
  2107. use the NUL character always and solely to terminate the records.
  2108. It is not possible to handle general binary data.
  2109. ‘char *key’
  2110. Pointer to a zero-terminated string of characters describing
  2111. the key for the search or the element in the hashing table.
  2112. ‘char *data’
  2113. Pointer to a zero-terminated string of characters describing
  2114. the data. If the functions will be called only for searching
  2115. an existing entry this element might stay undefined since it
  2116. is not used.
  2117. -- Function: ENTRY * hsearch (ENTRY ITEM, ACTION ACTION)
  2118. Preliminary: | MT-Unsafe race:hsearch | AS-Unsafe | AC-Unsafe
  2119. corrupt/action==ENTER | *Note POSIX Safety Concepts::.
  2120. To search in a hashing table created using ‘hcreate’ the ‘hsearch’
  2121. function must be used. This function can perform a simple search
  2122. for an element (if ACTION has the value ‘FIND’) or it can
  2123. alternatively insert the key element into the hashing table.
  2124. Entries are never replaced.
  2125. The key is denoted by a pointer to an object of type ‘ENTRY’. For
  2126. locating the corresponding position in the hashing table only the
  2127. ‘key’ element of the structure is used.
  2128. If an entry with a matching key is found the ACTION parameter is
  2129. irrelevant. The found entry is returned. If no matching entry is
  2130. found and the ACTION parameter has the value ‘FIND’ the function
  2131. returns a ‘NULL’ pointer. If no entry is found and the ACTION
  2132. parameter has the value ‘ENTER’ a new entry is added to the hashing
  2133. table which is initialized with the parameter ITEM. A pointer to
  2134. the newly added entry is returned.
  2135. As mentioned before, the hashing table used by the functions
  2136. described so far is global and there can be at any time at most one
  2137. hashing table in the program. A solution is to use the following
  2138. functions which are a GNU extension. All have in common that they
  2139. operate on a hashing table which is described by the content of an
  2140. object of the type ‘struct hsearch_data’. This type should be treated
  2141. as opaque, none of its members should be changed directly.
  2142. -- Function: int hcreate_r (size_t NEL, struct hsearch_data *HTAB)
  2143. Preliminary: | MT-Safe race:htab | AS-Unsafe heap | AC-Unsafe
  2144. corrupt mem | *Note POSIX Safety Concepts::.
  2145. The ‘hcreate_r’ function initializes the object pointed to by HTAB
  2146. to contain a hashing table with at least NEL elements. So this
  2147. function is equivalent to the ‘hcreate’ function except that the
  2148. initialized data structure is controlled by the user.
  2149. This allows having more than one hashing table at one time. The
  2150. memory necessary for the ‘struct hsearch_data’ object can be
  2151. allocated dynamically. It must be initialized with zero before
  2152. calling this function.
  2153. The return value is non-zero if the operation was successful. If
  2154. the return value is zero, something went wrong, which probably
  2155. means the program ran out of memory.
  2156. -- Function: void hdestroy_r (struct hsearch_data *HTAB)
  2157. Preliminary: | MT-Safe race:htab | AS-Unsafe heap | AC-Unsafe
  2158. corrupt mem | *Note POSIX Safety Concepts::.
  2159. The ‘hdestroy_r’ function frees all resources allocated by the
  2160. ‘hcreate_r’ function for this very same object HTAB. As for
  2161. ‘hdestroy’ it is the program’s responsibility to free the strings
  2162. for the elements of the table.
  2163. -- Function: int hsearch_r (ENTRY ITEM, ACTION ACTION, ENTRY **RETVAL,
  2164. struct hsearch_data *HTAB)
  2165. Preliminary: | MT-Safe race:htab | AS-Safe | AC-Unsafe
  2166. corrupt/action==ENTER | *Note POSIX Safety Concepts::.
  2167. The ‘hsearch_r’ function is equivalent to ‘hsearch’. The meaning
  2168. of the first two arguments is identical. But instead of operating
  2169. on a single global hashing table the function works on the table
  2170. described by the object pointed to by HTAB (which is initialized by
  2171. a call to ‘hcreate_r’).
  2172. Another difference to ‘hcreate’ is that the pointer to the found
  2173. entry in the table is not the return value of the function. It is
  2174. returned by storing it in a pointer variable pointed to by the
  2175. RETVAL parameter. The return value of the function is an integer
  2176. value indicating success if it is non-zero and failure if it is
  2177. zero. In the latter case the global variable ERRNO signals the
  2178. reason for the failure.
  2179. ‘ENOMEM’
  2180. The table is filled and ‘hsearch_r’ was called with a so far
  2181. unknown key and ACTION set to ‘ENTER’.
  2182. ‘ESRCH’
  2183. The ACTION parameter is ‘FIND’ and no corresponding element is
  2184. found in the table.
  2185. 
  2186. File: libc.info, Node: Tree Search Function, Prev: Hash Search Function, Up: Searching and Sorting
  2187. 9.6 The ‘tsearch’ function.
  2188. ===========================
  2189. Another common form to organize data for efficient search is to use
  2190. trees. The ‘tsearch’ function family provides a nice interface to
  2191. functions to organize possibly large amounts of data by providing a mean
  2192. access time proportional to the logarithm of the number of elements.
  2193. The GNU C Library implementation even guarantees that this bound is
  2194. never exceeded even for input data which cause problems for simple
  2195. binary tree implementations.
  2196. The functions described in the chapter are all described in the System V
  2197. and X/Open specifications and are therefore quite portable.
  2198. In contrast to the ‘hsearch’ functions the ‘tsearch’ functions can be
  2199. used with arbitrary data and not only zero-terminated strings.
  2200. The ‘tsearch’ functions have the advantage that no function to
  2201. initialize data structures is necessary. A simple pointer of type ‘void
  2202. *’ initialized to ‘NULL’ is a valid tree and can be extended or
  2203. searched. The prototypes for these functions can be found in the header
  2204. file ‘search.h’.
  2205. -- Function: void * tsearch (const void *KEY, void **ROOTP,
  2206. comparison_fn_t COMPAR)
  2207. Preliminary: | MT-Safe race:rootp | AS-Unsafe heap | AC-Unsafe
  2208. corrupt mem | *Note POSIX Safety Concepts::.
  2209. The ‘tsearch’ function searches in the tree pointed to by ‘*ROOTP’
  2210. for an element matching KEY. The function pointed to by COMPAR is
  2211. used to determine whether two elements match. *Note Comparison
  2212. Functions::, for a specification of the functions which can be used
  2213. for the COMPAR parameter.
  2214. If the tree does not contain a matching entry the KEY value will be
  2215. added to the tree. ‘tsearch’ does not make a copy of the object
  2216. pointed to by KEY (how could it since the size is unknown).
  2217. Instead it adds a reference to this object which means the object
  2218. must be available as long as the tree data structure is used.
  2219. The tree is represented by a pointer to a pointer since it is
  2220. sometimes necessary to change the root node of the tree. So it
  2221. must not be assumed that the variable pointed to by ROOTP has the
  2222. same value after the call. This also shows that it is not safe to
  2223. call the ‘tsearch’ function more than once at the same time using
  2224. the same tree. It is no problem to run it more than once at a time
  2225. on different trees.
  2226. The return value is a pointer to the matching element in the tree.
  2227. If a new element was created the pointer points to the new data
  2228. (which is in fact KEY). If an entry had to be created and the
  2229. program ran out of space ‘NULL’ is returned.
  2230. -- Function: void * tfind (const void *KEY, void *const *ROOTP,
  2231. comparison_fn_t COMPAR)
  2232. Preliminary: | MT-Safe race:rootp | AS-Safe | AC-Safe | *Note POSIX
  2233. Safety Concepts::.
  2234. The ‘tfind’ function is similar to the ‘tsearch’ function. It
  2235. locates an element matching the one pointed to by KEY and returns a
  2236. pointer to this element. But if no matching element is available
  2237. no new element is entered (note that the ROOTP parameter points to
  2238. a constant pointer). Instead the function returns ‘NULL’.
  2239. Another advantage of the ‘tsearch’ functions in contrast to the
  2240. ‘hsearch’ functions is that there is an easy way to remove elements.
  2241. -- Function: void * tdelete (const void *KEY, void **ROOTP,
  2242. comparison_fn_t COMPAR)
  2243. Preliminary: | MT-Safe race:rootp | AS-Unsafe heap | AC-Unsafe
  2244. corrupt mem | *Note POSIX Safety Concepts::.
  2245. To remove a specific element matching KEY from the tree ‘tdelete’
  2246. can be used. It locates the matching element using the same method
  2247. as ‘tfind’. The corresponding element is then removed and a
  2248. pointer to the parent of the deleted node is returned by the
  2249. function. If there is no matching entry in the tree nothing can be
  2250. deleted and the function returns ‘NULL’. If the root of the tree
  2251. is deleted ‘tdelete’ returns some unspecified value not equal to
  2252. ‘NULL’.
  2253. -- Function: void tdestroy (void *VROOT, __free_fn_t FREEFCT)
  2254. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  2255. POSIX Safety Concepts::.
  2256. If the complete search tree has to be removed one can use
  2257. ‘tdestroy’. It frees all resources allocated by the ‘tsearch’
  2258. functions to generate the tree pointed to by VROOT.
  2259. For the data in each tree node the function FREEFCT is called. The
  2260. pointer to the data is passed as the argument to the function. If
  2261. no such work is necessary FREEFCT must point to a function doing
  2262. nothing. It is called in any case.
  2263. This function is a GNU extension and not covered by the System V or
  2264. X/Open specifications.
  2265. In addition to the functions to create and destroy the tree data
  2266. structure, there is another function which allows you to apply a
  2267. function to all elements of the tree. The function must have this type:
  2268. void __action_fn_t (const void *nodep, VISIT value, int level);
  2269. The NODEP is the data value of the current node (once given as the
  2270. KEY argument to ‘tsearch’). LEVEL is a numeric value which corresponds
  2271. to the depth of the current node in the tree. The root node has the
  2272. depth 0 and its children have a depth of 1 and so on. The ‘VISIT’ type
  2273. is an enumeration type.
  2274. -- Data Type: VISIT
  2275. The ‘VISIT’ value indicates the status of the current node in the
  2276. tree and how the function is called. The status of a node is
  2277. either ‘leaf’ or ‘internal node’. For each leaf node the function
  2278. is called exactly once, for each internal node it is called three
  2279. times: before the first child is processed, after the first child
  2280. is processed and after both children are processed. This makes it
  2281. possible to handle all three methods of tree traversal (or even a
  2282. combination of them).
  2283. ‘preorder’
  2284. The current node is an internal node and the function is
  2285. called before the first child was processed.
  2286. ‘postorder’
  2287. The current node is an internal node and the function is
  2288. called after the first child was processed.
  2289. ‘endorder’
  2290. The current node is an internal node and the function is
  2291. called after the second child was processed.
  2292. ‘leaf’
  2293. The current node is a leaf.
  2294. -- Function: void twalk (const void *ROOT, __action_fn_t ACTION)
  2295. Preliminary: | MT-Safe race:root | AS-Safe | AC-Safe | *Note POSIX
  2296. Safety Concepts::.
  2297. For each node in the tree with a node pointed to by ROOT, the
  2298. ‘twalk’ function calls the function provided by the parameter
  2299. ACTION. For leaf nodes the function is called exactly once with
  2300. VALUE set to ‘leaf’. For internal nodes the function is called
  2301. three times, setting the VALUE parameter or ACTION to the
  2302. appropriate value. The LEVEL argument for the ACTION function is
  2303. computed while descending the tree by increasing the value by one
  2304. for each descent to a child, starting with the value 0 for the root
  2305. node.
  2306. Since the functions used for the ACTION parameter to ‘twalk’ must
  2307. not modify the tree data, it is safe to run ‘twalk’ in more than
  2308. one thread at the same time, working on the same tree. It is also
  2309. safe to call ‘tfind’ in parallel. Functions which modify the tree
  2310. must not be used, otherwise the behavior is undefined.
  2311. 
  2312. File: libc.info, Node: Pattern Matching, Next: I/O Overview, Prev: Searching and Sorting, Up: Top
  2313. 10 Pattern Matching
  2314. *******************
  2315. The GNU C Library provides pattern matching facilities for two kinds of
  2316. patterns: regular expressions and file-name wildcards. The library also
  2317. provides a facility for expanding variable and command references and
  2318. parsing text into words in the way the shell does.
  2319. * Menu:
  2320. * Wildcard Matching:: Matching a wildcard pattern against a single string.
  2321. * Globbing:: Finding the files that match a wildcard pattern.
  2322. * Regular Expressions:: Matching regular expressions against strings.
  2323. * Word Expansion:: Expanding shell variables, nested commands,
  2324. arithmetic, and wildcards.
  2325. This is what the shell does with shell commands.
  2326. 
  2327. File: libc.info, Node: Wildcard Matching, Next: Globbing, Up: Pattern Matching
  2328. 10.1 Wildcard Matching
  2329. ======================
  2330. This section describes how to match a wildcard pattern against a
  2331. particular string. The result is a yes or no answer: does the string
  2332. fit the pattern or not. The symbols described here are all declared in
  2333. ‘fnmatch.h’.
  2334. -- Function: int fnmatch (const char *PATTERN, const char *STRING, int
  2335. FLAGS)
  2336. Preliminary: | MT-Safe env locale | AS-Unsafe heap | AC-Unsafe mem
  2337. | *Note POSIX Safety Concepts::.
  2338. This function tests whether the string STRING matches the pattern
  2339. PATTERN. It returns ‘0’ if they do match; otherwise, it returns
  2340. the nonzero value ‘FNM_NOMATCH’. The arguments PATTERN and STRING
  2341. are both strings.
  2342. The argument FLAGS is a combination of flag bits that alter the
  2343. details of matching. See below for a list of the defined flags.
  2344. In the GNU C Library, ‘fnmatch’ might sometimes report “errors” by
  2345. returning nonzero values that are not equal to ‘FNM_NOMATCH’.
  2346. These are the available flags for the FLAGS argument:
  2347. ‘FNM_FILE_NAME’
  2348. Treat the ‘/’ character specially, for matching file names. If
  2349. this flag is set, wildcard constructs in PATTERN cannot match ‘/’
  2350. in STRING. Thus, the only way to match ‘/’ is with an explicit ‘/’
  2351. in PATTERN.
  2352. ‘FNM_PATHNAME’
  2353. This is an alias for ‘FNM_FILE_NAME’; it comes from POSIX.2. We
  2354. don’t recommend this name because we don’t use the term “pathname”
  2355. for file names.
  2356. ‘FNM_PERIOD’
  2357. Treat the ‘.’ character specially if it appears at the beginning of
  2358. STRING. If this flag is set, wildcard constructs in PATTERN cannot
  2359. match ‘.’ as the first character of STRING.
  2360. If you set both ‘FNM_PERIOD’ and ‘FNM_FILE_NAME’, then the special
  2361. treatment applies to ‘.’ following ‘/’ as well as to ‘.’ at the
  2362. beginning of STRING. (The shell uses the ‘FNM_PERIOD’ and
  2363. ‘FNM_FILE_NAME’ flags together for matching file names.)
  2364. ‘FNM_NOESCAPE’
  2365. Don’t treat the ‘\’ character specially in patterns. Normally, ‘\’
  2366. quotes the following character, turning off its special meaning (if
  2367. any) so that it matches only itself. When quoting is enabled, the
  2368. pattern ‘\?’ matches only the string ‘?’, because the question mark
  2369. in the pattern acts like an ordinary character.
  2370. If you use ‘FNM_NOESCAPE’, then ‘\’ is an ordinary character.
  2371. ‘FNM_LEADING_DIR’
  2372. Ignore a trailing sequence of characters starting with a ‘/’ in
  2373. STRING; that is to say, test whether STRING starts with a directory
  2374. name that PATTERN matches.
  2375. If this flag is set, either ‘foo*’ or ‘foobar’ as a pattern would
  2376. match the string ‘foobar/frobozz’.
  2377. ‘FNM_CASEFOLD’
  2378. Ignore case in comparing STRING to PATTERN.
  2379. ‘FNM_EXTMATCH’
  2380. Besides the normal patterns, also recognize the extended patterns
  2381. introduced in ‘ksh’. The patterns are written in the form
  2382. explained in the following table where PATTERN-LIST is a ‘|’
  2383. separated list of patterns.
  2384. ‘?(PATTERN-LIST)’
  2385. The pattern matches if zero or one occurrences of any of the
  2386. patterns in the PATTERN-LIST allow matching the input string.
  2387. ‘*(PATTERN-LIST)’
  2388. The pattern matches if zero or more occurrences of any of the
  2389. patterns in the PATTERN-LIST allow matching the input string.
  2390. ‘+(PATTERN-LIST)’
  2391. The pattern matches if one or more occurrences of any of the
  2392. patterns in the PATTERN-LIST allow matching the input string.
  2393. ‘@(PATTERN-LIST)’
  2394. The pattern matches if exactly one occurrence of any of the
  2395. patterns in the PATTERN-LIST allows matching the input string.
  2396. ‘!(PATTERN-LIST)’
  2397. The pattern matches if the input string cannot be matched with
  2398. any of the patterns in the PATTERN-LIST.
  2399. 
  2400. File: libc.info, Node: Globbing, Next: Regular Expressions, Prev: Wildcard Matching, Up: Pattern Matching
  2401. 10.2 Globbing
  2402. =============
  2403. The archetypal use of wildcards is for matching against the files in a
  2404. directory, and making a list of all the matches. This is called
  2405. "globbing".
  2406. You could do this using ‘fnmatch’, by reading the directory entries
  2407. one by one and testing each one with ‘fnmatch’. But that would be slow
  2408. (and complex, since you would have to handle subdirectories by hand).
  2409. The library provides a function ‘glob’ to make this particular use of
  2410. wildcards convenient. ‘glob’ and the other symbols in this section are
  2411. declared in ‘glob.h’.
  2412. * Menu:
  2413. * Calling Glob:: Basic use of ‘glob’.
  2414. * Flags for Globbing:: Flags that enable various options in ‘glob’.
  2415. * More Flags for Globbing:: GNU specific extensions to ‘glob’.
  2416. 
  2417. File: libc.info, Node: Calling Glob, Next: Flags for Globbing, Up: Globbing
  2418. 10.2.1 Calling ‘glob’
  2419. ---------------------
  2420. The result of globbing is a vector of file names (strings). To return
  2421. this vector, ‘glob’ uses a special data type, ‘glob_t’, which is a
  2422. structure. You pass ‘glob’ the address of the structure, and it fills
  2423. in the structure’s fields to tell you about the results.
  2424. -- Data Type: glob_t
  2425. This data type holds a pointer to a word vector. More precisely,
  2426. it records both the address of the word vector and its size. The
  2427. GNU implementation contains some more fields which are non-standard
  2428. extensions.
  2429. ‘gl_pathc’
  2430. The number of elements in the vector, excluding the initial
  2431. null entries if the GLOB_DOOFFS flag is used (see gl_offs
  2432. below).
  2433. ‘gl_pathv’
  2434. The address of the vector. This field has type ‘char **’.
  2435. ‘gl_offs’
  2436. The offset of the first real element of the vector, from its
  2437. nominal address in the ‘gl_pathv’ field. Unlike the other
  2438. fields, this is always an input to ‘glob’, rather than an
  2439. output from it.
  2440. If you use a nonzero offset, then that many elements at the
  2441. beginning of the vector are left empty. (The ‘glob’ function
  2442. fills them with null pointers.)
  2443. The ‘gl_offs’ field is meaningful only if you use the
  2444. ‘GLOB_DOOFFS’ flag. Otherwise, the offset is always zero
  2445. regardless of what is in this field, and the first real
  2446. element comes at the beginning of the vector.
  2447. ‘gl_closedir’
  2448. The address of an alternative implementation of the ‘closedir’
  2449. function. It is used if the ‘GLOB_ALTDIRFUNC’ bit is set in
  2450. the flag parameter. The type of this field is
  2451. ‘void (*) (void *)’.
  2452. This is a GNU extension.
  2453. ‘gl_readdir’
  2454. The address of an alternative implementation of the ‘readdir’
  2455. function used to read the contents of a directory. It is used
  2456. if the ‘GLOB_ALTDIRFUNC’ bit is set in the flag parameter.
  2457. The type of this field is ‘struct dirent *(*) (void *)’.
  2458. An implementation of ‘gl_readdir’ needs to initialize the
  2459. following members of the ‘struct dirent’ object:
  2460. ‘d_type’
  2461. This member should be set to the file type of the entry
  2462. if it is known. Otherwise, the value ‘DT_UNKNOWN’ can be
  2463. used. The ‘glob’ function may use the specified file
  2464. type to avoid callbacks in cases where the file type
  2465. indicates that the data is not required.
  2466. ‘d_ino’
  2467. This member needs to be non-zero, otherwise ‘glob’ may
  2468. skip the current entry and call the ‘gl_readdir’ callback
  2469. function again to retrieve another entry.
  2470. ‘d_name’
  2471. This member must be set to the name of the entry. It
  2472. must be null-terminated.
  2473. The example below shows how to allocate a ‘struct dirent’
  2474. object containing a given name.
  2475. #include <dirent.h>
  2476. #include <errno.h>
  2477. #include <stddef.h>
  2478. #include <stdlib.h>
  2479. #include <string.h>
  2480. struct dirent *
  2481. mkdirent (const char *name)
  2482. {
  2483. size_t dirent_size = offsetof (struct dirent, d_name) + 1;
  2484. size_t name_length = strlen (name);
  2485. size_t total_size = dirent_size + name_length;
  2486. if (total_size < dirent_size)
  2487. {
  2488. errno = ENOMEM;
  2489. return NULL;
  2490. }
  2491. struct dirent *result = malloc (total_size);
  2492. if (result == NULL)
  2493. return NULL;
  2494. result->d_type = DT_UNKNOWN;
  2495. result->d_ino = 1; /* Do not skip this entry. */
  2496. memcpy (result->d_name, name, name_length + 1);
  2497. return result;
  2498. }
  2499. The ‘glob’ function reads the ‘struct dirent’ members listed
  2500. above and makes a copy of the file name in the ‘d_name’ member
  2501. immediately after the ‘gl_readdir’ callback function returns.
  2502. Future invocations of any of the callback functions may
  2503. dealloacte or reuse the buffer. It is the responsibility of
  2504. the caller of the ‘glob’ function to allocate and deallocate
  2505. the buffer, around the call to ‘glob’ or using the callback
  2506. functions. For example, an application could allocate the
  2507. buffer in the ‘gl_readdir’ callback function, and deallocate
  2508. it in the ‘gl_closedir’ callback function.
  2509. The ‘gl_readdir’ member is a GNU extension.
  2510. ‘gl_opendir’
  2511. The address of an alternative implementation of the ‘opendir’
  2512. function. It is used if the ‘GLOB_ALTDIRFUNC’ bit is set in
  2513. the flag parameter. The type of this field is
  2514. ‘void *(*) (const char *)’.
  2515. This is a GNU extension.
  2516. ‘gl_stat’
  2517. The address of an alternative implementation of the ‘stat’
  2518. function to get information about an object in the filesystem.
  2519. It is used if the ‘GLOB_ALTDIRFUNC’ bit is set in the flag
  2520. parameter. The type of this field is
  2521. ‘int (*) (const char *, struct stat *)’.
  2522. This is a GNU extension.
  2523. ‘gl_lstat’
  2524. The address of an alternative implementation of the ‘lstat’
  2525. function to get information about an object in the
  2526. filesystems, not following symbolic links. It is used if the
  2527. ‘GLOB_ALTDIRFUNC’ bit is set in the flag parameter. The type
  2528. of this field is ‘int (*) (const char *, struct stat *)’.
  2529. This is a GNU extension.
  2530. ‘gl_flags’
  2531. The flags used when ‘glob’ was called. In addition,
  2532. ‘GLOB_MAGCHAR’ might be set. See *note Flags for Globbing::
  2533. for more details.
  2534. This is a GNU extension.
  2535. For use in the ‘glob64’ function ‘glob.h’ contains another definition
  2536. for a very similar type. ‘glob64_t’ differs from ‘glob_t’ only in the
  2537. types of the members ‘gl_readdir’, ‘gl_stat’, and ‘gl_lstat’.
  2538. -- Data Type: glob64_t
  2539. This data type holds a pointer to a word vector. More precisely,
  2540. it records both the address of the word vector and its size. The
  2541. GNU implementation contains some more fields which are non-standard
  2542. extensions.
  2543. ‘gl_pathc’
  2544. The number of elements in the vector, excluding the initial
  2545. null entries if the GLOB_DOOFFS flag is used (see gl_offs
  2546. below).
  2547. ‘gl_pathv’
  2548. The address of the vector. This field has type ‘char **’.
  2549. ‘gl_offs’
  2550. The offset of the first real element of the vector, from its
  2551. nominal address in the ‘gl_pathv’ field. Unlike the other
  2552. fields, this is always an input to ‘glob’, rather than an
  2553. output from it.
  2554. If you use a nonzero offset, then that many elements at the
  2555. beginning of the vector are left empty. (The ‘glob’ function
  2556. fills them with null pointers.)
  2557. The ‘gl_offs’ field is meaningful only if you use the
  2558. ‘GLOB_DOOFFS’ flag. Otherwise, the offset is always zero
  2559. regardless of what is in this field, and the first real
  2560. element comes at the beginning of the vector.
  2561. ‘gl_closedir’
  2562. The address of an alternative implementation of the ‘closedir’
  2563. function. It is used if the ‘GLOB_ALTDIRFUNC’ bit is set in
  2564. the flag parameter. The type of this field is
  2565. ‘void (*) (void *)’.
  2566. This is a GNU extension.
  2567. ‘gl_readdir’
  2568. The address of an alternative implementation of the
  2569. ‘readdir64’ function used to read the contents of a directory.
  2570. It is used if the ‘GLOB_ALTDIRFUNC’ bit is set in the flag
  2571. parameter. The type of this field is
  2572. ‘struct dirent64 *(*) (void *)’.
  2573. This is a GNU extension.
  2574. ‘gl_opendir’
  2575. The address of an alternative implementation of the ‘opendir’
  2576. function. It is used if the ‘GLOB_ALTDIRFUNC’ bit is set in
  2577. the flag parameter. The type of this field is
  2578. ‘void *(*) (const char *)’.
  2579. This is a GNU extension.
  2580. ‘gl_stat’
  2581. The address of an alternative implementation of the ‘stat64’
  2582. function to get information about an object in the filesystem.
  2583. It is used if the ‘GLOB_ALTDIRFUNC’ bit is set in the flag
  2584. parameter. The type of this field is
  2585. ‘int (*) (const char *, struct stat64 *)’.
  2586. This is a GNU extension.
  2587. ‘gl_lstat’
  2588. The address of an alternative implementation of the ‘lstat64’
  2589. function to get information about an object in the
  2590. filesystems, not following symbolic links. It is used if the
  2591. ‘GLOB_ALTDIRFUNC’ bit is set in the flag parameter. The type
  2592. of this field is ‘int (*) (const char *, struct stat64 *)’.
  2593. This is a GNU extension.
  2594. ‘gl_flags’
  2595. The flags used when ‘glob’ was called. In addition,
  2596. ‘GLOB_MAGCHAR’ might be set. See *note Flags for Globbing::
  2597. for more details.
  2598. This is a GNU extension.
  2599. -- Function: int glob (const char *PATTERN, int FLAGS, int (*ERRFUNC)
  2600. (const char *FILENAME, int ERROR-CODE), glob_t *VECTOR-PTR)
  2601. Preliminary: | MT-Unsafe race:utent env sig:ALRM timer locale |
  2602. AS-Unsafe dlopen plugin corrupt heap lock | AC-Unsafe corrupt lock
  2603. fd mem | *Note POSIX Safety Concepts::.
  2604. The function ‘glob’ does globbing using the pattern PATTERN in the
  2605. current directory. It puts the result in a newly allocated vector,
  2606. and stores the size and address of this vector into ‘*VECTOR-PTR’.
  2607. The argument FLAGS is a combination of bit flags; see *note Flags
  2608. for Globbing::, for details of the flags.
  2609. The result of globbing is a sequence of file names. The function
  2610. ‘glob’ allocates a string for each resulting word, then allocates a
  2611. vector of type ‘char **’ to store the addresses of these strings.
  2612. The last element of the vector is a null pointer. This vector is
  2613. called the "word vector".
  2614. To return this vector, ‘glob’ stores both its address and its
  2615. length (number of elements, not counting the terminating null
  2616. pointer) into ‘*VECTOR-PTR’.
  2617. Normally, ‘glob’ sorts the file names alphabetically before
  2618. returning them. You can turn this off with the flag ‘GLOB_NOSORT’
  2619. if you want to get the information as fast as possible. Usually
  2620. it’s a good idea to let ‘glob’ sort them—if you process the files
  2621. in alphabetical order, the users will have a feel for the rate of
  2622. progress that your application is making.
  2623. If ‘glob’ succeeds, it returns 0. Otherwise, it returns one of
  2624. these error codes:
  2625. ‘GLOB_ABORTED’
  2626. There was an error opening a directory, and you used the flag
  2627. ‘GLOB_ERR’ or your specified ERRFUNC returned a nonzero value.
  2628. *Note Flags for Globbing::, for an explanation of the
  2629. ‘GLOB_ERR’ flag and ERRFUNC.
  2630. ‘GLOB_NOMATCH’
  2631. The pattern didn’t match any existing files. If you use the
  2632. ‘GLOB_NOCHECK’ flag, then you never get this error code,
  2633. because that flag tells ‘glob’ to _pretend_ that the pattern
  2634. matched at least one file.
  2635. ‘GLOB_NOSPACE’
  2636. It was impossible to allocate memory to hold the result.
  2637. In the event of an error, ‘glob’ stores information in
  2638. ‘*VECTOR-PTR’ about all the matches it has found so far.
  2639. It is important to notice that the ‘glob’ function will not fail if
  2640. it encounters directories or files which cannot be handled without
  2641. the LFS interfaces. The implementation of ‘glob’ is supposed to
  2642. use these functions internally. This at least is the assumption
  2643. made by the Unix standard. The GNU extension of allowing the user
  2644. to provide their own directory handling and ‘stat’ functions
  2645. complicates things a bit. If these callback functions are used and
  2646. a large file or directory is encountered ‘glob’ _can_ fail.
  2647. -- Function: int glob64 (const char *PATTERN, int FLAGS, int (*ERRFUNC)
  2648. (const char *FILENAME, int ERROR-CODE), glob64_t *VECTOR-PTR)
  2649. Preliminary: | MT-Unsafe race:utent env sig:ALRM timer locale |
  2650. AS-Unsafe dlopen corrupt heap lock | AC-Unsafe corrupt lock fd mem
  2651. | *Note POSIX Safety Concepts::.
  2652. The ‘glob64’ function was added as part of the Large File Summit
  2653. extensions but is not part of the original LFS proposal. The
  2654. reason for this is simple: it is not necessary. The necessity for
  2655. a ‘glob64’ function is added by the extensions of the GNU ‘glob’
  2656. implementation which allows the user to provide their own directory
  2657. handling and ‘stat’ functions. The ‘readdir’ and ‘stat’ functions
  2658. do depend on the choice of ‘_FILE_OFFSET_BITS’ since the definition
  2659. of the types ‘struct dirent’ and ‘struct stat’ will change
  2660. depending on the choice.
  2661. Besides this difference, ‘glob64’ works just like ‘glob’ in all
  2662. aspects.
  2663. This function is a GNU extension.
  2664. 
  2665. File: libc.info, Node: Flags for Globbing, Next: More Flags for Globbing, Prev: Calling Glob, Up: Globbing
  2666. 10.2.2 Flags for Globbing
  2667. -------------------------
  2668. This section describes the standard flags that you can specify in the
  2669. FLAGS argument to ‘glob’. Choose the flags you want, and combine them
  2670. with the C bitwise OR operator ‘|’.
  2671. Note that there are *note More Flags for Globbing:: available as GNU
  2672. extensions.
  2673. ‘GLOB_APPEND’
  2674. Append the words from this expansion to the vector of words
  2675. produced by previous calls to ‘glob’. This way you can effectively
  2676. expand several words as if they were concatenated with spaces
  2677. between them.
  2678. In order for appending to work, you must not modify the contents of
  2679. the word vector structure between calls to ‘glob’. And, if you set
  2680. ‘GLOB_DOOFFS’ in the first call to ‘glob’, you must also set it
  2681. when you append to the results.
  2682. Note that the pointer stored in ‘gl_pathv’ may no longer be valid
  2683. after you call ‘glob’ the second time, because ‘glob’ might have
  2684. relocated the vector. So always fetch ‘gl_pathv’ from the ‘glob_t’
  2685. structure after each ‘glob’ call; *never* save the pointer across
  2686. calls.
  2687. ‘GLOB_DOOFFS’
  2688. Leave blank slots at the beginning of the vector of words. The
  2689. ‘gl_offs’ field says how many slots to leave. The blank slots
  2690. contain null pointers.
  2691. ‘GLOB_ERR’
  2692. Give up right away and report an error if there is any difficulty
  2693. reading the directories that must be read in order to expand
  2694. PATTERN fully. Such difficulties might include a directory in
  2695. which you don’t have the requisite access. Normally, ‘glob’ tries
  2696. its best to keep on going despite any errors, reading whatever
  2697. directories it can.
  2698. You can exercise even more control than this by specifying an
  2699. error-handler function ERRFUNC when you call ‘glob’. If ERRFUNC is
  2700. not a null pointer, then ‘glob’ doesn’t give up right away when it
  2701. can’t read a directory; instead, it calls ERRFUNC with two
  2702. arguments, like this:
  2703. (*ERRFUNC) (FILENAME, ERROR-CODE)
  2704. The argument FILENAME is the name of the directory that ‘glob’
  2705. couldn’t open or couldn’t read, and ERROR-CODE is the ‘errno’ value
  2706. that was reported to ‘glob’.
  2707. If the error handler function returns nonzero, then ‘glob’ gives up
  2708. right away. Otherwise, it continues.
  2709. ‘GLOB_MARK’
  2710. If the pattern matches the name of a directory, append ‘/’ to the
  2711. directory’s name when returning it.
  2712. ‘GLOB_NOCHECK’
  2713. If the pattern doesn’t match any file names, return the pattern
  2714. itself as if it were a file name that had been matched. (Normally,
  2715. when the pattern doesn’t match anything, ‘glob’ returns that there
  2716. were no matches.)
  2717. ‘GLOB_NOESCAPE’
  2718. Don’t treat the ‘\’ character specially in patterns. Normally, ‘\’
  2719. quotes the following character, turning off its special meaning (if
  2720. any) so that it matches only itself. When quoting is enabled, the
  2721. pattern ‘\?’ matches only the string ‘?’, because the question mark
  2722. in the pattern acts like an ordinary character.
  2723. If you use ‘GLOB_NOESCAPE’, then ‘\’ is an ordinary character.
  2724. ‘glob’ does its work by calling the function ‘fnmatch’ repeatedly.
  2725. It handles the flag ‘GLOB_NOESCAPE’ by turning on the
  2726. ‘FNM_NOESCAPE’ flag in calls to ‘fnmatch’.
  2727. ‘GLOB_NOSORT’
  2728. Don’t sort the file names; return them in no particular order. (In
  2729. practice, the order will depend on the order of the entries in the
  2730. directory.) The only reason _not_ to sort is to save time.
  2731. 
  2732. File: libc.info, Node: More Flags for Globbing, Prev: Flags for Globbing, Up: Globbing
  2733. 10.2.3 More Flags for Globbing
  2734. ------------------------------
  2735. Beside the flags described in the last section, the GNU implementation
  2736. of ‘glob’ allows a few more flags which are also defined in the ‘glob.h’
  2737. file. Some of the extensions implement functionality which is available
  2738. in modern shell implementations.
  2739. ‘GLOB_PERIOD’
  2740. The ‘.’ character (period) is treated special. It cannot be
  2741. matched by wildcards. *Note Wildcard Matching::, ‘FNM_PERIOD’.
  2742. ‘GLOB_MAGCHAR’
  2743. The ‘GLOB_MAGCHAR’ value is not to be given to ‘glob’ in the FLAGS
  2744. parameter. Instead, ‘glob’ sets this bit in the GL_FLAGS element
  2745. of the GLOB_T structure provided as the result if the pattern used
  2746. for matching contains any wildcard character.
  2747. ‘GLOB_ALTDIRFUNC’
  2748. Instead of using the normal functions for accessing the filesystem
  2749. the ‘glob’ implementation uses the user-supplied functions
  2750. specified in the structure pointed to by PGLOB parameter. For more
  2751. information about the functions refer to the sections about
  2752. directory handling see *note Accessing Directories::, and *note
  2753. Reading Attributes::.
  2754. ‘GLOB_BRACE’
  2755. If this flag is given, the handling of braces in the pattern is
  2756. changed. It is now required that braces appear correctly grouped.
  2757. I.e., for each opening brace there must be a closing one. Braces
  2758. can be used recursively. So it is possible to define one brace
  2759. expression in another one. It is important to note that the range
  2760. of each brace expression is completely contained in the outer brace
  2761. expression (if there is one).
  2762. The string between the matching braces is separated into single
  2763. expressions by splitting at ‘,’ (comma) characters. The commas
  2764. themselves are discarded. Please note what we said above about
  2765. recursive brace expressions. The commas used to separate the
  2766. subexpressions must be at the same level. Commas in brace
  2767. subexpressions are not matched. They are used during expansion of
  2768. the brace expression of the deeper level. The example below shows
  2769. this
  2770. glob ("{foo/{,bar,biz},baz}", GLOB_BRACE, NULL, &result)
  2771. is equivalent to the sequence
  2772. glob ("foo/", GLOB_BRACE, NULL, &result)
  2773. glob ("foo/bar", GLOB_BRACE|GLOB_APPEND, NULL, &result)
  2774. glob ("foo/biz", GLOB_BRACE|GLOB_APPEND, NULL, &result)
  2775. glob ("baz", GLOB_BRACE|GLOB_APPEND, NULL, &result)
  2776. if we leave aside error handling.
  2777. ‘GLOB_NOMAGIC’
  2778. If the pattern contains no wildcard constructs (it is a literal
  2779. file name), return it as the sole “matching” word, even if no file
  2780. exists by that name.
  2781. ‘GLOB_TILDE’
  2782. If this flag is used the character ‘~’ (tilde) is handled specially
  2783. if it appears at the beginning of the pattern. Instead of being
  2784. taken verbatim it is used to represent the home directory of a
  2785. known user.
  2786. If ‘~’ is the only character in pattern or it is followed by a ‘/’
  2787. (slash), the home directory of the process owner is substituted.
  2788. Using ‘getlogin’ and ‘getpwnam’ the information is read from the
  2789. system databases. As an example take user ‘bart’ with his home
  2790. directory at ‘/home/bart’. For him a call like
  2791. glob ("~/bin/*", GLOB_TILDE, NULL, &result)
  2792. would return the contents of the directory ‘/home/bart/bin’.
  2793. Instead of referring to the own home directory it is also possible
  2794. to name the home directory of other users. To do so one has to
  2795. append the user name after the tilde character. So the contents of
  2796. user ‘homer’’s ‘bin’ directory can be retrieved by
  2797. glob ("~homer/bin/*", GLOB_TILDE, NULL, &result)
  2798. If the user name is not valid or the home directory cannot be
  2799. determined for some reason the pattern is left untouched and itself
  2800. used as the result. I.e., if in the last example ‘home’ is not
  2801. available the tilde expansion yields to ‘"~homer/bin/*"’ and ‘glob’
  2802. is not looking for a directory named ‘~homer’.
  2803. This functionality is equivalent to what is available in C-shells
  2804. if the ‘nonomatch’ flag is set.
  2805. ‘GLOB_TILDE_CHECK’
  2806. If this flag is used ‘glob’ behaves as if ‘GLOB_TILDE’ is given.
  2807. The only difference is that if the user name is not available or
  2808. the home directory cannot be determined for other reasons this
  2809. leads to an error. ‘glob’ will return ‘GLOB_NOMATCH’ instead of
  2810. using the pattern itself as the name.
  2811. This functionality is equivalent to what is available in C-shells
  2812. if the ‘nonomatch’ flag is not set.
  2813. ‘GLOB_ONLYDIR’
  2814. If this flag is used the globbing function takes this as a *hint*
  2815. that the caller is only interested in directories matching the
  2816. pattern. If the information about the type of the file is easily
  2817. available non-directories will be rejected but no extra work will
  2818. be done to determine the information for each file. I.e., the
  2819. caller must still be able to filter directories out.
  2820. This functionality is only available with the GNU ‘glob’
  2821. implementation. It is mainly used internally to increase the
  2822. performance but might be useful for a user as well and therefore is
  2823. documented here.
  2824. Calling ‘glob’ will in most cases allocate resources which are used
  2825. to represent the result of the function call. If the same object of
  2826. type ‘glob_t’ is used in multiple call to ‘glob’ the resources are freed
  2827. or reused so that no leaks appear. But this does not include the time
  2828. when all ‘glob’ calls are done.
  2829. -- Function: void globfree (glob_t *PGLOB)
  2830. Preliminary: | MT-Safe | AS-Unsafe corrupt heap | AC-Unsafe corrupt
  2831. mem | *Note POSIX Safety Concepts::.
  2832. The ‘globfree’ function frees all resources allocated by previous
  2833. calls to ‘glob’ associated with the object pointed to by PGLOB.
  2834. This function should be called whenever the currently used ‘glob_t’
  2835. typed object isn’t used anymore.
  2836. -- Function: void globfree64 (glob64_t *PGLOB)
  2837. Preliminary: | MT-Safe | AS-Unsafe corrupt lock | AC-Unsafe corrupt
  2838. lock fd mem | *Note POSIX Safety Concepts::.
  2839. This function is equivalent to ‘globfree’ but it frees records of
  2840. type ‘glob64_t’ which were allocated by ‘glob64’.
  2841. 
  2842. File: libc.info, Node: Regular Expressions, Next: Word Expansion, Prev: Globbing, Up: Pattern Matching
  2843. 10.3 Regular Expression Matching
  2844. ================================
  2845. The GNU C Library supports two interfaces for matching regular
  2846. expressions. One is the standard POSIX.2 interface, and the other is
  2847. what the GNU C Library has had for many years.
  2848. Both interfaces are declared in the header file ‘regex.h’. If you
  2849. define ‘_POSIX_C_SOURCE’, then only the POSIX.2 functions, structures,
  2850. and constants are declared.
  2851. * Menu:
  2852. * POSIX Regexp Compilation:: Using ‘regcomp’ to prepare to match.
  2853. * Flags for POSIX Regexps:: Syntax variations for ‘regcomp’.
  2854. * Matching POSIX Regexps:: Using ‘regexec’ to match the compiled
  2855. pattern that you get from ‘regcomp’.
  2856. * Regexp Subexpressions:: Finding which parts of the string were matched.
  2857. * Subexpression Complications:: Find points of which parts were matched.
  2858. * Regexp Cleanup:: Freeing storage; reporting errors.
  2859. 
  2860. File: libc.info, Node: POSIX Regexp Compilation, Next: Flags for POSIX Regexps, Up: Regular Expressions
  2861. 10.3.1 POSIX Regular Expression Compilation
  2862. -------------------------------------------
  2863. Before you can actually match a regular expression, you must "compile"
  2864. it. This is not true compilation—it produces a special data structure,
  2865. not machine instructions. But it is like ordinary compilation in that
  2866. its purpose is to enable you to “execute” the pattern fast. (*Note
  2867. Matching POSIX Regexps::, for how to use the compiled regular expression
  2868. for matching.)
  2869. There is a special data type for compiled regular expressions:
  2870. -- Data Type: regex_t
  2871. This type of object holds a compiled regular expression. It is
  2872. actually a structure. It has just one field that your programs
  2873. should look at:
  2874. ‘re_nsub’
  2875. This field holds the number of parenthetical subexpressions in
  2876. the regular expression that was compiled.
  2877. There are several other fields, but we don’t describe them here,
  2878. because only the functions in the library should use them.
  2879. After you create a ‘regex_t’ object, you can compile a regular
  2880. expression into it by calling ‘regcomp’.
  2881. -- Function: int regcomp (regex_t *restrict COMPILED, const char
  2882. *restrict PATTERN, int CFLAGS)
  2883. Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap lock dlopen
  2884. | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
  2885. The function ‘regcomp’ “compiles” a regular expression into a data
  2886. structure that you can use with ‘regexec’ to match against a
  2887. string. The compiled regular expression format is designed for
  2888. efficient matching. ‘regcomp’ stores it into ‘*COMPILED’.
  2889. It’s up to you to allocate an object of type ‘regex_t’ and pass its
  2890. address to ‘regcomp’.
  2891. The argument CFLAGS lets you specify various options that control
  2892. the syntax and semantics of regular expressions. *Note Flags for
  2893. POSIX Regexps::.
  2894. If you use the flag ‘REG_NOSUB’, then ‘regcomp’ omits from the
  2895. compiled regular expression the information necessary to record how
  2896. subexpressions actually match. In this case, you might as well
  2897. pass ‘0’ for the MATCHPTR and NMATCH arguments when you call
  2898. ‘regexec’.
  2899. If you don’t use ‘REG_NOSUB’, then the compiled regular expression
  2900. does have the capacity to record how subexpressions match. Also,
  2901. ‘regcomp’ tells you how many subexpressions PATTERN has, by storing
  2902. the number in ‘COMPILED->re_nsub’. You can use that value to
  2903. decide how long an array to allocate to hold information about
  2904. subexpression matches.
  2905. ‘regcomp’ returns ‘0’ if it succeeds in compiling the regular
  2906. expression; otherwise, it returns a nonzero error code (see the
  2907. table below). You can use ‘regerror’ to produce an error message
  2908. string describing the reason for a nonzero value; see *note Regexp
  2909. Cleanup::.
  2910. Here are the possible nonzero values that ‘regcomp’ can return:
  2911. ‘REG_BADBR’
  2912. There was an invalid ‘\{…\}’ construct in the regular expression.
  2913. A valid ‘\{…\}’ construct must contain either a single number, or
  2914. two numbers in increasing order separated by a comma.
  2915. ‘REG_BADPAT’
  2916. There was a syntax error in the regular expression.
  2917. ‘REG_BADRPT’
  2918. A repetition operator such as ‘?’ or ‘*’ appeared in a bad position
  2919. (with no preceding subexpression to act on).
  2920. ‘REG_ECOLLATE’
  2921. The regular expression referred to an invalid collating element
  2922. (one not defined in the current locale for string collation).
  2923. *Note Locale Categories::.
  2924. ‘REG_ECTYPE’
  2925. The regular expression referred to an invalid character class name.
  2926. ‘REG_EESCAPE’
  2927. The regular expression ended with ‘\’.
  2928. ‘REG_ESUBREG’
  2929. There was an invalid number in the ‘\DIGIT’ construct.
  2930. ‘REG_EBRACK’
  2931. There were unbalanced square brackets in the regular expression.
  2932. ‘REG_EPAREN’
  2933. An extended regular expression had unbalanced parentheses, or a
  2934. basic regular expression had unbalanced ‘\(’ and ‘\)’.
  2935. ‘REG_EBRACE’
  2936. The regular expression had unbalanced ‘\{’ and ‘\}’.
  2937. ‘REG_ERANGE’
  2938. One of the endpoints in a range expression was invalid.
  2939. ‘REG_ESPACE’
  2940. ‘regcomp’ ran out of memory.
  2941. 
  2942. File: libc.info, Node: Flags for POSIX Regexps, Next: Matching POSIX Regexps, Prev: POSIX Regexp Compilation, Up: Regular Expressions
  2943. 10.3.2 Flags for POSIX Regular Expressions
  2944. ------------------------------------------
  2945. These are the bit flags that you can use in the CFLAGS operand when
  2946. compiling a regular expression with ‘regcomp’.
  2947. ‘REG_EXTENDED’
  2948. Treat the pattern as an extended regular expression, rather than as
  2949. a basic regular expression.
  2950. ‘REG_ICASE’
  2951. Ignore case when matching letters.
  2952. ‘REG_NOSUB’
  2953. Don’t bother storing the contents of the MATCHPTR array.
  2954. ‘REG_NEWLINE’
  2955. Treat a newline in STRING as dividing STRING into multiple lines,
  2956. so that ‘$’ can match before the newline and ‘^’ can match after.
  2957. Also, don’t permit ‘.’ to match a newline, and don’t permit ‘[^…]’
  2958. to match a newline.
  2959. Otherwise, newline acts like any other ordinary character.
  2960. 
  2961. File: libc.info, Node: Matching POSIX Regexps, Next: Regexp Subexpressions, Prev: Flags for POSIX Regexps, Up: Regular Expressions
  2962. 10.3.3 Matching a Compiled POSIX Regular Expression
  2963. ---------------------------------------------------
  2964. Once you have compiled a regular expression, as described in *note POSIX
  2965. Regexp Compilation::, you can match it against strings using ‘regexec’.
  2966. A match anywhere inside the string counts as success, unless the regular
  2967. expression contains anchor characters (‘^’ or ‘$’).
  2968. -- Function: int regexec (const regex_t *restrict COMPILED, const char
  2969. *restrict STRING, size_t NMATCH, regmatch_t
  2970. MATCHPTR[restrict], int EFLAGS)
  2971. Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap lock dlopen
  2972. | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety Concepts::.
  2973. This function tries to match the compiled regular expression
  2974. ‘*COMPILED’ against STRING.
  2975. ‘regexec’ returns ‘0’ if the regular expression matches; otherwise,
  2976. it returns a nonzero value. See the table below for what nonzero
  2977. values mean. You can use ‘regerror’ to produce an error message
  2978. string describing the reason for a nonzero value; see *note Regexp
  2979. Cleanup::.
  2980. The argument EFLAGS is a word of bit flags that enable various
  2981. options.
  2982. If you want to get information about what part of STRING actually
  2983. matched the regular expression or its subexpressions, use the
  2984. arguments MATCHPTR and NMATCH. Otherwise, pass ‘0’ for NMATCH, and
  2985. ‘NULL’ for MATCHPTR. *Note Regexp Subexpressions::.
  2986. You must match the regular expression with the same set of current
  2987. locales that were in effect when you compiled the regular expression.
  2988. The function ‘regexec’ accepts the following flags in the EFLAGS
  2989. argument:
  2990. ‘REG_NOTBOL’
  2991. Do not regard the beginning of the specified string as the
  2992. beginning of a line; more generally, don’t make any assumptions
  2993. about what text might precede it.
  2994. ‘REG_NOTEOL’
  2995. Do not regard the end of the specified string as the end of a line;
  2996. more generally, don’t make any assumptions about what text might
  2997. follow it.
  2998. Here are the possible nonzero values that ‘regexec’ can return:
  2999. ‘REG_NOMATCH’
  3000. The pattern didn’t match the string. This isn’t really an error.
  3001. ‘REG_ESPACE’
  3002. ‘regexec’ ran out of memory.
  3003. 
  3004. File: libc.info, Node: Regexp Subexpressions, Next: Subexpression Complications, Prev: Matching POSIX Regexps, Up: Regular Expressions
  3005. 10.3.4 Match Results with Subexpressions
  3006. ----------------------------------------
  3007. When ‘regexec’ matches parenthetical subexpressions of PATTERN, it
  3008. records which parts of STRING they match. It returns that information
  3009. by storing the offsets into an array whose elements are structures of
  3010. type ‘regmatch_t’. The first element of the array (index ‘0’) records
  3011. the part of the string that matched the entire regular expression. Each
  3012. other element of the array records the beginning and end of the part
  3013. that matched a single parenthetical subexpression.
  3014. -- Data Type: regmatch_t
  3015. This is the data type of the MATCHPTR array that you pass to
  3016. ‘regexec’. It contains two structure fields, as follows:
  3017. ‘rm_so’
  3018. The offset in STRING of the beginning of a substring. Add
  3019. this value to STRING to get the address of that part.
  3020. ‘rm_eo’
  3021. The offset in STRING of the end of the substring.
  3022. -- Data Type: regoff_t
  3023. ‘regoff_t’ is an alias for another signed integer type. The fields
  3024. of ‘regmatch_t’ have type ‘regoff_t’.
  3025. The ‘regmatch_t’ elements correspond to subexpressions positionally;
  3026. the first element (index ‘1’) records where the first subexpression
  3027. matched, the second element records the second subexpression, and so on.
  3028. The order of the subexpressions is the order in which they begin.
  3029. When you call ‘regexec’, you specify how long the MATCHPTR array is,
  3030. with the NMATCH argument. This tells ‘regexec’ how many elements to
  3031. store. If the actual regular expression has more than NMATCH
  3032. subexpressions, then you won’t get offset information about the rest of
  3033. them. But this doesn’t alter whether the pattern matches a particular
  3034. string or not.
  3035. If you don’t want ‘regexec’ to return any information about where the
  3036. subexpressions matched, you can either supply ‘0’ for NMATCH, or use the
  3037. flag ‘REG_NOSUB’ when you compile the pattern with ‘regcomp’.
  3038. 
  3039. File: libc.info, Node: Subexpression Complications, Next: Regexp Cleanup, Prev: Regexp Subexpressions, Up: Regular Expressions
  3040. 10.3.5 Complications in Subexpression Matching
  3041. ----------------------------------------------
  3042. Sometimes a subexpression matches a substring of no characters. This
  3043. happens when ‘f\(o*\)’ matches the string ‘fum’. (It really matches
  3044. just the ‘f’.) In this case, both of the offsets identify the point in
  3045. the string where the null substring was found. In this example, the
  3046. offsets are both ‘1’.
  3047. Sometimes the entire regular expression can match without using some
  3048. of its subexpressions at all—for example, when ‘ba\(na\)*’ matches the
  3049. string ‘ba’, the parenthetical subexpression is not used. When this
  3050. happens, ‘regexec’ stores ‘-1’ in both fields of the element for that
  3051. subexpression.
  3052. Sometimes matching the entire regular expression can match a
  3053. particular subexpression more than once—for example, when ‘ba\(na\)*’
  3054. matches the string ‘bananana’, the parenthetical subexpression matches
  3055. three times. When this happens, ‘regexec’ usually stores the offsets of
  3056. the last part of the string that matched the subexpression. In the case
  3057. of ‘bananana’, these offsets are ‘6’ and ‘8’.
  3058. But the last match is not always the one that is chosen. It’s more
  3059. accurate to say that the last _opportunity_ to match is the one that
  3060. takes precedence. What this means is that when one subexpression
  3061. appears within another, then the results reported for the inner
  3062. subexpression reflect whatever happened on the last match of the outer
  3063. subexpression. For an example, consider ‘\(ba\(na\)*s \)*’ matching the
  3064. string ‘bananas bas ’. The last time the inner expression actually
  3065. matches is near the end of the first word. But it is _considered_ again
  3066. in the second word, and fails to match there. ‘regexec’ reports nonuse
  3067. of the “na” subexpression.
  3068. Another place where this rule applies is when the regular expression
  3069. \(ba\(na\)*s \|nefer\(ti\)* \)*
  3070. matches ‘bananas nefertiti’. The “na” subexpression does match in the
  3071. first word, but it doesn’t match in the second word because the other
  3072. alternative is used there. Once again, the second repetition of the
  3073. outer subexpression overrides the first, and within that second
  3074. repetition, the “na” subexpression is not used. So ‘regexec’ reports
  3075. nonuse of the “na” subexpression.
  3076. 
  3077. File: libc.info, Node: Regexp Cleanup, Prev: Subexpression Complications, Up: Regular Expressions
  3078. 10.3.6 POSIX Regexp Matching Cleanup
  3079. ------------------------------------
  3080. When you are finished using a compiled regular expression, you can free
  3081. the storage it uses by calling ‘regfree’.
  3082. -- Function: void regfree (regex_t *COMPILED)
  3083. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  3084. POSIX Safety Concepts::.
  3085. Calling ‘regfree’ frees all the storage that ‘*COMPILED’ points to.
  3086. This includes various internal fields of the ‘regex_t’ structure
  3087. that aren’t documented in this manual.
  3088. ‘regfree’ does not free the object ‘*COMPILED’ itself.
  3089. You should always free the space in a ‘regex_t’ structure with
  3090. ‘regfree’ before using the structure to compile another regular
  3091. expression.
  3092. When ‘regcomp’ or ‘regexec’ reports an error, you can use the
  3093. function ‘regerror’ to turn it into an error message string.
  3094. -- Function: size_t regerror (int ERRCODE, const regex_t *restrict
  3095. COMPILED, char *restrict BUFFER, size_t LENGTH)
  3096. Preliminary: | MT-Safe env | AS-Unsafe corrupt heap lock dlopen |
  3097. AC-Unsafe corrupt lock fd mem | *Note POSIX Safety Concepts::.
  3098. This function produces an error message string for the error code
  3099. ERRCODE, and stores the string in LENGTH bytes of memory starting
  3100. at BUFFER. For the COMPILED argument, supply the same compiled
  3101. regular expression structure that ‘regcomp’ or ‘regexec’ was
  3102. working with when it got the error. Alternatively, you can supply
  3103. ‘NULL’ for COMPILED; you will still get a meaningful error message,
  3104. but it might not be as detailed.
  3105. If the error message can’t fit in LENGTH bytes (including a
  3106. terminating null character), then ‘regerror’ truncates it. The
  3107. string that ‘regerror’ stores is always null-terminated even if it
  3108. has been truncated.
  3109. The return value of ‘regerror’ is the minimum length needed to
  3110. store the entire error message. If this is less than LENGTH, then
  3111. the error message was not truncated, and you can use it.
  3112. Otherwise, you should call ‘regerror’ again with a larger buffer.
  3113. Here is a function which uses ‘regerror’, but always dynamically
  3114. allocates a buffer for the error message:
  3115. char *get_regerror (int errcode, regex_t *compiled)
  3116. {
  3117. size_t length = regerror (errcode, compiled, NULL, 0);
  3118. char *buffer = xmalloc (length);
  3119. (void) regerror (errcode, compiled, buffer, length);
  3120. return buffer;
  3121. }
  3122. 
  3123. File: libc.info, Node: Word Expansion, Prev: Regular Expressions, Up: Pattern Matching
  3124. 10.4 Shell-Style Word Expansion
  3125. ===============================
  3126. "Word expansion" means the process of splitting a string into "words"
  3127. and substituting for variables, commands, and wildcards just as the
  3128. shell does.
  3129. For example, when you write ‘ls -l foo.c’, this string is split into
  3130. three separate words—‘ls’, ‘-l’ and ‘foo.c’. This is the most basic
  3131. function of word expansion.
  3132. When you write ‘ls *.c’, this can become many words, because the word
  3133. ‘*.c’ can be replaced with any number of file names. This is called
  3134. "wildcard expansion", and it is also a part of word expansion.
  3135. When you use ‘echo $PATH’ to print your path, you are taking
  3136. advantage of "variable substitution", which is also part of word
  3137. expansion.
  3138. Ordinary programs can perform word expansion just like the shell by
  3139. calling the library function ‘wordexp’.
  3140. * Menu:
  3141. * Expansion Stages:: What word expansion does to a string.
  3142. * Calling Wordexp:: How to call ‘wordexp’.
  3143. * Flags for Wordexp:: Options you can enable in ‘wordexp’.
  3144. * Wordexp Example:: A sample program that does word expansion.
  3145. * Tilde Expansion:: Details of how tilde expansion works.
  3146. * Variable Substitution:: Different types of variable substitution.
  3147. 
  3148. File: libc.info, Node: Expansion Stages, Next: Calling Wordexp, Up: Word Expansion
  3149. 10.4.1 The Stages of Word Expansion
  3150. -----------------------------------
  3151. When word expansion is applied to a sequence of words, it performs the
  3152. following transformations in the order shown here:
  3153. 1. "Tilde expansion": Replacement of ‘~foo’ with the name of the home
  3154. directory of ‘foo’.
  3155. 2. Next, three different transformations are applied in the same step,
  3156. from left to right:
  3157. • "Variable substitution": Environment variables are substituted
  3158. for references such as ‘$foo’.
  3159. • "Command substitution": Constructs such as ‘`cat foo`’ and the
  3160. equivalent ‘$(cat foo)’ are replaced with the output from the
  3161. inner command.
  3162. • "Arithmetic expansion": Constructs such as ‘$(($x-1))’ are
  3163. replaced with the result of the arithmetic computation.
  3164. 3. "Field splitting": subdivision of the text into "words".
  3165. 4. "Wildcard expansion": The replacement of a construct such as ‘*.c’
  3166. with a list of ‘.c’ file names. Wildcard expansion applies to an
  3167. entire word at a time, and replaces that word with 0 or more file
  3168. names that are themselves words.
  3169. 5. "Quote removal": The deletion of string-quotes, now that they have
  3170. done their job by inhibiting the above transformations when
  3171. appropriate.
  3172. For the details of these transformations, and how to write the
  3173. constructs that use them, see ‘The BASH Manual’ (to appear).
  3174. 
  3175. File: libc.info, Node: Calling Wordexp, Next: Flags for Wordexp, Prev: Expansion Stages, Up: Word Expansion
  3176. 10.4.2 Calling ‘wordexp’
  3177. ------------------------
  3178. All the functions, constants and data types for word expansion are
  3179. declared in the header file ‘wordexp.h’.
  3180. Word expansion produces a vector of words (strings). To return this
  3181. vector, ‘wordexp’ uses a special data type, ‘wordexp_t’, which is a
  3182. structure. You pass ‘wordexp’ the address of the structure, and it
  3183. fills in the structure’s fields to tell you about the results.
  3184. -- Data Type: wordexp_t
  3185. This data type holds a pointer to a word vector. More precisely,
  3186. it records both the address of the word vector and its size.
  3187. ‘we_wordc’
  3188. The number of elements in the vector.
  3189. ‘we_wordv’
  3190. The address of the vector. This field has type ‘char **’.
  3191. ‘we_offs’
  3192. The offset of the first real element of the vector, from its
  3193. nominal address in the ‘we_wordv’ field. Unlike the other
  3194. fields, this is always an input to ‘wordexp’, rather than an
  3195. output from it.
  3196. If you use a nonzero offset, then that many elements at the
  3197. beginning of the vector are left empty. (The ‘wordexp’
  3198. function fills them with null pointers.)
  3199. The ‘we_offs’ field is meaningful only if you use the
  3200. ‘WRDE_DOOFFS’ flag. Otherwise, the offset is always zero
  3201. regardless of what is in this field, and the first real
  3202. element comes at the beginning of the vector.
  3203. -- Function: int wordexp (const char *WORDS, wordexp_t
  3204. *WORD-VECTOR-PTR, int FLAGS)
  3205. Preliminary: | MT-Unsafe race:utent const:env env sig:ALRM timer
  3206. locale | AS-Unsafe dlopen plugin i18n heap corrupt lock | AC-Unsafe
  3207. corrupt lock fd mem | *Note POSIX Safety Concepts::.
  3208. Perform word expansion on the string WORDS, putting the result in a
  3209. newly allocated vector, and store the size and address of this
  3210. vector into ‘*WORD-VECTOR-PTR’. The argument FLAGS is a
  3211. combination of bit flags; see *note Flags for Wordexp::, for
  3212. details of the flags.
  3213. You shouldn’t use any of the characters ‘|&;<>’ in the string WORDS
  3214. unless they are quoted; likewise for newline. If you use these
  3215. characters unquoted, you will get the ‘WRDE_BADCHAR’ error code.
  3216. Don’t use parentheses or braces unless they are quoted or part of a
  3217. word expansion construct. If you use quotation characters ‘'"`’,
  3218. they should come in pairs that balance.
  3219. The results of word expansion are a sequence of words. The
  3220. function ‘wordexp’ allocates a string for each resulting word, then
  3221. allocates a vector of type ‘char **’ to store the addresses of
  3222. these strings. The last element of the vector is a null pointer.
  3223. This vector is called the "word vector".
  3224. To return this vector, ‘wordexp’ stores both its address and its
  3225. length (number of elements, not counting the terminating null
  3226. pointer) into ‘*WORD-VECTOR-PTR’.
  3227. If ‘wordexp’ succeeds, it returns 0. Otherwise, it returns one of
  3228. these error codes:
  3229. ‘WRDE_BADCHAR’
  3230. The input string WORDS contains an unquoted invalid character
  3231. such as ‘|’.
  3232. ‘WRDE_BADVAL’
  3233. The input string refers to an undefined shell variable, and
  3234. you used the flag ‘WRDE_UNDEF’ to forbid such references.
  3235. ‘WRDE_CMDSUB’
  3236. The input string uses command substitution, and you used the
  3237. flag ‘WRDE_NOCMD’ to forbid command substitution.
  3238. ‘WRDE_NOSPACE’
  3239. It was impossible to allocate memory to hold the result. In
  3240. this case, ‘wordexp’ can store part of the results—as much as
  3241. it could allocate room for.
  3242. ‘WRDE_SYNTAX’
  3243. There was a syntax error in the input string. For example, an
  3244. unmatched quoting character is a syntax error. This error
  3245. code is also used to signal division by zero and overflow in
  3246. arithmetic expansion.
  3247. -- Function: void wordfree (wordexp_t *WORD-VECTOR-PTR)
  3248. Preliminary: | MT-Safe | AS-Unsafe corrupt heap | AC-Unsafe corrupt
  3249. mem | *Note POSIX Safety Concepts::.
  3250. Free the storage used for the word-strings and vector that
  3251. ‘*WORD-VECTOR-PTR’ points to. This does not free the structure
  3252. ‘*WORD-VECTOR-PTR’ itself—only the other data it points to.
  3253. 
  3254. File: libc.info, Node: Flags for Wordexp, Next: Wordexp Example, Prev: Calling Wordexp, Up: Word Expansion
  3255. 10.4.3 Flags for Word Expansion
  3256. -------------------------------
  3257. This section describes the flags that you can specify in the FLAGS
  3258. argument to ‘wordexp’. Choose the flags you want, and combine them with
  3259. the C operator ‘|’.
  3260. ‘WRDE_APPEND’
  3261. Append the words from this expansion to the vector of words
  3262. produced by previous calls to ‘wordexp’. This way you can
  3263. effectively expand several words as if they were concatenated with
  3264. spaces between them.
  3265. In order for appending to work, you must not modify the contents of
  3266. the word vector structure between calls to ‘wordexp’. And, if you
  3267. set ‘WRDE_DOOFFS’ in the first call to ‘wordexp’, you must also set
  3268. it when you append to the results.
  3269. ‘WRDE_DOOFFS’
  3270. Leave blank slots at the beginning of the vector of words. The
  3271. ‘we_offs’ field says how many slots to leave. The blank slots
  3272. contain null pointers.
  3273. ‘WRDE_NOCMD’
  3274. Don’t do command substitution; if the input requests command
  3275. substitution, report an error.
  3276. ‘WRDE_REUSE’
  3277. Reuse a word vector made by a previous call to ‘wordexp’. Instead
  3278. of allocating a new vector of words, this call to ‘wordexp’ will
  3279. use the vector that already exists (making it larger if necessary).
  3280. Note that the vector may move, so it is not safe to save an old
  3281. pointer and use it again after calling ‘wordexp’. You must fetch
  3282. ‘we_pathv’ anew after each call.
  3283. ‘WRDE_SHOWERR’
  3284. Do show any error messages printed by commands run by command
  3285. substitution. More precisely, allow these commands to inherit the
  3286. standard error output stream of the current process. By default,
  3287. ‘wordexp’ gives these commands a standard error stream that
  3288. discards all output.
  3289. ‘WRDE_UNDEF’
  3290. If the input refers to a shell variable that is not defined, report
  3291. an error.
  3292. 
  3293. File: libc.info, Node: Wordexp Example, Next: Tilde Expansion, Prev: Flags for Wordexp, Up: Word Expansion
  3294. 10.4.4 ‘wordexp’ Example
  3295. ------------------------
  3296. Here is an example of using ‘wordexp’ to expand several strings and use
  3297. the results to run a shell command. It also shows the use of
  3298. ‘WRDE_APPEND’ to concatenate the expansions and of ‘wordfree’ to free
  3299. the space allocated by ‘wordexp’.
  3300. int
  3301. expand_and_execute (const char *program, const char **options)
  3302. {
  3303. wordexp_t result;
  3304. pid_t pid
  3305. int status, i;
  3306. /* Expand the string for the program to run. */
  3307. switch (wordexp (program, &result, 0))
  3308. {
  3309. case 0: /* Successful. */
  3310. break;
  3311. case WRDE_NOSPACE:
  3312. /* If the error was ‘WRDE_NOSPACE’,
  3313. then perhaps part of the result was allocated. */
  3314. wordfree (&result);
  3315. default: /* Some other error. */
  3316. return -1;
  3317. }
  3318. /* Expand the strings specified for the arguments. */
  3319. for (i = 0; options[i] != NULL; i++)
  3320. {
  3321. if (wordexp (options[i], &result, WRDE_APPEND))
  3322. {
  3323. wordfree (&result);
  3324. return -1;
  3325. }
  3326. }
  3327. pid = fork ();
  3328. if (pid == 0)
  3329. {
  3330. /* This is the child process. Execute the command. */
  3331. execv (result.we_wordv[0], result.we_wordv);
  3332. exit (EXIT_FAILURE);
  3333. }
  3334. else if (pid < 0)
  3335. /* The fork failed. Report failure. */
  3336. status = -1;
  3337. else
  3338. /* This is the parent process. Wait for the child to complete. */
  3339. if (waitpid (pid, &status, 0) != pid)
  3340. status = -1;
  3341. wordfree (&result);
  3342. return status;
  3343. }
  3344. 
  3345. File: libc.info, Node: Tilde Expansion, Next: Variable Substitution, Prev: Wordexp Example, Up: Word Expansion
  3346. 10.4.5 Details of Tilde Expansion
  3347. ---------------------------------
  3348. It’s a standard part of shell syntax that you can use ‘~’ at the
  3349. beginning of a file name to stand for your own home directory. You can
  3350. use ‘~USER’ to stand for USER’s home directory.
  3351. "Tilde expansion" is the process of converting these abbreviations to
  3352. the directory names that they stand for.
  3353. Tilde expansion applies to the ‘~’ plus all following characters up
  3354. to whitespace or a slash. It takes place only at the beginning of a
  3355. word, and only if none of the characters to be transformed is quoted in
  3356. any way.
  3357. Plain ‘~’ uses the value of the environment variable ‘HOME’ as the
  3358. proper home directory name. ‘~’ followed by a user name uses
  3359. ‘getpwname’ to look up that user in the user database, and uses whatever
  3360. directory is recorded there. Thus, ‘~’ followed by your own name can
  3361. give different results from plain ‘~’, if the value of ‘HOME’ is not
  3362. really your home directory.
  3363. 
  3364. File: libc.info, Node: Variable Substitution, Prev: Tilde Expansion, Up: Word Expansion
  3365. 10.4.6 Details of Variable Substitution
  3366. ---------------------------------------
  3367. Part of ordinary shell syntax is the use of ‘$VARIABLE’ to substitute
  3368. the value of a shell variable into a command. This is called "variable
  3369. substitution", and it is one part of doing word expansion.
  3370. There are two basic ways you can write a variable reference for
  3371. substitution:
  3372. ‘${VARIABLE}’
  3373. If you write braces around the variable name, then it is completely
  3374. unambiguous where the variable name ends. You can concatenate
  3375. additional letters onto the end of the variable value by writing
  3376. them immediately after the close brace. For example, ‘${foo}s’
  3377. expands into ‘tractors’.
  3378. ‘$VARIABLE’
  3379. If you do not put braces around the variable name, then the
  3380. variable name consists of all the alphanumeric characters and
  3381. underscores that follow the ‘$’. The next punctuation character
  3382. ends the variable name. Thus, ‘$foo-bar’ refers to the variable
  3383. ‘foo’ and expands into ‘tractor-bar’.
  3384. When you use braces, you can also use various constructs to modify
  3385. the value that is substituted, or test it in various ways.
  3386. ‘${VARIABLE:-DEFAULT}’
  3387. Substitute the value of VARIABLE, but if that is empty or
  3388. undefined, use DEFAULT instead.
  3389. ‘${VARIABLE:=DEFAULT}’
  3390. Substitute the value of VARIABLE, but if that is empty or
  3391. undefined, use DEFAULT instead and set the variable to DEFAULT.
  3392. ‘${VARIABLE:?MESSAGE}’
  3393. If VARIABLE is defined and not empty, substitute its value.
  3394. Otherwise, print MESSAGE as an error message on the standard error
  3395. stream, and consider word expansion a failure.
  3396. ‘${VARIABLE:+REPLACEMENT}’
  3397. Substitute REPLACEMENT, but only if VARIABLE is defined and
  3398. nonempty. Otherwise, substitute nothing for this construct.
  3399. ‘${#VARIABLE}’
  3400. Substitute a numeral which expresses in base ten the number of
  3401. characters in the value of VARIABLE. ‘${#foo}’ stands for ‘7’,
  3402. because ‘tractor’ is seven characters.
  3403. These variants of variable substitution let you remove part of the
  3404. variable’s value before substituting it. The PREFIX and SUFFIX are not
  3405. mere strings; they are wildcard patterns, just like the patterns that
  3406. you use to match multiple file names. But in this context, they match
  3407. against parts of the variable value rather than against file names.
  3408. ‘${VARIABLE%%SUFFIX}’
  3409. Substitute the value of VARIABLE, but first discard from that
  3410. variable any portion at the end that matches the pattern SUFFIX.
  3411. If there is more than one alternative for how to match against
  3412. SUFFIX, this construct uses the longest possible match.
  3413. Thus, ‘${foo%%r*}’ substitutes ‘t’, because the largest match for
  3414. ‘r*’ at the end of ‘tractor’ is ‘ractor’.
  3415. ‘${VARIABLE%SUFFIX}’
  3416. Substitute the value of VARIABLE, but first discard from that
  3417. variable any portion at the end that matches the pattern SUFFIX.
  3418. If there is more than one alternative for how to match against
  3419. SUFFIX, this construct uses the shortest possible alternative.
  3420. Thus, ‘${foo%r*}’ substitutes ‘tracto’, because the shortest match
  3421. for ‘r*’ at the end of ‘tractor’ is just ‘r’.
  3422. ‘${VARIABLE##PREFIX}’
  3423. Substitute the value of VARIABLE, but first discard from that
  3424. variable any portion at the beginning that matches the pattern
  3425. PREFIX.
  3426. If there is more than one alternative for how to match against
  3427. PREFIX, this construct uses the longest possible match.
  3428. Thus, ‘${foo##*t}’ substitutes ‘or’, because the largest match for
  3429. ‘*t’ at the beginning of ‘tractor’ is ‘tract’.
  3430. ‘${VARIABLE#PREFIX}’
  3431. Substitute the value of VARIABLE, but first discard from that
  3432. variable any portion at the beginning that matches the pattern
  3433. PREFIX.
  3434. If there is more than one alternative for how to match against
  3435. PREFIX, this construct uses the shortest possible alternative.
  3436. Thus, ‘${foo#*t}’ substitutes ‘ractor’, because the shortest match
  3437. for ‘*t’ at the beginning of ‘tractor’ is just ‘t’.
  3438. 
  3439. File: libc.info, Node: I/O Overview, Next: I/O on Streams, Prev: Pattern Matching, Up: Top
  3440. 11 Input/Output Overview
  3441. ************************
  3442. Most programs need to do either input (reading data) or output (writing
  3443. data), or most frequently both, in order to do anything useful. The GNU
  3444. C Library provides such a large selection of input and output functions
  3445. that the hardest part is often deciding which function is most
  3446. appropriate!
  3447. This chapter introduces concepts and terminology relating to input
  3448. and output. Other chapters relating to the GNU I/O facilities are:
  3449. • *note I/O on Streams::, which covers the high-level functions that
  3450. operate on streams, including formatted input and output.
  3451. • *note Low-Level I/O::, which covers the basic I/O and control
  3452. functions on file descriptors.
  3453. • *note File System Interface::, which covers functions for operating
  3454. on directories and for manipulating file attributes such as access
  3455. modes and ownership.
  3456. • *note Pipes and FIFOs::, which includes information on the basic
  3457. interprocess communication facilities.
  3458. • *note Sockets::, which covers a more complicated interprocess
  3459. communication facility with support for networking.
  3460. • *note Low-Level Terminal Interface::, which covers functions for
  3461. changing how input and output to terminals or other serial devices
  3462. are processed.
  3463. * Menu:
  3464. * I/O Concepts:: Some basic information and terminology.
  3465. * File Names:: How to refer to a file.
  3466. 
  3467. File: libc.info, Node: I/O Concepts, Next: File Names, Up: I/O Overview
  3468. 11.1 Input/Output Concepts
  3469. ==========================
  3470. Before you can read or write the contents of a file, you must establish
  3471. a connection or communications channel to the file. This process is
  3472. called "opening" the file. You can open a file for reading, writing, or
  3473. both.
  3474. The connection to an open file is represented either as a stream or
  3475. as a file descriptor. You pass this as an argument to the functions
  3476. that do the actual read or write operations, to tell them which file to
  3477. operate on. Certain functions expect streams, and others are designed
  3478. to operate on file descriptors.
  3479. When you have finished reading to or writing from the file, you can
  3480. terminate the connection by "closing" the file. Once you have closed a
  3481. stream or file descriptor, you cannot do any more input or output
  3482. operations on it.
  3483. * Menu:
  3484. * Streams and File Descriptors:: The GNU C Library provides two ways
  3485. to access the contents of files.
  3486. * File Position:: The number of bytes from the
  3487. beginning of the file.
  3488. 
  3489. File: libc.info, Node: Streams and File Descriptors, Next: File Position, Up: I/O Concepts
  3490. 11.1.1 Streams and File Descriptors
  3491. -----------------------------------
  3492. When you want to do input or output to a file, you have a choice of two
  3493. basic mechanisms for representing the connection between your program
  3494. and the file: file descriptors and streams. File descriptors are
  3495. represented as objects of type ‘int’, while streams are represented as
  3496. ‘FILE *’ objects.
  3497. File descriptors provide a primitive, low-level interface to input
  3498. and output operations. Both file descriptors and streams can represent
  3499. a connection to a device (such as a terminal), or a pipe or socket for
  3500. communicating with another process, as well as a normal file. But, if
  3501. you want to do control operations that are specific to a particular kind
  3502. of device, you must use a file descriptor; there are no facilities to
  3503. use streams in this way. You must also use file descriptors if your
  3504. program needs to do input or output in special modes, such as
  3505. nonblocking (or polled) input (*note File Status Flags::).
  3506. Streams provide a higher-level interface, layered on top of the
  3507. primitive file descriptor facilities. The stream interface treats all
  3508. kinds of files pretty much alike—the sole exception being the three
  3509. styles of buffering that you can choose (*note Stream Buffering::).
  3510. The main advantage of using the stream interface is that the set of
  3511. functions for performing actual input and output operations (as opposed
  3512. to control operations) on streams is much richer and more powerful than
  3513. the corresponding facilities for file descriptors. The file descriptor
  3514. interface provides only simple functions for transferring blocks of
  3515. characters, but the stream interface also provides powerful formatted
  3516. input and output functions (‘printf’ and ‘scanf’) as well as functions
  3517. for character- and line-oriented input and output.
  3518. Since streams are implemented in terms of file descriptors, you can
  3519. extract the file descriptor from a stream and perform low-level
  3520. operations directly on the file descriptor. You can also initially open
  3521. a connection as a file descriptor and then make a stream associated with
  3522. that file descriptor.
  3523. In general, you should stick with using streams rather than file
  3524. descriptors, unless there is some specific operation you want to do that
  3525. can only be done on a file descriptor. If you are a beginning
  3526. programmer and aren’t sure what functions to use, we suggest that you
  3527. concentrate on the formatted input functions (*note Formatted Input::)
  3528. and formatted output functions (*note Formatted Output::).
  3529. If you are concerned about portability of your programs to systems
  3530. other than GNU, you should also be aware that file descriptors are not
  3531. as portable as streams. You can expect any system running ISO C to
  3532. support streams, but non-GNU systems may not support file descriptors at
  3533. all, or may only implement a subset of the GNU functions that operate on
  3534. file descriptors. Most of the file descriptor functions in the GNU C
  3535. Library are included in the POSIX.1 standard, however.
  3536. 
  3537. File: libc.info, Node: File Position, Prev: Streams and File Descriptors, Up: I/O Concepts
  3538. 11.1.2 File Position
  3539. --------------------
  3540. One of the attributes of an open file is its "file position" that keeps
  3541. track of where in the file the next character is to be read or written.
  3542. On GNU systems, and all POSIX.1 systems, the file position is simply an
  3543. integer representing the number of bytes from the beginning of the file.
  3544. The file position is normally set to the beginning of the file when
  3545. it is opened, and each time a character is read or written, the file
  3546. position is incremented. In other words, access to the file is normally
  3547. "sequential".
  3548. Ordinary files permit read or write operations at any position within
  3549. the file. Some other kinds of files may also permit this. Files which
  3550. do permit this are sometimes referred to as "random-access" files. You
  3551. can change the file position using the ‘fseek’ function on a stream
  3552. (*note File Positioning::) or the ‘lseek’ function on a file descriptor
  3553. (*note I/O Primitives::). If you try to change the file position on a
  3554. file that doesn’t support random access, you get the ‘ESPIPE’ error.
  3555. Streams and descriptors that are opened for "append access" are
  3556. treated specially for output: output to such files is _always_ appended
  3557. sequentially to the _end_ of the file, regardless of the file position.
  3558. However, the file position is still used to control where in the file
  3559. reading is done.
  3560. If you think about it, you’ll realize that several programs can read
  3561. a given file at the same time. In order for each program to be able to
  3562. read the file at its own pace, each program must have its own file
  3563. pointer, which is not affected by anything the other programs do.
  3564. In fact, each opening of a file creates a separate file position.
  3565. Thus, if you open a file twice even in the same program, you get two
  3566. streams or descriptors with independent file positions.
  3567. By contrast, if you open a descriptor and then duplicate it to get
  3568. another descriptor, these two descriptors share the same file position:
  3569. changing the file position of one descriptor will affect the other.
  3570. 
  3571. File: libc.info, Node: File Names, Prev: I/O Concepts, Up: I/O Overview
  3572. 11.2 File Names
  3573. ===============
  3574. In order to open a connection to a file, or to perform other operations
  3575. such as deleting a file, you need some way to refer to the file. Nearly
  3576. all files have names that are strings—even files which are actually
  3577. devices such as tape drives or terminals. These strings are called
  3578. "file names". You specify the file name to say which file you want to
  3579. open or operate on.
  3580. This section describes the conventions for file names and how the
  3581. operating system works with them.
  3582. * Menu:
  3583. * Directories:: Directories contain entries for files.
  3584. * File Name Resolution:: A file name specifies how to look up a file.
  3585. * File Name Errors:: Error conditions relating to file names.
  3586. * File Name Portability:: File name portability and syntax issues.
  3587. 
  3588. File: libc.info, Node: Directories, Next: File Name Resolution, Up: File Names
  3589. 11.2.1 Directories
  3590. ------------------
  3591. In order to understand the syntax of file names, you need to understand
  3592. how the file system is organized into a hierarchy of directories.
  3593. A "directory" is a file that contains information to associate other
  3594. files with names; these associations are called "links" or "directory
  3595. entries". Sometimes, people speak of “files in a directory”, but in
  3596. reality, a directory only contains pointers to files, not the files
  3597. themselves.
  3598. The name of a file contained in a directory entry is called a "file
  3599. name component". In general, a file name consists of a sequence of one
  3600. or more such components, separated by the slash character (‘/’). A file
  3601. name which is just one component names a file with respect to its
  3602. directory. A file name with multiple components names a directory, and
  3603. then a file in that directory, and so on.
  3604. Some other documents, such as the POSIX standard, use the term
  3605. "pathname" for what we call a file name, and either "filename" or
  3606. "pathname component" for what this manual calls a file name component.
  3607. We don’t use this terminology because a “path” is something completely
  3608. different (a list of directories to search), and we think that
  3609. “pathname” used for something else will confuse users. We always use
  3610. “file name” and “file name component” (or sometimes just “component”,
  3611. where the context is obvious) in GNU documentation. Some macros use the
  3612. POSIX terminology in their names, such as ‘PATH_MAX’. These macros are
  3613. defined by the POSIX standard, so we cannot change their names.
  3614. You can find more detailed information about operations on
  3615. directories in *note File System Interface::.
  3616. 
  3617. File: libc.info, Node: File Name Resolution, Next: File Name Errors, Prev: Directories, Up: File Names
  3618. 11.2.2 File Name Resolution
  3619. ---------------------------
  3620. A file name consists of file name components separated by slash (‘/’)
  3621. characters. On the systems that the GNU C Library supports, multiple
  3622. successive ‘/’ characters are equivalent to a single ‘/’ character.
  3623. The process of determining what file a file name refers to is called
  3624. "file name resolution". This is performed by examining the components
  3625. that make up a file name in left-to-right order, and locating each
  3626. successive component in the directory named by the previous component.
  3627. Of course, each of the files that are referenced as directories must
  3628. actually exist, be directories instead of regular files, and have the
  3629. appropriate permissions to be accessible by the process; otherwise the
  3630. file name resolution fails.
  3631. If a file name begins with a ‘/’, the first component in the file
  3632. name is located in the "root directory" of the process (usually all
  3633. processes on the system have the same root directory). Such a file name
  3634. is called an "absolute file name".
  3635. Otherwise, the first component in the file name is located in the
  3636. current working directory (*note Working Directory::). This kind of
  3637. file name is called a "relative file name".
  3638. The file name components ‘.’ (“dot”) and ‘..’ (“dot-dot”) have
  3639. special meanings. Every directory has entries for these file name
  3640. components. The file name component ‘.’ refers to the directory itself,
  3641. while the file name component ‘..’ refers to its "parent directory" (the
  3642. directory that contains the link for the directory in question). As a
  3643. special case, ‘..’ in the root directory refers to the root directory
  3644. itself, since it has no parent; thus ‘/..’ is the same as ‘/’.
  3645. Here are some examples of file names:
  3646. ‘/a’
  3647. The file named ‘a’, in the root directory.
  3648. ‘/a/b’
  3649. The file named ‘b’, in the directory named ‘a’ in the root
  3650. directory.
  3651. ‘a’
  3652. The file named ‘a’, in the current working directory.
  3653. ‘/a/./b’
  3654. This is the same as ‘/a/b’.
  3655. ‘./a’
  3656. The file named ‘a’, in the current working directory.
  3657. ‘../a’
  3658. The file named ‘a’, in the parent directory of the current working
  3659. directory.
  3660. A file name that names a directory may optionally end in a ‘/’. You
  3661. can specify a file name of ‘/’ to refer to the root directory, but the
  3662. empty string is not a meaningful file name. If you want to refer to the
  3663. current working directory, use a file name of ‘.’ or ‘./’.
  3664. Unlike some other operating systems, GNU systems don’t have any
  3665. built-in support for file types (or extensions) or file versions as part
  3666. of its file name syntax. Many programs and utilities use conventions
  3667. for file names—for example, files containing C source code usually have
  3668. names suffixed with ‘.c’—but there is nothing in the file system itself
  3669. that enforces this kind of convention.
  3670. 
  3671. File: libc.info, Node: File Name Errors, Next: File Name Portability, Prev: File Name Resolution, Up: File Names
  3672. 11.2.3 File Name Errors
  3673. -----------------------
  3674. Functions that accept file name arguments usually detect these ‘errno’
  3675. error conditions relating to the file name syntax or trouble finding the
  3676. named file. These errors are referred to throughout this manual as the
  3677. "usual file name errors".
  3678. ‘EACCES’
  3679. The process does not have search permission for a directory
  3680. component of the file name.
  3681. ‘ENAMETOOLONG’
  3682. This error is used when either the total length of a file name is
  3683. greater than ‘PATH_MAX’, or when an individual file name component
  3684. has a length greater than ‘NAME_MAX’. *Note Limits for Files::.
  3685. On GNU/Hurd systems, there is no imposed limit on overall file name
  3686. length, but some file systems may place limits on the length of a
  3687. component.
  3688. ‘ENOENT’
  3689. This error is reported when a file referenced as a directory
  3690. component in the file name doesn’t exist, or when a component is a
  3691. symbolic link whose target file does not exist. *Note Symbolic
  3692. Links::.
  3693. ‘ENOTDIR’
  3694. A file that is referenced as a directory component in the file name
  3695. exists, but it isn’t a directory.
  3696. ‘ELOOP’
  3697. Too many symbolic links were resolved while trying to look up the
  3698. file name. The system has an arbitrary limit on the number of
  3699. symbolic links that may be resolved in looking up a single file
  3700. name, as a primitive way to detect loops. *Note Symbolic Links::.
  3701. 
  3702. File: libc.info, Node: File Name Portability, Prev: File Name Errors, Up: File Names
  3703. 11.2.4 Portability of File Names
  3704. --------------------------------
  3705. The rules for the syntax of file names discussed in *note File Names::,
  3706. are the rules normally used by GNU systems and by other POSIX systems.
  3707. However, other operating systems may use other conventions.
  3708. There are two reasons why it can be important for you to be aware of
  3709. file name portability issues:
  3710. • If your program makes assumptions about file name syntax, or
  3711. contains embedded literal file name strings, it is more difficult
  3712. to get it to run under other operating systems that use different
  3713. syntax conventions.
  3714. • Even if you are not concerned about running your program on
  3715. machines that run other operating systems, it may still be possible
  3716. to access files that use different naming conventions. For
  3717. example, you may be able to access file systems on another computer
  3718. running a different operating system over a network, or read and
  3719. write disks in formats used by other operating systems.
  3720. The ISO C standard says very little about file name syntax, only that
  3721. file names are strings. In addition to varying restrictions on the
  3722. length of file names and what characters can validly appear in a file
  3723. name, different operating systems use different conventions and syntax
  3724. for concepts such as structured directories and file types or
  3725. extensions. Some concepts such as file versions might be supported in
  3726. some operating systems and not by others.
  3727. The POSIX.1 standard allows implementations to put additional
  3728. restrictions on file name syntax, concerning what characters are
  3729. permitted in file names and on the length of file name and file name
  3730. component strings. However, on GNU systems, any character except the
  3731. null character is permitted in a file name string, and on GNU/Hurd
  3732. systems there are no limits on the length of file name strings.
  3733. 
  3734. File: libc.info, Node: I/O on Streams, Next: Low-Level I/O, Prev: I/O Overview, Up: Top
  3735. 12 Input/Output on Streams
  3736. **************************
  3737. This chapter describes the functions for creating streams and performing
  3738. input and output operations on them. As discussed in *note I/O
  3739. Overview::, a stream is a fairly abstract, high-level concept
  3740. representing a communications channel to a file, device, or process.
  3741. * Menu:
  3742. * Streams:: About the data type representing a stream.
  3743. * Standard Streams:: Streams to the standard input and output
  3744. devices are created for you.
  3745. * Opening Streams:: How to create a stream to talk to a file.
  3746. * Closing Streams:: Close a stream when you are finished with it.
  3747. * Streams and Threads:: Issues with streams in threaded programs.
  3748. * Streams and I18N:: Streams in internationalized applications.
  3749. * Simple Output:: Unformatted output by characters and lines.
  3750. * Character Input:: Unformatted input by characters and words.
  3751. * Line Input:: Reading a line or a record from a stream.
  3752. * Unreading:: Peeking ahead/pushing back input just read.
  3753. * Block Input/Output:: Input and output operations on blocks of data.
  3754. * Formatted Output:: ‘printf’ and related functions.
  3755. * Customizing Printf:: You can define new conversion specifiers for
  3756. ‘printf’ and friends.
  3757. * Formatted Input:: ‘scanf’ and related functions.
  3758. * EOF and Errors:: How you can tell if an I/O error happens.
  3759. * Error Recovery:: What you can do about errors.
  3760. * Binary Streams:: Some systems distinguish between text files
  3761. and binary files.
  3762. * File Positioning:: About random-access streams.
  3763. * Portable Positioning:: Random access on peculiar ISO C systems.
  3764. * Stream Buffering:: How to control buffering of streams.
  3765. * Other Kinds of Streams:: Streams that do not necessarily correspond
  3766. to an open file.
  3767. * Formatted Messages:: Print strictly formatted messages.
  3768. 
  3769. File: libc.info, Node: Streams, Next: Standard Streams, Up: I/O on Streams
  3770. 12.1 Streams
  3771. ============
  3772. For historical reasons, the type of the C data structure that represents
  3773. a stream is called ‘FILE’ rather than “stream”. Since most of the
  3774. library functions deal with objects of type ‘FILE *’, sometimes the term
  3775. "file pointer" is also used to mean “stream”. This leads to unfortunate
  3776. confusion over terminology in many books on C. This manual, however, is
  3777. careful to use the terms “file” and “stream” only in the technical
  3778. sense.
  3779. The ‘FILE’ type is declared in the header file ‘stdio.h’.
  3780. -- Data Type: FILE
  3781. This is the data type used to represent stream objects. A ‘FILE’
  3782. object holds all of the internal state information about the
  3783. connection to the associated file, including such things as the
  3784. file position indicator and buffering information. Each stream
  3785. also has error and end-of-file status indicators that can be tested
  3786. with the ‘ferror’ and ‘feof’ functions; see *note EOF and Errors::.
  3787. ‘FILE’ objects are allocated and managed internally by the
  3788. input/output library functions. Don’t try to create your own objects of
  3789. type ‘FILE’; let the library do it. Your programs should deal only with
  3790. pointers to these objects (that is, ‘FILE *’ values) rather than the
  3791. objects themselves.
  3792. 
  3793. File: libc.info, Node: Standard Streams, Next: Opening Streams, Prev: Streams, Up: I/O on Streams
  3794. 12.2 Standard Streams
  3795. =====================
  3796. When the ‘main’ function of your program is invoked, it already has
  3797. three predefined streams open and available for use. These represent
  3798. the “standard” input and output channels that have been established for
  3799. the process.
  3800. These streams are declared in the header file ‘stdio.h’.
  3801. -- Variable: FILE * stdin
  3802. The "standard input" stream, which is the normal source of input
  3803. for the program.
  3804. -- Variable: FILE * stdout
  3805. The "standard output" stream, which is used for normal output from
  3806. the program.
  3807. -- Variable: FILE * stderr
  3808. The "standard error" stream, which is used for error messages and
  3809. diagnostics issued by the program.
  3810. On GNU systems, you can specify what files or processes correspond to
  3811. these streams using the pipe and redirection facilities provided by the
  3812. shell. (The primitives shells use to implement these facilities are
  3813. described in *note File System Interface::.) Most other operating
  3814. systems provide similar mechanisms, but the details of how to use them
  3815. can vary.
  3816. In the GNU C Library, ‘stdin’, ‘stdout’, and ‘stderr’ are normal
  3817. variables which you can set just like any others. For example, to
  3818. redirect the standard output to a file, you could do:
  3819. fclose (stdout);
  3820. stdout = fopen ("standard-output-file", "w");
  3821. Note however, that in other systems ‘stdin’, ‘stdout’, and ‘stderr’
  3822. are macros that you cannot assign to in the normal way. But you can use
  3823. ‘freopen’ to get the effect of closing one and reopening it. *Note
  3824. Opening Streams::.
  3825. The three streams ‘stdin’, ‘stdout’, and ‘stderr’ are not unoriented
  3826. at program start (*note Streams and I18N::).
  3827. 
  3828. File: libc.info, Node: Opening Streams, Next: Closing Streams, Prev: Standard Streams, Up: I/O on Streams
  3829. 12.3 Opening Streams
  3830. ====================
  3831. Opening a file with the ‘fopen’ function creates a new stream and
  3832. establishes a connection between the stream and a file. This may
  3833. involve creating a new file.
  3834. Everything described in this section is declared in the header file
  3835. ‘stdio.h’.
  3836. -- Function: FILE * fopen (const char *FILENAME, const char *OPENTYPE)
  3837. Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem fd
  3838. lock | *Note POSIX Safety Concepts::.
  3839. The ‘fopen’ function opens a stream for I/O to the file FILENAME,
  3840. and returns a pointer to the stream.
  3841. The OPENTYPE argument is a string that controls how the file is
  3842. opened and specifies attributes of the resulting stream. It must
  3843. begin with one of the following sequences of characters:
  3844. ‘r’
  3845. Open an existing file for reading only.
  3846. ‘w’
  3847. Open the file for writing only. If the file already exists,
  3848. it is truncated to zero length. Otherwise a new file is
  3849. created.
  3850. ‘a’
  3851. Open a file for append access; that is, writing at the end of
  3852. file only. If the file already exists, its initial contents
  3853. are unchanged and output to the stream is appended to the end
  3854. of the file. Otherwise, a new, empty file is created.
  3855. ‘r+’
  3856. Open an existing file for both reading and writing. The
  3857. initial contents of the file are unchanged and the initial
  3858. file position is at the beginning of the file.
  3859. ‘w+’
  3860. Open a file for both reading and writing. If the file already
  3861. exists, it is truncated to zero length. Otherwise, a new file
  3862. is created.
  3863. ‘a+’
  3864. Open or create file for both reading and appending. If the
  3865. file exists, its initial contents are unchanged. Otherwise, a
  3866. new file is created. The initial file position for reading is
  3867. at the beginning of the file, but output is always appended to
  3868. the end of the file.
  3869. As you can see, ‘+’ requests a stream that can do both input and
  3870. output. When using such a stream, you must call ‘fflush’ (*note
  3871. Stream Buffering::) or a file positioning function such as ‘fseek’
  3872. (*note File Positioning::) when switching from reading to writing
  3873. or vice versa. Otherwise, internal buffers might not be emptied
  3874. properly.
  3875. Additional characters may appear after these to specify flags for
  3876. the call. Always put the mode (‘r’, ‘w+’, etc.) first; that is
  3877. the only part you are guaranteed will be understood by all systems.
  3878. The GNU C Library defines additional characters for use in
  3879. OPENTYPE:
  3880. ‘c’
  3881. The file is opened with cancellation in the I/O functions
  3882. disabled.
  3883. ‘e’
  3884. The underlying file descriptor will be closed if you use any
  3885. of the ‘exec…’ functions (*note Executing a File::). (This is
  3886. equivalent to having set ‘FD_CLOEXEC’ on that descriptor.
  3887. *Note Descriptor Flags::.)
  3888. ‘m’
  3889. The file is opened and accessed using ‘mmap’. This is only
  3890. supported with files opened for reading.
  3891. ‘x’
  3892. Insist on creating a new file—if a file FILENAME already
  3893. exists, ‘fopen’ fails rather than opening it. If you use ‘x’
  3894. you are guaranteed that you will not clobber an existing file.
  3895. This is equivalent to the ‘O_EXCL’ option to the ‘open’
  3896. function (*note Opening and Closing Files::).
  3897. The ‘x’ modifier is part of ISO C11.
  3898. The character ‘b’ in OPENTYPE has a standard meaning; it requests a
  3899. binary stream rather than a text stream. But this makes no
  3900. difference in POSIX systems (including GNU systems). If both ‘+’
  3901. and ‘b’ are specified, they can appear in either order. *Note
  3902. Binary Streams::.
  3903. If the OPENTYPE string contains the sequence ‘,ccs=STRING’ then
  3904. STRING is taken as the name of a coded character set and ‘fopen’
  3905. will mark the stream as wide-oriented with appropriate conversion
  3906. functions in place to convert from and to the character set STRING.
  3907. Any other stream is opened initially unoriented and the orientation
  3908. is decided with the first file operation. If the first operation
  3909. is a wide character operation, the stream is not only marked as
  3910. wide-oriented, also the conversion functions to convert to the
  3911. coded character set used for the current locale are loaded. This
  3912. will not change anymore from this point on even if the locale
  3913. selected for the ‘LC_CTYPE’ category is changed.
  3914. Any other characters in OPENTYPE are simply ignored. They may be
  3915. meaningful in other systems.
  3916. If the open fails, ‘fopen’ returns a null pointer.
  3917. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
  3918. 32 bit machine this function is in fact ‘fopen64’ since the LFS
  3919. interface replaces transparently the old interface.
  3920. You can have multiple streams (or file descriptors) pointing to the
  3921. same file open at the same time. If you do only input, this works
  3922. straightforwardly, but you must be careful if any output streams are
  3923. included. *Note Stream/Descriptor Precautions::. This is equally true
  3924. whether the streams are in one program (not usual) or in several
  3925. programs (which can easily happen). It may be advantageous to use the
  3926. file locking facilities to avoid simultaneous access. *Note File
  3927. Locks::.
  3928. -- Function: FILE * fopen64 (const char *FILENAME, const char
  3929. *OPENTYPE)
  3930. Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem fd
  3931. lock | *Note POSIX Safety Concepts::.
  3932. This function is similar to ‘fopen’ but the stream it returns a
  3933. pointer for is opened using ‘open64’. Therefore this stream can be
  3934. used even on files larger than 2^31 bytes on 32 bit machines.
  3935. Please note that the return type is still ‘FILE *’. There is no
  3936. special ‘FILE’ type for the LFS interface.
  3937. If the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a 32
  3938. bits machine this function is available under the name ‘fopen’ and
  3939. so transparently replaces the old interface.
  3940. -- Macro: int FOPEN_MAX
  3941. The value of this macro is an integer constant expression that
  3942. represents the minimum number of streams that the implementation
  3943. guarantees can be open simultaneously. You might be able to open
  3944. more than this many streams, but that is not guaranteed. The value
  3945. of this constant is at least eight, which includes the three
  3946. standard streams ‘stdin’, ‘stdout’, and ‘stderr’. In POSIX.1
  3947. systems this value is determined by the ‘OPEN_MAX’ parameter; *note
  3948. General Limits::. In BSD and GNU, it is controlled by the
  3949. ‘RLIMIT_NOFILE’ resource limit; *note Limits on Resources::.
  3950. -- Function: FILE * freopen (const char *FILENAME, const char
  3951. *OPENTYPE, FILE *STREAM)
  3952. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt fd |
  3953. *Note POSIX Safety Concepts::.
  3954. This function is like a combination of ‘fclose’ and ‘fopen’. It
  3955. first closes the stream referred to by STREAM, ignoring any errors
  3956. that are detected in the process. (Because errors are ignored, you
  3957. should not use ‘freopen’ on an output stream if you have actually
  3958. done any output using the stream.) Then the file named by FILENAME
  3959. is opened with mode OPENTYPE as for ‘fopen’, and associated with
  3960. the same stream object STREAM.
  3961. If the operation fails, a null pointer is returned; otherwise,
  3962. ‘freopen’ returns STREAM.
  3963. ‘freopen’ has traditionally been used to connect a standard stream
  3964. such as ‘stdin’ with a file of your own choice. This is useful in
  3965. programs in which use of a standard stream for certain purposes is
  3966. hard-coded. In the GNU C Library, you can simply close the
  3967. standard streams and open new ones with ‘fopen’. But other systems
  3968. lack this ability, so using ‘freopen’ is more portable.
  3969. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
  3970. 32 bit machine this function is in fact ‘freopen64’ since the LFS
  3971. interface replaces transparently the old interface.
  3972. -- Function: FILE * freopen64 (const char *FILENAME, const char
  3973. *OPENTYPE, FILE *STREAM)
  3974. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt fd |
  3975. *Note POSIX Safety Concepts::.
  3976. This function is similar to ‘freopen’. The only difference is that
  3977. on 32 bit machine the stream returned is able to read beyond the
  3978. 2^31 bytes limits imposed by the normal interface. It should be
  3979. noted that the stream pointed to by STREAM need not be opened using
  3980. ‘fopen64’ or ‘freopen64’ since its mode is not important for this
  3981. function.
  3982. If the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a 32
  3983. bits machine this function is available under the name ‘freopen’
  3984. and so transparently replaces the old interface.
  3985. In some situations it is useful to know whether a given stream is
  3986. available for reading or writing. This information is normally not
  3987. available and would have to be remembered separately. Solaris
  3988. introduced a few functions to get this information from the stream
  3989. descriptor and these functions are also available in the GNU C Library.
  3990. -- Function: int __freadable (FILE *STREAM)
  3991. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3992. Concepts::.
  3993. The ‘__freadable’ function determines whether the stream STREAM was
  3994. opened to allow reading. In this case the return value is nonzero.
  3995. For write-only streams the function returns zero.
  3996. This function is declared in ‘stdio_ext.h’.
  3997. -- Function: int __fwritable (FILE *STREAM)
  3998. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3999. Concepts::.
  4000. The ‘__fwritable’ function determines whether the stream STREAM was
  4001. opened to allow writing. In this case the return value is nonzero.
  4002. For read-only streams the function returns zero.
  4003. This function is declared in ‘stdio_ext.h’.
  4004. For slightly different kinds of problems there are two more
  4005. functions. They provide even finer-grained information.
  4006. -- Function: int __freading (FILE *STREAM)
  4007. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4008. Concepts::.
  4009. The ‘__freading’ function determines whether the stream STREAM was
  4010. last read from or whether it is opened read-only. In this case the
  4011. return value is nonzero, otherwise it is zero. Determining whether
  4012. a stream opened for reading and writing was last used for writing
  4013. allows to draw conclusions about the content about the buffer,
  4014. among other things.
  4015. This function is declared in ‘stdio_ext.h’.
  4016. -- Function: int __fwriting (FILE *STREAM)
  4017. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4018. Concepts::.
  4019. The ‘__fwriting’ function determines whether the stream STREAM was
  4020. last written to or whether it is opened write-only. In this case
  4021. the return value is nonzero, otherwise it is zero.
  4022. This function is declared in ‘stdio_ext.h’.
  4023. 
  4024. File: libc.info, Node: Closing Streams, Next: Streams and Threads, Prev: Opening Streams, Up: I/O on Streams
  4025. 12.4 Closing Streams
  4026. ====================
  4027. When a stream is closed with ‘fclose’, the connection between the stream
  4028. and the file is canceled. After you have closed a stream, you cannot
  4029. perform any additional operations on it.
  4030. -- Function: int fclose (FILE *STREAM)
  4031. Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock mem
  4032. fd | *Note POSIX Safety Concepts::.
  4033. This function causes STREAM to be closed and the connection to the
  4034. corresponding file to be broken. Any buffered output is written
  4035. and any buffered input is discarded. The ‘fclose’ function returns
  4036. a value of ‘0’ if the file was closed successfully, and ‘EOF’ if an
  4037. error was detected.
  4038. It is important to check for errors when you call ‘fclose’ to close
  4039. an output stream, because real, everyday errors can be detected at
  4040. this time. For example, when ‘fclose’ writes the remaining
  4041. buffered output, it might get an error because the disk is full.
  4042. Even if you know the buffer is empty, errors can still occur when
  4043. closing a file if you are using NFS.
  4044. The function ‘fclose’ is declared in ‘stdio.h’.
  4045. To close all streams currently available the GNU C Library provides
  4046. another function.
  4047. -- Function: int fcloseall (void)
  4048. Preliminary: | MT-Unsafe race:streams | AS-Unsafe | AC-Safe | *Note
  4049. POSIX Safety Concepts::.
  4050. This function causes all open streams of the process to be closed
  4051. and the connections to corresponding files to be broken. All
  4052. buffered data is written and any buffered input is discarded. The
  4053. ‘fcloseall’ function returns a value of ‘0’ if all the files were
  4054. closed successfully, and ‘EOF’ if an error was detected.
  4055. This function should be used only in special situations, e.g., when
  4056. an error occurred and the program must be aborted. Normally each
  4057. single stream should be closed separately so that problems with
  4058. individual streams can be identified. It is also problematic since
  4059. the standard streams (*note Standard Streams::) will also be
  4060. closed.
  4061. The function ‘fcloseall’ is declared in ‘stdio.h’.
  4062. If the ‘main’ function to your program returns, or if you call the
  4063. ‘exit’ function (*note Normal Termination::), all open streams are
  4064. automatically closed properly. If your program terminates in any other
  4065. manner, such as by calling the ‘abort’ function (*note Aborting a
  4066. Program::) or from a fatal signal (*note Signal Handling::), open
  4067. streams might not be closed properly. Buffered output might not be
  4068. flushed and files may be incomplete. For more information on buffering
  4069. of streams, see *note Stream Buffering::.
  4070. 
  4071. File: libc.info, Node: Streams and Threads, Next: Streams and I18N, Prev: Closing Streams, Up: I/O on Streams
  4072. 12.5 Streams and Threads
  4073. ========================
  4074. Streams can be used in multi-threaded applications in the same way they
  4075. are used in single-threaded applications. But the programmer must be
  4076. aware of the possible complications. It is important to know about
  4077. these also if the program one writes never use threads since the design
  4078. and implementation of many stream functions are heavily influenced by
  4079. the requirements added by multi-threaded programming.
  4080. The POSIX standard requires that by default the stream operations are
  4081. atomic. I.e., issuing two stream operations for the same stream in two
  4082. threads at the same time will cause the operations to be executed as if
  4083. they were issued sequentially. The buffer operations performed while
  4084. reading or writing are protected from other uses of the same stream. To
  4085. do this each stream has an internal lock object which has to be
  4086. (implicitly) acquired before any work can be done.
  4087. But there are situations where this is not enough and there are also
  4088. situations where this is not wanted. The implicit locking is not enough
  4089. if the program requires more than one stream function call to happen
  4090. atomically. One example would be if an output line a program wants to
  4091. generate is created by several function calls. The functions by
  4092. themselves would ensure only atomicity of their own operation, but not
  4093. atomicity over all the function calls. For this it is necessary to
  4094. perform the stream locking in the application code.
  4095. -- Function: void flockfile (FILE *STREAM)
  4096. Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
  4097. Safety Concepts::.
  4098. The ‘flockfile’ function acquires the internal locking object
  4099. associated with the stream STREAM. This ensures that no other
  4100. thread can explicitly through ‘flockfile’/‘ftrylockfile’ or
  4101. implicitly through the call of a stream function lock the stream.
  4102. The thread will block until the lock is acquired. An explicit call
  4103. to ‘funlockfile’ has to be used to release the lock.
  4104. -- Function: int ftrylockfile (FILE *STREAM)
  4105. Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
  4106. Safety Concepts::.
  4107. The ‘ftrylockfile’ function tries to acquire the internal locking
  4108. object associated with the stream STREAM just like ‘flockfile’.
  4109. But unlike ‘flockfile’ this function does not block if the lock is
  4110. not available. ‘ftrylockfile’ returns zero if the lock was
  4111. successfully acquired. Otherwise the stream is locked by another
  4112. thread.
  4113. -- Function: void funlockfile (FILE *STREAM)
  4114. Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
  4115. Safety Concepts::.
  4116. The ‘funlockfile’ function releases the internal locking object of
  4117. the stream STREAM. The stream must have been locked before by a
  4118. call to ‘flockfile’ or a successful call of ‘ftrylockfile’. The
  4119. implicit locking performed by the stream operations do not count.
  4120. The ‘funlockfile’ function does not return an error status and the
  4121. behavior of a call for a stream which is not locked by the current
  4122. thread is undefined.
  4123. The following example shows how the functions above can be used to
  4124. generate an output line atomically even in multi-threaded applications
  4125. (yes, the same job could be done with one ‘fprintf’ call but it is
  4126. sometimes not possible):
  4127. FILE *fp;
  4128. {
  4129. flockfile (fp);
  4130. fputs ("This is test number ", fp);
  4131. fprintf (fp, "%d\n", test);
  4132. funlockfile (fp)
  4133. }
  4134. Without the explicit locking it would be possible for another thread
  4135. to use the stream FP after the ‘fputs’ call returns and before ‘fprintf’
  4136. was called with the result that the number does not follow the word
  4137. ‘number’.
  4138. From this description it might already be clear that the locking
  4139. objects in streams are no simple mutexes. Since locking the same stream
  4140. twice in the same thread is allowed the locking objects must be
  4141. equivalent to recursive mutexes. These mutexes keep track of the owner
  4142. and the number of times the lock is acquired. The same number of
  4143. ‘funlockfile’ calls by the same threads is necessary to unlock the
  4144. stream completely. For instance:
  4145. void
  4146. foo (FILE *fp)
  4147. {
  4148. ftrylockfile (fp);
  4149. fputs ("in foo\n", fp);
  4150. /* This is very wrong!!! */
  4151. funlockfile (fp);
  4152. }
  4153. It is important here that the ‘funlockfile’ function is only called
  4154. if the ‘ftrylockfile’ function succeeded in locking the stream. It is
  4155. therefore always wrong to ignore the result of ‘ftrylockfile’. And it
  4156. makes no sense since otherwise one would use ‘flockfile’. The result of
  4157. code like that above is that either ‘funlockfile’ tries to free a stream
  4158. that hasn’t been locked by the current thread or it frees the stream
  4159. prematurely. The code should look like this:
  4160. void
  4161. foo (FILE *fp)
  4162. {
  4163. if (ftrylockfile (fp) == 0)
  4164. {
  4165. fputs ("in foo\n", fp);
  4166. funlockfile (fp);
  4167. }
  4168. }
  4169. Now that we covered why it is necessary to have locking it is
  4170. necessary to talk about situations when locking is unwanted and what can
  4171. be done. The locking operations (explicit or implicit) don’t come for
  4172. free. Even if a lock is not taken the cost is not zero. The operations
  4173. which have to be performed require memory operations that are safe in
  4174. multi-processor environments. With the many local caches involved in
  4175. such systems this is quite costly. So it is best to avoid the locking
  4176. completely if it is not needed – because the code in question is never
  4177. used in a context where two or more threads may use a stream at a time.
  4178. This can be determined most of the time for application code; for
  4179. library code which can be used in many contexts one should default to be
  4180. conservative and use locking.
  4181. There are two basic mechanisms to avoid locking. The first is to use
  4182. the ‘_unlocked’ variants of the stream operations. The POSIX standard
  4183. defines quite a few of those and the GNU C Library adds a few more.
  4184. These variants of the functions behave just like the functions with the
  4185. name without the suffix except that they do not lock the stream. Using
  4186. these functions is very desirable since they are potentially much
  4187. faster. This is not only because the locking operation itself is
  4188. avoided. More importantly, functions like ‘putc’ and ‘getc’ are very
  4189. simple and traditionally (before the introduction of threads) were
  4190. implemented as macros which are very fast if the buffer is not empty.
  4191. With the addition of locking requirements these functions are no longer
  4192. implemented as macros since they would expand to too much code. But
  4193. these macros are still available with the same functionality under the
  4194. new names ‘putc_unlocked’ and ‘getc_unlocked’. This possibly huge
  4195. difference of speed also suggests the use of the ‘_unlocked’ functions
  4196. even if locking is required. The difference is that the locking then
  4197. has to be performed in the program:
  4198. void
  4199. foo (FILE *fp, char *buf)
  4200. {
  4201. flockfile (fp);
  4202. while (*buf != '/')
  4203. putc_unlocked (*buf++, fp);
  4204. funlockfile (fp);
  4205. }
  4206. If in this example the ‘putc’ function would be used and the explicit
  4207. locking would be missing the ‘putc’ function would have to acquire the
  4208. lock in every call, potentially many times depending on when the loop
  4209. terminates. Writing it the way illustrated above allows the
  4210. ‘putc_unlocked’ macro to be used which means no locking and direct
  4211. manipulation of the buffer of the stream.
  4212. A second way to avoid locking is by using a non-standard function
  4213. which was introduced in Solaris and is available in the GNU C Library as
  4214. well.
  4215. -- Function: int __fsetlocking (FILE *STREAM, int TYPE)
  4216. Preliminary: | MT-Safe race:stream | AS-Unsafe lock | AC-Safe |
  4217. *Note POSIX Safety Concepts::.
  4218. The ‘__fsetlocking’ function can be used to select whether the
  4219. stream operations will implicitly acquire the locking object of the
  4220. stream STREAM. By default this is done but it can be disabled and
  4221. reinstated using this function. There are three values defined for
  4222. the TYPE parameter.
  4223. ‘FSETLOCKING_INTERNAL’
  4224. The stream ‘stream’ will from now on use the default internal
  4225. locking. Every stream operation with exception of the
  4226. ‘_unlocked’ variants will implicitly lock the stream.
  4227. ‘FSETLOCKING_BYCALLER’
  4228. After the ‘__fsetlocking’ function returns, the user is
  4229. responsible for locking the stream. None of the stream
  4230. operations will implicitly do this anymore until the state is
  4231. set back to ‘FSETLOCKING_INTERNAL’.
  4232. ‘FSETLOCKING_QUERY’
  4233. ‘__fsetlocking’ only queries the current locking state of the
  4234. stream. The return value will be ‘FSETLOCKING_INTERNAL’ or
  4235. ‘FSETLOCKING_BYCALLER’ depending on the state.
  4236. The return value of ‘__fsetlocking’ is either
  4237. ‘FSETLOCKING_INTERNAL’ or ‘FSETLOCKING_BYCALLER’ depending on the
  4238. state of the stream before the call.
  4239. This function and the values for the TYPE parameter are declared in
  4240. ‘stdio_ext.h’.
  4241. This function is especially useful when program code has to be used
  4242. which is written without knowledge about the ‘_unlocked’ functions (or
  4243. if the programmer was too lazy to use them).
  4244. 
  4245. File: libc.info, Node: Streams and I18N, Next: Simple Output, Prev: Streams and Threads, Up: I/O on Streams
  4246. 12.6 Streams in Internationalized Applications
  4247. ==============================================
  4248. ISO C90 introduced the new type ‘wchar_t’ to allow handling larger
  4249. character sets. What was missing was a possibility to output strings of
  4250. ‘wchar_t’ directly. One had to convert them into multibyte strings
  4251. using ‘mbstowcs’ (there was no ‘mbsrtowcs’ yet) and then use the normal
  4252. stream functions. While this is doable it is very cumbersome since
  4253. performing the conversions is not trivial and greatly increases program
  4254. complexity and size.
  4255. The Unix standard early on (I think in XPG4.2) introduced two
  4256. additional format specifiers for the ‘printf’ and ‘scanf’ families of
  4257. functions. Printing and reading of single wide characters was made
  4258. possible using the ‘%C’ specifier and wide character strings can be
  4259. handled with ‘%S’. These modifiers behave just like ‘%c’ and ‘%s’ only
  4260. that they expect the corresponding argument to have the wide character
  4261. type and that the wide character and string are transformed into/from
  4262. multibyte strings before being used.
  4263. This was a beginning but it is still not good enough. Not always is
  4264. it desirable to use ‘printf’ and ‘scanf’. The other, smaller and faster
  4265. functions cannot handle wide characters. Second, it is not possible to
  4266. have a format string for ‘printf’ and ‘scanf’ consisting of wide
  4267. characters. The result is that format strings would have to be
  4268. generated if they have to contain non-basic characters.
  4269. In the Amendment 1 to ISO C90 a whole new set of functions was added
  4270. to solve the problem. Most of the stream functions got a counterpart
  4271. which take a wide character or wide character string instead of a
  4272. character or string respectively. The new functions operate on the same
  4273. streams (like ‘stdout’). This is different from the model of the C++
  4274. runtime library where separate streams for wide and normal I/O are used.
  4275. Being able to use the same stream for wide and normal operations
  4276. comes with a restriction: a stream can be used either for wide
  4277. operations or for normal operations. Once it is decided there is no way
  4278. back. Only a call to ‘freopen’ or ‘freopen64’ can reset the
  4279. "orientation". The orientation can be decided in three ways:
  4280. • If any of the normal character functions are used (this includes
  4281. the ‘fread’ and ‘fwrite’ functions) the stream is marked as not
  4282. wide oriented.
  4283. • If any of the wide character functions are used the stream is
  4284. marked as wide oriented.
  4285. • The ‘fwide’ function can be used to set the orientation either way.
  4286. It is important to never mix the use of wide and not wide operations
  4287. on a stream. There are no diagnostics issued. The application behavior
  4288. will simply be strange or the application will simply crash. The
  4289. ‘fwide’ function can help avoid this.
  4290. -- Function: int fwide (FILE *STREAM, int MODE)
  4291. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock | *Note
  4292. POSIX Safety Concepts::.
  4293. The ‘fwide’ function can be used to set and query the state of the
  4294. orientation of the stream STREAM. If the MODE parameter has a
  4295. positive value the streams get wide oriented, for negative values
  4296. narrow oriented. It is not possible to overwrite previous
  4297. orientations with ‘fwide’. I.e., if the stream STREAM was already
  4298. oriented before the call nothing is done.
  4299. If MODE is zero the current orientation state is queried and
  4300. nothing is changed.
  4301. The ‘fwide’ function returns a negative value, zero, or a positive
  4302. value if the stream is narrow, not at all, or wide oriented
  4303. respectively.
  4304. This function was introduced in Amendment 1 to ISO C90 and is
  4305. declared in ‘wchar.h’.
  4306. It is generally a good idea to orient a stream as early as possible.
  4307. This can prevent surprise especially for the standard streams ‘stdin’,
  4308. ‘stdout’, and ‘stderr’. If some library function in some situations
  4309. uses one of these streams and this use orients the stream in a different
  4310. way the rest of the application expects it one might end up with hard to
  4311. reproduce errors. Remember that no errors are signal if the streams are
  4312. used incorrectly. Leaving a stream unoriented after creation is
  4313. normally only necessary for library functions which create streams which
  4314. can be used in different contexts.
  4315. When writing code which uses streams and which can be used in
  4316. different contexts it is important to query the orientation of the
  4317. stream before using it (unless the rules of the library interface demand
  4318. a specific orientation). The following little, silly function
  4319. illustrates this.
  4320. void
  4321. print_f (FILE *fp)
  4322. {
  4323. if (fwide (fp, 0) > 0)
  4324. /* Positive return value means wide orientation. */
  4325. fputwc (L'f', fp);
  4326. else
  4327. fputc ('f', fp);
  4328. }
  4329. Note that in this case the function ‘print_f’ decides about the
  4330. orientation of the stream if it was unoriented before (will not happen
  4331. if the advice above is followed).
  4332. The encoding used for the ‘wchar_t’ values is unspecified and the
  4333. user must not make any assumptions about it. For I/O of ‘wchar_t’
  4334. values this means that it is impossible to write these values directly
  4335. to the stream. This is not what follows from the ISO C locale model
  4336. either. What happens instead is that the bytes read from or written to
  4337. the underlying media are first converted into the internal encoding
  4338. chosen by the implementation for ‘wchar_t’. The external encoding is
  4339. determined by the ‘LC_CTYPE’ category of the current locale or by the
  4340. ‘ccs’ part of the mode specification given to ‘fopen’, ‘fopen64’,
  4341. ‘freopen’, or ‘freopen64’. How and when the conversion happens is
  4342. unspecified and it happens invisibly to the user.
  4343. Since a stream is created in the unoriented state it has at that
  4344. point no conversion associated with it. The conversion which will be
  4345. used is determined by the ‘LC_CTYPE’ category selected at the time the
  4346. stream is oriented. If the locales are changed at the runtime this
  4347. might produce surprising results unless one pays attention. This is
  4348. just another good reason to orient the stream explicitly as soon as
  4349. possible, perhaps with a call to ‘fwide’.
  4350. 
  4351. File: libc.info, Node: Simple Output, Next: Character Input, Prev: Streams and I18N, Up: I/O on Streams
  4352. 12.7 Simple Output by Characters or Lines
  4353. =========================================
  4354. This section describes functions for performing character- and
  4355. line-oriented output.
  4356. These narrow stream functions are declared in the header file
  4357. ‘stdio.h’ and the wide stream functions in ‘wchar.h’.
  4358. -- Function: int fputc (int C, FILE *STREAM)
  4359. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
  4360. | *Note POSIX Safety Concepts::.
  4361. The ‘fputc’ function converts the character C to type ‘unsigned
  4362. char’, and writes it to the stream STREAM. ‘EOF’ is returned if a
  4363. write error occurs; otherwise the character C is returned.
  4364. -- Function: wint_t fputwc (wchar_t WC, FILE *STREAM)
  4365. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
  4366. | *Note POSIX Safety Concepts::.
  4367. The ‘fputwc’ function writes the wide character WC to the stream
  4368. STREAM. ‘WEOF’ is returned if a write error occurs; otherwise the
  4369. character WC is returned.
  4370. -- Function: int fputc_unlocked (int C, FILE *STREAM)
  4371. Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
  4372. corrupt | *Note POSIX Safety Concepts::.
  4373. The ‘fputc_unlocked’ function is equivalent to the ‘fputc’ function
  4374. except that it does not implicitly lock the stream.
  4375. -- Function: wint_t fputwc_unlocked (wchar_t WC, FILE *STREAM)
  4376. Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
  4377. corrupt | *Note POSIX Safety Concepts::.
  4378. The ‘fputwc_unlocked’ function is equivalent to the ‘fputwc’
  4379. function except that it does not implicitly lock the stream.
  4380. This function is a GNU extension.
  4381. -- Function: int putc (int C, FILE *STREAM)
  4382. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
  4383. | *Note POSIX Safety Concepts::.
  4384. This is just like ‘fputc’, except that most systems implement it as
  4385. a macro, making it faster. One consequence is that it may evaluate
  4386. the STREAM argument more than once, which is an exception to the
  4387. general rule for macros. ‘putc’ is usually the best function to
  4388. use for writing a single character.
  4389. -- Function: wint_t putwc (wchar_t WC, FILE *STREAM)
  4390. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
  4391. | *Note POSIX Safety Concepts::.
  4392. This is just like ‘fputwc’, except that it can be implement as a
  4393. macro, making it faster. One consequence is that it may evaluate
  4394. the STREAM argument more than once, which is an exception to the
  4395. general rule for macros. ‘putwc’ is usually the best function to
  4396. use for writing a single wide character.
  4397. -- Function: int putc_unlocked (int C, FILE *STREAM)
  4398. Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
  4399. corrupt | *Note POSIX Safety Concepts::.
  4400. The ‘putc_unlocked’ function is equivalent to the ‘putc’ function
  4401. except that it does not implicitly lock the stream.
  4402. -- Function: wint_t putwc_unlocked (wchar_t WC, FILE *STREAM)
  4403. Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
  4404. corrupt | *Note POSIX Safety Concepts::.
  4405. The ‘putwc_unlocked’ function is equivalent to the ‘putwc’ function
  4406. except that it does not implicitly lock the stream.
  4407. This function is a GNU extension.
  4408. -- Function: int putchar (int C)
  4409. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
  4410. | *Note POSIX Safety Concepts::.
  4411. The ‘putchar’ function is equivalent to ‘putc’ with ‘stdout’ as the
  4412. value of the STREAM argument.
  4413. -- Function: wint_t putwchar (wchar_t WC)
  4414. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
  4415. | *Note POSIX Safety Concepts::.
  4416. The ‘putwchar’ function is equivalent to ‘putwc’ with ‘stdout’ as
  4417. the value of the STREAM argument.
  4418. -- Function: int putchar_unlocked (int C)
  4419. Preliminary: | MT-Unsafe race:stdout | AS-Unsafe corrupt |
  4420. AC-Unsafe corrupt | *Note POSIX Safety Concepts::.
  4421. The ‘putchar_unlocked’ function is equivalent to the ‘putchar’
  4422. function except that it does not implicitly lock the stream.
  4423. -- Function: wint_t putwchar_unlocked (wchar_t WC)
  4424. Preliminary: | MT-Unsafe race:stdout | AS-Unsafe corrupt |
  4425. AC-Unsafe corrupt | *Note POSIX Safety Concepts::.
  4426. The ‘putwchar_unlocked’ function is equivalent to the ‘putwchar’
  4427. function except that it does not implicitly lock the stream.
  4428. This function is a GNU extension.
  4429. -- Function: int fputs (const char *S, FILE *STREAM)
  4430. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
  4431. | *Note POSIX Safety Concepts::.
  4432. The function ‘fputs’ writes the string S to the stream STREAM. The
  4433. terminating null character is not written. This function does
  4434. _not_ add a newline character, either. It outputs only the
  4435. characters in the string.
  4436. This function returns ‘EOF’ if a write error occurs, and otherwise
  4437. a non-negative value.
  4438. For example:
  4439. fputs ("Are ", stdout);
  4440. fputs ("you ", stdout);
  4441. fputs ("hungry?\n", stdout);
  4442. outputs the text ‘Are you hungry?’ followed by a newline.
  4443. -- Function: int fputws (const wchar_t *WS, FILE *STREAM)
  4444. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock
  4445. | *Note POSIX Safety Concepts::.
  4446. The function ‘fputws’ writes the wide character string WS to the
  4447. stream STREAM. The terminating null character is not written.
  4448. This function does _not_ add a newline character, either. It
  4449. outputs only the characters in the string.
  4450. This function returns ‘WEOF’ if a write error occurs, and otherwise
  4451. a non-negative value.
  4452. -- Function: int fputs_unlocked (const char *S, FILE *STREAM)
  4453. Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
  4454. corrupt | *Note POSIX Safety Concepts::.
  4455. The ‘fputs_unlocked’ function is equivalent to the ‘fputs’ function
  4456. except that it does not implicitly lock the stream.
  4457. This function is a GNU extension.
  4458. -- Function: int fputws_unlocked (const wchar_t *WS, FILE *STREAM)
  4459. Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
  4460. corrupt | *Note POSIX Safety Concepts::.
  4461. The ‘fputws_unlocked’ function is equivalent to the ‘fputws’
  4462. function except that it does not implicitly lock the stream.
  4463. This function is a GNU extension.
  4464. -- Function: int puts (const char *S)
  4465. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  4466. | *Note POSIX Safety Concepts::.
  4467. The ‘puts’ function writes the string S to the stream ‘stdout’
  4468. followed by a newline. The terminating null character of the
  4469. string is not written. (Note that ‘fputs’ does _not_ write a
  4470. newline as this function does.)
  4471. ‘puts’ is the most convenient function for printing simple
  4472. messages. For example:
  4473. puts ("This is a message.");
  4474. outputs the text ‘This is a message.’ followed by a newline.
  4475. -- Function: int putw (int W, FILE *STREAM)
  4476. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  4477. | *Note POSIX Safety Concepts::.
  4478. This function writes the word W (that is, an ‘int’) to STREAM. It
  4479. is provided for compatibility with SVID, but we recommend you use
  4480. ‘fwrite’ instead (*note Block Input/Output::).
  4481. 
  4482. File: libc.info, Node: Character Input, Next: Line Input, Prev: Simple Output, Up: I/O on Streams
  4483. 12.8 Character Input
  4484. ====================
  4485. This section describes functions for performing character-oriented
  4486. input. These narrow stream functions are declared in the header file
  4487. ‘stdio.h’ and the wide character functions are declared in ‘wchar.h’.
  4488. These functions return an ‘int’ or ‘wint_t’ value (for narrow and
  4489. wide stream functions respectively) that is either a character of input,
  4490. or the special value ‘EOF’/‘WEOF’ (usually -1). For the narrow stream
  4491. functions it is important to store the result of these functions in a
  4492. variable of type ‘int’ instead of ‘char’, even when you plan to use it
  4493. only as a character. Storing ‘EOF’ in a ‘char’ variable truncates its
  4494. value to the size of a character, so that it is no longer
  4495. distinguishable from the valid character ‘(char) -1’. So always use an
  4496. ‘int’ for the result of ‘getc’ and friends, and check for ‘EOF’ after
  4497. the call; once you’ve verified that the result is not ‘EOF’, you can be
  4498. sure that it will fit in a ‘char’ variable without loss of information.
  4499. -- Function: int fgetc (FILE *STREAM)
  4500. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  4501. | *Note POSIX Safety Concepts::.
  4502. This function reads the next character as an ‘unsigned char’ from
  4503. the stream STREAM and returns its value, converted to an ‘int’. If
  4504. an end-of-file condition or read error occurs, ‘EOF’ is returned
  4505. instead.
  4506. -- Function: wint_t fgetwc (FILE *STREAM)
  4507. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  4508. | *Note POSIX Safety Concepts::.
  4509. This function reads the next wide character from the stream STREAM
  4510. and returns its value. If an end-of-file condition or read error
  4511. occurs, ‘WEOF’ is returned instead.
  4512. -- Function: int fgetc_unlocked (FILE *STREAM)
  4513. Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
  4514. corrupt | *Note POSIX Safety Concepts::.
  4515. The ‘fgetc_unlocked’ function is equivalent to the ‘fgetc’ function
  4516. except that it does not implicitly lock the stream.
  4517. -- Function: wint_t fgetwc_unlocked (FILE *STREAM)
  4518. Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
  4519. corrupt | *Note POSIX Safety Concepts::.
  4520. The ‘fgetwc_unlocked’ function is equivalent to the ‘fgetwc’
  4521. function except that it does not implicitly lock the stream.
  4522. This function is a GNU extension.
  4523. -- Function: int getc (FILE *STREAM)
  4524. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  4525. | *Note POSIX Safety Concepts::.
  4526. This is just like ‘fgetc’, except that it is permissible (and
  4527. typical) for it to be implemented as a macro that evaluates the
  4528. STREAM argument more than once. ‘getc’ is often highly optimized,
  4529. so it is usually the best function to use to read a single
  4530. character.
  4531. -- Function: wint_t getwc (FILE *STREAM)
  4532. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  4533. | *Note POSIX Safety Concepts::.
  4534. This is just like ‘fgetwc’, except that it is permissible for it to
  4535. be implemented as a macro that evaluates the STREAM argument more
  4536. than once. ‘getwc’ can be highly optimized, so it is usually the
  4537. best function to use to read a single wide character.
  4538. -- Function: int getc_unlocked (FILE *STREAM)
  4539. Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
  4540. corrupt | *Note POSIX Safety Concepts::.
  4541. The ‘getc_unlocked’ function is equivalent to the ‘getc’ function
  4542. except that it does not implicitly lock the stream.
  4543. -- Function: wint_t getwc_unlocked (FILE *STREAM)
  4544. Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
  4545. corrupt | *Note POSIX Safety Concepts::.
  4546. The ‘getwc_unlocked’ function is equivalent to the ‘getwc’ function
  4547. except that it does not implicitly lock the stream.
  4548. This function is a GNU extension.
  4549. -- Function: int getchar (void)
  4550. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  4551. | *Note POSIX Safety Concepts::.
  4552. The ‘getchar’ function is equivalent to ‘getc’ with ‘stdin’ as the
  4553. value of the STREAM argument.
  4554. -- Function: wint_t getwchar (void)
  4555. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  4556. | *Note POSIX Safety Concepts::.
  4557. The ‘getwchar’ function is equivalent to ‘getwc’ with ‘stdin’ as
  4558. the value of the STREAM argument.
  4559. -- Function: int getchar_unlocked (void)
  4560. Preliminary: | MT-Unsafe race:stdin | AS-Unsafe corrupt | AC-Unsafe
  4561. corrupt | *Note POSIX Safety Concepts::.
  4562. The ‘getchar_unlocked’ function is equivalent to the ‘getchar’
  4563. function except that it does not implicitly lock the stream.
  4564. -- Function: wint_t getwchar_unlocked (void)
  4565. Preliminary: | MT-Unsafe race:stdin | AS-Unsafe corrupt | AC-Unsafe
  4566. corrupt | *Note POSIX Safety Concepts::.
  4567. The ‘getwchar_unlocked’ function is equivalent to the ‘getwchar’
  4568. function except that it does not implicitly lock the stream.
  4569. This function is a GNU extension.
  4570. Here is an example of a function that does input using ‘fgetc’. It
  4571. would work just as well using ‘getc’ instead, or using ‘getchar ()’
  4572. instead of ‘fgetc (stdin)’. The code would also work the same for the
  4573. wide character stream functions.
  4574. int
  4575. y_or_n_p (const char *question)
  4576. {
  4577. fputs (question, stdout);
  4578. while (1)
  4579. {
  4580. int c, answer;
  4581. /* Write a space to separate answer from question. */
  4582. fputc (' ', stdout);
  4583. /* Read the first character of the line.
  4584. This should be the answer character, but might not be. */
  4585. c = tolower (fgetc (stdin));
  4586. answer = c;
  4587. /* Discard rest of input line. */
  4588. while (c != '\n' && c != EOF)
  4589. c = fgetc (stdin);
  4590. /* Obey the answer if it was valid. */
  4591. if (answer == 'y')
  4592. return 1;
  4593. if (answer == 'n')
  4594. return 0;
  4595. /* Answer was invalid: ask for valid answer. */
  4596. fputs ("Please answer y or n:", stdout);
  4597. }
  4598. }
  4599. -- Function: int getw (FILE *STREAM)
  4600. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  4601. | *Note POSIX Safety Concepts::.
  4602. This function reads a word (that is, an ‘int’) from STREAM. It’s
  4603. provided for compatibility with SVID. We recommend you use ‘fread’
  4604. instead (*note Block Input/Output::). Unlike ‘getc’, any ‘int’
  4605. value could be a valid result. ‘getw’ returns ‘EOF’ when it
  4606. encounters end-of-file or an error, but there is no way to
  4607. distinguish this from an input word with value -1.
  4608. 
  4609. File: libc.info, Node: Line Input, Next: Unreading, Prev: Character Input, Up: I/O on Streams
  4610. 12.9 Line-Oriented Input
  4611. ========================
  4612. Since many programs interpret input on the basis of lines, it is
  4613. convenient to have functions to read a line of text from a stream.
  4614. Standard C has functions to do this, but they aren’t very safe: null
  4615. characters and even (for ‘gets’) long lines can confuse them. So the
  4616. GNU C Library provides the nonstandard ‘getline’ function that makes it
  4617. easy to read lines reliably.
  4618. Another GNU extension, ‘getdelim’, generalizes ‘getline’. It reads a
  4619. delimited record, defined as everything through the next occurrence of a
  4620. specified delimiter character.
  4621. All these functions are declared in ‘stdio.h’.
  4622. -- Function: ssize_t getline (char **LINEPTR, size_t *N, FILE *STREAM)
  4623. Preliminary: | MT-Safe | AS-Unsafe corrupt heap | AC-Unsafe lock
  4624. corrupt mem | *Note POSIX Safety Concepts::.
  4625. This function reads an entire line from STREAM, storing the text
  4626. (including the newline and a terminating null character) in a
  4627. buffer and storing the buffer address in ‘*LINEPTR’.
  4628. Before calling ‘getline’, you should place in ‘*LINEPTR’ the
  4629. address of a buffer ‘*N’ bytes long, allocated with ‘malloc’. If
  4630. this buffer is long enough to hold the line, ‘getline’ stores the
  4631. line in this buffer. Otherwise, ‘getline’ makes the buffer bigger
  4632. using ‘realloc’, storing the new buffer address back in ‘*LINEPTR’
  4633. and the increased size back in ‘*N’. *Note Unconstrained
  4634. Allocation::.
  4635. If you set ‘*LINEPTR’ to a null pointer, and ‘*N’ to zero, before
  4636. the call, then ‘getline’ allocates the initial buffer for you by
  4637. calling ‘malloc’. This buffer remains allocated even if ‘getline’
  4638. encounters errors and is unable to read any bytes.
  4639. In either case, when ‘getline’ returns, ‘*LINEPTR’ is a ‘char *’
  4640. which points to the text of the line.
  4641. When ‘getline’ is successful, it returns the number of characters
  4642. read (including the newline, but not including the terminating
  4643. null). This value enables you to distinguish null characters that
  4644. are part of the line from the null character inserted as a
  4645. terminator.
  4646. This function is a GNU extension, but it is the recommended way to
  4647. read lines from a stream. The alternative standard functions are
  4648. unreliable.
  4649. If an error occurs or end of file is reached without any bytes
  4650. read, ‘getline’ returns ‘-1’.
  4651. -- Function: ssize_t getdelim (char **LINEPTR, size_t *N, int
  4652. DELIMITER, FILE *STREAM)
  4653. Preliminary: | MT-Safe | AS-Unsafe corrupt heap | AC-Unsafe lock
  4654. corrupt mem | *Note POSIX Safety Concepts::.
  4655. This function is like ‘getline’ except that the character which
  4656. tells it to stop reading is not necessarily newline. The argument
  4657. DELIMITER specifies the delimiter character; ‘getdelim’ keeps
  4658. reading until it sees that character (or end of file).
  4659. The text is stored in LINEPTR, including the delimiter character
  4660. and a terminating null. Like ‘getline’, ‘getdelim’ makes LINEPTR
  4661. bigger if it isn’t big enough.
  4662. ‘getline’ is in fact implemented in terms of ‘getdelim’, just like
  4663. this:
  4664. ssize_t
  4665. getline (char **lineptr, size_t *n, FILE *stream)
  4666. {
  4667. return getdelim (lineptr, n, '\n', stream);
  4668. }
  4669. -- Function: char * fgets (char *S, int COUNT, FILE *STREAM)
  4670. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  4671. | *Note POSIX Safety Concepts::.
  4672. The ‘fgets’ function reads characters from the stream STREAM up to
  4673. and including a newline character and stores them in the string S,
  4674. adding a null character to mark the end of the string. You must
  4675. supply COUNT characters worth of space in S, but the number of
  4676. characters read is at most COUNT − 1. The extra character space is
  4677. used to hold the null character at the end of the string.
  4678. If the system is already at end of file when you call ‘fgets’, then
  4679. the contents of the array S are unchanged and a null pointer is
  4680. returned. A null pointer is also returned if a read error occurs.
  4681. Otherwise, the return value is the pointer S.
  4682. *Warning:* If the input data has a null character, you can’t tell.
  4683. So don’t use ‘fgets’ unless you know the data cannot contain a
  4684. null. Don’t use it to read files edited by the user because, if
  4685. the user inserts a null character, you should either handle it
  4686. properly or print a clear error message. We recommend using
  4687. ‘getline’ instead of ‘fgets’.
  4688. -- Function: wchar_t * fgetws (wchar_t *WS, int COUNT, FILE *STREAM)
  4689. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  4690. | *Note POSIX Safety Concepts::.
  4691. The ‘fgetws’ function reads wide characters from the stream STREAM
  4692. up to and including a newline character and stores them in the
  4693. string WS, adding a null wide character to mark the end of the
  4694. string. You must supply COUNT wide characters worth of space in
  4695. WS, but the number of characters read is at most COUNT − 1. The
  4696. extra character space is used to hold the null wide character at
  4697. the end of the string.
  4698. If the system is already at end of file when you call ‘fgetws’,
  4699. then the contents of the array WS are unchanged and a null pointer
  4700. is returned. A null pointer is also returned if a read error
  4701. occurs. Otherwise, the return value is the pointer WS.
  4702. *Warning:* If the input data has a null wide character (which are
  4703. null bytes in the input stream), you can’t tell. So don’t use
  4704. ‘fgetws’ unless you know the data cannot contain a null. Don’t use
  4705. it to read files edited by the user because, if the user inserts a
  4706. null character, you should either handle it properly or print a
  4707. clear error message.
  4708. -- Function: char * fgets_unlocked (char *S, int COUNT, FILE *STREAM)
  4709. Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
  4710. corrupt | *Note POSIX Safety Concepts::.
  4711. The ‘fgets_unlocked’ function is equivalent to the ‘fgets’ function
  4712. except that it does not implicitly lock the stream.
  4713. This function is a GNU extension.
  4714. -- Function: wchar_t * fgetws_unlocked (wchar_t *WS, int COUNT, FILE
  4715. *STREAM)
  4716. Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
  4717. corrupt | *Note POSIX Safety Concepts::.
  4718. The ‘fgetws_unlocked’ function is equivalent to the ‘fgetws’
  4719. function except that it does not implicitly lock the stream.
  4720. This function is a GNU extension.
  4721. -- Deprecated function: char * gets (char *S)
  4722. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  4723. | *Note POSIX Safety Concepts::.
  4724. The function ‘gets’ reads characters from the stream ‘stdin’ up to
  4725. the next newline character, and stores them in the string S. The
  4726. newline character is discarded (note that this differs from the
  4727. behavior of ‘fgets’, which copies the newline character into the
  4728. string). If ‘gets’ encounters a read error or end-of-file, it
  4729. returns a null pointer; otherwise it returns S.
  4730. *Warning:* The ‘gets’ function is *very dangerous* because it
  4731. provides no protection against overflowing the string S. The GNU C
  4732. Library includes it for compatibility only. You should *always*
  4733. use ‘fgets’ or ‘getline’ instead. To remind you of this, the
  4734. linker (if using GNU ‘ld’) will issue a warning whenever you use
  4735. ‘gets’.
  4736. 
  4737. File: libc.info, Node: Unreading, Next: Block Input/Output, Prev: Line Input, Up: I/O on Streams
  4738. 12.10 Unreading
  4739. ===============
  4740. In parser programs it is often useful to examine the next character in
  4741. the input stream without removing it from the stream. This is called
  4742. “peeking ahead” at the input because your program gets a glimpse of the
  4743. input it will read next.
  4744. Using stream I/O, you can peek ahead at input by first reading it and
  4745. then "unreading" it (also called "pushing it back" on the stream).
  4746. Unreading a character makes it available to be input again from the
  4747. stream, by the next call to ‘fgetc’ or other input function on that
  4748. stream.
  4749. * Menu:
  4750. * Unreading Idea:: An explanation of unreading with pictures.
  4751. * How Unread:: How to call ‘ungetc’ to do unreading.
  4752. 
  4753. File: libc.info, Node: Unreading Idea, Next: How Unread, Up: Unreading
  4754. 12.10.1 What Unreading Means
  4755. ----------------------------
  4756. Here is a pictorial explanation of unreading. Suppose you have a stream
  4757. reading a file that contains just six characters, the letters ‘foobar’.
  4758. Suppose you have read three characters so far. The situation looks like
  4759. this:
  4760. f o o b a r
  4761. ^
  4762. so the next input character will be ‘b’.
  4763. If instead of reading ‘b’ you unread the letter ‘o’, you get a
  4764. situation like this:
  4765. f o o b a r
  4766. |
  4767. o--
  4768. ^
  4769. so that the next input characters will be ‘o’ and ‘b’.
  4770. If you unread ‘9’ instead of ‘o’, you get this situation:
  4771. f o o b a r
  4772. |
  4773. 9--
  4774. ^
  4775. so that the next input characters will be ‘9’ and ‘b’.
  4776. 
  4777. File: libc.info, Node: How Unread, Prev: Unreading Idea, Up: Unreading
  4778. 12.10.2 Using ‘ungetc’ To Do Unreading
  4779. --------------------------------------
  4780. The function to unread a character is called ‘ungetc’, because it
  4781. reverses the action of ‘getc’.
  4782. -- Function: int ungetc (int C, FILE *STREAM)
  4783. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  4784. | *Note POSIX Safety Concepts::.
  4785. The ‘ungetc’ function pushes back the character C onto the input
  4786. stream STREAM. So the next input from STREAM will read C before
  4787. anything else.
  4788. If C is ‘EOF’, ‘ungetc’ does nothing and just returns ‘EOF’. This
  4789. lets you call ‘ungetc’ with the return value of ‘getc’ without
  4790. needing to check for an error from ‘getc’.
  4791. The character that you push back doesn’t have to be the same as the
  4792. last character that was actually read from the stream. In fact, it
  4793. isn’t necessary to actually read any characters from the stream
  4794. before unreading them with ‘ungetc’! But that is a strange way to
  4795. write a program; usually ‘ungetc’ is used only to unread a
  4796. character that was just read from the same stream. The GNU C
  4797. Library supports this even on files opened in binary mode, but
  4798. other systems might not.
  4799. The GNU C Library only supports one character of pushback—in other
  4800. words, it does not work to call ‘ungetc’ twice without doing input
  4801. in between. Other systems might let you push back multiple
  4802. characters; then reading from the stream retrieves the characters
  4803. in the reverse order that they were pushed.
  4804. Pushing back characters doesn’t alter the file; only the internal
  4805. buffering for the stream is affected. If a file positioning
  4806. function (such as ‘fseek’, ‘fseeko’ or ‘rewind’; *note File
  4807. Positioning::) is called, any pending pushed-back characters are
  4808. discarded.
  4809. Unreading a character on a stream that is at end of file clears the
  4810. end-of-file indicator for the stream, because it makes the
  4811. character of input available. After you read that character,
  4812. trying to read again will encounter end of file.
  4813. -- Function: wint_t ungetwc (wint_t WC, FILE *STREAM)
  4814. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  4815. | *Note POSIX Safety Concepts::.
  4816. The ‘ungetwc’ function behaves just like ‘ungetc’ just that it
  4817. pushes back a wide character.
  4818. Here is an example showing the use of ‘getc’ and ‘ungetc’ to skip
  4819. over whitespace characters. When this function reaches a non-whitespace
  4820. character, it unreads that character to be seen again on the next read
  4821. operation on the stream.
  4822. #include <stdio.h>
  4823. #include <ctype.h>
  4824. void
  4825. skip_whitespace (FILE *stream)
  4826. {
  4827. int c;
  4828. do
  4829. /* No need to check for ‘EOF’ because it is not
  4830. ‘isspace’, and ‘ungetc’ ignores ‘EOF’. */
  4831. c = getc (stream);
  4832. while (isspace (c));
  4833. ungetc (c, stream);
  4834. }
  4835. 
  4836. File: libc.info, Node: Block Input/Output, Next: Formatted Output, Prev: Unreading, Up: I/O on Streams
  4837. 12.11 Block Input/Output
  4838. ========================
  4839. This section describes how to do input and output operations on blocks
  4840. of data. You can use these functions to read and write binary data, as
  4841. well as to read and write text in fixed-size blocks instead of by
  4842. characters or lines.
  4843. Binary files are typically used to read and write blocks of data in
  4844. the same format as is used to represent the data in a running program.
  4845. In other words, arbitrary blocks of memory—not just character or string
  4846. objects—can be written to a binary file, and meaningfully read in again
  4847. by the same program.
  4848. Storing data in binary form is often considerably more efficient than
  4849. using the formatted I/O functions. Also, for floating-point numbers,
  4850. the binary form avoids possible loss of precision in the conversion
  4851. process. On the other hand, binary files can’t be examined or modified
  4852. easily using many standard file utilities (such as text editors), and
  4853. are not portable between different implementations of the language, or
  4854. different kinds of computers.
  4855. These functions are declared in ‘stdio.h’.
  4856. -- Function: size_t fread (void *DATA, size_t SIZE, size_t COUNT, FILE
  4857. *STREAM)
  4858. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  4859. | *Note POSIX Safety Concepts::.
  4860. This function reads up to COUNT objects of size SIZE into the array
  4861. DATA, from the stream STREAM. It returns the number of objects
  4862. actually read, which might be less than COUNT if a read error
  4863. occurs or the end of the file is reached. This function returns a
  4864. value of zero (and doesn’t read anything) if either SIZE or COUNT
  4865. is zero.
  4866. If ‘fread’ encounters end of file in the middle of an object, it
  4867. returns the number of complete objects read, and discards the
  4868. partial object. Therefore, the stream remains at the actual end of
  4869. the file.
  4870. -- Function: size_t fread_unlocked (void *DATA, size_t SIZE, size_t
  4871. COUNT, FILE *STREAM)
  4872. Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
  4873. corrupt | *Note POSIX Safety Concepts::.
  4874. The ‘fread_unlocked’ function is equivalent to the ‘fread’ function
  4875. except that it does not implicitly lock the stream.
  4876. This function is a GNU extension.
  4877. -- Function: size_t fwrite (const void *DATA, size_t SIZE, size_t
  4878. COUNT, FILE *STREAM)
  4879. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  4880. | *Note POSIX Safety Concepts::.
  4881. This function writes up to COUNT objects of size SIZE from the
  4882. array DATA, to the stream STREAM. The return value is normally
  4883. COUNT, if the call succeeds. Any other value indicates some sort
  4884. of error, such as running out of space.
  4885. -- Function: size_t fwrite_unlocked (const void *DATA, size_t SIZE,
  4886. size_t COUNT, FILE *STREAM)
  4887. Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
  4888. corrupt | *Note POSIX Safety Concepts::.
  4889. The ‘fwrite_unlocked’ function is equivalent to the ‘fwrite’
  4890. function except that it does not implicitly lock the stream.
  4891. This function is a GNU extension.
  4892. 
  4893. File: libc.info, Node: Formatted Output, Next: Customizing Printf, Prev: Block Input/Output, Up: I/O on Streams
  4894. 12.12 Formatted Output
  4895. ======================
  4896. The functions described in this section (‘printf’ and related functions)
  4897. provide a convenient way to perform formatted output. You call ‘printf’
  4898. with a "format string" or "template string" that specifies how to format
  4899. the values of the remaining arguments.
  4900. Unless your program is a filter that specifically performs line- or
  4901. character-oriented processing, using ‘printf’ or one of the other
  4902. related functions described in this section is usually the easiest and
  4903. most concise way to perform output. These functions are especially
  4904. useful for printing error messages, tables of data, and the like.
  4905. * Menu:
  4906. * Formatted Output Basics:: Some examples to get you started.
  4907. * Output Conversion Syntax:: General syntax of conversion
  4908. specifications.
  4909. * Table of Output Conversions:: Summary of output conversions and
  4910. what they do.
  4911. * Integer Conversions:: Details about formatting of integers.
  4912. * Floating-Point Conversions:: Details about formatting of
  4913. floating-point numbers.
  4914. * Other Output Conversions:: Details about formatting of strings,
  4915. characters, pointers, and the like.
  4916. * Formatted Output Functions:: Descriptions of the actual functions.
  4917. * Dynamic Output:: Functions that allocate memory for the output.
  4918. * Variable Arguments Output:: ‘vprintf’ and friends.
  4919. * Parsing a Template String:: What kinds of args does a given template
  4920. call for?
  4921. * Example of Parsing:: Sample program using ‘parse_printf_format’.
  4922. 
  4923. File: libc.info, Node: Formatted Output Basics, Next: Output Conversion Syntax, Up: Formatted Output
  4924. 12.12.1 Formatted Output Basics
  4925. -------------------------------
  4926. The ‘printf’ function can be used to print any number of arguments. The
  4927. template string argument you supply in a call provides information not
  4928. only about the number of additional arguments, but also about their
  4929. types and what style should be used for printing them.
  4930. Ordinary characters in the template string are simply written to the
  4931. output stream as-is, while "conversion specifications" introduced by a
  4932. ‘%’ character in the template cause subsequent arguments to be formatted
  4933. and written to the output stream. For example,
  4934. int pct = 37;
  4935. char filename[] = "foo.txt";
  4936. printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
  4937. filename, pct);
  4938. produces output like
  4939. Processing of `foo.txt' is 37% finished.
  4940. Please be patient.
  4941. This example shows the use of the ‘%d’ conversion to specify that an
  4942. ‘int’ argument should be printed in decimal notation, the ‘%s’
  4943. conversion to specify printing of a string argument, and the ‘%%’
  4944. conversion to print a literal ‘%’ character.
  4945. There are also conversions for printing an integer argument as an
  4946. unsigned value in octal, decimal, or hexadecimal radix (‘%o’, ‘%u’, or
  4947. ‘%x’, respectively); or as a character value (‘%c’).
  4948. Floating-point numbers can be printed in normal, fixed-point notation
  4949. using the ‘%f’ conversion or in exponential notation using the ‘%e’
  4950. conversion. The ‘%g’ conversion uses either ‘%e’ or ‘%f’ format,
  4951. depending on what is more appropriate for the magnitude of the
  4952. particular number.
  4953. You can control formatting more precisely by writing "modifiers"
  4954. between the ‘%’ and the character that indicates which conversion to
  4955. apply. These slightly alter the ordinary behavior of the conversion.
  4956. For example, most conversion specifications permit you to specify a
  4957. minimum field width and a flag indicating whether you want the result
  4958. left- or right-justified within the field.
  4959. The specific flags and modifiers that are permitted and their
  4960. interpretation vary depending on the particular conversion. They’re all
  4961. described in more detail in the following sections. Don’t worry if this
  4962. all seems excessively complicated at first; you can almost always get
  4963. reasonable free-format output without using any of the modifiers at all.
  4964. The modifiers are mostly used to make the output look “prettier” in
  4965. tables.
  4966. 
  4967. File: libc.info, Node: Output Conversion Syntax, Next: Table of Output Conversions, Prev: Formatted Output Basics, Up: Formatted Output
  4968. 12.12.2 Output Conversion Syntax
  4969. --------------------------------
  4970. This section provides details about the precise syntax of conversion
  4971. specifications that can appear in a ‘printf’ template string.
  4972. Characters in the template string that are not part of a conversion
  4973. specification are printed as-is to the output stream. Multibyte
  4974. character sequences (*note Character Set Handling::) are permitted in a
  4975. template string.
  4976. The conversion specifications in a ‘printf’ template string have the
  4977. general form:
  4978. % [ PARAM-NO $] FLAGS WIDTH [ . PRECISION ] TYPE CONVERSION
  4979. or
  4980. % [ PARAM-NO $] FLAGS WIDTH . * [ PARAM-NO $] TYPE CONVERSION
  4981. For example, in the conversion specifier ‘%-10.8ld’, the ‘-’ is a
  4982. flag, ‘10’ specifies the field width, the precision is ‘8’, the letter
  4983. ‘l’ is a type modifier, and ‘d’ specifies the conversion style. (This
  4984. particular type specifier says to print a ‘long int’ argument in decimal
  4985. notation, with a minimum of 8 digits left-justified in a field at least
  4986. 10 characters wide.)
  4987. In more detail, output conversion specifications consist of an
  4988. initial ‘%’ character followed in sequence by:
  4989. • An optional specification of the parameter used for this format.
  4990. Normally the parameters to the ‘printf’ function are assigned to
  4991. the formats in the order of appearance in the format string. But
  4992. in some situations (such as message translation) this is not
  4993. desirable and this extension allows an explicit parameter to be
  4994. specified.
  4995. The PARAM-NO parts of the format must be integers in the range of 1
  4996. to the maximum number of arguments present to the function call.
  4997. Some implementations limit this number to a certain upper bound.
  4998. The exact limit can be retrieved by the following constant.
  4999. -- Macro: NL_ARGMAX
  5000. The value of ‘NL_ARGMAX’ is the maximum value allowed for the
  5001. specification of a positional parameter in a ‘printf’ call.
  5002. The actual value in effect at runtime can be retrieved by
  5003. using ‘sysconf’ using the ‘_SC_NL_ARGMAX’ parameter *note
  5004. Sysconf Definition::.
  5005. Some systems have a quite low limit such as 9 for System V
  5006. systems. The GNU C Library has no real limit.
  5007. If any of the formats has a specification for the parameter
  5008. position all of them in the format string shall have one.
  5009. Otherwise the behavior is undefined.
  5010. • Zero or more "flag characters" that modify the normal behavior of
  5011. the conversion specification.
  5012. • An optional decimal integer specifying the "minimum field width".
  5013. If the normal conversion produces fewer characters than this, the
  5014. field is padded with spaces to the specified width. This is a
  5015. _minimum_ value; if the normal conversion produces more characters
  5016. than this, the field is _not_ truncated. Normally, the output is
  5017. right-justified within the field.
  5018. You can also specify a field width of ‘*’. This means that the
  5019. next argument in the argument list (before the actual value to be
  5020. printed) is used as the field width. The value must be an ‘int’.
  5021. If the value is negative, this means to set the ‘-’ flag (see
  5022. below) and to use the absolute value as the field width.
  5023. • An optional "precision" to specify the number of digits to be
  5024. written for the numeric conversions. If the precision is
  5025. specified, it consists of a period (‘.’) followed optionally by a
  5026. decimal integer (which defaults to zero if omitted).
  5027. You can also specify a precision of ‘*’. This means that the next
  5028. argument in the argument list (before the actual value to be
  5029. printed) is used as the precision. The value must be an ‘int’, and
  5030. is ignored if it is negative. If you specify ‘*’ for both the
  5031. field width and precision, the field width argument precedes the
  5032. precision argument. Other C library versions may not recognize
  5033. this syntax.
  5034. • An optional "type modifier character", which is used to specify the
  5035. data type of the corresponding argument if it differs from the
  5036. default type. (For example, the integer conversions assume a type
  5037. of ‘int’, but you can specify ‘h’, ‘l’, or ‘L’ for other integer
  5038. types.)
  5039. • A character that specifies the conversion to be applied.
  5040. The exact options that are permitted and how they are interpreted
  5041. vary between the different conversion specifiers. See the descriptions
  5042. of the individual conversions for information about the particular
  5043. options that they use.
  5044. With the ‘-Wformat’ option, the GNU C compiler checks calls to
  5045. ‘printf’ and related functions. It examines the format string and
  5046. verifies that the correct number and types of arguments are supplied.
  5047. There is also a GNU C syntax to tell the compiler that a function you
  5048. write uses a ‘printf’-style format string. *Note Declaring Attributes
  5049. of Functions: (gcc.info)Function Attributes, for more information.
  5050. 
  5051. File: libc.info, Node: Table of Output Conversions, Next: Integer Conversions, Prev: Output Conversion Syntax, Up: Formatted Output
  5052. 12.12.3 Table of Output Conversions
  5053. -----------------------------------
  5054. Here is a table summarizing what all the different conversions do:
  5055. ‘%d’, ‘%i’
  5056. Print an integer as a signed decimal number. *Note Integer
  5057. Conversions::, for details. ‘%d’ and ‘%i’ are synonymous for
  5058. output, but are different when used with ‘scanf’ for input (*note
  5059. Table of Input Conversions::).
  5060. ‘%o’
  5061. Print an integer as an unsigned octal number. *Note Integer
  5062. Conversions::, for details.
  5063. ‘%u’
  5064. Print an integer as an unsigned decimal number. *Note Integer
  5065. Conversions::, for details.
  5066. ‘%x’, ‘%X’
  5067. Print an integer as an unsigned hexadecimal number. ‘%x’ uses
  5068. lower-case letters and ‘%X’ uses upper-case. *Note Integer
  5069. Conversions::, for details.
  5070. ‘%f’
  5071. Print a floating-point number in normal (fixed-point) notation.
  5072. *Note Floating-Point Conversions::, for details.
  5073. ‘%e’, ‘%E’
  5074. Print a floating-point number in exponential notation. ‘%e’ uses
  5075. lower-case letters and ‘%E’ uses upper-case. *Note Floating-Point
  5076. Conversions::, for details.
  5077. ‘%g’, ‘%G’
  5078. Print a floating-point number in either normal or exponential
  5079. notation, whichever is more appropriate for its magnitude. ‘%g’
  5080. uses lower-case letters and ‘%G’ uses upper-case. *Note
  5081. Floating-Point Conversions::, for details.
  5082. ‘%a’, ‘%A’
  5083. Print a floating-point number in a hexadecimal fractional notation
  5084. with the exponent to base 2 represented in decimal digits. ‘%a’
  5085. uses lower-case letters and ‘%A’ uses upper-case. *Note
  5086. Floating-Point Conversions::, for details.
  5087. ‘%c’
  5088. Print a single character. *Note Other Output Conversions::.
  5089. ‘%C’
  5090. This is an alias for ‘%lc’ which is supported for compatibility
  5091. with the Unix standard.
  5092. ‘%s’
  5093. Print a string. *Note Other Output Conversions::.
  5094. ‘%S’
  5095. This is an alias for ‘%ls’ which is supported for compatibility
  5096. with the Unix standard.
  5097. ‘%p’
  5098. Print the value of a pointer. *Note Other Output Conversions::.
  5099. ‘%n’
  5100. Get the number of characters printed so far. *Note Other Output
  5101. Conversions::. Note that this conversion specification never
  5102. produces any output.
  5103. ‘%m’
  5104. Print the string corresponding to the value of ‘errno’. (This is a
  5105. GNU extension.) *Note Other Output Conversions::.
  5106. ‘%%’
  5107. Print a literal ‘%’ character. *Note Other Output Conversions::.
  5108. If the syntax of a conversion specification is invalid, unpredictable
  5109. things will happen, so don’t do this. If there aren’t enough function
  5110. arguments provided to supply values for all the conversion
  5111. specifications in the template string, or if the arguments are not of
  5112. the correct types, the results are unpredictable. If you supply more
  5113. arguments than conversion specifications, the extra argument values are
  5114. simply ignored; this is sometimes useful.
  5115. 
  5116. File: libc.info, Node: Integer Conversions, Next: Floating-Point Conversions, Prev: Table of Output Conversions, Up: Formatted Output
  5117. 12.12.4 Integer Conversions
  5118. ---------------------------
  5119. This section describes the options for the ‘%d’, ‘%i’, ‘%o’, ‘%u’, ‘%x’,
  5120. and ‘%X’ conversion specifications. These conversions print integers in
  5121. various formats.
  5122. The ‘%d’ and ‘%i’ conversion specifications both print an ‘int’
  5123. argument as a signed decimal number; while ‘%o’, ‘%u’, and ‘%x’ print
  5124. the argument as an unsigned octal, decimal, or hexadecimal number
  5125. (respectively). The ‘%X’ conversion specification is just like ‘%x’
  5126. except that it uses the characters ‘ABCDEF’ as digits instead of
  5127. ‘abcdef’.
  5128. The following flags are meaningful:
  5129. ‘-’
  5130. Left-justify the result in the field (instead of the normal
  5131. right-justification).
  5132. ‘+’
  5133. For the signed ‘%d’ and ‘%i’ conversions, print a plus sign if the
  5134. value is positive.
  5135. ‘ ’
  5136. For the signed ‘%d’ and ‘%i’ conversions, if the result doesn’t
  5137. start with a plus or minus sign, prefix it with a space character
  5138. instead. Since the ‘+’ flag ensures that the result includes a
  5139. sign, this flag is ignored if you supply both of them.
  5140. ‘#’
  5141. For the ‘%o’ conversion, this forces the leading digit to be ‘0’,
  5142. as if by increasing the precision. For ‘%x’ or ‘%X’, this prefixes
  5143. a leading ‘0x’ or ‘0X’ (respectively) to the result. This doesn’t
  5144. do anything useful for the ‘%d’, ‘%i’, or ‘%u’ conversions. Using
  5145. this flag produces output which can be parsed by the ‘strtoul’
  5146. function (*note Parsing of Integers::) and ‘scanf’ with the ‘%i’
  5147. conversion (*note Numeric Input Conversions::).
  5148. ‘'’
  5149. Separate the digits into groups as specified by the locale
  5150. specified for the ‘LC_NUMERIC’ category; *note General Numeric::.
  5151. This flag is a GNU extension.
  5152. ‘0’
  5153. Pad the field with zeros instead of spaces. The zeros are placed
  5154. after any indication of sign or base. This flag is ignored if the
  5155. ‘-’ flag is also specified, or if a precision is specified.
  5156. If a precision is supplied, it specifies the minimum number of digits
  5157. to appear; leading zeros are produced if necessary. If you don’t
  5158. specify a precision, the number is printed with as many digits as it
  5159. needs. If you convert a value of zero with an explicit precision of
  5160. zero, then no characters at all are produced.
  5161. Without a type modifier, the corresponding argument is treated as an
  5162. ‘int’ (for the signed conversions ‘%i’ and ‘%d’) or ‘unsigned int’ (for
  5163. the unsigned conversions ‘%o’, ‘%u’, ‘%x’, and ‘%X’). Recall that since
  5164. ‘printf’ and friends are variadic, any ‘char’ and ‘short’ arguments are
  5165. automatically converted to ‘int’ by the default argument promotions.
  5166. For arguments of other integer types, you can use these modifiers:
  5167. ‘hh’
  5168. Specifies that the argument is a ‘signed char’ or ‘unsigned char’,
  5169. as appropriate. A ‘char’ argument is converted to an ‘int’ or
  5170. ‘unsigned int’ by the default argument promotions anyway, but the
  5171. ‘hh’ modifier says to convert it back to a ‘char’ again.
  5172. This modifier was introduced in ISO C99.
  5173. ‘h’
  5174. Specifies that the argument is a ‘short int’ or ‘unsigned short
  5175. int’, as appropriate. A ‘short’ argument is converted to an ‘int’
  5176. or ‘unsigned int’ by the default argument promotions anyway, but
  5177. the ‘h’ modifier says to convert it back to a ‘short’ again.
  5178. ‘j’
  5179. Specifies that the argument is a ‘intmax_t’ or ‘uintmax_t’, as
  5180. appropriate.
  5181. This modifier was introduced in ISO C99.
  5182. ‘l’
  5183. Specifies that the argument is a ‘long int’ or ‘unsigned long int’,
  5184. as appropriate. Two ‘l’ characters are like the ‘L’ modifier,
  5185. below.
  5186. If used with ‘%c’ or ‘%s’ the corresponding parameter is considered
  5187. as a wide character or wide character string respectively. This
  5188. use of ‘l’ was introduced in Amendment 1 to ISO C90.
  5189. ‘L’
  5190. ‘ll’
  5191. ‘q’
  5192. Specifies that the argument is a ‘long long int’. (This type is an
  5193. extension supported by the GNU C compiler. On systems that don’t
  5194. support extra-long integers, this is the same as ‘long int’.)
  5195. The ‘q’ modifier is another name for the same thing, which comes
  5196. from 4.4 BSD; a ‘long long int’ is sometimes called a “quad” ‘int’.
  5197. ‘t’
  5198. Specifies that the argument is a ‘ptrdiff_t’.
  5199. This modifier was introduced in ISO C99.
  5200. ‘z’
  5201. ‘Z’
  5202. Specifies that the argument is a ‘size_t’.
  5203. ‘z’ was introduced in ISO C99. ‘Z’ is a GNU extension predating
  5204. this addition and should not be used in new code.
  5205. Here is an example. Using the template string:
  5206. "|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
  5207. to print numbers using the different options for the ‘%d’ conversion
  5208. gives results like:
  5209. | 0|0 | +0|+0 | 0|00000| | 00|0|
  5210. | 1|1 | +1|+1 | 1|00001| 1| 01|1|
  5211. | -1|-1 | -1|-1 | -1|-0001| -1| -01|-1|
  5212. |100000|100000|+100000|+100000| 100000|100000|100000|100000|100000|
  5213. In particular, notice what happens in the last case where the number
  5214. is too large to fit in the minimum field width specified.
  5215. Here are some more examples showing how unsigned integers print under
  5216. various format options, using the template string:
  5217. "|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
  5218. | 0| 0| 0| 0| 0| 0| 0| 00000000|
  5219. | 1| 1| 1| 1| 01| 0x1| 0X1|0x00000001|
  5220. |100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
  5221. 
  5222. File: libc.info, Node: Floating-Point Conversions, Next: Other Output Conversions, Prev: Integer Conversions, Up: Formatted Output
  5223. 12.12.5 Floating-Point Conversions
  5224. ----------------------------------
  5225. This section discusses the conversion specifications for floating-point
  5226. numbers: the ‘%f’, ‘%e’, ‘%E’, ‘%g’, and ‘%G’ conversions.
  5227. The ‘%f’ conversion prints its argument in fixed-point notation,
  5228. producing output of the form [‘-’]DDD‘.’DDD, where the number of digits
  5229. following the decimal point is controlled by the precision you specify.
  5230. The ‘%e’ conversion prints its argument in exponential notation,
  5231. producing output of the form [‘-’]D‘.’DDD‘e’[‘+’|‘-’]DD. Again, the
  5232. number of digits following the decimal point is controlled by the
  5233. precision. The exponent always contains at least two digits. The ‘%E’
  5234. conversion is similar but the exponent is marked with the letter ‘E’
  5235. instead of ‘e’.
  5236. The ‘%g’ and ‘%G’ conversions print the argument in the style of ‘%e’
  5237. or ‘%E’ (respectively) if the exponent would be less than -4 or greater
  5238. than or equal to the precision; otherwise they use the ‘%f’ style. A
  5239. precision of ‘0’, is taken as 1. Trailing zeros are removed from the
  5240. fractional portion of the result and a decimal-point character appears
  5241. only if it is followed by a digit.
  5242. The ‘%a’ and ‘%A’ conversions are meant for representing
  5243. floating-point numbers exactly in textual form so that they can be
  5244. exchanged as texts between different programs and/or machines. The
  5245. numbers are represented in the form [‘-’]‘0x’H‘.’HHH‘p’[‘+’|‘-’]DD. At
  5246. the left of the decimal-point character exactly one digit is print.
  5247. This character is only ‘0’ if the number is denormalized. Otherwise the
  5248. value is unspecified; it is implementation dependent how many bits are
  5249. used. The number of hexadecimal digits on the right side of the
  5250. decimal-point character is equal to the precision. If the precision is
  5251. zero it is determined to be large enough to provide an exact
  5252. representation of the number (or it is large enough to distinguish two
  5253. adjacent values if the ‘FLT_RADIX’ is not a power of 2, *note Floating
  5254. Point Parameters::). For the ‘%a’ conversion lower-case characters are
  5255. used to represent the hexadecimal number and the prefix and exponent
  5256. sign are printed as ‘0x’ and ‘p’ respectively. Otherwise upper-case
  5257. characters are used and ‘0X’ and ‘P’ are used for the representation of
  5258. prefix and exponent string. The exponent to the base of two is printed
  5259. as a decimal number using at least one digit but at most as many digits
  5260. as necessary to represent the value exactly.
  5261. If the value to be printed represents infinity or a NaN, the output
  5262. is [‘-’]‘inf’ or ‘nan’ respectively if the conversion specifier is ‘%a’,
  5263. ‘%e’, ‘%f’, or ‘%g’ and it is [‘-’]‘INF’ or ‘NAN’ respectively if the
  5264. conversion is ‘%A’, ‘%E’, or ‘%G’.
  5265. The following flags can be used to modify the behavior:
  5266. ‘-’
  5267. Left-justify the result in the field. Normally the result is
  5268. right-justified.
  5269. ‘+’
  5270. Always include a plus or minus sign in the result.
  5271. ‘ ’
  5272. If the result doesn’t start with a plus or minus sign, prefix it
  5273. with a space instead. Since the ‘+’ flag ensures that the result
  5274. includes a sign, this flag is ignored if you supply both of them.
  5275. ‘#’
  5276. Specifies that the result should always include a decimal point,
  5277. even if no digits follow it. For the ‘%g’ and ‘%G’ conversions,
  5278. this also forces trailing zeros after the decimal point to be left
  5279. in place where they would otherwise be removed.
  5280. ‘'’
  5281. Separate the digits of the integer part of the result into groups
  5282. as specified by the locale specified for the ‘LC_NUMERIC’ category;
  5283. *note General Numeric::. This flag is a GNU extension.
  5284. ‘0’
  5285. Pad the field with zeros instead of spaces; the zeros are placed
  5286. after any sign. This flag is ignored if the ‘-’ flag is also
  5287. specified.
  5288. The precision specifies how many digits follow the decimal-point
  5289. character for the ‘%f’, ‘%e’, and ‘%E’ conversions. For these
  5290. conversions, the default precision is ‘6’. If the precision is
  5291. explicitly ‘0’, this suppresses the decimal point character entirely.
  5292. For the ‘%g’ and ‘%G’ conversions, the precision specifies how many
  5293. significant digits to print. Significant digits are the first digit
  5294. before the decimal point, and all the digits after it. If the precision
  5295. is ‘0’ or not specified for ‘%g’ or ‘%G’, it is treated like a value of
  5296. ‘1’. If the value being printed cannot be expressed accurately in the
  5297. specified number of digits, the value is rounded to the nearest number
  5298. that fits.
  5299. Without a type modifier, the floating-point conversions use an
  5300. argument of type ‘double’. (By the default argument promotions, any
  5301. ‘float’ arguments are automatically converted to ‘double’.) The
  5302. following type modifier is supported:
  5303. ‘L’
  5304. An uppercase ‘L’ specifies that the argument is a ‘long double’.
  5305. Here are some examples showing how numbers print using the various
  5306. floating-point conversions. All of the numbers were printed using this
  5307. template string:
  5308. "|%13.4a|%13.4f|%13.4e|%13.4g|\n"
  5309. Here is the output:
  5310. | 0x0.0000p+0| 0.0000| 0.0000e+00| 0|
  5311. | 0x1.0000p-1| 0.5000| 5.0000e-01| 0.5|
  5312. | 0x1.0000p+0| 1.0000| 1.0000e+00| 1|
  5313. | -0x1.0000p+0| -1.0000| -1.0000e+00| -1|
  5314. | 0x1.9000p+6| 100.0000| 1.0000e+02| 100|
  5315. | 0x1.f400p+9| 1000.0000| 1.0000e+03| 1000|
  5316. | 0x1.3880p+13| 10000.0000| 1.0000e+04| 1e+04|
  5317. | 0x1.81c8p+13| 12345.0000| 1.2345e+04| 1.234e+04|
  5318. | 0x1.86a0p+16| 100000.0000| 1.0000e+05| 1e+05|
  5319. | 0x1.e240p+16| 123456.0000| 1.2346e+05| 1.235e+05|
  5320. Notice how the ‘%g’ conversion drops trailing zeros.
  5321. 
  5322. File: libc.info, Node: Other Output Conversions, Next: Formatted Output Functions, Prev: Floating-Point Conversions, Up: Formatted Output
  5323. 12.12.6 Other Output Conversions
  5324. --------------------------------
  5325. This section describes miscellaneous conversions for ‘printf’.
  5326. The ‘%c’ conversion prints a single character. In case there is no
  5327. ‘l’ modifier the ‘int’ argument is first converted to an ‘unsigned
  5328. char’. Then, if used in a wide stream function, the character is
  5329. converted into the corresponding wide character. The ‘-’ flag can be
  5330. used to specify left-justification in the field, but no other flags are
  5331. defined, and no precision or type modifier can be given. For example:
  5332. printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
  5333. prints ‘hello’.
  5334. If there is an ‘l’ modifier present the argument is expected to be of
  5335. type ‘wint_t’. If used in a multibyte function the wide character is
  5336. converted into a multibyte character before being added to the output.
  5337. In this case more than one output byte can be produced.
  5338. The ‘%s’ conversion prints a string. If no ‘l’ modifier is present
  5339. the corresponding argument must be of type ‘char *’ (or ‘const char *’).
  5340. If used in a wide stream function the string is first converted to a
  5341. wide character string. A precision can be specified to indicate the
  5342. maximum number of characters to write; otherwise characters in the
  5343. string up to but not including the terminating null character are
  5344. written to the output stream. The ‘-’ flag can be used to specify
  5345. left-justification in the field, but no other flags or type modifiers
  5346. are defined for this conversion. For example:
  5347. printf ("%3s%-6s", "no", "where");
  5348. prints ‘ nowhere ’.
  5349. If there is an ‘l’ modifier present, the argument is expected to be
  5350. of type ‘wchar_t’ (or ‘const wchar_t *’).
  5351. If you accidentally pass a null pointer as the argument for a ‘%s’
  5352. conversion, the GNU C Library prints it as ‘(null)’. We think this is
  5353. more useful than crashing. But it’s not good practice to pass a null
  5354. argument intentionally.
  5355. The ‘%m’ conversion prints the string corresponding to the error code
  5356. in ‘errno’. *Note Error Messages::. Thus:
  5357. fprintf (stderr, "can't open `%s': %m\n", filename);
  5358. is equivalent to:
  5359. fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
  5360. The ‘%m’ conversion is a GNU C Library extension.
  5361. The ‘%p’ conversion prints a pointer value. The corresponding
  5362. argument must be of type ‘void *’. In practice, you can use any type of
  5363. pointer.
  5364. In the GNU C Library, non-null pointers are printed as unsigned
  5365. integers, as if a ‘%#x’ conversion were used. Null pointers print as
  5366. ‘(nil)’. (Pointers might print differently in other systems.)
  5367. For example:
  5368. printf ("%p", "testing");
  5369. prints ‘0x’ followed by a hexadecimal number—the address of the string
  5370. constant ‘"testing"’. It does not print the word ‘testing’.
  5371. You can supply the ‘-’ flag with the ‘%p’ conversion to specify
  5372. left-justification, but no other flags, precision, or type modifiers are
  5373. defined.
  5374. The ‘%n’ conversion is unlike any of the other output conversions.
  5375. It uses an argument which must be a pointer to an ‘int’, but instead of
  5376. printing anything it stores the number of characters printed so far by
  5377. this call at that location. The ‘h’ and ‘l’ type modifiers are
  5378. permitted to specify that the argument is of type ‘short int *’ or ‘long
  5379. int *’ instead of ‘int *’, but no flags, field width, or precision are
  5380. permitted.
  5381. For example,
  5382. int nchar;
  5383. printf ("%d %s%n\n", 3, "bears", &nchar);
  5384. prints:
  5385. 3 bears
  5386. and sets ‘nchar’ to ‘7’, because ‘3 bears’ is seven characters.
  5387. The ‘%%’ conversion prints a literal ‘%’ character. This conversion
  5388. doesn’t use an argument, and no flags, field width, precision, or type
  5389. modifiers are permitted.
  5390. 
  5391. File: libc.info, Node: Formatted Output Functions, Next: Dynamic Output, Prev: Other Output Conversions, Up: Formatted Output
  5392. 12.12.7 Formatted Output Functions
  5393. ----------------------------------
  5394. This section describes how to call ‘printf’ and related functions.
  5395. Prototypes for these functions are in the header file ‘stdio.h’.
  5396. Because these functions take a variable number of arguments, you _must_
  5397. declare prototypes for them before using them. Of course, the easiest
  5398. way to make sure you have all the right prototypes is to just include
  5399. ‘stdio.h’.
  5400. -- Function: int printf (const char *TEMPLATE, …)
  5401. Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
  5402. mem lock corrupt | *Note POSIX Safety Concepts::.
  5403. The ‘printf’ function prints the optional arguments under the
  5404. control of the template string TEMPLATE to the stream ‘stdout’. It
  5405. returns the number of characters printed, or a negative value if
  5406. there was an output error.
  5407. -- Function: int wprintf (const wchar_t *TEMPLATE, …)
  5408. Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
  5409. mem lock corrupt | *Note POSIX Safety Concepts::.
  5410. The ‘wprintf’ function prints the optional arguments under the
  5411. control of the wide template string TEMPLATE to the stream
  5412. ‘stdout’. It returns the number of wide characters printed, or a
  5413. negative value if there was an output error.
  5414. -- Function: int fprintf (FILE *STREAM, const char *TEMPLATE, …)
  5415. Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
  5416. mem lock corrupt | *Note POSIX Safety Concepts::.
  5417. This function is just like ‘printf’, except that the output is
  5418. written to the stream STREAM instead of ‘stdout’.
  5419. -- Function: int fwprintf (FILE *STREAM, const wchar_t *TEMPLATE, …)
  5420. Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
  5421. mem lock corrupt | *Note POSIX Safety Concepts::.
  5422. This function is just like ‘wprintf’, except that the output is
  5423. written to the stream STREAM instead of ‘stdout’.
  5424. -- Function: int sprintf (char *S, const char *TEMPLATE, …)
  5425. Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
  5426. *Note POSIX Safety Concepts::.
  5427. This is like ‘printf’, except that the output is stored in the
  5428. character array S instead of written to a stream. A null character
  5429. is written to mark the end of the string.
  5430. The ‘sprintf’ function returns the number of characters stored in
  5431. the array S, not including the terminating null character.
  5432. The behavior of this function is undefined if copying takes place
  5433. between objects that overlap—for example, if S is also given as an
  5434. argument to be printed under control of the ‘%s’ conversion. *Note
  5435. Copying Strings and Arrays::.
  5436. *Warning:* The ‘sprintf’ function can be *dangerous* because it can
  5437. potentially output more characters than can fit in the allocation
  5438. size of the string S. Remember that the field width given in a
  5439. conversion specification is only a _minimum_ value.
  5440. To avoid this problem, you can use ‘snprintf’ or ‘asprintf’,
  5441. described below.
  5442. -- Function: int swprintf (wchar_t *WS, size_t SIZE, const wchar_t
  5443. *TEMPLATE, …)
  5444. Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
  5445. *Note POSIX Safety Concepts::.
  5446. This is like ‘wprintf’, except that the output is stored in the
  5447. wide character array WS instead of written to a stream. A null
  5448. wide character is written to mark the end of the string. The SIZE
  5449. argument specifies the maximum number of characters to produce.
  5450. The trailing null character is counted towards this limit, so you
  5451. should allocate at least SIZE wide characters for the string WS.
  5452. The return value is the number of characters generated for the
  5453. given input, excluding the trailing null. If not all output fits
  5454. into the provided buffer a negative value is returned. You should
  5455. try again with a bigger output string. _Note:_ this is different
  5456. from how ‘snprintf’ handles this situation.
  5457. Note that the corresponding narrow stream function takes fewer
  5458. parameters. ‘swprintf’ in fact corresponds to the ‘snprintf’
  5459. function. Since the ‘sprintf’ function can be dangerous and should
  5460. be avoided the ISO C committee refused to make the same mistake
  5461. again and decided to not define a function exactly corresponding to
  5462. ‘sprintf’.
  5463. -- Function: int snprintf (char *S, size_t SIZE, const char *TEMPLATE,
  5464. …)
  5465. Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
  5466. *Note POSIX Safety Concepts::.
  5467. The ‘snprintf’ function is similar to ‘sprintf’, except that the
  5468. SIZE argument specifies the maximum number of characters to
  5469. produce. The trailing null character is counted towards this
  5470. limit, so you should allocate at least SIZE characters for the
  5471. string S. If SIZE is zero, nothing, not even the null byte, shall
  5472. be written and S may be a null pointer.
  5473. The return value is the number of characters which would be
  5474. generated for the given input, excluding the trailing null. If
  5475. this value is greater than or equal to SIZE, not all characters
  5476. from the result have been stored in S. You should try again with a
  5477. bigger output string. Here is an example of doing this:
  5478. /* Construct a message describing the value of a variable
  5479. whose name is NAME and whose value is VALUE. */
  5480. char *
  5481. make_message (char *name, char *value)
  5482. {
  5483. /* Guess we need no more than 100 chars of space. */
  5484. int size = 100;
  5485. char *buffer = (char *) xmalloc (size);
  5486. int nchars;
  5487. if (buffer == NULL)
  5488. return NULL;
  5489. /* Try to print in the allocated space. */
  5490. nchars = snprintf (buffer, size, "value of %s is %s",
  5491. name, value);
  5492. if (nchars >= size)
  5493. {
  5494. /* Reallocate buffer now that we know
  5495. how much space is needed. */
  5496. size = nchars + 1;
  5497. buffer = (char *) xrealloc (buffer, size);
  5498. if (buffer != NULL)
  5499. /* Try again. */
  5500. snprintf (buffer, size, "value of %s is %s",
  5501. name, value);
  5502. }
  5503. /* The last call worked, return the string. */
  5504. return buffer;
  5505. }
  5506. In practice, it is often easier just to use ‘asprintf’, below.
  5507. *Attention:* In versions of the GNU C Library prior to 2.1 the
  5508. return value is the number of characters stored, not including the
  5509. terminating null; unless there was not enough space in S to store
  5510. the result in which case ‘-1’ is returned. This was changed in
  5511. order to comply with the ISO C99 standard.
  5512. 
  5513. File: libc.info, Node: Dynamic Output, Next: Variable Arguments Output, Prev: Formatted Output Functions, Up: Formatted Output
  5514. 12.12.8 Dynamically Allocating Formatted Output
  5515. -----------------------------------------------
  5516. The functions in this section do formatted output and place the results
  5517. in dynamically allocated memory.
  5518. -- Function: int asprintf (char **PTR, const char *TEMPLATE, …)
  5519. Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
  5520. *Note POSIX Safety Concepts::.
  5521. This function is similar to ‘sprintf’, except that it dynamically
  5522. allocates a string (as with ‘malloc’; *note Unconstrained
  5523. Allocation::) to hold the output, instead of putting the output in
  5524. a buffer you allocate in advance. The PTR argument should be the
  5525. address of a ‘char *’ object, and a successful call to ‘asprintf’
  5526. stores a pointer to the newly allocated string at that location.
  5527. The return value is the number of characters allocated for the
  5528. buffer, or less than zero if an error occurred. Usually this means
  5529. that the buffer could not be allocated.
  5530. Here is how to use ‘asprintf’ to get the same result as the
  5531. ‘snprintf’ example, but more easily:
  5532. /* Construct a message describing the value of a variable
  5533. whose name is NAME and whose value is VALUE. */
  5534. char *
  5535. make_message (char *name, char *value)
  5536. {
  5537. char *result;
  5538. if (asprintf (&result, "value of %s is %s", name, value) < 0)
  5539. return NULL;
  5540. return result;
  5541. }
  5542. -- Function: int obstack_printf (struct obstack *OBSTACK, const char
  5543. *TEMPLATE, …)
  5544. Preliminary: | MT-Safe race:obstack locale | AS-Unsafe corrupt heap
  5545. | AC-Unsafe corrupt mem | *Note POSIX Safety Concepts::.
  5546. This function is similar to ‘asprintf’, except that it uses the
  5547. obstack OBSTACK to allocate the space. *Note Obstacks::.
  5548. The characters are written onto the end of the current object. To
  5549. get at them, you must finish the object with ‘obstack_finish’
  5550. (*note Growing Objects::).
  5551. 
  5552. File: libc.info, Node: Variable Arguments Output, Next: Parsing a Template String, Prev: Dynamic Output, Up: Formatted Output
  5553. 12.12.9 Variable Arguments Output Functions
  5554. -------------------------------------------
  5555. The functions ‘vprintf’ and friends are provided so that you can define
  5556. your own variadic ‘printf’-like functions that make use of the same
  5557. internals as the built-in formatted output functions.
  5558. The most natural way to define such functions would be to use a
  5559. language construct to say, “Call ‘printf’ and pass this template plus
  5560. all of my arguments after the first five.” But there is no way to do
  5561. this in C, and it would be hard to provide a way, since at the C
  5562. language level there is no way to tell how many arguments your function
  5563. received.
  5564. Since that method is impossible, we provide alternative functions,
  5565. the ‘vprintf’ series, which lets you pass a ‘va_list’ to describe “all
  5566. of my arguments after the first five.”
  5567. When it is sufficient to define a macro rather than a real function,
  5568. the GNU C compiler provides a way to do this much more easily with
  5569. macros. For example:
  5570. #define myprintf(a, b, c, d, e, rest...) \
  5571. printf (mytemplate , ## rest)
  5572. *Note (cpp)Variadic Macros::, for details. But this is limited to
  5573. macros, and does not apply to real functions at all.
  5574. Before calling ‘vprintf’ or the other functions listed in this
  5575. section, you _must_ call ‘va_start’ (*note Variadic Functions::) to
  5576. initialize a pointer to the variable arguments. Then you can call
  5577. ‘va_arg’ to fetch the arguments that you want to handle yourself. This
  5578. advances the pointer past those arguments.
  5579. Once your ‘va_list’ pointer is pointing at the argument of your
  5580. choice, you are ready to call ‘vprintf’. That argument and all
  5581. subsequent arguments that were passed to your function are used by
  5582. ‘vprintf’ along with the template that you specified separately.
  5583. *Portability Note:* The value of the ‘va_list’ pointer is
  5584. undetermined after the call to ‘vprintf’, so you must not use ‘va_arg’
  5585. after you call ‘vprintf’. Instead, you should call ‘va_end’ to retire
  5586. the pointer from service. You can call ‘va_start’ again and begin
  5587. fetching the arguments from the start of the variable argument list.
  5588. (Alternatively, you can use ‘va_copy’ to make a copy of the ‘va_list’
  5589. pointer before calling ‘vfprintf’.) Calling ‘vprintf’ does not destroy
  5590. the argument list of your function, merely the particular pointer that
  5591. you passed to it.
  5592. Prototypes for these functions are declared in ‘stdio.h’.
  5593. -- Function: int vprintf (const char *TEMPLATE, va_list AP)
  5594. Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
  5595. mem lock corrupt | *Note POSIX Safety Concepts::.
  5596. This function is similar to ‘printf’ except that, instead of taking
  5597. a variable number of arguments directly, it takes an argument list
  5598. pointer AP.
  5599. -- Function: int vwprintf (const wchar_t *TEMPLATE, va_list AP)
  5600. Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
  5601. mem lock corrupt | *Note POSIX Safety Concepts::.
  5602. This function is similar to ‘wprintf’ except that, instead of
  5603. taking a variable number of arguments directly, it takes an
  5604. argument list pointer AP.
  5605. -- Function: int vfprintf (FILE *STREAM, const char *TEMPLATE, va_list
  5606. AP)
  5607. Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
  5608. mem lock corrupt | *Note POSIX Safety Concepts::.
  5609. This is the equivalent of ‘fprintf’ with the variable argument list
  5610. specified directly as for ‘vprintf’.
  5611. -- Function: int vfwprintf (FILE *STREAM, const wchar_t *TEMPLATE,
  5612. va_list AP)
  5613. Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
  5614. mem lock corrupt | *Note POSIX Safety Concepts::.
  5615. This is the equivalent of ‘fwprintf’ with the variable argument
  5616. list specified directly as for ‘vwprintf’.
  5617. -- Function: int vsprintf (char *S, const char *TEMPLATE, va_list AP)
  5618. Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
  5619. *Note POSIX Safety Concepts::.
  5620. This is the equivalent of ‘sprintf’ with the variable argument list
  5621. specified directly as for ‘vprintf’.
  5622. -- Function: int vswprintf (wchar_t *WS, size_t SIZE, const wchar_t
  5623. *TEMPLATE, va_list AP)
  5624. Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
  5625. *Note POSIX Safety Concepts::.
  5626. This is the equivalent of ‘swprintf’ with the variable argument
  5627. list specified directly as for ‘vwprintf’.
  5628. -- Function: int vsnprintf (char *S, size_t SIZE, const char *TEMPLATE,
  5629. va_list AP)
  5630. Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
  5631. *Note POSIX Safety Concepts::.
  5632. This is the equivalent of ‘snprintf’ with the variable argument
  5633. list specified directly as for ‘vprintf’.
  5634. -- Function: int vasprintf (char **PTR, const char *TEMPLATE, va_list
  5635. AP)
  5636. Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
  5637. *Note POSIX Safety Concepts::.
  5638. The ‘vasprintf’ function is the equivalent of ‘asprintf’ with the
  5639. variable argument list specified directly as for ‘vprintf’.
  5640. -- Function: int obstack_vprintf (struct obstack *OBSTACK, const char
  5641. *TEMPLATE, va_list AP)
  5642. Preliminary: | MT-Safe race:obstack locale | AS-Unsafe corrupt heap
  5643. | AC-Unsafe corrupt mem | *Note POSIX Safety Concepts::.
  5644. The ‘obstack_vprintf’ function is the equivalent of
  5645. ‘obstack_printf’ with the variable argument list specified directly
  5646. as for ‘vprintf’.
  5647. Here’s an example showing how you might use ‘vfprintf’. This is a
  5648. function that prints error messages to the stream ‘stderr’, along with a
  5649. prefix indicating the name of the program (*note Error Messages::, for a
  5650. description of ‘program_invocation_short_name’).
  5651. #include <stdio.h>
  5652. #include <stdarg.h>
  5653. void
  5654. eprintf (const char *template, ...)
  5655. {
  5656. va_list ap;
  5657. extern char *program_invocation_short_name;
  5658. fprintf (stderr, "%s: ", program_invocation_short_name);
  5659. va_start (ap, template);
  5660. vfprintf (stderr, template, ap);
  5661. va_end (ap);
  5662. }
  5663. You could call ‘eprintf’ like this:
  5664. eprintf ("file `%s' does not exist\n", filename);
  5665. In GNU C, there is a special construct you can use to let the
  5666. compiler know that a function uses a ‘printf’-style format string. Then
  5667. it can check the number and types of arguments in each call to the
  5668. function, and warn you when they do not match the format string. For
  5669. example, take this declaration of ‘eprintf’:
  5670. void eprintf (const char *template, ...)
  5671. __attribute__ ((format (printf, 1, 2)));
  5672. This tells the compiler that ‘eprintf’ uses a format string like
  5673. ‘printf’ (as opposed to ‘scanf’; *note Formatted Input::); the format
  5674. string appears as the first argument; and the arguments to satisfy the
  5675. format begin with the second. *Note Declaring Attributes of Functions:
  5676. (gcc.info)Function Attributes, for more information.
  5677. 
  5678. File: libc.info, Node: Parsing a Template String, Next: Example of Parsing, Prev: Variable Arguments Output, Up: Formatted Output
  5679. 12.12.10 Parsing a Template String
  5680. ----------------------------------
  5681. You can use the function ‘parse_printf_format’ to obtain information
  5682. about the number and types of arguments that are expected by a given
  5683. template string. This function permits interpreters that provide
  5684. interfaces to ‘printf’ to avoid passing along invalid arguments from the
  5685. user’s program, which could cause a crash.
  5686. All the symbols described in this section are declared in the header
  5687. file ‘printf.h’.
  5688. -- Function: size_t parse_printf_format (const char *TEMPLATE, size_t
  5689. N, int *ARGTYPES)
  5690. Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
  5691. Safety Concepts::.
  5692. This function returns information about the number and types of
  5693. arguments expected by the ‘printf’ template string TEMPLATE. The
  5694. information is stored in the array ARGTYPES; each element of this
  5695. array describes one argument. This information is encoded using
  5696. the various ‘PA_’ macros, listed below.
  5697. The argument N specifies the number of elements in the array
  5698. ARGTYPES. This is the maximum number of elements that
  5699. ‘parse_printf_format’ will try to write.
  5700. ‘parse_printf_format’ returns the total number of arguments
  5701. required by TEMPLATE. If this number is greater than N, then the
  5702. information returned describes only the first N arguments. If you
  5703. want information about additional arguments, allocate a bigger
  5704. array and call ‘parse_printf_format’ again.
  5705. The argument types are encoded as a combination of a basic type and
  5706. modifier flag bits.
  5707. -- Macro: int PA_FLAG_MASK
  5708. This macro is a bitmask for the type modifier flag bits. You can
  5709. write the expression ‘(argtypes[i] & PA_FLAG_MASK)’ to extract just
  5710. the flag bits for an argument, or ‘(argtypes[i] & ~PA_FLAG_MASK)’
  5711. to extract just the basic type code.
  5712. Here are symbolic constants that represent the basic types; they
  5713. stand for integer values.
  5714. ‘PA_INT’
  5715. This specifies that the base type is ‘int’.
  5716. ‘PA_CHAR’
  5717. This specifies that the base type is ‘int’, cast to ‘char’.
  5718. ‘PA_STRING’
  5719. This specifies that the base type is ‘char *’, a null-terminated
  5720. string.
  5721. ‘PA_POINTER’
  5722. This specifies that the base type is ‘void *’, an arbitrary
  5723. pointer.
  5724. ‘PA_FLOAT’
  5725. This specifies that the base type is ‘float’.
  5726. ‘PA_DOUBLE’
  5727. This specifies that the base type is ‘double’.
  5728. ‘PA_LAST’
  5729. You can define additional base types for your own programs as
  5730. offsets from ‘PA_LAST’. For example, if you have data types ‘foo’
  5731. and ‘bar’ with their own specialized ‘printf’ conversions, you
  5732. could define encodings for these types as:
  5733. #define PA_FOO PA_LAST
  5734. #define PA_BAR (PA_LAST + 1)
  5735. Here are the flag bits that modify a basic type. They are combined
  5736. with the code for the basic type using inclusive-or.
  5737. ‘PA_FLAG_PTR’
  5738. If this bit is set, it indicates that the encoded type is a pointer
  5739. to the base type, rather than an immediate value. For example,
  5740. ‘PA_INT|PA_FLAG_PTR’ represents the type ‘int *’.
  5741. ‘PA_FLAG_SHORT’
  5742. If this bit is set, it indicates that the base type is modified
  5743. with ‘short’. (This corresponds to the ‘h’ type modifier.)
  5744. ‘PA_FLAG_LONG’
  5745. If this bit is set, it indicates that the base type is modified
  5746. with ‘long’. (This corresponds to the ‘l’ type modifier.)
  5747. ‘PA_FLAG_LONG_LONG’
  5748. If this bit is set, it indicates that the base type is modified
  5749. with ‘long long’. (This corresponds to the ‘L’ type modifier.)
  5750. ‘PA_FLAG_LONG_DOUBLE’
  5751. This is a synonym for ‘PA_FLAG_LONG_LONG’, used by convention with
  5752. a base type of ‘PA_DOUBLE’ to indicate a type of ‘long double’.
  5753. For an example of using these facilities, see *note Example of
  5754. Parsing::.
  5755. 
  5756. File: libc.info, Node: Example of Parsing, Prev: Parsing a Template String, Up: Formatted Output
  5757. 12.12.11 Example of Parsing a Template String
  5758. ---------------------------------------------
  5759. Here is an example of decoding argument types for a format string. We
  5760. assume this is part of an interpreter which contains arguments of type
  5761. ‘NUMBER’, ‘CHAR’, ‘STRING’ and ‘STRUCTURE’ (and perhaps others which are
  5762. not valid here).
  5763. /* Test whether the NARGS specified objects
  5764. in the vector ARGS are valid
  5765. for the format string FORMAT:
  5766. if so, return 1.
  5767. If not, return 0 after printing an error message. */
  5768. int
  5769. validate_args (char *format, int nargs, OBJECT *args)
  5770. {
  5771. int *argtypes;
  5772. int nwanted;
  5773. /* Get the information about the arguments.
  5774. Each conversion specification must be at least two characters
  5775. long, so there cannot be more specifications than half the
  5776. length of the string. */
  5777. argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int));
  5778. nwanted = parse_printf_format (string, nelts, argtypes);
  5779. /* Check the number of arguments. */
  5780. if (nwanted > nargs)
  5781. {
  5782. error ("too few arguments (at least %d required)", nwanted);
  5783. return 0;
  5784. }
  5785. /* Check the C type wanted for each argument
  5786. and see if the object given is suitable. */
  5787. for (i = 0; i < nwanted; i++)
  5788. {
  5789. int wanted;
  5790. if (argtypes[i] & PA_FLAG_PTR)
  5791. wanted = STRUCTURE;
  5792. else
  5793. switch (argtypes[i] & ~PA_FLAG_MASK)
  5794. {
  5795. case PA_INT:
  5796. case PA_FLOAT:
  5797. case PA_DOUBLE:
  5798. wanted = NUMBER;
  5799. break;
  5800. case PA_CHAR:
  5801. wanted = CHAR;
  5802. break;
  5803. case PA_STRING:
  5804. wanted = STRING;
  5805. break;
  5806. case PA_POINTER:
  5807. wanted = STRUCTURE;
  5808. break;
  5809. }
  5810. if (TYPE (args[i]) != wanted)
  5811. {
  5812. error ("type mismatch for arg number %d", i);
  5813. return 0;
  5814. }
  5815. }
  5816. return 1;
  5817. }
  5818. 
  5819. File: libc.info, Node: Customizing Printf, Next: Formatted Input, Prev: Formatted Output, Up: I/O on Streams
  5820. 12.13 Customizing ‘printf’
  5821. ==========================
  5822. The GNU C Library lets you define your own custom conversion specifiers
  5823. for ‘printf’ template strings, to teach ‘printf’ clever ways to print
  5824. the important data structures of your program.
  5825. The way you do this is by registering the conversion with the
  5826. function ‘register_printf_function’; see *note Registering New
  5827. Conversions::. One of the arguments you pass to this function is a
  5828. pointer to a handler function that produces the actual output; see *note
  5829. Defining the Output Handler::, for information on how to write this
  5830. function.
  5831. You can also install a function that just returns information about
  5832. the number and type of arguments expected by the conversion specifier.
  5833. *Note Parsing a Template String::, for information about this.
  5834. The facilities of this section are declared in the header file
  5835. ‘printf.h’.
  5836. * Menu:
  5837. * Registering New Conversions:: Using ‘register_printf_function’
  5838. to register a new output conversion.
  5839. * Conversion Specifier Options:: The handler must be able to get
  5840. the options specified in the
  5841. template when it is called.
  5842. * Defining the Output Handler:: Defining the handler and arginfo
  5843. functions that are passed as arguments
  5844. to ‘register_printf_function’.
  5845. * Printf Extension Example:: How to define a ‘printf’
  5846. handler function.
  5847. * Predefined Printf Handlers:: Predefined ‘printf’ handlers.
  5848. *Portability Note:* The ability to extend the syntax of ‘printf’
  5849. template strings is a GNU extension. ISO standard C has nothing
  5850. similar.
  5851. 
  5852. File: libc.info, Node: Registering New Conversions, Next: Conversion Specifier Options, Up: Customizing Printf
  5853. 12.13.1 Registering New Conversions
  5854. -----------------------------------
  5855. The function to register a new output conversion is
  5856. ‘register_printf_function’, declared in ‘printf.h’.
  5857. -- Function: int register_printf_function (int SPEC, printf_function
  5858. HANDLER-FUNCTION, printf_arginfo_function ARGINFO-FUNCTION)
  5859. Preliminary: | MT-Unsafe const:printfext | AS-Unsafe heap lock |
  5860. AC-Unsafe mem lock | *Note POSIX Safety Concepts::.
  5861. This function defines the conversion specifier character SPEC.
  5862. Thus, if SPEC is ‘'Y'’, it defines the conversion ‘%Y’. You can
  5863. redefine the built-in conversions like ‘%s’, but flag characters
  5864. like ‘#’ and type modifiers like ‘l’ can never be used as
  5865. conversions; calling ‘register_printf_function’ for those
  5866. characters has no effect. It is advisable not to use lowercase
  5867. letters, since the ISO C standard warns that additional lowercase
  5868. letters may be standardized in future editions of the standard.
  5869. The HANDLER-FUNCTION is the function called by ‘printf’ and friends
  5870. when this conversion appears in a template string. *Note Defining
  5871. the Output Handler::, for information about how to define a
  5872. function to pass as this argument. If you specify a null pointer,
  5873. any existing handler function for SPEC is removed.
  5874. The ARGINFO-FUNCTION is the function called by
  5875. ‘parse_printf_format’ when this conversion appears in a template
  5876. string. *Note Parsing a Template String::, for information about
  5877. this.
  5878. *Attention:* In the GNU C Library versions before 2.0 the
  5879. ARGINFO-FUNCTION function did not need to be installed unless the
  5880. user used the ‘parse_printf_format’ function. This has changed.
  5881. Now a call to any of the ‘printf’ functions will call this function
  5882. when this format specifier appears in the format string.
  5883. The return value is ‘0’ on success, and ‘-1’ on failure (which
  5884. occurs if SPEC is out of range).
  5885. You can redefine the standard output conversions, but this is
  5886. probably not a good idea because of the potential for confusion.
  5887. Library routines written by other people could break if you do
  5888. this.
  5889. 
  5890. File: libc.info, Node: Conversion Specifier Options, Next: Defining the Output Handler, Prev: Registering New Conversions, Up: Customizing Printf
  5891. 12.13.2 Conversion Specifier Options
  5892. ------------------------------------
  5893. If you define a meaning for ‘%A’, what if the template contains ‘%+23A’
  5894. or ‘%-#A’? To implement a sensible meaning for these, the handler when
  5895. called needs to be able to get the options specified in the template.
  5896. Both the HANDLER-FUNCTION and ARGINFO-FUNCTION accept an argument
  5897. that points to a ‘struct printf_info’, which contains information about
  5898. the options appearing in an instance of the conversion specifier. This
  5899. data type is declared in the header file ‘printf.h’.
  5900. -- Type: struct printf_info
  5901. This structure is used to pass information about the options
  5902. appearing in an instance of a conversion specifier in a ‘printf’
  5903. template string to the handler and arginfo functions for that
  5904. specifier. It contains the following members:
  5905. ‘int prec’
  5906. This is the precision specified. The value is ‘-1’ if no
  5907. precision was specified. If the precision was given as ‘*’,
  5908. the ‘printf_info’ structure passed to the handler function
  5909. contains the actual value retrieved from the argument list.
  5910. But the structure passed to the arginfo function contains a
  5911. value of ‘INT_MIN’, since the actual value is not known.
  5912. ‘int width’
  5913. This is the minimum field width specified. The value is ‘0’
  5914. if no width was specified. If the field width was given as
  5915. ‘*’, the ‘printf_info’ structure passed to the handler
  5916. function contains the actual value retrieved from the argument
  5917. list. But the structure passed to the arginfo function
  5918. contains a value of ‘INT_MIN’, since the actual value is not
  5919. known.
  5920. ‘wchar_t spec’
  5921. This is the conversion specifier character specified. It’s
  5922. stored in the structure so that you can register the same
  5923. handler function for multiple characters, but still have a way
  5924. to tell them apart when the handler function is called.
  5925. ‘unsigned int is_long_double’
  5926. This is a boolean that is true if the ‘L’, ‘ll’, or ‘q’ type
  5927. modifier was specified. For integer conversions, this
  5928. indicates ‘long long int’, as opposed to ‘long double’ for
  5929. floating point conversions.
  5930. ‘unsigned int is_char’
  5931. This is a boolean that is true if the ‘hh’ type modifier was
  5932. specified.
  5933. ‘unsigned int is_short’
  5934. This is a boolean that is true if the ‘h’ type modifier was
  5935. specified.
  5936. ‘unsigned int is_long’
  5937. This is a boolean that is true if the ‘l’ type modifier was
  5938. specified.
  5939. ‘unsigned int alt’
  5940. This is a boolean that is true if the ‘#’ flag was specified.
  5941. ‘unsigned int space’
  5942. This is a boolean that is true if the ‘ ’ flag was specified.
  5943. ‘unsigned int left’
  5944. This is a boolean that is true if the ‘-’ flag was specified.
  5945. ‘unsigned int showsign’
  5946. This is a boolean that is true if the ‘+’ flag was specified.
  5947. ‘unsigned int group’
  5948. This is a boolean that is true if the ‘'’ flag was specified.
  5949. ‘unsigned int extra’
  5950. This flag has a special meaning depending on the context. It
  5951. could be used freely by the user-defined handlers but when
  5952. called from the ‘printf’ function this variable always
  5953. contains the value ‘0’.
  5954. ‘unsigned int wide’
  5955. This flag is set if the stream is wide oriented.
  5956. ‘wchar_t pad’
  5957. This is the character to use for padding the output to the
  5958. minimum field width. The value is ‘'0'’ if the ‘0’ flag was
  5959. specified, and ‘' '’ otherwise.