12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971397239733974397539763977397839793980398139823983398439853986398739883989399039913992399339943995399639973998399940004001400240034004400540064007400840094010401140124013401440154016401740184019402040214022402340244025402640274028402940304031403240334034403540364037403840394040404140424043404440454046404740484049405040514052405340544055405640574058405940604061406240634064406540664067406840694070407140724073407440754076407740784079408040814082408340844085408640874088408940904091409240934094409540964097409840994100410141024103410441054106410741084109411041114112411341144115411641174118411941204121412241234124412541264127412841294130413141324133413441354136413741384139414041414142414341444145414641474148414941504151415241534154415541564157415841594160416141624163416441654166416741684169417041714172417341744175417641774178417941804181418241834184418541864187418841894190419141924193419441954196419741984199420042014202420342044205420642074208420942104211421242134214421542164217421842194220422142224223422442254226422742284229423042314232423342344235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262426342644265426642674268426942704271427242734274427542764277427842794280428142824283428442854286428742884289429042914292429342944295429642974298429943004301430243034304430543064307430843094310431143124313431443154316431743184319432043214322432343244325432643274328432943304331433243334334433543364337433843394340434143424343434443454346434743484349435043514352435343544355435643574358435943604361436243634364436543664367436843694370437143724373437443754376437743784379438043814382438343844385438643874388438943904391439243934394439543964397439843994400440144024403440444054406440744084409441044114412441344144415441644174418441944204421442244234424442544264427442844294430443144324433443444354436443744384439444044414442444344444445444644474448444944504451445244534454445544564457445844594460446144624463446444654466446744684469447044714472447344744475447644774478447944804481448244834484448544864487448844894490449144924493449444954496449744984499450045014502450345044505450645074508450945104511451245134514451545164517451845194520452145224523452445254526452745284529453045314532453345344535453645374538453945404541454245434544454545464547454845494550455145524553455445554556455745584559456045614562456345644565456645674568456945704571457245734574457545764577457845794580458145824583458445854586458745884589459045914592459345944595459645974598459946004601460246034604460546064607460846094610461146124613461446154616461746184619462046214622462346244625462646274628462946304631463246334634463546364637463846394640464146424643464446454646464746484649465046514652465346544655465646574658465946604661466246634664466546664667466846694670467146724673467446754676467746784679468046814682468346844685468646874688468946904691469246934694469546964697469846994700470147024703470447054706470747084709471047114712471347144715471647174718471947204721472247234724472547264727472847294730473147324733473447354736473747384739474047414742474347444745474647474748474947504751475247534754475547564757475847594760476147624763476447654766476747684769477047714772477347744775477647774778477947804781478247834784478547864787478847894790479147924793479447954796479747984799480048014802480348044805480648074808480948104811481248134814481548164817481848194820482148224823482448254826482748284829483048314832483348344835483648374838483948404841484248434844484548464847484848494850485148524853485448554856485748584859486048614862486348644865486648674868486948704871487248734874487548764877487848794880488148824883488448854886488748884889489048914892489348944895489648974898489949004901490249034904490549064907490849094910491149124913491449154916491749184919492049214922492349244925492649274928492949304931493249334934493549364937493849394940494149424943494449454946494749484949495049514952495349544955495649574958495949604961496249634964496549664967496849694970497149724973497449754976497749784979498049814982498349844985498649874988498949904991499249934994499549964997499849995000500150025003500450055006500750085009501050115012501350145015501650175018501950205021502250235024502550265027502850295030503150325033503450355036503750385039504050415042504350445045504650475048504950505051505250535054505550565057505850595060506150625063506450655066506750685069507050715072507350745075507650775078507950805081508250835084508550865087508850895090509150925093509450955096509750985099510051015102510351045105510651075108510951105111511251135114511551165117511851195120512151225123512451255126512751285129513051315132513351345135513651375138513951405141514251435144514551465147514851495150515151525153515451555156515751585159516051615162516351645165516651675168516951705171517251735174517551765177517851795180518151825183518451855186518751885189519051915192519351945195519651975198519952005201520252035204520552065207520852095210521152125213521452155216521752185219522052215222522352245225522652275228522952305231523252335234523552365237523852395240524152425243524452455246524752485249525052515252525352545255525652575258525952605261526252635264526552665267526852695270527152725273527452755276527752785279528052815282528352845285528652875288528952905291529252935294529552965297529852995300530153025303530453055306530753085309531053115312531353145315531653175318531953205321532253235324532553265327532853295330533153325333533453355336533753385339534053415342534353445345534653475348534953505351535253535354535553565357535853595360536153625363536453655366536753685369537053715372537353745375537653775378537953805381538253835384538553865387538853895390539153925393539453955396539753985399540054015402540354045405540654075408540954105411541254135414541554165417541854195420542154225423542454255426542754285429543054315432543354345435543654375438543954405441544254435444544554465447544854495450545154525453545454555456545754585459546054615462546354645465546654675468546954705471547254735474547554765477547854795480548154825483548454855486548754885489549054915492549354945495549654975498549955005501550255035504550555065507550855095510551155125513551455155516551755185519552055215522552355245525552655275528552955305531553255335534553555365537553855395540554155425543554455455546554755485549555055515552555355545555555655575558555955605561556255635564556555665567556855695570557155725573557455755576557755785579558055815582558355845585558655875588558955905591559255935594559555965597559855995600560156025603560456055606560756085609561056115612561356145615561656175618561956205621562256235624562556265627562856295630563156325633563456355636563756385639564056415642564356445645564656475648564956505651565256535654565556565657565856595660566156625663566456655666566756685669567056715672567356745675567656775678567956805681568256835684568556865687568856895690569156925693569456955696569756985699570057015702570357045705570657075708570957105711571257135714571557165717571857195720572157225723572457255726572757285729573057315732573357345735573657375738573957405741574257435744574557465747574857495750575157525753575457555756575757585759576057615762576357645765576657675768576957705771577257735774577557765777577857795780578157825783578457855786578757885789579057915792579357945795579657975798579958005801580258035804580558065807580858095810581158125813581458155816581758185819582058215822582358245825582658275828582958305831583258335834583558365837583858395840584158425843584458455846584758485849585058515852585358545855585658575858585958605861586258635864586558665867586858695870587158725873587458755876587758785879588058815882588358845885588658875888588958905891589258935894589558965897589858995900590159025903590459055906590759085909591059115912591359145915591659175918591959205921592259235924592559265927592859295930593159325933593459355936593759385939594059415942594359445945594659475948594959505951595259535954595559565957595859595960596159625963596459655966596759685969597059715972597359745975597659775978597959805981598259835984598559865987598859895990599159925993599459955996599759985999600060016002600360046005600660076008600960106011601260136014601560166017601860196020602160226023602460256026602760286029603060316032603360346035603660376038603960406041604260436044604560466047604860496050605160526053605460556056605760586059606060616062606360646065606660676068606960706071607260736074607560766077607860796080608160826083608460856086608760886089609060916092609360946095609660976098609961006101610261036104610561066107610861096110611161126113611461156116611761186119612061216122612361246125612661276128612961306131613261336134613561366137613861396140614161426143614461456146614761486149615061516152615361546155615661576158615961606161616261636164616561666167616861696170617161726173617461756176617761786179618061816182618361846185618661876188618961906191619261936194619561966197619861996200620162026203620462056206620762086209621062116212621362146215621662176218621962206221622262236224622562266227622862296230623162326233623462356236623762386239624062416242624362446245624662476248624962506251625262536254625562566257625862596260626162626263626462656266626762686269627062716272627362746275627662776278627962806281628262836284628562866287628862896290629162926293629462956296629762986299630063016302630363046305630663076308630963106311631263136314631563166317631863196320632163226323632463256326632763286329633063316332633363346335633663376338633963406341634263436344634563466347634863496350635163526353635463556356635763586359636063616362636363646365636663676368636963706371637263736374637563766377637863796380638163826383638463856386638763886389639063916392639363946395639663976398639964006401640264036404640564066407640864096410641164126413641464156416641764186419642064216422642364246425642664276428642964306431643264336434643564366437643864396440644164426443644464456446644764486449645064516452645364546455645664576458645964606461646264636464646564666467646864696470647164726473647464756476647764786479648064816482648364846485648664876488648964906491649264936494649564966497649864996500650165026503650465056506650765086509651065116512651365146515651665176518651965206521652265236524652565266527652865296530653165326533653465356536653765386539654065416542654365446545654665476548654965506551655265536554655565566557655865596560656165626563656465656566656765686569657065716572657365746575657665776578657965806581658265836584658565866587658865896590659165926593659465956596659765986599660066016602660366046605660666076608660966106611661266136614661566166617661866196620662166226623662466256626662766286629663066316632663366346635663666376638663966406641664266436644664566466647664866496650665166526653665466556656665766586659666066616662666366646665666666676668666966706671667266736674667566766677667866796680668166826683668466856686668766886689669066916692669366946695669666976698669967006701670267036704670567066707670867096710671167126713671467156716671767186719672067216722672367246725672667276728672967306731673267336734673567366737673867396740674167426743674467456746674767486749675067516752675367546755675667576758675967606761676267636764676567666767676867696770677167726773677467756776677767786779678067816782678367846785678667876788678967906791679267936794679567966797679867996800680168026803680468056806680768086809681068116812681368146815681668176818681968206821682268236824682568266827682868296830683168326833683468356836683768386839684068416842684368446845684668476848684968506851685268536854685568566857685868596860686168626863686468656866686768686869687068716872687368746875687668776878687968806881688268836884688568866887688868896890689168926893689468956896689768986899690069016902690369046905690669076908690969106911691269136914691569166917691869196920692169226923692469256926692769286929693069316932693369346935693669376938693969406941694269436944694569466947694869496950695169526953695469556956695769586959696069616962696369646965696669676968696969706971697269736974697569766977697869796980698169826983698469856986698769886989699069916992699369946995699669976998699970007001700270037004700570067007700870097010701170127013701470157016701770187019702070217022702370247025702670277028702970307031703270337034703570367037703870397040704170427043704470457046704770487049705070517052705370547055705670577058705970607061706270637064706570667067706870697070707170727073707470757076 |
- This is libc.info, produced by makeinfo version 5.2 from libc.texinfo.
- This file documents the GNU C Library.
- This is ‘The GNU C Library Reference Manual’, for version 2.25.
- Copyright © 1993–2017 Free Software Foundation, Inc.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.3 or
- any later version published by the Free Software Foundation; with the
- Invariant Sections being “Free Software Needs Free Documentation” and
- “GNU Lesser General Public License”, the Front-Cover texts being “A GNU
- Manual”, and with the Back-Cover Texts as in (a) below. A copy of the
- license is included in the section entitled "GNU Free Documentation
- License".
- (a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
- modify this GNU manual. Buying copies from the FSF supports it in
- developing GNU and promoting software freedom.”
- INFO-DIR-SECTION Software libraries
- START-INFO-DIR-ENTRY
- * Libc: (libc). C library.
- END-INFO-DIR-ENTRY
- INFO-DIR-SECTION GNU C library functions and macros
- START-INFO-DIR-ENTRY
- * a64l: (libc)Encode Binary Data.
- * abort: (libc)Aborting a Program.
- * abs: (libc)Absolute Value.
- * accept: (libc)Accepting Connections.
- * access: (libc)Testing File Access.
- * acosf: (libc)Inverse Trig Functions.
- * acoshf: (libc)Hyperbolic Functions.
- * acosh: (libc)Hyperbolic Functions.
- * acoshl: (libc)Hyperbolic Functions.
- * acos: (libc)Inverse Trig Functions.
- * acosl: (libc)Inverse Trig Functions.
- * addmntent: (libc)mtab.
- * addseverity: (libc)Adding Severity Classes.
- * adjtime: (libc)High-Resolution Calendar.
- * adjtimex: (libc)High-Resolution Calendar.
- * aio_cancel64: (libc)Cancel AIO Operations.
- * aio_cancel: (libc)Cancel AIO Operations.
- * aio_error64: (libc)Status of AIO Operations.
- * aio_error: (libc)Status of AIO Operations.
- * aio_fsync64: (libc)Synchronizing AIO Operations.
- * aio_fsync: (libc)Synchronizing AIO Operations.
- * aio_init: (libc)Configuration of AIO.
- * aio_read64: (libc)Asynchronous Reads/Writes.
- * aio_read: (libc)Asynchronous Reads/Writes.
- * aio_return64: (libc)Status of AIO Operations.
- * aio_return: (libc)Status of AIO Operations.
- * aio_suspend64: (libc)Synchronizing AIO Operations.
- * aio_suspend: (libc)Synchronizing AIO Operations.
- * aio_write64: (libc)Asynchronous Reads/Writes.
- * aio_write: (libc)Asynchronous Reads/Writes.
- * alarm: (libc)Setting an Alarm.
- * aligned_alloc: (libc)Aligned Memory Blocks.
- * alloca: (libc)Variable Size Automatic.
- * alphasort64: (libc)Scanning Directory Content.
- * alphasort: (libc)Scanning Directory Content.
- * ALTWERASE: (libc)Local Modes.
- * ARG_MAX: (libc)General Limits.
- * argp_error: (libc)Argp Helper Functions.
- * ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions.
- * argp_failure: (libc)Argp Helper Functions.
- * argp_help: (libc)Argp Help.
- * argp_parse: (libc)Argp.
- * argp_state_help: (libc)Argp Helper Functions.
- * argp_usage: (libc)Argp Helper Functions.
- * argz_add: (libc)Argz Functions.
- * argz_add_sep: (libc)Argz Functions.
- * argz_append: (libc)Argz Functions.
- * argz_count: (libc)Argz Functions.
- * argz_create: (libc)Argz Functions.
- * argz_create_sep: (libc)Argz Functions.
- * argz_delete: (libc)Argz Functions.
- * argz_extract: (libc)Argz Functions.
- * argz_insert: (libc)Argz Functions.
- * argz_next: (libc)Argz Functions.
- * argz_replace: (libc)Argz Functions.
- * argz_stringify: (libc)Argz Functions.
- * asctime: (libc)Formatting Calendar Time.
- * asctime_r: (libc)Formatting Calendar Time.
- * asinf: (libc)Inverse Trig Functions.
- * asinhf: (libc)Hyperbolic Functions.
- * asinh: (libc)Hyperbolic Functions.
- * asinhl: (libc)Hyperbolic Functions.
- * asin: (libc)Inverse Trig Functions.
- * asinl: (libc)Inverse Trig Functions.
- * asprintf: (libc)Dynamic Output.
- * assert: (libc)Consistency Checking.
- * assert_perror: (libc)Consistency Checking.
- * atan2f: (libc)Inverse Trig Functions.
- * atan2: (libc)Inverse Trig Functions.
- * atan2l: (libc)Inverse Trig Functions.
- * atanf: (libc)Inverse Trig Functions.
- * atanhf: (libc)Hyperbolic Functions.
- * atanh: (libc)Hyperbolic Functions.
- * atanhl: (libc)Hyperbolic Functions.
- * atan: (libc)Inverse Trig Functions.
- * atanl: (libc)Inverse Trig Functions.
- * atexit: (libc)Cleanups on Exit.
- * atof: (libc)Parsing of Floats.
- * atoi: (libc)Parsing of Integers.
- * atol: (libc)Parsing of Integers.
- * atoll: (libc)Parsing of Integers.
- * backtrace: (libc)Backtraces.
- * backtrace_symbols_fd: (libc)Backtraces.
- * backtrace_symbols: (libc)Backtraces.
- * basename: (libc)Finding Tokens in a String.
- * basename: (libc)Finding Tokens in a String.
- * BC_BASE_MAX: (libc)Utility Limits.
- * BC_DIM_MAX: (libc)Utility Limits.
- * bcmp: (libc)String/Array Comparison.
- * bcopy: (libc)Copying Strings and Arrays.
- * BC_SCALE_MAX: (libc)Utility Limits.
- * BC_STRING_MAX: (libc)Utility Limits.
- * bind: (libc)Setting Address.
- * bind_textdomain_codeset: (libc)Charset conversion in gettext.
- * bindtextdomain: (libc)Locating gettext catalog.
- * BRKINT: (libc)Input Modes.
- * brk: (libc)Resizing the Data Segment.
- * bsearch: (libc)Array Search Function.
- * btowc: (libc)Converting a Character.
- * BUFSIZ: (libc)Controlling Buffering.
- * bzero: (libc)Copying Strings and Arrays.
- * cabsf: (libc)Absolute Value.
- * cabs: (libc)Absolute Value.
- * cabsl: (libc)Absolute Value.
- * cacosf: (libc)Inverse Trig Functions.
- * cacoshf: (libc)Hyperbolic Functions.
- * cacosh: (libc)Hyperbolic Functions.
- * cacoshl: (libc)Hyperbolic Functions.
- * cacos: (libc)Inverse Trig Functions.
- * cacosl: (libc)Inverse Trig Functions.
- * calloc: (libc)Allocating Cleared Space.
- * canonicalize_file_name: (libc)Symbolic Links.
- * canonicalizef: (libc)FP Bit Twiddling.
- * canonicalize: (libc)FP Bit Twiddling.
- * canonicalizel: (libc)FP Bit Twiddling.
- * cargf: (libc)Operations on Complex.
- * carg: (libc)Operations on Complex.
- * cargl: (libc)Operations on Complex.
- * casinf: (libc)Inverse Trig Functions.
- * casinhf: (libc)Hyperbolic Functions.
- * casinh: (libc)Hyperbolic Functions.
- * casinhl: (libc)Hyperbolic Functions.
- * casin: (libc)Inverse Trig Functions.
- * casinl: (libc)Inverse Trig Functions.
- * catanf: (libc)Inverse Trig Functions.
- * catanhf: (libc)Hyperbolic Functions.
- * catanh: (libc)Hyperbolic Functions.
- * catanhl: (libc)Hyperbolic Functions.
- * catan: (libc)Inverse Trig Functions.
- * catanl: (libc)Inverse Trig Functions.
- * catclose: (libc)The catgets Functions.
- * catgets: (libc)The catgets Functions.
- * catopen: (libc)The catgets Functions.
- * cbc_crypt: (libc)DES Encryption.
- * cbrtf: (libc)Exponents and Logarithms.
- * cbrt: (libc)Exponents and Logarithms.
- * cbrtl: (libc)Exponents and Logarithms.
- * ccosf: (libc)Trig Functions.
- * ccoshf: (libc)Hyperbolic Functions.
- * ccosh: (libc)Hyperbolic Functions.
- * ccoshl: (libc)Hyperbolic Functions.
- * ccos: (libc)Trig Functions.
- * ccosl: (libc)Trig Functions.
- * CCTS_OFLOW: (libc)Control Modes.
- * ceilf: (libc)Rounding Functions.
- * ceil: (libc)Rounding Functions.
- * ceill: (libc)Rounding Functions.
- * cexpf: (libc)Exponents and Logarithms.
- * cexp: (libc)Exponents and Logarithms.
- * cexpl: (libc)Exponents and Logarithms.
- * cfgetispeed: (libc)Line Speed.
- * cfgetospeed: (libc)Line Speed.
- * cfmakeraw: (libc)Noncanonical Input.
- * cfree: (libc)Freeing after Malloc.
- * cfsetispeed: (libc)Line Speed.
- * cfsetospeed: (libc)Line Speed.
- * cfsetspeed: (libc)Line Speed.
- * chdir: (libc)Working Directory.
- * CHILD_MAX: (libc)General Limits.
- * chmod: (libc)Setting Permissions.
- * chown: (libc)File Owner.
- * CIGNORE: (libc)Control Modes.
- * cimagf: (libc)Operations on Complex.
- * cimag: (libc)Operations on Complex.
- * cimagl: (libc)Operations on Complex.
- * clearenv: (libc)Environment Access.
- * clearerr: (libc)Error Recovery.
- * clearerr_unlocked: (libc)Error Recovery.
- * CLK_TCK: (libc)Processor Time.
- * CLOCAL: (libc)Control Modes.
- * clock: (libc)CPU Time.
- * CLOCKS_PER_SEC: (libc)CPU Time.
- * clog10f: (libc)Exponents and Logarithms.
- * clog10: (libc)Exponents and Logarithms.
- * clog10l: (libc)Exponents and Logarithms.
- * clogf: (libc)Exponents and Logarithms.
- * clog: (libc)Exponents and Logarithms.
- * clogl: (libc)Exponents and Logarithms.
- * closedir: (libc)Reading/Closing Directory.
- * close: (libc)Opening and Closing Files.
- * closelog: (libc)closelog.
- * COLL_WEIGHTS_MAX: (libc)Utility Limits.
- * _Complex_I: (libc)Complex Numbers.
- * confstr: (libc)String Parameters.
- * conjf: (libc)Operations on Complex.
- * conj: (libc)Operations on Complex.
- * conjl: (libc)Operations on Complex.
- * connect: (libc)Connecting.
- * copysignf: (libc)FP Bit Twiddling.
- * copysign: (libc)FP Bit Twiddling.
- * copysignl: (libc)FP Bit Twiddling.
- * cosf: (libc)Trig Functions.
- * coshf: (libc)Hyperbolic Functions.
- * cosh: (libc)Hyperbolic Functions.
- * coshl: (libc)Hyperbolic Functions.
- * cos: (libc)Trig Functions.
- * cosl: (libc)Trig Functions.
- * cpowf: (libc)Exponents and Logarithms.
- * cpow: (libc)Exponents and Logarithms.
- * cpowl: (libc)Exponents and Logarithms.
- * cprojf: (libc)Operations on Complex.
- * cproj: (libc)Operations on Complex.
- * cprojl: (libc)Operations on Complex.
- * CPU_CLR: (libc)CPU Affinity.
- * CPU_ISSET: (libc)CPU Affinity.
- * CPU_SET: (libc)CPU Affinity.
- * CPU_SETSIZE: (libc)CPU Affinity.
- * CPU_ZERO: (libc)CPU Affinity.
- * CREAD: (libc)Control Modes.
- * crealf: (libc)Operations on Complex.
- * creal: (libc)Operations on Complex.
- * creall: (libc)Operations on Complex.
- * creat64: (libc)Opening and Closing Files.
- * creat: (libc)Opening and Closing Files.
- * CRTS_IFLOW: (libc)Control Modes.
- * crypt: (libc)crypt.
- * crypt_r: (libc)crypt.
- * CS5: (libc)Control Modes.
- * CS6: (libc)Control Modes.
- * CS7: (libc)Control Modes.
- * CS8: (libc)Control Modes.
- * csinf: (libc)Trig Functions.
- * csinhf: (libc)Hyperbolic Functions.
- * csinh: (libc)Hyperbolic Functions.
- * csinhl: (libc)Hyperbolic Functions.
- * csin: (libc)Trig Functions.
- * csinl: (libc)Trig Functions.
- * CSIZE: (libc)Control Modes.
- * csqrtf: (libc)Exponents and Logarithms.
- * csqrt: (libc)Exponents and Logarithms.
- * csqrtl: (libc)Exponents and Logarithms.
- * CSTOPB: (libc)Control Modes.
- * ctanf: (libc)Trig Functions.
- * ctanhf: (libc)Hyperbolic Functions.
- * ctanh: (libc)Hyperbolic Functions.
- * ctanhl: (libc)Hyperbolic Functions.
- * ctan: (libc)Trig Functions.
- * ctanl: (libc)Trig Functions.
- * ctermid: (libc)Identifying the Terminal.
- * ctime: (libc)Formatting Calendar Time.
- * ctime_r: (libc)Formatting Calendar Time.
- * cuserid: (libc)Who Logged In.
- * dcgettext: (libc)Translation with gettext.
- * dcngettext: (libc)Advanced gettext functions.
- * DES_FAILED: (libc)DES Encryption.
- * des_setparity: (libc)DES Encryption.
- * dgettext: (libc)Translation with gettext.
- * difftime: (libc)Elapsed Time.
- * dirfd: (libc)Opening a Directory.
- * dirname: (libc)Finding Tokens in a String.
- * div: (libc)Integer Division.
- * dngettext: (libc)Advanced gettext functions.
- * drand48: (libc)SVID Random.
- * drand48_r: (libc)SVID Random.
- * dremf: (libc)Remainder Functions.
- * drem: (libc)Remainder Functions.
- * dreml: (libc)Remainder Functions.
- * DTTOIF: (libc)Directory Entries.
- * dup2: (libc)Duplicating Descriptors.
- * dup: (libc)Duplicating Descriptors.
- * E2BIG: (libc)Error Codes.
- * EACCES: (libc)Error Codes.
- * EADDRINUSE: (libc)Error Codes.
- * EADDRNOTAVAIL: (libc)Error Codes.
- * EADV: (libc)Error Codes.
- * EAFNOSUPPORT: (libc)Error Codes.
- * EAGAIN: (libc)Error Codes.
- * EALREADY: (libc)Error Codes.
- * EAUTH: (libc)Error Codes.
- * EBACKGROUND: (libc)Error Codes.
- * EBADE: (libc)Error Codes.
- * EBADFD: (libc)Error Codes.
- * EBADF: (libc)Error Codes.
- * EBADMSG: (libc)Error Codes.
- * EBADR: (libc)Error Codes.
- * EBADRPC: (libc)Error Codes.
- * EBADRQC: (libc)Error Codes.
- * EBADSLT: (libc)Error Codes.
- * EBFONT: (libc)Error Codes.
- * EBUSY: (libc)Error Codes.
- * ECANCELED: (libc)Error Codes.
- * ecb_crypt: (libc)DES Encryption.
- * ECHILD: (libc)Error Codes.
- * ECHOCTL: (libc)Local Modes.
- * ECHOE: (libc)Local Modes.
- * ECHOKE: (libc)Local Modes.
- * ECHOK: (libc)Local Modes.
- * ECHO: (libc)Local Modes.
- * ECHONL: (libc)Local Modes.
- * ECHOPRT: (libc)Local Modes.
- * ECHRNG: (libc)Error Codes.
- * ECOMM: (libc)Error Codes.
- * ECONNABORTED: (libc)Error Codes.
- * ECONNREFUSED: (libc)Error Codes.
- * ECONNRESET: (libc)Error Codes.
- * ecvt: (libc)System V Number Conversion.
- * ecvt_r: (libc)System V Number Conversion.
- * EDEADLK: (libc)Error Codes.
- * EDEADLOCK: (libc)Error Codes.
- * EDESTADDRREQ: (libc)Error Codes.
- * EDIED: (libc)Error Codes.
- * ED: (libc)Error Codes.
- * EDOM: (libc)Error Codes.
- * EDOTDOT: (libc)Error Codes.
- * EDQUOT: (libc)Error Codes.
- * EEXIST: (libc)Error Codes.
- * EFAULT: (libc)Error Codes.
- * EFBIG: (libc)Error Codes.
- * EFTYPE: (libc)Error Codes.
- * EGRATUITOUS: (libc)Error Codes.
- * EGREGIOUS: (libc)Error Codes.
- * EHOSTDOWN: (libc)Error Codes.
- * EHOSTUNREACH: (libc)Error Codes.
- * EHWPOISON: (libc)Error Codes.
- * EIDRM: (libc)Error Codes.
- * EIEIO: (libc)Error Codes.
- * EILSEQ: (libc)Error Codes.
- * EINPROGRESS: (libc)Error Codes.
- * EINTR: (libc)Error Codes.
- * EINVAL: (libc)Error Codes.
- * EIO: (libc)Error Codes.
- * EISCONN: (libc)Error Codes.
- * EISDIR: (libc)Error Codes.
- * EISNAM: (libc)Error Codes.
- * EKEYEXPIRED: (libc)Error Codes.
- * EKEYREJECTED: (libc)Error Codes.
- * EKEYREVOKED: (libc)Error Codes.
- * EL2HLT: (libc)Error Codes.
- * EL2NSYNC: (libc)Error Codes.
- * EL3HLT: (libc)Error Codes.
- * EL3RST: (libc)Error Codes.
- * ELIBACC: (libc)Error Codes.
- * ELIBBAD: (libc)Error Codes.
- * ELIBEXEC: (libc)Error Codes.
- * ELIBMAX: (libc)Error Codes.
- * ELIBSCN: (libc)Error Codes.
- * ELNRNG: (libc)Error Codes.
- * ELOOP: (libc)Error Codes.
- * EMEDIUMTYPE: (libc)Error Codes.
- * EMFILE: (libc)Error Codes.
- * EMLINK: (libc)Error Codes.
- * EMSGSIZE: (libc)Error Codes.
- * EMULTIHOP: (libc)Error Codes.
- * ENAMETOOLONG: (libc)Error Codes.
- * ENAVAIL: (libc)Error Codes.
- * encrypt: (libc)DES Encryption.
- * encrypt_r: (libc)DES Encryption.
- * endfsent: (libc)fstab.
- * endgrent: (libc)Scanning All Groups.
- * endhostent: (libc)Host Names.
- * endmntent: (libc)mtab.
- * endnetent: (libc)Networks Database.
- * endnetgrent: (libc)Lookup Netgroup.
- * endprotoent: (libc)Protocols Database.
- * endpwent: (libc)Scanning All Users.
- * endservent: (libc)Services Database.
- * endutent: (libc)Manipulating the Database.
- * endutxent: (libc)XPG Functions.
- * ENEEDAUTH: (libc)Error Codes.
- * ENETDOWN: (libc)Error Codes.
- * ENETRESET: (libc)Error Codes.
- * ENETUNREACH: (libc)Error Codes.
- * ENFILE: (libc)Error Codes.
- * ENOANO: (libc)Error Codes.
- * ENOBUFS: (libc)Error Codes.
- * ENOCSI: (libc)Error Codes.
- * ENODATA: (libc)Error Codes.
- * ENODEV: (libc)Error Codes.
- * ENOENT: (libc)Error Codes.
- * ENOEXEC: (libc)Error Codes.
- * ENOKEY: (libc)Error Codes.
- * ENOLCK: (libc)Error Codes.
- * ENOLINK: (libc)Error Codes.
- * ENOMEDIUM: (libc)Error Codes.
- * ENOMEM: (libc)Error Codes.
- * ENOMSG: (libc)Error Codes.
- * ENONET: (libc)Error Codes.
- * ENOPKG: (libc)Error Codes.
- * ENOPROTOOPT: (libc)Error Codes.
- * ENOSPC: (libc)Error Codes.
- * ENOSR: (libc)Error Codes.
- * ENOSTR: (libc)Error Codes.
- * ENOSYS: (libc)Error Codes.
- * ENOTBLK: (libc)Error Codes.
- * ENOTCONN: (libc)Error Codes.
- * ENOTDIR: (libc)Error Codes.
- * ENOTEMPTY: (libc)Error Codes.
- * ENOTNAM: (libc)Error Codes.
- * ENOTRECOVERABLE: (libc)Error Codes.
- * ENOTSOCK: (libc)Error Codes.
- * ENOTSUP: (libc)Error Codes.
- * ENOTTY: (libc)Error Codes.
- * ENOTUNIQ: (libc)Error Codes.
- * envz_add: (libc)Envz Functions.
- * envz_entry: (libc)Envz Functions.
- * envz_get: (libc)Envz Functions.
- * envz_merge: (libc)Envz Functions.
- * envz_remove: (libc)Envz Functions.
- * envz_strip: (libc)Envz Functions.
- * ENXIO: (libc)Error Codes.
- * EOF: (libc)EOF and Errors.
- * EOPNOTSUPP: (libc)Error Codes.
- * EOVERFLOW: (libc)Error Codes.
- * EOWNERDEAD: (libc)Error Codes.
- * EPERM: (libc)Error Codes.
- * EPFNOSUPPORT: (libc)Error Codes.
- * EPIPE: (libc)Error Codes.
- * EPROCLIM: (libc)Error Codes.
- * EPROCUNAVAIL: (libc)Error Codes.
- * EPROGMISMATCH: (libc)Error Codes.
- * EPROGUNAVAIL: (libc)Error Codes.
- * EPROTO: (libc)Error Codes.
- * EPROTONOSUPPORT: (libc)Error Codes.
- * EPROTOTYPE: (libc)Error Codes.
- * EQUIV_CLASS_MAX: (libc)Utility Limits.
- * erand48: (libc)SVID Random.
- * erand48_r: (libc)SVID Random.
- * ERANGE: (libc)Error Codes.
- * EREMCHG: (libc)Error Codes.
- * EREMOTEIO: (libc)Error Codes.
- * EREMOTE: (libc)Error Codes.
- * ERESTART: (libc)Error Codes.
- * erfcf: (libc)Special Functions.
- * erfc: (libc)Special Functions.
- * erfcl: (libc)Special Functions.
- * erff: (libc)Special Functions.
- * ERFKILL: (libc)Error Codes.
- * erf: (libc)Special Functions.
- * erfl: (libc)Special Functions.
- * EROFS: (libc)Error Codes.
- * ERPCMISMATCH: (libc)Error Codes.
- * err: (libc)Error Messages.
- * errno: (libc)Checking for Errors.
- * error_at_line: (libc)Error Messages.
- * error: (libc)Error Messages.
- * errx: (libc)Error Messages.
- * ESHUTDOWN: (libc)Error Codes.
- * ESOCKTNOSUPPORT: (libc)Error Codes.
- * ESPIPE: (libc)Error Codes.
- * ESRCH: (libc)Error Codes.
- * ESRMNT: (libc)Error Codes.
- * ESTALE: (libc)Error Codes.
- * ESTRPIPE: (libc)Error Codes.
- * ETIMEDOUT: (libc)Error Codes.
- * ETIME: (libc)Error Codes.
- * ETOOMANYREFS: (libc)Error Codes.
- * ETXTBSY: (libc)Error Codes.
- * EUCLEAN: (libc)Error Codes.
- * EUNATCH: (libc)Error Codes.
- * EUSERS: (libc)Error Codes.
- * EWOULDBLOCK: (libc)Error Codes.
- * EXDEV: (libc)Error Codes.
- * execle: (libc)Executing a File.
- * execl: (libc)Executing a File.
- * execlp: (libc)Executing a File.
- * execve: (libc)Executing a File.
- * execv: (libc)Executing a File.
- * execvp: (libc)Executing a File.
- * EXFULL: (libc)Error Codes.
- * EXIT_FAILURE: (libc)Exit Status.
- * exit: (libc)Normal Termination.
- * _exit: (libc)Termination Internals.
- * _Exit: (libc)Termination Internals.
- * EXIT_SUCCESS: (libc)Exit Status.
- * exp10f: (libc)Exponents and Logarithms.
- * exp10: (libc)Exponents and Logarithms.
- * exp10l: (libc)Exponents and Logarithms.
- * exp2f: (libc)Exponents and Logarithms.
- * exp2: (libc)Exponents and Logarithms.
- * exp2l: (libc)Exponents and Logarithms.
- * expf: (libc)Exponents and Logarithms.
- * exp: (libc)Exponents and Logarithms.
- * explicit_bzero: (libc)Erasing Sensitive Data.
- * expl: (libc)Exponents and Logarithms.
- * expm1f: (libc)Exponents and Logarithms.
- * expm1: (libc)Exponents and Logarithms.
- * expm1l: (libc)Exponents and Logarithms.
- * EXPR_NEST_MAX: (libc)Utility Limits.
- * fabsf: (libc)Absolute Value.
- * fabs: (libc)Absolute Value.
- * fabsl: (libc)Absolute Value.
- * __fbufsize: (libc)Controlling Buffering.
- * fchdir: (libc)Working Directory.
- * fchmod: (libc)Setting Permissions.
- * fchown: (libc)File Owner.
- * fcloseall: (libc)Closing Streams.
- * fclose: (libc)Closing Streams.
- * fcntl: (libc)Control Operations.
- * fcvt: (libc)System V Number Conversion.
- * fcvt_r: (libc)System V Number Conversion.
- * fdatasync: (libc)Synchronizing I/O.
- * FD_CLOEXEC: (libc)Descriptor Flags.
- * FD_CLR: (libc)Waiting for I/O.
- * fdimf: (libc)Misc FP Arithmetic.
- * fdim: (libc)Misc FP Arithmetic.
- * fdiml: (libc)Misc FP Arithmetic.
- * FD_ISSET: (libc)Waiting for I/O.
- * fdopendir: (libc)Opening a Directory.
- * fdopen: (libc)Descriptors and Streams.
- * FD_SET: (libc)Waiting for I/O.
- * FD_SETSIZE: (libc)Waiting for I/O.
- * F_DUPFD: (libc)Duplicating Descriptors.
- * FD_ZERO: (libc)Waiting for I/O.
- * feclearexcept: (libc)Status bit operations.
- * fedisableexcept: (libc)Control Functions.
- * feenableexcept: (libc)Control Functions.
- * fegetenv: (libc)Control Functions.
- * fegetexceptflag: (libc)Status bit operations.
- * fegetexcept: (libc)Control Functions.
- * fegetmode: (libc)Control Functions.
- * fegetround: (libc)Rounding.
- * feholdexcept: (libc)Control Functions.
- * feof: (libc)EOF and Errors.
- * feof_unlocked: (libc)EOF and Errors.
- * feraiseexcept: (libc)Status bit operations.
- * ferror: (libc)EOF and Errors.
- * ferror_unlocked: (libc)EOF and Errors.
- * fesetenv: (libc)Control Functions.
- * fesetexceptflag: (libc)Status bit operations.
- * fesetexcept: (libc)Status bit operations.
- * fesetmode: (libc)Control Functions.
- * fesetround: (libc)Rounding.
- * FE_SNANS_ALWAYS_SIGNAL: (libc)Infinity and NaN.
- * fetestexceptflag: (libc)Status bit operations.
- * fetestexcept: (libc)Status bit operations.
- * feupdateenv: (libc)Control Functions.
- * fflush: (libc)Flushing Buffers.
- * fflush_unlocked: (libc)Flushing Buffers.
- * fgetc: (libc)Character Input.
- * fgetc_unlocked: (libc)Character Input.
- * F_GETFD: (libc)Descriptor Flags.
- * F_GETFL: (libc)Getting File Status Flags.
- * fgetgrent: (libc)Scanning All Groups.
- * fgetgrent_r: (libc)Scanning All Groups.
- * F_GETLK: (libc)File Locks.
- * F_GETOWN: (libc)Interrupt Input.
- * fgetpos64: (libc)Portable Positioning.
- * fgetpos: (libc)Portable Positioning.
- * fgetpwent: (libc)Scanning All Users.
- * fgetpwent_r: (libc)Scanning All Users.
- * fgets: (libc)Line Input.
- * fgets_unlocked: (libc)Line Input.
- * fgetwc: (libc)Character Input.
- * fgetwc_unlocked: (libc)Character Input.
- * fgetws: (libc)Line Input.
- * fgetws_unlocked: (libc)Line Input.
- * FILENAME_MAX: (libc)Limits for Files.
- * fileno: (libc)Descriptors and Streams.
- * fileno_unlocked: (libc)Descriptors and Streams.
- * finitef: (libc)Floating Point Classes.
- * finite: (libc)Floating Point Classes.
- * finitel: (libc)Floating Point Classes.
- * __flbf: (libc)Controlling Buffering.
- * flockfile: (libc)Streams and Threads.
- * floorf: (libc)Rounding Functions.
- * floor: (libc)Rounding Functions.
- * floorl: (libc)Rounding Functions.
- * _flushlbf: (libc)Flushing Buffers.
- * FLUSHO: (libc)Local Modes.
- * fmaf: (libc)Misc FP Arithmetic.
- * fma: (libc)Misc FP Arithmetic.
- * fmal: (libc)Misc FP Arithmetic.
- * fmaxf: (libc)Misc FP Arithmetic.
- * fmax: (libc)Misc FP Arithmetic.
- * fmaxl: (libc)Misc FP Arithmetic.
- * fmaxmagf: (libc)Misc FP Arithmetic.
- * fmaxmag: (libc)Misc FP Arithmetic.
- * fmaxmagl: (libc)Misc FP Arithmetic.
- * fmemopen: (libc)String Streams.
- * fminf: (libc)Misc FP Arithmetic.
- * fmin: (libc)Misc FP Arithmetic.
- * fminl: (libc)Misc FP Arithmetic.
- * fminmagf: (libc)Misc FP Arithmetic.
- * fminmag: (libc)Misc FP Arithmetic.
- * fminmagl: (libc)Misc FP Arithmetic.
- * fmodf: (libc)Remainder Functions.
- * fmod: (libc)Remainder Functions.
- * fmodl: (libc)Remainder Functions.
- * fmtmsg: (libc)Printing Formatted Messages.
- * fnmatch: (libc)Wildcard Matching.
- * F_OFD_GETLK: (libc)Open File Description Locks.
- * F_OFD_SETLK: (libc)Open File Description Locks.
- * F_OFD_SETLKW: (libc)Open File Description Locks.
- * F_OK: (libc)Testing File Access.
- * fopen64: (libc)Opening Streams.
- * fopencookie: (libc)Streams and Cookies.
- * fopen: (libc)Opening Streams.
- * FOPEN_MAX: (libc)Opening Streams.
- * fork: (libc)Creating a Process.
- * forkpty: (libc)Pseudo-Terminal Pairs.
- * fpathconf: (libc)Pathconf.
- * fpclassify: (libc)Floating Point Classes.
- * __fpending: (libc)Controlling Buffering.
- * FP_ILOGB0: (libc)Exponents and Logarithms.
- * FP_ILOGBNAN: (libc)Exponents and Logarithms.
- * FP_LLOGB0: (libc)Exponents and Logarithms.
- * FP_LLOGBNAN: (libc)Exponents and Logarithms.
- * fprintf: (libc)Formatted Output Functions.
- * __fpurge: (libc)Flushing Buffers.
- * fputc: (libc)Simple Output.
- * fputc_unlocked: (libc)Simple Output.
- * fputs: (libc)Simple Output.
- * fputs_unlocked: (libc)Simple Output.
- * fputwc: (libc)Simple Output.
- * fputwc_unlocked: (libc)Simple Output.
- * fputws: (libc)Simple Output.
- * fputws_unlocked: (libc)Simple Output.
- * __freadable: (libc)Opening Streams.
- * __freading: (libc)Opening Streams.
- * fread: (libc)Block Input/Output.
- * fread_unlocked: (libc)Block Input/Output.
- * free: (libc)Freeing after Malloc.
- * freopen64: (libc)Opening Streams.
- * freopen: (libc)Opening Streams.
- * frexpf: (libc)Normalization Functions.
- * frexp: (libc)Normalization Functions.
- * frexpl: (libc)Normalization Functions.
- * fromfpf: (libc)Rounding Functions.
- * fromfp: (libc)Rounding Functions.
- * fromfpl: (libc)Rounding Functions.
- * fromfpxf: (libc)Rounding Functions.
- * fromfpx: (libc)Rounding Functions.
- * fromfpxl: (libc)Rounding Functions.
- * fscanf: (libc)Formatted Input Functions.
- * fseek: (libc)File Positioning.
- * fseeko64: (libc)File Positioning.
- * fseeko: (libc)File Positioning.
- * F_SETFD: (libc)Descriptor Flags.
- * F_SETFL: (libc)Getting File Status Flags.
- * F_SETLK: (libc)File Locks.
- * F_SETLKW: (libc)File Locks.
- * __fsetlocking: (libc)Streams and Threads.
- * F_SETOWN: (libc)Interrupt Input.
- * fsetpos64: (libc)Portable Positioning.
- * fsetpos: (libc)Portable Positioning.
- * fstat64: (libc)Reading Attributes.
- * fstat: (libc)Reading Attributes.
- * fsync: (libc)Synchronizing I/O.
- * ftell: (libc)File Positioning.
- * ftello64: (libc)File Positioning.
- * ftello: (libc)File Positioning.
- * ftruncate64: (libc)File Size.
- * ftruncate: (libc)File Size.
- * ftrylockfile: (libc)Streams and Threads.
- * ftw64: (libc)Working with Directory Trees.
- * ftw: (libc)Working with Directory Trees.
- * funlockfile: (libc)Streams and Threads.
- * futimes: (libc)File Times.
- * fwide: (libc)Streams and I18N.
- * fwprintf: (libc)Formatted Output Functions.
- * __fwritable: (libc)Opening Streams.
- * fwrite: (libc)Block Input/Output.
- * fwrite_unlocked: (libc)Block Input/Output.
- * __fwriting: (libc)Opening Streams.
- * fwscanf: (libc)Formatted Input Functions.
- * gammaf: (libc)Special Functions.
- * gamma: (libc)Special Functions.
- * gammal: (libc)Special Functions.
- * __gconv_end_fct: (libc)glibc iconv Implementation.
- * __gconv_fct: (libc)glibc iconv Implementation.
- * __gconv_init_fct: (libc)glibc iconv Implementation.
- * gcvt: (libc)System V Number Conversion.
- * getauxval: (libc)Auxiliary Vector.
- * get_avphys_pages: (libc)Query Memory Parameters.
- * getchar: (libc)Character Input.
- * getchar_unlocked: (libc)Character Input.
- * getc: (libc)Character Input.
- * getcontext: (libc)System V contexts.
- * getc_unlocked: (libc)Character Input.
- * get_current_dir_name: (libc)Working Directory.
- * getcwd: (libc)Working Directory.
- * getdate: (libc)General Time String Parsing.
- * getdate_r: (libc)General Time String Parsing.
- * getdelim: (libc)Line Input.
- * getdomainnname: (libc)Host Identification.
- * getegid: (libc)Reading Persona.
- * getentropy: (libc)Unpredictable Bytes.
- * getenv: (libc)Environment Access.
- * geteuid: (libc)Reading Persona.
- * getfsent: (libc)fstab.
- * getfsfile: (libc)fstab.
- * getfsspec: (libc)fstab.
- * getgid: (libc)Reading Persona.
- * getgrent: (libc)Scanning All Groups.
- * getgrent_r: (libc)Scanning All Groups.
- * getgrgid: (libc)Lookup Group.
- * getgrgid_r: (libc)Lookup Group.
- * getgrnam: (libc)Lookup Group.
- * getgrnam_r: (libc)Lookup Group.
- * getgrouplist: (libc)Setting Groups.
- * getgroups: (libc)Reading Persona.
- * gethostbyaddr: (libc)Host Names.
- * gethostbyaddr_r: (libc)Host Names.
- * gethostbyname2: (libc)Host Names.
- * gethostbyname2_r: (libc)Host Names.
- * gethostbyname: (libc)Host Names.
- * gethostbyname_r: (libc)Host Names.
- * gethostent: (libc)Host Names.
- * gethostid: (libc)Host Identification.
- * gethostname: (libc)Host Identification.
- * getitimer: (libc)Setting an Alarm.
- * getline: (libc)Line Input.
- * getloadavg: (libc)Processor Resources.
- * getlogin: (libc)Who Logged In.
- * getmntent: (libc)mtab.
- * getmntent_r: (libc)mtab.
- * getnetbyaddr: (libc)Networks Database.
- * getnetbyname: (libc)Networks Database.
- * getnetent: (libc)Networks Database.
- * getnetgrent: (libc)Lookup Netgroup.
- * getnetgrent_r: (libc)Lookup Netgroup.
- * get_nprocs_conf: (libc)Processor Resources.
- * get_nprocs: (libc)Processor Resources.
- * getopt: (libc)Using Getopt.
- * getopt_long: (libc)Getopt Long Options.
- * getopt_long_only: (libc)Getopt Long Options.
- * getpagesize: (libc)Query Memory Parameters.
- * getpass: (libc)getpass.
- * getpayloadf: (libc)FP Bit Twiddling.
- * getpayload: (libc)FP Bit Twiddling.
- * getpayloadl: (libc)FP Bit Twiddling.
- * getpeername: (libc)Who is Connected.
- * getpgid: (libc)Process Group Functions.
- * getpgrp: (libc)Process Group Functions.
- * get_phys_pages: (libc)Query Memory Parameters.
- * getpid: (libc)Process Identification.
- * getppid: (libc)Process Identification.
- * getpriority: (libc)Traditional Scheduling Functions.
- * getprotobyname: (libc)Protocols Database.
- * getprotobynumber: (libc)Protocols Database.
- * getprotoent: (libc)Protocols Database.
- * getpt: (libc)Allocation.
- * getpwent: (libc)Scanning All Users.
- * getpwent_r: (libc)Scanning All Users.
- * getpwnam: (libc)Lookup User.
- * getpwnam_r: (libc)Lookup User.
- * getpwuid: (libc)Lookup User.
- * getpwuid_r: (libc)Lookup User.
- * getrandom: (libc)Unpredictable Bytes.
- * getrlimit64: (libc)Limits on Resources.
- * getrlimit: (libc)Limits on Resources.
- * getrusage: (libc)Resource Usage.
- * getservbyname: (libc)Services Database.
- * getservbyport: (libc)Services Database.
- * getservent: (libc)Services Database.
- * getsid: (libc)Process Group Functions.
- * gets: (libc)Line Input.
- * getsockname: (libc)Reading Address.
- * getsockopt: (libc)Socket Option Functions.
- * getsubopt: (libc)Suboptions.
- * gettext: (libc)Translation with gettext.
- * gettimeofday: (libc)High-Resolution Calendar.
- * getuid: (libc)Reading Persona.
- * getumask: (libc)Setting Permissions.
- * getutent: (libc)Manipulating the Database.
- * getutent_r: (libc)Manipulating the Database.
- * getutid: (libc)Manipulating the Database.
- * getutid_r: (libc)Manipulating the Database.
- * getutline: (libc)Manipulating the Database.
- * getutline_r: (libc)Manipulating the Database.
- * getutmp: (libc)XPG Functions.
- * getutmpx: (libc)XPG Functions.
- * getutxent: (libc)XPG Functions.
- * getutxid: (libc)XPG Functions.
- * getutxline: (libc)XPG Functions.
- * getwchar: (libc)Character Input.
- * getwchar_unlocked: (libc)Character Input.
- * getwc: (libc)Character Input.
- * getwc_unlocked: (libc)Character Input.
- * getwd: (libc)Working Directory.
- * getw: (libc)Character Input.
- * glob64: (libc)Calling Glob.
- * globfree64: (libc)More Flags for Globbing.
- * globfree: (libc)More Flags for Globbing.
- * glob: (libc)Calling Glob.
- * gmtime: (libc)Broken-down Time.
- * gmtime_r: (libc)Broken-down Time.
- * grantpt: (libc)Allocation.
- * gsignal: (libc)Signaling Yourself.
- * gtty: (libc)BSD Terminal Modes.
- * hasmntopt: (libc)mtab.
- * hcreate: (libc)Hash Search Function.
- * hcreate_r: (libc)Hash Search Function.
- * hdestroy: (libc)Hash Search Function.
- * hdestroy_r: (libc)Hash Search Function.
- * hsearch: (libc)Hash Search Function.
- * hsearch_r: (libc)Hash Search Function.
- * htonl: (libc)Byte Order.
- * htons: (libc)Byte Order.
- * HUGE_VALF: (libc)Math Error Reporting.
- * HUGE_VAL: (libc)Math Error Reporting.
- * HUGE_VALL: (libc)Math Error Reporting.
- * HUPCL: (libc)Control Modes.
- * hypotf: (libc)Exponents and Logarithms.
- * hypot: (libc)Exponents and Logarithms.
- * hypotl: (libc)Exponents and Logarithms.
- * ICANON: (libc)Local Modes.
- * iconv_close: (libc)Generic Conversion Interface.
- * iconv: (libc)Generic Conversion Interface.
- * iconv_open: (libc)Generic Conversion Interface.
- * ICRNL: (libc)Input Modes.
- * IEXTEN: (libc)Local Modes.
- * if_freenameindex: (libc)Interface Naming.
- * if_indextoname: (libc)Interface Naming.
- * if_nameindex: (libc)Interface Naming.
- * if_nametoindex: (libc)Interface Naming.
- * IFNAMSIZ: (libc)Interface Naming.
- * IFTODT: (libc)Directory Entries.
- * IGNBRK: (libc)Input Modes.
- * IGNCR: (libc)Input Modes.
- * IGNPAR: (libc)Input Modes.
- * I: (libc)Complex Numbers.
- * ilogbf: (libc)Exponents and Logarithms.
- * ilogb: (libc)Exponents and Logarithms.
- * ilogbl: (libc)Exponents and Logarithms.
- * _Imaginary_I: (libc)Complex Numbers.
- * imaxabs: (libc)Absolute Value.
- * IMAXBEL: (libc)Input Modes.
- * imaxdiv: (libc)Integer Division.
- * in6addr_any: (libc)Host Address Data Type.
- * in6addr_loopback: (libc)Host Address Data Type.
- * INADDR_ANY: (libc)Host Address Data Type.
- * INADDR_BROADCAST: (libc)Host Address Data Type.
- * INADDR_LOOPBACK: (libc)Host Address Data Type.
- * INADDR_NONE: (libc)Host Address Data Type.
- * index: (libc)Search Functions.
- * inet_addr: (libc)Host Address Functions.
- * inet_aton: (libc)Host Address Functions.
- * inet_lnaof: (libc)Host Address Functions.
- * inet_makeaddr: (libc)Host Address Functions.
- * inet_netof: (libc)Host Address Functions.
- * inet_network: (libc)Host Address Functions.
- * inet_ntoa: (libc)Host Address Functions.
- * inet_ntop: (libc)Host Address Functions.
- * inet_pton: (libc)Host Address Functions.
- * INFINITY: (libc)Infinity and NaN.
- * initgroups: (libc)Setting Groups.
- * initstate: (libc)BSD Random.
- * initstate_r: (libc)BSD Random.
- * INLCR: (libc)Input Modes.
- * innetgr: (libc)Netgroup Membership.
- * INPCK: (libc)Input Modes.
- * ioctl: (libc)IOCTLs.
- * _IOFBF: (libc)Controlling Buffering.
- * _IOLBF: (libc)Controlling Buffering.
- * _IONBF: (libc)Controlling Buffering.
- * IPPORT_RESERVED: (libc)Ports.
- * IPPORT_USERRESERVED: (libc)Ports.
- * isalnum: (libc)Classification of Characters.
- * isalpha: (libc)Classification of Characters.
- * isascii: (libc)Classification of Characters.
- * isatty: (libc)Is It a Terminal.
- * isblank: (libc)Classification of Characters.
- * iscanonical: (libc)Floating Point Classes.
- * iscntrl: (libc)Classification of Characters.
- * isdigit: (libc)Classification of Characters.
- * iseqsig: (libc)FP Comparison Functions.
- * isfinite: (libc)Floating Point Classes.
- * isgraph: (libc)Classification of Characters.
- * isgreaterequal: (libc)FP Comparison Functions.
- * isgreater: (libc)FP Comparison Functions.
- * ISIG: (libc)Local Modes.
- * isinff: (libc)Floating Point Classes.
- * isinf: (libc)Floating Point Classes.
- * isinfl: (libc)Floating Point Classes.
- * islessequal: (libc)FP Comparison Functions.
- * islessgreater: (libc)FP Comparison Functions.
- * isless: (libc)FP Comparison Functions.
- * islower: (libc)Classification of Characters.
- * isnanf: (libc)Floating Point Classes.
- * isnan: (libc)Floating Point Classes.
- * isnan: (libc)Floating Point Classes.
- * isnanl: (libc)Floating Point Classes.
- * isnormal: (libc)Floating Point Classes.
- * isprint: (libc)Classification of Characters.
- * ispunct: (libc)Classification of Characters.
- * issignaling: (libc)Floating Point Classes.
- * isspace: (libc)Classification of Characters.
- * issubnormal: (libc)Floating Point Classes.
- * ISTRIP: (libc)Input Modes.
- * isunordered: (libc)FP Comparison Functions.
- * isupper: (libc)Classification of Characters.
- * iswalnum: (libc)Classification of Wide Characters.
- * iswalpha: (libc)Classification of Wide Characters.
- * iswblank: (libc)Classification of Wide Characters.
- * iswcntrl: (libc)Classification of Wide Characters.
- * iswctype: (libc)Classification of Wide Characters.
- * iswdigit: (libc)Classification of Wide Characters.
- * iswgraph: (libc)Classification of Wide Characters.
- * iswlower: (libc)Classification of Wide Characters.
- * iswprint: (libc)Classification of Wide Characters.
- * iswpunct: (libc)Classification of Wide Characters.
- * iswspace: (libc)Classification of Wide Characters.
- * iswupper: (libc)Classification of Wide Characters.
- * iswxdigit: (libc)Classification of Wide Characters.
- * isxdigit: (libc)Classification of Characters.
- * iszero: (libc)Floating Point Classes.
- * IXANY: (libc)Input Modes.
- * IXOFF: (libc)Input Modes.
- * IXON: (libc)Input Modes.
- * j0f: (libc)Special Functions.
- * j0: (libc)Special Functions.
- * j0l: (libc)Special Functions.
- * j1f: (libc)Special Functions.
- * j1: (libc)Special Functions.
- * j1l: (libc)Special Functions.
- * jnf: (libc)Special Functions.
- * jn: (libc)Special Functions.
- * jnl: (libc)Special Functions.
- * jrand48: (libc)SVID Random.
- * jrand48_r: (libc)SVID Random.
- * kill: (libc)Signaling Another Process.
- * killpg: (libc)Signaling Another Process.
- * l64a: (libc)Encode Binary Data.
- * labs: (libc)Absolute Value.
- * lcong48: (libc)SVID Random.
- * lcong48_r: (libc)SVID Random.
- * L_ctermid: (libc)Identifying the Terminal.
- * L_cuserid: (libc)Who Logged In.
- * ldexpf: (libc)Normalization Functions.
- * ldexp: (libc)Normalization Functions.
- * ldexpl: (libc)Normalization Functions.
- * ldiv: (libc)Integer Division.
- * lfind: (libc)Array Search Function.
- * lgammaf: (libc)Special Functions.
- * lgammaf_r: (libc)Special Functions.
- * lgamma: (libc)Special Functions.
- * lgammal: (libc)Special Functions.
- * lgammal_r: (libc)Special Functions.
- * lgamma_r: (libc)Special Functions.
- * LINE_MAX: (libc)Utility Limits.
- * link: (libc)Hard Links.
- * LINK_MAX: (libc)Limits for Files.
- * lio_listio64: (libc)Asynchronous Reads/Writes.
- * lio_listio: (libc)Asynchronous Reads/Writes.
- * listen: (libc)Listening.
- * llabs: (libc)Absolute Value.
- * lldiv: (libc)Integer Division.
- * llogbf: (libc)Exponents and Logarithms.
- * llogb: (libc)Exponents and Logarithms.
- * llogbl: (libc)Exponents and Logarithms.
- * llrintf: (libc)Rounding Functions.
- * llrint: (libc)Rounding Functions.
- * llrintl: (libc)Rounding Functions.
- * llroundf: (libc)Rounding Functions.
- * llround: (libc)Rounding Functions.
- * llroundl: (libc)Rounding Functions.
- * localeconv: (libc)The Lame Way to Locale Data.
- * localtime: (libc)Broken-down Time.
- * localtime_r: (libc)Broken-down Time.
- * log10f: (libc)Exponents and Logarithms.
- * log10: (libc)Exponents and Logarithms.
- * log10l: (libc)Exponents and Logarithms.
- * log1pf: (libc)Exponents and Logarithms.
- * log1p: (libc)Exponents and Logarithms.
- * log1pl: (libc)Exponents and Logarithms.
- * log2f: (libc)Exponents and Logarithms.
- * log2: (libc)Exponents and Logarithms.
- * log2l: (libc)Exponents and Logarithms.
- * logbf: (libc)Exponents and Logarithms.
- * logb: (libc)Exponents and Logarithms.
- * logbl: (libc)Exponents and Logarithms.
- * logf: (libc)Exponents and Logarithms.
- * login: (libc)Logging In and Out.
- * login_tty: (libc)Logging In and Out.
- * log: (libc)Exponents and Logarithms.
- * logl: (libc)Exponents and Logarithms.
- * logout: (libc)Logging In and Out.
- * logwtmp: (libc)Logging In and Out.
- * longjmp: (libc)Non-Local Details.
- * lrand48: (libc)SVID Random.
- * lrand48_r: (libc)SVID Random.
- * lrintf: (libc)Rounding Functions.
- * lrint: (libc)Rounding Functions.
- * lrintl: (libc)Rounding Functions.
- * lroundf: (libc)Rounding Functions.
- * lround: (libc)Rounding Functions.
- * lroundl: (libc)Rounding Functions.
- * lsearch: (libc)Array Search Function.
- * lseek64: (libc)File Position Primitive.
- * lseek: (libc)File Position Primitive.
- * lstat64: (libc)Reading Attributes.
- * lstat: (libc)Reading Attributes.
- * L_tmpnam: (libc)Temporary Files.
- * lutimes: (libc)File Times.
- * madvise: (libc)Memory-mapped I/O.
- * makecontext: (libc)System V contexts.
- * mallinfo: (libc)Statistics of Malloc.
- * malloc: (libc)Basic Allocation.
- * mallopt: (libc)Malloc Tunable Parameters.
- * MAX_CANON: (libc)Limits for Files.
- * MAX_INPUT: (libc)Limits for Files.
- * MAXNAMLEN: (libc)Limits for Files.
- * MAXSYMLINKS: (libc)Symbolic Links.
- * MB_CUR_MAX: (libc)Selecting the Conversion.
- * mblen: (libc)Non-reentrant Character Conversion.
- * MB_LEN_MAX: (libc)Selecting the Conversion.
- * mbrlen: (libc)Converting a Character.
- * mbrtowc: (libc)Converting a Character.
- * mbsinit: (libc)Keeping the state.
- * mbsnrtowcs: (libc)Converting Strings.
- * mbsrtowcs: (libc)Converting Strings.
- * mbstowcs: (libc)Non-reentrant String Conversion.
- * mbtowc: (libc)Non-reentrant Character Conversion.
- * mcheck: (libc)Heap Consistency Checking.
- * MDMBUF: (libc)Control Modes.
- * memalign: (libc)Aligned Memory Blocks.
- * memccpy: (libc)Copying Strings and Arrays.
- * memchr: (libc)Search Functions.
- * memcmp: (libc)String/Array Comparison.
- * memcpy: (libc)Copying Strings and Arrays.
- * memfrob: (libc)Trivial Encryption.
- * memmem: (libc)Search Functions.
- * memmove: (libc)Copying Strings and Arrays.
- * mempcpy: (libc)Copying Strings and Arrays.
- * memrchr: (libc)Search Functions.
- * memset: (libc)Copying Strings and Arrays.
- * mkdir: (libc)Creating Directories.
- * mkdtemp: (libc)Temporary Files.
- * mkfifo: (libc)FIFO Special Files.
- * mknod: (libc)Making Special Files.
- * mkstemp: (libc)Temporary Files.
- * mktemp: (libc)Temporary Files.
- * mktime: (libc)Broken-down Time.
- * mlockall: (libc)Page Lock Functions.
- * mlock: (libc)Page Lock Functions.
- * mmap64: (libc)Memory-mapped I/O.
- * mmap: (libc)Memory-mapped I/O.
- * modff: (libc)Rounding Functions.
- * modf: (libc)Rounding Functions.
- * modfl: (libc)Rounding Functions.
- * mount: (libc)Mount-Unmount-Remount.
- * mprobe: (libc)Heap Consistency Checking.
- * mrand48: (libc)SVID Random.
- * mrand48_r: (libc)SVID Random.
- * mremap: (libc)Memory-mapped I/O.
- * MSG_DONTROUTE: (libc)Socket Data Options.
- * MSG_OOB: (libc)Socket Data Options.
- * MSG_PEEK: (libc)Socket Data Options.
- * msync: (libc)Memory-mapped I/O.
- * mtrace: (libc)Tracing malloc.
- * munlockall: (libc)Page Lock Functions.
- * munlock: (libc)Page Lock Functions.
- * munmap: (libc)Memory-mapped I/O.
- * muntrace: (libc)Tracing malloc.
- * NAME_MAX: (libc)Limits for Files.
- * nanf: (libc)FP Bit Twiddling.
- * nan: (libc)FP Bit Twiddling.
- * NAN: (libc)Infinity and NaN.
- * nanl: (libc)FP Bit Twiddling.
- * nanosleep: (libc)Sleeping.
- * NCCS: (libc)Mode Data Types.
- * nearbyintf: (libc)Rounding Functions.
- * nearbyint: (libc)Rounding Functions.
- * nearbyintl: (libc)Rounding Functions.
- * nextafterf: (libc)FP Bit Twiddling.
- * nextafter: (libc)FP Bit Twiddling.
- * nextafterl: (libc)FP Bit Twiddling.
- * nextdownf: (libc)FP Bit Twiddling.
- * nextdown: (libc)FP Bit Twiddling.
- * nextdownl: (libc)FP Bit Twiddling.
- * nexttowardf: (libc)FP Bit Twiddling.
- * nexttoward: (libc)FP Bit Twiddling.
- * nexttowardl: (libc)FP Bit Twiddling.
- * nextupf: (libc)FP Bit Twiddling.
- * nextup: (libc)FP Bit Twiddling.
- * nextupl: (libc)FP Bit Twiddling.
- * nftw64: (libc)Working with Directory Trees.
- * nftw: (libc)Working with Directory Trees.
- * ngettext: (libc)Advanced gettext functions.
- * NGROUPS_MAX: (libc)General Limits.
- * nice: (libc)Traditional Scheduling Functions.
- * nl_langinfo: (libc)The Elegant and Fast Way.
- * NOFLSH: (libc)Local Modes.
- * NOKERNINFO: (libc)Local Modes.
- * nrand48: (libc)SVID Random.
- * nrand48_r: (libc)SVID Random.
- * NSIG: (libc)Standard Signals.
- * ntohl: (libc)Byte Order.
- * ntohs: (libc)Byte Order.
- * ntp_adjtime: (libc)High Accuracy Clock.
- * ntp_gettime: (libc)High Accuracy Clock.
- * NULL: (libc)Null Pointer Constant.
- * O_ACCMODE: (libc)Access Modes.
- * O_APPEND: (libc)Operating Modes.
- * O_ASYNC: (libc)Operating Modes.
- * obstack_1grow_fast: (libc)Extra Fast Growing.
- * obstack_1grow: (libc)Growing Objects.
- * obstack_alignment_mask: (libc)Obstacks Data Alignment.
- * obstack_alloc: (libc)Allocation in an Obstack.
- * obstack_base: (libc)Status of an Obstack.
- * obstack_blank_fast: (libc)Extra Fast Growing.
- * obstack_blank: (libc)Growing Objects.
- * obstack_chunk_size: (libc)Obstack Chunks.
- * obstack_copy0: (libc)Allocation in an Obstack.
- * obstack_copy: (libc)Allocation in an Obstack.
- * obstack_finish: (libc)Growing Objects.
- * obstack_free: (libc)Freeing Obstack Objects.
- * obstack_grow0: (libc)Growing Objects.
- * obstack_grow: (libc)Growing Objects.
- * obstack_init: (libc)Preparing for Obstacks.
- * obstack_int_grow_fast: (libc)Extra Fast Growing.
- * obstack_int_grow: (libc)Growing Objects.
- * obstack_next_free: (libc)Status of an Obstack.
- * obstack_object_size: (libc)Growing Objects.
- * obstack_object_size: (libc)Status of an Obstack.
- * obstack_printf: (libc)Dynamic Output.
- * obstack_ptr_grow_fast: (libc)Extra Fast Growing.
- * obstack_ptr_grow: (libc)Growing Objects.
- * obstack_room: (libc)Extra Fast Growing.
- * obstack_vprintf: (libc)Variable Arguments Output.
- * O_CREAT: (libc)Open-time Flags.
- * O_EXCL: (libc)Open-time Flags.
- * O_EXEC: (libc)Access Modes.
- * O_EXLOCK: (libc)Open-time Flags.
- * offsetof: (libc)Structure Measurement.
- * O_FSYNC: (libc)Operating Modes.
- * O_IGNORE_CTTY: (libc)Open-time Flags.
- * O_NDELAY: (libc)Operating Modes.
- * on_exit: (libc)Cleanups on Exit.
- * ONLCR: (libc)Output Modes.
- * O_NOATIME: (libc)Operating Modes.
- * O_NOCTTY: (libc)Open-time Flags.
- * ONOEOT: (libc)Output Modes.
- * O_NOLINK: (libc)Open-time Flags.
- * O_NONBLOCK: (libc)Open-time Flags.
- * O_NONBLOCK: (libc)Operating Modes.
- * O_NOTRANS: (libc)Open-time Flags.
- * open64: (libc)Opening and Closing Files.
- * opendir: (libc)Opening a Directory.
- * open: (libc)Opening and Closing Files.
- * openlog: (libc)openlog.
- * OPEN_MAX: (libc)General Limits.
- * open_memstream: (libc)String Streams.
- * openpty: (libc)Pseudo-Terminal Pairs.
- * OPOST: (libc)Output Modes.
- * O_RDONLY: (libc)Access Modes.
- * O_RDWR: (libc)Access Modes.
- * O_READ: (libc)Access Modes.
- * O_SHLOCK: (libc)Open-time Flags.
- * O_SYNC: (libc)Operating Modes.
- * O_TRUNC: (libc)Open-time Flags.
- * O_WRITE: (libc)Access Modes.
- * O_WRONLY: (libc)Access Modes.
- * OXTABS: (libc)Output Modes.
- * PA_FLAG_MASK: (libc)Parsing a Template String.
- * PARENB: (libc)Control Modes.
- * PARMRK: (libc)Input Modes.
- * PARODD: (libc)Control Modes.
- * parse_printf_format: (libc)Parsing a Template String.
- * pathconf: (libc)Pathconf.
- * PATH_MAX: (libc)Limits for Files.
- * _PATH_UTMP: (libc)Manipulating the Database.
- * _PATH_WTMP: (libc)Manipulating the Database.
- * pause: (libc)Using Pause.
- * pclose: (libc)Pipe to a Subprocess.
- * PENDIN: (libc)Local Modes.
- * perror: (libc)Error Messages.
- * PF_FILE: (libc)Local Namespace Details.
- * PF_INET6: (libc)Internet Namespace.
- * PF_INET: (libc)Internet Namespace.
- * PF_LOCAL: (libc)Local Namespace Details.
- * PF_UNIX: (libc)Local Namespace Details.
- * PIPE_BUF: (libc)Limits for Files.
- * pipe: (libc)Creating a Pipe.
- * popen: (libc)Pipe to a Subprocess.
- * _POSIX2_C_DEV: (libc)System Options.
- * _POSIX2_C_VERSION: (libc)Version Supported.
- * _POSIX2_FORT_DEV: (libc)System Options.
- * _POSIX2_FORT_RUN: (libc)System Options.
- * _POSIX2_LOCALEDEF: (libc)System Options.
- * _POSIX2_SW_DEV: (libc)System Options.
- * _POSIX_CHOWN_RESTRICTED: (libc)Options for Files.
- * posix_fallocate64: (libc)Storage Allocation.
- * posix_fallocate: (libc)Storage Allocation.
- * _POSIX_JOB_CONTROL: (libc)System Options.
- * posix_memalign: (libc)Aligned Memory Blocks.
- * _POSIX_NO_TRUNC: (libc)Options for Files.
- * _POSIX_SAVED_IDS: (libc)System Options.
- * _POSIX_VDISABLE: (libc)Options for Files.
- * _POSIX_VERSION: (libc)Version Supported.
- * pow10f: (libc)Exponents and Logarithms.
- * pow10: (libc)Exponents and Logarithms.
- * pow10l: (libc)Exponents and Logarithms.
- * powf: (libc)Exponents and Logarithms.
- * pow: (libc)Exponents and Logarithms.
- * powl: (libc)Exponents and Logarithms.
- * __ppc_get_timebase_freq: (libc)PowerPC.
- * __ppc_get_timebase: (libc)PowerPC.
- * __ppc_mdoio: (libc)PowerPC.
- * __ppc_mdoom: (libc)PowerPC.
- * __ppc_set_ppr_low: (libc)PowerPC.
- * __ppc_set_ppr_med_high: (libc)PowerPC.
- * __ppc_set_ppr_med: (libc)PowerPC.
- * __ppc_set_ppr_med_low: (libc)PowerPC.
- * __ppc_set_ppr_very_low: (libc)PowerPC.
- * __ppc_yield: (libc)PowerPC.
- * pread64: (libc)I/O Primitives.
- * pread: (libc)I/O Primitives.
- * printf: (libc)Formatted Output Functions.
- * printf_size_info: (libc)Predefined Printf Handlers.
- * printf_size: (libc)Predefined Printf Handlers.
- * psignal: (libc)Signal Messages.
- * pthread_getattr_default_np: (libc)Default Thread Attributes.
- * pthread_getspecific: (libc)Thread-specific Data.
- * pthread_key_create: (libc)Thread-specific Data.
- * pthread_key_delete: (libc)Thread-specific Data.
- * pthread_setattr_default_np: (libc)Default Thread Attributes.
- * pthread_setspecific: (libc)Thread-specific Data.
- * P_tmpdir: (libc)Temporary Files.
- * ptsname: (libc)Allocation.
- * ptsname_r: (libc)Allocation.
- * putchar: (libc)Simple Output.
- * putchar_unlocked: (libc)Simple Output.
- * putc: (libc)Simple Output.
- * putc_unlocked: (libc)Simple Output.
- * putenv: (libc)Environment Access.
- * putpwent: (libc)Writing a User Entry.
- * puts: (libc)Simple Output.
- * pututline: (libc)Manipulating the Database.
- * pututxline: (libc)XPG Functions.
- * putwchar: (libc)Simple Output.
- * putwchar_unlocked: (libc)Simple Output.
- * putwc: (libc)Simple Output.
- * putwc_unlocked: (libc)Simple Output.
- * putw: (libc)Simple Output.
- * pwrite64: (libc)I/O Primitives.
- * pwrite: (libc)I/O Primitives.
- * qecvt: (libc)System V Number Conversion.
- * qecvt_r: (libc)System V Number Conversion.
- * qfcvt: (libc)System V Number Conversion.
- * qfcvt_r: (libc)System V Number Conversion.
- * qgcvt: (libc)System V Number Conversion.
- * qsort: (libc)Array Sort Function.
- * raise: (libc)Signaling Yourself.
- * rand: (libc)ISO Random.
- * RAND_MAX: (libc)ISO Random.
- * random: (libc)BSD Random.
- * random_r: (libc)BSD Random.
- * rand_r: (libc)ISO Random.
- * rawmemchr: (libc)Search Functions.
- * readdir64: (libc)Reading/Closing Directory.
- * readdir64_r: (libc)Reading/Closing Directory.
- * readdir: (libc)Reading/Closing Directory.
- * readdir_r: (libc)Reading/Closing Directory.
- * read: (libc)I/O Primitives.
- * readlink: (libc)Symbolic Links.
- * readv: (libc)Scatter-Gather.
- * realloc: (libc)Changing Block Size.
- * realpath: (libc)Symbolic Links.
- * recvfrom: (libc)Receiving Datagrams.
- * recv: (libc)Receiving Data.
- * recvmsg: (libc)Receiving Datagrams.
- * RE_DUP_MAX: (libc)General Limits.
- * regcomp: (libc)POSIX Regexp Compilation.
- * regerror: (libc)Regexp Cleanup.
- * regexec: (libc)Matching POSIX Regexps.
- * regfree: (libc)Regexp Cleanup.
- * register_printf_function: (libc)Registering New Conversions.
- * remainderf: (libc)Remainder Functions.
- * remainder: (libc)Remainder Functions.
- * remainderl: (libc)Remainder Functions.
- * remove: (libc)Deleting Files.
- * rename: (libc)Renaming Files.
- * rewinddir: (libc)Random Access Directory.
- * rewind: (libc)File Positioning.
- * rindex: (libc)Search Functions.
- * rintf: (libc)Rounding Functions.
- * rint: (libc)Rounding Functions.
- * rintl: (libc)Rounding Functions.
- * RLIM_INFINITY: (libc)Limits on Resources.
- * rmdir: (libc)Deleting Files.
- * R_OK: (libc)Testing File Access.
- * roundevenf: (libc)Rounding Functions.
- * roundeven: (libc)Rounding Functions.
- * roundevenl: (libc)Rounding Functions.
- * roundf: (libc)Rounding Functions.
- * round: (libc)Rounding Functions.
- * roundl: (libc)Rounding Functions.
- * rpmatch: (libc)Yes-or-No Questions.
- * SA_NOCLDSTOP: (libc)Flags for Sigaction.
- * SA_ONSTACK: (libc)Flags for Sigaction.
- * SA_RESTART: (libc)Flags for Sigaction.
- * sbrk: (libc)Resizing the Data Segment.
- * scalbf: (libc)Normalization Functions.
- * scalb: (libc)Normalization Functions.
- * scalbl: (libc)Normalization Functions.
- * scalblnf: (libc)Normalization Functions.
- * scalbln: (libc)Normalization Functions.
- * scalblnl: (libc)Normalization Functions.
- * scalbnf: (libc)Normalization Functions.
- * scalbn: (libc)Normalization Functions.
- * scalbnl: (libc)Normalization Functions.
- * scandir64: (libc)Scanning Directory Content.
- * scandir: (libc)Scanning Directory Content.
- * scanf: (libc)Formatted Input Functions.
- * sched_getaffinity: (libc)CPU Affinity.
- * sched_getparam: (libc)Basic Scheduling Functions.
- * sched_get_priority_max: (libc)Basic Scheduling Functions.
- * sched_get_priority_min: (libc)Basic Scheduling Functions.
- * sched_getscheduler: (libc)Basic Scheduling Functions.
- * sched_rr_get_interval: (libc)Basic Scheduling Functions.
- * sched_setaffinity: (libc)CPU Affinity.
- * sched_setparam: (libc)Basic Scheduling Functions.
- * sched_setscheduler: (libc)Basic Scheduling Functions.
- * sched_yield: (libc)Basic Scheduling Functions.
- * secure_getenv: (libc)Environment Access.
- * seed48: (libc)SVID Random.
- * seed48_r: (libc)SVID Random.
- * SEEK_CUR: (libc)File Positioning.
- * seekdir: (libc)Random Access Directory.
- * SEEK_END: (libc)File Positioning.
- * SEEK_SET: (libc)File Positioning.
- * select: (libc)Waiting for I/O.
- * sem_close: (libc)Semaphores.
- * semctl: (libc)Semaphores.
- * sem_destroy: (libc)Semaphores.
- * semget: (libc)Semaphores.
- * sem_getvalue: (libc)Semaphores.
- * sem_init: (libc)Semaphores.
- * sem_open: (libc)Semaphores.
- * semop: (libc)Semaphores.
- * sem_post: (libc)Semaphores.
- * semtimedop: (libc)Semaphores.
- * sem_timedwait: (libc)Semaphores.
- * sem_trywait: (libc)Semaphores.
- * sem_unlink: (libc)Semaphores.
- * sem_wait: (libc)Semaphores.
- * send: (libc)Sending Data.
- * sendmsg: (libc)Receiving Datagrams.
- * sendto: (libc)Sending Datagrams.
- * setbuffer: (libc)Controlling Buffering.
- * setbuf: (libc)Controlling Buffering.
- * setcontext: (libc)System V contexts.
- * setdomainname: (libc)Host Identification.
- * setegid: (libc)Setting Groups.
- * setenv: (libc)Environment Access.
- * seteuid: (libc)Setting User ID.
- * setfsent: (libc)fstab.
- * setgid: (libc)Setting Groups.
- * setgrent: (libc)Scanning All Groups.
- * setgroups: (libc)Setting Groups.
- * sethostent: (libc)Host Names.
- * sethostid: (libc)Host Identification.
- * sethostname: (libc)Host Identification.
- * setitimer: (libc)Setting an Alarm.
- * setjmp: (libc)Non-Local Details.
- * setkey: (libc)DES Encryption.
- * setkey_r: (libc)DES Encryption.
- * setlinebuf: (libc)Controlling Buffering.
- * setlocale: (libc)Setting the Locale.
- * setlogmask: (libc)setlogmask.
- * setmntent: (libc)mtab.
- * setnetent: (libc)Networks Database.
- * setnetgrent: (libc)Lookup Netgroup.
- * setpayloadf: (libc)FP Bit Twiddling.
- * setpayload: (libc)FP Bit Twiddling.
- * setpayloadl: (libc)FP Bit Twiddling.
- * setpayloadsigf: (libc)FP Bit Twiddling.
- * setpayloadsig: (libc)FP Bit Twiddling.
- * setpayloadsigl: (libc)FP Bit Twiddling.
- * setpgid: (libc)Process Group Functions.
- * setpgrp: (libc)Process Group Functions.
- * setpriority: (libc)Traditional Scheduling Functions.
- * setprotoent: (libc)Protocols Database.
- * setpwent: (libc)Scanning All Users.
- * setregid: (libc)Setting Groups.
- * setreuid: (libc)Setting User ID.
- * setrlimit64: (libc)Limits on Resources.
- * setrlimit: (libc)Limits on Resources.
- * setservent: (libc)Services Database.
- * setsid: (libc)Process Group Functions.
- * setsockopt: (libc)Socket Option Functions.
- * setstate: (libc)BSD Random.
- * setstate_r: (libc)BSD Random.
- * settimeofday: (libc)High-Resolution Calendar.
- * setuid: (libc)Setting User ID.
- * setutent: (libc)Manipulating the Database.
- * setutxent: (libc)XPG Functions.
- * setvbuf: (libc)Controlling Buffering.
- * shm_open: (libc)Memory-mapped I/O.
- * shm_unlink: (libc)Memory-mapped I/O.
- * shutdown: (libc)Closing a Socket.
- * S_IFMT: (libc)Testing File Type.
- * SIGABRT: (libc)Program Error Signals.
- * sigaction: (libc)Advanced Signal Handling.
- * sigaddset: (libc)Signal Sets.
- * SIGALRM: (libc)Alarm Signals.
- * sigaltstack: (libc)Signal Stack.
- * sigblock: (libc)BSD Signal Handling.
- * SIGBUS: (libc)Program Error Signals.
- * SIGCHLD: (libc)Job Control Signals.
- * SIGCLD: (libc)Job Control Signals.
- * SIGCONT: (libc)Job Control Signals.
- * sigdelset: (libc)Signal Sets.
- * sigemptyset: (libc)Signal Sets.
- * SIGEMT: (libc)Program Error Signals.
- * SIG_ERR: (libc)Basic Signal Handling.
- * sigfillset: (libc)Signal Sets.
- * SIGFPE: (libc)Program Error Signals.
- * SIGHUP: (libc)Termination Signals.
- * SIGILL: (libc)Program Error Signals.
- * SIGINFO: (libc)Miscellaneous Signals.
- * siginterrupt: (libc)BSD Signal Handling.
- * SIGINT: (libc)Termination Signals.
- * SIGIO: (libc)Asynchronous I/O Signals.
- * SIGIOT: (libc)Program Error Signals.
- * sigismember: (libc)Signal Sets.
- * SIGKILL: (libc)Termination Signals.
- * siglongjmp: (libc)Non-Local Exits and Signals.
- * SIGLOST: (libc)Operation Error Signals.
- * sigmask: (libc)BSD Signal Handling.
- * signal: (libc)Basic Signal Handling.
- * signbit: (libc)FP Bit Twiddling.
- * significandf: (libc)Normalization Functions.
- * significand: (libc)Normalization Functions.
- * significandl: (libc)Normalization Functions.
- * sigpause: (libc)BSD Signal Handling.
- * sigpending: (libc)Checking for Pending Signals.
- * SIGPIPE: (libc)Operation Error Signals.
- * SIGPOLL: (libc)Asynchronous I/O Signals.
- * sigprocmask: (libc)Process Signal Mask.
- * SIGPROF: (libc)Alarm Signals.
- * SIGQUIT: (libc)Termination Signals.
- * SIGSEGV: (libc)Program Error Signals.
- * sigsetjmp: (libc)Non-Local Exits and Signals.
- * sigsetmask: (libc)BSD Signal Handling.
- * sigstack: (libc)Signal Stack.
- * SIGSTOP: (libc)Job Control Signals.
- * sigsuspend: (libc)Sigsuspend.
- * SIGSYS: (libc)Program Error Signals.
- * SIGTERM: (libc)Termination Signals.
- * SIGTRAP: (libc)Program Error Signals.
- * SIGTSTP: (libc)Job Control Signals.
- * SIGTTIN: (libc)Job Control Signals.
- * SIGTTOU: (libc)Job Control Signals.
- * SIGURG: (libc)Asynchronous I/O Signals.
- * SIGUSR1: (libc)Miscellaneous Signals.
- * SIGUSR2: (libc)Miscellaneous Signals.
- * SIGVTALRM: (libc)Alarm Signals.
- * SIGWINCH: (libc)Miscellaneous Signals.
- * SIGXCPU: (libc)Operation Error Signals.
- * SIGXFSZ: (libc)Operation Error Signals.
- * sincosf: (libc)Trig Functions.
- * sincos: (libc)Trig Functions.
- * sincosl: (libc)Trig Functions.
- * sinf: (libc)Trig Functions.
- * sinhf: (libc)Hyperbolic Functions.
- * sinh: (libc)Hyperbolic Functions.
- * sinhl: (libc)Hyperbolic Functions.
- * sin: (libc)Trig Functions.
- * sinl: (libc)Trig Functions.
- * S_ISBLK: (libc)Testing File Type.
- * S_ISCHR: (libc)Testing File Type.
- * S_ISDIR: (libc)Testing File Type.
- * S_ISFIFO: (libc)Testing File Type.
- * S_ISLNK: (libc)Testing File Type.
- * S_ISREG: (libc)Testing File Type.
- * S_ISSOCK: (libc)Testing File Type.
- * sleep: (libc)Sleeping.
- * SNANF: (libc)Infinity and NaN.
- * SNAN: (libc)Infinity and NaN.
- * SNANL: (libc)Infinity and NaN.
- * snprintf: (libc)Formatted Output Functions.
- * SOCK_DGRAM: (libc)Communication Styles.
- * socket: (libc)Creating a Socket.
- * socketpair: (libc)Socket Pairs.
- * SOCK_RAW: (libc)Communication Styles.
- * SOCK_RDM: (libc)Communication Styles.
- * SOCK_SEQPACKET: (libc)Communication Styles.
- * SOCK_STREAM: (libc)Communication Styles.
- * SOL_SOCKET: (libc)Socket-Level Options.
- * sprintf: (libc)Formatted Output Functions.
- * sqrtf: (libc)Exponents and Logarithms.
- * sqrt: (libc)Exponents and Logarithms.
- * sqrtl: (libc)Exponents and Logarithms.
- * srand48: (libc)SVID Random.
- * srand48_r: (libc)SVID Random.
- * srand: (libc)ISO Random.
- * srandom: (libc)BSD Random.
- * srandom_r: (libc)BSD Random.
- * sscanf: (libc)Formatted Input Functions.
- * ssignal: (libc)Basic Signal Handling.
- * SSIZE_MAX: (libc)General Limits.
- * stat64: (libc)Reading Attributes.
- * stat: (libc)Reading Attributes.
- * stime: (libc)Simple Calendar Time.
- * stpcpy: (libc)Copying Strings and Arrays.
- * stpncpy: (libc)Truncating Strings.
- * strcasecmp: (libc)String/Array Comparison.
- * strcasestr: (libc)Search Functions.
- * strcat: (libc)Concatenating Strings.
- * strchr: (libc)Search Functions.
- * strchrnul: (libc)Search Functions.
- * strcmp: (libc)String/Array Comparison.
- * strcoll: (libc)Collation Functions.
- * strcpy: (libc)Copying Strings and Arrays.
- * strcspn: (libc)Search Functions.
- * strdupa: (libc)Copying Strings and Arrays.
- * strdup: (libc)Copying Strings and Arrays.
- * STREAM_MAX: (libc)General Limits.
- * strerror: (libc)Error Messages.
- * strerror_r: (libc)Error Messages.
- * strfmon: (libc)Formatting Numbers.
- * strfromd: (libc)Printing of Floats.
- * strfromf: (libc)Printing of Floats.
- * strfroml: (libc)Printing of Floats.
- * strfry: (libc)strfry.
- * strftime: (libc)Formatting Calendar Time.
- * strlen: (libc)String Length.
- * strncasecmp: (libc)String/Array Comparison.
- * strncat: (libc)Truncating Strings.
- * strncmp: (libc)String/Array Comparison.
- * strncpy: (libc)Truncating Strings.
- * strndupa: (libc)Truncating Strings.
- * strndup: (libc)Truncating Strings.
- * strnlen: (libc)String Length.
- * strpbrk: (libc)Search Functions.
- * strptime: (libc)Low-Level Time String Parsing.
- * strrchr: (libc)Search Functions.
- * strsep: (libc)Finding Tokens in a String.
- * strsignal: (libc)Signal Messages.
- * strspn: (libc)Search Functions.
- * strstr: (libc)Search Functions.
- * strtod: (libc)Parsing of Floats.
- * strtof: (libc)Parsing of Floats.
- * strtoimax: (libc)Parsing of Integers.
- * strtok: (libc)Finding Tokens in a String.
- * strtok_r: (libc)Finding Tokens in a String.
- * strtold: (libc)Parsing of Floats.
- * strtol: (libc)Parsing of Integers.
- * strtoll: (libc)Parsing of Integers.
- * strtoq: (libc)Parsing of Integers.
- * strtoul: (libc)Parsing of Integers.
- * strtoull: (libc)Parsing of Integers.
- * strtoumax: (libc)Parsing of Integers.
- * strtouq: (libc)Parsing of Integers.
- * strverscmp: (libc)String/Array Comparison.
- * strxfrm: (libc)Collation Functions.
- * stty: (libc)BSD Terminal Modes.
- * S_TYPEISMQ: (libc)Testing File Type.
- * S_TYPEISSEM: (libc)Testing File Type.
- * S_TYPEISSHM: (libc)Testing File Type.
- * SUN_LEN: (libc)Local Namespace Details.
- * swapcontext: (libc)System V contexts.
- * swprintf: (libc)Formatted Output Functions.
- * swscanf: (libc)Formatted Input Functions.
- * symlink: (libc)Symbolic Links.
- * sync: (libc)Synchronizing I/O.
- * syscall: (libc)System Calls.
- * sysconf: (libc)Sysconf Definition.
- * sysctl: (libc)System Parameters.
- * syslog: (libc)syslog; vsyslog.
- * system: (libc)Running a Command.
- * sysv_signal: (libc)Basic Signal Handling.
- * tanf: (libc)Trig Functions.
- * tanhf: (libc)Hyperbolic Functions.
- * tanh: (libc)Hyperbolic Functions.
- * tanhl: (libc)Hyperbolic Functions.
- * tan: (libc)Trig Functions.
- * tanl: (libc)Trig Functions.
- * tcdrain: (libc)Line Control.
- * tcflow: (libc)Line Control.
- * tcflush: (libc)Line Control.
- * tcgetattr: (libc)Mode Functions.
- * tcgetpgrp: (libc)Terminal Access Functions.
- * tcgetsid: (libc)Terminal Access Functions.
- * tcsendbreak: (libc)Line Control.
- * tcsetattr: (libc)Mode Functions.
- * tcsetpgrp: (libc)Terminal Access Functions.
- * tdelete: (libc)Tree Search Function.
- * tdestroy: (libc)Tree Search Function.
- * telldir: (libc)Random Access Directory.
- * tempnam: (libc)Temporary Files.
- * textdomain: (libc)Locating gettext catalog.
- * tfind: (libc)Tree Search Function.
- * tgammaf: (libc)Special Functions.
- * tgamma: (libc)Special Functions.
- * tgammal: (libc)Special Functions.
- * timegm: (libc)Broken-down Time.
- * time: (libc)Simple Calendar Time.
- * timelocal: (libc)Broken-down Time.
- * times: (libc)Processor Time.
- * tmpfile64: (libc)Temporary Files.
- * tmpfile: (libc)Temporary Files.
- * TMP_MAX: (libc)Temporary Files.
- * tmpnam: (libc)Temporary Files.
- * tmpnam_r: (libc)Temporary Files.
- * toascii: (libc)Case Conversion.
- * _tolower: (libc)Case Conversion.
- * tolower: (libc)Case Conversion.
- * TOSTOP: (libc)Local Modes.
- * totalorderf: (libc)FP Comparison Functions.
- * totalorder: (libc)FP Comparison Functions.
- * totalorderl: (libc)FP Comparison Functions.
- * totalordermagf: (libc)FP Comparison Functions.
- * totalordermag: (libc)FP Comparison Functions.
- * totalordermagl: (libc)FP Comparison Functions.
- * _toupper: (libc)Case Conversion.
- * toupper: (libc)Case Conversion.
- * towctrans: (libc)Wide Character Case Conversion.
- * towlower: (libc)Wide Character Case Conversion.
- * towupper: (libc)Wide Character Case Conversion.
- * truncate64: (libc)File Size.
- * truncate: (libc)File Size.
- * truncf: (libc)Rounding Functions.
- * trunc: (libc)Rounding Functions.
- * truncl: (libc)Rounding Functions.
- * tsearch: (libc)Tree Search Function.
- * ttyname: (libc)Is It a Terminal.
- * ttyname_r: (libc)Is It a Terminal.
- * twalk: (libc)Tree Search Function.
- * TZNAME_MAX: (libc)General Limits.
- * tzset: (libc)Time Zone Functions.
- * ufromfpf: (libc)Rounding Functions.
- * ufromfp: (libc)Rounding Functions.
- * ufromfpl: (libc)Rounding Functions.
- * ufromfpxf: (libc)Rounding Functions.
- * ufromfpx: (libc)Rounding Functions.
- * ufromfpxl: (libc)Rounding Functions.
- * ulimit: (libc)Limits on Resources.
- * umask: (libc)Setting Permissions.
- * umount2: (libc)Mount-Unmount-Remount.
- * umount: (libc)Mount-Unmount-Remount.
- * uname: (libc)Platform Type.
- * ungetc: (libc)How Unread.
- * ungetwc: (libc)How Unread.
- * unlink: (libc)Deleting Files.
- * unlockpt: (libc)Allocation.
- * unsetenv: (libc)Environment Access.
- * updwtmp: (libc)Manipulating the Database.
- * utime: (libc)File Times.
- * utimes: (libc)File Times.
- * utmpname: (libc)Manipulating the Database.
- * utmpxname: (libc)XPG Functions.
- * va_arg: (libc)Argument Macros.
- * __va_copy: (libc)Argument Macros.
- * va_copy: (libc)Argument Macros.
- * va_end: (libc)Argument Macros.
- * valloc: (libc)Aligned Memory Blocks.
- * vasprintf: (libc)Variable Arguments Output.
- * va_start: (libc)Argument Macros.
- * VDISCARD: (libc)Other Special.
- * VDSUSP: (libc)Signal Characters.
- * VEOF: (libc)Editing Characters.
- * VEOL2: (libc)Editing Characters.
- * VEOL: (libc)Editing Characters.
- * VERASE: (libc)Editing Characters.
- * verr: (libc)Error Messages.
- * verrx: (libc)Error Messages.
- * versionsort64: (libc)Scanning Directory Content.
- * versionsort: (libc)Scanning Directory Content.
- * vfork: (libc)Creating a Process.
- * vfprintf: (libc)Variable Arguments Output.
- * vfscanf: (libc)Variable Arguments Input.
- * vfwprintf: (libc)Variable Arguments Output.
- * vfwscanf: (libc)Variable Arguments Input.
- * VINTR: (libc)Signal Characters.
- * VKILL: (libc)Editing Characters.
- * vlimit: (libc)Limits on Resources.
- * VLNEXT: (libc)Other Special.
- * VMIN: (libc)Noncanonical Input.
- * vprintf: (libc)Variable Arguments Output.
- * VQUIT: (libc)Signal Characters.
- * VREPRINT: (libc)Editing Characters.
- * vscanf: (libc)Variable Arguments Input.
- * vsnprintf: (libc)Variable Arguments Output.
- * vsprintf: (libc)Variable Arguments Output.
- * vsscanf: (libc)Variable Arguments Input.
- * VSTART: (libc)Start/Stop Characters.
- * VSTATUS: (libc)Other Special.
- * VSTOP: (libc)Start/Stop Characters.
- * VSUSP: (libc)Signal Characters.
- * vswprintf: (libc)Variable Arguments Output.
- * vswscanf: (libc)Variable Arguments Input.
- * vsyslog: (libc)syslog; vsyslog.
- * VTIME: (libc)Noncanonical Input.
- * vtimes: (libc)Resource Usage.
- * vwarn: (libc)Error Messages.
- * vwarnx: (libc)Error Messages.
- * VWERASE: (libc)Editing Characters.
- * vwprintf: (libc)Variable Arguments Output.
- * vwscanf: (libc)Variable Arguments Input.
- * wait3: (libc)BSD Wait Functions.
- * wait4: (libc)Process Completion.
- * wait: (libc)Process Completion.
- * waitpid: (libc)Process Completion.
- * warn: (libc)Error Messages.
- * warnx: (libc)Error Messages.
- * WCHAR_MAX: (libc)Extended Char Intro.
- * WCHAR_MIN: (libc)Extended Char Intro.
- * WCOREDUMP: (libc)Process Completion Status.
- * wcpcpy: (libc)Copying Strings and Arrays.
- * wcpncpy: (libc)Truncating Strings.
- * wcrtomb: (libc)Converting a Character.
- * wcscasecmp: (libc)String/Array Comparison.
- * wcscat: (libc)Concatenating Strings.
- * wcschr: (libc)Search Functions.
- * wcschrnul: (libc)Search Functions.
- * wcscmp: (libc)String/Array Comparison.
- * wcscoll: (libc)Collation Functions.
- * wcscpy: (libc)Copying Strings and Arrays.
- * wcscspn: (libc)Search Functions.
- * wcsdup: (libc)Copying Strings and Arrays.
- * wcsftime: (libc)Formatting Calendar Time.
- * wcslen: (libc)String Length.
- * wcsncasecmp: (libc)String/Array Comparison.
- * wcsncat: (libc)Truncating Strings.
- * wcsncmp: (libc)String/Array Comparison.
- * wcsncpy: (libc)Truncating Strings.
- * wcsnlen: (libc)String Length.
- * wcsnrtombs: (libc)Converting Strings.
- * wcspbrk: (libc)Search Functions.
- * wcsrchr: (libc)Search Functions.
- * wcsrtombs: (libc)Converting Strings.
- * wcsspn: (libc)Search Functions.
- * wcsstr: (libc)Search Functions.
- * wcstod: (libc)Parsing of Floats.
- * wcstof: (libc)Parsing of Floats.
- * wcstoimax: (libc)Parsing of Integers.
- * wcstok: (libc)Finding Tokens in a String.
- * wcstold: (libc)Parsing of Floats.
- * wcstol: (libc)Parsing of Integers.
- * wcstoll: (libc)Parsing of Integers.
- * wcstombs: (libc)Non-reentrant String Conversion.
- * wcstoq: (libc)Parsing of Integers.
- * wcstoul: (libc)Parsing of Integers.
- * wcstoull: (libc)Parsing of Integers.
- * wcstoumax: (libc)Parsing of Integers.
- * wcstouq: (libc)Parsing of Integers.
- * wcswcs: (libc)Search Functions.
- * wcsxfrm: (libc)Collation Functions.
- * wctob: (libc)Converting a Character.
- * wctomb: (libc)Non-reentrant Character Conversion.
- * wctrans: (libc)Wide Character Case Conversion.
- * wctype: (libc)Classification of Wide Characters.
- * WEOF: (libc)EOF and Errors.
- * WEOF: (libc)Extended Char Intro.
- * WEXITSTATUS: (libc)Process Completion Status.
- * WIFEXITED: (libc)Process Completion Status.
- * WIFSIGNALED: (libc)Process Completion Status.
- * WIFSTOPPED: (libc)Process Completion Status.
- * wmemchr: (libc)Search Functions.
- * wmemcmp: (libc)String/Array Comparison.
- * wmemcpy: (libc)Copying Strings and Arrays.
- * wmemmove: (libc)Copying Strings and Arrays.
- * wmempcpy: (libc)Copying Strings and Arrays.
- * wmemset: (libc)Copying Strings and Arrays.
- * W_OK: (libc)Testing File Access.
- * wordexp: (libc)Calling Wordexp.
- * wordfree: (libc)Calling Wordexp.
- * wprintf: (libc)Formatted Output Functions.
- * write: (libc)I/O Primitives.
- * writev: (libc)Scatter-Gather.
- * wscanf: (libc)Formatted Input Functions.
- * WSTOPSIG: (libc)Process Completion Status.
- * WTERMSIG: (libc)Process Completion Status.
- * X_OK: (libc)Testing File Access.
- * y0f: (libc)Special Functions.
- * y0: (libc)Special Functions.
- * y0l: (libc)Special Functions.
- * y1f: (libc)Special Functions.
- * y1: (libc)Special Functions.
- * y1l: (libc)Special Functions.
- * ynf: (libc)Special Functions.
- * yn: (libc)Special Functions.
- * ynl: (libc)Special Functions.
- END-INFO-DIR-ENTRY
- File: libc.info, Node: Defining the Output Handler, Next: Printf Extension Example, Prev: Conversion Specifier Options, Up: Customizing Printf
- 12.13.3 Defining the Output Handler
- -----------------------------------
- Now let’s look at how to define the handler and arginfo functions which
- are passed as arguments to ‘register_printf_function’.
- *Compatibility Note:* The interface changed in the GNU C Library
- version 2.0. Previously the third argument was of type ‘va_list *’.
- You should define your handler functions with a prototype like:
- int FUNCTION (FILE *stream, const struct printf_info *info,
- const void *const *args)
- The STREAM argument passed to the handler function is the stream to
- which it should write output.
- The INFO argument is a pointer to a structure that contains
- information about the various options that were included with the
- conversion in the template string. You should not modify this structure
- inside your handler function. *Note Conversion Specifier Options::, for
- a description of this data structure.
- The ARGS is a vector of pointers to the arguments data. The number
- of arguments was determined by calling the argument information function
- provided by the user.
- Your handler function should return a value just like ‘printf’ does:
- it should return the number of characters it has written, or a negative
- value to indicate an error.
- -- Data Type: printf_function
- This is the data type that a handler function should have.
- If you are going to use ‘parse_printf_format’ in your application,
- you must also define a function to pass as the ARGINFO-FUNCTION argument
- for each new conversion you install with ‘register_printf_function’.
- You have to define these functions with a prototype like:
- int FUNCTION (const struct printf_info *info,
- size_t n, int *argtypes)
- The return value from the function should be the number of arguments
- the conversion expects. The function should also fill in no more than N
- elements of the ARGTYPES array with information about the types of each
- of these arguments. This information is encoded using the various ‘PA_’
- macros. (You will notice that this is the same calling convention
- ‘parse_printf_format’ itself uses.)
- -- Data Type: printf_arginfo_function
- This type is used to describe functions that return information
- about the number and type of arguments used by a conversion
- specifier.
- File: libc.info, Node: Printf Extension Example, Next: Predefined Printf Handlers, Prev: Defining the Output Handler, Up: Customizing Printf
- 12.13.4 ‘printf’ Extension Example
- ----------------------------------
- Here is an example showing how to define a ‘printf’ handler function.
- This program defines a data structure called a ‘Widget’ and defines the
- ‘%W’ conversion to print information about ‘Widget *’ arguments,
- including the pointer value and the name stored in the data structure.
- The ‘%W’ conversion supports the minimum field width and
- left-justification options, but ignores everything else.
- #include <stdio.h>
- #include <stdlib.h>
- #include <printf.h>
- typedef struct
- {
- char *name;
- }
- Widget;
- int
- print_widget (FILE *stream,
- const struct printf_info *info,
- const void *const *args)
- {
- const Widget *w;
- char *buffer;
- int len;
- /* Format the output into a string. */
- w = *((const Widget **) (args[0]));
- len = asprintf (&buffer, "<Widget %p: %s>", w, w->name);
- if (len == -1)
- return -1;
- /* Pad to the minimum field width and print to the stream. */
- len = fprintf (stream, "%*s",
- (info->left ? -info->width : info->width),
- buffer);
- /* Clean up and return. */
- free (buffer);
- return len;
- }
- int
- print_widget_arginfo (const struct printf_info *info, size_t n,
- int *argtypes)
- {
- /* We always take exactly one argument and this is a pointer to the
- structure.. */
- if (n > 0)
- argtypes[0] = PA_POINTER;
- return 1;
- }
- int
- main (void)
- {
- /* Make a widget to print. */
- Widget mywidget;
- mywidget.name = "mywidget";
- /* Register the print function for widgets. */
- register_printf_function ('W', print_widget, print_widget_arginfo);
- /* Now print the widget. */
- printf ("|%W|\n", &mywidget);
- printf ("|%35W|\n", &mywidget);
- printf ("|%-35W|\n", &mywidget);
- return 0;
- }
- The output produced by this program looks like:
- |<Widget 0xffeffb7c: mywidget>|
- | <Widget 0xffeffb7c: mywidget>|
- |<Widget 0xffeffb7c: mywidget> |
- File: libc.info, Node: Predefined Printf Handlers, Prev: Printf Extension Example, Up: Customizing Printf
- 12.13.5 Predefined ‘printf’ Handlers
- ------------------------------------
- The GNU C Library also contains a concrete and useful application of the
- ‘printf’ handler extension. There are two functions available which
- implement a special way to print floating-point numbers.
- -- Function: int printf_size (FILE *FP, const struct printf_info *INFO,
- const void *const *ARGS)
- Preliminary: | MT-Safe race:fp locale | AS-Unsafe corrupt heap |
- AC-Unsafe mem corrupt | *Note POSIX Safety Concepts::.
- Print a given floating point number as for the format ‘%f’ except
- that there is a postfix character indicating the divisor for the
- number to make this less than 1000. There are two possible
- divisors: powers of 1024 or powers of 1000. Which one is used
- depends on the format character specified while registered this
- handler. If the character is of lower case, 1024 is used. For
- upper case characters, 1000 is used.
- The postfix tag corresponds to bytes, kilobytes, megabytes,
- gigabytes, etc. The full table is:
- low Multiplier From Upper Multiplier
- ’ ’ 1 ’ ’ 1
- k 2^10 (1024) kilo K 10^3 (1000)
- m 2^20 mega M 10^6
- g 2^30 giga G 10^9
- t 2^40 tera T 10^12
- p 2^50 peta P 10^15
- e 2^60 exa E 10^18
- z 2^70 zetta Z 10^21
- y 2^80 yotta Y 10^24
- The default precision is 3, i.e., 1024 is printed with a lower-case
- format character as if it were ‘%.3fk’ and will yield ‘1.000k’.
- Due to the requirements of ‘register_printf_function’ we must also
- provide the function which returns information about the arguments.
- -- Function: int printf_size_info (const struct printf_info *INFO,
- size_t N, int *ARGTYPES)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function will return in ARGTYPES the information about the
- used parameters in the way the ‘vfprintf’ implementation expects
- it. The format always takes one argument.
- To use these functions both functions must be registered with a call
- like
- register_printf_function ('B', printf_size, printf_size_info);
- Here we register the functions to print numbers as powers of 1000
- since the format character ‘'B'’ is an upper-case character. If we
- would additionally use ‘'b'’ in a line like
- register_printf_function ('b', printf_size, printf_size_info);
- we could also print using a power of 1024. Please note that all that is
- different in these two lines is the format specifier. The ‘printf_size’
- function knows about the difference between lower and upper case format
- specifiers.
- The use of ‘'B'’ and ‘'b'’ is no coincidence. Rather it is the
- preferred way to use this functionality since it is available on some
- other systems which also use format specifiers.
- File: libc.info, Node: Formatted Input, Next: EOF and Errors, Prev: Customizing Printf, Up: I/O on Streams
- 12.14 Formatted Input
- =====================
- The functions described in this section (‘scanf’ and related functions)
- provide facilities for formatted input analogous to the formatted output
- facilities. These functions provide a mechanism for reading arbitrary
- values under the control of a "format string" or "template string".
- * Menu:
- * Formatted Input Basics:: Some basics to get you started.
- * Input Conversion Syntax:: Syntax of conversion specifications.
- * Table of Input Conversions:: Summary of input conversions and what they do.
- * Numeric Input Conversions:: Details of conversions for reading numbers.
- * String Input Conversions:: Details of conversions for reading strings.
- * Dynamic String Input:: String conversions that ‘malloc’ the buffer.
- * Other Input Conversions:: Details of miscellaneous other conversions.
- * Formatted Input Functions:: Descriptions of the actual functions.
- * Variable Arguments Input:: ‘vscanf’ and friends.
- File: libc.info, Node: Formatted Input Basics, Next: Input Conversion Syntax, Up: Formatted Input
- 12.14.1 Formatted Input Basics
- ------------------------------
- Calls to ‘scanf’ are superficially similar to calls to ‘printf’ in that
- arbitrary arguments are read under the control of a template string.
- While the syntax of the conversion specifications in the template is
- very similar to that for ‘printf’, the interpretation of the template is
- oriented more towards free-format input and simple pattern matching,
- rather than fixed-field formatting. For example, most ‘scanf’
- conversions skip over any amount of “white space” (including spaces,
- tabs, and newlines) in the input file, and there is no concept of
- precision for the numeric input conversions as there is for the
- corresponding output conversions. Ordinarily, non-whitespace characters
- in the template are expected to match characters in the input stream
- exactly, but a matching failure is distinct from an input error on the
- stream.
- Another area of difference between ‘scanf’ and ‘printf’ is that you
- must remember to supply pointers rather than immediate values as the
- optional arguments to ‘scanf’; the values that are read are stored in
- the objects that the pointers point to. Even experienced programmers
- tend to forget this occasionally, so if your program is getting strange
- errors that seem to be related to ‘scanf’, you might want to
- double-check this.
- When a "matching failure" occurs, ‘scanf’ returns immediately,
- leaving the first non-matching character as the next character to be
- read from the stream. The normal return value from ‘scanf’ is the
- number of values that were assigned, so you can use this to determine if
- a matching error happened before all the expected values were read.
- The ‘scanf’ function is typically used for things like reading in the
- contents of tables. For example, here is a function that uses ‘scanf’
- to initialize an array of ‘double’:
- void
- readarray (double *array, int n)
- {
- int i;
- for (i=0; i<n; i++)
- if (scanf (" %lf", &(array[i])) != 1)
- invalid_input_error ();
- }
- The formatted input functions are not used as frequently as the
- formatted output functions. Partly, this is because it takes some care
- to use them properly. Another reason is that it is difficult to recover
- from a matching error.
- If you are trying to read input that doesn’t match a single, fixed
- pattern, you may be better off using a tool such as Flex to generate a
- lexical scanner, or Bison to generate a parser, rather than using
- ‘scanf’. For more information about these tools, see *note
- (flex.info)Top::, and *note (bison.info)Top::.
- File: libc.info, Node: Input Conversion Syntax, Next: Table of Input Conversions, Prev: Formatted Input Basics, Up: Formatted Input
- 12.14.2 Input Conversion Syntax
- -------------------------------
- A ‘scanf’ template string is a string that contains ordinary multibyte
- characters interspersed with conversion specifications that start with
- ‘%’.
- Any whitespace character (as defined by the ‘isspace’ function; *note
- Classification of Characters::) in the template causes any number of
- whitespace characters in the input stream to be read and discarded. The
- whitespace characters that are matched need not be exactly the same
- whitespace characters that appear in the template string. For example,
- write ‘ , ’ in the template to recognize a comma with optional
- whitespace before and after.
- Other characters in the template string that are not part of
- conversion specifications must match characters in the input stream
- exactly; if this is not the case, a matching failure occurs.
- The conversion specifications in a ‘scanf’ template string have the
- general form:
- % FLAGS WIDTH TYPE CONVERSION
- In more detail, an input conversion specification consists of an
- initial ‘%’ character followed in sequence by:
- • An optional "flag character" ‘*’, which says to ignore the text
- read for this specification. When ‘scanf’ finds a conversion
- specification that uses this flag, it reads input as directed by
- the rest of the conversion specification, but it discards this
- input, does not use a pointer argument, and does not increment the
- count of successful assignments.
- • An optional flag character ‘a’ (valid with string conversions only)
- which requests allocation of a buffer long enough to store the
- string in. (This is a GNU extension.) *Note Dynamic String
- Input::.
- • An optional decimal integer that specifies the "maximum field
- width". Reading of characters from the input stream stops either
- when this maximum is reached or when a non-matching character is
- found, whichever happens first. Most conversions discard initial
- whitespace characters (those that don’t are explicitly documented),
- and these discarded characters don’t count towards the maximum
- field width. String input conversions store a null character to
- mark the end of the input; the maximum field width does not include
- this terminator.
- • An optional "type modifier character". For example, you can
- specify a type modifier of ‘l’ with integer conversions such as
- ‘%d’ to specify that the argument is a pointer to a ‘long int’
- rather than a pointer to an ‘int’.
- • A character that specifies the conversion to be applied.
- The exact options that are permitted and how they are interpreted
- vary between the different conversion specifiers. See the descriptions
- of the individual conversions for information about the particular
- options that they allow.
- With the ‘-Wformat’ option, the GNU C compiler checks calls to
- ‘scanf’ and related functions. It examines the format string and
- verifies that the correct number and types of arguments are supplied.
- There is also a GNU C syntax to tell the compiler that a function you
- write uses a ‘scanf’-style format string. *Note Declaring Attributes of
- Functions: (gcc.info)Function Attributes, for more information.
- File: libc.info, Node: Table of Input Conversions, Next: Numeric Input Conversions, Prev: Input Conversion Syntax, Up: Formatted Input
- 12.14.3 Table of Input Conversions
- ----------------------------------
- Here is a table that summarizes the various conversion specifications:
- ‘%d’
- Matches an optionally signed integer written in decimal. *Note
- Numeric Input Conversions::.
- ‘%i’
- Matches an optionally signed integer in any of the formats that the
- C language defines for specifying an integer constant. *Note
- Numeric Input Conversions::.
- ‘%o’
- Matches an unsigned integer written in octal radix. *Note Numeric
- Input Conversions::.
- ‘%u’
- Matches an unsigned integer written in decimal radix. *Note
- Numeric Input Conversions::.
- ‘%x’, ‘%X’
- Matches an unsigned integer written in hexadecimal radix. *Note
- Numeric Input Conversions::.
- ‘%e’, ‘%f’, ‘%g’, ‘%E’, ‘%G’
- Matches an optionally signed floating-point number. *Note Numeric
- Input Conversions::.
- ‘%s’
- Matches a string containing only non-whitespace characters. *Note
- String Input Conversions::. The presence of the ‘l’ modifier
- determines whether the output is stored as a wide character string
- or a multibyte string. If ‘%s’ is used in a wide character
- function the string is converted as with multiple calls to
- ‘wcrtomb’ into a multibyte string. This means that the buffer must
- provide room for ‘MB_CUR_MAX’ bytes for each wide character read.
- In case ‘%ls’ is used in a multibyte function the result is
- converted into wide characters as with multiple calls of ‘mbrtowc’
- before being stored in the user provided buffer.
- ‘%S’
- This is an alias for ‘%ls’ which is supported for compatibility
- with the Unix standard.
- ‘%[’
- Matches a string of characters that belong to a specified set.
- *Note String Input Conversions::. The presence of the ‘l’ modifier
- determines whether the output is stored as a wide character string
- or a multibyte string. If ‘%[’ is used in a wide character
- function the string is converted as with multiple calls to
- ‘wcrtomb’ into a multibyte string. This means that the buffer must
- provide room for ‘MB_CUR_MAX’ bytes for each wide character read.
- In case ‘%l[’ is used in a multibyte function the result is
- converted into wide characters as with multiple calls of ‘mbrtowc’
- before being stored in the user provided buffer.
- ‘%c’
- Matches a string of one or more characters; the number of
- characters read is controlled by the maximum field width given for
- the conversion. *Note String Input Conversions::.
- If ‘%c’ is used in a wide stream function the read value is
- converted from a wide character to the corresponding multibyte
- character before storing it. Note that this conversion can produce
- more than one byte of output and therefore the provided buffer must
- be large enough for up to ‘MB_CUR_MAX’ bytes for each character.
- If ‘%lc’ is used in a multibyte function the input is treated as a
- multibyte sequence (and not bytes) and the result is converted as
- with calls to ‘mbrtowc’.
- ‘%C’
- This is an alias for ‘%lc’ which is supported for compatibility
- with the Unix standard.
- ‘%p’
- Matches a pointer value in the same implementation-defined format
- used by the ‘%p’ output conversion for ‘printf’. *Note Other Input
- Conversions::.
- ‘%n’
- This conversion doesn’t read any characters; it records the number
- of characters read so far by this call. *Note Other Input
- Conversions::.
- ‘%%’
- This matches a literal ‘%’ character in the input stream. No
- corresponding argument is used. *Note Other Input Conversions::.
- If the syntax of a conversion specification is invalid, the behavior
- is undefined. If there aren’t enough function arguments provided to
- supply addresses for all the conversion specifications in the template
- strings that perform assignments, or if the arguments are not of the
- correct types, the behavior is also undefined. On the other hand, extra
- arguments are simply ignored.
- File: libc.info, Node: Numeric Input Conversions, Next: String Input Conversions, Prev: Table of Input Conversions, Up: Formatted Input
- 12.14.4 Numeric Input Conversions
- ---------------------------------
- This section describes the ‘scanf’ conversions for reading numeric
- values.
- The ‘%d’ conversion matches an optionally signed integer in decimal
- radix. The syntax that is recognized is the same as that for the
- ‘strtol’ function (*note Parsing of Integers::) with the value ‘10’ for
- the BASE argument.
- The ‘%i’ conversion matches an optionally signed integer in any of
- the formats that the C language defines for specifying an integer
- constant. The syntax that is recognized is the same as that for the
- ‘strtol’ function (*note Parsing of Integers::) with the value ‘0’ for
- the BASE argument. (You can print integers in this syntax with ‘printf’
- by using the ‘#’ flag character with the ‘%x’, ‘%o’, or ‘%d’ conversion.
- *Note Integer Conversions::.)
- For example, any of the strings ‘10’, ‘0xa’, or ‘012’ could be read
- in as integers under the ‘%i’ conversion. Each of these specifies a
- number with decimal value ‘10’.
- The ‘%o’, ‘%u’, and ‘%x’ conversions match unsigned integers in
- octal, decimal, and hexadecimal radices, respectively. The syntax that
- is recognized is the same as that for the ‘strtoul’ function (*note
- Parsing of Integers::) with the appropriate value (‘8’, ‘10’, or ‘16’)
- for the BASE argument.
- The ‘%X’ conversion is identical to the ‘%x’ conversion. They both
- permit either uppercase or lowercase letters to be used as digits.
- The default type of the corresponding argument for the ‘%d’ and ‘%i’
- conversions is ‘int *’, and ‘unsigned int *’ for the other integer
- conversions. You can use the following type modifiers to specify other
- sizes of integer:
- ‘hh’
- Specifies that the argument is a ‘signed char *’ or ‘unsigned char
- *’.
- This modifier was introduced in ISO C99.
- ‘h’
- Specifies that the argument is a ‘short int *’ or ‘unsigned short
- int *’.
- ‘j’
- Specifies that the argument is a ‘intmax_t *’ or ‘uintmax_t *’.
- This modifier was introduced in ISO C99.
- ‘l’
- Specifies that the argument is a ‘long int *’ or ‘unsigned long int
- *’. Two ‘l’ characters is like the ‘L’ modifier, below.
- If used with ‘%c’ or ‘%s’ the corresponding parameter is considered
- as a pointer to a wide character or wide character string
- respectively. This use of ‘l’ was introduced in Amendment 1 to
- ISO C90.
- ‘ll’
- ‘L’
- ‘q’
- Specifies that the argument is a ‘long long int *’ or ‘unsigned
- long long int *’. (The ‘long long’ type is an extension supported
- by the GNU C compiler. For systems that don’t provide extra-long
- integers, this is the same as ‘long int’.)
- The ‘q’ modifier is another name for the same thing, which comes
- from 4.4 BSD; a ‘long long int’ is sometimes called a “quad” ‘int’.
- ‘t’
- Specifies that the argument is a ‘ptrdiff_t *’.
- This modifier was introduced in ISO C99.
- ‘z’
- Specifies that the argument is a ‘size_t *’.
- This modifier was introduced in ISO C99.
- All of the ‘%e’, ‘%f’, ‘%g’, ‘%E’, and ‘%G’ input conversions are
- interchangeable. They all match an optionally signed floating point
- number, in the same syntax as for the ‘strtod’ function (*note Parsing
- of Floats::).
- For the floating-point input conversions, the default argument type
- is ‘float *’. (This is different from the corresponding output
- conversions, where the default type is ‘double’; remember that ‘float’
- arguments to ‘printf’ are converted to ‘double’ by the default argument
- promotions, but ‘float *’ arguments are not promoted to ‘double *’.)
- You can specify other sizes of float using these type modifiers:
- ‘l’
- Specifies that the argument is of type ‘double *’.
- ‘L’
- Specifies that the argument is of type ‘long double *’.
- For all the above number parsing formats there is an additional
- optional flag ‘'’. When this flag is given the ‘scanf’ function expects
- the number represented in the input string to be formatted according to
- the grouping rules of the currently selected locale (*note General
- Numeric::).
- If the ‘"C"’ or ‘"POSIX"’ locale is selected there is no difference.
- But for a locale which specifies values for the appropriate fields in
- the locale the input must have the correct form in the input. Otherwise
- the longest prefix with a correct form is processed.
- File: libc.info, Node: String Input Conversions, Next: Dynamic String Input, Prev: Numeric Input Conversions, Up: Formatted Input
- 12.14.5 String Input Conversions
- --------------------------------
- This section describes the ‘scanf’ input conversions for reading string
- and character values: ‘%s’, ‘%S’, ‘%[’, ‘%c’, and ‘%C’.
- You have two options for how to receive the input from these
- conversions:
- • Provide a buffer to store it in. This is the default. You should
- provide an argument of type ‘char *’ or ‘wchar_t *’ (the latter if
- the ‘l’ modifier is present).
- *Warning:* To make a robust program, you must make sure that the
- input (plus its terminating null) cannot possibly exceed the size
- of the buffer you provide. In general, the only way to do this is
- to specify a maximum field width one less than the buffer size.
- *If you provide the buffer, always specify a maximum field width to
- prevent overflow.*
- • Ask ‘scanf’ to allocate a big enough buffer, by specifying the ‘a’
- flag character. This is a GNU extension. You should provide an
- argument of type ‘char **’ for the buffer address to be stored in.
- *Note Dynamic String Input::.
- The ‘%c’ conversion is the simplest: it matches a fixed number of
- characters, always. The maximum field width says how many characters to
- read; if you don’t specify the maximum, the default is 1. This
- conversion doesn’t append a null character to the end of the text it
- reads. It also does not skip over initial whitespace characters. It
- reads precisely the next N characters, and fails if it cannot get that
- many. Since there is always a maximum field width with ‘%c’ (whether
- specified, or 1 by default), you can always prevent overflow by making
- the buffer long enough.
- If the format is ‘%lc’ or ‘%C’ the function stores wide characters
- which are converted using the conversion determined at the time the
- stream was opened from the external byte stream. The number of bytes
- read from the medium is limited by ‘MB_CUR_LEN * N’ but at most N wide
- characters get stored in the output string.
- The ‘%s’ conversion matches a string of non-whitespace characters.
- It skips and discards initial whitespace, but stops when it encounters
- more whitespace after having read something. It stores a null character
- at the end of the text that it reads.
- For example, reading the input:
- hello, world
- with the conversion ‘%10c’ produces ‘" hello, wo"’, but reading the same
- input with the conversion ‘%10s’ produces ‘"hello,"’.
- *Warning:* If you do not specify a field width for ‘%s’, then the
- number of characters read is limited only by where the next whitespace
- character appears. This almost certainly means that invalid input can
- make your program crash—which is a bug.
- The ‘%ls’ and ‘%S’ format are handled just like ‘%s’ except that the
- external byte sequence is converted using the conversion associated with
- the stream to wide characters with their own encoding. A width or
- precision specified with the format do not directly determine how many
- bytes are read from the stream since they measure wide characters. But
- an upper limit can be computed by multiplying the value of the width or
- precision by ‘MB_CUR_MAX’.
- To read in characters that belong to an arbitrary set of your choice,
- use the ‘%[’ conversion. You specify the set between the ‘[’ character
- and a following ‘]’ character, using the same syntax used in regular
- expressions for explicit sets of characters. As special cases:
- • A literal ‘]’ character can be specified as the first character of
- the set.
- • An embedded ‘-’ character (that is, one that is not the first or
- last character of the set) is used to specify a range of
- characters.
- • If a caret character ‘^’ immediately follows the initial ‘[’, then
- the set of allowed input characters is everything _except_ the
- characters listed.
- The ‘%[’ conversion does not skip over initial whitespace characters.
- Note that the "character class" syntax available in character sets
- that appear inside regular expressions (such as ‘[:alpha:]’) is _not_
- available in the ‘%[’ conversion.
- Here are some examples of ‘%[’ conversions and what they mean:
- ‘%25[1234567890]’
- Matches a string of up to 25 digits.
- ‘%25[][]’
- Matches a string of up to 25 square brackets.
- ‘%25[^ \f\n\r\t\v]’
- Matches a string up to 25 characters long that doesn’t contain any
- of the standard whitespace characters. This is slightly different
- from ‘%s’, because if the input begins with a whitespace character,
- ‘%[’ reports a matching failure while ‘%s’ simply discards the
- initial whitespace.
- ‘%25[a-z]’
- Matches up to 25 lowercase characters.
- As for ‘%c’ and ‘%s’ the ‘%[’ format is also modified to produce wide
- characters if the ‘l’ modifier is present. All what is said about ‘%ls’
- above is true for ‘%l[’.
- One more reminder: the ‘%s’ and ‘%[’ conversions are *dangerous* if
- you don’t specify a maximum width or use the ‘a’ flag, because input too
- long would overflow whatever buffer you have provided for it. No matter
- how long your buffer is, a user could supply input that is longer. A
- well-written program reports invalid input with a comprehensible error
- message, not with a crash.
- File: libc.info, Node: Dynamic String Input, Next: Other Input Conversions, Prev: String Input Conversions, Up: Formatted Input
- 12.14.6 Dynamically Allocating String Conversions
- -------------------------------------------------
- A GNU extension to formatted input lets you safely read a string with no
- maximum size. Using this feature, you don’t supply a buffer; instead,
- ‘scanf’ allocates a buffer big enough to hold the data and gives you its
- address. To use this feature, write ‘a’ as a flag character, as in
- ‘%as’ or ‘%a[0-9a-z]’.
- The pointer argument you supply for where to store the input should
- have type ‘char **’. The ‘scanf’ function allocates a buffer and stores
- its address in the word that the argument points to. You should free
- the buffer with ‘free’ when you no longer need it.
- Here is an example of using the ‘a’ flag with the ‘%[…]’ conversion
- specification to read a “variable assignment” of the form ‘VARIABLE =
- VALUE’.
- {
- char *variable, *value;
- if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
- &variable, &value))
- {
- invalid_input_error ();
- return 0;
- }
- …
- }
- File: libc.info, Node: Other Input Conversions, Next: Formatted Input Functions, Prev: Dynamic String Input, Up: Formatted Input
- 12.14.7 Other Input Conversions
- -------------------------------
- This section describes the miscellaneous input conversions.
- The ‘%p’ conversion is used to read a pointer value. It recognizes
- the same syntax used by the ‘%p’ output conversion for ‘printf’ (*note
- Other Output Conversions::); that is, a hexadecimal number just as the
- ‘%x’ conversion accepts. The corresponding argument should be of type
- ‘void **’; that is, the address of a place to store a pointer.
- The resulting pointer value is not guaranteed to be valid if it was
- not originally written during the same program execution that reads it
- in.
- The ‘%n’ conversion produces the number of characters read so far by
- this call. The corresponding argument should be of type ‘int *’. This
- conversion works in the same way as the ‘%n’ conversion for ‘printf’;
- see *note Other Output Conversions::, for an example.
- The ‘%n’ conversion is the only mechanism for determining the success
- of literal matches or conversions with suppressed assignments. If the
- ‘%n’ follows the locus of a matching failure, then no value is stored
- for it since ‘scanf’ returns before processing the ‘%n’. If you store
- ‘-1’ in that argument slot before calling ‘scanf’, the presence of ‘-1’
- after ‘scanf’ indicates an error occurred before the ‘%n’ was reached.
- Finally, the ‘%%’ conversion matches a literal ‘%’ character in the
- input stream, without using an argument. This conversion does not
- permit any flags, field width, or type modifier to be specified.
- File: libc.info, Node: Formatted Input Functions, Next: Variable Arguments Input, Prev: Other Input Conversions, Up: Formatted Input
- 12.14.8 Formatted Input Functions
- ---------------------------------
- Here are the descriptions of the functions for performing formatted
- input. Prototypes for these functions are in the header file ‘stdio.h’.
- -- Function: int scanf (const char *TEMPLATE, …)
- Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
- mem lock corrupt | *Note POSIX Safety Concepts::.
- The ‘scanf’ function reads formatted input from the stream ‘stdin’
- under the control of the template string TEMPLATE. The optional
- arguments are pointers to the places which receive the resulting
- values.
- The return value is normally the number of successful assignments.
- If an end-of-file condition is detected before any matches are
- performed, including matches against whitespace and literal
- characters in the template, then ‘EOF’ is returned.
- -- Function: int wscanf (const wchar_t *TEMPLATE, …)
- Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
- mem lock corrupt | *Note POSIX Safety Concepts::.
- The ‘wscanf’ function reads formatted input from the stream ‘stdin’
- under the control of the template string TEMPLATE. The optional
- arguments are pointers to the places which receive the resulting
- values.
- The return value is normally the number of successful assignments.
- If an end-of-file condition is detected before any matches are
- performed, including matches against whitespace and literal
- characters in the template, then ‘WEOF’ is returned.
- -- Function: int fscanf (FILE *STREAM, const char *TEMPLATE, …)
- Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
- mem lock corrupt | *Note POSIX Safety Concepts::.
- This function is just like ‘scanf’, except that the input is read
- from the stream STREAM instead of ‘stdin’.
- -- Function: int fwscanf (FILE *STREAM, const wchar_t *TEMPLATE, …)
- Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
- mem lock corrupt | *Note POSIX Safety Concepts::.
- This function is just like ‘wscanf’, except that the input is read
- from the stream STREAM instead of ‘stdin’.
- -- Function: int sscanf (const char *S, const char *TEMPLATE, …)
- Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
- *Note POSIX Safety Concepts::.
- This is like ‘scanf’, except that the characters are taken from the
- null-terminated string S instead of from a stream. Reaching the
- end of the string is treated as an end-of-file condition.
- The behavior of this function is undefined if copying takes place
- between objects that overlap—for example, if S is also given as an
- argument to receive a string read under control of the ‘%s’, ‘%S’,
- or ‘%[’ conversion.
- -- Function: int swscanf (const wchar_t *WS, const wchar_t *TEMPLATE,
- …)
- Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
- *Note POSIX Safety Concepts::.
- This is like ‘wscanf’, except that the characters are taken from
- the null-terminated string WS instead of from a stream. Reaching
- the end of the string is treated as an end-of-file condition.
- The behavior of this function is undefined if copying takes place
- between objects that overlap—for example, if WS is also given as an
- argument to receive a string read under control of the ‘%s’, ‘%S’,
- or ‘%[’ conversion.
- File: libc.info, Node: Variable Arguments Input, Prev: Formatted Input Functions, Up: Formatted Input
- 12.14.9 Variable Arguments Input Functions
- ------------------------------------------
- The functions ‘vscanf’ and friends are provided so that you can define
- your own variadic ‘scanf’-like functions that make use of the same
- internals as the built-in formatted output functions. These functions
- are analogous to the ‘vprintf’ series of output functions. *Note
- Variable Arguments Output::, for important information on how to use
- them.
- *Portability Note:* The functions listed in this section were
- introduced in ISO C99 and were before available as GNU extensions.
- -- Function: int vscanf (const char *TEMPLATE, va_list AP)
- Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
- mem lock corrupt | *Note POSIX Safety Concepts::.
- This function is similar to ‘scanf’, but instead of taking a
- variable number of arguments directly, it takes an argument list
- pointer AP of type ‘va_list’ (*note Variadic Functions::).
- -- Function: int vwscanf (const wchar_t *TEMPLATE, va_list AP)
- Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
- mem lock corrupt | *Note POSIX Safety Concepts::.
- This function is similar to ‘wscanf’, but instead of taking a
- variable number of arguments directly, it takes an argument list
- pointer AP of type ‘va_list’ (*note Variadic Functions::).
- -- Function: int vfscanf (FILE *STREAM, const char *TEMPLATE, va_list
- AP)
- Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
- mem lock corrupt | *Note POSIX Safety Concepts::.
- This is the equivalent of ‘fscanf’ with the variable argument list
- specified directly as for ‘vscanf’.
- -- Function: int vfwscanf (FILE *STREAM, const wchar_t *TEMPLATE,
- va_list AP)
- Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
- mem lock corrupt | *Note POSIX Safety Concepts::.
- This is the equivalent of ‘fwscanf’ with the variable argument list
- specified directly as for ‘vwscanf’.
- -- Function: int vsscanf (const char *S, const char *TEMPLATE, va_list
- AP)
- Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
- *Note POSIX Safety Concepts::.
- This is the equivalent of ‘sscanf’ with the variable argument list
- specified directly as for ‘vscanf’.
- -- Function: int vswscanf (const wchar_t *S, const wchar_t *TEMPLATE,
- va_list AP)
- Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
- *Note POSIX Safety Concepts::.
- This is the equivalent of ‘swscanf’ with the variable argument list
- specified directly as for ‘vwscanf’.
- In GNU C, there is a special construct you can use to let the
- compiler know that a function uses a ‘scanf’-style format string. Then
- it can check the number and types of arguments in each call to the
- function, and warn you when they do not match the format string. For
- details, see *note Declaring Attributes of Functions: (gcc.info)Function
- Attributes.
- File: libc.info, Node: EOF and Errors, Next: Error Recovery, Prev: Formatted Input, Up: I/O on Streams
- 12.15 End-Of-File and Errors
- ============================
- Many of the functions described in this chapter return the value of the
- macro ‘EOF’ to indicate unsuccessful completion of the operation. Since
- ‘EOF’ is used to report both end of file and random errors, it’s often
- better to use the ‘feof’ function to check explicitly for end of file
- and ‘ferror’ to check for errors. These functions check indicators that
- are part of the internal state of the stream object, indicators set if
- the appropriate condition was detected by a previous I/O operation on
- that stream.
- -- Macro: int EOF
- This macro is an integer value that is returned by a number of
- narrow stream functions to indicate an end-of-file condition, or
- some other error situation. With the GNU C Library, ‘EOF’ is ‘-1’.
- In other libraries, its value may be some other negative number.
- This symbol is declared in ‘stdio.h’.
- -- Macro: int WEOF
- This macro is an integer value that is returned by a number of wide
- stream functions to indicate an end-of-file condition, or some
- other error situation. With the GNU C Library, ‘WEOF’ is ‘-1’. In
- other libraries, its value may be some other negative number.
- This symbol is declared in ‘wchar.h’.
- -- Function: int feof (FILE *STREAM)
- Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
- Safety Concepts::.
- The ‘feof’ function returns nonzero if and only if the end-of-file
- indicator for the stream STREAM is set.
- This symbol is declared in ‘stdio.h’.
- -- Function: int feof_unlocked (FILE *STREAM)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘feof_unlocked’ function is equivalent to the ‘feof’ function
- except that it does not implicitly lock the stream.
- This function is a GNU extension.
- This symbol is declared in ‘stdio.h’.
- -- Function: int ferror (FILE *STREAM)
- Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
- Safety Concepts::.
- The ‘ferror’ function returns nonzero if and only if the error
- indicator for the stream STREAM is set, indicating that an error
- has occurred on a previous operation on the stream.
- This symbol is declared in ‘stdio.h’.
- -- Function: int ferror_unlocked (FILE *STREAM)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘ferror_unlocked’ function is equivalent to the ‘ferror’
- function except that it does not implicitly lock the stream.
- This function is a GNU extension.
- This symbol is declared in ‘stdio.h’.
- In addition to setting the error indicator associated with the
- stream, the functions that operate on streams also set ‘errno’ in the
- same way as the corresponding low-level functions that operate on file
- descriptors. For example, all of the functions that perform output to a
- stream—such as ‘fputc’, ‘printf’, and ‘fflush’—are implemented in terms
- of ‘write’, and all of the ‘errno’ error conditions defined for ‘write’
- are meaningful for these functions. For more information about the
- descriptor-level I/O functions, see *note Low-Level I/O::.
- File: libc.info, Node: Error Recovery, Next: Binary Streams, Prev: EOF and Errors, Up: I/O on Streams
- 12.16 Recovering from errors
- ============================
- You may explicitly clear the error and EOF flags with the ‘clearerr’
- function.
- -- Function: void clearerr (FILE *STREAM)
- Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
- Safety Concepts::.
- This function clears the end-of-file and error indicators for the
- stream STREAM.
- The file positioning functions (*note File Positioning::) also
- clear the end-of-file indicator for the stream.
- -- Function: void clearerr_unlocked (FILE *STREAM)
- Preliminary: | MT-Safe race:stream | AS-Safe | AC-Safe | *Note
- POSIX Safety Concepts::.
- The ‘clearerr_unlocked’ function is equivalent to the ‘clearerr’
- function except that it does not implicitly lock the stream.
- This function is a GNU extension.
- Note that it is _not_ correct to just clear the error flag and retry
- a failed stream operation. After a failed write, any number of
- characters since the last buffer flush may have been committed to the
- file, while some buffered data may have been discarded. Merely retrying
- can thus cause lost or repeated data.
- A failed read may leave the file pointer in an inappropriate position
- for a second try. In both cases, you should seek to a known position
- before retrying.
- Most errors that can happen are not recoverable — a second try will
- always fail again in the same way. So usually it is best to give up and
- report the error to the user, rather than install complicated recovery
- logic.
- One important exception is ‘EINTR’ (*note Interrupted Primitives::).
- Many stream I/O implementations will treat it as an ordinary error,
- which can be quite inconvenient. You can avoid this hassle by
- installing all signals with the ‘SA_RESTART’ flag.
- For similar reasons, setting nonblocking I/O on a stream’s file
- descriptor is not usually advisable.
- File: libc.info, Node: Binary Streams, Next: File Positioning, Prev: Error Recovery, Up: I/O on Streams
- 12.17 Text and Binary Streams
- =============================
- GNU systems and other POSIX-compatible operating systems organize all
- files as uniform sequences of characters. However, some other systems
- make a distinction between files containing text and files containing
- binary data, and the input and output facilities of ISO C provide for
- this distinction. This section tells you how to write programs portable
- to such systems.
- When you open a stream, you can specify either a "text stream" or a
- "binary stream". You indicate that you want a binary stream by
- specifying the ‘b’ modifier in the OPENTYPE argument to ‘fopen’; see
- *note Opening Streams::. Without this option, ‘fopen’ opens the file as
- a text stream.
- Text and binary streams differ in several ways:
- • The data read from a text stream is divided into "lines" which are
- terminated by newline (‘'\n'’) characters, while a binary stream is
- simply a long series of characters. A text stream might on some
- systems fail to handle lines more than 254 characters long
- (including the terminating newline character).
- • On some systems, text files can contain only printing characters,
- horizontal tab characters, and newlines, and so text streams may
- not support other characters. However, binary streams can handle
- any character value.
- • Space characters that are written immediately preceding a newline
- character in a text stream may disappear when the file is read in
- again.
- • More generally, there need not be a one-to-one mapping between
- characters that are read from or written to a text stream, and the
- characters in the actual file.
- Since a binary stream is always more capable and more predictable
- than a text stream, you might wonder what purpose text streams serve.
- Why not simply always use binary streams? The answer is that on these
- operating systems, text and binary streams use different file formats,
- and the only way to read or write “an ordinary file of text” that can
- work with other text-oriented programs is through a text stream.
- In the GNU C Library, and on all POSIX systems, there is no
- difference between text streams and binary streams. When you open a
- stream, you get the same kind of stream regardless of whether you ask
- for binary. This stream can handle any file content, and has none of
- the restrictions that text streams sometimes have.
- File: libc.info, Node: File Positioning, Next: Portable Positioning, Prev: Binary Streams, Up: I/O on Streams
- 12.18 File Positioning
- ======================
- The "file position" of a stream describes where in the file the stream
- is currently reading or writing. I/O on the stream advances the file
- position through the file. On GNU systems, the file position is
- represented as an integer, which counts the number of bytes from the
- beginning of the file. *Note File Position::.
- During I/O to an ordinary disk file, you can change the file position
- whenever you wish, so as to read or write any portion of the file. Some
- other kinds of files may also permit this. Files which support changing
- the file position are sometimes referred to as "random-access" files.
- You can use the functions in this section to examine or modify the
- file position indicator associated with a stream. The symbols listed
- below are declared in the header file ‘stdio.h’.
- -- Function: long int ftell (FILE *STREAM)
- Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
- | *Note POSIX Safety Concepts::.
- This function returns the current file position of the stream
- STREAM.
- This function can fail if the stream doesn’t support file
- positioning, or if the file position can’t be represented in a
- ‘long int’, and possibly for other reasons as well. If a failure
- occurs, a value of ‘-1’ is returned.
- -- Function: off_t ftello (FILE *STREAM)
- Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
- | *Note POSIX Safety Concepts::.
- The ‘ftello’ function is similar to ‘ftell’, except that it returns
- a value of type ‘off_t’. Systems which support this type use it to
- describe all file positions, unlike the POSIX specification which
- uses a long int. The two are not necessarily the same size.
- Therefore, using ftell can lead to problems if the implementation
- is written on top of a POSIX compliant low-level I/O
- implementation, and using ‘ftello’ is preferable whenever it is
- available.
- If this function fails it returns ‘(off_t) -1’. This can happen
- due to missing support for file positioning or internal errors.
- Otherwise the return value is the current file position.
- The function is an extension defined in the Unix Single
- Specification version 2.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
- 32 bit system this function is in fact ‘ftello64’. I.e., the LFS
- interface transparently replaces the old interface.
- -- Function: off64_t ftello64 (FILE *STREAM)
- Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
- | *Note POSIX Safety Concepts::.
- This function is similar to ‘ftello’ with the only difference that
- the return value is of type ‘off64_t’. This also requires that the
- stream STREAM was opened using either ‘fopen64’, ‘freopen64’, or
- ‘tmpfile64’ since otherwise the underlying file operations to
- position the file pointer beyond the 2^31 bytes limit might fail.
- If the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a 32
- bits machine this function is available under the name ‘ftello’ and
- so transparently replaces the old interface.
- -- Function: int fseek (FILE *STREAM, long int OFFSET, int WHENCE)
- Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
- | *Note POSIX Safety Concepts::.
- The ‘fseek’ function is used to change the file position of the
- stream STREAM. The value of WHENCE must be one of the constants
- ‘SEEK_SET’, ‘SEEK_CUR’, or ‘SEEK_END’, to indicate whether the
- OFFSET is relative to the beginning of the file, the current file
- position, or the end of the file, respectively.
- This function returns a value of zero if the operation was
- successful, and a nonzero value to indicate failure. A successful
- call also clears the end-of-file indicator of STREAM and discards
- any characters that were “pushed back” by the use of ‘ungetc’.
- ‘fseek’ either flushes any buffered output before setting the file
- position or else remembers it so it will be written later in its
- proper place in the file.
- -- Function: int fseeko (FILE *STREAM, off_t OFFSET, int WHENCE)
- Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
- | *Note POSIX Safety Concepts::.
- This function is similar to ‘fseek’ but it corrects a problem with
- ‘fseek’ in a system with POSIX types. Using a value of type ‘long
- int’ for the offset is not compatible with POSIX. ‘fseeko’ uses the
- correct type ‘off_t’ for the OFFSET parameter.
- For this reason it is a good idea to prefer ‘ftello’ whenever it is
- available since its functionality is (if different at all) closer
- the underlying definition.
- The functionality and return value are the same as for ‘fseek’.
- The function is an extension defined in the Unix Single
- Specification version 2.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
- 32 bit system this function is in fact ‘fseeko64’. I.e., the LFS
- interface transparently replaces the old interface.
- -- Function: int fseeko64 (FILE *STREAM, off64_t OFFSET, int WHENCE)
- Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
- | *Note POSIX Safety Concepts::.
- This function is similar to ‘fseeko’ with the only difference that
- the OFFSET parameter is of type ‘off64_t’. This also requires that
- the stream STREAM was opened using either ‘fopen64’, ‘freopen64’,
- or ‘tmpfile64’ since otherwise the underlying file operations to
- position the file pointer beyond the 2^31 bytes limit might fail.
- If the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a 32
- bits machine this function is available under the name ‘fseeko’ and
- so transparently replaces the old interface.
- *Portability Note:* In non-POSIX systems, ‘ftell’, ‘ftello’, ‘fseek’
- and ‘fseeko’ might work reliably only on binary streams. *Note Binary
- Streams::.
- The following symbolic constants are defined for use as the WHENCE
- argument to ‘fseek’. They are also used with the ‘lseek’ function
- (*note I/O Primitives::) and to specify offsets for file locks (*note
- Control Operations::).
- -- Macro: int SEEK_SET
- This is an integer constant which, when used as the WHENCE argument
- to the ‘fseek’ or ‘fseeko’ functions, specifies that the offset
- provided is relative to the beginning of the file.
- -- Macro: int SEEK_CUR
- This is an integer constant which, when used as the WHENCE argument
- to the ‘fseek’ or ‘fseeko’ functions, specifies that the offset
- provided is relative to the current file position.
- -- Macro: int SEEK_END
- This is an integer constant which, when used as the WHENCE argument
- to the ‘fseek’ or ‘fseeko’ functions, specifies that the offset
- provided is relative to the end of the file.
- -- Function: void rewind (FILE *STREAM)
- Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
- | *Note POSIX Safety Concepts::.
- The ‘rewind’ function positions the stream STREAM at the beginning
- of the file. It is equivalent to calling ‘fseek’ or ‘fseeko’ on
- the STREAM with an OFFSET argument of ‘0L’ and a WHENCE argument of
- ‘SEEK_SET’, except that the return value is discarded and the error
- indicator for the stream is reset.
- These three aliases for the ‘SEEK_…’ constants exist for the sake of
- compatibility with older BSD systems. They are defined in two different
- header files: ‘fcntl.h’ and ‘sys/file.h’.
- ‘L_SET’
- An alias for ‘SEEK_SET’.
- ‘L_INCR’
- An alias for ‘SEEK_CUR’.
- ‘L_XTND’
- An alias for ‘SEEK_END’.
- File: libc.info, Node: Portable Positioning, Next: Stream Buffering, Prev: File Positioning, Up: I/O on Streams
- 12.19 Portable File-Position Functions
- ======================================
- On GNU systems, the file position is truly a character count. You can
- specify any character count value as an argument to ‘fseek’ or ‘fseeko’
- and get reliable results for any random access file. However, some ISO C
- systems do not represent file positions in this way.
- On some systems where text streams truly differ from binary streams,
- it is impossible to represent the file position of a text stream as a
- count of characters from the beginning of the file. For example, the
- file position on some systems must encode both a record offset within
- the file, and a character offset within the record.
- As a consequence, if you want your programs to be portable to these
- systems, you must observe certain rules:
- • The value returned from ‘ftell’ on a text stream has no predictable
- relationship to the number of characters you have read so far. The
- only thing you can rely on is that you can use it subsequently as
- the OFFSET argument to ‘fseek’ or ‘fseeko’ to move back to the same
- file position.
- • In a call to ‘fseek’ or ‘fseeko’ on a text stream, either the
- OFFSET must be zero, or WHENCE must be ‘SEEK_SET’ and the OFFSET
- must be the result of an earlier call to ‘ftell’ on the same
- stream.
- • The value of the file position indicator of a text stream is
- undefined while there are characters that have been pushed back
- with ‘ungetc’ that haven’t been read or discarded. *Note
- Unreading::.
- But even if you observe these rules, you may still have trouble for
- long files, because ‘ftell’ and ‘fseek’ use a ‘long int’ value to
- represent the file position. This type may not have room to encode all
- the file positions in a large file. Using the ‘ftello’ and ‘fseeko’
- functions might help here since the ‘off_t’ type is expected to be able
- to hold all file position values but this still does not help to handle
- additional information which must be associated with a file position.
- So if you do want to support systems with peculiar encodings for the
- file positions, it is better to use the functions ‘fgetpos’ and
- ‘fsetpos’ instead. These functions represent the file position using
- the data type ‘fpos_t’, whose internal representation varies from system
- to system.
- These symbols are declared in the header file ‘stdio.h’.
- -- Data Type: fpos_t
- This is the type of an object that can encode information about the
- file position of a stream, for use by the functions ‘fgetpos’ and
- ‘fsetpos’.
- In the GNU C Library, ‘fpos_t’ is an opaque data structure that
- contains internal data to represent file offset and conversion
- state information. In other systems, it might have a different
- internal representation.
- When compiling with ‘_FILE_OFFSET_BITS == 64’ on a 32 bit machine
- this type is in fact equivalent to ‘fpos64_t’ since the LFS
- interface transparently replaces the old interface.
- -- Data Type: fpos64_t
- This is the type of an object that can encode information about the
- file position of a stream, for use by the functions ‘fgetpos64’ and
- ‘fsetpos64’.
- In the GNU C Library, ‘fpos64_t’ is an opaque data structure that
- contains internal data to represent file offset and conversion
- state information. In other systems, it might have a different
- internal representation.
- -- Function: int fgetpos (FILE *STREAM, fpos_t *POSITION)
- Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
- | *Note POSIX Safety Concepts::.
- This function stores the value of the file position indicator for
- the stream STREAM in the ‘fpos_t’ object pointed to by POSITION.
- If successful, ‘fgetpos’ returns zero; otherwise it returns a
- nonzero value and stores an implementation-defined positive value
- in ‘errno’.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
- 32 bit system the function is in fact ‘fgetpos64’. I.e., the LFS
- interface transparently replaces the old interface.
- -- Function: int fgetpos64 (FILE *STREAM, fpos64_t *POSITION)
- Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
- | *Note POSIX Safety Concepts::.
- This function is similar to ‘fgetpos’ but the file position is
- returned in a variable of type ‘fpos64_t’ to which POSITION points.
- If the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a 32
- bits machine this function is available under the name ‘fgetpos’
- and so transparently replaces the old interface.
- -- Function: int fsetpos (FILE *STREAM, const fpos_t *POSITION)
- Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
- | *Note POSIX Safety Concepts::.
- This function sets the file position indicator for the stream
- STREAM to the position POSITION, which must have been set by a
- previous call to ‘fgetpos’ on the same stream. If successful,
- ‘fsetpos’ clears the end-of-file indicator on the stream, discards
- any characters that were “pushed back” by the use of ‘ungetc’, and
- returns a value of zero. Otherwise, ‘fsetpos’ returns a nonzero
- value and stores an implementation-defined positive value in
- ‘errno’.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
- 32 bit system the function is in fact ‘fsetpos64’. I.e., the LFS
- interface transparently replaces the old interface.
- -- Function: int fsetpos64 (FILE *STREAM, const fpos64_t *POSITION)
- Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
- | *Note POSIX Safety Concepts::.
- This function is similar to ‘fsetpos’ but the file position used
- for positioning is provided in a variable of type ‘fpos64_t’ to
- which POSITION points.
- If the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a 32
- bits machine this function is available under the name ‘fsetpos’
- and so transparently replaces the old interface.
- File: libc.info, Node: Stream Buffering, Next: Other Kinds of Streams, Prev: Portable Positioning, Up: I/O on Streams
- 12.20 Stream Buffering
- ======================
- Characters that are written to a stream are normally accumulated and
- transmitted asynchronously to the file in a block, instead of appearing
- as soon as they are output by the application program. Similarly,
- streams often retrieve input from the host environment in blocks rather
- than on a character-by-character basis. This is called "buffering".
- If you are writing programs that do interactive input and output
- using streams, you need to understand how buffering works when you
- design the user interface to your program. Otherwise, you might find
- that output (such as progress or prompt messages) doesn’t appear when
- you intended it to, or displays some other unexpected behavior.
- This section deals only with controlling when characters are
- transmitted between the stream and the file or device, and _not_ with
- how things like echoing, flow control, and the like are handled on
- specific classes of devices. For information on common control
- operations on terminal devices, see *note Low-Level Terminal
- Interface::.
- You can bypass the stream buffering facilities altogether by using
- the low-level input and output functions that operate on file
- descriptors instead. *Note Low-Level I/O::.
- * Menu:
- * Buffering Concepts:: Terminology is defined here.
- * Flushing Buffers:: How to ensure that output buffers are flushed.
- * Controlling Buffering:: How to specify what kind of buffering to use.
- File: libc.info, Node: Buffering Concepts, Next: Flushing Buffers, Up: Stream Buffering
- 12.20.1 Buffering Concepts
- --------------------------
- There are three different kinds of buffering strategies:
- • Characters written to or read from an "unbuffered" stream are
- transmitted individually to or from the file as soon as possible.
- • Characters written to a "line buffered" stream are transmitted to
- the file in blocks when a newline character is encountered.
- • Characters written to or read from a "fully buffered" stream are
- transmitted to or from the file in blocks of arbitrary size.
- Newly opened streams are normally fully buffered, with one exception:
- a stream connected to an interactive device such as a terminal is
- initially line buffered. *Note Controlling Buffering::, for information
- on how to select a different kind of buffering. Usually the automatic
- selection gives you the most convenient kind of buffering for the file
- or device you open.
- The use of line buffering for interactive devices implies that output
- messages ending in a newline will appear immediately—which is usually
- what you want. Output that doesn’t end in a newline might or might not
- show up immediately, so if you want them to appear immediately, you
- should flush buffered output explicitly with ‘fflush’, as described in
- *note Flushing Buffers::.
- File: libc.info, Node: Flushing Buffers, Next: Controlling Buffering, Prev: Buffering Concepts, Up: Stream Buffering
- 12.20.2 Flushing Buffers
- ------------------------
- "Flushing" output on a buffered stream means transmitting all
- accumulated characters to the file. There are many circumstances when
- buffered output on a stream is flushed automatically:
- • When you try to do output and the output buffer is full.
- • When the stream is closed. *Note Closing Streams::.
- • When the program terminates by calling ‘exit’. *Note Normal
- Termination::.
- • When a newline is written, if the stream is line buffered.
- • Whenever an input operation on _any_ stream actually reads data
- from its file.
- If you want to flush the buffered output at another time, call
- ‘fflush’, which is declared in the header file ‘stdio.h’.
- -- Function: int fflush (FILE *STREAM)
- Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
- | *Note POSIX Safety Concepts::.
- This function causes any buffered output on STREAM to be delivered
- to the file. If STREAM is a null pointer, then ‘fflush’ causes
- buffered output on _all_ open output streams to be flushed.
- This function returns ‘EOF’ if a write error occurs, or zero
- otherwise.
- -- Function: int fflush_unlocked (FILE *STREAM)
- Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
- corrupt | *Note POSIX Safety Concepts::.
- The ‘fflush_unlocked’ function is equivalent to the ‘fflush’
- function except that it does not implicitly lock the stream.
- The ‘fflush’ function can be used to flush all streams currently
- opened. While this is useful in some situations it does often more than
- necessary since it might be done in situations when terminal input is
- required and the program wants to be sure that all output is visible on
- the terminal. But this means that only line buffered streams have to be
- flushed. Solaris introduced a function especially for this. It was
- always available in the GNU C Library in some form but never officially
- exported.
- -- Function: void _flushlbf (void)
- Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
- | *Note POSIX Safety Concepts::.
- The ‘_flushlbf’ function flushes all line buffered streams
- currently opened.
- This function is declared in the ‘stdio_ext.h’ header.
- *Compatibility Note:* Some brain-damaged operating systems have been
- known to be so thoroughly fixated on line-oriented input and output that
- flushing a line buffered stream causes a newline to be written!
- Fortunately, this “feature” seems to be becoming less common. You do
- not need to worry about this with the GNU C Library.
- In some situations it might be useful to not flush the output pending
- for a stream but instead simply forget it. If transmission is costly
- and the output is not needed anymore this is valid reasoning. In this
- situation a non-standard function introduced in Solaris and available in
- the GNU C Library can be used.
- -- Function: void __fpurge (FILE *STREAM)
- Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
- corrupt | *Note POSIX Safety Concepts::.
- The ‘__fpurge’ function causes the buffer of the stream STREAM to
- be emptied. If the stream is currently in read mode all input in
- the buffer is lost. If the stream is in output mode the buffered
- output is not written to the device (or whatever other underlying
- storage) and the buffer is cleared.
- This function is declared in ‘stdio_ext.h’.
- File: libc.info, Node: Controlling Buffering, Prev: Flushing Buffers, Up: Stream Buffering
- 12.20.3 Controlling Which Kind of Buffering
- -------------------------------------------
- After opening a stream (but before any other operations have been
- performed on it), you can explicitly specify what kind of buffering you
- want it to have using the ‘setvbuf’ function.
- The facilities listed in this section are declared in the header file
- ‘stdio.h’.
- -- Function: int setvbuf (FILE *STREAM, char *BUF, int MODE, size_t
- SIZE)
- Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
- | *Note POSIX Safety Concepts::.
- This function is used to specify that the stream STREAM should have
- the buffering mode MODE, which can be either ‘_IOFBF’ (for full
- buffering), ‘_IOLBF’ (for line buffering), or ‘_IONBF’ (for
- unbuffered input/output).
- If you specify a null pointer as the BUF argument, then ‘setvbuf’
- allocates a buffer itself using ‘malloc’. This buffer will be
- freed when you close the stream.
- Otherwise, BUF should be a character array that can hold at least
- SIZE characters. You should not free the space for this array as
- long as the stream remains open and this array remains its buffer.
- You should usually either allocate it statically, or ‘malloc’
- (*note Unconstrained Allocation::) the buffer. Using an automatic
- array is not a good idea unless you close the file before exiting
- the block that declares the array.
- While the array remains a stream buffer, the stream I/O functions
- will use the buffer for their internal purposes. You shouldn’t try
- to access the values in the array directly while the stream is
- using it for buffering.
- The ‘setvbuf’ function returns zero on success, or a nonzero value
- if the value of MODE is not valid or if the request could not be
- honored.
- -- Macro: int _IOFBF
- The value of this macro is an integer constant expression that can
- be used as the MODE argument to the ‘setvbuf’ function to specify
- that the stream should be fully buffered.
- -- Macro: int _IOLBF
- The value of this macro is an integer constant expression that can
- be used as the MODE argument to the ‘setvbuf’ function to specify
- that the stream should be line buffered.
- -- Macro: int _IONBF
- The value of this macro is an integer constant expression that can
- be used as the MODE argument to the ‘setvbuf’ function to specify
- that the stream should be unbuffered.
- -- Macro: int BUFSIZ
- The value of this macro is an integer constant expression that is
- good to use for the SIZE argument to ‘setvbuf’. This value is
- guaranteed to be at least ‘256’.
- The value of ‘BUFSIZ’ is chosen on each system so as to make stream
- I/O efficient. So it is a good idea to use ‘BUFSIZ’ as the size
- for the buffer when you call ‘setvbuf’.
- Actually, you can get an even better value to use for the buffer
- size by means of the ‘fstat’ system call: it is found in the
- ‘st_blksize’ field of the file attributes. *Note Attribute
- Meanings::.
- Sometimes people also use ‘BUFSIZ’ as the allocation size of
- buffers used for related purposes, such as strings used to receive
- a line of input with ‘fgets’ (*note Character Input::). There is
- no particular reason to use ‘BUFSIZ’ for this instead of any other
- integer, except that it might lead to doing I/O in chunks of an
- efficient size.
- -- Function: void setbuf (FILE *STREAM, char *BUF)
- Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
- | *Note POSIX Safety Concepts::.
- If BUF is a null pointer, the effect of this function is equivalent
- to calling ‘setvbuf’ with a MODE argument of ‘_IONBF’. Otherwise,
- it is equivalent to calling ‘setvbuf’ with BUF, and a MODE of
- ‘_IOFBF’ and a SIZE argument of ‘BUFSIZ’.
- The ‘setbuf’ function is provided for compatibility with old code;
- use ‘setvbuf’ in all new programs.
- -- Function: void setbuffer (FILE *STREAM, char *BUF, size_t SIZE)
- Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
- | *Note POSIX Safety Concepts::.
- If BUF is a null pointer, this function makes STREAM unbuffered.
- Otherwise, it makes STREAM fully buffered using BUF as the buffer.
- The SIZE argument specifies the length of BUF.
- This function is provided for compatibility with old BSD code. Use
- ‘setvbuf’ instead.
- -- Function: void setlinebuf (FILE *STREAM)
- Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
- | *Note POSIX Safety Concepts::.
- This function makes STREAM be line buffered, and allocates the
- buffer for you.
- This function is provided for compatibility with old BSD code. Use
- ‘setvbuf’ instead.
- It is possible to query whether a given stream is line buffered or
- not using a non-standard function introduced in Solaris and available in
- the GNU C Library.
- -- Function: int __flbf (FILE *STREAM)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘__flbf’ function will return a nonzero value in case the
- stream STREAM is line buffered. Otherwise the return value is
- zero.
- This function is declared in the ‘stdio_ext.h’ header.
- Two more extensions allow to determine the size of the buffer and how
- much of it is used. These functions were also introduced in Solaris.
- -- Function: size_t __fbufsize (FILE *STREAM)
- Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Safe |
- *Note POSIX Safety Concepts::.
- The ‘__fbufsize’ function return the size of the buffer in the
- stream STREAM. This value can be used to optimize the use of the
- stream.
- This function is declared in the ‘stdio_ext.h’ header.
- -- Function: size_t __fpending (FILE *STREAM)
- Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Safe |
- *Note POSIX Safety Concepts::.
- The ‘__fpending’ function returns the number of bytes currently in
- the output buffer. For wide-oriented streams the measuring unit is
- wide characters. This function should not be used on buffers in
- read mode or opened read-only.
- This function is declared in the ‘stdio_ext.h’ header.
- File: libc.info, Node: Other Kinds of Streams, Next: Formatted Messages, Prev: Stream Buffering, Up: I/O on Streams
- 12.21 Other Kinds of Streams
- ============================
- The GNU C Library provides ways for you to define additional kinds of
- streams that do not necessarily correspond to an open file.
- One such type of stream takes input from or writes output to a
- string. These kinds of streams are used internally to implement the
- ‘sprintf’ and ‘sscanf’ functions. You can also create such a stream
- explicitly, using the functions described in *note String Streams::.
- More generally, you can define streams that do input/output to
- arbitrary objects using functions supplied by your program. This
- protocol is discussed in *note Custom Streams::.
- *Portability Note:* The facilities described in this section are
- specific to GNU. Other systems or C implementations might or might not
- provide equivalent functionality.
- * Menu:
- * String Streams:: Streams that get data from or put data in
- a string or memory buffer.
- * Custom Streams:: Defining your own streams with an arbitrary
- input data source and/or output data sink.
- File: libc.info, Node: String Streams, Next: Custom Streams, Up: Other Kinds of Streams
- 12.21.1 String Streams
- ----------------------
- The ‘fmemopen’ and ‘open_memstream’ functions allow you to do I/O to a
- string or memory buffer. These facilities are declared in ‘stdio.h’.
- -- Function: FILE * fmemopen (void *BUF, size_t SIZE, const char
- *OPENTYPE)
- Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem lock |
- *Note POSIX Safety Concepts::.
- This function opens a stream that allows the access specified by
- the OPENTYPE argument, that reads from or writes to the buffer
- specified by the argument BUF. This array must be at least SIZE
- bytes long.
- If you specify a null pointer as the BUF argument, ‘fmemopen’
- dynamically allocates an array SIZE bytes long (as with ‘malloc’;
- *note Unconstrained Allocation::). This is really only useful if
- you are going to write things to the buffer and then read them back
- in again, because you have no way of actually getting a pointer to
- the buffer (for this, try ‘open_memstream’, below). The buffer is
- freed when the stream is closed.
- The argument OPENTYPE is the same as in ‘fopen’ (*note Opening
- Streams::). If the OPENTYPE specifies append mode, then the
- initial file position is set to the first null character in the
- buffer. Otherwise the initial file position is at the beginning of
- the buffer.
- When a stream open for writing is flushed or closed, a null
- character (zero byte) is written at the end of the buffer if it
- fits. You should add an extra byte to the SIZE argument to account
- for this. Attempts to write more than SIZE bytes to the buffer
- result in an error.
- For a stream open for reading, null characters (zero bytes) in the
- buffer do not count as “end of file”. Read operations indicate end
- of file only when the file position advances past SIZE bytes. So,
- if you want to read characters from a null-terminated string, you
- should supply the length of the string as the SIZE argument.
- Here is an example of using ‘fmemopen’ to create a stream for reading
- from a string:
- #include <stdio.h>
- static char buffer[] = "foobar";
- int
- main (void)
- {
- int ch;
- FILE *stream;
- stream = fmemopen (buffer, strlen (buffer), "r");
- while ((ch = fgetc (stream)) != EOF)
- printf ("Got %c\n", ch);
- fclose (stream);
- return 0;
- }
- This program produces the following output:
- Got f
- Got o
- Got o
- Got b
- Got a
- Got r
- -- Function: FILE * open_memstream (char **PTR, size_t *SIZELOC)
- Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
- POSIX Safety Concepts::.
- This function opens a stream for writing to a buffer. The buffer
- is allocated dynamically and grown as necessary, using ‘malloc’.
- After you’ve closed the stream, this buffer is your responsibility
- to clean up using ‘free’ or ‘realloc’. *Note Unconstrained
- Allocation::.
- When the stream is closed with ‘fclose’ or flushed with ‘fflush’,
- the locations PTR and SIZELOC are updated to contain the pointer to
- the buffer and its size. The values thus stored remain valid only
- as long as no further output on the stream takes place. If you do
- more output, you must flush the stream again to store new values
- before you use them again.
- A null character is written at the end of the buffer. This null
- character is _not_ included in the size value stored at SIZELOC.
- You can move the stream’s file position with ‘fseek’ or ‘fseeko’
- (*note File Positioning::). Moving the file position past the end
- of the data already written fills the intervening space with
- zeroes.
- Here is an example of using ‘open_memstream’:
- #include <stdio.h>
- int
- main (void)
- {
- char *bp;
- size_t size;
- FILE *stream;
- stream = open_memstream (&bp, &size);
- fprintf (stream, "hello");
- fflush (stream);
- printf ("buf = `%s', size = %zu\n", bp, size);
- fprintf (stream, ", world");
- fclose (stream);
- printf ("buf = `%s', size = %zu\n", bp, size);
- return 0;
- }
- This program produces the following output:
- buf = `hello', size = 5
- buf = `hello, world', size = 12
- File: libc.info, Node: Custom Streams, Prev: String Streams, Up: Other Kinds of Streams
- 12.21.2 Programming Your Own Custom Streams
- -------------------------------------------
- This section describes how you can make a stream that gets input from an
- arbitrary data source or writes output to an arbitrary data sink
- programmed by you. We call these "custom streams". The functions and
- types described here are all GNU extensions.
- * Menu:
- * Streams and Cookies:: The "cookie" records where to fetch or
- store data that is read or written.
- * Hook Functions:: How you should define the four "hook
- functions" that a custom stream needs.
- File: libc.info, Node: Streams and Cookies, Next: Hook Functions, Up: Custom Streams
- 12.21.2.1 Custom Streams and Cookies
- ....................................
- Inside every custom stream is a special object called the "cookie".
- This is an object supplied by you which records where to fetch or store
- the data read or written. It is up to you to define a data type to use
- for the cookie. The stream functions in the library never refer
- directly to its contents, and they don’t even know what the type is;
- they record its address with type ‘void *’.
- To implement a custom stream, you must specify _how_ to fetch or
- store the data in the specified place. You do this by defining "hook
- functions" to read, write, change “file position”, and close the stream.
- All four of these functions will be passed the stream’s cookie so they
- can tell where to fetch or store the data. The library functions don’t
- know what’s inside the cookie, but your functions will know.
- When you create a custom stream, you must specify the cookie pointer,
- and also the four hook functions stored in a structure of type
- ‘cookie_io_functions_t’.
- These facilities are declared in ‘stdio.h’.
- -- Data Type: cookie_io_functions_t
- This is a structure type that holds the functions that define the
- communications protocol between the stream and its cookie. It has
- the following members:
- ‘cookie_read_function_t *read’
- This is the function that reads data from the cookie. If the
- value is a null pointer instead of a function, then read
- operations on this stream always return ‘EOF’.
- ‘cookie_write_function_t *write’
- This is the function that writes data to the cookie. If the
- value is a null pointer instead of a function, then data
- written to the stream is discarded.
- ‘cookie_seek_function_t *seek’
- This is the function that performs the equivalent of file
- positioning on the cookie. If the value is a null pointer
- instead of a function, calls to ‘fseek’ or ‘fseeko’ on this
- stream can only seek to locations within the buffer; any
- attempt to seek outside the buffer will return an ‘ESPIPE’
- error.
- ‘cookie_close_function_t *close’
- This function performs any appropriate cleanup on the cookie
- when closing the stream. If the value is a null pointer
- instead of a function, nothing special is done to close the
- cookie when the stream is closed.
- -- Function: FILE * fopencookie (void *COOKIE, const char *OPENTYPE,
- cookie_io_functions_t IO-FUNCTIONS)
- Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem lock |
- *Note POSIX Safety Concepts::.
- This function actually creates the stream for communicating with
- the COOKIE using the functions in the IO-FUNCTIONS argument. The
- OPENTYPE argument is interpreted as for ‘fopen’; see *note Opening
- Streams::. (But note that the “truncate on open” option is
- ignored.) The new stream is fully buffered.
- The ‘fopencookie’ function returns the newly created stream, or a
- null pointer in case of an error.
- File: libc.info, Node: Hook Functions, Prev: Streams and Cookies, Up: Custom Streams
- 12.21.2.2 Custom Stream Hook Functions
- ......................................
- Here are more details on how you should define the four hook functions
- that a custom stream needs.
- You should define the function to read data from the cookie as:
- ssize_t READER (void *COOKIE, char *BUFFER, size_t SIZE)
- This is very similar to the ‘read’ function; see *note I/O
- Primitives::. Your function should transfer up to SIZE bytes into the
- BUFFER, and return the number of bytes read, or zero to indicate
- end-of-file. You can return a value of ‘-1’ to indicate an error.
- You should define the function to write data to the cookie as:
- ssize_t WRITER (void *COOKIE, const char *BUFFER, size_t SIZE)
- This is very similar to the ‘write’ function; see *note I/O
- Primitives::. Your function should transfer up to SIZE bytes from the
- buffer, and return the number of bytes written. You can return a value
- of ‘0’ to indicate an error. You must not return any negative value.
- You should define the function to perform seek operations on the
- cookie as:
- int SEEKER (void *COOKIE, off64_t *POSITION, int WHENCE)
- For this function, the POSITION and WHENCE arguments are interpreted
- as for ‘fgetpos’; see *note Portable Positioning::.
- After doing the seek operation, your function should store the
- resulting file position relative to the beginning of the file in
- POSITION. Your function should return a value of ‘0’ on success and
- ‘-1’ to indicate an error.
- You should define the function to do cleanup operations on the cookie
- appropriate for closing the stream as:
- int CLEANER (void *COOKIE)
- Your function should return ‘-1’ to indicate an error, and ‘0’
- otherwise.
- -- Data Type: cookie_read_function_t
- This is the data type that the read function for a custom stream
- should have. If you declare the function as shown above, this is
- the type it will have.
- -- Data Type: cookie_write_function_t
- The data type of the write function for a custom stream.
- -- Data Type: cookie_seek_function_t
- The data type of the seek function for a custom stream.
- -- Data Type: cookie_close_function_t
- The data type of the close function for a custom stream.
- File: libc.info, Node: Formatted Messages, Prev: Other Kinds of Streams, Up: I/O on Streams
- 12.22 Formatted Messages
- ========================
- On systems which are based on System V messages of programs (especially
- the system tools) are printed in a strict form using the ‘fmtmsg’
- function. The uniformity sometimes helps the user to interpret messages
- and the strictness tests of the ‘fmtmsg’ function ensure that the
- programmer follows some minimal requirements.
- * Menu:
- * Printing Formatted Messages:: The ‘fmtmsg’ function.
- * Adding Severity Classes:: Add more severity classes.
- * Example:: How to use ‘fmtmsg’ and ‘addseverity’.
- File: libc.info, Node: Printing Formatted Messages, Next: Adding Severity Classes, Up: Formatted Messages
- 12.22.1 Printing Formatted Messages
- -----------------------------------
- Messages can be printed to standard error and/or to the console. To
- select the destination the programmer can use the following two values,
- bitwise OR combined if wanted, for the CLASSIFICATION parameter of
- ‘fmtmsg’:
- ‘MM_PRINT’
- Display the message in standard error.
- ‘MM_CONSOLE’
- Display the message on the system console.
- The erroneous piece of the system can be signalled by exactly one of
- the following values which also is bitwise ORed with the CLASSIFICATION
- parameter to ‘fmtmsg’:
- ‘MM_HARD’
- The source of the condition is some hardware.
- ‘MM_SOFT’
- The source of the condition is some software.
- ‘MM_FIRM’
- The source of the condition is some firmware.
- A third component of the CLASSIFICATION parameter to ‘fmtmsg’ can
- describe the part of the system which detects the problem. This is done
- by using exactly one of the following values:
- ‘MM_APPL’
- The erroneous condition is detected by the application.
- ‘MM_UTIL’
- The erroneous condition is detected by a utility.
- ‘MM_OPSYS’
- The erroneous condition is detected by the operating system.
- A last component of CLASSIFICATION can signal the results of this
- message. Exactly one of the following values can be used:
- ‘MM_RECOVER’
- It is a recoverable error.
- ‘MM_NRECOV’
- It is a non-recoverable error.
- -- Function: int fmtmsg (long int CLASSIFICATION, const char *LABEL,
- int SEVERITY, const char *TEXT, const char *ACTION, const char
- *TAG)
- Preliminary: | MT-Safe | AS-Unsafe lock | AC-Safe | *Note POSIX
- Safety Concepts::.
- Display a message described by its parameters on the device(s)
- specified in the CLASSIFICATION parameter. The LABEL parameter
- identifies the source of the message. The string should consist of
- two colon separated parts where the first part has not more than 10
- and the second part not more than 14 characters. The TEXT
- parameter describes the condition of the error, the ACTION
- parameter possible steps to recover from the error and the TAG
- parameter is a reference to the online documentation where more
- information can be found. It should contain the LABEL value and a
- unique identification number.
- Each of the parameters can be a special value which means this
- value is to be omitted. The symbolic names for these values are:
- ‘MM_NULLLBL’
- Ignore LABEL parameter.
- ‘MM_NULLSEV’
- Ignore SEVERITY parameter.
- ‘MM_NULLMC’
- Ignore CLASSIFICATION parameter. This implies that nothing is
- actually printed.
- ‘MM_NULLTXT’
- Ignore TEXT parameter.
- ‘MM_NULLACT’
- Ignore ACTION parameter.
- ‘MM_NULLTAG’
- Ignore TAG parameter.
- There is another way certain fields can be omitted from the output
- to standard error. This is described below in the description of
- environment variables influencing the behavior.
- The SEVERITY parameter can have one of the values in the following
- table:
- ‘MM_NOSEV’
- Nothing is printed, this value is the same as ‘MM_NULLSEV’.
- ‘MM_HALT’
- This value is printed as ‘HALT’.
- ‘MM_ERROR’
- This value is printed as ‘ERROR’.
- ‘MM_WARNING’
- This value is printed as ‘WARNING’.
- ‘MM_INFO’
- This value is printed as ‘INFO’.
- The numeric value of these five macros are between ‘0’ and ‘4’.
- Using the environment variable ‘SEV_LEVEL’ or using the
- ‘addseverity’ function one can add more severity levels with their
- corresponding string to print. This is described below (*note
- Adding Severity Classes::).
- If no parameter is ignored the output looks like this:
- LABEL: SEVERITY-STRING: TEXT
- TO FIX: ACTION TAG
- The colons, new line characters and the ‘TO FIX’ string are
- inserted if necessary, i.e., if the corresponding parameter is not
- ignored.
- This function is specified in the X/Open Portability Guide. It is
- also available on all systems derived from System V.
- The function returns the value ‘MM_OK’ if no error occurred. If
- only the printing to standard error failed, it returns ‘MM_NOMSG’.
- If printing to the console fails, it returns ‘MM_NOCON’. If
- nothing is printed ‘MM_NOTOK’ is returned. Among situations where
- all outputs fail this last value is also returned if a parameter
- value is incorrect.
- There are two environment variables which influence the behavior of
- ‘fmtmsg’. The first is ‘MSGVERB’. It is used to control the output
- actually happening on standard error (_not_ the console output). Each
- of the five fields can explicitly be enabled. To do this the user has
- to put the ‘MSGVERB’ variable with a format like the following in the
- environment before calling the ‘fmtmsg’ function the first time:
- MSGVERB=KEYWORD[:KEYWORD[:…]]
- Valid KEYWORDs are ‘label’, ‘severity’, ‘text’, ‘action’, and ‘tag’.
- If the environment variable is not given or is the empty string, a not
- supported keyword is given or the value is somehow else invalid, no part
- of the message is masked out.
- The second environment variable which influences the behavior of
- ‘fmtmsg’ is ‘SEV_LEVEL’. This variable and the change in the behavior
- of ‘fmtmsg’ is not specified in the X/Open Portability Guide. It is
- available in System V systems, though. It can be used to introduce new
- severity levels. By default, only the five severity levels described
- above are available. Any other numeric value would make ‘fmtmsg’ print
- nothing.
- If the user puts ‘SEV_LEVEL’ with a format like
- SEV_LEVEL=[DESCRIPTION[:DESCRIPTION[:…]]]
- in the environment of the process before the first call to ‘fmtmsg’,
- where DESCRIPTION has a value of the form
- SEVERITY-KEYWORD,LEVEL,PRINTSTRING
- The SEVERITY-KEYWORD part is not used by ‘fmtmsg’ but it has to be
- present. The LEVEL part is a string representation of a number. The
- numeric value must be a number greater than 4. This value must be used
- in the SEVERITY parameter of ‘fmtmsg’ to select this class. It is not
- possible to overwrite any of the predefined classes. The PRINTSTRING is
- the string printed when a message of this class is processed by ‘fmtmsg’
- (see above, ‘fmtsmg’ does not print the numeric value but instead the
- string representation).
- File: libc.info, Node: Adding Severity Classes, Next: Example, Prev: Printing Formatted Messages, Up: Formatted Messages
- 12.22.2 Adding Severity Classes
- -------------------------------
- There is another possibility to introduce severity classes besides using
- the environment variable ‘SEV_LEVEL’. This simplifies the task of
- introducing new classes in a running program. One could use the
- ‘setenv’ or ‘putenv’ function to set the environment variable, but this
- is toilsome.
- -- Function: int addseverity (int SEVERITY, const char *STRING)
- Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock mem |
- *Note POSIX Safety Concepts::.
- This function allows the introduction of new severity classes which
- can be addressed by the SEVERITY parameter of the ‘fmtmsg’
- function. The SEVERITY parameter of ‘addseverity’ must match the
- value for the parameter with the same name of ‘fmtmsg’, and STRING
- is the string printed in the actual messages instead of the numeric
- value.
- If STRING is ‘NULL’ the severity class with the numeric value
- according to SEVERITY is removed.
- It is not possible to overwrite or remove one of the default
- severity classes. All calls to ‘addseverity’ with SEVERITY set to
- one of the values for the default classes will fail.
- The return value is ‘MM_OK’ if the task was successfully performed.
- If the return value is ‘MM_NOTOK’ something went wrong. This could
- mean that no more memory is available or a class is not available
- when it has to be removed.
- This function is not specified in the X/Open Portability Guide
- although the ‘fmtsmg’ function is. It is available on System V
- systems.
- File: libc.info, Node: Example, Prev: Adding Severity Classes, Up: Formatted Messages
- 12.22.3 How to use ‘fmtmsg’ and ‘addseverity’
- ---------------------------------------------
- Here is a simple example program to illustrate the use of both functions
- described in this section.
- #include <fmtmsg.h>
- int
- main (void)
- {
- addseverity (5, "NOTE2");
- fmtmsg (MM_PRINT, "only1field", MM_INFO, "text2", "action2", "tag2");
- fmtmsg (MM_PRINT, "UX:cat", 5, "invalid syntax", "refer to manual",
- "UX:cat:001");
- fmtmsg (MM_PRINT, "label:foo", 6, "text", "action", "tag");
- return 0;
- }
- The second call to ‘fmtmsg’ illustrates a use of this function as it
- usually occurs on System V systems, which heavily use this function. It
- seems worthwhile to give a short explanation here of how this system
- works on System V. The value of the LABEL field (‘UX:cat’) says that the
- error occurred in the Unix program ‘cat’. The explanation of the error
- follows and the value for the ACTION parameter is ‘"refer to manual"’.
- One could be more specific here, if necessary. The TAG field contains,
- as proposed above, the value of the string given for the LABEL
- parameter, and additionally a unique ID (‘001’ in this case). For a GNU
- environment this string could contain a reference to the corresponding
- node in the Info page for the program.
- Running this program without specifying the ‘MSGVERB’ and ‘SEV_LEVEL’
- function produces the following output:
- UX:cat: NOTE2: invalid syntax
- TO FIX: refer to manual UX:cat:001
- We see the different fields of the message and how the extra glue
- (the colons and the ‘TO FIX’ string) is printed. But only one of the
- three calls to ‘fmtmsg’ produced output. The first call does not print
- anything because the LABEL parameter is not in the correct form. The
- string must contain two fields, separated by a colon (*note Printing
- Formatted Messages::). The third ‘fmtmsg’ call produced no output since
- the class with the numeric value ‘6’ is not defined. Although a class
- with numeric value ‘5’ is also not defined by default, the call to
- ‘addseverity’ introduces it and the second call to ‘fmtmsg’ produces the
- above output.
- When we change the environment of the program to contain
- ‘SEV_LEVEL=XXX,6,NOTE’ when running it we get a different result:
- UX:cat: NOTE2: invalid syntax
- TO FIX: refer to manual UX:cat:001
- label:foo: NOTE: text
- TO FIX: action tag
- Now the third call to ‘fmtmsg’ produced some output and we see how
- the string ‘NOTE’ from the environment variable appears in the message.
- Now we can reduce the output by specifying which fields we are
- interested in. If we additionally set the environment variable
- ‘MSGVERB’ to the value ‘severity:label:action’ we get the following
- output:
- UX:cat: NOTE2
- TO FIX: refer to manual
- label:foo: NOTE
- TO FIX: action
- I.e., the output produced by the TEXT and the TAG parameters to ‘fmtmsg’
- vanished. Please also note that now there is no colon after the ‘NOTE’
- and ‘NOTE2’ strings in the output. This is not necessary since there is
- no more output on this line because the text is missing.
- File: libc.info, Node: Low-Level I/O, Next: File System Interface, Prev: I/O on Streams, Up: Top
- 13 Low-Level Input/Output
- *************************
- This chapter describes functions for performing low-level input/output
- operations on file descriptors. These functions include the primitives
- for the higher-level I/O functions described in *note I/O on Streams::,
- as well as functions for performing low-level control operations for
- which there are no equivalents on streams.
- Stream-level I/O is more flexible and usually more convenient;
- therefore, programmers generally use the descriptor-level functions only
- when necessary. These are some of the usual reasons:
- • For reading binary files in large chunks.
- • For reading an entire file into core before parsing it.
- • To perform operations other than data transfer, which can only be
- done with a descriptor. (You can use ‘fileno’ to get the
- descriptor corresponding to a stream.)
- • To pass descriptors to a child process. (The child can create its
- own stream to use a descriptor that it inherits, but cannot inherit
- a stream directly.)
- * Menu:
- * Opening and Closing Files:: How to open and close file
- descriptors.
- * I/O Primitives:: Reading and writing data.
- * File Position Primitive:: Setting a descriptor’s file
- position.
- * Descriptors and Streams:: Converting descriptor to stream
- or vice-versa.
- * Stream/Descriptor Precautions:: Precautions needed if you use both
- descriptors and streams.
- * Scatter-Gather:: Fast I/O to discontinuous buffers.
- * Memory-mapped I/O:: Using files like memory.
- * Waiting for I/O:: How to check for input or output
- on multiple file descriptors.
- * Synchronizing I/O:: Making sure all I/O actions completed.
- * Asynchronous I/O:: Perform I/O in parallel.
- * Control Operations:: Various other operations on file
- descriptors.
- * Duplicating Descriptors:: Fcntl commands for duplicating
- file descriptors.
- * Descriptor Flags:: Fcntl commands for manipulating
- flags associated with file
- descriptors.
- * File Status Flags:: Fcntl commands for manipulating
- flags associated with open files.
- * File Locks:: Fcntl commands for implementing
- file locking.
- * Open File Description Locks:: Fcntl commands for implementing
- open file description locking.
- * Open File Description Locks Example:: An example of open file description lock
- usage
- * Interrupt Input:: Getting an asynchronous signal when
- input arrives.
- * IOCTLs:: Generic I/O Control operations.
- File: libc.info, Node: Opening and Closing Files, Next: I/O Primitives, Up: Low-Level I/O
- 13.1 Opening and Closing Files
- ==============================
- This section describes the primitives for opening and closing files
- using file descriptors. The ‘open’ and ‘creat’ functions are declared
- in the header file ‘fcntl.h’, while ‘close’ is declared in ‘unistd.h’.
- -- Function: int open (const char *FILENAME, int FLAGS[, mode_t MODE])
- Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
- Concepts::.
- The ‘open’ function creates and returns a new file descriptor for
- the file named by FILENAME. Initially, the file position indicator
- for the file is at the beginning of the file. The argument MODE
- (*note Permission Bits::) is used only when a file is created, but
- it doesn’t hurt to supply the argument in any case.
- The FLAGS argument controls how the file is to be opened. This is
- a bit mask; you create the value by the bitwise OR of the
- appropriate parameters (using the ‘|’ operator in C). *Note File
- Status Flags::, for the parameters available.
- The normal return value from ‘open’ is a non-negative integer file
- descriptor. In the case of an error, a value of -1 is returned
- instead. In addition to the usual file name errors (*note File
- Name Errors::), the following ‘errno’ error conditions are defined
- for this function:
- ‘EACCES’
- The file exists but is not readable/writable as requested by
- the FLAGS argument, or the file does not exist and the
- directory is unwritable so it cannot be created.
- ‘EEXIST’
- Both ‘O_CREAT’ and ‘O_EXCL’ are set, and the named file
- already exists.
- ‘EINTR’
- The ‘open’ operation was interrupted by a signal. *Note
- Interrupted Primitives::.
- ‘EISDIR’
- The FLAGS argument specified write access, and the file is a
- directory.
- ‘EMFILE’
- The process has too many files open. The maximum number of
- file descriptors is controlled by the ‘RLIMIT_NOFILE’ resource
- limit; *note Limits on Resources::.
- ‘ENFILE’
- The entire system, or perhaps the file system which contains
- the directory, cannot support any additional open files at the
- moment. (This problem cannot happen on GNU/Hurd systems.)
- ‘ENOENT’
- The named file does not exist, and ‘O_CREAT’ is not specified.
- ‘ENOSPC’
- The directory or file system that would contain the new file
- cannot be extended, because there is no disk space left.
- ‘ENXIO’
- ‘O_NONBLOCK’ and ‘O_WRONLY’ are both set in the FLAGS
- argument, the file named by FILENAME is a FIFO (*note Pipes
- and FIFOs::), and no process has the file open for reading.
- ‘EROFS’
- The file resides on a read-only file system and any of
- ‘O_WRONLY’, ‘O_RDWR’, and ‘O_TRUNC’ are set in the FLAGS
- argument, or ‘O_CREAT’ is set and the file does not already
- exist.
- If on a 32 bit machine the sources are translated with
- ‘_FILE_OFFSET_BITS == 64’ the function ‘open’ returns a file
- descriptor opened in the large file mode which enables the file
- handling functions to use files up to 2^63 bytes in size and offset
- from −2^63 to 2^63. This happens transparently for the user since
- all of the low-level file handling functions are equally replaced.
- This function is a cancellation point in multi-threaded programs.
- This is a problem if the thread allocates some resources (like
- memory, file descriptors, semaphores or whatever) at the time
- ‘open’ is called. If the thread gets canceled these resources stay
- allocated until the program ends. To avoid this calls to ‘open’
- should be protected using cancellation handlers.
- The ‘open’ function is the underlying primitive for the ‘fopen’ and
- ‘freopen’ functions, that create streams.
- -- Function: int open64 (const char *FILENAME, int FLAGS[, mode_t
- MODE])
- Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
- Concepts::.
- This function is similar to ‘open’. It returns a file descriptor
- which can be used to access the file named by FILENAME. The only
- difference is that on 32 bit systems the file is opened in the
- large file mode. I.e., file length and file offsets can exceed 31
- bits.
- When the sources are translated with ‘_FILE_OFFSET_BITS == 64’ this
- function is actually available under the name ‘open’. I.e., the
- new, extended API using 64 bit file sizes and offsets transparently
- replaces the old API.
- -- Obsolete function: int creat (const char *FILENAME, mode_t MODE)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
- Concepts::.
- This function is obsolete. The call:
- creat (FILENAME, MODE)
- is equivalent to:
- open (FILENAME, O_WRONLY | O_CREAT | O_TRUNC, MODE)
- If on a 32 bit machine the sources are translated with
- ‘_FILE_OFFSET_BITS == 64’ the function ‘creat’ returns a file
- descriptor opened in the large file mode which enables the file
- handling functions to use files up to 2^63 in size and offset from
- −2^63 to 2^63. This happens transparently for the user since all
- of the low-level file handling functions are equally replaced.
- -- Obsolete function: int creat64 (const char *FILENAME, mode_t MODE)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
- Concepts::.
- This function is similar to ‘creat’. It returns a file descriptor
- which can be used to access the file named by FILENAME. The only
- difference is that on 32 bit systems the file is opened in the
- large file mode. I.e., file length and file offsets can exceed 31
- bits.
- To use this file descriptor one must not use the normal operations
- but instead the counterparts named ‘*64’, e.g., ‘read64’.
- When the sources are translated with ‘_FILE_OFFSET_BITS == 64’ this
- function is actually available under the name ‘open’. I.e., the
- new, extended API using 64 bit file sizes and offsets transparently
- replaces the old API.
- -- Function: int close (int FILEDES)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
- Concepts::.
- The function ‘close’ closes the file descriptor FILEDES. Closing a
- file has the following consequences:
- • The file descriptor is deallocated.
- • Any record locks owned by the process on the file are
- unlocked.
- • When all file descriptors associated with a pipe or FIFO have
- been closed, any unread data is discarded.
- This function is a cancellation point in multi-threaded programs.
- This is a problem if the thread allocates some resources (like
- memory, file descriptors, semaphores or whatever) at the time
- ‘close’ is called. If the thread gets canceled these resources
- stay allocated until the program ends. To avoid this, calls to
- ‘close’ should be protected using cancellation handlers.
- The normal return value from ‘close’ is 0; a value of -1 is
- returned in case of failure. The following ‘errno’ error
- conditions are defined for this function:
- ‘EBADF’
- The FILEDES argument is not a valid file descriptor.
- ‘EINTR’
- The ‘close’ call was interrupted by a signal. *Note
- Interrupted Primitives::. Here is an example of how to handle
- ‘EINTR’ properly:
- TEMP_FAILURE_RETRY (close (desc));
- ‘ENOSPC’
- ‘EIO’
- ‘EDQUOT’
- When the file is accessed by NFS, these errors from ‘write’
- can sometimes not be detected until ‘close’. *Note I/O
- Primitives::, for details on their meaning.
- Please note that there is _no_ separate ‘close64’ function. This
- is not necessary since this function does not determine nor depend
- on the mode of the file. The kernel which performs the ‘close’
- operation knows which mode the descriptor is used for and can
- handle this situation.
- To close a stream, call ‘fclose’ (*note Closing Streams::) instead of
- trying to close its underlying file descriptor with ‘close’. This
- flushes any buffered output and updates the stream object to indicate
- that it is closed.
- File: libc.info, Node: I/O Primitives, Next: File Position Primitive, Prev: Opening and Closing Files, Up: Low-Level I/O
- 13.2 Input and Output Primitives
- ================================
- This section describes the functions for performing primitive input and
- output operations on file descriptors: ‘read’, ‘write’, and ‘lseek’.
- These functions are declared in the header file ‘unistd.h’.
- -- Data Type: ssize_t
- This data type is used to represent the sizes of blocks that can be
- read or written in a single operation. It is similar to ‘size_t’,
- but must be a signed type.
- -- Function: ssize_t read (int FILEDES, void *BUFFER, size_t SIZE)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘read’ function reads up to SIZE bytes from the file with
- descriptor FILEDES, storing the results in the BUFFER. (This is
- not necessarily a character string, and no terminating null
- character is added.)
- The return value is the number of bytes actually read. This might
- be less than SIZE; for example, if there aren’t that many bytes
- left in the file or if there aren’t that many bytes immediately
- available. The exact behavior depends on what kind of file it is.
- Note that reading less than SIZE bytes is not an error.
- A value of zero indicates end-of-file (except if the value of the
- SIZE argument is also zero). This is not considered an error. If
- you keep calling ‘read’ while at end-of-file, it will keep
- returning zero and doing nothing else.
- If ‘read’ returns at least one character, there is no way you can
- tell whether end-of-file was reached. But if you did reach the
- end, the next read will return zero.
- In case of an error, ‘read’ returns -1. The following ‘errno’
- error conditions are defined for this function:
- ‘EAGAIN’
- Normally, when no input is immediately available, ‘read’ waits
- for some input. But if the ‘O_NONBLOCK’ flag is set for the
- file (*note File Status Flags::), ‘read’ returns immediately
- without reading any data, and reports this error.
- *Compatibility Note:* Most versions of BSD Unix use a
- different error code for this: ‘EWOULDBLOCK’. In the GNU C
- Library, ‘EWOULDBLOCK’ is an alias for ‘EAGAIN’, so it doesn’t
- matter which name you use.
- On some systems, reading a large amount of data from a
- character special file can also fail with ‘EAGAIN’ if the
- kernel cannot find enough physical memory to lock down the
- user’s pages. This is limited to devices that transfer with
- direct memory access into the user’s memory, which means it
- does not include terminals, since they always use separate
- buffers inside the kernel. This problem never happens on
- GNU/Hurd systems.
- Any condition that could result in ‘EAGAIN’ can instead result
- in a successful ‘read’ which returns fewer bytes than
- requested. Calling ‘read’ again immediately would result in
- ‘EAGAIN’.
- ‘EBADF’
- The FILEDES argument is not a valid file descriptor, or is not
- open for reading.
- ‘EINTR’
- ‘read’ was interrupted by a signal while it was waiting for
- input. *Note Interrupted Primitives::. A signal will not
- necessarily cause ‘read’ to return ‘EINTR’; it may instead
- result in a successful ‘read’ which returns fewer bytes than
- requested.
- ‘EIO’
- For many devices, and for disk files, this error code
- indicates a hardware error.
- ‘EIO’ also occurs when a background process tries to read from
- the controlling terminal, and the normal action of stopping
- the process by sending it a ‘SIGTTIN’ signal isn’t working.
- This might happen if the signal is being blocked or ignored,
- or because the process group is orphaned. *Note Job
- Control::, for more information about job control, and *note
- Signal Handling::, for information about signals.
- ‘EINVAL’
- In some systems, when reading from a character or block
- device, position and size offsets must be aligned to a
- particular block size. This error indicates that the offsets
- were not properly aligned.
- Please note that there is no function named ‘read64’. This is not
- necessary since this function does not directly modify or handle
- the possibly wide file offset. Since the kernel handles this state
- internally, the ‘read’ function can be used for all cases.
- This function is a cancellation point in multi-threaded programs.
- This is a problem if the thread allocates some resources (like
- memory, file descriptors, semaphores or whatever) at the time
- ‘read’ is called. If the thread gets canceled these resources stay
- allocated until the program ends. To avoid this, calls to ‘read’
- should be protected using cancellation handlers.
- The ‘read’ function is the underlying primitive for all of the
- functions that read from streams, such as ‘fgetc’.
- -- Function: ssize_t pread (int FILEDES, void *BUFFER, size_t SIZE,
- off_t OFFSET)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘pread’ function is similar to the ‘read’ function. The first
- three arguments are identical, and the return values and error
- codes also correspond.
- The difference is the fourth argument and its handling. The data
- block is not read from the current position of the file descriptor
- ‘filedes’. Instead the data is read from the file starting at
- position OFFSET. The position of the file descriptor itself is not
- affected by the operation. The value is the same as before the
- call.
- When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ the
- ‘pread’ function is in fact ‘pread64’ and the type ‘off_t’ has 64
- bits, which makes it possible to handle files up to 2^63 bytes in
- length.
- The return value of ‘pread’ describes the number of bytes read. In
- the error case it returns -1 like ‘read’ does and the error codes
- are also the same, with these additions:
- ‘EINVAL’
- The value given for OFFSET is negative and therefore illegal.
- ‘ESPIPE’
- The file descriptor FILEDES is associated with a pipe or a
- FIFO and this device does not allow positioning of the file
- pointer.
- The function is an extension defined in the Unix Single
- Specification version 2.
- -- Function: ssize_t pread64 (int FILEDES, void *BUFFER, size_t SIZE,
- off64_t OFFSET)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function is similar to the ‘pread’ function. The difference
- is that the OFFSET parameter is of type ‘off64_t’ instead of
- ‘off_t’ which makes it possible on 32 bit machines to address files
- larger than 2^31 bytes and up to 2^63 bytes. The file descriptor
- ‘filedes’ must be opened using ‘open64’ since otherwise the large
- offsets possible with ‘off64_t’ will lead to errors with a
- descriptor in small file mode.
- When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ on
- a 32 bit machine this function is actually available under the name
- ‘pread’ and so transparently replaces the 32 bit interface.
- -- Function: ssize_t write (int FILEDES, const void *BUFFER, size_t
- SIZE)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘write’ function writes up to SIZE bytes from BUFFER to the
- file with descriptor FILEDES. The data in BUFFER is not
- necessarily a character string and a null character is output like
- any other character.
- The return value is the number of bytes actually written. This may
- be SIZE, but can always be smaller. Your program should always
- call ‘write’ in a loop, iterating until all the data is written.
- Once ‘write’ returns, the data is enqueued to be written and can be
- read back right away, but it is not necessarily written out to
- permanent storage immediately. You can use ‘fsync’ when you need
- to be sure your data has been permanently stored before continuing.
- (It is more efficient for the system to batch up consecutive writes
- and do them all at once when convenient. Normally they will always
- be written to disk within a minute or less.) Modern systems
- provide another function ‘fdatasync’ which guarantees integrity
- only for the file data and is therefore faster. You can use the
- ‘O_FSYNC’ open mode to make ‘write’ always store the data to disk
- before returning; *note Operating Modes::.
- In the case of an error, ‘write’ returns -1. The following ‘errno’
- error conditions are defined for this function:
- ‘EAGAIN’
- Normally, ‘write’ blocks until the write operation is
- complete. But if the ‘O_NONBLOCK’ flag is set for the file
- (*note Control Operations::), it returns immediately without
- writing any data and reports this error. An example of a
- situation that might cause the process to block on output is
- writing to a terminal device that supports flow control, where
- output has been suspended by receipt of a STOP character.
- *Compatibility Note:* Most versions of BSD Unix use a
- different error code for this: ‘EWOULDBLOCK’. In the GNU C
- Library, ‘EWOULDBLOCK’ is an alias for ‘EAGAIN’, so it doesn’t
- matter which name you use.
- On some systems, writing a large amount of data from a
- character special file can also fail with ‘EAGAIN’ if the
- kernel cannot find enough physical memory to lock down the
- user’s pages. This is limited to devices that transfer with
- direct memory access into the user’s memory, which means it
- does not include terminals, since they always use separate
- buffers inside the kernel. This problem does not arise on
- GNU/Hurd systems.
- ‘EBADF’
- The FILEDES argument is not a valid file descriptor, or is not
- open for writing.
- ‘EFBIG’
- The size of the file would become larger than the
- implementation can support.
- ‘EINTR’
- The ‘write’ operation was interrupted by a signal while it was
- blocked waiting for completion. A signal will not necessarily
- cause ‘write’ to return ‘EINTR’; it may instead result in a
- successful ‘write’ which writes fewer bytes than requested.
- *Note Interrupted Primitives::.
- ‘EIO’
- For many devices, and for disk files, this error code
- indicates a hardware error.
- ‘ENOSPC’
- The device containing the file is full.
- ‘EPIPE’
- This error is returned when you try to write to a pipe or FIFO
- that isn’t open for reading by any process. When this
- happens, a ‘SIGPIPE’ signal is also sent to the process; see
- *note Signal Handling::.
- ‘EINVAL’
- In some systems, when writing to a character or block device,
- position and size offsets must be aligned to a particular
- block size. This error indicates that the offsets were not
- properly aligned.
- Unless you have arranged to prevent ‘EINTR’ failures, you should
- check ‘errno’ after each failing call to ‘write’, and if the error
- was ‘EINTR’, you should simply repeat the call. *Note Interrupted
- Primitives::. The easy way to do this is with the macro
- ‘TEMP_FAILURE_RETRY’, as follows:
- nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
- Please note that there is no function named ‘write64’. This is not
- necessary since this function does not directly modify or handle
- the possibly wide file offset. Since the kernel handles this state
- internally the ‘write’ function can be used for all cases.
- This function is a cancellation point in multi-threaded programs.
- This is a problem if the thread allocates some resources (like
- memory, file descriptors, semaphores or whatever) at the time
- ‘write’ is called. If the thread gets canceled these resources
- stay allocated until the program ends. To avoid this, calls to
- ‘write’ should be protected using cancellation handlers.
- The ‘write’ function is the underlying primitive for all of the
- functions that write to streams, such as ‘fputc’.
- -- Function: ssize_t pwrite (int FILEDES, const void *BUFFER, size_t
- SIZE, off_t OFFSET)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘pwrite’ function is similar to the ‘write’ function. The
- first three arguments are identical, and the return values and
- error codes also correspond.
- The difference is the fourth argument and its handling. The data
- block is not written to the current position of the file descriptor
- ‘filedes’. Instead the data is written to the file starting at
- position OFFSET. The position of the file descriptor itself is not
- affected by the operation. The value is the same as before the
- call.
- When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ the
- ‘pwrite’ function is in fact ‘pwrite64’ and the type ‘off_t’ has 64
- bits, which makes it possible to handle files up to 2^63 bytes in
- length.
- The return value of ‘pwrite’ describes the number of written bytes.
- In the error case it returns -1 like ‘write’ does and the error
- codes are also the same, with these additions:
- ‘EINVAL’
- The value given for OFFSET is negative and therefore illegal.
- ‘ESPIPE’
- The file descriptor FILEDES is associated with a pipe or a
- FIFO and this device does not allow positioning of the file
- pointer.
- The function is an extension defined in the Unix Single
- Specification version 2.
- -- Function: ssize_t pwrite64 (int FILEDES, const void *BUFFER, size_t
- SIZE, off64_t OFFSET)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function is similar to the ‘pwrite’ function. The difference
- is that the OFFSET parameter is of type ‘off64_t’ instead of
- ‘off_t’ which makes it possible on 32 bit machines to address files
- larger than 2^31 bytes and up to 2^63 bytes. The file descriptor
- ‘filedes’ must be opened using ‘open64’ since otherwise the large
- offsets possible with ‘off64_t’ will lead to errors with a
- descriptor in small file mode.
- When the source file is compiled using ‘_FILE_OFFSET_BITS == 64’ on
- a 32 bit machine this function is actually available under the name
- ‘pwrite’ and so transparently replaces the 32 bit interface.
- File: libc.info, Node: File Position Primitive, Next: Descriptors and Streams, Prev: I/O Primitives, Up: Low-Level I/O
- 13.3 Setting the File Position of a Descriptor
- ==============================================
- Just as you can set the file position of a stream with ‘fseek’, you can
- set the file position of a descriptor with ‘lseek’. This specifies the
- position in the file for the next ‘read’ or ‘write’ operation. *Note
- File Positioning::, for more information on the file position and what
- it means.
- To read the current file position value from a descriptor, use ‘lseek
- (DESC, 0, SEEK_CUR)’.
- -- Function: off_t lseek (int FILEDES, off_t OFFSET, int WHENCE)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘lseek’ function is used to change the file position of the
- file with descriptor FILEDES.
- The WHENCE argument specifies how the OFFSET should be interpreted,
- in the same way as for the ‘fseek’ function, and it must be one of
- the symbolic constants ‘SEEK_SET’, ‘SEEK_CUR’, or ‘SEEK_END’.
- ‘SEEK_SET’
- Specifies that OFFSET is a count of characters from the
- beginning of the file.
- ‘SEEK_CUR’
- Specifies that OFFSET is a count of characters from the
- current file position. This count may be positive or
- negative.
- ‘SEEK_END’
- Specifies that OFFSET is a count of characters from the end of
- the file. A negative count specifies a position within the
- current extent of the file; a positive count specifies a
- position past the current end. If you set the position past
- the current end, and actually write data, you will extend the
- file with zeros up to that position.
- The return value from ‘lseek’ is normally the resulting file
- position, measured in bytes from the beginning of the file. You
- can use this feature together with ‘SEEK_CUR’ to read the current
- file position.
- If you want to append to the file, setting the file position to the
- current end of file with ‘SEEK_END’ is not sufficient. Another
- process may write more data after you seek but before you write,
- extending the file so the position you write onto clobbers their
- data. Instead, use the ‘O_APPEND’ operating mode; *note Operating
- Modes::.
- You can set the file position past the current end of the file.
- This does not by itself make the file longer; ‘lseek’ never changes
- the file. But subsequent output at that position will extend the
- file. Characters between the previous end of file and the new
- position are filled with zeros. Extending the file in this way can
- create a “hole”: the blocks of zeros are not actually allocated on
- disk, so the file takes up less space than it appears to; it is
- then called a “sparse file”.
- If the file position cannot be changed, or the operation is in some
- way invalid, ‘lseek’ returns a value of -1. The following ‘errno’
- error conditions are defined for this function:
- ‘EBADF’
- The FILEDES is not a valid file descriptor.
- ‘EINVAL’
- The WHENCE argument value is not valid, or the resulting file
- offset is not valid. A file offset is invalid.
- ‘ESPIPE’
- The FILEDES corresponds to an object that cannot be
- positioned, such as a pipe, FIFO or terminal device. (POSIX.1
- specifies this error only for pipes and FIFOs, but on GNU
- systems, you always get ‘ESPIPE’ if the object is not
- seekable.)
- When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ the
- ‘lseek’ function is in fact ‘lseek64’ and the type ‘off_t’ has 64
- bits which makes it possible to handle files up to 2^63 bytes in
- length.
- This function is a cancellation point in multi-threaded programs.
- This is a problem if the thread allocates some resources (like
- memory, file descriptors, semaphores or whatever) at the time
- ‘lseek’ is called. If the thread gets canceled these resources
- stay allocated until the program ends. To avoid this calls to
- ‘lseek’ should be protected using cancellation handlers.
- The ‘lseek’ function is the underlying primitive for the ‘fseek’,
- ‘fseeko’, ‘ftell’, ‘ftello’ and ‘rewind’ functions, which operate
- on streams instead of file descriptors.
- -- Function: off64_t lseek64 (int FILEDES, off64_t OFFSET, int WHENCE)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function is similar to the ‘lseek’ function. The difference
- is that the OFFSET parameter is of type ‘off64_t’ instead of
- ‘off_t’ which makes it possible on 32 bit machines to address files
- larger than 2^31 bytes and up to 2^63 bytes. The file descriptor
- ‘filedes’ must be opened using ‘open64’ since otherwise the large
- offsets possible with ‘off64_t’ will lead to errors with a
- descriptor in small file mode.
- When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ on
- a 32 bits machine this function is actually available under the
- name ‘lseek’ and so transparently replaces the 32 bit interface.
- You can have multiple descriptors for the same file if you open the
- file more than once, or if you duplicate a descriptor with ‘dup’.
- Descriptors that come from separate calls to ‘open’ have independent
- file positions; using ‘lseek’ on one descriptor has no effect on the
- other. For example,
- {
- int d1, d2;
- char buf[4];
- d1 = open ("foo", O_RDONLY);
- d2 = open ("foo", O_RDONLY);
- lseek (d1, 1024, SEEK_SET);
- read (d2, buf, 4);
- }
- will read the first four characters of the file ‘foo’. (The
- error-checking code necessary for a real program has been omitted here
- for brevity.)
- By contrast, descriptors made by duplication share a common file
- position with the original descriptor that was duplicated. Anything
- which alters the file position of one of the duplicates, including
- reading or writing data, affects all of them alike. Thus, for example,
- {
- int d1, d2, d3;
- char buf1[4], buf2[4];
- d1 = open ("foo", O_RDONLY);
- d2 = dup (d1);
- d3 = dup (d2);
- lseek (d3, 1024, SEEK_SET);
- read (d1, buf1, 4);
- read (d2, buf2, 4);
- }
- will read four characters starting with the 1024’th character of ‘foo’,
- and then four more characters starting with the 1028’th character.
- -- Data Type: off_t
- This is a signed integer type used to represent file sizes. In the
- GNU C Library, this type is no narrower than ‘int’.
- If the source is compiled with ‘_FILE_OFFSET_BITS == 64’ this type
- is transparently replaced by ‘off64_t’.
- -- Data Type: off64_t
- This type is used similar to ‘off_t’. The difference is that even
- on 32 bit machines, where the ‘off_t’ type would have 32 bits,
- ‘off64_t’ has 64 bits and so is able to address files up to 2^63
- bytes in length.
- When compiling with ‘_FILE_OFFSET_BITS == 64’ this type is
- available under the name ‘off_t’.
- These aliases for the ‘SEEK_…’ constants exist for the sake of
- compatibility with older BSD systems. They are defined in two different
- header files: ‘fcntl.h’ and ‘sys/file.h’.
- ‘L_SET’
- An alias for ‘SEEK_SET’.
- ‘L_INCR’
- An alias for ‘SEEK_CUR’.
- ‘L_XTND’
- An alias for ‘SEEK_END’.
- File: libc.info, Node: Descriptors and Streams, Next: Stream/Descriptor Precautions, Prev: File Position Primitive, Up: Low-Level I/O
- 13.4 Descriptors and Streams
- ============================
- Given an open file descriptor, you can create a stream for it with the
- ‘fdopen’ function. You can get the underlying file descriptor for an
- existing stream with the ‘fileno’ function. These functions are
- declared in the header file ‘stdio.h’.
- -- Function: FILE * fdopen (int FILEDES, const char *OPENTYPE)
- Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem lock |
- *Note POSIX Safety Concepts::.
- The ‘fdopen’ function returns a new stream for the file descriptor
- FILEDES.
- The OPENTYPE argument is interpreted in the same way as for the
- ‘fopen’ function (*note Opening Streams::), except that the ‘b’
- option is not permitted; this is because GNU systems make no
- distinction between text and binary files. Also, ‘"w"’ and ‘"w+"’
- do not cause truncation of the file; these have an effect only when
- opening a file, and in this case the file has already been opened.
- You must make sure that the OPENTYPE argument matches the actual
- mode of the open file descriptor.
- The return value is the new stream. If the stream cannot be
- created (for example, if the modes for the file indicated by the
- file descriptor do not permit the access specified by the OPENTYPE
- argument), a null pointer is returned instead.
- In some other systems, ‘fdopen’ may fail to detect that the modes
- for file descriptors do not permit the access specified by
- ‘opentype’. The GNU C Library always checks for this.
- For an example showing the use of the ‘fdopen’ function, see *note
- Creating a Pipe::.
- -- Function: int fileno (FILE *STREAM)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function returns the file descriptor associated with the
- stream STREAM. If an error is detected (for example, if the STREAM
- is not valid) or if STREAM does not do I/O to a file, ‘fileno’
- returns -1.
- -- Function: int fileno_unlocked (FILE *STREAM)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘fileno_unlocked’ function is equivalent to the ‘fileno’
- function except that it does not implicitly lock the stream if the
- state is ‘FSETLOCKING_INTERNAL’.
- This function is a GNU extension.
- There are also symbolic constants defined in ‘unistd.h’ for the file
- descriptors belonging to the standard streams ‘stdin’, ‘stdout’, and
- ‘stderr’; see *note Standard Streams::.
- ‘STDIN_FILENO’
- This macro has value ‘0’, which is the file descriptor for standard
- input.
- ‘STDOUT_FILENO’
- This macro has value ‘1’, which is the file descriptor for standard
- output.
- ‘STDERR_FILENO’
- This macro has value ‘2’, which is the file descriptor for standard
- error output.
- File: libc.info, Node: Stream/Descriptor Precautions, Next: Scatter-Gather, Prev: Descriptors and Streams, Up: Low-Level I/O
- 13.5 Dangers of Mixing Streams and Descriptors
- ==============================================
- You can have multiple file descriptors and streams (let’s call both
- streams and descriptors “channels” for short) connected to the same
- file, but you must take care to avoid confusion between channels. There
- are two cases to consider: "linked" channels that share a single file
- position value, and "independent" channels that have their own file
- positions.
- It’s best to use just one channel in your program for actual data
- transfer to any given file, except when all the access is for input.
- For example, if you open a pipe (something you can only do at the file
- descriptor level), either do all I/O with the descriptor, or construct a
- stream from the descriptor with ‘fdopen’ and then do all I/O with the
- stream.
- * Menu:
- * Linked Channels:: Dealing with channels sharing a file position.
- * Independent Channels:: Dealing with separately opened, unlinked channels.
- * Cleaning Streams:: Cleaning a stream makes it safe to use
- another channel.
- File: libc.info, Node: Linked Channels, Next: Independent Channels, Up: Stream/Descriptor Precautions
- 13.5.1 Linked Channels
- ----------------------
- Channels that come from a single opening share the same file position;
- we call them "linked" channels. Linked channels result when you make a
- stream from a descriptor using ‘fdopen’, when you get a descriptor from
- a stream with ‘fileno’, when you copy a descriptor with ‘dup’ or ‘dup2’,
- and when descriptors are inherited during ‘fork’. For files that don’t
- support random access, such as terminals and pipes, _all_ channels are
- effectively linked. On random-access files, all append-type output
- streams are effectively linked to each other.
- If you have been using a stream for I/O (or have just opened the
- stream), and you want to do I/O using another channel (either a stream
- or a descriptor) that is linked to it, you must first "clean up" the
- stream that you have been using. *Note Cleaning Streams::.
- Terminating a process, or executing a new program in the process,
- destroys all the streams in the process. If descriptors linked to these
- streams persist in other processes, their file positions become
- undefined as a result. To prevent this, you must clean up the streams
- before destroying them.
- File: libc.info, Node: Independent Channels, Next: Cleaning Streams, Prev: Linked Channels, Up: Stream/Descriptor Precautions
- 13.5.2 Independent Channels
- ---------------------------
- When you open channels (streams or descriptors) separately on a seekable
- file, each channel has its own file position. These are called
- "independent channels".
- The system handles each channel independently. Most of the time,
- this is quite predictable and natural (especially for input): each
- channel can read or write sequentially at its own place in the file.
- However, if some of the channels are streams, you must take these
- precautions:
- • You should clean an output stream after use, before doing anything
- else that might read or write from the same part of the file.
- • You should clean an input stream before reading data that may have
- been modified using an independent channel. Otherwise, you might
- read obsolete data that had been in the stream’s buffer.
- If you do output to one channel at the end of the file, this will
- certainly leave the other independent channels positioned somewhere
- before the new end. You cannot reliably set their file positions to the
- new end of file before writing, because the file can always be extended
- by another process between when you set the file position and when you
- write the data. Instead, use an append-type descriptor or stream; they
- always output at the current end of the file. In order to make the
- end-of-file position accurate, you must clean the output channel you
- were using, if it is a stream.
- It’s impossible for two channels to have separate file pointers for a
- file that doesn’t support random access. Thus, channels for reading or
- writing such files are always linked, never independent. Append-type
- channels are also always linked. For these channels, follow the rules
- for linked channels; see *note Linked Channels::.
- File: libc.info, Node: Cleaning Streams, Prev: Independent Channels, Up: Stream/Descriptor Precautions
- 13.5.3 Cleaning Streams
- -----------------------
- You can use ‘fflush’ to clean a stream in most cases.
- You can skip the ‘fflush’ if you know the stream is already clean. A
- stream is clean whenever its buffer is empty. For example, an
- unbuffered stream is always clean. An input stream that is at
- end-of-file is clean. A line-buffered stream is clean when the last
- character output was a newline. However, a just-opened input stream
- might not be clean, as its input buffer might not be empty.
- There is one case in which cleaning a stream is impossible on most
- systems. This is when the stream is doing input from a file that is not
- random-access. Such streams typically read ahead, and when the file is
- not random access, there is no way to give back the excess data already
- read. When an input stream reads from a random-access file, ‘fflush’
- does clean the stream, but leaves the file pointer at an unpredictable
- place; you must set the file pointer before doing any further I/O.
- Closing an output-only stream also does ‘fflush’, so this is a valid
- way of cleaning an output stream.
- You need not clean a stream before using its descriptor for control
- operations such as setting terminal modes; these operations don’t affect
- the file position and are not affected by it. You can use any
- descriptor for these operations, and all channels are affected
- simultaneously. However, text already “output” to a stream but still
- buffered by the stream will be subject to the new terminal modes when
- subsequently flushed. To make sure “past” output is covered by the
- terminal settings that were in effect at the time, flush the output
- streams for that terminal before setting the modes. *Note Terminal
- Modes::.
- File: libc.info, Node: Scatter-Gather, Next: Memory-mapped I/O, Prev: Stream/Descriptor Precautions, Up: Low-Level I/O
- 13.6 Fast Scatter-Gather I/O
- ============================
- Some applications may need to read or write data to multiple buffers,
- which are separated in memory. Although this can be done easily enough
- with multiple calls to ‘read’ and ‘write’, it is inefficient because
- there is overhead associated with each kernel call.
- Instead, many platforms provide special high-speed primitives to
- perform these "scatter-gather" operations in a single kernel call. The
- GNU C Library will provide an emulation on any system that lacks these
- primitives, so they are not a portability threat. They are defined in
- ‘sys/uio.h’.
- These functions are controlled with arrays of ‘iovec’ structures,
- which describe the location and size of each buffer.
- -- Data Type: struct iovec
- The ‘iovec’ structure describes a buffer. It contains two fields:
- ‘void *iov_base’
- Contains the address of a buffer.
- ‘size_t iov_len’
- Contains the length of the buffer.
- -- Function: ssize_t readv (int FILEDES, const struct iovec *VECTOR,
- int COUNT)
- Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
- POSIX Safety Concepts::.
- The ‘readv’ function reads data from FILEDES and scatters it into
- the buffers described in VECTOR, which is taken to be COUNT
- structures long. As each buffer is filled, data is sent to the
- next.
- Note that ‘readv’ is not guaranteed to fill all the buffers. It
- may stop at any point, for the same reasons ‘read’ would.
- The return value is a count of bytes (_not_ buffers) read, 0
- indicating end-of-file, or -1 indicating an error. The possible
- errors are the same as in ‘read’.
- -- Function: ssize_t writev (int FILEDES, const struct iovec *VECTOR,
- int COUNT)
- Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
- POSIX Safety Concepts::.
- The ‘writev’ function gathers data from the buffers described in
- VECTOR, which is taken to be COUNT structures long, and writes them
- to ‘filedes’. As each buffer is written, it moves on to the next.
- Like ‘readv’, ‘writev’ may stop midstream under the same conditions
- ‘write’ would.
- The return value is a count of bytes written, or -1 indicating an
- error. The possible errors are the same as in ‘write’.
- Note that if the buffers are small (under about 1kB), high-level
- streams may be easier to use than these functions. However, ‘readv’ and
- ‘writev’ are more efficient when the individual buffers themselves (as
- opposed to the total output), are large. In that case, a high-level
- stream would not be able to cache the data efficiently.
- File: libc.info, Node: Memory-mapped I/O, Next: Waiting for I/O, Prev: Scatter-Gather, Up: Low-Level I/O
- 13.7 Memory-mapped I/O
- ======================
- On modern operating systems, it is possible to "mmap" (pronounced
- “em-map”) a file to a region of memory. When this is done, the file can
- be accessed just like an array in the program.
- This is more efficient than ‘read’ or ‘write’, as only the regions of
- the file that a program actually accesses are loaded. Accesses to
- not-yet-loaded parts of the mmapped region are handled in the same way
- as swapped out pages.
- Since mmapped pages can be stored back to their file when physical
- memory is low, it is possible to mmap files orders of magnitude larger
- than both the physical memory _and_ swap space. The only limit is
- address space. The theoretical limit is 4GB on a 32-bit machine -
- however, the actual limit will be smaller since some areas will be
- reserved for other purposes. If the LFS interface is used the file size
- on 32-bit systems is not limited to 2GB (offsets are signed which
- reduces the addressable area of 4GB by half); the full 64-bit are
- available.
- Memory mapping only works on entire pages of memory. Thus, addresses
- for mapping must be page-aligned, and length values will be rounded up.
- To determine the size of a page the machine uses one should use
- size_t page_size = (size_t) sysconf (_SC_PAGESIZE);
- These functions are declared in ‘sys/mman.h’.
- -- Function: void * mmap (void *ADDRESS, size_t LENGTH, int PROTECT,
- int FLAGS, int FILEDES, off_t OFFSET)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘mmap’ function creates a new mapping, connected to bytes
- (OFFSET) to (OFFSET + LENGTH - 1) in the file open on FILEDES. A
- new reference for the file specified by FILEDES is created, which
- is not removed by closing the file.
- ADDRESS gives a preferred starting address for the mapping. ‘NULL’
- expresses no preference. Any previous mapping at that address is
- automatically removed. The address you give may still be changed,
- unless you use the ‘MAP_FIXED’ flag.
- PROTECT contains flags that control what kind of access is
- permitted. They include ‘PROT_READ’, ‘PROT_WRITE’, and
- ‘PROT_EXEC’, which permit reading, writing, and execution,
- respectively. Inappropriate access will cause a segfault (*note
- Program Error Signals::).
- Note that most hardware designs cannot support write permission
- without read permission, and many do not distinguish read and
- execute permission. Thus, you may receive wider permissions than
- you ask for, and mappings of write-only files may be denied even if
- you do not use ‘PROT_READ’.
- FLAGS contains flags that control the nature of the map. One of
- ‘MAP_SHARED’ or ‘MAP_PRIVATE’ must be specified.
- They include:
- ‘MAP_PRIVATE’
- This specifies that writes to the region should never be
- written back to the attached file. Instead, a copy is made
- for the process, and the region will be swapped normally if
- memory runs low. No other process will see the changes.
- Since private mappings effectively revert to ordinary memory
- when written to, you must have enough virtual memory for a
- copy of the entire mmapped region if you use this mode with
- ‘PROT_WRITE’.
- ‘MAP_SHARED’
- This specifies that writes to the region will be written back
- to the file. Changes made will be shared immediately with
- other processes mmaping the same file.
- Note that actual writing may take place at any time. You need
- to use ‘msync’, described below, if it is important that other
- processes using conventional I/O get a consistent view of the
- file.
- ‘MAP_FIXED’
- This forces the system to use the exact mapping address
- specified in ADDRESS and fail if it can’t.
- ‘MAP_ANONYMOUS’
- ‘MAP_ANON’
- This flag tells the system to create an anonymous mapping, not
- connected to a file. FILEDES and OFFSET are ignored, and the
- region is initialized with zeros.
- Anonymous maps are used as the basic primitive to extend the
- heap on some systems. They are also useful to share data
- between multiple tasks without creating a file.
- On some systems using private anonymous mmaps is more
- efficient than using ‘malloc’ for large blocks. This is not
- an issue with the GNU C Library, as the included ‘malloc’
- automatically uses ‘mmap’ where appropriate.
- ‘mmap’ returns the address of the new mapping, or ‘MAP_FAILED’ for
- an error.
- Possible errors include:
- ‘EINVAL’
- Either ADDRESS was unusable, or inconsistent FLAGS were given.
- ‘EACCES’
- FILEDES was not open for the type of access specified in
- PROTECT.
- ‘ENOMEM’
- Either there is not enough memory for the operation, or the
- process is out of address space.
- ‘ENODEV’
- This file is of a type that doesn’t support mapping.
- ‘ENOEXEC’
- The file is on a filesystem that doesn’t support mapping.
- -- Function: void * mmap64 (void *ADDRESS, size_t LENGTH, int PROTECT,
- int FLAGS, int FILEDES, off64_t OFFSET)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘mmap64’ function is equivalent to the ‘mmap’ function but the
- OFFSET parameter is of type ‘off64_t’. On 32-bit systems this
- allows the file associated with the FILEDES descriptor to be larger
- than 2GB. FILEDES must be a descriptor returned from a call to
- ‘open64’ or ‘fopen64’ and ‘freopen64’ where the descriptor is
- retrieved with ‘fileno’.
- When the sources are translated with ‘_FILE_OFFSET_BITS == 64’ this
- function is actually available under the name ‘mmap’. I.e., the
- new, extended API using 64 bit file sizes and offsets transparently
- replaces the old API.
- -- Function: int munmap (void *ADDR, size_t LENGTH)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- ‘munmap’ removes any memory maps from (ADDR) to (ADDR + LENGTH).
- LENGTH should be the length of the mapping.
- It is safe to unmap multiple mappings in one command, or include
- unmapped space in the range. It is also possible to unmap only
- part of an existing mapping. However, only entire pages can be
- removed. If LENGTH is not an even number of pages, it will be
- rounded up.
- It returns 0 for success and -1 for an error.
- One error is possible:
- ‘EINVAL’
- The memory range given was outside the user mmap range or
- wasn’t page aligned.
- -- Function: int msync (void *ADDRESS, size_t LENGTH, int FLAGS)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- When using shared mappings, the kernel can write the file at any
- time before the mapping is removed. To be certain data has
- actually been written to the file and will be accessible to
- non-memory-mapped I/O, it is necessary to use this function.
- It operates on the region ADDRESS to (ADDRESS + LENGTH). It may be
- used on part of a mapping or multiple mappings, however the region
- given should not contain any unmapped space.
- FLAGS can contain some options:
- ‘MS_SYNC’
- This flag makes sure the data is actually written _to disk_.
- Normally ‘msync’ only makes sure that accesses to a file with
- conventional I/O reflect the recent changes.
- ‘MS_ASYNC’
- This tells ‘msync’ to begin the synchronization, but not to
- wait for it to complete.
- ‘msync’ returns 0 for success and -1 for error. Errors include:
- ‘EINVAL’
- An invalid region was given, or the FLAGS were invalid.
- ‘EFAULT’
- There is no existing mapping in at least part of the given
- region.
- -- Function: void * mremap (void *ADDRESS, size_t LENGTH, size_t
- NEW_LENGTH, int FLAG)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function can be used to change the size of an existing memory
- area. ADDRESS and LENGTH must cover a region entirely mapped in
- the same ‘mmap’ statement. A new mapping with the same
- characteristics will be returned with the length NEW_LENGTH.
- One option is possible, ‘MREMAP_MAYMOVE’. If it is given in FLAGS,
- the system may remove the existing mapping and create a new one of
- the desired length in another location.
- The address of the resulting mapping is returned, or -1. Possible
- error codes include:
- ‘EFAULT’
- There is no existing mapping in at least part of the original
- region, or the region covers two or more distinct mappings.
- ‘EINVAL’
- The address given is misaligned or inappropriate.
- ‘EAGAIN’
- The region has pages locked, and if extended it would exceed
- the process’s resource limit for locked pages. *Note Limits
- on Resources::.
- ‘ENOMEM’
- The region is private writable, and insufficient virtual
- memory is available to extend it. Also, this error will occur
- if ‘MREMAP_MAYMOVE’ is not given and the extension would
- collide with another mapped region.
- This function is only available on a few systems. Except for
- performing optional optimizations one should not rely on this function.
- Not all file descriptors may be mapped. Sockets, pipes, and most
- devices only allow sequential access and do not fit into the mapping
- abstraction. In addition, some regular files may not be mmapable, and
- older kernels may not support mapping at all. Thus, programs using
- ‘mmap’ should have a fallback method to use should it fail. *Note
- (standards)Mmap::.
- -- Function: int madvise (void *ADDR, size_t LENGTH, int ADVICE)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function can be used to provide the system with ADVICE about
- the intended usage patterns of the memory region starting at ADDR
- and extending LENGTH bytes.
- The valid BSD values for ADVICE are:
- ‘MADV_NORMAL’
- The region should receive no further special treatment.
- ‘MADV_RANDOM’
- The region will be accessed via random page references. The
- kernel should page-in the minimal number of pages for each
- page fault.
- ‘MADV_SEQUENTIAL’
- The region will be accessed via sequential page references.
- This may cause the kernel to aggressively read-ahead,
- expecting further sequential references after any page fault
- within this region.
- ‘MADV_WILLNEED’
- The region will be needed. The pages within this region may
- be pre-faulted in by the kernel.
- ‘MADV_DONTNEED’
- The region is no longer needed. The kernel may free these
- pages, causing any changes to the pages to be lost, as well as
- swapped out pages to be discarded.
- The POSIX names are slightly different, but with the same meanings:
- ‘POSIX_MADV_NORMAL’
- This corresponds with BSD’s ‘MADV_NORMAL’.
- ‘POSIX_MADV_RANDOM’
- This corresponds with BSD’s ‘MADV_RANDOM’.
- ‘POSIX_MADV_SEQUENTIAL’
- This corresponds with BSD’s ‘MADV_SEQUENTIAL’.
- ‘POSIX_MADV_WILLNEED’
- This corresponds with BSD’s ‘MADV_WILLNEED’.
- ‘POSIX_MADV_DONTNEED’
- This corresponds with BSD’s ‘MADV_DONTNEED’.
- ‘madvise’ returns 0 for success and -1 for error. Errors include:
- ‘EINVAL’
- An invalid region was given, or the ADVICE was invalid.
- ‘EFAULT’
- There is no existing mapping in at least part of the given
- region.
- -- Function: int shm_open (const char *NAME, int OFLAG, mode_t MODE)
- Preliminary: | MT-Safe locale | AS-Unsafe init heap lock |
- AC-Unsafe lock mem fd | *Note POSIX Safety Concepts::.
- This function returns a file descriptor that can be used to
- allocate shared memory via mmap. Unrelated processes can use same
- NAME to create or open existing shared memory objects.
- A NAME argument specifies the shared memory object to be opened.
- In the GNU C Library it must be a string smaller than ‘NAME_MAX’
- bytes starting with an optional slash but containing no other
- slashes.
- The semantics of OFLAG and MODE arguments is same as in ‘open’.
- ‘shm_open’ returns the file descriptor on success or -1 on error.
- On failure ‘errno’ is set.
- -- Function: int shm_unlink (const char *NAME)
- Preliminary: | MT-Safe locale | AS-Unsafe init heap lock |
- AC-Unsafe lock mem fd | *Note POSIX Safety Concepts::.
- This function is the inverse of ‘shm_open’ and removes the object
- with the given NAME previously created by ‘shm_open’.
- ‘shm_unlink’ returns 0 on success or -1 on error. On failure
- ‘errno’ is set.
- File: libc.info, Node: Waiting for I/O, Next: Synchronizing I/O, Prev: Memory-mapped I/O, Up: Low-Level I/O
- 13.8 Waiting for Input or Output
- ================================
- Sometimes a program needs to accept input on multiple input channels
- whenever input arrives. For example, some workstations may have devices
- such as a digitizing tablet, function button box, or dial box that are
- connected via normal asynchronous serial interfaces; good user interface
- style requires responding immediately to input on any device. Another
- example is a program that acts as a server to several other processes
- via pipes or sockets.
- You cannot normally use ‘read’ for this purpose, because this blocks
- the program until input is available on one particular file descriptor;
- input on other channels won’t wake it up. You could set nonblocking
- mode and poll each file descriptor in turn, but this is very
- inefficient.
- A better solution is to use the ‘select’ function. This blocks the
- program until input or output is ready on a specified set of file
- descriptors, or until a timer expires, whichever comes first. This
- facility is declared in the header file ‘sys/types.h’.
- In the case of a server socket (*note Listening::), we say that
- “input” is available when there are pending connections that could be
- accepted (*note Accepting Connections::). ‘accept’ for server sockets
- blocks and interacts with ‘select’ just as ‘read’ does for normal input.
- The file descriptor sets for the ‘select’ function are specified as
- ‘fd_set’ objects. Here is the description of the data type and some
- macros for manipulating these objects.
- -- Data Type: fd_set
- The ‘fd_set’ data type represents file descriptor sets for the
- ‘select’ function. It is actually a bit array.
- -- Macro: int FD_SETSIZE
- The value of this macro is the maximum number of file descriptors
- that a ‘fd_set’ object can hold information about. On systems with
- a fixed maximum number, ‘FD_SETSIZE’ is at least that number. On
- some systems, including GNU, there is no absolute limit on the
- number of descriptors open, but this macro still has a constant
- value which controls the number of bits in an ‘fd_set’; if you get
- a file descriptor with a value as high as ‘FD_SETSIZE’, you cannot
- put that descriptor into an ‘fd_set’.
- -- Macro: void FD_ZERO (fd_set *SET)
- Preliminary: | MT-Safe race:set | AS-Safe | AC-Safe | *Note POSIX
- Safety Concepts::.
- This macro initializes the file descriptor set SET to be the empty
- set.
- -- Macro: void FD_SET (int FILEDES, fd_set *SET)
- Preliminary: | MT-Safe race:set | AS-Safe | AC-Safe | *Note POSIX
- Safety Concepts::.
- This macro adds FILEDES to the file descriptor set SET.
- The FILEDES parameter must not have side effects since it is
- evaluated more than once.
- -- Macro: void FD_CLR (int FILEDES, fd_set *SET)
- Preliminary: | MT-Safe race:set | AS-Safe | AC-Safe | *Note POSIX
- Safety Concepts::.
- This macro removes FILEDES from the file descriptor set SET.
- The FILEDES parameter must not have side effects since it is
- evaluated more than once.
- -- Macro: int FD_ISSET (int FILEDES, const fd_set *SET)
- Preliminary: | MT-Safe race:set | AS-Safe | AC-Safe | *Note POSIX
- Safety Concepts::.
- This macro returns a nonzero value (true) if FILEDES is a member of
- the file descriptor set SET, and zero (false) otherwise.
- The FILEDES parameter must not have side effects since it is
- evaluated more than once.
- Next, here is the description of the ‘select’ function itself.
- -- Function: int select (int NFDS, fd_set *READ-FDS, fd_set *WRITE-FDS,
- fd_set *EXCEPT-FDS, struct timeval *TIMEOUT)
- Preliminary: | MT-Safe race:read-fds race:write-fds race:except-fds
- | AS-Safe | AC-Safe | *Note POSIX Safety Concepts::.
- The ‘select’ function blocks the calling process until there is
- activity on any of the specified sets of file descriptors, or until
- the timeout period has expired.
- The file descriptors specified by the READ-FDS argument are checked
- to see if they are ready for reading; the WRITE-FDS file
- descriptors are checked to see if they are ready for writing; and
- the EXCEPT-FDS file descriptors are checked for exceptional
- conditions. You can pass a null pointer for any of these arguments
- if you are not interested in checking for that kind of condition.
- A file descriptor is considered ready for reading if a ‘read’ call
- will not block. This usually includes the read offset being at the
- end of the file or there is an error to report. A server socket is
- considered ready for reading if there is a pending connection which
- can be accepted with ‘accept’; *note Accepting Connections::. A
- client socket is ready for writing when its connection is fully
- established; *note Connecting::.
- “Exceptional conditions” does not mean errors—errors are reported
- immediately when an erroneous system call is executed, and do not
- constitute a state of the descriptor. Rather, they include
- conditions such as the presence of an urgent message on a socket.
- (*Note Sockets::, for information on urgent messages.)
- The ‘select’ function checks only the first NFDS file descriptors.
- The usual thing is to pass ‘FD_SETSIZE’ as the value of this
- argument.
- The TIMEOUT specifies the maximum time to wait. If you pass a null
- pointer for this argument, it means to block indefinitely until one
- of the file descriptors is ready. Otherwise, you should provide
- the time in ‘struct timeval’ format; see *note High-Resolution
- Calendar::. Specify zero as the time (a ‘struct timeval’
- containing all zeros) if you want to find out which descriptors are
- ready without waiting if none are ready.
- The normal return value from ‘select’ is the total number of ready
- file descriptors in all of the sets. Each of the argument sets is
- overwritten with information about the descriptors that are ready
- for the corresponding operation. Thus, to see if a particular
- descriptor DESC has input, use ‘FD_ISSET (DESC, READ-FDS)’ after
- ‘select’ returns.
- If ‘select’ returns because the timeout period expires, it returns
- a value of zero.
- Any signal will cause ‘select’ to return immediately. So if your
- program uses signals, you can’t rely on ‘select’ to keep waiting
- for the full time specified. If you want to be sure of waiting for
- a particular amount of time, you must check for ‘EINTR’ and repeat
- the ‘select’ with a newly calculated timeout based on the current
- time. See the example below. See also *note Interrupted
- Primitives::.
- If an error occurs, ‘select’ returns ‘-1’ and does not modify the
- argument file descriptor sets. The following ‘errno’ error
- conditions are defined for this function:
- ‘EBADF’
- One of the file descriptor sets specified an invalid file
- descriptor.
- ‘EINTR’
- The operation was interrupted by a signal. *Note Interrupted
- Primitives::.
- ‘EINVAL’
- The TIMEOUT argument is invalid; one of the components is
- negative or too large.
- *Portability Note:* The ‘select’ function is a BSD Unix feature.
- Here is an example showing how you can use ‘select’ to establish a
- timeout period for reading from a file descriptor. The ‘input_timeout’
- function blocks the calling process until input is available on the file
- descriptor, or until the timeout period expires.
- #include <errno.h>
- #include <stdio.h>
- #include <unistd.h>
- #include <sys/types.h>
- #include <sys/time.h>
- int
- input_timeout (int filedes, unsigned int seconds)
- {
- fd_set set;
- struct timeval timeout;
- /* Initialize the file descriptor set. */
- FD_ZERO (&set);
- FD_SET (filedes, &set);
- /* Initialize the timeout data structure. */
- timeout.tv_sec = seconds;
- timeout.tv_usec = 0;
- /* ‘select’ returns 0 if timeout, 1 if input available, -1 if error. */
- return TEMP_FAILURE_RETRY (select (FD_SETSIZE,
- &set, NULL, NULL,
- &timeout));
- }
- int
- main (void)
- {
- fprintf (stderr, "select returned %d.\n",
- input_timeout (STDIN_FILENO, 5));
- return 0;
- }
- There is another example showing the use of ‘select’ to multiplex
- input from multiple sockets in *note Server Example::.
- File: libc.info, Node: Synchronizing I/O, Next: Asynchronous I/O, Prev: Waiting for I/O, Up: Low-Level I/O
- 13.9 Synchronizing I/O operations
- =================================
- In most modern operating systems, the normal I/O operations are not
- executed synchronously. I.e., even if a ‘write’ system call returns,
- this does not mean the data is actually written to the media, e.g., the
- disk.
- In situations where synchronization points are necessary, you can use
- special functions which ensure that all operations finish before they
- return.
- -- Function: void sync (void)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- A call to this function will not return as long as there is data
- which has not been written to the device. All dirty buffers in the
- kernel will be written and so an overall consistent system can be
- achieved (if no other process in parallel writes data).
- A prototype for ‘sync’ can be found in ‘unistd.h’.
- Programs more often want to ensure that data written to a given file
- is committed, rather than all data in the system. For this, ‘sync’ is
- overkill.
- -- Function: int fsync (int FILDES)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘fsync’ function can be used to make sure all data associated
- with the open file FILDES is written to the device associated with
- the descriptor. The function call does not return unless all
- actions have finished.
- A prototype for ‘fsync’ can be found in ‘unistd.h’.
- This function is a cancellation point in multi-threaded programs.
- This is a problem if the thread allocates some resources (like
- memory, file descriptors, semaphores or whatever) at the time
- ‘fsync’ is called. If the thread gets canceled these resources
- stay allocated until the program ends. To avoid this, calls to
- ‘fsync’ should be protected using cancellation handlers.
- The return value of the function is zero if no error occurred.
- Otherwise it is -1 and the global variable ERRNO is set to the
- following values:
- ‘EBADF’
- The descriptor FILDES is not valid.
- ‘EINVAL’
- No synchronization is possible since the system does not
- implement this.
- Sometimes it is not even necessary to write all data associated with
- a file descriptor. E.g., in database files which do not change in size
- it is enough to write all the file content data to the device.
- Meta-information, like the modification time etc., are not that
- important and leaving such information uncommitted does not prevent a
- successful recovery of the file in case of a problem.
- -- Function: int fdatasync (int FILDES)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- When a call to the ‘fdatasync’ function returns, it is ensured that
- all of the file data is written to the device. For all pending I/O
- operations, the parts guaranteeing data integrity finished.
- Not all systems implement the ‘fdatasync’ operation. On systems
- missing this functionality ‘fdatasync’ is emulated by a call to
- ‘fsync’ since the performed actions are a superset of those
- required by ‘fdatasync’.
- The prototype for ‘fdatasync’ is in ‘unistd.h’.
- The return value of the function is zero if no error occurred.
- Otherwise it is -1 and the global variable ERRNO is set to the
- following values:
- ‘EBADF’
- The descriptor FILDES is not valid.
- ‘EINVAL’
- No synchronization is possible since the system does not
- implement this.
- File: libc.info, Node: Asynchronous I/O, Next: Control Operations, Prev: Synchronizing I/O, Up: Low-Level I/O
- 13.10 Perform I/O Operations in Parallel
- ========================================
- The POSIX.1b standard defines a new set of I/O operations which can
- significantly reduce the time an application spends waiting for I/O. The
- new functions allow a program to initiate one or more I/O operations and
- then immediately resume normal work while the I/O operations are
- executed in parallel. This functionality is available if the ‘unistd.h’
- file defines the symbol ‘_POSIX_ASYNCHRONOUS_IO’.
- These functions are part of the library with realtime functions named
- ‘librt’. They are not actually part of the ‘libc’ binary. The
- implementation of these functions can be done using support in the
- kernel (if available) or using an implementation based on threads at
- userlevel. In the latter case it might be necessary to link
- applications with the thread library ‘libpthread’ in addition to
- ‘librt’.
- All AIO operations operate on files which were opened previously.
- There might be arbitrarily many operations running for one file. The
- asynchronous I/O operations are controlled using a data structure named
- ‘struct aiocb’ ("AIO control block"). It is defined in ‘aio.h’ as
- follows.
- -- Data Type: struct aiocb
- The POSIX.1b standard mandates that the ‘struct aiocb’ structure
- contains at least the members described in the following table.
- There might be more elements which are used by the implementation,
- but depending upon these elements is not portable and is highly
- deprecated.
- ‘int aio_fildes’
- This element specifies the file descriptor to be used for the
- operation. It must be a legal descriptor, otherwise the
- operation will fail.
- The device on which the file is opened must allow the seek
- operation. I.e., it is not possible to use any of the AIO
- operations on devices like terminals where an ‘lseek’ call
- would lead to an error.
- ‘off_t aio_offset’
- This element specifies the offset in the file at which the
- operation (input or output) is performed. Since the
- operations are carried out in arbitrary order and more than
- one operation for one file descriptor can be started, one
- cannot expect a current read/write position of the file
- descriptor.
- ‘volatile void *aio_buf’
- This is a pointer to the buffer with the data to be written or
- the place where the read data is stored.
- ‘size_t aio_nbytes’
- This element specifies the length of the buffer pointed to by
- ‘aio_buf’.
- ‘int aio_reqprio’
- If the platform has defined ‘_POSIX_PRIORITIZED_IO’ and
- ‘_POSIX_PRIORITY_SCHEDULING’, the AIO requests are processed
- based on the current scheduling priority. The ‘aio_reqprio’
- element can then be used to lower the priority of the AIO
- operation.
- ‘struct sigevent aio_sigevent’
- This element specifies how the calling process is notified
- once the operation terminates. If the ‘sigev_notify’ element
- is ‘SIGEV_NONE’, no notification is sent. If it is
- ‘SIGEV_SIGNAL’, the signal determined by ‘sigev_signo’ is
- sent. Otherwise, ‘sigev_notify’ must be ‘SIGEV_THREAD’. In
- this case, a thread is created which starts executing the
- function pointed to by ‘sigev_notify_function’.
- ‘int aio_lio_opcode’
- This element is only used by the ‘lio_listio’ and
- ‘lio_listio64’ functions. Since these functions allow an
- arbitrary number of operations to start at once, and each
- operation can be input or output (or nothing), the information
- must be stored in the control block. The possible values are:
- ‘LIO_READ’
- Start a read operation. Read from the file at position
- ‘aio_offset’ and store the next ‘aio_nbytes’ bytes in the
- buffer pointed to by ‘aio_buf’.
- ‘LIO_WRITE’
- Start a write operation. Write ‘aio_nbytes’ bytes
- starting at ‘aio_buf’ into the file starting at position
- ‘aio_offset’.
- ‘LIO_NOP’
- Do nothing for this control block. This value is useful
- sometimes when an array of ‘struct aiocb’ values contains
- holes, i.e., some of the values must not be handled
- although the whole array is presented to the ‘lio_listio’
- function.
- When the sources are compiled using ‘_FILE_OFFSET_BITS == 64’ on a
- 32 bit machine, this type is in fact ‘struct aiocb64’, since the
- LFS interface transparently replaces the ‘struct aiocb’ definition.
- For use with the AIO functions defined in the LFS, there is a similar
- type defined which replaces the types of the appropriate members with
- larger types but otherwise is equivalent to ‘struct aiocb’.
- Particularly, all member names are the same.
- -- Data Type: struct aiocb64
- ‘int aio_fildes’
- This element specifies the file descriptor which is used for
- the operation. It must be a legal descriptor since otherwise
- the operation fails for obvious reasons.
- The device on which the file is opened must allow the seek
- operation. I.e., it is not possible to use any of the AIO
- operations on devices like terminals where an ‘lseek’ call
- would lead to an error.
- ‘off64_t aio_offset’
- This element specifies at which offset in the file the
- operation (input or output) is performed. Since the operation
- are carried in arbitrary order and more than one operation for
- one file descriptor can be started, one cannot expect a
- current read/write position of the file descriptor.
- ‘volatile void *aio_buf’
- This is a pointer to the buffer with the data to be written or
- the place where the read data is stored.
- ‘size_t aio_nbytes’
- This element specifies the length of the buffer pointed to by
- ‘aio_buf’.
- ‘int aio_reqprio’
- If for the platform ‘_POSIX_PRIORITIZED_IO’ and
- ‘_POSIX_PRIORITY_SCHEDULING’ are defined the AIO requests are
- processed based on the current scheduling priority. The
- ‘aio_reqprio’ element can then be used to lower the priority
- of the AIO operation.
- ‘struct sigevent aio_sigevent’
- This element specifies how the calling process is notified
- once the operation terminates. If the ‘sigev_notify’ element
- is ‘SIGEV_NONE’ no notification is sent. If it is
- ‘SIGEV_SIGNAL’, the signal determined by ‘sigev_signo’ is
- sent. Otherwise, ‘sigev_notify’ must be ‘SIGEV_THREAD’ in
- which case a thread is created which starts executing the
- function pointed to by ‘sigev_notify_function’.
- ‘int aio_lio_opcode’
- This element is only used by the ‘lio_listio’ and
- ‘lio_listio64’ functions. Since these functions allow an
- arbitrary number of operations to start at once, and since
- each operation can be input or output (or nothing), the
- information must be stored in the control block. See the
- description of ‘struct aiocb’ for a description of the
- possible values.
- When the sources are compiled using ‘_FILE_OFFSET_BITS == 64’ on a
- 32 bit machine, this type is available under the name ‘struct
- aiocb64’, since the LFS transparently replaces the old interface.
- * Menu:
- * Asynchronous Reads/Writes:: Asynchronous Read and Write Operations.
- * Status of AIO Operations:: Getting the Status of AIO Operations.
- * Synchronizing AIO Operations:: Getting into a consistent state.
- * Cancel AIO Operations:: Cancellation of AIO Operations.
- * Configuration of AIO:: How to optimize the AIO implementation.
- File: libc.info, Node: Asynchronous Reads/Writes, Next: Status of AIO Operations, Up: Asynchronous I/O
- 13.10.1 Asynchronous Read and Write Operations
- ----------------------------------------------
- -- Function: int aio_read (struct aiocb *AIOCBP)
- Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
- *Note POSIX Safety Concepts::.
- This function initiates an asynchronous read operation. It
- immediately returns after the operation was enqueued or when an
- error was encountered.
- The first ‘aiocbp->aio_nbytes’ bytes of the file for which
- ‘aiocbp->aio_fildes’ is a descriptor are written to the buffer
- starting at ‘aiocbp->aio_buf’. Reading starts at the absolute
- position ‘aiocbp->aio_offset’ in the file.
- If prioritized I/O is supported by the platform the
- ‘aiocbp->aio_reqprio’ value is used to adjust the priority before
- the request is actually enqueued.
- The calling process is notified about the termination of the read
- request according to the ‘aiocbp->aio_sigevent’ value.
- When ‘aio_read’ returns, the return value is zero if no error
- occurred that can be found before the process is enqueued. If such
- an early error is found, the function returns -1 and sets ‘errno’
- to one of the following values:
- ‘EAGAIN’
- The request was not enqueued due to (temporarily) exceeded
- resource limitations.
- ‘ENOSYS’
- The ‘aio_read’ function is not implemented.
- ‘EBADF’
- The ‘aiocbp->aio_fildes’ descriptor is not valid. This
- condition need not be recognized before enqueueing the request
- and so this error might also be signaled asynchronously.
- ‘EINVAL’
- The ‘aiocbp->aio_offset’ or ‘aiocbp->aio_reqpiro’ value is
- invalid. This condition need not be recognized before
- enqueueing the request and so this error might also be
- signaled asynchronously.
- If ‘aio_read’ returns zero, the current status of the request can
- be queried using ‘aio_error’ and ‘aio_return’ functions. As long
- as the value returned by ‘aio_error’ is ‘EINPROGRESS’ the operation
- has not yet completed. If ‘aio_error’ returns zero, the operation
- successfully terminated, otherwise the value is to be interpreted
- as an error code. If the function terminated, the result of the
- operation can be obtained using a call to ‘aio_return’. The
- returned value is the same as an equivalent call to ‘read’ would
- have returned. Possible error codes returned by ‘aio_error’ are:
- ‘EBADF’
- The ‘aiocbp->aio_fildes’ descriptor is not valid.
- ‘ECANCELED’
- The operation was canceled before the operation was finished
- (*note Cancel AIO Operations::)
- ‘EINVAL’
- The ‘aiocbp->aio_offset’ value is invalid.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
- function is in fact ‘aio_read64’ since the LFS interface
- transparently replaces the normal implementation.
- -- Function: int aio_read64 (struct aiocb64 *AIOCBP)
- Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
- *Note POSIX Safety Concepts::.
- This function is similar to the ‘aio_read’ function. The only
- difference is that on 32 bit machines, the file descriptor should
- be opened in the large file mode. Internally, ‘aio_read64’ uses
- functionality equivalent to ‘lseek64’ (*note File Position
- Primitive::) to position the file descriptor correctly for the
- reading, as opposed to the ‘lseek’ functionality used in
- ‘aio_read’.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
- function is available under the name ‘aio_read’ and so
- transparently replaces the interface for small files on 32 bit
- machines.
- To write data asynchronously to a file, there exists an equivalent
- pair of functions with a very similar interface.
- -- Function: int aio_write (struct aiocb *AIOCBP)
- Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
- *Note POSIX Safety Concepts::.
- This function initiates an asynchronous write operation. The
- function call immediately returns after the operation was enqueued
- or if before this happens an error was encountered.
- The first ‘aiocbp->aio_nbytes’ bytes from the buffer starting at
- ‘aiocbp->aio_buf’ are written to the file for which
- ‘aiocbp->aio_fildes’ is a descriptor, starting at the absolute
- position ‘aiocbp->aio_offset’ in the file.
- If prioritized I/O is supported by the platform, the
- ‘aiocbp->aio_reqprio’ value is used to adjust the priority before
- the request is actually enqueued.
- The calling process is notified about the termination of the read
- request according to the ‘aiocbp->aio_sigevent’ value.
- When ‘aio_write’ returns, the return value is zero if no error
- occurred that can be found before the process is enqueued. If such
- an early error is found the function returns -1 and sets ‘errno’ to
- one of the following values.
- ‘EAGAIN’
- The request was not enqueued due to (temporarily) exceeded
- resource limitations.
- ‘ENOSYS’
- The ‘aio_write’ function is not implemented.
- ‘EBADF’
- The ‘aiocbp->aio_fildes’ descriptor is not valid. This
- condition may not be recognized before enqueueing the request,
- and so this error might also be signaled asynchronously.
- ‘EINVAL’
- The ‘aiocbp->aio_offset’ or ‘aiocbp->aio_reqprio’ value is
- invalid. This condition may not be recognized before
- enqueueing the request and so this error might also be
- signaled asynchronously.
- In the case ‘aio_write’ returns zero, the current status of the
- request can be queried using the ‘aio_error’ and ‘aio_return’
- functions. As long as the value returned by ‘aio_error’ is
- ‘EINPROGRESS’ the operation has not yet completed. If ‘aio_error’
- returns zero, the operation successfully terminated, otherwise the
- value is to be interpreted as an error code. If the function
- terminated, the result of the operation can be obtained using a
- call to ‘aio_return’. The returned value is the same as an
- equivalent call to ‘read’ would have returned. Possible error
- codes returned by ‘aio_error’ are:
- ‘EBADF’
- The ‘aiocbp->aio_fildes’ descriptor is not valid.
- ‘ECANCELED’
- The operation was canceled before the operation was finished.
- (*note Cancel AIO Operations::)
- ‘EINVAL’
- The ‘aiocbp->aio_offset’ value is invalid.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
- function is in fact ‘aio_write64’ since the LFS interface
- transparently replaces the normal implementation.
- -- Function: int aio_write64 (struct aiocb64 *AIOCBP)
- Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
- *Note POSIX Safety Concepts::.
- This function is similar to the ‘aio_write’ function. The only
- difference is that on 32 bit machines the file descriptor should be
- opened in the large file mode. Internally ‘aio_write64’ uses
- functionality equivalent to ‘lseek64’ (*note File Position
- Primitive::) to position the file descriptor correctly for the
- writing, as opposed to the ‘lseek’ functionality used in
- ‘aio_write’.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
- function is available under the name ‘aio_write’ and so
- transparently replaces the interface for small files on 32 bit
- machines.
- Besides these functions with the more or less traditional interface,
- POSIX.1b also defines a function which can initiate more than one
- operation at a time, and which can handle freely mixed read and write
- operations. It is therefore similar to a combination of ‘readv’ and
- ‘writev’.
- -- Function: int lio_listio (int MODE, struct aiocb *const LIST[], int
- NENT, struct sigevent *SIG)
- Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
- *Note POSIX Safety Concepts::.
- The ‘lio_listio’ function can be used to enqueue an arbitrary
- number of read and write requests at one time. The requests can
- all be meant for the same file, all for different files or every
- solution in between.
- ‘lio_listio’ gets the NENT requests from the array pointed to by
- LIST. The operation to be performed is determined by the
- ‘aio_lio_opcode’ member in each element of LIST. If this field is
- ‘LIO_READ’ a read operation is enqueued, similar to a call of
- ‘aio_read’ for this element of the array (except that the way the
- termination is signalled is different, as we will see below). If
- the ‘aio_lio_opcode’ member is ‘LIO_WRITE’ a write operation is
- enqueued. Otherwise the ‘aio_lio_opcode’ must be ‘LIO_NOP’ in
- which case this element of LIST is simply ignored. This
- “operation” is useful in situations where one has a fixed array of
- ‘struct aiocb’ elements from which only a few need to be handled at
- a time. Another situation is where the ‘lio_listio’ call was
- canceled before all requests are processed (*note Cancel AIO
- Operations::) and the remaining requests have to be reissued.
- The other members of each element of the array pointed to by ‘list’
- must have values suitable for the operation as described in the
- documentation for ‘aio_read’ and ‘aio_write’ above.
- The MODE argument determines how ‘lio_listio’ behaves after having
- enqueued all the requests. If MODE is ‘LIO_WAIT’ it waits until
- all requests terminated. Otherwise MODE must be ‘LIO_NOWAIT’ and
- in this case the function returns immediately after having enqueued
- all the requests. In this case the caller gets a notification of
- the termination of all requests according to the SIG parameter. If
- SIG is ‘NULL’ no notification is sent. Otherwise a signal is sent
- or a thread is started, just as described in the description for
- ‘aio_read’ or ‘aio_write’.
- If MODE is ‘LIO_WAIT’, the return value of ‘lio_listio’ is 0 when
- all requests completed successfully. Otherwise the function
- returns -1 and ‘errno’ is set accordingly. To find out which
- request or requests failed one has to use the ‘aio_error’ function
- on all the elements of the array LIST.
- In case MODE is ‘LIO_NOWAIT’, the function returns 0 if all
- requests were enqueued correctly. The current state of the
- requests can be found using ‘aio_error’ and ‘aio_return’ as
- described above. If ‘lio_listio’ returns -1 in this mode, the
- global variable ‘errno’ is set accordingly. If a request did not
- yet terminate, a call to ‘aio_error’ returns ‘EINPROGRESS’. If the
- value is different, the request is finished and the error value (or
- 0) is returned and the result of the operation can be retrieved
- using ‘aio_return’.
- Possible values for ‘errno’ are:
- ‘EAGAIN’
- The resources necessary to queue all the requests are not
- available at the moment. The error status for each element of
- LIST must be checked to determine which request failed.
- Another reason could be that the system wide limit of AIO
- requests is exceeded. This cannot be the case for the
- implementation on GNU systems since no arbitrary limits exist.
- ‘EINVAL’
- The MODE parameter is invalid or NENT is larger than
- ‘AIO_LISTIO_MAX’.
- ‘EIO’
- One or more of the request’s I/O operations failed. The error
- status of each request should be checked to determine which
- one failed.
- ‘ENOSYS’
- The ‘lio_listio’ function is not supported.
- If the MODE parameter is ‘LIO_NOWAIT’ and the caller cancels a
- request, the error status for this request returned by ‘aio_error’
- is ‘ECANCELED’.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
- function is in fact ‘lio_listio64’ since the LFS interface
- transparently replaces the normal implementation.
- -- Function: int lio_listio64 (int MODE, struct aiocb64 *const LIST[],
- int NENT, struct sigevent *SIG)
- Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
- *Note POSIX Safety Concepts::.
- This function is similar to the ‘lio_listio’ function. The only
- difference is that on 32 bit machines, the file descriptor should
- be opened in the large file mode. Internally, ‘lio_listio64’ uses
- functionality equivalent to ‘lseek64’ (*note File Position
- Primitive::) to position the file descriptor correctly for the
- reading or writing, as opposed to the ‘lseek’ functionality used in
- ‘lio_listio’.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
- function is available under the name ‘lio_listio’ and so
- transparently replaces the interface for small files on 32 bit
- machines.
- File: libc.info, Node: Status of AIO Operations, Next: Synchronizing AIO Operations, Prev: Asynchronous Reads/Writes, Up: Asynchronous I/O
- 13.10.2 Getting the Status of AIO Operations
- --------------------------------------------
- As already described in the documentation of the functions in the last
- section, it must be possible to get information about the status of an
- I/O request. When the operation is performed truly asynchronously (as
- with ‘aio_read’ and ‘aio_write’ and with ‘lio_listio’ when the mode is
- ‘LIO_NOWAIT’), one sometimes needs to know whether a specific request
- already terminated and if so, what the result was. The following two
- functions allow you to get this kind of information.
- -- Function: int aio_error (const struct aiocb *AIOCBP)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function determines the error state of the request described
- by the ‘struct aiocb’ variable pointed to by AIOCBP. If the
- request has not yet terminated the value returned is always
- ‘EINPROGRESS’. Once the request has terminated the value
- ‘aio_error’ returns is either 0 if the request completed
- successfully or it returns the value which would be stored in the
- ‘errno’ variable if the request would have been done using ‘read’,
- ‘write’, or ‘fsync’.
- The function can return ‘ENOSYS’ if it is not implemented. It
- could also return ‘EINVAL’ if the AIOCBP parameter does not refer
- to an asynchronous operation whose return status is not yet known.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
- function is in fact ‘aio_error64’ since the LFS interface
- transparently replaces the normal implementation.
- -- Function: int aio_error64 (const struct aiocb64 *AIOCBP)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function is similar to ‘aio_error’ with the only difference
- that the argument is a reference to a variable of type ‘struct
- aiocb64’.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
- function is available under the name ‘aio_error’ and so
- transparently replaces the interface for small files on 32 bit
- machines.
- -- Function: ssize_t aio_return (struct aiocb *AIOCBP)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function can be used to retrieve the return status of the
- operation carried out by the request described in the variable
- pointed to by AIOCBP. As long as the error status of this request
- as returned by ‘aio_error’ is ‘EINPROGRESS’ the return value of
- this function is undefined.
- Once the request is finished this function can be used exactly once
- to retrieve the return value. Following calls might lead to
- undefined behavior. The return value itself is the value which
- would have been returned by the ‘read’, ‘write’, or ‘fsync’ call.
- The function can return ‘ENOSYS’ if it is not implemented. It
- could also return ‘EINVAL’ if the AIOCBP parameter does not refer
- to an asynchronous operation whose return status is not yet known.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
- function is in fact ‘aio_return64’ since the LFS interface
- transparently replaces the normal implementation.
- -- Function: ssize_t aio_return64 (struct aiocb64 *AIOCBP)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function is similar to ‘aio_return’ with the only difference
- that the argument is a reference to a variable of type ‘struct
- aiocb64’.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
- function is available under the name ‘aio_return’ and so
- transparently replaces the interface for small files on 32 bit
- machines.
- File: libc.info, Node: Synchronizing AIO Operations, Next: Cancel AIO Operations, Prev: Status of AIO Operations, Up: Asynchronous I/O
- 13.10.3 Getting into a Consistent State
- ---------------------------------------
- When dealing with asynchronous operations it is sometimes necessary to
- get into a consistent state. This would mean for AIO that one wants to
- know whether a certain request or a group of requests were processed.
- This could be done by waiting for the notification sent by the system
- after the operation terminated, but this sometimes would mean wasting
- resources (mainly computation time). Instead POSIX.1b defines two
- functions which will help with most kinds of consistency.
- The ‘aio_fsync’ and ‘aio_fsync64’ functions are only available if the
- symbol ‘_POSIX_SYNCHRONIZED_IO’ is defined in ‘unistd.h’.
- -- Function: int aio_fsync (int OP, struct aiocb *AIOCBP)
- Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
- *Note POSIX Safety Concepts::.
- Calling this function forces all I/O operations queued at the time
- of the function call operating on the file descriptor
- ‘aiocbp->aio_fildes’ into the synchronized I/O completion state
- (*note Synchronizing I/O::). The ‘aio_fsync’ function returns
- immediately but the notification through the method described in
- ‘aiocbp->aio_sigevent’ will happen only after all requests for this
- file descriptor have terminated and the file is synchronized. This
- also means that requests for this very same file descriptor which
- are queued after the synchronization request are not affected.
- If OP is ‘O_DSYNC’ the synchronization happens as with a call to
- ‘fdatasync’. Otherwise OP should be ‘O_SYNC’ and the
- synchronization happens as with ‘fsync’.
- As long as the synchronization has not happened, a call to
- ‘aio_error’ with the reference to the object pointed to by AIOCBP
- returns ‘EINPROGRESS’. Once the synchronization is done
- ‘aio_error’ return 0 if the synchronization was not successful.
- Otherwise the value returned is the value to which the ‘fsync’ or
- ‘fdatasync’ function would have set the ‘errno’ variable. In this
- case nothing can be assumed about the consistency of the data
- written to this file descriptor.
- The return value of this function is 0 if the request was
- successfully enqueued. Otherwise the return value is -1 and
- ‘errno’ is set to one of the following values:
- ‘EAGAIN’
- The request could not be enqueued due to temporary lack of
- resources.
- ‘EBADF’
- The file descriptor ‘AIOCBP->aio_fildes’ is not valid.
- ‘EINVAL’
- The implementation does not support I/O synchronization or the
- OP parameter is other than ‘O_DSYNC’ and ‘O_SYNC’.
- ‘ENOSYS’
- This function is not implemented.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
- function is in fact ‘aio_fsync64’ since the LFS interface
- transparently replaces the normal implementation.
- -- Function: int aio_fsync64 (int OP, struct aiocb64 *AIOCBP)
- Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
- *Note POSIX Safety Concepts::.
- This function is similar to ‘aio_fsync’ with the only difference
- that the argument is a reference to a variable of type ‘struct
- aiocb64’.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
- function is available under the name ‘aio_fsync’ and so
- transparently replaces the interface for small files on 32 bit
- machines.
- Another method of synchronization is to wait until one or more
- requests of a specific set terminated. This could be achieved by the
- ‘aio_*’ functions to notify the initiating process about the termination
- but in some situations this is not the ideal solution. In a program
- which constantly updates clients somehow connected to the server it is
- not always the best solution to go round robin since some connections
- might be slow. On the other hand letting the ‘aio_*’ functions notify
- the caller might also be not the best solution since whenever the
- process works on preparing data for a client it makes no sense to be
- interrupted by a notification since the new client will not be handled
- before the current client is served. For situations like this
- ‘aio_suspend’ should be used.
- -- Function: int aio_suspend (const struct aiocb *const LIST[], int
- NENT, const struct timespec *TIMEOUT)
- Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
- POSIX Safety Concepts::.
- When calling this function, the calling thread is suspended until
- at least one of the requests pointed to by the NENT elements of the
- array LIST has completed. If any of the requests has already
- completed at the time ‘aio_suspend’ is called, the function returns
- immediately. Whether a request has terminated or not is determined
- by comparing the error status of the request with ‘EINPROGRESS’.
- If an element of LIST is ‘NULL’, the entry is simply ignored.
- If no request has finished, the calling process is suspended. If
- TIMEOUT is ‘NULL’, the process is not woken until a request has
- finished. If TIMEOUT is not ‘NULL’, the process remains suspended
- at least as long as specified in TIMEOUT. In this case,
- ‘aio_suspend’ returns with an error.
- The return value of the function is 0 if one or more requests from
- the LIST have terminated. Otherwise the function returns -1 and
- ‘errno’ is set to one of the following values:
- ‘EAGAIN’
- None of the requests from the LIST completed in the time
- specified by TIMEOUT.
- ‘EINTR’
- A signal interrupted the ‘aio_suspend’ function. This signal
- might also be sent by the AIO implementation while signalling
- the termination of one of the requests.
- ‘ENOSYS’
- The ‘aio_suspend’ function is not implemented.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
- function is in fact ‘aio_suspend64’ since the LFS interface
- transparently replaces the normal implementation.
- -- Function: int aio_suspend64 (const struct aiocb64 *const LIST[], int
- NENT, const struct timespec *TIMEOUT)
- Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
- POSIX Safety Concepts::.
- This function is similar to ‘aio_suspend’ with the only difference
- that the argument is a reference to a variable of type ‘struct
- aiocb64’.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
- function is available under the name ‘aio_suspend’ and so
- transparently replaces the interface for small files on 32 bit
- machines.
- File: libc.info, Node: Cancel AIO Operations, Next: Configuration of AIO, Prev: Synchronizing AIO Operations, Up: Asynchronous I/O
- 13.10.4 Cancellation of AIO Operations
- --------------------------------------
- When one or more requests are asynchronously processed, it might be
- useful in some situations to cancel a selected operation, e.g., if it
- becomes obvious that the written data is no longer accurate and would
- have to be overwritten soon. As an example, assume an application,
- which writes data in files in a situation where new incoming data would
- have to be written in a file which will be updated by an enqueued
- request. The POSIX AIO implementation provides such a function, but
- this function is not capable of forcing the cancellation of the request.
- It is up to the implementation to decide whether it is possible to
- cancel the operation or not. Therefore using this function is merely a
- hint.
- -- Function: int aio_cancel (int FILDES, struct aiocb *AIOCBP)
- Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
- *Note POSIX Safety Concepts::.
- The ‘aio_cancel’ function can be used to cancel one or more
- outstanding requests. If the AIOCBP parameter is ‘NULL’, the
- function tries to cancel all of the outstanding requests which
- would process the file descriptor FILDES (i.e., whose ‘aio_fildes’
- member is FILDES). If AIOCBP is not ‘NULL’, ‘aio_cancel’ attempts
- to cancel the specific request pointed to by AIOCBP.
- For requests which were successfully canceled, the normal
- notification about the termination of the request should take
- place. I.e., depending on the ‘struct sigevent’ object which
- controls this, nothing happens, a signal is sent or a thread is
- started. If the request cannot be canceled, it terminates the
- usual way after performing the operation.
- After a request is successfully canceled, a call to ‘aio_error’
- with a reference to this request as the parameter will return
- ‘ECANCELED’ and a call to ‘aio_return’ will return -1. If the
- request wasn’t canceled and is still running the error status is
- still ‘EINPROGRESS’.
- The return value of the function is ‘AIO_CANCELED’ if there were
- requests which haven’t terminated and which were successfully
- canceled. If there is one or more requests left which couldn’t be
- canceled, the return value is ‘AIO_NOTCANCELED’. In this case
- ‘aio_error’ must be used to find out which of the, perhaps
- multiple, requests (if AIOCBP is ‘NULL’) weren’t successfully
- canceled. If all requests already terminated at the time
- ‘aio_cancel’ is called the return value is ‘AIO_ALLDONE’.
- If an error occurred during the execution of ‘aio_cancel’ the
- function returns -1 and sets ‘errno’ to one of the following
- values.
- ‘EBADF’
- The file descriptor FILDES is not valid.
- ‘ENOSYS’
- ‘aio_cancel’ is not implemented.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
- function is in fact ‘aio_cancel64’ since the LFS interface
- transparently replaces the normal implementation.
- -- Function: int aio_cancel64 (int FILDES, struct aiocb64 *AIOCBP)
- Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
- *Note POSIX Safety Concepts::.
- This function is similar to ‘aio_cancel’ with the only difference
- that the argument is a reference to a variable of type ‘struct
- aiocb64’.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
- function is available under the name ‘aio_cancel’ and so
- transparently replaces the interface for small files on 32 bit
- machines.
- File: libc.info, Node: Configuration of AIO, Prev: Cancel AIO Operations, Up: Asynchronous I/O
- 13.10.5 How to optimize the AIO implementation
- ----------------------------------------------
- The POSIX standard does not specify how the AIO functions are
- implemented. They could be system calls, but it is also possible to
- emulate them at userlevel.
- At the time of writing, the available implementation is a user-level
- implementation which uses threads for handling the enqueued requests.
- While this implementation requires making some decisions about
- limitations, hard limitations are something best avoided in the GNU C
- Library. Therefore, the GNU C Library provides a means for tuning the
- AIO implementation according to the individual use.
- -- Data Type: struct aioinit
- This data type is used to pass the configuration or tunable
- parameters to the implementation. The program has to initialize
- the members of this struct and pass it to the implementation using
- the ‘aio_init’ function.
- ‘int aio_threads’
- This member specifies the maximal number of threads which may
- be used at any one time.
- ‘int aio_num’
- This number provides an estimate on the maximal number of
- simultaneously enqueued requests.
- ‘int aio_locks’
- Unused.
- ‘int aio_usedba’
- Unused.
- ‘int aio_debug’
- Unused.
- ‘int aio_numusers’
- Unused.
- ‘int aio_reserved[2]’
- Unused.
- -- Function: void aio_init (const struct aioinit *INIT)
- Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
- POSIX Safety Concepts::.
- This function must be called before any other AIO function.
- Calling it is completely voluntary, as it is only meant to help the
- AIO implementation perform better.
- Before calling ‘aio_init’, the members of a variable of type
- ‘struct aioinit’ must be initialized. Then a reference to this
- variable is passed as the parameter to ‘aio_init’ which itself may
- or may not pay attention to the hints.
- The function has no return value and no error cases are defined.
- It is an extension which follows a proposal from the SGI
- implementation in Irix 6. It is not covered by POSIX.1b or Unix98.
- File: libc.info, Node: Control Operations, Next: Duplicating Descriptors, Prev: Asynchronous I/O, Up: Low-Level I/O
- 13.11 Control Operations on Files
- =================================
- This section describes how you can perform various other operations on
- file descriptors, such as inquiring about or setting flags describing
- the status of the file descriptor, manipulating record locks, and the
- like. All of these operations are performed by the function ‘fcntl’.
- The second argument to the ‘fcntl’ function is a command that
- specifies which operation to perform. The function and macros that name
- various flags that are used with it are declared in the header file
- ‘fcntl.h’. Many of these flags are also used by the ‘open’ function;
- see *note Opening and Closing Files::.
- -- Function: int fcntl (int FILEDES, int COMMAND, …)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘fcntl’ function performs the operation specified by COMMAND on
- the file descriptor FILEDES. Some commands require additional
- arguments to be supplied. These additional arguments and the
- return value and error conditions are given in the detailed
- descriptions of the individual commands.
- Briefly, here is a list of what the various commands are.
- ‘F_DUPFD’
- Duplicate the file descriptor (return another file descriptor
- pointing to the same open file). *Note Duplicating
- Descriptors::.
- ‘F_GETFD’
- Get flags associated with the file descriptor. *Note
- Descriptor Flags::.
- ‘F_SETFD’
- Set flags associated with the file descriptor. *Note
- Descriptor Flags::.
- ‘F_GETFL’
- Get flags associated with the open file. *Note File Status
- Flags::.
- ‘F_SETFL’
- Set flags associated with the open file. *Note File Status
- Flags::.
- ‘F_GETLK’
- Test a file lock. *Note File Locks::.
- ‘F_SETLK’
- Set or clear a file lock. *Note File Locks::.
- ‘F_SETLKW’
- Like ‘F_SETLK’, but wait for completion. *Note File Locks::.
- ‘F_OFD_GETLK’
- Test an open file description lock. *Note Open File
- Description Locks::. Specific to Linux.
- ‘F_OFD_SETLK’
- Set or clear an open file description lock. *Note Open File
- Description Locks::. Specific to Linux.
- ‘F_OFD_SETLKW’
- Like ‘F_OFD_SETLK’, but block until lock is acquired. *Note
- Open File Description Locks::. Specific to Linux.
- ‘F_GETOWN’
- Get process or process group ID to receive ‘SIGIO’ signals.
- *Note Interrupt Input::.
- ‘F_SETOWN’
- Set process or process group ID to receive ‘SIGIO’ signals.
- *Note Interrupt Input::.
- This function is a cancellation point in multi-threaded programs.
- This is a problem if the thread allocates some resources (like
- memory, file descriptors, semaphores or whatever) at the time
- ‘fcntl’ is called. If the thread gets canceled these resources
- stay allocated until the program ends. To avoid this calls to
- ‘fcntl’ should be protected using cancellation handlers.
- File: libc.info, Node: Duplicating Descriptors, Next: Descriptor Flags, Prev: Control Operations, Up: Low-Level I/O
- 13.12 Duplicating Descriptors
- =============================
- You can "duplicate" a file descriptor, or allocate another file
- descriptor that refers to the same open file as the original. Duplicate
- descriptors share one file position and one set of file status flags
- (*note File Status Flags::), but each has its own set of file descriptor
- flags (*note Descriptor Flags::).
- The major use of duplicating a file descriptor is to implement
- "redirection" of input or output: that is, to change the file or pipe
- that a particular file descriptor corresponds to.
- You can perform this operation using the ‘fcntl’ function with the
- ‘F_DUPFD’ command, but there are also convenient functions ‘dup’ and
- ‘dup2’ for duplicating descriptors.
- The ‘fcntl’ function and flags are declared in ‘fcntl.h’, while
- prototypes for ‘dup’ and ‘dup2’ are in the header file ‘unistd.h’.
- -- Function: int dup (int OLD)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function copies descriptor OLD to the first available
- descriptor number (the first number not currently open). It is
- equivalent to ‘fcntl (OLD, F_DUPFD, 0)’.
- -- Function: int dup2 (int OLD, int NEW)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function copies the descriptor OLD to descriptor number NEW.
- If OLD is an invalid descriptor, then ‘dup2’ does nothing; it does
- not close NEW. Otherwise, the new duplicate of OLD replaces any
- previous meaning of descriptor NEW, as if NEW were closed first.
- If OLD and NEW are different numbers, and OLD is a valid descriptor
- number, then ‘dup2’ is equivalent to:
- close (NEW);
- fcntl (OLD, F_DUPFD, NEW)
- However, ‘dup2’ does this atomically; there is no instant in the
- middle of calling ‘dup2’ at which NEW is closed and not yet a
- duplicate of OLD.
- -- Macro: int F_DUPFD
- This macro is used as the COMMAND argument to ‘fcntl’, to copy the
- file descriptor given as the first argument.
- The form of the call in this case is:
- fcntl (OLD, F_DUPFD, NEXT-FILEDES)
- The NEXT-FILEDES argument is of type ‘int’ and specifies that the
- file descriptor returned should be the next available one greater
- than or equal to this value.
- The return value from ‘fcntl’ with this command is normally the
- value of the new file descriptor. A return value of -1 indicates
- an error. The following ‘errno’ error conditions are defined for
- this command:
- ‘EBADF’
- The OLD argument is invalid.
- ‘EINVAL’
- The NEXT-FILEDES argument is invalid.
- ‘EMFILE’
- There are no more file descriptors available—your program is
- already using the maximum. In BSD and GNU, the maximum is
- controlled by a resource limit that can be changed; *note
- Limits on Resources::, for more information about the
- ‘RLIMIT_NOFILE’ limit.
- ‘ENFILE’ is not a possible error code for ‘dup2’ because ‘dup2’
- does not create a new opening of a file; duplicate descriptors do
- not count toward the limit which ‘ENFILE’ indicates. ‘EMFILE’ is
- possible because it refers to the limit on distinct descriptor
- numbers in use in one process.
- Here is an example showing how to use ‘dup2’ to do redirection.
- Typically, redirection of the standard streams (like ‘stdin’) is done by
- a shell or shell-like program before calling one of the ‘exec’ functions
- (*note Executing a File::) to execute a new program in a child process.
- When the new program is executed, it creates and initializes the
- standard streams to point to the corresponding file descriptors, before
- its ‘main’ function is invoked.
- So, to redirect standard input to a file, the shell could do
- something like:
- pid = fork ();
- if (pid == 0)
- {
- char *filename;
- char *program;
- int file;
- …
- file = TEMP_FAILURE_RETRY (open (filename, O_RDONLY));
- dup2 (file, STDIN_FILENO);
- TEMP_FAILURE_RETRY (close (file));
- execv (program, NULL);
- }
- There is also a more detailed example showing how to implement
- redirection in the context of a pipeline of processes in *note Launching
- Jobs::.
- File: libc.info, Node: Descriptor Flags, Next: File Status Flags, Prev: Duplicating Descriptors, Up: Low-Level I/O
- 13.13 File Descriptor Flags
- ===========================
- "File descriptor flags" are miscellaneous attributes of a file
- descriptor. These flags are associated with particular file
- descriptors, so that if you have created duplicate file descriptors from
- a single opening of a file, each descriptor has its own set of flags.
- Currently there is just one file descriptor flag: ‘FD_CLOEXEC’, which
- causes the descriptor to be closed if you use any of the ‘exec…’
- functions (*note Executing a File::).
- The symbols in this section are defined in the header file ‘fcntl.h’.
- -- Macro: int F_GETFD
- This macro is used as the COMMAND argument to ‘fcntl’, to specify
- that it should return the file descriptor flags associated with the
- FILEDES argument.
- The normal return value from ‘fcntl’ with this command is a
- nonnegative number which can be interpreted as the bitwise OR of
- the individual flags (except that currently there is only one flag
- to use).
- In case of an error, ‘fcntl’ returns -1. The following ‘errno’
- error conditions are defined for this command:
- ‘EBADF’
- The FILEDES argument is invalid.
- -- Macro: int F_SETFD
- This macro is used as the COMMAND argument to ‘fcntl’, to specify
- that it should set the file descriptor flags associated with the
- FILEDES argument. This requires a third ‘int’ argument to specify
- the new flags, so the form of the call is:
- fcntl (FILEDES, F_SETFD, NEW-FLAGS)
- The normal return value from ‘fcntl’ with this command is an
- unspecified value other than -1, which indicates an error. The
- flags and error conditions are the same as for the ‘F_GETFD’
- command.
- The following macro is defined for use as a file descriptor flag with
- the ‘fcntl’ function. The value is an integer constant usable as a bit
- mask value.
- -- Macro: int FD_CLOEXEC
- This flag specifies that the file descriptor should be closed when
- an ‘exec’ function is invoked; see *note Executing a File::. When
- a file descriptor is allocated (as with ‘open’ or ‘dup’), this bit
- is initially cleared on the new file descriptor, meaning that
- descriptor will survive into the new program after ‘exec’.
- If you want to modify the file descriptor flags, you should get the
- current flags with ‘F_GETFD’ and modify the value. Don’t assume that
- the flags listed here are the only ones that are implemented; your
- program may be run years from now and more flags may exist then. For
- example, here is a function to set or clear the flag ‘FD_CLOEXEC’
- without altering any other flags:
- /* Set the ‘FD_CLOEXEC’ flag of DESC if VALUE is nonzero,
- or clear the flag if VALUE is 0.
- Return 0 on success, or -1 on error with ‘errno’ set. */
- int
- set_cloexec_flag (int desc, int value)
- {
- int oldflags = fcntl (desc, F_GETFD, 0);
- /* If reading the flags failed, return error indication now. */
- if (oldflags < 0)
- return oldflags;
- /* Set just the flag we want to set. */
- if (value != 0)
- oldflags |= FD_CLOEXEC;
- else
- oldflags &= ~FD_CLOEXEC;
- /* Store modified flag word in the descriptor. */
- return fcntl (desc, F_SETFD, oldflags);
- }
- File: libc.info, Node: File Status Flags, Next: File Locks, Prev: Descriptor Flags, Up: Low-Level I/O
- 13.14 File Status Flags
- =======================
- "File status flags" are used to specify attributes of the opening of a
- file. Unlike the file descriptor flags discussed in *note Descriptor
- Flags::, the file status flags are shared by duplicated file descriptors
- resulting from a single opening of the file. The file status flags are
- specified with the FLAGS argument to ‘open’; *note Opening and Closing
- Files::.
- File status flags fall into three categories, which are described in
- the following sections.
- • *note Access Modes::, specify what type of access is allowed to the
- file: reading, writing, or both. They are set by ‘open’ and are
- returned by ‘fcntl’, but cannot be changed.
- • *note Open-time Flags::, control details of what ‘open’ will do.
- These flags are not preserved after the ‘open’ call.
- • *note Operating Modes::, affect how operations such as ‘read’ and
- ‘write’ are done. They are set by ‘open’, and can be fetched or
- changed with ‘fcntl’.
- The symbols in this section are defined in the header file ‘fcntl.h’.
- * Menu:
- * Access Modes:: Whether the descriptor can read or write.
- * Open-time Flags:: Details of ‘open’.
- * Operating Modes:: Special modes to control I/O operations.
- * Getting File Status Flags:: Fetching and changing these flags.
- File: libc.info, Node: Access Modes, Next: Open-time Flags, Up: File Status Flags
- 13.14.1 File Access Modes
- -------------------------
- The file access modes allow a file descriptor to be used for reading,
- writing, or both. (On GNU/Hurd systems, they can also allow none of
- these, and allow execution of the file as a program.) The access modes
- are chosen when the file is opened, and never change.
- -- Macro: int O_RDONLY
- Open the file for read access.
- -- Macro: int O_WRONLY
- Open the file for write access.
- -- Macro: int O_RDWR
- Open the file for both reading and writing.
- On GNU/Hurd systems (and not on other systems), ‘O_RDONLY’ and
- ‘O_WRONLY’ are independent bits that can be bitwise-ORed together, and
- it is valid for either bit to be set or clear. This means that ‘O_RDWR’
- is the same as ‘O_RDONLY|O_WRONLY’. A file access mode of zero is
- permissible; it allows no operations that do input or output to the
- file, but does allow other operations such as ‘fchmod’. On GNU/Hurd
- systems, since “read-only” or “write-only” is a misnomer, ‘fcntl.h’
- defines additional names for the file access modes. These names are
- preferred when writing GNU-specific code. But most programs will want
- to be portable to other POSIX.1 systems and should use the POSIX.1 names
- above instead.
- -- Macro: int O_READ
- Open the file for reading. Same as ‘O_RDONLY’; only defined on
- GNU.
- -- Macro: int O_WRITE
- Open the file for writing. Same as ‘O_WRONLY’; only defined on
- GNU.
- -- Macro: int O_EXEC
- Open the file for executing. Only defined on GNU.
- To determine the file access mode with ‘fcntl’, you must extract the
- access mode bits from the retrieved file status flags. On GNU/Hurd
- systems, you can just test the ‘O_READ’ and ‘O_WRITE’ bits in the flags
- word. But in other POSIX.1 systems, reading and writing access modes
- are not stored as distinct bit flags. The portable way to extract the
- file access mode bits is with ‘O_ACCMODE’.
- -- Macro: int O_ACCMODE
- This macro stands for a mask that can be bitwise-ANDed with the
- file status flag value to produce a value representing the file
- access mode. The mode will be ‘O_RDONLY’, ‘O_WRONLY’, or ‘O_RDWR’.
- (On GNU/Hurd systems it could also be zero, and it never includes
- the ‘O_EXEC’ bit.)
- File: libc.info, Node: Open-time Flags, Next: Operating Modes, Prev: Access Modes, Up: File Status Flags
- 13.14.2 Open-time Flags
- -----------------------
- The open-time flags specify options affecting how ‘open’ will behave.
- These options are not preserved once the file is open. The exception to
- this is ‘O_NONBLOCK’, which is also an I/O operating mode and so it _is_
- saved. *Note Opening and Closing Files::, for how to call ‘open’.
- There are two sorts of options specified by open-time flags.
- • "File name translation flags" affect how ‘open’ looks up the file
- name to locate the file, and whether the file can be created.
- • "Open-time action flags" specify extra operations that ‘open’ will
- perform on the file once it is open.
- Here are the file name translation flags.
- -- Macro: int O_CREAT
- If set, the file will be created if it doesn’t already exist.
- -- Macro: int O_EXCL
- If both ‘O_CREAT’ and ‘O_EXCL’ are set, then ‘open’ fails if the
- specified file already exists. This is guaranteed to never clobber
- an existing file.
- -- Macro: int O_NONBLOCK
- This prevents ‘open’ from blocking for a “long time” to open the
- file. This is only meaningful for some kinds of files, usually
- devices such as serial ports; when it is not meaningful, it is
- harmless and ignored. Often, opening a port to a modem blocks
- until the modem reports carrier detection; if ‘O_NONBLOCK’ is
- specified, ‘open’ will return immediately without a carrier.
- Note that the ‘O_NONBLOCK’ flag is overloaded as both an I/O
- operating mode and a file name translation flag. This means that
- specifying ‘O_NONBLOCK’ in ‘open’ also sets nonblocking I/O mode;
- *note Operating Modes::. To open the file without blocking but do
- normal I/O that blocks, you must call ‘open’ with ‘O_NONBLOCK’ set
- and then call ‘fcntl’ to turn the bit off.
- -- Macro: int O_NOCTTY
- If the named file is a terminal device, don’t make it the
- controlling terminal for the process. *Note Job Control::, for
- information about what it means to be the controlling terminal.
- On GNU/Hurd systems and 4.4 BSD, opening a file never makes it the
- controlling terminal and ‘O_NOCTTY’ is zero. However, GNU/Linux
- systems and some other systems use a nonzero value for ‘O_NOCTTY’
- and set the controlling terminal when you open a file that is a
- terminal device; so to be portable, use ‘O_NOCTTY’ when it is
- important to avoid this.
- The following three file name translation flags exist only on
- GNU/Hurd systems.
- -- Macro: int O_IGNORE_CTTY
- Do not recognize the named file as the controlling terminal, even
- if it refers to the process’s existing controlling terminal device.
- Operations on the new file descriptor will never induce job control
- signals. *Note Job Control::.
- -- Macro: int O_NOLINK
- If the named file is a symbolic link, open the link itself instead
- of the file it refers to. (‘fstat’ on the new file descriptor will
- return the information returned by ‘lstat’ on the link’s name.)
- -- Macro: int O_NOTRANS
- If the named file is specially translated, do not invoke the
- translator. Open the bare file the translator itself sees.
- The open-time action flags tell ‘open’ to do additional operations
- which are not really related to opening the file. The reason to do them
- as part of ‘open’ instead of in separate calls is that ‘open’ can do
- them atomically.
- -- Macro: int O_TRUNC
- Truncate the file to zero length. This option is only useful for
- regular files, not special files such as directories or FIFOs.
- POSIX.1 requires that you open the file for writing to use
- ‘O_TRUNC’. In BSD and GNU you must have permission to write the
- file to truncate it, but you need not open for write access.
- This is the only open-time action flag specified by POSIX.1. There
- is no good reason for truncation to be done by ‘open’, instead of
- by calling ‘ftruncate’ afterwards. The ‘O_TRUNC’ flag existed in
- Unix before ‘ftruncate’ was invented, and is retained for backward
- compatibility.
- The remaining operating modes are BSD extensions. They exist only on
- some systems. On other systems, these macros are not defined.
- -- Macro: int O_SHLOCK
- Acquire a shared lock on the file, as with ‘flock’. *Note File
- Locks::.
- If ‘O_CREAT’ is specified, the locking is done atomically when
- creating the file. You are guaranteed that no other process will
- get the lock on the new file first.
- -- Macro: int O_EXLOCK
- Acquire an exclusive lock on the file, as with ‘flock’. *Note File
- Locks::. This is atomic like ‘O_SHLOCK’.
|