libc.info-5 294 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971397239733974397539763977397839793980398139823983398439853986398739883989399039913992399339943995399639973998399940004001400240034004400540064007400840094010401140124013401440154016401740184019402040214022402340244025402640274028402940304031403240334034403540364037403840394040404140424043404440454046404740484049405040514052405340544055405640574058405940604061406240634064406540664067406840694070407140724073407440754076407740784079408040814082408340844085408640874088408940904091409240934094409540964097409840994100410141024103410441054106410741084109411041114112411341144115411641174118411941204121412241234124412541264127412841294130413141324133413441354136413741384139414041414142414341444145414641474148414941504151415241534154415541564157415841594160416141624163416441654166416741684169417041714172417341744175417641774178417941804181418241834184418541864187418841894190419141924193419441954196419741984199420042014202420342044205420642074208420942104211421242134214421542164217421842194220422142224223422442254226422742284229423042314232423342344235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262426342644265426642674268426942704271427242734274427542764277427842794280428142824283428442854286428742884289429042914292429342944295429642974298429943004301430243034304430543064307430843094310431143124313431443154316431743184319432043214322432343244325432643274328432943304331433243334334433543364337433843394340434143424343434443454346434743484349435043514352435343544355435643574358435943604361436243634364436543664367436843694370437143724373437443754376437743784379438043814382438343844385438643874388438943904391439243934394439543964397439843994400440144024403440444054406440744084409441044114412441344144415441644174418441944204421442244234424442544264427442844294430443144324433443444354436443744384439444044414442444344444445444644474448444944504451445244534454445544564457445844594460446144624463446444654466446744684469447044714472447344744475447644774478447944804481448244834484448544864487448844894490449144924493449444954496449744984499450045014502450345044505450645074508450945104511451245134514451545164517451845194520452145224523452445254526452745284529453045314532453345344535453645374538453945404541454245434544454545464547454845494550455145524553455445554556455745584559456045614562456345644565456645674568456945704571457245734574457545764577457845794580458145824583458445854586458745884589459045914592459345944595459645974598459946004601460246034604460546064607460846094610461146124613461446154616461746184619462046214622462346244625462646274628462946304631463246334634463546364637463846394640464146424643464446454646464746484649465046514652465346544655465646574658465946604661466246634664466546664667466846694670467146724673467446754676467746784679468046814682468346844685468646874688468946904691469246934694469546964697469846994700470147024703470447054706470747084709471047114712471347144715471647174718471947204721472247234724472547264727472847294730473147324733473447354736473747384739474047414742474347444745474647474748474947504751475247534754475547564757475847594760476147624763476447654766476747684769477047714772477347744775477647774778477947804781478247834784478547864787478847894790479147924793479447954796479747984799480048014802480348044805480648074808480948104811481248134814481548164817481848194820482148224823482448254826482748284829483048314832483348344835483648374838483948404841484248434844484548464847484848494850485148524853485448554856485748584859486048614862486348644865486648674868486948704871487248734874487548764877487848794880488148824883488448854886488748884889489048914892489348944895489648974898489949004901490249034904490549064907490849094910491149124913491449154916491749184919492049214922492349244925492649274928492949304931493249334934493549364937493849394940494149424943494449454946494749484949495049514952495349544955495649574958495949604961496249634964496549664967496849694970497149724973497449754976497749784979498049814982498349844985498649874988498949904991499249934994499549964997499849995000500150025003500450055006500750085009501050115012501350145015501650175018501950205021502250235024502550265027502850295030503150325033503450355036503750385039504050415042504350445045504650475048504950505051505250535054505550565057505850595060506150625063506450655066506750685069507050715072507350745075507650775078507950805081508250835084508550865087508850895090509150925093509450955096509750985099510051015102510351045105510651075108510951105111511251135114511551165117511851195120512151225123512451255126512751285129513051315132513351345135513651375138513951405141514251435144514551465147514851495150515151525153515451555156515751585159516051615162516351645165516651675168516951705171517251735174517551765177517851795180518151825183518451855186518751885189519051915192519351945195519651975198519952005201520252035204520552065207520852095210521152125213521452155216521752185219522052215222522352245225522652275228522952305231523252335234523552365237523852395240524152425243524452455246524752485249525052515252525352545255525652575258525952605261526252635264526552665267526852695270527152725273527452755276527752785279528052815282528352845285528652875288528952905291529252935294529552965297529852995300530153025303530453055306530753085309531053115312531353145315531653175318531953205321532253235324532553265327532853295330533153325333533453355336533753385339534053415342534353445345534653475348534953505351535253535354535553565357535853595360536153625363536453655366536753685369537053715372537353745375537653775378537953805381538253835384538553865387538853895390539153925393539453955396539753985399540054015402540354045405540654075408540954105411541254135414541554165417541854195420542154225423542454255426542754285429543054315432543354345435543654375438543954405441544254435444544554465447544854495450545154525453545454555456545754585459546054615462546354645465546654675468546954705471547254735474547554765477547854795480548154825483548454855486548754885489549054915492549354945495549654975498549955005501550255035504550555065507550855095510551155125513551455155516551755185519552055215522552355245525552655275528552955305531553255335534553555365537553855395540554155425543554455455546554755485549555055515552555355545555555655575558555955605561556255635564556555665567556855695570557155725573557455755576557755785579558055815582558355845585558655875588558955905591559255935594559555965597559855995600560156025603560456055606560756085609561056115612561356145615561656175618561956205621562256235624562556265627562856295630563156325633563456355636563756385639564056415642564356445645564656475648564956505651565256535654565556565657565856595660566156625663566456655666566756685669567056715672567356745675567656775678567956805681568256835684568556865687568856895690569156925693569456955696569756985699570057015702570357045705570657075708570957105711571257135714571557165717571857195720572157225723572457255726572757285729573057315732573357345735573657375738573957405741574257435744574557465747574857495750575157525753575457555756575757585759576057615762576357645765576657675768576957705771577257735774577557765777577857795780578157825783578457855786578757885789579057915792579357945795579657975798579958005801580258035804580558065807580858095810581158125813581458155816581758185819582058215822582358245825582658275828582958305831583258335834583558365837583858395840584158425843584458455846584758485849585058515852585358545855585658575858585958605861586258635864586558665867586858695870587158725873587458755876587758785879588058815882588358845885588658875888588958905891589258935894589558965897589858995900590159025903590459055906590759085909591059115912591359145915591659175918591959205921592259235924592559265927592859295930593159325933593459355936593759385939594059415942594359445945594659475948594959505951595259535954595559565957595859595960596159625963596459655966596759685969597059715972597359745975597659775978597959805981598259835984598559865987598859895990599159925993599459955996599759985999600060016002600360046005600660076008600960106011601260136014601560166017601860196020602160226023602460256026602760286029603060316032603360346035603660376038603960406041604260436044604560466047604860496050605160526053605460556056605760586059606060616062606360646065606660676068606960706071607260736074607560766077607860796080608160826083608460856086608760886089609060916092609360946095609660976098609961006101610261036104610561066107610861096110611161126113611461156116611761186119612061216122612361246125612661276128612961306131613261336134613561366137613861396140614161426143614461456146614761486149615061516152615361546155615661576158615961606161616261636164616561666167616861696170617161726173617461756176617761786179618061816182618361846185618661876188618961906191619261936194619561966197619861996200620162026203620462056206620762086209621062116212621362146215621662176218621962206221622262236224622562266227622862296230623162326233623462356236623762386239624062416242624362446245624662476248624962506251625262536254625562566257625862596260626162626263626462656266626762686269627062716272627362746275627662776278627962806281628262836284628562866287628862896290629162926293629462956296629762986299630063016302630363046305630663076308630963106311631263136314631563166317631863196320632163226323632463256326632763286329633063316332633363346335633663376338633963406341634263436344634563466347634863496350635163526353635463556356635763586359636063616362636363646365636663676368636963706371637263736374637563766377637863796380638163826383638463856386638763886389639063916392639363946395639663976398639964006401640264036404640564066407640864096410641164126413641464156416641764186419642064216422642364246425642664276428642964306431643264336434643564366437643864396440644164426443644464456446644764486449645064516452645364546455645664576458645964606461646264636464646564666467646864696470647164726473647464756476647764786479648064816482648364846485648664876488648964906491649264936494649564966497649864996500650165026503650465056506650765086509651065116512651365146515651665176518651965206521652265236524652565266527652865296530653165326533653465356536653765386539654065416542654365446545654665476548654965506551655265536554655565566557655865596560656165626563656465656566656765686569657065716572657365746575657665776578657965806581658265836584658565866587658865896590659165926593659465956596659765986599660066016602660366046605660666076608660966106611661266136614661566166617661866196620662166226623662466256626662766286629663066316632663366346635663666376638663966406641664266436644664566466647664866496650665166526653665466556656665766586659666066616662666366646665666666676668666966706671667266736674667566766677667866796680668166826683668466856686668766886689669066916692669366946695669666976698669967006701670267036704670567066707670867096710671167126713671467156716671767186719672067216722672367246725672667276728672967306731673267336734673567366737673867396740674167426743674467456746674767486749675067516752675367546755675667576758675967606761676267636764676567666767676867696770677167726773677467756776677767786779678067816782678367846785678667876788678967906791679267936794679567966797679867996800680168026803680468056806680768086809681068116812681368146815681668176818681968206821682268236824682568266827682868296830683168326833683468356836683768386839684068416842684368446845684668476848684968506851685268536854685568566857685868596860686168626863686468656866686768686869687068716872687368746875687668776878687968806881688268836884688568866887688868896890689168926893689468956896689768986899690069016902690369046905690669076908690969106911691269136914691569166917691869196920692169226923692469256926692769286929693069316932693369346935693669376938693969406941694269436944694569466947694869496950695169526953695469556956695769586959696069616962696369646965696669676968696969706971697269736974697569766977697869796980698169826983698469856986698769886989699069916992699369946995699669976998699970007001700270037004700570067007700870097010701170127013701470157016701770187019702070217022702370247025702670277028702970307031703270337034703570367037703870397040704170427043704470457046704770487049705070517052705370547055705670577058705970607061706270637064706570667067706870697070707170727073707470757076
  1. This is libc.info, produced by makeinfo version 5.2 from libc.texinfo.
  2. This file documents the GNU C Library.
  3. This is ‘The GNU C Library Reference Manual’, for version 2.25.
  4. Copyright © 1993–2017 Free Software Foundation, Inc.
  5. Permission is granted to copy, distribute and/or modify this document
  6. under the terms of the GNU Free Documentation License, Version 1.3 or
  7. any later version published by the Free Software Foundation; with the
  8. Invariant Sections being “Free Software Needs Free Documentation” and
  9. “GNU Lesser General Public License”, the Front-Cover texts being “A GNU
  10. Manual”, and with the Back-Cover Texts as in (a) below. A copy of the
  11. license is included in the section entitled "GNU Free Documentation
  12. License".
  13. (a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
  14. modify this GNU manual. Buying copies from the FSF supports it in
  15. developing GNU and promoting software freedom.”
  16. INFO-DIR-SECTION Software libraries
  17. START-INFO-DIR-ENTRY
  18. * Libc: (libc). C library.
  19. END-INFO-DIR-ENTRY
  20. INFO-DIR-SECTION GNU C library functions and macros
  21. START-INFO-DIR-ENTRY
  22. * a64l: (libc)Encode Binary Data.
  23. * abort: (libc)Aborting a Program.
  24. * abs: (libc)Absolute Value.
  25. * accept: (libc)Accepting Connections.
  26. * access: (libc)Testing File Access.
  27. * acosf: (libc)Inverse Trig Functions.
  28. * acoshf: (libc)Hyperbolic Functions.
  29. * acosh: (libc)Hyperbolic Functions.
  30. * acoshl: (libc)Hyperbolic Functions.
  31. * acos: (libc)Inverse Trig Functions.
  32. * acosl: (libc)Inverse Trig Functions.
  33. * addmntent: (libc)mtab.
  34. * addseverity: (libc)Adding Severity Classes.
  35. * adjtime: (libc)High-Resolution Calendar.
  36. * adjtimex: (libc)High-Resolution Calendar.
  37. * aio_cancel64: (libc)Cancel AIO Operations.
  38. * aio_cancel: (libc)Cancel AIO Operations.
  39. * aio_error64: (libc)Status of AIO Operations.
  40. * aio_error: (libc)Status of AIO Operations.
  41. * aio_fsync64: (libc)Synchronizing AIO Operations.
  42. * aio_fsync: (libc)Synchronizing AIO Operations.
  43. * aio_init: (libc)Configuration of AIO.
  44. * aio_read64: (libc)Asynchronous Reads/Writes.
  45. * aio_read: (libc)Asynchronous Reads/Writes.
  46. * aio_return64: (libc)Status of AIO Operations.
  47. * aio_return: (libc)Status of AIO Operations.
  48. * aio_suspend64: (libc)Synchronizing AIO Operations.
  49. * aio_suspend: (libc)Synchronizing AIO Operations.
  50. * aio_write64: (libc)Asynchronous Reads/Writes.
  51. * aio_write: (libc)Asynchronous Reads/Writes.
  52. * alarm: (libc)Setting an Alarm.
  53. * aligned_alloc: (libc)Aligned Memory Blocks.
  54. * alloca: (libc)Variable Size Automatic.
  55. * alphasort64: (libc)Scanning Directory Content.
  56. * alphasort: (libc)Scanning Directory Content.
  57. * ALTWERASE: (libc)Local Modes.
  58. * ARG_MAX: (libc)General Limits.
  59. * argp_error: (libc)Argp Helper Functions.
  60. * ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions.
  61. * argp_failure: (libc)Argp Helper Functions.
  62. * argp_help: (libc)Argp Help.
  63. * argp_parse: (libc)Argp.
  64. * argp_state_help: (libc)Argp Helper Functions.
  65. * argp_usage: (libc)Argp Helper Functions.
  66. * argz_add: (libc)Argz Functions.
  67. * argz_add_sep: (libc)Argz Functions.
  68. * argz_append: (libc)Argz Functions.
  69. * argz_count: (libc)Argz Functions.
  70. * argz_create: (libc)Argz Functions.
  71. * argz_create_sep: (libc)Argz Functions.
  72. * argz_delete: (libc)Argz Functions.
  73. * argz_extract: (libc)Argz Functions.
  74. * argz_insert: (libc)Argz Functions.
  75. * argz_next: (libc)Argz Functions.
  76. * argz_replace: (libc)Argz Functions.
  77. * argz_stringify: (libc)Argz Functions.
  78. * asctime: (libc)Formatting Calendar Time.
  79. * asctime_r: (libc)Formatting Calendar Time.
  80. * asinf: (libc)Inverse Trig Functions.
  81. * asinhf: (libc)Hyperbolic Functions.
  82. * asinh: (libc)Hyperbolic Functions.
  83. * asinhl: (libc)Hyperbolic Functions.
  84. * asin: (libc)Inverse Trig Functions.
  85. * asinl: (libc)Inverse Trig Functions.
  86. * asprintf: (libc)Dynamic Output.
  87. * assert: (libc)Consistency Checking.
  88. * assert_perror: (libc)Consistency Checking.
  89. * atan2f: (libc)Inverse Trig Functions.
  90. * atan2: (libc)Inverse Trig Functions.
  91. * atan2l: (libc)Inverse Trig Functions.
  92. * atanf: (libc)Inverse Trig Functions.
  93. * atanhf: (libc)Hyperbolic Functions.
  94. * atanh: (libc)Hyperbolic Functions.
  95. * atanhl: (libc)Hyperbolic Functions.
  96. * atan: (libc)Inverse Trig Functions.
  97. * atanl: (libc)Inverse Trig Functions.
  98. * atexit: (libc)Cleanups on Exit.
  99. * atof: (libc)Parsing of Floats.
  100. * atoi: (libc)Parsing of Integers.
  101. * atol: (libc)Parsing of Integers.
  102. * atoll: (libc)Parsing of Integers.
  103. * backtrace: (libc)Backtraces.
  104. * backtrace_symbols_fd: (libc)Backtraces.
  105. * backtrace_symbols: (libc)Backtraces.
  106. * basename: (libc)Finding Tokens in a String.
  107. * basename: (libc)Finding Tokens in a String.
  108. * BC_BASE_MAX: (libc)Utility Limits.
  109. * BC_DIM_MAX: (libc)Utility Limits.
  110. * bcmp: (libc)String/Array Comparison.
  111. * bcopy: (libc)Copying Strings and Arrays.
  112. * BC_SCALE_MAX: (libc)Utility Limits.
  113. * BC_STRING_MAX: (libc)Utility Limits.
  114. * bind: (libc)Setting Address.
  115. * bind_textdomain_codeset: (libc)Charset conversion in gettext.
  116. * bindtextdomain: (libc)Locating gettext catalog.
  117. * BRKINT: (libc)Input Modes.
  118. * brk: (libc)Resizing the Data Segment.
  119. * bsearch: (libc)Array Search Function.
  120. * btowc: (libc)Converting a Character.
  121. * BUFSIZ: (libc)Controlling Buffering.
  122. * bzero: (libc)Copying Strings and Arrays.
  123. * cabsf: (libc)Absolute Value.
  124. * cabs: (libc)Absolute Value.
  125. * cabsl: (libc)Absolute Value.
  126. * cacosf: (libc)Inverse Trig Functions.
  127. * cacoshf: (libc)Hyperbolic Functions.
  128. * cacosh: (libc)Hyperbolic Functions.
  129. * cacoshl: (libc)Hyperbolic Functions.
  130. * cacos: (libc)Inverse Trig Functions.
  131. * cacosl: (libc)Inverse Trig Functions.
  132. * calloc: (libc)Allocating Cleared Space.
  133. * canonicalize_file_name: (libc)Symbolic Links.
  134. * canonicalizef: (libc)FP Bit Twiddling.
  135. * canonicalize: (libc)FP Bit Twiddling.
  136. * canonicalizel: (libc)FP Bit Twiddling.
  137. * cargf: (libc)Operations on Complex.
  138. * carg: (libc)Operations on Complex.
  139. * cargl: (libc)Operations on Complex.
  140. * casinf: (libc)Inverse Trig Functions.
  141. * casinhf: (libc)Hyperbolic Functions.
  142. * casinh: (libc)Hyperbolic Functions.
  143. * casinhl: (libc)Hyperbolic Functions.
  144. * casin: (libc)Inverse Trig Functions.
  145. * casinl: (libc)Inverse Trig Functions.
  146. * catanf: (libc)Inverse Trig Functions.
  147. * catanhf: (libc)Hyperbolic Functions.
  148. * catanh: (libc)Hyperbolic Functions.
  149. * catanhl: (libc)Hyperbolic Functions.
  150. * catan: (libc)Inverse Trig Functions.
  151. * catanl: (libc)Inverse Trig Functions.
  152. * catclose: (libc)The catgets Functions.
  153. * catgets: (libc)The catgets Functions.
  154. * catopen: (libc)The catgets Functions.
  155. * cbc_crypt: (libc)DES Encryption.
  156. * cbrtf: (libc)Exponents and Logarithms.
  157. * cbrt: (libc)Exponents and Logarithms.
  158. * cbrtl: (libc)Exponents and Logarithms.
  159. * ccosf: (libc)Trig Functions.
  160. * ccoshf: (libc)Hyperbolic Functions.
  161. * ccosh: (libc)Hyperbolic Functions.
  162. * ccoshl: (libc)Hyperbolic Functions.
  163. * ccos: (libc)Trig Functions.
  164. * ccosl: (libc)Trig Functions.
  165. * CCTS_OFLOW: (libc)Control Modes.
  166. * ceilf: (libc)Rounding Functions.
  167. * ceil: (libc)Rounding Functions.
  168. * ceill: (libc)Rounding Functions.
  169. * cexpf: (libc)Exponents and Logarithms.
  170. * cexp: (libc)Exponents and Logarithms.
  171. * cexpl: (libc)Exponents and Logarithms.
  172. * cfgetispeed: (libc)Line Speed.
  173. * cfgetospeed: (libc)Line Speed.
  174. * cfmakeraw: (libc)Noncanonical Input.
  175. * cfree: (libc)Freeing after Malloc.
  176. * cfsetispeed: (libc)Line Speed.
  177. * cfsetospeed: (libc)Line Speed.
  178. * cfsetspeed: (libc)Line Speed.
  179. * chdir: (libc)Working Directory.
  180. * CHILD_MAX: (libc)General Limits.
  181. * chmod: (libc)Setting Permissions.
  182. * chown: (libc)File Owner.
  183. * CIGNORE: (libc)Control Modes.
  184. * cimagf: (libc)Operations on Complex.
  185. * cimag: (libc)Operations on Complex.
  186. * cimagl: (libc)Operations on Complex.
  187. * clearenv: (libc)Environment Access.
  188. * clearerr: (libc)Error Recovery.
  189. * clearerr_unlocked: (libc)Error Recovery.
  190. * CLK_TCK: (libc)Processor Time.
  191. * CLOCAL: (libc)Control Modes.
  192. * clock: (libc)CPU Time.
  193. * CLOCKS_PER_SEC: (libc)CPU Time.
  194. * clog10f: (libc)Exponents and Logarithms.
  195. * clog10: (libc)Exponents and Logarithms.
  196. * clog10l: (libc)Exponents and Logarithms.
  197. * clogf: (libc)Exponents and Logarithms.
  198. * clog: (libc)Exponents and Logarithms.
  199. * clogl: (libc)Exponents and Logarithms.
  200. * closedir: (libc)Reading/Closing Directory.
  201. * close: (libc)Opening and Closing Files.
  202. * closelog: (libc)closelog.
  203. * COLL_WEIGHTS_MAX: (libc)Utility Limits.
  204. * _Complex_I: (libc)Complex Numbers.
  205. * confstr: (libc)String Parameters.
  206. * conjf: (libc)Operations on Complex.
  207. * conj: (libc)Operations on Complex.
  208. * conjl: (libc)Operations on Complex.
  209. * connect: (libc)Connecting.
  210. * copysignf: (libc)FP Bit Twiddling.
  211. * copysign: (libc)FP Bit Twiddling.
  212. * copysignl: (libc)FP Bit Twiddling.
  213. * cosf: (libc)Trig Functions.
  214. * coshf: (libc)Hyperbolic Functions.
  215. * cosh: (libc)Hyperbolic Functions.
  216. * coshl: (libc)Hyperbolic Functions.
  217. * cos: (libc)Trig Functions.
  218. * cosl: (libc)Trig Functions.
  219. * cpowf: (libc)Exponents and Logarithms.
  220. * cpow: (libc)Exponents and Logarithms.
  221. * cpowl: (libc)Exponents and Logarithms.
  222. * cprojf: (libc)Operations on Complex.
  223. * cproj: (libc)Operations on Complex.
  224. * cprojl: (libc)Operations on Complex.
  225. * CPU_CLR: (libc)CPU Affinity.
  226. * CPU_ISSET: (libc)CPU Affinity.
  227. * CPU_SET: (libc)CPU Affinity.
  228. * CPU_SETSIZE: (libc)CPU Affinity.
  229. * CPU_ZERO: (libc)CPU Affinity.
  230. * CREAD: (libc)Control Modes.
  231. * crealf: (libc)Operations on Complex.
  232. * creal: (libc)Operations on Complex.
  233. * creall: (libc)Operations on Complex.
  234. * creat64: (libc)Opening and Closing Files.
  235. * creat: (libc)Opening and Closing Files.
  236. * CRTS_IFLOW: (libc)Control Modes.
  237. * crypt: (libc)crypt.
  238. * crypt_r: (libc)crypt.
  239. * CS5: (libc)Control Modes.
  240. * CS6: (libc)Control Modes.
  241. * CS7: (libc)Control Modes.
  242. * CS8: (libc)Control Modes.
  243. * csinf: (libc)Trig Functions.
  244. * csinhf: (libc)Hyperbolic Functions.
  245. * csinh: (libc)Hyperbolic Functions.
  246. * csinhl: (libc)Hyperbolic Functions.
  247. * csin: (libc)Trig Functions.
  248. * csinl: (libc)Trig Functions.
  249. * CSIZE: (libc)Control Modes.
  250. * csqrtf: (libc)Exponents and Logarithms.
  251. * csqrt: (libc)Exponents and Logarithms.
  252. * csqrtl: (libc)Exponents and Logarithms.
  253. * CSTOPB: (libc)Control Modes.
  254. * ctanf: (libc)Trig Functions.
  255. * ctanhf: (libc)Hyperbolic Functions.
  256. * ctanh: (libc)Hyperbolic Functions.
  257. * ctanhl: (libc)Hyperbolic Functions.
  258. * ctan: (libc)Trig Functions.
  259. * ctanl: (libc)Trig Functions.
  260. * ctermid: (libc)Identifying the Terminal.
  261. * ctime: (libc)Formatting Calendar Time.
  262. * ctime_r: (libc)Formatting Calendar Time.
  263. * cuserid: (libc)Who Logged In.
  264. * dcgettext: (libc)Translation with gettext.
  265. * dcngettext: (libc)Advanced gettext functions.
  266. * DES_FAILED: (libc)DES Encryption.
  267. * des_setparity: (libc)DES Encryption.
  268. * dgettext: (libc)Translation with gettext.
  269. * difftime: (libc)Elapsed Time.
  270. * dirfd: (libc)Opening a Directory.
  271. * dirname: (libc)Finding Tokens in a String.
  272. * div: (libc)Integer Division.
  273. * dngettext: (libc)Advanced gettext functions.
  274. * drand48: (libc)SVID Random.
  275. * drand48_r: (libc)SVID Random.
  276. * dremf: (libc)Remainder Functions.
  277. * drem: (libc)Remainder Functions.
  278. * dreml: (libc)Remainder Functions.
  279. * DTTOIF: (libc)Directory Entries.
  280. * dup2: (libc)Duplicating Descriptors.
  281. * dup: (libc)Duplicating Descriptors.
  282. * E2BIG: (libc)Error Codes.
  283. * EACCES: (libc)Error Codes.
  284. * EADDRINUSE: (libc)Error Codes.
  285. * EADDRNOTAVAIL: (libc)Error Codes.
  286. * EADV: (libc)Error Codes.
  287. * EAFNOSUPPORT: (libc)Error Codes.
  288. * EAGAIN: (libc)Error Codes.
  289. * EALREADY: (libc)Error Codes.
  290. * EAUTH: (libc)Error Codes.
  291. * EBACKGROUND: (libc)Error Codes.
  292. * EBADE: (libc)Error Codes.
  293. * EBADFD: (libc)Error Codes.
  294. * EBADF: (libc)Error Codes.
  295. * EBADMSG: (libc)Error Codes.
  296. * EBADR: (libc)Error Codes.
  297. * EBADRPC: (libc)Error Codes.
  298. * EBADRQC: (libc)Error Codes.
  299. * EBADSLT: (libc)Error Codes.
  300. * EBFONT: (libc)Error Codes.
  301. * EBUSY: (libc)Error Codes.
  302. * ECANCELED: (libc)Error Codes.
  303. * ecb_crypt: (libc)DES Encryption.
  304. * ECHILD: (libc)Error Codes.
  305. * ECHOCTL: (libc)Local Modes.
  306. * ECHOE: (libc)Local Modes.
  307. * ECHOKE: (libc)Local Modes.
  308. * ECHOK: (libc)Local Modes.
  309. * ECHO: (libc)Local Modes.
  310. * ECHONL: (libc)Local Modes.
  311. * ECHOPRT: (libc)Local Modes.
  312. * ECHRNG: (libc)Error Codes.
  313. * ECOMM: (libc)Error Codes.
  314. * ECONNABORTED: (libc)Error Codes.
  315. * ECONNREFUSED: (libc)Error Codes.
  316. * ECONNRESET: (libc)Error Codes.
  317. * ecvt: (libc)System V Number Conversion.
  318. * ecvt_r: (libc)System V Number Conversion.
  319. * EDEADLK: (libc)Error Codes.
  320. * EDEADLOCK: (libc)Error Codes.
  321. * EDESTADDRREQ: (libc)Error Codes.
  322. * EDIED: (libc)Error Codes.
  323. * ED: (libc)Error Codes.
  324. * EDOM: (libc)Error Codes.
  325. * EDOTDOT: (libc)Error Codes.
  326. * EDQUOT: (libc)Error Codes.
  327. * EEXIST: (libc)Error Codes.
  328. * EFAULT: (libc)Error Codes.
  329. * EFBIG: (libc)Error Codes.
  330. * EFTYPE: (libc)Error Codes.
  331. * EGRATUITOUS: (libc)Error Codes.
  332. * EGREGIOUS: (libc)Error Codes.
  333. * EHOSTDOWN: (libc)Error Codes.
  334. * EHOSTUNREACH: (libc)Error Codes.
  335. * EHWPOISON: (libc)Error Codes.
  336. * EIDRM: (libc)Error Codes.
  337. * EIEIO: (libc)Error Codes.
  338. * EILSEQ: (libc)Error Codes.
  339. * EINPROGRESS: (libc)Error Codes.
  340. * EINTR: (libc)Error Codes.
  341. * EINVAL: (libc)Error Codes.
  342. * EIO: (libc)Error Codes.
  343. * EISCONN: (libc)Error Codes.
  344. * EISDIR: (libc)Error Codes.
  345. * EISNAM: (libc)Error Codes.
  346. * EKEYEXPIRED: (libc)Error Codes.
  347. * EKEYREJECTED: (libc)Error Codes.
  348. * EKEYREVOKED: (libc)Error Codes.
  349. * EL2HLT: (libc)Error Codes.
  350. * EL2NSYNC: (libc)Error Codes.
  351. * EL3HLT: (libc)Error Codes.
  352. * EL3RST: (libc)Error Codes.
  353. * ELIBACC: (libc)Error Codes.
  354. * ELIBBAD: (libc)Error Codes.
  355. * ELIBEXEC: (libc)Error Codes.
  356. * ELIBMAX: (libc)Error Codes.
  357. * ELIBSCN: (libc)Error Codes.
  358. * ELNRNG: (libc)Error Codes.
  359. * ELOOP: (libc)Error Codes.
  360. * EMEDIUMTYPE: (libc)Error Codes.
  361. * EMFILE: (libc)Error Codes.
  362. * EMLINK: (libc)Error Codes.
  363. * EMSGSIZE: (libc)Error Codes.
  364. * EMULTIHOP: (libc)Error Codes.
  365. * ENAMETOOLONG: (libc)Error Codes.
  366. * ENAVAIL: (libc)Error Codes.
  367. * encrypt: (libc)DES Encryption.
  368. * encrypt_r: (libc)DES Encryption.
  369. * endfsent: (libc)fstab.
  370. * endgrent: (libc)Scanning All Groups.
  371. * endhostent: (libc)Host Names.
  372. * endmntent: (libc)mtab.
  373. * endnetent: (libc)Networks Database.
  374. * endnetgrent: (libc)Lookup Netgroup.
  375. * endprotoent: (libc)Protocols Database.
  376. * endpwent: (libc)Scanning All Users.
  377. * endservent: (libc)Services Database.
  378. * endutent: (libc)Manipulating the Database.
  379. * endutxent: (libc)XPG Functions.
  380. * ENEEDAUTH: (libc)Error Codes.
  381. * ENETDOWN: (libc)Error Codes.
  382. * ENETRESET: (libc)Error Codes.
  383. * ENETUNREACH: (libc)Error Codes.
  384. * ENFILE: (libc)Error Codes.
  385. * ENOANO: (libc)Error Codes.
  386. * ENOBUFS: (libc)Error Codes.
  387. * ENOCSI: (libc)Error Codes.
  388. * ENODATA: (libc)Error Codes.
  389. * ENODEV: (libc)Error Codes.
  390. * ENOENT: (libc)Error Codes.
  391. * ENOEXEC: (libc)Error Codes.
  392. * ENOKEY: (libc)Error Codes.
  393. * ENOLCK: (libc)Error Codes.
  394. * ENOLINK: (libc)Error Codes.
  395. * ENOMEDIUM: (libc)Error Codes.
  396. * ENOMEM: (libc)Error Codes.
  397. * ENOMSG: (libc)Error Codes.
  398. * ENONET: (libc)Error Codes.
  399. * ENOPKG: (libc)Error Codes.
  400. * ENOPROTOOPT: (libc)Error Codes.
  401. * ENOSPC: (libc)Error Codes.
  402. * ENOSR: (libc)Error Codes.
  403. * ENOSTR: (libc)Error Codes.
  404. * ENOSYS: (libc)Error Codes.
  405. * ENOTBLK: (libc)Error Codes.
  406. * ENOTCONN: (libc)Error Codes.
  407. * ENOTDIR: (libc)Error Codes.
  408. * ENOTEMPTY: (libc)Error Codes.
  409. * ENOTNAM: (libc)Error Codes.
  410. * ENOTRECOVERABLE: (libc)Error Codes.
  411. * ENOTSOCK: (libc)Error Codes.
  412. * ENOTSUP: (libc)Error Codes.
  413. * ENOTTY: (libc)Error Codes.
  414. * ENOTUNIQ: (libc)Error Codes.
  415. * envz_add: (libc)Envz Functions.
  416. * envz_entry: (libc)Envz Functions.
  417. * envz_get: (libc)Envz Functions.
  418. * envz_merge: (libc)Envz Functions.
  419. * envz_remove: (libc)Envz Functions.
  420. * envz_strip: (libc)Envz Functions.
  421. * ENXIO: (libc)Error Codes.
  422. * EOF: (libc)EOF and Errors.
  423. * EOPNOTSUPP: (libc)Error Codes.
  424. * EOVERFLOW: (libc)Error Codes.
  425. * EOWNERDEAD: (libc)Error Codes.
  426. * EPERM: (libc)Error Codes.
  427. * EPFNOSUPPORT: (libc)Error Codes.
  428. * EPIPE: (libc)Error Codes.
  429. * EPROCLIM: (libc)Error Codes.
  430. * EPROCUNAVAIL: (libc)Error Codes.
  431. * EPROGMISMATCH: (libc)Error Codes.
  432. * EPROGUNAVAIL: (libc)Error Codes.
  433. * EPROTO: (libc)Error Codes.
  434. * EPROTONOSUPPORT: (libc)Error Codes.
  435. * EPROTOTYPE: (libc)Error Codes.
  436. * EQUIV_CLASS_MAX: (libc)Utility Limits.
  437. * erand48: (libc)SVID Random.
  438. * erand48_r: (libc)SVID Random.
  439. * ERANGE: (libc)Error Codes.
  440. * EREMCHG: (libc)Error Codes.
  441. * EREMOTEIO: (libc)Error Codes.
  442. * EREMOTE: (libc)Error Codes.
  443. * ERESTART: (libc)Error Codes.
  444. * erfcf: (libc)Special Functions.
  445. * erfc: (libc)Special Functions.
  446. * erfcl: (libc)Special Functions.
  447. * erff: (libc)Special Functions.
  448. * ERFKILL: (libc)Error Codes.
  449. * erf: (libc)Special Functions.
  450. * erfl: (libc)Special Functions.
  451. * EROFS: (libc)Error Codes.
  452. * ERPCMISMATCH: (libc)Error Codes.
  453. * err: (libc)Error Messages.
  454. * errno: (libc)Checking for Errors.
  455. * error_at_line: (libc)Error Messages.
  456. * error: (libc)Error Messages.
  457. * errx: (libc)Error Messages.
  458. * ESHUTDOWN: (libc)Error Codes.
  459. * ESOCKTNOSUPPORT: (libc)Error Codes.
  460. * ESPIPE: (libc)Error Codes.
  461. * ESRCH: (libc)Error Codes.
  462. * ESRMNT: (libc)Error Codes.
  463. * ESTALE: (libc)Error Codes.
  464. * ESTRPIPE: (libc)Error Codes.
  465. * ETIMEDOUT: (libc)Error Codes.
  466. * ETIME: (libc)Error Codes.
  467. * ETOOMANYREFS: (libc)Error Codes.
  468. * ETXTBSY: (libc)Error Codes.
  469. * EUCLEAN: (libc)Error Codes.
  470. * EUNATCH: (libc)Error Codes.
  471. * EUSERS: (libc)Error Codes.
  472. * EWOULDBLOCK: (libc)Error Codes.
  473. * EXDEV: (libc)Error Codes.
  474. * execle: (libc)Executing a File.
  475. * execl: (libc)Executing a File.
  476. * execlp: (libc)Executing a File.
  477. * execve: (libc)Executing a File.
  478. * execv: (libc)Executing a File.
  479. * execvp: (libc)Executing a File.
  480. * EXFULL: (libc)Error Codes.
  481. * EXIT_FAILURE: (libc)Exit Status.
  482. * exit: (libc)Normal Termination.
  483. * _exit: (libc)Termination Internals.
  484. * _Exit: (libc)Termination Internals.
  485. * EXIT_SUCCESS: (libc)Exit Status.
  486. * exp10f: (libc)Exponents and Logarithms.
  487. * exp10: (libc)Exponents and Logarithms.
  488. * exp10l: (libc)Exponents and Logarithms.
  489. * exp2f: (libc)Exponents and Logarithms.
  490. * exp2: (libc)Exponents and Logarithms.
  491. * exp2l: (libc)Exponents and Logarithms.
  492. * expf: (libc)Exponents and Logarithms.
  493. * exp: (libc)Exponents and Logarithms.
  494. * explicit_bzero: (libc)Erasing Sensitive Data.
  495. * expl: (libc)Exponents and Logarithms.
  496. * expm1f: (libc)Exponents and Logarithms.
  497. * expm1: (libc)Exponents and Logarithms.
  498. * expm1l: (libc)Exponents and Logarithms.
  499. * EXPR_NEST_MAX: (libc)Utility Limits.
  500. * fabsf: (libc)Absolute Value.
  501. * fabs: (libc)Absolute Value.
  502. * fabsl: (libc)Absolute Value.
  503. * __fbufsize: (libc)Controlling Buffering.
  504. * fchdir: (libc)Working Directory.
  505. * fchmod: (libc)Setting Permissions.
  506. * fchown: (libc)File Owner.
  507. * fcloseall: (libc)Closing Streams.
  508. * fclose: (libc)Closing Streams.
  509. * fcntl: (libc)Control Operations.
  510. * fcvt: (libc)System V Number Conversion.
  511. * fcvt_r: (libc)System V Number Conversion.
  512. * fdatasync: (libc)Synchronizing I/O.
  513. * FD_CLOEXEC: (libc)Descriptor Flags.
  514. * FD_CLR: (libc)Waiting for I/O.
  515. * fdimf: (libc)Misc FP Arithmetic.
  516. * fdim: (libc)Misc FP Arithmetic.
  517. * fdiml: (libc)Misc FP Arithmetic.
  518. * FD_ISSET: (libc)Waiting for I/O.
  519. * fdopendir: (libc)Opening a Directory.
  520. * fdopen: (libc)Descriptors and Streams.
  521. * FD_SET: (libc)Waiting for I/O.
  522. * FD_SETSIZE: (libc)Waiting for I/O.
  523. * F_DUPFD: (libc)Duplicating Descriptors.
  524. * FD_ZERO: (libc)Waiting for I/O.
  525. * feclearexcept: (libc)Status bit operations.
  526. * fedisableexcept: (libc)Control Functions.
  527. * feenableexcept: (libc)Control Functions.
  528. * fegetenv: (libc)Control Functions.
  529. * fegetexceptflag: (libc)Status bit operations.
  530. * fegetexcept: (libc)Control Functions.
  531. * fegetmode: (libc)Control Functions.
  532. * fegetround: (libc)Rounding.
  533. * feholdexcept: (libc)Control Functions.
  534. * feof: (libc)EOF and Errors.
  535. * feof_unlocked: (libc)EOF and Errors.
  536. * feraiseexcept: (libc)Status bit operations.
  537. * ferror: (libc)EOF and Errors.
  538. * ferror_unlocked: (libc)EOF and Errors.
  539. * fesetenv: (libc)Control Functions.
  540. * fesetexceptflag: (libc)Status bit operations.
  541. * fesetexcept: (libc)Status bit operations.
  542. * fesetmode: (libc)Control Functions.
  543. * fesetround: (libc)Rounding.
  544. * FE_SNANS_ALWAYS_SIGNAL: (libc)Infinity and NaN.
  545. * fetestexceptflag: (libc)Status bit operations.
  546. * fetestexcept: (libc)Status bit operations.
  547. * feupdateenv: (libc)Control Functions.
  548. * fflush: (libc)Flushing Buffers.
  549. * fflush_unlocked: (libc)Flushing Buffers.
  550. * fgetc: (libc)Character Input.
  551. * fgetc_unlocked: (libc)Character Input.
  552. * F_GETFD: (libc)Descriptor Flags.
  553. * F_GETFL: (libc)Getting File Status Flags.
  554. * fgetgrent: (libc)Scanning All Groups.
  555. * fgetgrent_r: (libc)Scanning All Groups.
  556. * F_GETLK: (libc)File Locks.
  557. * F_GETOWN: (libc)Interrupt Input.
  558. * fgetpos64: (libc)Portable Positioning.
  559. * fgetpos: (libc)Portable Positioning.
  560. * fgetpwent: (libc)Scanning All Users.
  561. * fgetpwent_r: (libc)Scanning All Users.
  562. * fgets: (libc)Line Input.
  563. * fgets_unlocked: (libc)Line Input.
  564. * fgetwc: (libc)Character Input.
  565. * fgetwc_unlocked: (libc)Character Input.
  566. * fgetws: (libc)Line Input.
  567. * fgetws_unlocked: (libc)Line Input.
  568. * FILENAME_MAX: (libc)Limits for Files.
  569. * fileno: (libc)Descriptors and Streams.
  570. * fileno_unlocked: (libc)Descriptors and Streams.
  571. * finitef: (libc)Floating Point Classes.
  572. * finite: (libc)Floating Point Classes.
  573. * finitel: (libc)Floating Point Classes.
  574. * __flbf: (libc)Controlling Buffering.
  575. * flockfile: (libc)Streams and Threads.
  576. * floorf: (libc)Rounding Functions.
  577. * floor: (libc)Rounding Functions.
  578. * floorl: (libc)Rounding Functions.
  579. * _flushlbf: (libc)Flushing Buffers.
  580. * FLUSHO: (libc)Local Modes.
  581. * fmaf: (libc)Misc FP Arithmetic.
  582. * fma: (libc)Misc FP Arithmetic.
  583. * fmal: (libc)Misc FP Arithmetic.
  584. * fmaxf: (libc)Misc FP Arithmetic.
  585. * fmax: (libc)Misc FP Arithmetic.
  586. * fmaxl: (libc)Misc FP Arithmetic.
  587. * fmaxmagf: (libc)Misc FP Arithmetic.
  588. * fmaxmag: (libc)Misc FP Arithmetic.
  589. * fmaxmagl: (libc)Misc FP Arithmetic.
  590. * fmemopen: (libc)String Streams.
  591. * fminf: (libc)Misc FP Arithmetic.
  592. * fmin: (libc)Misc FP Arithmetic.
  593. * fminl: (libc)Misc FP Arithmetic.
  594. * fminmagf: (libc)Misc FP Arithmetic.
  595. * fminmag: (libc)Misc FP Arithmetic.
  596. * fminmagl: (libc)Misc FP Arithmetic.
  597. * fmodf: (libc)Remainder Functions.
  598. * fmod: (libc)Remainder Functions.
  599. * fmodl: (libc)Remainder Functions.
  600. * fmtmsg: (libc)Printing Formatted Messages.
  601. * fnmatch: (libc)Wildcard Matching.
  602. * F_OFD_GETLK: (libc)Open File Description Locks.
  603. * F_OFD_SETLK: (libc)Open File Description Locks.
  604. * F_OFD_SETLKW: (libc)Open File Description Locks.
  605. * F_OK: (libc)Testing File Access.
  606. * fopen64: (libc)Opening Streams.
  607. * fopencookie: (libc)Streams and Cookies.
  608. * fopen: (libc)Opening Streams.
  609. * FOPEN_MAX: (libc)Opening Streams.
  610. * fork: (libc)Creating a Process.
  611. * forkpty: (libc)Pseudo-Terminal Pairs.
  612. * fpathconf: (libc)Pathconf.
  613. * fpclassify: (libc)Floating Point Classes.
  614. * __fpending: (libc)Controlling Buffering.
  615. * FP_ILOGB0: (libc)Exponents and Logarithms.
  616. * FP_ILOGBNAN: (libc)Exponents and Logarithms.
  617. * FP_LLOGB0: (libc)Exponents and Logarithms.
  618. * FP_LLOGBNAN: (libc)Exponents and Logarithms.
  619. * fprintf: (libc)Formatted Output Functions.
  620. * __fpurge: (libc)Flushing Buffers.
  621. * fputc: (libc)Simple Output.
  622. * fputc_unlocked: (libc)Simple Output.
  623. * fputs: (libc)Simple Output.
  624. * fputs_unlocked: (libc)Simple Output.
  625. * fputwc: (libc)Simple Output.
  626. * fputwc_unlocked: (libc)Simple Output.
  627. * fputws: (libc)Simple Output.
  628. * fputws_unlocked: (libc)Simple Output.
  629. * __freadable: (libc)Opening Streams.
  630. * __freading: (libc)Opening Streams.
  631. * fread: (libc)Block Input/Output.
  632. * fread_unlocked: (libc)Block Input/Output.
  633. * free: (libc)Freeing after Malloc.
  634. * freopen64: (libc)Opening Streams.
  635. * freopen: (libc)Opening Streams.
  636. * frexpf: (libc)Normalization Functions.
  637. * frexp: (libc)Normalization Functions.
  638. * frexpl: (libc)Normalization Functions.
  639. * fromfpf: (libc)Rounding Functions.
  640. * fromfp: (libc)Rounding Functions.
  641. * fromfpl: (libc)Rounding Functions.
  642. * fromfpxf: (libc)Rounding Functions.
  643. * fromfpx: (libc)Rounding Functions.
  644. * fromfpxl: (libc)Rounding Functions.
  645. * fscanf: (libc)Formatted Input Functions.
  646. * fseek: (libc)File Positioning.
  647. * fseeko64: (libc)File Positioning.
  648. * fseeko: (libc)File Positioning.
  649. * F_SETFD: (libc)Descriptor Flags.
  650. * F_SETFL: (libc)Getting File Status Flags.
  651. * F_SETLK: (libc)File Locks.
  652. * F_SETLKW: (libc)File Locks.
  653. * __fsetlocking: (libc)Streams and Threads.
  654. * F_SETOWN: (libc)Interrupt Input.
  655. * fsetpos64: (libc)Portable Positioning.
  656. * fsetpos: (libc)Portable Positioning.
  657. * fstat64: (libc)Reading Attributes.
  658. * fstat: (libc)Reading Attributes.
  659. * fsync: (libc)Synchronizing I/O.
  660. * ftell: (libc)File Positioning.
  661. * ftello64: (libc)File Positioning.
  662. * ftello: (libc)File Positioning.
  663. * ftruncate64: (libc)File Size.
  664. * ftruncate: (libc)File Size.
  665. * ftrylockfile: (libc)Streams and Threads.
  666. * ftw64: (libc)Working with Directory Trees.
  667. * ftw: (libc)Working with Directory Trees.
  668. * funlockfile: (libc)Streams and Threads.
  669. * futimes: (libc)File Times.
  670. * fwide: (libc)Streams and I18N.
  671. * fwprintf: (libc)Formatted Output Functions.
  672. * __fwritable: (libc)Opening Streams.
  673. * fwrite: (libc)Block Input/Output.
  674. * fwrite_unlocked: (libc)Block Input/Output.
  675. * __fwriting: (libc)Opening Streams.
  676. * fwscanf: (libc)Formatted Input Functions.
  677. * gammaf: (libc)Special Functions.
  678. * gamma: (libc)Special Functions.
  679. * gammal: (libc)Special Functions.
  680. * __gconv_end_fct: (libc)glibc iconv Implementation.
  681. * __gconv_fct: (libc)glibc iconv Implementation.
  682. * __gconv_init_fct: (libc)glibc iconv Implementation.
  683. * gcvt: (libc)System V Number Conversion.
  684. * getauxval: (libc)Auxiliary Vector.
  685. * get_avphys_pages: (libc)Query Memory Parameters.
  686. * getchar: (libc)Character Input.
  687. * getchar_unlocked: (libc)Character Input.
  688. * getc: (libc)Character Input.
  689. * getcontext: (libc)System V contexts.
  690. * getc_unlocked: (libc)Character Input.
  691. * get_current_dir_name: (libc)Working Directory.
  692. * getcwd: (libc)Working Directory.
  693. * getdate: (libc)General Time String Parsing.
  694. * getdate_r: (libc)General Time String Parsing.
  695. * getdelim: (libc)Line Input.
  696. * getdomainnname: (libc)Host Identification.
  697. * getegid: (libc)Reading Persona.
  698. * getentropy: (libc)Unpredictable Bytes.
  699. * getenv: (libc)Environment Access.
  700. * geteuid: (libc)Reading Persona.
  701. * getfsent: (libc)fstab.
  702. * getfsfile: (libc)fstab.
  703. * getfsspec: (libc)fstab.
  704. * getgid: (libc)Reading Persona.
  705. * getgrent: (libc)Scanning All Groups.
  706. * getgrent_r: (libc)Scanning All Groups.
  707. * getgrgid: (libc)Lookup Group.
  708. * getgrgid_r: (libc)Lookup Group.
  709. * getgrnam: (libc)Lookup Group.
  710. * getgrnam_r: (libc)Lookup Group.
  711. * getgrouplist: (libc)Setting Groups.
  712. * getgroups: (libc)Reading Persona.
  713. * gethostbyaddr: (libc)Host Names.
  714. * gethostbyaddr_r: (libc)Host Names.
  715. * gethostbyname2: (libc)Host Names.
  716. * gethostbyname2_r: (libc)Host Names.
  717. * gethostbyname: (libc)Host Names.
  718. * gethostbyname_r: (libc)Host Names.
  719. * gethostent: (libc)Host Names.
  720. * gethostid: (libc)Host Identification.
  721. * gethostname: (libc)Host Identification.
  722. * getitimer: (libc)Setting an Alarm.
  723. * getline: (libc)Line Input.
  724. * getloadavg: (libc)Processor Resources.
  725. * getlogin: (libc)Who Logged In.
  726. * getmntent: (libc)mtab.
  727. * getmntent_r: (libc)mtab.
  728. * getnetbyaddr: (libc)Networks Database.
  729. * getnetbyname: (libc)Networks Database.
  730. * getnetent: (libc)Networks Database.
  731. * getnetgrent: (libc)Lookup Netgroup.
  732. * getnetgrent_r: (libc)Lookup Netgroup.
  733. * get_nprocs_conf: (libc)Processor Resources.
  734. * get_nprocs: (libc)Processor Resources.
  735. * getopt: (libc)Using Getopt.
  736. * getopt_long: (libc)Getopt Long Options.
  737. * getopt_long_only: (libc)Getopt Long Options.
  738. * getpagesize: (libc)Query Memory Parameters.
  739. * getpass: (libc)getpass.
  740. * getpayloadf: (libc)FP Bit Twiddling.
  741. * getpayload: (libc)FP Bit Twiddling.
  742. * getpayloadl: (libc)FP Bit Twiddling.
  743. * getpeername: (libc)Who is Connected.
  744. * getpgid: (libc)Process Group Functions.
  745. * getpgrp: (libc)Process Group Functions.
  746. * get_phys_pages: (libc)Query Memory Parameters.
  747. * getpid: (libc)Process Identification.
  748. * getppid: (libc)Process Identification.
  749. * getpriority: (libc)Traditional Scheduling Functions.
  750. * getprotobyname: (libc)Protocols Database.
  751. * getprotobynumber: (libc)Protocols Database.
  752. * getprotoent: (libc)Protocols Database.
  753. * getpt: (libc)Allocation.
  754. * getpwent: (libc)Scanning All Users.
  755. * getpwent_r: (libc)Scanning All Users.
  756. * getpwnam: (libc)Lookup User.
  757. * getpwnam_r: (libc)Lookup User.
  758. * getpwuid: (libc)Lookup User.
  759. * getpwuid_r: (libc)Lookup User.
  760. * getrandom: (libc)Unpredictable Bytes.
  761. * getrlimit64: (libc)Limits on Resources.
  762. * getrlimit: (libc)Limits on Resources.
  763. * getrusage: (libc)Resource Usage.
  764. * getservbyname: (libc)Services Database.
  765. * getservbyport: (libc)Services Database.
  766. * getservent: (libc)Services Database.
  767. * getsid: (libc)Process Group Functions.
  768. * gets: (libc)Line Input.
  769. * getsockname: (libc)Reading Address.
  770. * getsockopt: (libc)Socket Option Functions.
  771. * getsubopt: (libc)Suboptions.
  772. * gettext: (libc)Translation with gettext.
  773. * gettimeofday: (libc)High-Resolution Calendar.
  774. * getuid: (libc)Reading Persona.
  775. * getumask: (libc)Setting Permissions.
  776. * getutent: (libc)Manipulating the Database.
  777. * getutent_r: (libc)Manipulating the Database.
  778. * getutid: (libc)Manipulating the Database.
  779. * getutid_r: (libc)Manipulating the Database.
  780. * getutline: (libc)Manipulating the Database.
  781. * getutline_r: (libc)Manipulating the Database.
  782. * getutmp: (libc)XPG Functions.
  783. * getutmpx: (libc)XPG Functions.
  784. * getutxent: (libc)XPG Functions.
  785. * getutxid: (libc)XPG Functions.
  786. * getutxline: (libc)XPG Functions.
  787. * getwchar: (libc)Character Input.
  788. * getwchar_unlocked: (libc)Character Input.
  789. * getwc: (libc)Character Input.
  790. * getwc_unlocked: (libc)Character Input.
  791. * getwd: (libc)Working Directory.
  792. * getw: (libc)Character Input.
  793. * glob64: (libc)Calling Glob.
  794. * globfree64: (libc)More Flags for Globbing.
  795. * globfree: (libc)More Flags for Globbing.
  796. * glob: (libc)Calling Glob.
  797. * gmtime: (libc)Broken-down Time.
  798. * gmtime_r: (libc)Broken-down Time.
  799. * grantpt: (libc)Allocation.
  800. * gsignal: (libc)Signaling Yourself.
  801. * gtty: (libc)BSD Terminal Modes.
  802. * hasmntopt: (libc)mtab.
  803. * hcreate: (libc)Hash Search Function.
  804. * hcreate_r: (libc)Hash Search Function.
  805. * hdestroy: (libc)Hash Search Function.
  806. * hdestroy_r: (libc)Hash Search Function.
  807. * hsearch: (libc)Hash Search Function.
  808. * hsearch_r: (libc)Hash Search Function.
  809. * htonl: (libc)Byte Order.
  810. * htons: (libc)Byte Order.
  811. * HUGE_VALF: (libc)Math Error Reporting.
  812. * HUGE_VAL: (libc)Math Error Reporting.
  813. * HUGE_VALL: (libc)Math Error Reporting.
  814. * HUPCL: (libc)Control Modes.
  815. * hypotf: (libc)Exponents and Logarithms.
  816. * hypot: (libc)Exponents and Logarithms.
  817. * hypotl: (libc)Exponents and Logarithms.
  818. * ICANON: (libc)Local Modes.
  819. * iconv_close: (libc)Generic Conversion Interface.
  820. * iconv: (libc)Generic Conversion Interface.
  821. * iconv_open: (libc)Generic Conversion Interface.
  822. * ICRNL: (libc)Input Modes.
  823. * IEXTEN: (libc)Local Modes.
  824. * if_freenameindex: (libc)Interface Naming.
  825. * if_indextoname: (libc)Interface Naming.
  826. * if_nameindex: (libc)Interface Naming.
  827. * if_nametoindex: (libc)Interface Naming.
  828. * IFNAMSIZ: (libc)Interface Naming.
  829. * IFTODT: (libc)Directory Entries.
  830. * IGNBRK: (libc)Input Modes.
  831. * IGNCR: (libc)Input Modes.
  832. * IGNPAR: (libc)Input Modes.
  833. * I: (libc)Complex Numbers.
  834. * ilogbf: (libc)Exponents and Logarithms.
  835. * ilogb: (libc)Exponents and Logarithms.
  836. * ilogbl: (libc)Exponents and Logarithms.
  837. * _Imaginary_I: (libc)Complex Numbers.
  838. * imaxabs: (libc)Absolute Value.
  839. * IMAXBEL: (libc)Input Modes.
  840. * imaxdiv: (libc)Integer Division.
  841. * in6addr_any: (libc)Host Address Data Type.
  842. * in6addr_loopback: (libc)Host Address Data Type.
  843. * INADDR_ANY: (libc)Host Address Data Type.
  844. * INADDR_BROADCAST: (libc)Host Address Data Type.
  845. * INADDR_LOOPBACK: (libc)Host Address Data Type.
  846. * INADDR_NONE: (libc)Host Address Data Type.
  847. * index: (libc)Search Functions.
  848. * inet_addr: (libc)Host Address Functions.
  849. * inet_aton: (libc)Host Address Functions.
  850. * inet_lnaof: (libc)Host Address Functions.
  851. * inet_makeaddr: (libc)Host Address Functions.
  852. * inet_netof: (libc)Host Address Functions.
  853. * inet_network: (libc)Host Address Functions.
  854. * inet_ntoa: (libc)Host Address Functions.
  855. * inet_ntop: (libc)Host Address Functions.
  856. * inet_pton: (libc)Host Address Functions.
  857. * INFINITY: (libc)Infinity and NaN.
  858. * initgroups: (libc)Setting Groups.
  859. * initstate: (libc)BSD Random.
  860. * initstate_r: (libc)BSD Random.
  861. * INLCR: (libc)Input Modes.
  862. * innetgr: (libc)Netgroup Membership.
  863. * INPCK: (libc)Input Modes.
  864. * ioctl: (libc)IOCTLs.
  865. * _IOFBF: (libc)Controlling Buffering.
  866. * _IOLBF: (libc)Controlling Buffering.
  867. * _IONBF: (libc)Controlling Buffering.
  868. * IPPORT_RESERVED: (libc)Ports.
  869. * IPPORT_USERRESERVED: (libc)Ports.
  870. * isalnum: (libc)Classification of Characters.
  871. * isalpha: (libc)Classification of Characters.
  872. * isascii: (libc)Classification of Characters.
  873. * isatty: (libc)Is It a Terminal.
  874. * isblank: (libc)Classification of Characters.
  875. * iscanonical: (libc)Floating Point Classes.
  876. * iscntrl: (libc)Classification of Characters.
  877. * isdigit: (libc)Classification of Characters.
  878. * iseqsig: (libc)FP Comparison Functions.
  879. * isfinite: (libc)Floating Point Classes.
  880. * isgraph: (libc)Classification of Characters.
  881. * isgreaterequal: (libc)FP Comparison Functions.
  882. * isgreater: (libc)FP Comparison Functions.
  883. * ISIG: (libc)Local Modes.
  884. * isinff: (libc)Floating Point Classes.
  885. * isinf: (libc)Floating Point Classes.
  886. * isinfl: (libc)Floating Point Classes.
  887. * islessequal: (libc)FP Comparison Functions.
  888. * islessgreater: (libc)FP Comparison Functions.
  889. * isless: (libc)FP Comparison Functions.
  890. * islower: (libc)Classification of Characters.
  891. * isnanf: (libc)Floating Point Classes.
  892. * isnan: (libc)Floating Point Classes.
  893. * isnan: (libc)Floating Point Classes.
  894. * isnanl: (libc)Floating Point Classes.
  895. * isnormal: (libc)Floating Point Classes.
  896. * isprint: (libc)Classification of Characters.
  897. * ispunct: (libc)Classification of Characters.
  898. * issignaling: (libc)Floating Point Classes.
  899. * isspace: (libc)Classification of Characters.
  900. * issubnormal: (libc)Floating Point Classes.
  901. * ISTRIP: (libc)Input Modes.
  902. * isunordered: (libc)FP Comparison Functions.
  903. * isupper: (libc)Classification of Characters.
  904. * iswalnum: (libc)Classification of Wide Characters.
  905. * iswalpha: (libc)Classification of Wide Characters.
  906. * iswblank: (libc)Classification of Wide Characters.
  907. * iswcntrl: (libc)Classification of Wide Characters.
  908. * iswctype: (libc)Classification of Wide Characters.
  909. * iswdigit: (libc)Classification of Wide Characters.
  910. * iswgraph: (libc)Classification of Wide Characters.
  911. * iswlower: (libc)Classification of Wide Characters.
  912. * iswprint: (libc)Classification of Wide Characters.
  913. * iswpunct: (libc)Classification of Wide Characters.
  914. * iswspace: (libc)Classification of Wide Characters.
  915. * iswupper: (libc)Classification of Wide Characters.
  916. * iswxdigit: (libc)Classification of Wide Characters.
  917. * isxdigit: (libc)Classification of Characters.
  918. * iszero: (libc)Floating Point Classes.
  919. * IXANY: (libc)Input Modes.
  920. * IXOFF: (libc)Input Modes.
  921. * IXON: (libc)Input Modes.
  922. * j0f: (libc)Special Functions.
  923. * j0: (libc)Special Functions.
  924. * j0l: (libc)Special Functions.
  925. * j1f: (libc)Special Functions.
  926. * j1: (libc)Special Functions.
  927. * j1l: (libc)Special Functions.
  928. * jnf: (libc)Special Functions.
  929. * jn: (libc)Special Functions.
  930. * jnl: (libc)Special Functions.
  931. * jrand48: (libc)SVID Random.
  932. * jrand48_r: (libc)SVID Random.
  933. * kill: (libc)Signaling Another Process.
  934. * killpg: (libc)Signaling Another Process.
  935. * l64a: (libc)Encode Binary Data.
  936. * labs: (libc)Absolute Value.
  937. * lcong48: (libc)SVID Random.
  938. * lcong48_r: (libc)SVID Random.
  939. * L_ctermid: (libc)Identifying the Terminal.
  940. * L_cuserid: (libc)Who Logged In.
  941. * ldexpf: (libc)Normalization Functions.
  942. * ldexp: (libc)Normalization Functions.
  943. * ldexpl: (libc)Normalization Functions.
  944. * ldiv: (libc)Integer Division.
  945. * lfind: (libc)Array Search Function.
  946. * lgammaf: (libc)Special Functions.
  947. * lgammaf_r: (libc)Special Functions.
  948. * lgamma: (libc)Special Functions.
  949. * lgammal: (libc)Special Functions.
  950. * lgammal_r: (libc)Special Functions.
  951. * lgamma_r: (libc)Special Functions.
  952. * LINE_MAX: (libc)Utility Limits.
  953. * link: (libc)Hard Links.
  954. * LINK_MAX: (libc)Limits for Files.
  955. * lio_listio64: (libc)Asynchronous Reads/Writes.
  956. * lio_listio: (libc)Asynchronous Reads/Writes.
  957. * listen: (libc)Listening.
  958. * llabs: (libc)Absolute Value.
  959. * lldiv: (libc)Integer Division.
  960. * llogbf: (libc)Exponents and Logarithms.
  961. * llogb: (libc)Exponents and Logarithms.
  962. * llogbl: (libc)Exponents and Logarithms.
  963. * llrintf: (libc)Rounding Functions.
  964. * llrint: (libc)Rounding Functions.
  965. * llrintl: (libc)Rounding Functions.
  966. * llroundf: (libc)Rounding Functions.
  967. * llround: (libc)Rounding Functions.
  968. * llroundl: (libc)Rounding Functions.
  969. * localeconv: (libc)The Lame Way to Locale Data.
  970. * localtime: (libc)Broken-down Time.
  971. * localtime_r: (libc)Broken-down Time.
  972. * log10f: (libc)Exponents and Logarithms.
  973. * log10: (libc)Exponents and Logarithms.
  974. * log10l: (libc)Exponents and Logarithms.
  975. * log1pf: (libc)Exponents and Logarithms.
  976. * log1p: (libc)Exponents and Logarithms.
  977. * log1pl: (libc)Exponents and Logarithms.
  978. * log2f: (libc)Exponents and Logarithms.
  979. * log2: (libc)Exponents and Logarithms.
  980. * log2l: (libc)Exponents and Logarithms.
  981. * logbf: (libc)Exponents and Logarithms.
  982. * logb: (libc)Exponents and Logarithms.
  983. * logbl: (libc)Exponents and Logarithms.
  984. * logf: (libc)Exponents and Logarithms.
  985. * login: (libc)Logging In and Out.
  986. * login_tty: (libc)Logging In and Out.
  987. * log: (libc)Exponents and Logarithms.
  988. * logl: (libc)Exponents and Logarithms.
  989. * logout: (libc)Logging In and Out.
  990. * logwtmp: (libc)Logging In and Out.
  991. * longjmp: (libc)Non-Local Details.
  992. * lrand48: (libc)SVID Random.
  993. * lrand48_r: (libc)SVID Random.
  994. * lrintf: (libc)Rounding Functions.
  995. * lrint: (libc)Rounding Functions.
  996. * lrintl: (libc)Rounding Functions.
  997. * lroundf: (libc)Rounding Functions.
  998. * lround: (libc)Rounding Functions.
  999. * lroundl: (libc)Rounding Functions.
  1000. * lsearch: (libc)Array Search Function.
  1001. * lseek64: (libc)File Position Primitive.
  1002. * lseek: (libc)File Position Primitive.
  1003. * lstat64: (libc)Reading Attributes.
  1004. * lstat: (libc)Reading Attributes.
  1005. * L_tmpnam: (libc)Temporary Files.
  1006. * lutimes: (libc)File Times.
  1007. * madvise: (libc)Memory-mapped I/O.
  1008. * makecontext: (libc)System V contexts.
  1009. * mallinfo: (libc)Statistics of Malloc.
  1010. * malloc: (libc)Basic Allocation.
  1011. * mallopt: (libc)Malloc Tunable Parameters.
  1012. * MAX_CANON: (libc)Limits for Files.
  1013. * MAX_INPUT: (libc)Limits for Files.
  1014. * MAXNAMLEN: (libc)Limits for Files.
  1015. * MAXSYMLINKS: (libc)Symbolic Links.
  1016. * MB_CUR_MAX: (libc)Selecting the Conversion.
  1017. * mblen: (libc)Non-reentrant Character Conversion.
  1018. * MB_LEN_MAX: (libc)Selecting the Conversion.
  1019. * mbrlen: (libc)Converting a Character.
  1020. * mbrtowc: (libc)Converting a Character.
  1021. * mbsinit: (libc)Keeping the state.
  1022. * mbsnrtowcs: (libc)Converting Strings.
  1023. * mbsrtowcs: (libc)Converting Strings.
  1024. * mbstowcs: (libc)Non-reentrant String Conversion.
  1025. * mbtowc: (libc)Non-reentrant Character Conversion.
  1026. * mcheck: (libc)Heap Consistency Checking.
  1027. * MDMBUF: (libc)Control Modes.
  1028. * memalign: (libc)Aligned Memory Blocks.
  1029. * memccpy: (libc)Copying Strings and Arrays.
  1030. * memchr: (libc)Search Functions.
  1031. * memcmp: (libc)String/Array Comparison.
  1032. * memcpy: (libc)Copying Strings and Arrays.
  1033. * memfrob: (libc)Trivial Encryption.
  1034. * memmem: (libc)Search Functions.
  1035. * memmove: (libc)Copying Strings and Arrays.
  1036. * mempcpy: (libc)Copying Strings and Arrays.
  1037. * memrchr: (libc)Search Functions.
  1038. * memset: (libc)Copying Strings and Arrays.
  1039. * mkdir: (libc)Creating Directories.
  1040. * mkdtemp: (libc)Temporary Files.
  1041. * mkfifo: (libc)FIFO Special Files.
  1042. * mknod: (libc)Making Special Files.
  1043. * mkstemp: (libc)Temporary Files.
  1044. * mktemp: (libc)Temporary Files.
  1045. * mktime: (libc)Broken-down Time.
  1046. * mlockall: (libc)Page Lock Functions.
  1047. * mlock: (libc)Page Lock Functions.
  1048. * mmap64: (libc)Memory-mapped I/O.
  1049. * mmap: (libc)Memory-mapped I/O.
  1050. * modff: (libc)Rounding Functions.
  1051. * modf: (libc)Rounding Functions.
  1052. * modfl: (libc)Rounding Functions.
  1053. * mount: (libc)Mount-Unmount-Remount.
  1054. * mprobe: (libc)Heap Consistency Checking.
  1055. * mrand48: (libc)SVID Random.
  1056. * mrand48_r: (libc)SVID Random.
  1057. * mremap: (libc)Memory-mapped I/O.
  1058. * MSG_DONTROUTE: (libc)Socket Data Options.
  1059. * MSG_OOB: (libc)Socket Data Options.
  1060. * MSG_PEEK: (libc)Socket Data Options.
  1061. * msync: (libc)Memory-mapped I/O.
  1062. * mtrace: (libc)Tracing malloc.
  1063. * munlockall: (libc)Page Lock Functions.
  1064. * munlock: (libc)Page Lock Functions.
  1065. * munmap: (libc)Memory-mapped I/O.
  1066. * muntrace: (libc)Tracing malloc.
  1067. * NAME_MAX: (libc)Limits for Files.
  1068. * nanf: (libc)FP Bit Twiddling.
  1069. * nan: (libc)FP Bit Twiddling.
  1070. * NAN: (libc)Infinity and NaN.
  1071. * nanl: (libc)FP Bit Twiddling.
  1072. * nanosleep: (libc)Sleeping.
  1073. * NCCS: (libc)Mode Data Types.
  1074. * nearbyintf: (libc)Rounding Functions.
  1075. * nearbyint: (libc)Rounding Functions.
  1076. * nearbyintl: (libc)Rounding Functions.
  1077. * nextafterf: (libc)FP Bit Twiddling.
  1078. * nextafter: (libc)FP Bit Twiddling.
  1079. * nextafterl: (libc)FP Bit Twiddling.
  1080. * nextdownf: (libc)FP Bit Twiddling.
  1081. * nextdown: (libc)FP Bit Twiddling.
  1082. * nextdownl: (libc)FP Bit Twiddling.
  1083. * nexttowardf: (libc)FP Bit Twiddling.
  1084. * nexttoward: (libc)FP Bit Twiddling.
  1085. * nexttowardl: (libc)FP Bit Twiddling.
  1086. * nextupf: (libc)FP Bit Twiddling.
  1087. * nextup: (libc)FP Bit Twiddling.
  1088. * nextupl: (libc)FP Bit Twiddling.
  1089. * nftw64: (libc)Working with Directory Trees.
  1090. * nftw: (libc)Working with Directory Trees.
  1091. * ngettext: (libc)Advanced gettext functions.
  1092. * NGROUPS_MAX: (libc)General Limits.
  1093. * nice: (libc)Traditional Scheduling Functions.
  1094. * nl_langinfo: (libc)The Elegant and Fast Way.
  1095. * NOFLSH: (libc)Local Modes.
  1096. * NOKERNINFO: (libc)Local Modes.
  1097. * nrand48: (libc)SVID Random.
  1098. * nrand48_r: (libc)SVID Random.
  1099. * NSIG: (libc)Standard Signals.
  1100. * ntohl: (libc)Byte Order.
  1101. * ntohs: (libc)Byte Order.
  1102. * ntp_adjtime: (libc)High Accuracy Clock.
  1103. * ntp_gettime: (libc)High Accuracy Clock.
  1104. * NULL: (libc)Null Pointer Constant.
  1105. * O_ACCMODE: (libc)Access Modes.
  1106. * O_APPEND: (libc)Operating Modes.
  1107. * O_ASYNC: (libc)Operating Modes.
  1108. * obstack_1grow_fast: (libc)Extra Fast Growing.
  1109. * obstack_1grow: (libc)Growing Objects.
  1110. * obstack_alignment_mask: (libc)Obstacks Data Alignment.
  1111. * obstack_alloc: (libc)Allocation in an Obstack.
  1112. * obstack_base: (libc)Status of an Obstack.
  1113. * obstack_blank_fast: (libc)Extra Fast Growing.
  1114. * obstack_blank: (libc)Growing Objects.
  1115. * obstack_chunk_size: (libc)Obstack Chunks.
  1116. * obstack_copy0: (libc)Allocation in an Obstack.
  1117. * obstack_copy: (libc)Allocation in an Obstack.
  1118. * obstack_finish: (libc)Growing Objects.
  1119. * obstack_free: (libc)Freeing Obstack Objects.
  1120. * obstack_grow0: (libc)Growing Objects.
  1121. * obstack_grow: (libc)Growing Objects.
  1122. * obstack_init: (libc)Preparing for Obstacks.
  1123. * obstack_int_grow_fast: (libc)Extra Fast Growing.
  1124. * obstack_int_grow: (libc)Growing Objects.
  1125. * obstack_next_free: (libc)Status of an Obstack.
  1126. * obstack_object_size: (libc)Growing Objects.
  1127. * obstack_object_size: (libc)Status of an Obstack.
  1128. * obstack_printf: (libc)Dynamic Output.
  1129. * obstack_ptr_grow_fast: (libc)Extra Fast Growing.
  1130. * obstack_ptr_grow: (libc)Growing Objects.
  1131. * obstack_room: (libc)Extra Fast Growing.
  1132. * obstack_vprintf: (libc)Variable Arguments Output.
  1133. * O_CREAT: (libc)Open-time Flags.
  1134. * O_EXCL: (libc)Open-time Flags.
  1135. * O_EXEC: (libc)Access Modes.
  1136. * O_EXLOCK: (libc)Open-time Flags.
  1137. * offsetof: (libc)Structure Measurement.
  1138. * O_FSYNC: (libc)Operating Modes.
  1139. * O_IGNORE_CTTY: (libc)Open-time Flags.
  1140. * O_NDELAY: (libc)Operating Modes.
  1141. * on_exit: (libc)Cleanups on Exit.
  1142. * ONLCR: (libc)Output Modes.
  1143. * O_NOATIME: (libc)Operating Modes.
  1144. * O_NOCTTY: (libc)Open-time Flags.
  1145. * ONOEOT: (libc)Output Modes.
  1146. * O_NOLINK: (libc)Open-time Flags.
  1147. * O_NONBLOCK: (libc)Open-time Flags.
  1148. * O_NONBLOCK: (libc)Operating Modes.
  1149. * O_NOTRANS: (libc)Open-time Flags.
  1150. * open64: (libc)Opening and Closing Files.
  1151. * opendir: (libc)Opening a Directory.
  1152. * open: (libc)Opening and Closing Files.
  1153. * openlog: (libc)openlog.
  1154. * OPEN_MAX: (libc)General Limits.
  1155. * open_memstream: (libc)String Streams.
  1156. * openpty: (libc)Pseudo-Terminal Pairs.
  1157. * OPOST: (libc)Output Modes.
  1158. * O_RDONLY: (libc)Access Modes.
  1159. * O_RDWR: (libc)Access Modes.
  1160. * O_READ: (libc)Access Modes.
  1161. * O_SHLOCK: (libc)Open-time Flags.
  1162. * O_SYNC: (libc)Operating Modes.
  1163. * O_TRUNC: (libc)Open-time Flags.
  1164. * O_WRITE: (libc)Access Modes.
  1165. * O_WRONLY: (libc)Access Modes.
  1166. * OXTABS: (libc)Output Modes.
  1167. * PA_FLAG_MASK: (libc)Parsing a Template String.
  1168. * PARENB: (libc)Control Modes.
  1169. * PARMRK: (libc)Input Modes.
  1170. * PARODD: (libc)Control Modes.
  1171. * parse_printf_format: (libc)Parsing a Template String.
  1172. * pathconf: (libc)Pathconf.
  1173. * PATH_MAX: (libc)Limits for Files.
  1174. * _PATH_UTMP: (libc)Manipulating the Database.
  1175. * _PATH_WTMP: (libc)Manipulating the Database.
  1176. * pause: (libc)Using Pause.
  1177. * pclose: (libc)Pipe to a Subprocess.
  1178. * PENDIN: (libc)Local Modes.
  1179. * perror: (libc)Error Messages.
  1180. * PF_FILE: (libc)Local Namespace Details.
  1181. * PF_INET6: (libc)Internet Namespace.
  1182. * PF_INET: (libc)Internet Namespace.
  1183. * PF_LOCAL: (libc)Local Namespace Details.
  1184. * PF_UNIX: (libc)Local Namespace Details.
  1185. * PIPE_BUF: (libc)Limits for Files.
  1186. * pipe: (libc)Creating a Pipe.
  1187. * popen: (libc)Pipe to a Subprocess.
  1188. * _POSIX2_C_DEV: (libc)System Options.
  1189. * _POSIX2_C_VERSION: (libc)Version Supported.
  1190. * _POSIX2_FORT_DEV: (libc)System Options.
  1191. * _POSIX2_FORT_RUN: (libc)System Options.
  1192. * _POSIX2_LOCALEDEF: (libc)System Options.
  1193. * _POSIX2_SW_DEV: (libc)System Options.
  1194. * _POSIX_CHOWN_RESTRICTED: (libc)Options for Files.
  1195. * posix_fallocate64: (libc)Storage Allocation.
  1196. * posix_fallocate: (libc)Storage Allocation.
  1197. * _POSIX_JOB_CONTROL: (libc)System Options.
  1198. * posix_memalign: (libc)Aligned Memory Blocks.
  1199. * _POSIX_NO_TRUNC: (libc)Options for Files.
  1200. * _POSIX_SAVED_IDS: (libc)System Options.
  1201. * _POSIX_VDISABLE: (libc)Options for Files.
  1202. * _POSIX_VERSION: (libc)Version Supported.
  1203. * pow10f: (libc)Exponents and Logarithms.
  1204. * pow10: (libc)Exponents and Logarithms.
  1205. * pow10l: (libc)Exponents and Logarithms.
  1206. * powf: (libc)Exponents and Logarithms.
  1207. * pow: (libc)Exponents and Logarithms.
  1208. * powl: (libc)Exponents and Logarithms.
  1209. * __ppc_get_timebase_freq: (libc)PowerPC.
  1210. * __ppc_get_timebase: (libc)PowerPC.
  1211. * __ppc_mdoio: (libc)PowerPC.
  1212. * __ppc_mdoom: (libc)PowerPC.
  1213. * __ppc_set_ppr_low: (libc)PowerPC.
  1214. * __ppc_set_ppr_med_high: (libc)PowerPC.
  1215. * __ppc_set_ppr_med: (libc)PowerPC.
  1216. * __ppc_set_ppr_med_low: (libc)PowerPC.
  1217. * __ppc_set_ppr_very_low: (libc)PowerPC.
  1218. * __ppc_yield: (libc)PowerPC.
  1219. * pread64: (libc)I/O Primitives.
  1220. * pread: (libc)I/O Primitives.
  1221. * printf: (libc)Formatted Output Functions.
  1222. * printf_size_info: (libc)Predefined Printf Handlers.
  1223. * printf_size: (libc)Predefined Printf Handlers.
  1224. * psignal: (libc)Signal Messages.
  1225. * pthread_getattr_default_np: (libc)Default Thread Attributes.
  1226. * pthread_getspecific: (libc)Thread-specific Data.
  1227. * pthread_key_create: (libc)Thread-specific Data.
  1228. * pthread_key_delete: (libc)Thread-specific Data.
  1229. * pthread_setattr_default_np: (libc)Default Thread Attributes.
  1230. * pthread_setspecific: (libc)Thread-specific Data.
  1231. * P_tmpdir: (libc)Temporary Files.
  1232. * ptsname: (libc)Allocation.
  1233. * ptsname_r: (libc)Allocation.
  1234. * putchar: (libc)Simple Output.
  1235. * putchar_unlocked: (libc)Simple Output.
  1236. * putc: (libc)Simple Output.
  1237. * putc_unlocked: (libc)Simple Output.
  1238. * putenv: (libc)Environment Access.
  1239. * putpwent: (libc)Writing a User Entry.
  1240. * puts: (libc)Simple Output.
  1241. * pututline: (libc)Manipulating the Database.
  1242. * pututxline: (libc)XPG Functions.
  1243. * putwchar: (libc)Simple Output.
  1244. * putwchar_unlocked: (libc)Simple Output.
  1245. * putwc: (libc)Simple Output.
  1246. * putwc_unlocked: (libc)Simple Output.
  1247. * putw: (libc)Simple Output.
  1248. * pwrite64: (libc)I/O Primitives.
  1249. * pwrite: (libc)I/O Primitives.
  1250. * qecvt: (libc)System V Number Conversion.
  1251. * qecvt_r: (libc)System V Number Conversion.
  1252. * qfcvt: (libc)System V Number Conversion.
  1253. * qfcvt_r: (libc)System V Number Conversion.
  1254. * qgcvt: (libc)System V Number Conversion.
  1255. * qsort: (libc)Array Sort Function.
  1256. * raise: (libc)Signaling Yourself.
  1257. * rand: (libc)ISO Random.
  1258. * RAND_MAX: (libc)ISO Random.
  1259. * random: (libc)BSD Random.
  1260. * random_r: (libc)BSD Random.
  1261. * rand_r: (libc)ISO Random.
  1262. * rawmemchr: (libc)Search Functions.
  1263. * readdir64: (libc)Reading/Closing Directory.
  1264. * readdir64_r: (libc)Reading/Closing Directory.
  1265. * readdir: (libc)Reading/Closing Directory.
  1266. * readdir_r: (libc)Reading/Closing Directory.
  1267. * read: (libc)I/O Primitives.
  1268. * readlink: (libc)Symbolic Links.
  1269. * readv: (libc)Scatter-Gather.
  1270. * realloc: (libc)Changing Block Size.
  1271. * realpath: (libc)Symbolic Links.
  1272. * recvfrom: (libc)Receiving Datagrams.
  1273. * recv: (libc)Receiving Data.
  1274. * recvmsg: (libc)Receiving Datagrams.
  1275. * RE_DUP_MAX: (libc)General Limits.
  1276. * regcomp: (libc)POSIX Regexp Compilation.
  1277. * regerror: (libc)Regexp Cleanup.
  1278. * regexec: (libc)Matching POSIX Regexps.
  1279. * regfree: (libc)Regexp Cleanup.
  1280. * register_printf_function: (libc)Registering New Conversions.
  1281. * remainderf: (libc)Remainder Functions.
  1282. * remainder: (libc)Remainder Functions.
  1283. * remainderl: (libc)Remainder Functions.
  1284. * remove: (libc)Deleting Files.
  1285. * rename: (libc)Renaming Files.
  1286. * rewinddir: (libc)Random Access Directory.
  1287. * rewind: (libc)File Positioning.
  1288. * rindex: (libc)Search Functions.
  1289. * rintf: (libc)Rounding Functions.
  1290. * rint: (libc)Rounding Functions.
  1291. * rintl: (libc)Rounding Functions.
  1292. * RLIM_INFINITY: (libc)Limits on Resources.
  1293. * rmdir: (libc)Deleting Files.
  1294. * R_OK: (libc)Testing File Access.
  1295. * roundevenf: (libc)Rounding Functions.
  1296. * roundeven: (libc)Rounding Functions.
  1297. * roundevenl: (libc)Rounding Functions.
  1298. * roundf: (libc)Rounding Functions.
  1299. * round: (libc)Rounding Functions.
  1300. * roundl: (libc)Rounding Functions.
  1301. * rpmatch: (libc)Yes-or-No Questions.
  1302. * SA_NOCLDSTOP: (libc)Flags for Sigaction.
  1303. * SA_ONSTACK: (libc)Flags for Sigaction.
  1304. * SA_RESTART: (libc)Flags for Sigaction.
  1305. * sbrk: (libc)Resizing the Data Segment.
  1306. * scalbf: (libc)Normalization Functions.
  1307. * scalb: (libc)Normalization Functions.
  1308. * scalbl: (libc)Normalization Functions.
  1309. * scalblnf: (libc)Normalization Functions.
  1310. * scalbln: (libc)Normalization Functions.
  1311. * scalblnl: (libc)Normalization Functions.
  1312. * scalbnf: (libc)Normalization Functions.
  1313. * scalbn: (libc)Normalization Functions.
  1314. * scalbnl: (libc)Normalization Functions.
  1315. * scandir64: (libc)Scanning Directory Content.
  1316. * scandir: (libc)Scanning Directory Content.
  1317. * scanf: (libc)Formatted Input Functions.
  1318. * sched_getaffinity: (libc)CPU Affinity.
  1319. * sched_getparam: (libc)Basic Scheduling Functions.
  1320. * sched_get_priority_max: (libc)Basic Scheduling Functions.
  1321. * sched_get_priority_min: (libc)Basic Scheduling Functions.
  1322. * sched_getscheduler: (libc)Basic Scheduling Functions.
  1323. * sched_rr_get_interval: (libc)Basic Scheduling Functions.
  1324. * sched_setaffinity: (libc)CPU Affinity.
  1325. * sched_setparam: (libc)Basic Scheduling Functions.
  1326. * sched_setscheduler: (libc)Basic Scheduling Functions.
  1327. * sched_yield: (libc)Basic Scheduling Functions.
  1328. * secure_getenv: (libc)Environment Access.
  1329. * seed48: (libc)SVID Random.
  1330. * seed48_r: (libc)SVID Random.
  1331. * SEEK_CUR: (libc)File Positioning.
  1332. * seekdir: (libc)Random Access Directory.
  1333. * SEEK_END: (libc)File Positioning.
  1334. * SEEK_SET: (libc)File Positioning.
  1335. * select: (libc)Waiting for I/O.
  1336. * sem_close: (libc)Semaphores.
  1337. * semctl: (libc)Semaphores.
  1338. * sem_destroy: (libc)Semaphores.
  1339. * semget: (libc)Semaphores.
  1340. * sem_getvalue: (libc)Semaphores.
  1341. * sem_init: (libc)Semaphores.
  1342. * sem_open: (libc)Semaphores.
  1343. * semop: (libc)Semaphores.
  1344. * sem_post: (libc)Semaphores.
  1345. * semtimedop: (libc)Semaphores.
  1346. * sem_timedwait: (libc)Semaphores.
  1347. * sem_trywait: (libc)Semaphores.
  1348. * sem_unlink: (libc)Semaphores.
  1349. * sem_wait: (libc)Semaphores.
  1350. * send: (libc)Sending Data.
  1351. * sendmsg: (libc)Receiving Datagrams.
  1352. * sendto: (libc)Sending Datagrams.
  1353. * setbuffer: (libc)Controlling Buffering.
  1354. * setbuf: (libc)Controlling Buffering.
  1355. * setcontext: (libc)System V contexts.
  1356. * setdomainname: (libc)Host Identification.
  1357. * setegid: (libc)Setting Groups.
  1358. * setenv: (libc)Environment Access.
  1359. * seteuid: (libc)Setting User ID.
  1360. * setfsent: (libc)fstab.
  1361. * setgid: (libc)Setting Groups.
  1362. * setgrent: (libc)Scanning All Groups.
  1363. * setgroups: (libc)Setting Groups.
  1364. * sethostent: (libc)Host Names.
  1365. * sethostid: (libc)Host Identification.
  1366. * sethostname: (libc)Host Identification.
  1367. * setitimer: (libc)Setting an Alarm.
  1368. * setjmp: (libc)Non-Local Details.
  1369. * setkey: (libc)DES Encryption.
  1370. * setkey_r: (libc)DES Encryption.
  1371. * setlinebuf: (libc)Controlling Buffering.
  1372. * setlocale: (libc)Setting the Locale.
  1373. * setlogmask: (libc)setlogmask.
  1374. * setmntent: (libc)mtab.
  1375. * setnetent: (libc)Networks Database.
  1376. * setnetgrent: (libc)Lookup Netgroup.
  1377. * setpayloadf: (libc)FP Bit Twiddling.
  1378. * setpayload: (libc)FP Bit Twiddling.
  1379. * setpayloadl: (libc)FP Bit Twiddling.
  1380. * setpayloadsigf: (libc)FP Bit Twiddling.
  1381. * setpayloadsig: (libc)FP Bit Twiddling.
  1382. * setpayloadsigl: (libc)FP Bit Twiddling.
  1383. * setpgid: (libc)Process Group Functions.
  1384. * setpgrp: (libc)Process Group Functions.
  1385. * setpriority: (libc)Traditional Scheduling Functions.
  1386. * setprotoent: (libc)Protocols Database.
  1387. * setpwent: (libc)Scanning All Users.
  1388. * setregid: (libc)Setting Groups.
  1389. * setreuid: (libc)Setting User ID.
  1390. * setrlimit64: (libc)Limits on Resources.
  1391. * setrlimit: (libc)Limits on Resources.
  1392. * setservent: (libc)Services Database.
  1393. * setsid: (libc)Process Group Functions.
  1394. * setsockopt: (libc)Socket Option Functions.
  1395. * setstate: (libc)BSD Random.
  1396. * setstate_r: (libc)BSD Random.
  1397. * settimeofday: (libc)High-Resolution Calendar.
  1398. * setuid: (libc)Setting User ID.
  1399. * setutent: (libc)Manipulating the Database.
  1400. * setutxent: (libc)XPG Functions.
  1401. * setvbuf: (libc)Controlling Buffering.
  1402. * shm_open: (libc)Memory-mapped I/O.
  1403. * shm_unlink: (libc)Memory-mapped I/O.
  1404. * shutdown: (libc)Closing a Socket.
  1405. * S_IFMT: (libc)Testing File Type.
  1406. * SIGABRT: (libc)Program Error Signals.
  1407. * sigaction: (libc)Advanced Signal Handling.
  1408. * sigaddset: (libc)Signal Sets.
  1409. * SIGALRM: (libc)Alarm Signals.
  1410. * sigaltstack: (libc)Signal Stack.
  1411. * sigblock: (libc)BSD Signal Handling.
  1412. * SIGBUS: (libc)Program Error Signals.
  1413. * SIGCHLD: (libc)Job Control Signals.
  1414. * SIGCLD: (libc)Job Control Signals.
  1415. * SIGCONT: (libc)Job Control Signals.
  1416. * sigdelset: (libc)Signal Sets.
  1417. * sigemptyset: (libc)Signal Sets.
  1418. * SIGEMT: (libc)Program Error Signals.
  1419. * SIG_ERR: (libc)Basic Signal Handling.
  1420. * sigfillset: (libc)Signal Sets.
  1421. * SIGFPE: (libc)Program Error Signals.
  1422. * SIGHUP: (libc)Termination Signals.
  1423. * SIGILL: (libc)Program Error Signals.
  1424. * SIGINFO: (libc)Miscellaneous Signals.
  1425. * siginterrupt: (libc)BSD Signal Handling.
  1426. * SIGINT: (libc)Termination Signals.
  1427. * SIGIO: (libc)Asynchronous I/O Signals.
  1428. * SIGIOT: (libc)Program Error Signals.
  1429. * sigismember: (libc)Signal Sets.
  1430. * SIGKILL: (libc)Termination Signals.
  1431. * siglongjmp: (libc)Non-Local Exits and Signals.
  1432. * SIGLOST: (libc)Operation Error Signals.
  1433. * sigmask: (libc)BSD Signal Handling.
  1434. * signal: (libc)Basic Signal Handling.
  1435. * signbit: (libc)FP Bit Twiddling.
  1436. * significandf: (libc)Normalization Functions.
  1437. * significand: (libc)Normalization Functions.
  1438. * significandl: (libc)Normalization Functions.
  1439. * sigpause: (libc)BSD Signal Handling.
  1440. * sigpending: (libc)Checking for Pending Signals.
  1441. * SIGPIPE: (libc)Operation Error Signals.
  1442. * SIGPOLL: (libc)Asynchronous I/O Signals.
  1443. * sigprocmask: (libc)Process Signal Mask.
  1444. * SIGPROF: (libc)Alarm Signals.
  1445. * SIGQUIT: (libc)Termination Signals.
  1446. * SIGSEGV: (libc)Program Error Signals.
  1447. * sigsetjmp: (libc)Non-Local Exits and Signals.
  1448. * sigsetmask: (libc)BSD Signal Handling.
  1449. * sigstack: (libc)Signal Stack.
  1450. * SIGSTOP: (libc)Job Control Signals.
  1451. * sigsuspend: (libc)Sigsuspend.
  1452. * SIGSYS: (libc)Program Error Signals.
  1453. * SIGTERM: (libc)Termination Signals.
  1454. * SIGTRAP: (libc)Program Error Signals.
  1455. * SIGTSTP: (libc)Job Control Signals.
  1456. * SIGTTIN: (libc)Job Control Signals.
  1457. * SIGTTOU: (libc)Job Control Signals.
  1458. * SIGURG: (libc)Asynchronous I/O Signals.
  1459. * SIGUSR1: (libc)Miscellaneous Signals.
  1460. * SIGUSR2: (libc)Miscellaneous Signals.
  1461. * SIGVTALRM: (libc)Alarm Signals.
  1462. * SIGWINCH: (libc)Miscellaneous Signals.
  1463. * SIGXCPU: (libc)Operation Error Signals.
  1464. * SIGXFSZ: (libc)Operation Error Signals.
  1465. * sincosf: (libc)Trig Functions.
  1466. * sincos: (libc)Trig Functions.
  1467. * sincosl: (libc)Trig Functions.
  1468. * sinf: (libc)Trig Functions.
  1469. * sinhf: (libc)Hyperbolic Functions.
  1470. * sinh: (libc)Hyperbolic Functions.
  1471. * sinhl: (libc)Hyperbolic Functions.
  1472. * sin: (libc)Trig Functions.
  1473. * sinl: (libc)Trig Functions.
  1474. * S_ISBLK: (libc)Testing File Type.
  1475. * S_ISCHR: (libc)Testing File Type.
  1476. * S_ISDIR: (libc)Testing File Type.
  1477. * S_ISFIFO: (libc)Testing File Type.
  1478. * S_ISLNK: (libc)Testing File Type.
  1479. * S_ISREG: (libc)Testing File Type.
  1480. * S_ISSOCK: (libc)Testing File Type.
  1481. * sleep: (libc)Sleeping.
  1482. * SNANF: (libc)Infinity and NaN.
  1483. * SNAN: (libc)Infinity and NaN.
  1484. * SNANL: (libc)Infinity and NaN.
  1485. * snprintf: (libc)Formatted Output Functions.
  1486. * SOCK_DGRAM: (libc)Communication Styles.
  1487. * socket: (libc)Creating a Socket.
  1488. * socketpair: (libc)Socket Pairs.
  1489. * SOCK_RAW: (libc)Communication Styles.
  1490. * SOCK_RDM: (libc)Communication Styles.
  1491. * SOCK_SEQPACKET: (libc)Communication Styles.
  1492. * SOCK_STREAM: (libc)Communication Styles.
  1493. * SOL_SOCKET: (libc)Socket-Level Options.
  1494. * sprintf: (libc)Formatted Output Functions.
  1495. * sqrtf: (libc)Exponents and Logarithms.
  1496. * sqrt: (libc)Exponents and Logarithms.
  1497. * sqrtl: (libc)Exponents and Logarithms.
  1498. * srand48: (libc)SVID Random.
  1499. * srand48_r: (libc)SVID Random.
  1500. * srand: (libc)ISO Random.
  1501. * srandom: (libc)BSD Random.
  1502. * srandom_r: (libc)BSD Random.
  1503. * sscanf: (libc)Formatted Input Functions.
  1504. * ssignal: (libc)Basic Signal Handling.
  1505. * SSIZE_MAX: (libc)General Limits.
  1506. * stat64: (libc)Reading Attributes.
  1507. * stat: (libc)Reading Attributes.
  1508. * stime: (libc)Simple Calendar Time.
  1509. * stpcpy: (libc)Copying Strings and Arrays.
  1510. * stpncpy: (libc)Truncating Strings.
  1511. * strcasecmp: (libc)String/Array Comparison.
  1512. * strcasestr: (libc)Search Functions.
  1513. * strcat: (libc)Concatenating Strings.
  1514. * strchr: (libc)Search Functions.
  1515. * strchrnul: (libc)Search Functions.
  1516. * strcmp: (libc)String/Array Comparison.
  1517. * strcoll: (libc)Collation Functions.
  1518. * strcpy: (libc)Copying Strings and Arrays.
  1519. * strcspn: (libc)Search Functions.
  1520. * strdupa: (libc)Copying Strings and Arrays.
  1521. * strdup: (libc)Copying Strings and Arrays.
  1522. * STREAM_MAX: (libc)General Limits.
  1523. * strerror: (libc)Error Messages.
  1524. * strerror_r: (libc)Error Messages.
  1525. * strfmon: (libc)Formatting Numbers.
  1526. * strfromd: (libc)Printing of Floats.
  1527. * strfromf: (libc)Printing of Floats.
  1528. * strfroml: (libc)Printing of Floats.
  1529. * strfry: (libc)strfry.
  1530. * strftime: (libc)Formatting Calendar Time.
  1531. * strlen: (libc)String Length.
  1532. * strncasecmp: (libc)String/Array Comparison.
  1533. * strncat: (libc)Truncating Strings.
  1534. * strncmp: (libc)String/Array Comparison.
  1535. * strncpy: (libc)Truncating Strings.
  1536. * strndupa: (libc)Truncating Strings.
  1537. * strndup: (libc)Truncating Strings.
  1538. * strnlen: (libc)String Length.
  1539. * strpbrk: (libc)Search Functions.
  1540. * strptime: (libc)Low-Level Time String Parsing.
  1541. * strrchr: (libc)Search Functions.
  1542. * strsep: (libc)Finding Tokens in a String.
  1543. * strsignal: (libc)Signal Messages.
  1544. * strspn: (libc)Search Functions.
  1545. * strstr: (libc)Search Functions.
  1546. * strtod: (libc)Parsing of Floats.
  1547. * strtof: (libc)Parsing of Floats.
  1548. * strtoimax: (libc)Parsing of Integers.
  1549. * strtok: (libc)Finding Tokens in a String.
  1550. * strtok_r: (libc)Finding Tokens in a String.
  1551. * strtold: (libc)Parsing of Floats.
  1552. * strtol: (libc)Parsing of Integers.
  1553. * strtoll: (libc)Parsing of Integers.
  1554. * strtoq: (libc)Parsing of Integers.
  1555. * strtoul: (libc)Parsing of Integers.
  1556. * strtoull: (libc)Parsing of Integers.
  1557. * strtoumax: (libc)Parsing of Integers.
  1558. * strtouq: (libc)Parsing of Integers.
  1559. * strverscmp: (libc)String/Array Comparison.
  1560. * strxfrm: (libc)Collation Functions.
  1561. * stty: (libc)BSD Terminal Modes.
  1562. * S_TYPEISMQ: (libc)Testing File Type.
  1563. * S_TYPEISSEM: (libc)Testing File Type.
  1564. * S_TYPEISSHM: (libc)Testing File Type.
  1565. * SUN_LEN: (libc)Local Namespace Details.
  1566. * swapcontext: (libc)System V contexts.
  1567. * swprintf: (libc)Formatted Output Functions.
  1568. * swscanf: (libc)Formatted Input Functions.
  1569. * symlink: (libc)Symbolic Links.
  1570. * sync: (libc)Synchronizing I/O.
  1571. * syscall: (libc)System Calls.
  1572. * sysconf: (libc)Sysconf Definition.
  1573. * sysctl: (libc)System Parameters.
  1574. * syslog: (libc)syslog; vsyslog.
  1575. * system: (libc)Running a Command.
  1576. * sysv_signal: (libc)Basic Signal Handling.
  1577. * tanf: (libc)Trig Functions.
  1578. * tanhf: (libc)Hyperbolic Functions.
  1579. * tanh: (libc)Hyperbolic Functions.
  1580. * tanhl: (libc)Hyperbolic Functions.
  1581. * tan: (libc)Trig Functions.
  1582. * tanl: (libc)Trig Functions.
  1583. * tcdrain: (libc)Line Control.
  1584. * tcflow: (libc)Line Control.
  1585. * tcflush: (libc)Line Control.
  1586. * tcgetattr: (libc)Mode Functions.
  1587. * tcgetpgrp: (libc)Terminal Access Functions.
  1588. * tcgetsid: (libc)Terminal Access Functions.
  1589. * tcsendbreak: (libc)Line Control.
  1590. * tcsetattr: (libc)Mode Functions.
  1591. * tcsetpgrp: (libc)Terminal Access Functions.
  1592. * tdelete: (libc)Tree Search Function.
  1593. * tdestroy: (libc)Tree Search Function.
  1594. * telldir: (libc)Random Access Directory.
  1595. * tempnam: (libc)Temporary Files.
  1596. * textdomain: (libc)Locating gettext catalog.
  1597. * tfind: (libc)Tree Search Function.
  1598. * tgammaf: (libc)Special Functions.
  1599. * tgamma: (libc)Special Functions.
  1600. * tgammal: (libc)Special Functions.
  1601. * timegm: (libc)Broken-down Time.
  1602. * time: (libc)Simple Calendar Time.
  1603. * timelocal: (libc)Broken-down Time.
  1604. * times: (libc)Processor Time.
  1605. * tmpfile64: (libc)Temporary Files.
  1606. * tmpfile: (libc)Temporary Files.
  1607. * TMP_MAX: (libc)Temporary Files.
  1608. * tmpnam: (libc)Temporary Files.
  1609. * tmpnam_r: (libc)Temporary Files.
  1610. * toascii: (libc)Case Conversion.
  1611. * _tolower: (libc)Case Conversion.
  1612. * tolower: (libc)Case Conversion.
  1613. * TOSTOP: (libc)Local Modes.
  1614. * totalorderf: (libc)FP Comparison Functions.
  1615. * totalorder: (libc)FP Comparison Functions.
  1616. * totalorderl: (libc)FP Comparison Functions.
  1617. * totalordermagf: (libc)FP Comparison Functions.
  1618. * totalordermag: (libc)FP Comparison Functions.
  1619. * totalordermagl: (libc)FP Comparison Functions.
  1620. * _toupper: (libc)Case Conversion.
  1621. * toupper: (libc)Case Conversion.
  1622. * towctrans: (libc)Wide Character Case Conversion.
  1623. * towlower: (libc)Wide Character Case Conversion.
  1624. * towupper: (libc)Wide Character Case Conversion.
  1625. * truncate64: (libc)File Size.
  1626. * truncate: (libc)File Size.
  1627. * truncf: (libc)Rounding Functions.
  1628. * trunc: (libc)Rounding Functions.
  1629. * truncl: (libc)Rounding Functions.
  1630. * tsearch: (libc)Tree Search Function.
  1631. * ttyname: (libc)Is It a Terminal.
  1632. * ttyname_r: (libc)Is It a Terminal.
  1633. * twalk: (libc)Tree Search Function.
  1634. * TZNAME_MAX: (libc)General Limits.
  1635. * tzset: (libc)Time Zone Functions.
  1636. * ufromfpf: (libc)Rounding Functions.
  1637. * ufromfp: (libc)Rounding Functions.
  1638. * ufromfpl: (libc)Rounding Functions.
  1639. * ufromfpxf: (libc)Rounding Functions.
  1640. * ufromfpx: (libc)Rounding Functions.
  1641. * ufromfpxl: (libc)Rounding Functions.
  1642. * ulimit: (libc)Limits on Resources.
  1643. * umask: (libc)Setting Permissions.
  1644. * umount2: (libc)Mount-Unmount-Remount.
  1645. * umount: (libc)Mount-Unmount-Remount.
  1646. * uname: (libc)Platform Type.
  1647. * ungetc: (libc)How Unread.
  1648. * ungetwc: (libc)How Unread.
  1649. * unlink: (libc)Deleting Files.
  1650. * unlockpt: (libc)Allocation.
  1651. * unsetenv: (libc)Environment Access.
  1652. * updwtmp: (libc)Manipulating the Database.
  1653. * utime: (libc)File Times.
  1654. * utimes: (libc)File Times.
  1655. * utmpname: (libc)Manipulating the Database.
  1656. * utmpxname: (libc)XPG Functions.
  1657. * va_arg: (libc)Argument Macros.
  1658. * __va_copy: (libc)Argument Macros.
  1659. * va_copy: (libc)Argument Macros.
  1660. * va_end: (libc)Argument Macros.
  1661. * valloc: (libc)Aligned Memory Blocks.
  1662. * vasprintf: (libc)Variable Arguments Output.
  1663. * va_start: (libc)Argument Macros.
  1664. * VDISCARD: (libc)Other Special.
  1665. * VDSUSP: (libc)Signal Characters.
  1666. * VEOF: (libc)Editing Characters.
  1667. * VEOL2: (libc)Editing Characters.
  1668. * VEOL: (libc)Editing Characters.
  1669. * VERASE: (libc)Editing Characters.
  1670. * verr: (libc)Error Messages.
  1671. * verrx: (libc)Error Messages.
  1672. * versionsort64: (libc)Scanning Directory Content.
  1673. * versionsort: (libc)Scanning Directory Content.
  1674. * vfork: (libc)Creating a Process.
  1675. * vfprintf: (libc)Variable Arguments Output.
  1676. * vfscanf: (libc)Variable Arguments Input.
  1677. * vfwprintf: (libc)Variable Arguments Output.
  1678. * vfwscanf: (libc)Variable Arguments Input.
  1679. * VINTR: (libc)Signal Characters.
  1680. * VKILL: (libc)Editing Characters.
  1681. * vlimit: (libc)Limits on Resources.
  1682. * VLNEXT: (libc)Other Special.
  1683. * VMIN: (libc)Noncanonical Input.
  1684. * vprintf: (libc)Variable Arguments Output.
  1685. * VQUIT: (libc)Signal Characters.
  1686. * VREPRINT: (libc)Editing Characters.
  1687. * vscanf: (libc)Variable Arguments Input.
  1688. * vsnprintf: (libc)Variable Arguments Output.
  1689. * vsprintf: (libc)Variable Arguments Output.
  1690. * vsscanf: (libc)Variable Arguments Input.
  1691. * VSTART: (libc)Start/Stop Characters.
  1692. * VSTATUS: (libc)Other Special.
  1693. * VSTOP: (libc)Start/Stop Characters.
  1694. * VSUSP: (libc)Signal Characters.
  1695. * vswprintf: (libc)Variable Arguments Output.
  1696. * vswscanf: (libc)Variable Arguments Input.
  1697. * vsyslog: (libc)syslog; vsyslog.
  1698. * VTIME: (libc)Noncanonical Input.
  1699. * vtimes: (libc)Resource Usage.
  1700. * vwarn: (libc)Error Messages.
  1701. * vwarnx: (libc)Error Messages.
  1702. * VWERASE: (libc)Editing Characters.
  1703. * vwprintf: (libc)Variable Arguments Output.
  1704. * vwscanf: (libc)Variable Arguments Input.
  1705. * wait3: (libc)BSD Wait Functions.
  1706. * wait4: (libc)Process Completion.
  1707. * wait: (libc)Process Completion.
  1708. * waitpid: (libc)Process Completion.
  1709. * warn: (libc)Error Messages.
  1710. * warnx: (libc)Error Messages.
  1711. * WCHAR_MAX: (libc)Extended Char Intro.
  1712. * WCHAR_MIN: (libc)Extended Char Intro.
  1713. * WCOREDUMP: (libc)Process Completion Status.
  1714. * wcpcpy: (libc)Copying Strings and Arrays.
  1715. * wcpncpy: (libc)Truncating Strings.
  1716. * wcrtomb: (libc)Converting a Character.
  1717. * wcscasecmp: (libc)String/Array Comparison.
  1718. * wcscat: (libc)Concatenating Strings.
  1719. * wcschr: (libc)Search Functions.
  1720. * wcschrnul: (libc)Search Functions.
  1721. * wcscmp: (libc)String/Array Comparison.
  1722. * wcscoll: (libc)Collation Functions.
  1723. * wcscpy: (libc)Copying Strings and Arrays.
  1724. * wcscspn: (libc)Search Functions.
  1725. * wcsdup: (libc)Copying Strings and Arrays.
  1726. * wcsftime: (libc)Formatting Calendar Time.
  1727. * wcslen: (libc)String Length.
  1728. * wcsncasecmp: (libc)String/Array Comparison.
  1729. * wcsncat: (libc)Truncating Strings.
  1730. * wcsncmp: (libc)String/Array Comparison.
  1731. * wcsncpy: (libc)Truncating Strings.
  1732. * wcsnlen: (libc)String Length.
  1733. * wcsnrtombs: (libc)Converting Strings.
  1734. * wcspbrk: (libc)Search Functions.
  1735. * wcsrchr: (libc)Search Functions.
  1736. * wcsrtombs: (libc)Converting Strings.
  1737. * wcsspn: (libc)Search Functions.
  1738. * wcsstr: (libc)Search Functions.
  1739. * wcstod: (libc)Parsing of Floats.
  1740. * wcstof: (libc)Parsing of Floats.
  1741. * wcstoimax: (libc)Parsing of Integers.
  1742. * wcstok: (libc)Finding Tokens in a String.
  1743. * wcstold: (libc)Parsing of Floats.
  1744. * wcstol: (libc)Parsing of Integers.
  1745. * wcstoll: (libc)Parsing of Integers.
  1746. * wcstombs: (libc)Non-reentrant String Conversion.
  1747. * wcstoq: (libc)Parsing of Integers.
  1748. * wcstoul: (libc)Parsing of Integers.
  1749. * wcstoull: (libc)Parsing of Integers.
  1750. * wcstoumax: (libc)Parsing of Integers.
  1751. * wcstouq: (libc)Parsing of Integers.
  1752. * wcswcs: (libc)Search Functions.
  1753. * wcsxfrm: (libc)Collation Functions.
  1754. * wctob: (libc)Converting a Character.
  1755. * wctomb: (libc)Non-reentrant Character Conversion.
  1756. * wctrans: (libc)Wide Character Case Conversion.
  1757. * wctype: (libc)Classification of Wide Characters.
  1758. * WEOF: (libc)EOF and Errors.
  1759. * WEOF: (libc)Extended Char Intro.
  1760. * WEXITSTATUS: (libc)Process Completion Status.
  1761. * WIFEXITED: (libc)Process Completion Status.
  1762. * WIFSIGNALED: (libc)Process Completion Status.
  1763. * WIFSTOPPED: (libc)Process Completion Status.
  1764. * wmemchr: (libc)Search Functions.
  1765. * wmemcmp: (libc)String/Array Comparison.
  1766. * wmemcpy: (libc)Copying Strings and Arrays.
  1767. * wmemmove: (libc)Copying Strings and Arrays.
  1768. * wmempcpy: (libc)Copying Strings and Arrays.
  1769. * wmemset: (libc)Copying Strings and Arrays.
  1770. * W_OK: (libc)Testing File Access.
  1771. * wordexp: (libc)Calling Wordexp.
  1772. * wordfree: (libc)Calling Wordexp.
  1773. * wprintf: (libc)Formatted Output Functions.
  1774. * write: (libc)I/O Primitives.
  1775. * writev: (libc)Scatter-Gather.
  1776. * wscanf: (libc)Formatted Input Functions.
  1777. * WSTOPSIG: (libc)Process Completion Status.
  1778. * WTERMSIG: (libc)Process Completion Status.
  1779. * X_OK: (libc)Testing File Access.
  1780. * y0f: (libc)Special Functions.
  1781. * y0: (libc)Special Functions.
  1782. * y0l: (libc)Special Functions.
  1783. * y1f: (libc)Special Functions.
  1784. * y1: (libc)Special Functions.
  1785. * y1l: (libc)Special Functions.
  1786. * ynf: (libc)Special Functions.
  1787. * yn: (libc)Special Functions.
  1788. * ynl: (libc)Special Functions.
  1789. END-INFO-DIR-ENTRY
  1790. 
  1791. File: libc.info, Node: Defining the Output Handler, Next: Printf Extension Example, Prev: Conversion Specifier Options, Up: Customizing Printf
  1792. 12.13.3 Defining the Output Handler
  1793. -----------------------------------
  1794. Now let’s look at how to define the handler and arginfo functions which
  1795. are passed as arguments to ‘register_printf_function’.
  1796. *Compatibility Note:* The interface changed in the GNU C Library
  1797. version 2.0. Previously the third argument was of type ‘va_list *’.
  1798. You should define your handler functions with a prototype like:
  1799. int FUNCTION (FILE *stream, const struct printf_info *info,
  1800. const void *const *args)
  1801. The STREAM argument passed to the handler function is the stream to
  1802. which it should write output.
  1803. The INFO argument is a pointer to a structure that contains
  1804. information about the various options that were included with the
  1805. conversion in the template string. You should not modify this structure
  1806. inside your handler function. *Note Conversion Specifier Options::, for
  1807. a description of this data structure.
  1808. The ARGS is a vector of pointers to the arguments data. The number
  1809. of arguments was determined by calling the argument information function
  1810. provided by the user.
  1811. Your handler function should return a value just like ‘printf’ does:
  1812. it should return the number of characters it has written, or a negative
  1813. value to indicate an error.
  1814. -- Data Type: printf_function
  1815. This is the data type that a handler function should have.
  1816. If you are going to use ‘parse_printf_format’ in your application,
  1817. you must also define a function to pass as the ARGINFO-FUNCTION argument
  1818. for each new conversion you install with ‘register_printf_function’.
  1819. You have to define these functions with a prototype like:
  1820. int FUNCTION (const struct printf_info *info,
  1821. size_t n, int *argtypes)
  1822. The return value from the function should be the number of arguments
  1823. the conversion expects. The function should also fill in no more than N
  1824. elements of the ARGTYPES array with information about the types of each
  1825. of these arguments. This information is encoded using the various ‘PA_’
  1826. macros. (You will notice that this is the same calling convention
  1827. ‘parse_printf_format’ itself uses.)
  1828. -- Data Type: printf_arginfo_function
  1829. This type is used to describe functions that return information
  1830. about the number and type of arguments used by a conversion
  1831. specifier.
  1832. 
  1833. File: libc.info, Node: Printf Extension Example, Next: Predefined Printf Handlers, Prev: Defining the Output Handler, Up: Customizing Printf
  1834. 12.13.4 ‘printf’ Extension Example
  1835. ----------------------------------
  1836. Here is an example showing how to define a ‘printf’ handler function.
  1837. This program defines a data structure called a ‘Widget’ and defines the
  1838. ‘%W’ conversion to print information about ‘Widget *’ arguments,
  1839. including the pointer value and the name stored in the data structure.
  1840. The ‘%W’ conversion supports the minimum field width and
  1841. left-justification options, but ignores everything else.
  1842. #include <stdio.h>
  1843. #include <stdlib.h>
  1844. #include <printf.h>
  1845. typedef struct
  1846. {
  1847. char *name;
  1848. }
  1849. Widget;
  1850. int
  1851. print_widget (FILE *stream,
  1852. const struct printf_info *info,
  1853. const void *const *args)
  1854. {
  1855. const Widget *w;
  1856. char *buffer;
  1857. int len;
  1858. /* Format the output into a string. */
  1859. w = *((const Widget **) (args[0]));
  1860. len = asprintf (&buffer, "<Widget %p: %s>", w, w->name);
  1861. if (len == -1)
  1862. return -1;
  1863. /* Pad to the minimum field width and print to the stream. */
  1864. len = fprintf (stream, "%*s",
  1865. (info->left ? -info->width : info->width),
  1866. buffer);
  1867. /* Clean up and return. */
  1868. free (buffer);
  1869. return len;
  1870. }
  1871. int
  1872. print_widget_arginfo (const struct printf_info *info, size_t n,
  1873. int *argtypes)
  1874. {
  1875. /* We always take exactly one argument and this is a pointer to the
  1876. structure.. */
  1877. if (n > 0)
  1878. argtypes[0] = PA_POINTER;
  1879. return 1;
  1880. }
  1881. int
  1882. main (void)
  1883. {
  1884. /* Make a widget to print. */
  1885. Widget mywidget;
  1886. mywidget.name = "mywidget";
  1887. /* Register the print function for widgets. */
  1888. register_printf_function ('W', print_widget, print_widget_arginfo);
  1889. /* Now print the widget. */
  1890. printf ("|%W|\n", &mywidget);
  1891. printf ("|%35W|\n", &mywidget);
  1892. printf ("|%-35W|\n", &mywidget);
  1893. return 0;
  1894. }
  1895. The output produced by this program looks like:
  1896. |<Widget 0xffeffb7c: mywidget>|
  1897. | <Widget 0xffeffb7c: mywidget>|
  1898. |<Widget 0xffeffb7c: mywidget> |
  1899. 
  1900. File: libc.info, Node: Predefined Printf Handlers, Prev: Printf Extension Example, Up: Customizing Printf
  1901. 12.13.5 Predefined ‘printf’ Handlers
  1902. ------------------------------------
  1903. The GNU C Library also contains a concrete and useful application of the
  1904. ‘printf’ handler extension. There are two functions available which
  1905. implement a special way to print floating-point numbers.
  1906. -- Function: int printf_size (FILE *FP, const struct printf_info *INFO,
  1907. const void *const *ARGS)
  1908. Preliminary: | MT-Safe race:fp locale | AS-Unsafe corrupt heap |
  1909. AC-Unsafe mem corrupt | *Note POSIX Safety Concepts::.
  1910. Print a given floating point number as for the format ‘%f’ except
  1911. that there is a postfix character indicating the divisor for the
  1912. number to make this less than 1000. There are two possible
  1913. divisors: powers of 1024 or powers of 1000. Which one is used
  1914. depends on the format character specified while registered this
  1915. handler. If the character is of lower case, 1024 is used. For
  1916. upper case characters, 1000 is used.
  1917. The postfix tag corresponds to bytes, kilobytes, megabytes,
  1918. gigabytes, etc. The full table is:
  1919. low Multiplier From Upper Multiplier
  1920. ’ ’ 1 ’ ’ 1
  1921. k 2^10 (1024) kilo K 10^3 (1000)
  1922. m 2^20 mega M 10^6
  1923. g 2^30 giga G 10^9
  1924. t 2^40 tera T 10^12
  1925. p 2^50 peta P 10^15
  1926. e 2^60 exa E 10^18
  1927. z 2^70 zetta Z 10^21
  1928. y 2^80 yotta Y 10^24
  1929. The default precision is 3, i.e., 1024 is printed with a lower-case
  1930. format character as if it were ‘%.3fk’ and will yield ‘1.000k’.
  1931. Due to the requirements of ‘register_printf_function’ we must also
  1932. provide the function which returns information about the arguments.
  1933. -- Function: int printf_size_info (const struct printf_info *INFO,
  1934. size_t N, int *ARGTYPES)
  1935. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  1936. Concepts::.
  1937. This function will return in ARGTYPES the information about the
  1938. used parameters in the way the ‘vfprintf’ implementation expects
  1939. it. The format always takes one argument.
  1940. To use these functions both functions must be registered with a call
  1941. like
  1942. register_printf_function ('B', printf_size, printf_size_info);
  1943. Here we register the functions to print numbers as powers of 1000
  1944. since the format character ‘'B'’ is an upper-case character. If we
  1945. would additionally use ‘'b'’ in a line like
  1946. register_printf_function ('b', printf_size, printf_size_info);
  1947. we could also print using a power of 1024. Please note that all that is
  1948. different in these two lines is the format specifier. The ‘printf_size’
  1949. function knows about the difference between lower and upper case format
  1950. specifiers.
  1951. The use of ‘'B'’ and ‘'b'’ is no coincidence. Rather it is the
  1952. preferred way to use this functionality since it is available on some
  1953. other systems which also use format specifiers.
  1954. 
  1955. File: libc.info, Node: Formatted Input, Next: EOF and Errors, Prev: Customizing Printf, Up: I/O on Streams
  1956. 12.14 Formatted Input
  1957. =====================
  1958. The functions described in this section (‘scanf’ and related functions)
  1959. provide facilities for formatted input analogous to the formatted output
  1960. facilities. These functions provide a mechanism for reading arbitrary
  1961. values under the control of a "format string" or "template string".
  1962. * Menu:
  1963. * Formatted Input Basics:: Some basics to get you started.
  1964. * Input Conversion Syntax:: Syntax of conversion specifications.
  1965. * Table of Input Conversions:: Summary of input conversions and what they do.
  1966. * Numeric Input Conversions:: Details of conversions for reading numbers.
  1967. * String Input Conversions:: Details of conversions for reading strings.
  1968. * Dynamic String Input:: String conversions that ‘malloc’ the buffer.
  1969. * Other Input Conversions:: Details of miscellaneous other conversions.
  1970. * Formatted Input Functions:: Descriptions of the actual functions.
  1971. * Variable Arguments Input:: ‘vscanf’ and friends.
  1972. 
  1973. File: libc.info, Node: Formatted Input Basics, Next: Input Conversion Syntax, Up: Formatted Input
  1974. 12.14.1 Formatted Input Basics
  1975. ------------------------------
  1976. Calls to ‘scanf’ are superficially similar to calls to ‘printf’ in that
  1977. arbitrary arguments are read under the control of a template string.
  1978. While the syntax of the conversion specifications in the template is
  1979. very similar to that for ‘printf’, the interpretation of the template is
  1980. oriented more towards free-format input and simple pattern matching,
  1981. rather than fixed-field formatting. For example, most ‘scanf’
  1982. conversions skip over any amount of “white space” (including spaces,
  1983. tabs, and newlines) in the input file, and there is no concept of
  1984. precision for the numeric input conversions as there is for the
  1985. corresponding output conversions. Ordinarily, non-whitespace characters
  1986. in the template are expected to match characters in the input stream
  1987. exactly, but a matching failure is distinct from an input error on the
  1988. stream.
  1989. Another area of difference between ‘scanf’ and ‘printf’ is that you
  1990. must remember to supply pointers rather than immediate values as the
  1991. optional arguments to ‘scanf’; the values that are read are stored in
  1992. the objects that the pointers point to. Even experienced programmers
  1993. tend to forget this occasionally, so if your program is getting strange
  1994. errors that seem to be related to ‘scanf’, you might want to
  1995. double-check this.
  1996. When a "matching failure" occurs, ‘scanf’ returns immediately,
  1997. leaving the first non-matching character as the next character to be
  1998. read from the stream. The normal return value from ‘scanf’ is the
  1999. number of values that were assigned, so you can use this to determine if
  2000. a matching error happened before all the expected values were read.
  2001. The ‘scanf’ function is typically used for things like reading in the
  2002. contents of tables. For example, here is a function that uses ‘scanf’
  2003. to initialize an array of ‘double’:
  2004. void
  2005. readarray (double *array, int n)
  2006. {
  2007. int i;
  2008. for (i=0; i<n; i++)
  2009. if (scanf (" %lf", &(array[i])) != 1)
  2010. invalid_input_error ();
  2011. }
  2012. The formatted input functions are not used as frequently as the
  2013. formatted output functions. Partly, this is because it takes some care
  2014. to use them properly. Another reason is that it is difficult to recover
  2015. from a matching error.
  2016. If you are trying to read input that doesn’t match a single, fixed
  2017. pattern, you may be better off using a tool such as Flex to generate a
  2018. lexical scanner, or Bison to generate a parser, rather than using
  2019. ‘scanf’. For more information about these tools, see *note
  2020. (flex.info)Top::, and *note (bison.info)Top::.
  2021. 
  2022. File: libc.info, Node: Input Conversion Syntax, Next: Table of Input Conversions, Prev: Formatted Input Basics, Up: Formatted Input
  2023. 12.14.2 Input Conversion Syntax
  2024. -------------------------------
  2025. A ‘scanf’ template string is a string that contains ordinary multibyte
  2026. characters interspersed with conversion specifications that start with
  2027. ‘%’.
  2028. Any whitespace character (as defined by the ‘isspace’ function; *note
  2029. Classification of Characters::) in the template causes any number of
  2030. whitespace characters in the input stream to be read and discarded. The
  2031. whitespace characters that are matched need not be exactly the same
  2032. whitespace characters that appear in the template string. For example,
  2033. write ‘ , ’ in the template to recognize a comma with optional
  2034. whitespace before and after.
  2035. Other characters in the template string that are not part of
  2036. conversion specifications must match characters in the input stream
  2037. exactly; if this is not the case, a matching failure occurs.
  2038. The conversion specifications in a ‘scanf’ template string have the
  2039. general form:
  2040. % FLAGS WIDTH TYPE CONVERSION
  2041. In more detail, an input conversion specification consists of an
  2042. initial ‘%’ character followed in sequence by:
  2043. • An optional "flag character" ‘*’, which says to ignore the text
  2044. read for this specification. When ‘scanf’ finds a conversion
  2045. specification that uses this flag, it reads input as directed by
  2046. the rest of the conversion specification, but it discards this
  2047. input, does not use a pointer argument, and does not increment the
  2048. count of successful assignments.
  2049. • An optional flag character ‘a’ (valid with string conversions only)
  2050. which requests allocation of a buffer long enough to store the
  2051. string in. (This is a GNU extension.) *Note Dynamic String
  2052. Input::.
  2053. • An optional decimal integer that specifies the "maximum field
  2054. width". Reading of characters from the input stream stops either
  2055. when this maximum is reached or when a non-matching character is
  2056. found, whichever happens first. Most conversions discard initial
  2057. whitespace characters (those that don’t are explicitly documented),
  2058. and these discarded characters don’t count towards the maximum
  2059. field width. String input conversions store a null character to
  2060. mark the end of the input; the maximum field width does not include
  2061. this terminator.
  2062. • An optional "type modifier character". For example, you can
  2063. specify a type modifier of ‘l’ with integer conversions such as
  2064. ‘%d’ to specify that the argument is a pointer to a ‘long int’
  2065. rather than a pointer to an ‘int’.
  2066. • A character that specifies the conversion to be applied.
  2067. The exact options that are permitted and how they are interpreted
  2068. vary between the different conversion specifiers. See the descriptions
  2069. of the individual conversions for information about the particular
  2070. options that they allow.
  2071. With the ‘-Wformat’ option, the GNU C compiler checks calls to
  2072. ‘scanf’ and related functions. It examines the format string and
  2073. verifies that the correct number and types of arguments are supplied.
  2074. There is also a GNU C syntax to tell the compiler that a function you
  2075. write uses a ‘scanf’-style format string. *Note Declaring Attributes of
  2076. Functions: (gcc.info)Function Attributes, for more information.
  2077. 
  2078. File: libc.info, Node: Table of Input Conversions, Next: Numeric Input Conversions, Prev: Input Conversion Syntax, Up: Formatted Input
  2079. 12.14.3 Table of Input Conversions
  2080. ----------------------------------
  2081. Here is a table that summarizes the various conversion specifications:
  2082. ‘%d’
  2083. Matches an optionally signed integer written in decimal. *Note
  2084. Numeric Input Conversions::.
  2085. ‘%i’
  2086. Matches an optionally signed integer in any of the formats that the
  2087. C language defines for specifying an integer constant. *Note
  2088. Numeric Input Conversions::.
  2089. ‘%o’
  2090. Matches an unsigned integer written in octal radix. *Note Numeric
  2091. Input Conversions::.
  2092. ‘%u’
  2093. Matches an unsigned integer written in decimal radix. *Note
  2094. Numeric Input Conversions::.
  2095. ‘%x’, ‘%X’
  2096. Matches an unsigned integer written in hexadecimal radix. *Note
  2097. Numeric Input Conversions::.
  2098. ‘%e’, ‘%f’, ‘%g’, ‘%E’, ‘%G’
  2099. Matches an optionally signed floating-point number. *Note Numeric
  2100. Input Conversions::.
  2101. ‘%s’
  2102. Matches a string containing only non-whitespace characters. *Note
  2103. String Input Conversions::. The presence of the ‘l’ modifier
  2104. determines whether the output is stored as a wide character string
  2105. or a multibyte string. If ‘%s’ is used in a wide character
  2106. function the string is converted as with multiple calls to
  2107. ‘wcrtomb’ into a multibyte string. This means that the buffer must
  2108. provide room for ‘MB_CUR_MAX’ bytes for each wide character read.
  2109. In case ‘%ls’ is used in a multibyte function the result is
  2110. converted into wide characters as with multiple calls of ‘mbrtowc’
  2111. before being stored in the user provided buffer.
  2112. ‘%S’
  2113. This is an alias for ‘%ls’ which is supported for compatibility
  2114. with the Unix standard.
  2115. ‘%[’
  2116. Matches a string of characters that belong to a specified set.
  2117. *Note String Input Conversions::. The presence of the ‘l’ modifier
  2118. determines whether the output is stored as a wide character string
  2119. or a multibyte string. If ‘%[’ is used in a wide character
  2120. function the string is converted as with multiple calls to
  2121. ‘wcrtomb’ into a multibyte string. This means that the buffer must
  2122. provide room for ‘MB_CUR_MAX’ bytes for each wide character read.
  2123. In case ‘%l[’ is used in a multibyte function the result is
  2124. converted into wide characters as with multiple calls of ‘mbrtowc’
  2125. before being stored in the user provided buffer.
  2126. ‘%c’
  2127. Matches a string of one or more characters; the number of
  2128. characters read is controlled by the maximum field width given for
  2129. the conversion. *Note String Input Conversions::.
  2130. If ‘%c’ is used in a wide stream function the read value is
  2131. converted from a wide character to the corresponding multibyte
  2132. character before storing it. Note that this conversion can produce
  2133. more than one byte of output and therefore the provided buffer must
  2134. be large enough for up to ‘MB_CUR_MAX’ bytes for each character.
  2135. If ‘%lc’ is used in a multibyte function the input is treated as a
  2136. multibyte sequence (and not bytes) and the result is converted as
  2137. with calls to ‘mbrtowc’.
  2138. ‘%C’
  2139. This is an alias for ‘%lc’ which is supported for compatibility
  2140. with the Unix standard.
  2141. ‘%p’
  2142. Matches a pointer value in the same implementation-defined format
  2143. used by the ‘%p’ output conversion for ‘printf’. *Note Other Input
  2144. Conversions::.
  2145. ‘%n’
  2146. This conversion doesn’t read any characters; it records the number
  2147. of characters read so far by this call. *Note Other Input
  2148. Conversions::.
  2149. ‘%%’
  2150. This matches a literal ‘%’ character in the input stream. No
  2151. corresponding argument is used. *Note Other Input Conversions::.
  2152. If the syntax of a conversion specification is invalid, the behavior
  2153. is undefined. If there aren’t enough function arguments provided to
  2154. supply addresses for all the conversion specifications in the template
  2155. strings that perform assignments, or if the arguments are not of the
  2156. correct types, the behavior is also undefined. On the other hand, extra
  2157. arguments are simply ignored.
  2158. 
  2159. File: libc.info, Node: Numeric Input Conversions, Next: String Input Conversions, Prev: Table of Input Conversions, Up: Formatted Input
  2160. 12.14.4 Numeric Input Conversions
  2161. ---------------------------------
  2162. This section describes the ‘scanf’ conversions for reading numeric
  2163. values.
  2164. The ‘%d’ conversion matches an optionally signed integer in decimal
  2165. radix. The syntax that is recognized is the same as that for the
  2166. ‘strtol’ function (*note Parsing of Integers::) with the value ‘10’ for
  2167. the BASE argument.
  2168. The ‘%i’ conversion matches an optionally signed integer in any of
  2169. the formats that the C language defines for specifying an integer
  2170. constant. The syntax that is recognized is the same as that for the
  2171. ‘strtol’ function (*note Parsing of Integers::) with the value ‘0’ for
  2172. the BASE argument. (You can print integers in this syntax with ‘printf’
  2173. by using the ‘#’ flag character with the ‘%x’, ‘%o’, or ‘%d’ conversion.
  2174. *Note Integer Conversions::.)
  2175. For example, any of the strings ‘10’, ‘0xa’, or ‘012’ could be read
  2176. in as integers under the ‘%i’ conversion. Each of these specifies a
  2177. number with decimal value ‘10’.
  2178. The ‘%o’, ‘%u’, and ‘%x’ conversions match unsigned integers in
  2179. octal, decimal, and hexadecimal radices, respectively. The syntax that
  2180. is recognized is the same as that for the ‘strtoul’ function (*note
  2181. Parsing of Integers::) with the appropriate value (‘8’, ‘10’, or ‘16’)
  2182. for the BASE argument.
  2183. The ‘%X’ conversion is identical to the ‘%x’ conversion. They both
  2184. permit either uppercase or lowercase letters to be used as digits.
  2185. The default type of the corresponding argument for the ‘%d’ and ‘%i’
  2186. conversions is ‘int *’, and ‘unsigned int *’ for the other integer
  2187. conversions. You can use the following type modifiers to specify other
  2188. sizes of integer:
  2189. ‘hh’
  2190. Specifies that the argument is a ‘signed char *’ or ‘unsigned char
  2191. *’.
  2192. This modifier was introduced in ISO C99.
  2193. ‘h’
  2194. Specifies that the argument is a ‘short int *’ or ‘unsigned short
  2195. int *’.
  2196. ‘j’
  2197. Specifies that the argument is a ‘intmax_t *’ or ‘uintmax_t *’.
  2198. This modifier was introduced in ISO C99.
  2199. ‘l’
  2200. Specifies that the argument is a ‘long int *’ or ‘unsigned long int
  2201. *’. Two ‘l’ characters is like the ‘L’ modifier, below.
  2202. If used with ‘%c’ or ‘%s’ the corresponding parameter is considered
  2203. as a pointer to a wide character or wide character string
  2204. respectively. This use of ‘l’ was introduced in Amendment 1 to
  2205. ISO C90.
  2206. ‘ll’
  2207. ‘L’
  2208. ‘q’
  2209. Specifies that the argument is a ‘long long int *’ or ‘unsigned
  2210. long long int *’. (The ‘long long’ type is an extension supported
  2211. by the GNU C compiler. For systems that don’t provide extra-long
  2212. integers, this is the same as ‘long int’.)
  2213. The ‘q’ modifier is another name for the same thing, which comes
  2214. from 4.4 BSD; a ‘long long int’ is sometimes called a “quad” ‘int’.
  2215. ‘t’
  2216. Specifies that the argument is a ‘ptrdiff_t *’.
  2217. This modifier was introduced in ISO C99.
  2218. ‘z’
  2219. Specifies that the argument is a ‘size_t *’.
  2220. This modifier was introduced in ISO C99.
  2221. All of the ‘%e’, ‘%f’, ‘%g’, ‘%E’, and ‘%G’ input conversions are
  2222. interchangeable. They all match an optionally signed floating point
  2223. number, in the same syntax as for the ‘strtod’ function (*note Parsing
  2224. of Floats::).
  2225. For the floating-point input conversions, the default argument type
  2226. is ‘float *’. (This is different from the corresponding output
  2227. conversions, where the default type is ‘double’; remember that ‘float’
  2228. arguments to ‘printf’ are converted to ‘double’ by the default argument
  2229. promotions, but ‘float *’ arguments are not promoted to ‘double *’.)
  2230. You can specify other sizes of float using these type modifiers:
  2231. ‘l’
  2232. Specifies that the argument is of type ‘double *’.
  2233. ‘L’
  2234. Specifies that the argument is of type ‘long double *’.
  2235. For all the above number parsing formats there is an additional
  2236. optional flag ‘'’. When this flag is given the ‘scanf’ function expects
  2237. the number represented in the input string to be formatted according to
  2238. the grouping rules of the currently selected locale (*note General
  2239. Numeric::).
  2240. If the ‘"C"’ or ‘"POSIX"’ locale is selected there is no difference.
  2241. But for a locale which specifies values for the appropriate fields in
  2242. the locale the input must have the correct form in the input. Otherwise
  2243. the longest prefix with a correct form is processed.
  2244. 
  2245. File: libc.info, Node: String Input Conversions, Next: Dynamic String Input, Prev: Numeric Input Conversions, Up: Formatted Input
  2246. 12.14.5 String Input Conversions
  2247. --------------------------------
  2248. This section describes the ‘scanf’ input conversions for reading string
  2249. and character values: ‘%s’, ‘%S’, ‘%[’, ‘%c’, and ‘%C’.
  2250. You have two options for how to receive the input from these
  2251. conversions:
  2252. • Provide a buffer to store it in. This is the default. You should
  2253. provide an argument of type ‘char *’ or ‘wchar_t *’ (the latter if
  2254. the ‘l’ modifier is present).
  2255. *Warning:* To make a robust program, you must make sure that the
  2256. input (plus its terminating null) cannot possibly exceed the size
  2257. of the buffer you provide. In general, the only way to do this is
  2258. to specify a maximum field width one less than the buffer size.
  2259. *If you provide the buffer, always specify a maximum field width to
  2260. prevent overflow.*
  2261. • Ask ‘scanf’ to allocate a big enough buffer, by specifying the ‘a’
  2262. flag character. This is a GNU extension. You should provide an
  2263. argument of type ‘char **’ for the buffer address to be stored in.
  2264. *Note Dynamic String Input::.
  2265. The ‘%c’ conversion is the simplest: it matches a fixed number of
  2266. characters, always. The maximum field width says how many characters to
  2267. read; if you don’t specify the maximum, the default is 1. This
  2268. conversion doesn’t append a null character to the end of the text it
  2269. reads. It also does not skip over initial whitespace characters. It
  2270. reads precisely the next N characters, and fails if it cannot get that
  2271. many. Since there is always a maximum field width with ‘%c’ (whether
  2272. specified, or 1 by default), you can always prevent overflow by making
  2273. the buffer long enough.
  2274. If the format is ‘%lc’ or ‘%C’ the function stores wide characters
  2275. which are converted using the conversion determined at the time the
  2276. stream was opened from the external byte stream. The number of bytes
  2277. read from the medium is limited by ‘MB_CUR_LEN * N’ but at most N wide
  2278. characters get stored in the output string.
  2279. The ‘%s’ conversion matches a string of non-whitespace characters.
  2280. It skips and discards initial whitespace, but stops when it encounters
  2281. more whitespace after having read something. It stores a null character
  2282. at the end of the text that it reads.
  2283. For example, reading the input:
  2284. hello, world
  2285. with the conversion ‘%10c’ produces ‘" hello, wo"’, but reading the same
  2286. input with the conversion ‘%10s’ produces ‘"hello,"’.
  2287. *Warning:* If you do not specify a field width for ‘%s’, then the
  2288. number of characters read is limited only by where the next whitespace
  2289. character appears. This almost certainly means that invalid input can
  2290. make your program crash—which is a bug.
  2291. The ‘%ls’ and ‘%S’ format are handled just like ‘%s’ except that the
  2292. external byte sequence is converted using the conversion associated with
  2293. the stream to wide characters with their own encoding. A width or
  2294. precision specified with the format do not directly determine how many
  2295. bytes are read from the stream since they measure wide characters. But
  2296. an upper limit can be computed by multiplying the value of the width or
  2297. precision by ‘MB_CUR_MAX’.
  2298. To read in characters that belong to an arbitrary set of your choice,
  2299. use the ‘%[’ conversion. You specify the set between the ‘[’ character
  2300. and a following ‘]’ character, using the same syntax used in regular
  2301. expressions for explicit sets of characters. As special cases:
  2302. • A literal ‘]’ character can be specified as the first character of
  2303. the set.
  2304. • An embedded ‘-’ character (that is, one that is not the first or
  2305. last character of the set) is used to specify a range of
  2306. characters.
  2307. • If a caret character ‘^’ immediately follows the initial ‘[’, then
  2308. the set of allowed input characters is everything _except_ the
  2309. characters listed.
  2310. The ‘%[’ conversion does not skip over initial whitespace characters.
  2311. Note that the "character class" syntax available in character sets
  2312. that appear inside regular expressions (such as ‘[:alpha:]’) is _not_
  2313. available in the ‘%[’ conversion.
  2314. Here are some examples of ‘%[’ conversions and what they mean:
  2315. ‘%25[1234567890]’
  2316. Matches a string of up to 25 digits.
  2317. ‘%25[][]’
  2318. Matches a string of up to 25 square brackets.
  2319. ‘%25[^ \f\n\r\t\v]’
  2320. Matches a string up to 25 characters long that doesn’t contain any
  2321. of the standard whitespace characters. This is slightly different
  2322. from ‘%s’, because if the input begins with a whitespace character,
  2323. ‘%[’ reports a matching failure while ‘%s’ simply discards the
  2324. initial whitespace.
  2325. ‘%25[a-z]’
  2326. Matches up to 25 lowercase characters.
  2327. As for ‘%c’ and ‘%s’ the ‘%[’ format is also modified to produce wide
  2328. characters if the ‘l’ modifier is present. All what is said about ‘%ls’
  2329. above is true for ‘%l[’.
  2330. One more reminder: the ‘%s’ and ‘%[’ conversions are *dangerous* if
  2331. you don’t specify a maximum width or use the ‘a’ flag, because input too
  2332. long would overflow whatever buffer you have provided for it. No matter
  2333. how long your buffer is, a user could supply input that is longer. A
  2334. well-written program reports invalid input with a comprehensible error
  2335. message, not with a crash.
  2336. 
  2337. File: libc.info, Node: Dynamic String Input, Next: Other Input Conversions, Prev: String Input Conversions, Up: Formatted Input
  2338. 12.14.6 Dynamically Allocating String Conversions
  2339. -------------------------------------------------
  2340. A GNU extension to formatted input lets you safely read a string with no
  2341. maximum size. Using this feature, you don’t supply a buffer; instead,
  2342. ‘scanf’ allocates a buffer big enough to hold the data and gives you its
  2343. address. To use this feature, write ‘a’ as a flag character, as in
  2344. ‘%as’ or ‘%a[0-9a-z]’.
  2345. The pointer argument you supply for where to store the input should
  2346. have type ‘char **’. The ‘scanf’ function allocates a buffer and stores
  2347. its address in the word that the argument points to. You should free
  2348. the buffer with ‘free’ when you no longer need it.
  2349. Here is an example of using the ‘a’ flag with the ‘%[…]’ conversion
  2350. specification to read a “variable assignment” of the form ‘VARIABLE =
  2351. VALUE’.
  2352. {
  2353. char *variable, *value;
  2354. if (2 > scanf ("%a[a-zA-Z0-9] = %a[^\n]\n",
  2355. &variable, &value))
  2356. {
  2357. invalid_input_error ();
  2358. return 0;
  2359. }
  2360. }
  2361. 
  2362. File: libc.info, Node: Other Input Conversions, Next: Formatted Input Functions, Prev: Dynamic String Input, Up: Formatted Input
  2363. 12.14.7 Other Input Conversions
  2364. -------------------------------
  2365. This section describes the miscellaneous input conversions.
  2366. The ‘%p’ conversion is used to read a pointer value. It recognizes
  2367. the same syntax used by the ‘%p’ output conversion for ‘printf’ (*note
  2368. Other Output Conversions::); that is, a hexadecimal number just as the
  2369. ‘%x’ conversion accepts. The corresponding argument should be of type
  2370. ‘void **’; that is, the address of a place to store a pointer.
  2371. The resulting pointer value is not guaranteed to be valid if it was
  2372. not originally written during the same program execution that reads it
  2373. in.
  2374. The ‘%n’ conversion produces the number of characters read so far by
  2375. this call. The corresponding argument should be of type ‘int *’. This
  2376. conversion works in the same way as the ‘%n’ conversion for ‘printf’;
  2377. see *note Other Output Conversions::, for an example.
  2378. The ‘%n’ conversion is the only mechanism for determining the success
  2379. of literal matches or conversions with suppressed assignments. If the
  2380. ‘%n’ follows the locus of a matching failure, then no value is stored
  2381. for it since ‘scanf’ returns before processing the ‘%n’. If you store
  2382. ‘-1’ in that argument slot before calling ‘scanf’, the presence of ‘-1’
  2383. after ‘scanf’ indicates an error occurred before the ‘%n’ was reached.
  2384. Finally, the ‘%%’ conversion matches a literal ‘%’ character in the
  2385. input stream, without using an argument. This conversion does not
  2386. permit any flags, field width, or type modifier to be specified.
  2387. 
  2388. File: libc.info, Node: Formatted Input Functions, Next: Variable Arguments Input, Prev: Other Input Conversions, Up: Formatted Input
  2389. 12.14.8 Formatted Input Functions
  2390. ---------------------------------
  2391. Here are the descriptions of the functions for performing formatted
  2392. input. Prototypes for these functions are in the header file ‘stdio.h’.
  2393. -- Function: int scanf (const char *TEMPLATE, …)
  2394. Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
  2395. mem lock corrupt | *Note POSIX Safety Concepts::.
  2396. The ‘scanf’ function reads formatted input from the stream ‘stdin’
  2397. under the control of the template string TEMPLATE. The optional
  2398. arguments are pointers to the places which receive the resulting
  2399. values.
  2400. The return value is normally the number of successful assignments.
  2401. If an end-of-file condition is detected before any matches are
  2402. performed, including matches against whitespace and literal
  2403. characters in the template, then ‘EOF’ is returned.
  2404. -- Function: int wscanf (const wchar_t *TEMPLATE, …)
  2405. Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
  2406. mem lock corrupt | *Note POSIX Safety Concepts::.
  2407. The ‘wscanf’ function reads formatted input from the stream ‘stdin’
  2408. under the control of the template string TEMPLATE. The optional
  2409. arguments are pointers to the places which receive the resulting
  2410. values.
  2411. The return value is normally the number of successful assignments.
  2412. If an end-of-file condition is detected before any matches are
  2413. performed, including matches against whitespace and literal
  2414. characters in the template, then ‘WEOF’ is returned.
  2415. -- Function: int fscanf (FILE *STREAM, const char *TEMPLATE, …)
  2416. Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
  2417. mem lock corrupt | *Note POSIX Safety Concepts::.
  2418. This function is just like ‘scanf’, except that the input is read
  2419. from the stream STREAM instead of ‘stdin’.
  2420. -- Function: int fwscanf (FILE *STREAM, const wchar_t *TEMPLATE, …)
  2421. Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
  2422. mem lock corrupt | *Note POSIX Safety Concepts::.
  2423. This function is just like ‘wscanf’, except that the input is read
  2424. from the stream STREAM instead of ‘stdin’.
  2425. -- Function: int sscanf (const char *S, const char *TEMPLATE, …)
  2426. Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
  2427. *Note POSIX Safety Concepts::.
  2428. This is like ‘scanf’, except that the characters are taken from the
  2429. null-terminated string S instead of from a stream. Reaching the
  2430. end of the string is treated as an end-of-file condition.
  2431. The behavior of this function is undefined if copying takes place
  2432. between objects that overlap—for example, if S is also given as an
  2433. argument to receive a string read under control of the ‘%s’, ‘%S’,
  2434. or ‘%[’ conversion.
  2435. -- Function: int swscanf (const wchar_t *WS, const wchar_t *TEMPLATE,
  2436. …)
  2437. Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
  2438. *Note POSIX Safety Concepts::.
  2439. This is like ‘wscanf’, except that the characters are taken from
  2440. the null-terminated string WS instead of from a stream. Reaching
  2441. the end of the string is treated as an end-of-file condition.
  2442. The behavior of this function is undefined if copying takes place
  2443. between objects that overlap—for example, if WS is also given as an
  2444. argument to receive a string read under control of the ‘%s’, ‘%S’,
  2445. or ‘%[’ conversion.
  2446. 
  2447. File: libc.info, Node: Variable Arguments Input, Prev: Formatted Input Functions, Up: Formatted Input
  2448. 12.14.9 Variable Arguments Input Functions
  2449. ------------------------------------------
  2450. The functions ‘vscanf’ and friends are provided so that you can define
  2451. your own variadic ‘scanf’-like functions that make use of the same
  2452. internals as the built-in formatted output functions. These functions
  2453. are analogous to the ‘vprintf’ series of output functions. *Note
  2454. Variable Arguments Output::, for important information on how to use
  2455. them.
  2456. *Portability Note:* The functions listed in this section were
  2457. introduced in ISO C99 and were before available as GNU extensions.
  2458. -- Function: int vscanf (const char *TEMPLATE, va_list AP)
  2459. Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
  2460. mem lock corrupt | *Note POSIX Safety Concepts::.
  2461. This function is similar to ‘scanf’, but instead of taking a
  2462. variable number of arguments directly, it takes an argument list
  2463. pointer AP of type ‘va_list’ (*note Variadic Functions::).
  2464. -- Function: int vwscanf (const wchar_t *TEMPLATE, va_list AP)
  2465. Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
  2466. mem lock corrupt | *Note POSIX Safety Concepts::.
  2467. This function is similar to ‘wscanf’, but instead of taking a
  2468. variable number of arguments directly, it takes an argument list
  2469. pointer AP of type ‘va_list’ (*note Variadic Functions::).
  2470. -- Function: int vfscanf (FILE *STREAM, const char *TEMPLATE, va_list
  2471. AP)
  2472. Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
  2473. mem lock corrupt | *Note POSIX Safety Concepts::.
  2474. This is the equivalent of ‘fscanf’ with the variable argument list
  2475. specified directly as for ‘vscanf’.
  2476. -- Function: int vfwscanf (FILE *STREAM, const wchar_t *TEMPLATE,
  2477. va_list AP)
  2478. Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe
  2479. mem lock corrupt | *Note POSIX Safety Concepts::.
  2480. This is the equivalent of ‘fwscanf’ with the variable argument list
  2481. specified directly as for ‘vwscanf’.
  2482. -- Function: int vsscanf (const char *S, const char *TEMPLATE, va_list
  2483. AP)
  2484. Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
  2485. *Note POSIX Safety Concepts::.
  2486. This is the equivalent of ‘sscanf’ with the variable argument list
  2487. specified directly as for ‘vscanf’.
  2488. -- Function: int vswscanf (const wchar_t *S, const wchar_t *TEMPLATE,
  2489. va_list AP)
  2490. Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem |
  2491. *Note POSIX Safety Concepts::.
  2492. This is the equivalent of ‘swscanf’ with the variable argument list
  2493. specified directly as for ‘vwscanf’.
  2494. In GNU C, there is a special construct you can use to let the
  2495. compiler know that a function uses a ‘scanf’-style format string. Then
  2496. it can check the number and types of arguments in each call to the
  2497. function, and warn you when they do not match the format string. For
  2498. details, see *note Declaring Attributes of Functions: (gcc.info)Function
  2499. Attributes.
  2500. 
  2501. File: libc.info, Node: EOF and Errors, Next: Error Recovery, Prev: Formatted Input, Up: I/O on Streams
  2502. 12.15 End-Of-File and Errors
  2503. ============================
  2504. Many of the functions described in this chapter return the value of the
  2505. macro ‘EOF’ to indicate unsuccessful completion of the operation. Since
  2506. ‘EOF’ is used to report both end of file and random errors, it’s often
  2507. better to use the ‘feof’ function to check explicitly for end of file
  2508. and ‘ferror’ to check for errors. These functions check indicators that
  2509. are part of the internal state of the stream object, indicators set if
  2510. the appropriate condition was detected by a previous I/O operation on
  2511. that stream.
  2512. -- Macro: int EOF
  2513. This macro is an integer value that is returned by a number of
  2514. narrow stream functions to indicate an end-of-file condition, or
  2515. some other error situation. With the GNU C Library, ‘EOF’ is ‘-1’.
  2516. In other libraries, its value may be some other negative number.
  2517. This symbol is declared in ‘stdio.h’.
  2518. -- Macro: int WEOF
  2519. This macro is an integer value that is returned by a number of wide
  2520. stream functions to indicate an end-of-file condition, or some
  2521. other error situation. With the GNU C Library, ‘WEOF’ is ‘-1’. In
  2522. other libraries, its value may be some other negative number.
  2523. This symbol is declared in ‘wchar.h’.
  2524. -- Function: int feof (FILE *STREAM)
  2525. Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
  2526. Safety Concepts::.
  2527. The ‘feof’ function returns nonzero if and only if the end-of-file
  2528. indicator for the stream STREAM is set.
  2529. This symbol is declared in ‘stdio.h’.
  2530. -- Function: int feof_unlocked (FILE *STREAM)
  2531. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2532. Concepts::.
  2533. The ‘feof_unlocked’ function is equivalent to the ‘feof’ function
  2534. except that it does not implicitly lock the stream.
  2535. This function is a GNU extension.
  2536. This symbol is declared in ‘stdio.h’.
  2537. -- Function: int ferror (FILE *STREAM)
  2538. Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
  2539. Safety Concepts::.
  2540. The ‘ferror’ function returns nonzero if and only if the error
  2541. indicator for the stream STREAM is set, indicating that an error
  2542. has occurred on a previous operation on the stream.
  2543. This symbol is declared in ‘stdio.h’.
  2544. -- Function: int ferror_unlocked (FILE *STREAM)
  2545. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  2546. Concepts::.
  2547. The ‘ferror_unlocked’ function is equivalent to the ‘ferror’
  2548. function except that it does not implicitly lock the stream.
  2549. This function is a GNU extension.
  2550. This symbol is declared in ‘stdio.h’.
  2551. In addition to setting the error indicator associated with the
  2552. stream, the functions that operate on streams also set ‘errno’ in the
  2553. same way as the corresponding low-level functions that operate on file
  2554. descriptors. For example, all of the functions that perform output to a
  2555. stream—such as ‘fputc’, ‘printf’, and ‘fflush’—are implemented in terms
  2556. of ‘write’, and all of the ‘errno’ error conditions defined for ‘write’
  2557. are meaningful for these functions. For more information about the
  2558. descriptor-level I/O functions, see *note Low-Level I/O::.
  2559. 
  2560. File: libc.info, Node: Error Recovery, Next: Binary Streams, Prev: EOF and Errors, Up: I/O on Streams
  2561. 12.16 Recovering from errors
  2562. ============================
  2563. You may explicitly clear the error and EOF flags with the ‘clearerr’
  2564. function.
  2565. -- Function: void clearerr (FILE *STREAM)
  2566. Preliminary: | MT-Safe | AS-Safe | AC-Unsafe lock | *Note POSIX
  2567. Safety Concepts::.
  2568. This function clears the end-of-file and error indicators for the
  2569. stream STREAM.
  2570. The file positioning functions (*note File Positioning::) also
  2571. clear the end-of-file indicator for the stream.
  2572. -- Function: void clearerr_unlocked (FILE *STREAM)
  2573. Preliminary: | MT-Safe race:stream | AS-Safe | AC-Safe | *Note
  2574. POSIX Safety Concepts::.
  2575. The ‘clearerr_unlocked’ function is equivalent to the ‘clearerr’
  2576. function except that it does not implicitly lock the stream.
  2577. This function is a GNU extension.
  2578. Note that it is _not_ correct to just clear the error flag and retry
  2579. a failed stream operation. After a failed write, any number of
  2580. characters since the last buffer flush may have been committed to the
  2581. file, while some buffered data may have been discarded. Merely retrying
  2582. can thus cause lost or repeated data.
  2583. A failed read may leave the file pointer in an inappropriate position
  2584. for a second try. In both cases, you should seek to a known position
  2585. before retrying.
  2586. Most errors that can happen are not recoverable — a second try will
  2587. always fail again in the same way. So usually it is best to give up and
  2588. report the error to the user, rather than install complicated recovery
  2589. logic.
  2590. One important exception is ‘EINTR’ (*note Interrupted Primitives::).
  2591. Many stream I/O implementations will treat it as an ordinary error,
  2592. which can be quite inconvenient. You can avoid this hassle by
  2593. installing all signals with the ‘SA_RESTART’ flag.
  2594. For similar reasons, setting nonblocking I/O on a stream’s file
  2595. descriptor is not usually advisable.
  2596. 
  2597. File: libc.info, Node: Binary Streams, Next: File Positioning, Prev: Error Recovery, Up: I/O on Streams
  2598. 12.17 Text and Binary Streams
  2599. =============================
  2600. GNU systems and other POSIX-compatible operating systems organize all
  2601. files as uniform sequences of characters. However, some other systems
  2602. make a distinction between files containing text and files containing
  2603. binary data, and the input and output facilities of ISO C provide for
  2604. this distinction. This section tells you how to write programs portable
  2605. to such systems.
  2606. When you open a stream, you can specify either a "text stream" or a
  2607. "binary stream". You indicate that you want a binary stream by
  2608. specifying the ‘b’ modifier in the OPENTYPE argument to ‘fopen’; see
  2609. *note Opening Streams::. Without this option, ‘fopen’ opens the file as
  2610. a text stream.
  2611. Text and binary streams differ in several ways:
  2612. • The data read from a text stream is divided into "lines" which are
  2613. terminated by newline (‘'\n'’) characters, while a binary stream is
  2614. simply a long series of characters. A text stream might on some
  2615. systems fail to handle lines more than 254 characters long
  2616. (including the terminating newline character).
  2617. • On some systems, text files can contain only printing characters,
  2618. horizontal tab characters, and newlines, and so text streams may
  2619. not support other characters. However, binary streams can handle
  2620. any character value.
  2621. • Space characters that are written immediately preceding a newline
  2622. character in a text stream may disappear when the file is read in
  2623. again.
  2624. • More generally, there need not be a one-to-one mapping between
  2625. characters that are read from or written to a text stream, and the
  2626. characters in the actual file.
  2627. Since a binary stream is always more capable and more predictable
  2628. than a text stream, you might wonder what purpose text streams serve.
  2629. Why not simply always use binary streams? The answer is that on these
  2630. operating systems, text and binary streams use different file formats,
  2631. and the only way to read or write “an ordinary file of text” that can
  2632. work with other text-oriented programs is through a text stream.
  2633. In the GNU C Library, and on all POSIX systems, there is no
  2634. difference between text streams and binary streams. When you open a
  2635. stream, you get the same kind of stream regardless of whether you ask
  2636. for binary. This stream can handle any file content, and has none of
  2637. the restrictions that text streams sometimes have.
  2638. 
  2639. File: libc.info, Node: File Positioning, Next: Portable Positioning, Prev: Binary Streams, Up: I/O on Streams
  2640. 12.18 File Positioning
  2641. ======================
  2642. The "file position" of a stream describes where in the file the stream
  2643. is currently reading or writing. I/O on the stream advances the file
  2644. position through the file. On GNU systems, the file position is
  2645. represented as an integer, which counts the number of bytes from the
  2646. beginning of the file. *Note File Position::.
  2647. During I/O to an ordinary disk file, you can change the file position
  2648. whenever you wish, so as to read or write any portion of the file. Some
  2649. other kinds of files may also permit this. Files which support changing
  2650. the file position are sometimes referred to as "random-access" files.
  2651. You can use the functions in this section to examine or modify the
  2652. file position indicator associated with a stream. The symbols listed
  2653. below are declared in the header file ‘stdio.h’.
  2654. -- Function: long int ftell (FILE *STREAM)
  2655. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  2656. | *Note POSIX Safety Concepts::.
  2657. This function returns the current file position of the stream
  2658. STREAM.
  2659. This function can fail if the stream doesn’t support file
  2660. positioning, or if the file position can’t be represented in a
  2661. ‘long int’, and possibly for other reasons as well. If a failure
  2662. occurs, a value of ‘-1’ is returned.
  2663. -- Function: off_t ftello (FILE *STREAM)
  2664. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  2665. | *Note POSIX Safety Concepts::.
  2666. The ‘ftello’ function is similar to ‘ftell’, except that it returns
  2667. a value of type ‘off_t’. Systems which support this type use it to
  2668. describe all file positions, unlike the POSIX specification which
  2669. uses a long int. The two are not necessarily the same size.
  2670. Therefore, using ftell can lead to problems if the implementation
  2671. is written on top of a POSIX compliant low-level I/O
  2672. implementation, and using ‘ftello’ is preferable whenever it is
  2673. available.
  2674. If this function fails it returns ‘(off_t) -1’. This can happen
  2675. due to missing support for file positioning or internal errors.
  2676. Otherwise the return value is the current file position.
  2677. The function is an extension defined in the Unix Single
  2678. Specification version 2.
  2679. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
  2680. 32 bit system this function is in fact ‘ftello64’. I.e., the LFS
  2681. interface transparently replaces the old interface.
  2682. -- Function: off64_t ftello64 (FILE *STREAM)
  2683. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  2684. | *Note POSIX Safety Concepts::.
  2685. This function is similar to ‘ftello’ with the only difference that
  2686. the return value is of type ‘off64_t’. This also requires that the
  2687. stream STREAM was opened using either ‘fopen64’, ‘freopen64’, or
  2688. ‘tmpfile64’ since otherwise the underlying file operations to
  2689. position the file pointer beyond the 2^31 bytes limit might fail.
  2690. If the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a 32
  2691. bits machine this function is available under the name ‘ftello’ and
  2692. so transparently replaces the old interface.
  2693. -- Function: int fseek (FILE *STREAM, long int OFFSET, int WHENCE)
  2694. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  2695. | *Note POSIX Safety Concepts::.
  2696. The ‘fseek’ function is used to change the file position of the
  2697. stream STREAM. The value of WHENCE must be one of the constants
  2698. ‘SEEK_SET’, ‘SEEK_CUR’, or ‘SEEK_END’, to indicate whether the
  2699. OFFSET is relative to the beginning of the file, the current file
  2700. position, or the end of the file, respectively.
  2701. This function returns a value of zero if the operation was
  2702. successful, and a nonzero value to indicate failure. A successful
  2703. call also clears the end-of-file indicator of STREAM and discards
  2704. any characters that were “pushed back” by the use of ‘ungetc’.
  2705. ‘fseek’ either flushes any buffered output before setting the file
  2706. position or else remembers it so it will be written later in its
  2707. proper place in the file.
  2708. -- Function: int fseeko (FILE *STREAM, off_t OFFSET, int WHENCE)
  2709. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  2710. | *Note POSIX Safety Concepts::.
  2711. This function is similar to ‘fseek’ but it corrects a problem with
  2712. ‘fseek’ in a system with POSIX types. Using a value of type ‘long
  2713. int’ for the offset is not compatible with POSIX. ‘fseeko’ uses the
  2714. correct type ‘off_t’ for the OFFSET parameter.
  2715. For this reason it is a good idea to prefer ‘ftello’ whenever it is
  2716. available since its functionality is (if different at all) closer
  2717. the underlying definition.
  2718. The functionality and return value are the same as for ‘fseek’.
  2719. The function is an extension defined in the Unix Single
  2720. Specification version 2.
  2721. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
  2722. 32 bit system this function is in fact ‘fseeko64’. I.e., the LFS
  2723. interface transparently replaces the old interface.
  2724. -- Function: int fseeko64 (FILE *STREAM, off64_t OFFSET, int WHENCE)
  2725. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  2726. | *Note POSIX Safety Concepts::.
  2727. This function is similar to ‘fseeko’ with the only difference that
  2728. the OFFSET parameter is of type ‘off64_t’. This also requires that
  2729. the stream STREAM was opened using either ‘fopen64’, ‘freopen64’,
  2730. or ‘tmpfile64’ since otherwise the underlying file operations to
  2731. position the file pointer beyond the 2^31 bytes limit might fail.
  2732. If the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a 32
  2733. bits machine this function is available under the name ‘fseeko’ and
  2734. so transparently replaces the old interface.
  2735. *Portability Note:* In non-POSIX systems, ‘ftell’, ‘ftello’, ‘fseek’
  2736. and ‘fseeko’ might work reliably only on binary streams. *Note Binary
  2737. Streams::.
  2738. The following symbolic constants are defined for use as the WHENCE
  2739. argument to ‘fseek’. They are also used with the ‘lseek’ function
  2740. (*note I/O Primitives::) and to specify offsets for file locks (*note
  2741. Control Operations::).
  2742. -- Macro: int SEEK_SET
  2743. This is an integer constant which, when used as the WHENCE argument
  2744. to the ‘fseek’ or ‘fseeko’ functions, specifies that the offset
  2745. provided is relative to the beginning of the file.
  2746. -- Macro: int SEEK_CUR
  2747. This is an integer constant which, when used as the WHENCE argument
  2748. to the ‘fseek’ or ‘fseeko’ functions, specifies that the offset
  2749. provided is relative to the current file position.
  2750. -- Macro: int SEEK_END
  2751. This is an integer constant which, when used as the WHENCE argument
  2752. to the ‘fseek’ or ‘fseeko’ functions, specifies that the offset
  2753. provided is relative to the end of the file.
  2754. -- Function: void rewind (FILE *STREAM)
  2755. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  2756. | *Note POSIX Safety Concepts::.
  2757. The ‘rewind’ function positions the stream STREAM at the beginning
  2758. of the file. It is equivalent to calling ‘fseek’ or ‘fseeko’ on
  2759. the STREAM with an OFFSET argument of ‘0L’ and a WHENCE argument of
  2760. ‘SEEK_SET’, except that the return value is discarded and the error
  2761. indicator for the stream is reset.
  2762. These three aliases for the ‘SEEK_…’ constants exist for the sake of
  2763. compatibility with older BSD systems. They are defined in two different
  2764. header files: ‘fcntl.h’ and ‘sys/file.h’.
  2765. ‘L_SET’
  2766. An alias for ‘SEEK_SET’.
  2767. ‘L_INCR’
  2768. An alias for ‘SEEK_CUR’.
  2769. ‘L_XTND’
  2770. An alias for ‘SEEK_END’.
  2771. 
  2772. File: libc.info, Node: Portable Positioning, Next: Stream Buffering, Prev: File Positioning, Up: I/O on Streams
  2773. 12.19 Portable File-Position Functions
  2774. ======================================
  2775. On GNU systems, the file position is truly a character count. You can
  2776. specify any character count value as an argument to ‘fseek’ or ‘fseeko’
  2777. and get reliable results for any random access file. However, some ISO C
  2778. systems do not represent file positions in this way.
  2779. On some systems where text streams truly differ from binary streams,
  2780. it is impossible to represent the file position of a text stream as a
  2781. count of characters from the beginning of the file. For example, the
  2782. file position on some systems must encode both a record offset within
  2783. the file, and a character offset within the record.
  2784. As a consequence, if you want your programs to be portable to these
  2785. systems, you must observe certain rules:
  2786. • The value returned from ‘ftell’ on a text stream has no predictable
  2787. relationship to the number of characters you have read so far. The
  2788. only thing you can rely on is that you can use it subsequently as
  2789. the OFFSET argument to ‘fseek’ or ‘fseeko’ to move back to the same
  2790. file position.
  2791. • In a call to ‘fseek’ or ‘fseeko’ on a text stream, either the
  2792. OFFSET must be zero, or WHENCE must be ‘SEEK_SET’ and the OFFSET
  2793. must be the result of an earlier call to ‘ftell’ on the same
  2794. stream.
  2795. • The value of the file position indicator of a text stream is
  2796. undefined while there are characters that have been pushed back
  2797. with ‘ungetc’ that haven’t been read or discarded. *Note
  2798. Unreading::.
  2799. But even if you observe these rules, you may still have trouble for
  2800. long files, because ‘ftell’ and ‘fseek’ use a ‘long int’ value to
  2801. represent the file position. This type may not have room to encode all
  2802. the file positions in a large file. Using the ‘ftello’ and ‘fseeko’
  2803. functions might help here since the ‘off_t’ type is expected to be able
  2804. to hold all file position values but this still does not help to handle
  2805. additional information which must be associated with a file position.
  2806. So if you do want to support systems with peculiar encodings for the
  2807. file positions, it is better to use the functions ‘fgetpos’ and
  2808. ‘fsetpos’ instead. These functions represent the file position using
  2809. the data type ‘fpos_t’, whose internal representation varies from system
  2810. to system.
  2811. These symbols are declared in the header file ‘stdio.h’.
  2812. -- Data Type: fpos_t
  2813. This is the type of an object that can encode information about the
  2814. file position of a stream, for use by the functions ‘fgetpos’ and
  2815. ‘fsetpos’.
  2816. In the GNU C Library, ‘fpos_t’ is an opaque data structure that
  2817. contains internal data to represent file offset and conversion
  2818. state information. In other systems, it might have a different
  2819. internal representation.
  2820. When compiling with ‘_FILE_OFFSET_BITS == 64’ on a 32 bit machine
  2821. this type is in fact equivalent to ‘fpos64_t’ since the LFS
  2822. interface transparently replaces the old interface.
  2823. -- Data Type: fpos64_t
  2824. This is the type of an object that can encode information about the
  2825. file position of a stream, for use by the functions ‘fgetpos64’ and
  2826. ‘fsetpos64’.
  2827. In the GNU C Library, ‘fpos64_t’ is an opaque data structure that
  2828. contains internal data to represent file offset and conversion
  2829. state information. In other systems, it might have a different
  2830. internal representation.
  2831. -- Function: int fgetpos (FILE *STREAM, fpos_t *POSITION)
  2832. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  2833. | *Note POSIX Safety Concepts::.
  2834. This function stores the value of the file position indicator for
  2835. the stream STREAM in the ‘fpos_t’ object pointed to by POSITION.
  2836. If successful, ‘fgetpos’ returns zero; otherwise it returns a
  2837. nonzero value and stores an implementation-defined positive value
  2838. in ‘errno’.
  2839. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
  2840. 32 bit system the function is in fact ‘fgetpos64’. I.e., the LFS
  2841. interface transparently replaces the old interface.
  2842. -- Function: int fgetpos64 (FILE *STREAM, fpos64_t *POSITION)
  2843. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  2844. | *Note POSIX Safety Concepts::.
  2845. This function is similar to ‘fgetpos’ but the file position is
  2846. returned in a variable of type ‘fpos64_t’ to which POSITION points.
  2847. If the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a 32
  2848. bits machine this function is available under the name ‘fgetpos’
  2849. and so transparently replaces the old interface.
  2850. -- Function: int fsetpos (FILE *STREAM, const fpos_t *POSITION)
  2851. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  2852. | *Note POSIX Safety Concepts::.
  2853. This function sets the file position indicator for the stream
  2854. STREAM to the position POSITION, which must have been set by a
  2855. previous call to ‘fgetpos’ on the same stream. If successful,
  2856. ‘fsetpos’ clears the end-of-file indicator on the stream, discards
  2857. any characters that were “pushed back” by the use of ‘ungetc’, and
  2858. returns a value of zero. Otherwise, ‘fsetpos’ returns a nonzero
  2859. value and stores an implementation-defined positive value in
  2860. ‘errno’.
  2861. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
  2862. 32 bit system the function is in fact ‘fsetpos64’. I.e., the LFS
  2863. interface transparently replaces the old interface.
  2864. -- Function: int fsetpos64 (FILE *STREAM, const fpos64_t *POSITION)
  2865. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  2866. | *Note POSIX Safety Concepts::.
  2867. This function is similar to ‘fsetpos’ but the file position used
  2868. for positioning is provided in a variable of type ‘fpos64_t’ to
  2869. which POSITION points.
  2870. If the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a 32
  2871. bits machine this function is available under the name ‘fsetpos’
  2872. and so transparently replaces the old interface.
  2873. 
  2874. File: libc.info, Node: Stream Buffering, Next: Other Kinds of Streams, Prev: Portable Positioning, Up: I/O on Streams
  2875. 12.20 Stream Buffering
  2876. ======================
  2877. Characters that are written to a stream are normally accumulated and
  2878. transmitted asynchronously to the file in a block, instead of appearing
  2879. as soon as they are output by the application program. Similarly,
  2880. streams often retrieve input from the host environment in blocks rather
  2881. than on a character-by-character basis. This is called "buffering".
  2882. If you are writing programs that do interactive input and output
  2883. using streams, you need to understand how buffering works when you
  2884. design the user interface to your program. Otherwise, you might find
  2885. that output (such as progress or prompt messages) doesn’t appear when
  2886. you intended it to, or displays some other unexpected behavior.
  2887. This section deals only with controlling when characters are
  2888. transmitted between the stream and the file or device, and _not_ with
  2889. how things like echoing, flow control, and the like are handled on
  2890. specific classes of devices. For information on common control
  2891. operations on terminal devices, see *note Low-Level Terminal
  2892. Interface::.
  2893. You can bypass the stream buffering facilities altogether by using
  2894. the low-level input and output functions that operate on file
  2895. descriptors instead. *Note Low-Level I/O::.
  2896. * Menu:
  2897. * Buffering Concepts:: Terminology is defined here.
  2898. * Flushing Buffers:: How to ensure that output buffers are flushed.
  2899. * Controlling Buffering:: How to specify what kind of buffering to use.
  2900. 
  2901. File: libc.info, Node: Buffering Concepts, Next: Flushing Buffers, Up: Stream Buffering
  2902. 12.20.1 Buffering Concepts
  2903. --------------------------
  2904. There are three different kinds of buffering strategies:
  2905. • Characters written to or read from an "unbuffered" stream are
  2906. transmitted individually to or from the file as soon as possible.
  2907. • Characters written to a "line buffered" stream are transmitted to
  2908. the file in blocks when a newline character is encountered.
  2909. • Characters written to or read from a "fully buffered" stream are
  2910. transmitted to or from the file in blocks of arbitrary size.
  2911. Newly opened streams are normally fully buffered, with one exception:
  2912. a stream connected to an interactive device such as a terminal is
  2913. initially line buffered. *Note Controlling Buffering::, for information
  2914. on how to select a different kind of buffering. Usually the automatic
  2915. selection gives you the most convenient kind of buffering for the file
  2916. or device you open.
  2917. The use of line buffering for interactive devices implies that output
  2918. messages ending in a newline will appear immediately—which is usually
  2919. what you want. Output that doesn’t end in a newline might or might not
  2920. show up immediately, so if you want them to appear immediately, you
  2921. should flush buffered output explicitly with ‘fflush’, as described in
  2922. *note Flushing Buffers::.
  2923. 
  2924. File: libc.info, Node: Flushing Buffers, Next: Controlling Buffering, Prev: Buffering Concepts, Up: Stream Buffering
  2925. 12.20.2 Flushing Buffers
  2926. ------------------------
  2927. "Flushing" output on a buffered stream means transmitting all
  2928. accumulated characters to the file. There are many circumstances when
  2929. buffered output on a stream is flushed automatically:
  2930. • When you try to do output and the output buffer is full.
  2931. • When the stream is closed. *Note Closing Streams::.
  2932. • When the program terminates by calling ‘exit’. *Note Normal
  2933. Termination::.
  2934. • When a newline is written, if the stream is line buffered.
  2935. • Whenever an input operation on _any_ stream actually reads data
  2936. from its file.
  2937. If you want to flush the buffered output at another time, call
  2938. ‘fflush’, which is declared in the header file ‘stdio.h’.
  2939. -- Function: int fflush (FILE *STREAM)
  2940. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  2941. | *Note POSIX Safety Concepts::.
  2942. This function causes any buffered output on STREAM to be delivered
  2943. to the file. If STREAM is a null pointer, then ‘fflush’ causes
  2944. buffered output on _all_ open output streams to be flushed.
  2945. This function returns ‘EOF’ if a write error occurs, or zero
  2946. otherwise.
  2947. -- Function: int fflush_unlocked (FILE *STREAM)
  2948. Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
  2949. corrupt | *Note POSIX Safety Concepts::.
  2950. The ‘fflush_unlocked’ function is equivalent to the ‘fflush’
  2951. function except that it does not implicitly lock the stream.
  2952. The ‘fflush’ function can be used to flush all streams currently
  2953. opened. While this is useful in some situations it does often more than
  2954. necessary since it might be done in situations when terminal input is
  2955. required and the program wants to be sure that all output is visible on
  2956. the terminal. But this means that only line buffered streams have to be
  2957. flushed. Solaris introduced a function especially for this. It was
  2958. always available in the GNU C Library in some form but never officially
  2959. exported.
  2960. -- Function: void _flushlbf (void)
  2961. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  2962. | *Note POSIX Safety Concepts::.
  2963. The ‘_flushlbf’ function flushes all line buffered streams
  2964. currently opened.
  2965. This function is declared in the ‘stdio_ext.h’ header.
  2966. *Compatibility Note:* Some brain-damaged operating systems have been
  2967. known to be so thoroughly fixated on line-oriented input and output that
  2968. flushing a line buffered stream causes a newline to be written!
  2969. Fortunately, this “feature” seems to be becoming less common. You do
  2970. not need to worry about this with the GNU C Library.
  2971. In some situations it might be useful to not flush the output pending
  2972. for a stream but instead simply forget it. If transmission is costly
  2973. and the output is not needed anymore this is valid reasoning. In this
  2974. situation a non-standard function introduced in Solaris and available in
  2975. the GNU C Library can be used.
  2976. -- Function: void __fpurge (FILE *STREAM)
  2977. Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Unsafe
  2978. corrupt | *Note POSIX Safety Concepts::.
  2979. The ‘__fpurge’ function causes the buffer of the stream STREAM to
  2980. be emptied. If the stream is currently in read mode all input in
  2981. the buffer is lost. If the stream is in output mode the buffered
  2982. output is not written to the device (or whatever other underlying
  2983. storage) and the buffer is cleared.
  2984. This function is declared in ‘stdio_ext.h’.
  2985. 
  2986. File: libc.info, Node: Controlling Buffering, Prev: Flushing Buffers, Up: Stream Buffering
  2987. 12.20.3 Controlling Which Kind of Buffering
  2988. -------------------------------------------
  2989. After opening a stream (but before any other operations have been
  2990. performed on it), you can explicitly specify what kind of buffering you
  2991. want it to have using the ‘setvbuf’ function.
  2992. The facilities listed in this section are declared in the header file
  2993. ‘stdio.h’.
  2994. -- Function: int setvbuf (FILE *STREAM, char *BUF, int MODE, size_t
  2995. SIZE)
  2996. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  2997. | *Note POSIX Safety Concepts::.
  2998. This function is used to specify that the stream STREAM should have
  2999. the buffering mode MODE, which can be either ‘_IOFBF’ (for full
  3000. buffering), ‘_IOLBF’ (for line buffering), or ‘_IONBF’ (for
  3001. unbuffered input/output).
  3002. If you specify a null pointer as the BUF argument, then ‘setvbuf’
  3003. allocates a buffer itself using ‘malloc’. This buffer will be
  3004. freed when you close the stream.
  3005. Otherwise, BUF should be a character array that can hold at least
  3006. SIZE characters. You should not free the space for this array as
  3007. long as the stream remains open and this array remains its buffer.
  3008. You should usually either allocate it statically, or ‘malloc’
  3009. (*note Unconstrained Allocation::) the buffer. Using an automatic
  3010. array is not a good idea unless you close the file before exiting
  3011. the block that declares the array.
  3012. While the array remains a stream buffer, the stream I/O functions
  3013. will use the buffer for their internal purposes. You shouldn’t try
  3014. to access the values in the array directly while the stream is
  3015. using it for buffering.
  3016. The ‘setvbuf’ function returns zero on success, or a nonzero value
  3017. if the value of MODE is not valid or if the request could not be
  3018. honored.
  3019. -- Macro: int _IOFBF
  3020. The value of this macro is an integer constant expression that can
  3021. be used as the MODE argument to the ‘setvbuf’ function to specify
  3022. that the stream should be fully buffered.
  3023. -- Macro: int _IOLBF
  3024. The value of this macro is an integer constant expression that can
  3025. be used as the MODE argument to the ‘setvbuf’ function to specify
  3026. that the stream should be line buffered.
  3027. -- Macro: int _IONBF
  3028. The value of this macro is an integer constant expression that can
  3029. be used as the MODE argument to the ‘setvbuf’ function to specify
  3030. that the stream should be unbuffered.
  3031. -- Macro: int BUFSIZ
  3032. The value of this macro is an integer constant expression that is
  3033. good to use for the SIZE argument to ‘setvbuf’. This value is
  3034. guaranteed to be at least ‘256’.
  3035. The value of ‘BUFSIZ’ is chosen on each system so as to make stream
  3036. I/O efficient. So it is a good idea to use ‘BUFSIZ’ as the size
  3037. for the buffer when you call ‘setvbuf’.
  3038. Actually, you can get an even better value to use for the buffer
  3039. size by means of the ‘fstat’ system call: it is found in the
  3040. ‘st_blksize’ field of the file attributes. *Note Attribute
  3041. Meanings::.
  3042. Sometimes people also use ‘BUFSIZ’ as the allocation size of
  3043. buffers used for related purposes, such as strings used to receive
  3044. a line of input with ‘fgets’ (*note Character Input::). There is
  3045. no particular reason to use ‘BUFSIZ’ for this instead of any other
  3046. integer, except that it might lead to doing I/O in chunks of an
  3047. efficient size.
  3048. -- Function: void setbuf (FILE *STREAM, char *BUF)
  3049. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  3050. | *Note POSIX Safety Concepts::.
  3051. If BUF is a null pointer, the effect of this function is equivalent
  3052. to calling ‘setvbuf’ with a MODE argument of ‘_IONBF’. Otherwise,
  3053. it is equivalent to calling ‘setvbuf’ with BUF, and a MODE of
  3054. ‘_IOFBF’ and a SIZE argument of ‘BUFSIZ’.
  3055. The ‘setbuf’ function is provided for compatibility with old code;
  3056. use ‘setvbuf’ in all new programs.
  3057. -- Function: void setbuffer (FILE *STREAM, char *BUF, size_t SIZE)
  3058. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  3059. | *Note POSIX Safety Concepts::.
  3060. If BUF is a null pointer, this function makes STREAM unbuffered.
  3061. Otherwise, it makes STREAM fully buffered using BUF as the buffer.
  3062. The SIZE argument specifies the length of BUF.
  3063. This function is provided for compatibility with old BSD code. Use
  3064. ‘setvbuf’ instead.
  3065. -- Function: void setlinebuf (FILE *STREAM)
  3066. Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
  3067. | *Note POSIX Safety Concepts::.
  3068. This function makes STREAM be line buffered, and allocates the
  3069. buffer for you.
  3070. This function is provided for compatibility with old BSD code. Use
  3071. ‘setvbuf’ instead.
  3072. It is possible to query whether a given stream is line buffered or
  3073. not using a non-standard function introduced in Solaris and available in
  3074. the GNU C Library.
  3075. -- Function: int __flbf (FILE *STREAM)
  3076. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3077. Concepts::.
  3078. The ‘__flbf’ function will return a nonzero value in case the
  3079. stream STREAM is line buffered. Otherwise the return value is
  3080. zero.
  3081. This function is declared in the ‘stdio_ext.h’ header.
  3082. Two more extensions allow to determine the size of the buffer and how
  3083. much of it is used. These functions were also introduced in Solaris.
  3084. -- Function: size_t __fbufsize (FILE *STREAM)
  3085. Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Safe |
  3086. *Note POSIX Safety Concepts::.
  3087. The ‘__fbufsize’ function return the size of the buffer in the
  3088. stream STREAM. This value can be used to optimize the use of the
  3089. stream.
  3090. This function is declared in the ‘stdio_ext.h’ header.
  3091. -- Function: size_t __fpending (FILE *STREAM)
  3092. Preliminary: | MT-Safe race:stream | AS-Unsafe corrupt | AC-Safe |
  3093. *Note POSIX Safety Concepts::.
  3094. The ‘__fpending’ function returns the number of bytes currently in
  3095. the output buffer. For wide-oriented streams the measuring unit is
  3096. wide characters. This function should not be used on buffers in
  3097. read mode or opened read-only.
  3098. This function is declared in the ‘stdio_ext.h’ header.
  3099. 
  3100. File: libc.info, Node: Other Kinds of Streams, Next: Formatted Messages, Prev: Stream Buffering, Up: I/O on Streams
  3101. 12.21 Other Kinds of Streams
  3102. ============================
  3103. The GNU C Library provides ways for you to define additional kinds of
  3104. streams that do not necessarily correspond to an open file.
  3105. One such type of stream takes input from or writes output to a
  3106. string. These kinds of streams are used internally to implement the
  3107. ‘sprintf’ and ‘sscanf’ functions. You can also create such a stream
  3108. explicitly, using the functions described in *note String Streams::.
  3109. More generally, you can define streams that do input/output to
  3110. arbitrary objects using functions supplied by your program. This
  3111. protocol is discussed in *note Custom Streams::.
  3112. *Portability Note:* The facilities described in this section are
  3113. specific to GNU. Other systems or C implementations might or might not
  3114. provide equivalent functionality.
  3115. * Menu:
  3116. * String Streams:: Streams that get data from or put data in
  3117. a string or memory buffer.
  3118. * Custom Streams:: Defining your own streams with an arbitrary
  3119. input data source and/or output data sink.
  3120. 
  3121. File: libc.info, Node: String Streams, Next: Custom Streams, Up: Other Kinds of Streams
  3122. 12.21.1 String Streams
  3123. ----------------------
  3124. The ‘fmemopen’ and ‘open_memstream’ functions allow you to do I/O to a
  3125. string or memory buffer. These facilities are declared in ‘stdio.h’.
  3126. -- Function: FILE * fmemopen (void *BUF, size_t SIZE, const char
  3127. *OPENTYPE)
  3128. Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem lock |
  3129. *Note POSIX Safety Concepts::.
  3130. This function opens a stream that allows the access specified by
  3131. the OPENTYPE argument, that reads from or writes to the buffer
  3132. specified by the argument BUF. This array must be at least SIZE
  3133. bytes long.
  3134. If you specify a null pointer as the BUF argument, ‘fmemopen’
  3135. dynamically allocates an array SIZE bytes long (as with ‘malloc’;
  3136. *note Unconstrained Allocation::). This is really only useful if
  3137. you are going to write things to the buffer and then read them back
  3138. in again, because you have no way of actually getting a pointer to
  3139. the buffer (for this, try ‘open_memstream’, below). The buffer is
  3140. freed when the stream is closed.
  3141. The argument OPENTYPE is the same as in ‘fopen’ (*note Opening
  3142. Streams::). If the OPENTYPE specifies append mode, then the
  3143. initial file position is set to the first null character in the
  3144. buffer. Otherwise the initial file position is at the beginning of
  3145. the buffer.
  3146. When a stream open for writing is flushed or closed, a null
  3147. character (zero byte) is written at the end of the buffer if it
  3148. fits. You should add an extra byte to the SIZE argument to account
  3149. for this. Attempts to write more than SIZE bytes to the buffer
  3150. result in an error.
  3151. For a stream open for reading, null characters (zero bytes) in the
  3152. buffer do not count as “end of file”. Read operations indicate end
  3153. of file only when the file position advances past SIZE bytes. So,
  3154. if you want to read characters from a null-terminated string, you
  3155. should supply the length of the string as the SIZE argument.
  3156. Here is an example of using ‘fmemopen’ to create a stream for reading
  3157. from a string:
  3158. #include <stdio.h>
  3159. static char buffer[] = "foobar";
  3160. int
  3161. main (void)
  3162. {
  3163. int ch;
  3164. FILE *stream;
  3165. stream = fmemopen (buffer, strlen (buffer), "r");
  3166. while ((ch = fgetc (stream)) != EOF)
  3167. printf ("Got %c\n", ch);
  3168. fclose (stream);
  3169. return 0;
  3170. }
  3171. This program produces the following output:
  3172. Got f
  3173. Got o
  3174. Got o
  3175. Got b
  3176. Got a
  3177. Got r
  3178. -- Function: FILE * open_memstream (char **PTR, size_t *SIZELOC)
  3179. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  3180. POSIX Safety Concepts::.
  3181. This function opens a stream for writing to a buffer. The buffer
  3182. is allocated dynamically and grown as necessary, using ‘malloc’.
  3183. After you’ve closed the stream, this buffer is your responsibility
  3184. to clean up using ‘free’ or ‘realloc’. *Note Unconstrained
  3185. Allocation::.
  3186. When the stream is closed with ‘fclose’ or flushed with ‘fflush’,
  3187. the locations PTR and SIZELOC are updated to contain the pointer to
  3188. the buffer and its size. The values thus stored remain valid only
  3189. as long as no further output on the stream takes place. If you do
  3190. more output, you must flush the stream again to store new values
  3191. before you use them again.
  3192. A null character is written at the end of the buffer. This null
  3193. character is _not_ included in the size value stored at SIZELOC.
  3194. You can move the stream’s file position with ‘fseek’ or ‘fseeko’
  3195. (*note File Positioning::). Moving the file position past the end
  3196. of the data already written fills the intervening space with
  3197. zeroes.
  3198. Here is an example of using ‘open_memstream’:
  3199. #include <stdio.h>
  3200. int
  3201. main (void)
  3202. {
  3203. char *bp;
  3204. size_t size;
  3205. FILE *stream;
  3206. stream = open_memstream (&bp, &size);
  3207. fprintf (stream, "hello");
  3208. fflush (stream);
  3209. printf ("buf = `%s', size = %zu\n", bp, size);
  3210. fprintf (stream, ", world");
  3211. fclose (stream);
  3212. printf ("buf = `%s', size = %zu\n", bp, size);
  3213. return 0;
  3214. }
  3215. This program produces the following output:
  3216. buf = `hello', size = 5
  3217. buf = `hello, world', size = 12
  3218. 
  3219. File: libc.info, Node: Custom Streams, Prev: String Streams, Up: Other Kinds of Streams
  3220. 12.21.2 Programming Your Own Custom Streams
  3221. -------------------------------------------
  3222. This section describes how you can make a stream that gets input from an
  3223. arbitrary data source or writes output to an arbitrary data sink
  3224. programmed by you. We call these "custom streams". The functions and
  3225. types described here are all GNU extensions.
  3226. * Menu:
  3227. * Streams and Cookies:: The "cookie" records where to fetch or
  3228. store data that is read or written.
  3229. * Hook Functions:: How you should define the four "hook
  3230. functions" that a custom stream needs.
  3231. 
  3232. File: libc.info, Node: Streams and Cookies, Next: Hook Functions, Up: Custom Streams
  3233. 12.21.2.1 Custom Streams and Cookies
  3234. ....................................
  3235. Inside every custom stream is a special object called the "cookie".
  3236. This is an object supplied by you which records where to fetch or store
  3237. the data read or written. It is up to you to define a data type to use
  3238. for the cookie. The stream functions in the library never refer
  3239. directly to its contents, and they don’t even know what the type is;
  3240. they record its address with type ‘void *’.
  3241. To implement a custom stream, you must specify _how_ to fetch or
  3242. store the data in the specified place. You do this by defining "hook
  3243. functions" to read, write, change “file position”, and close the stream.
  3244. All four of these functions will be passed the stream’s cookie so they
  3245. can tell where to fetch or store the data. The library functions don’t
  3246. know what’s inside the cookie, but your functions will know.
  3247. When you create a custom stream, you must specify the cookie pointer,
  3248. and also the four hook functions stored in a structure of type
  3249. ‘cookie_io_functions_t’.
  3250. These facilities are declared in ‘stdio.h’.
  3251. -- Data Type: cookie_io_functions_t
  3252. This is a structure type that holds the functions that define the
  3253. communications protocol between the stream and its cookie. It has
  3254. the following members:
  3255. ‘cookie_read_function_t *read’
  3256. This is the function that reads data from the cookie. If the
  3257. value is a null pointer instead of a function, then read
  3258. operations on this stream always return ‘EOF’.
  3259. ‘cookie_write_function_t *write’
  3260. This is the function that writes data to the cookie. If the
  3261. value is a null pointer instead of a function, then data
  3262. written to the stream is discarded.
  3263. ‘cookie_seek_function_t *seek’
  3264. This is the function that performs the equivalent of file
  3265. positioning on the cookie. If the value is a null pointer
  3266. instead of a function, calls to ‘fseek’ or ‘fseeko’ on this
  3267. stream can only seek to locations within the buffer; any
  3268. attempt to seek outside the buffer will return an ‘ESPIPE’
  3269. error.
  3270. ‘cookie_close_function_t *close’
  3271. This function performs any appropriate cleanup on the cookie
  3272. when closing the stream. If the value is a null pointer
  3273. instead of a function, nothing special is done to close the
  3274. cookie when the stream is closed.
  3275. -- Function: FILE * fopencookie (void *COOKIE, const char *OPENTYPE,
  3276. cookie_io_functions_t IO-FUNCTIONS)
  3277. Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem lock |
  3278. *Note POSIX Safety Concepts::.
  3279. This function actually creates the stream for communicating with
  3280. the COOKIE using the functions in the IO-FUNCTIONS argument. The
  3281. OPENTYPE argument is interpreted as for ‘fopen’; see *note Opening
  3282. Streams::. (But note that the “truncate on open” option is
  3283. ignored.) The new stream is fully buffered.
  3284. The ‘fopencookie’ function returns the newly created stream, or a
  3285. null pointer in case of an error.
  3286. 
  3287. File: libc.info, Node: Hook Functions, Prev: Streams and Cookies, Up: Custom Streams
  3288. 12.21.2.2 Custom Stream Hook Functions
  3289. ......................................
  3290. Here are more details on how you should define the four hook functions
  3291. that a custom stream needs.
  3292. You should define the function to read data from the cookie as:
  3293. ssize_t READER (void *COOKIE, char *BUFFER, size_t SIZE)
  3294. This is very similar to the ‘read’ function; see *note I/O
  3295. Primitives::. Your function should transfer up to SIZE bytes into the
  3296. BUFFER, and return the number of bytes read, or zero to indicate
  3297. end-of-file. You can return a value of ‘-1’ to indicate an error.
  3298. You should define the function to write data to the cookie as:
  3299. ssize_t WRITER (void *COOKIE, const char *BUFFER, size_t SIZE)
  3300. This is very similar to the ‘write’ function; see *note I/O
  3301. Primitives::. Your function should transfer up to SIZE bytes from the
  3302. buffer, and return the number of bytes written. You can return a value
  3303. of ‘0’ to indicate an error. You must not return any negative value.
  3304. You should define the function to perform seek operations on the
  3305. cookie as:
  3306. int SEEKER (void *COOKIE, off64_t *POSITION, int WHENCE)
  3307. For this function, the POSITION and WHENCE arguments are interpreted
  3308. as for ‘fgetpos’; see *note Portable Positioning::.
  3309. After doing the seek operation, your function should store the
  3310. resulting file position relative to the beginning of the file in
  3311. POSITION. Your function should return a value of ‘0’ on success and
  3312. ‘-1’ to indicate an error.
  3313. You should define the function to do cleanup operations on the cookie
  3314. appropriate for closing the stream as:
  3315. int CLEANER (void *COOKIE)
  3316. Your function should return ‘-1’ to indicate an error, and ‘0’
  3317. otherwise.
  3318. -- Data Type: cookie_read_function_t
  3319. This is the data type that the read function for a custom stream
  3320. should have. If you declare the function as shown above, this is
  3321. the type it will have.
  3322. -- Data Type: cookie_write_function_t
  3323. The data type of the write function for a custom stream.
  3324. -- Data Type: cookie_seek_function_t
  3325. The data type of the seek function for a custom stream.
  3326. -- Data Type: cookie_close_function_t
  3327. The data type of the close function for a custom stream.
  3328. 
  3329. File: libc.info, Node: Formatted Messages, Prev: Other Kinds of Streams, Up: I/O on Streams
  3330. 12.22 Formatted Messages
  3331. ========================
  3332. On systems which are based on System V messages of programs (especially
  3333. the system tools) are printed in a strict form using the ‘fmtmsg’
  3334. function. The uniformity sometimes helps the user to interpret messages
  3335. and the strictness tests of the ‘fmtmsg’ function ensure that the
  3336. programmer follows some minimal requirements.
  3337. * Menu:
  3338. * Printing Formatted Messages:: The ‘fmtmsg’ function.
  3339. * Adding Severity Classes:: Add more severity classes.
  3340. * Example:: How to use ‘fmtmsg’ and ‘addseverity’.
  3341. 
  3342. File: libc.info, Node: Printing Formatted Messages, Next: Adding Severity Classes, Up: Formatted Messages
  3343. 12.22.1 Printing Formatted Messages
  3344. -----------------------------------
  3345. Messages can be printed to standard error and/or to the console. To
  3346. select the destination the programmer can use the following two values,
  3347. bitwise OR combined if wanted, for the CLASSIFICATION parameter of
  3348. ‘fmtmsg’:
  3349. ‘MM_PRINT’
  3350. Display the message in standard error.
  3351. ‘MM_CONSOLE’
  3352. Display the message on the system console.
  3353. The erroneous piece of the system can be signalled by exactly one of
  3354. the following values which also is bitwise ORed with the CLASSIFICATION
  3355. parameter to ‘fmtmsg’:
  3356. ‘MM_HARD’
  3357. The source of the condition is some hardware.
  3358. ‘MM_SOFT’
  3359. The source of the condition is some software.
  3360. ‘MM_FIRM’
  3361. The source of the condition is some firmware.
  3362. A third component of the CLASSIFICATION parameter to ‘fmtmsg’ can
  3363. describe the part of the system which detects the problem. This is done
  3364. by using exactly one of the following values:
  3365. ‘MM_APPL’
  3366. The erroneous condition is detected by the application.
  3367. ‘MM_UTIL’
  3368. The erroneous condition is detected by a utility.
  3369. ‘MM_OPSYS’
  3370. The erroneous condition is detected by the operating system.
  3371. A last component of CLASSIFICATION can signal the results of this
  3372. message. Exactly one of the following values can be used:
  3373. ‘MM_RECOVER’
  3374. It is a recoverable error.
  3375. ‘MM_NRECOV’
  3376. It is a non-recoverable error.
  3377. -- Function: int fmtmsg (long int CLASSIFICATION, const char *LABEL,
  3378. int SEVERITY, const char *TEXT, const char *ACTION, const char
  3379. *TAG)
  3380. Preliminary: | MT-Safe | AS-Unsafe lock | AC-Safe | *Note POSIX
  3381. Safety Concepts::.
  3382. Display a message described by its parameters on the device(s)
  3383. specified in the CLASSIFICATION parameter. The LABEL parameter
  3384. identifies the source of the message. The string should consist of
  3385. two colon separated parts where the first part has not more than 10
  3386. and the second part not more than 14 characters. The TEXT
  3387. parameter describes the condition of the error, the ACTION
  3388. parameter possible steps to recover from the error and the TAG
  3389. parameter is a reference to the online documentation where more
  3390. information can be found. It should contain the LABEL value and a
  3391. unique identification number.
  3392. Each of the parameters can be a special value which means this
  3393. value is to be omitted. The symbolic names for these values are:
  3394. ‘MM_NULLLBL’
  3395. Ignore LABEL parameter.
  3396. ‘MM_NULLSEV’
  3397. Ignore SEVERITY parameter.
  3398. ‘MM_NULLMC’
  3399. Ignore CLASSIFICATION parameter. This implies that nothing is
  3400. actually printed.
  3401. ‘MM_NULLTXT’
  3402. Ignore TEXT parameter.
  3403. ‘MM_NULLACT’
  3404. Ignore ACTION parameter.
  3405. ‘MM_NULLTAG’
  3406. Ignore TAG parameter.
  3407. There is another way certain fields can be omitted from the output
  3408. to standard error. This is described below in the description of
  3409. environment variables influencing the behavior.
  3410. The SEVERITY parameter can have one of the values in the following
  3411. table:
  3412. ‘MM_NOSEV’
  3413. Nothing is printed, this value is the same as ‘MM_NULLSEV’.
  3414. ‘MM_HALT’
  3415. This value is printed as ‘HALT’.
  3416. ‘MM_ERROR’
  3417. This value is printed as ‘ERROR’.
  3418. ‘MM_WARNING’
  3419. This value is printed as ‘WARNING’.
  3420. ‘MM_INFO’
  3421. This value is printed as ‘INFO’.
  3422. The numeric value of these five macros are between ‘0’ and ‘4’.
  3423. Using the environment variable ‘SEV_LEVEL’ or using the
  3424. ‘addseverity’ function one can add more severity levels with their
  3425. corresponding string to print. This is described below (*note
  3426. Adding Severity Classes::).
  3427. If no parameter is ignored the output looks like this:
  3428. LABEL: SEVERITY-STRING: TEXT
  3429. TO FIX: ACTION TAG
  3430. The colons, new line characters and the ‘TO FIX’ string are
  3431. inserted if necessary, i.e., if the corresponding parameter is not
  3432. ignored.
  3433. This function is specified in the X/Open Portability Guide. It is
  3434. also available on all systems derived from System V.
  3435. The function returns the value ‘MM_OK’ if no error occurred. If
  3436. only the printing to standard error failed, it returns ‘MM_NOMSG’.
  3437. If printing to the console fails, it returns ‘MM_NOCON’. If
  3438. nothing is printed ‘MM_NOTOK’ is returned. Among situations where
  3439. all outputs fail this last value is also returned if a parameter
  3440. value is incorrect.
  3441. There are two environment variables which influence the behavior of
  3442. ‘fmtmsg’. The first is ‘MSGVERB’. It is used to control the output
  3443. actually happening on standard error (_not_ the console output). Each
  3444. of the five fields can explicitly be enabled. To do this the user has
  3445. to put the ‘MSGVERB’ variable with a format like the following in the
  3446. environment before calling the ‘fmtmsg’ function the first time:
  3447. MSGVERB=KEYWORD[:KEYWORD[:…]]
  3448. Valid KEYWORDs are ‘label’, ‘severity’, ‘text’, ‘action’, and ‘tag’.
  3449. If the environment variable is not given or is the empty string, a not
  3450. supported keyword is given or the value is somehow else invalid, no part
  3451. of the message is masked out.
  3452. The second environment variable which influences the behavior of
  3453. ‘fmtmsg’ is ‘SEV_LEVEL’. This variable and the change in the behavior
  3454. of ‘fmtmsg’ is not specified in the X/Open Portability Guide. It is
  3455. available in System V systems, though. It can be used to introduce new
  3456. severity levels. By default, only the five severity levels described
  3457. above are available. Any other numeric value would make ‘fmtmsg’ print
  3458. nothing.
  3459. If the user puts ‘SEV_LEVEL’ with a format like
  3460. SEV_LEVEL=[DESCRIPTION[:DESCRIPTION[:…]]]
  3461. in the environment of the process before the first call to ‘fmtmsg’,
  3462. where DESCRIPTION has a value of the form
  3463. SEVERITY-KEYWORD,LEVEL,PRINTSTRING
  3464. The SEVERITY-KEYWORD part is not used by ‘fmtmsg’ but it has to be
  3465. present. The LEVEL part is a string representation of a number. The
  3466. numeric value must be a number greater than 4. This value must be used
  3467. in the SEVERITY parameter of ‘fmtmsg’ to select this class. It is not
  3468. possible to overwrite any of the predefined classes. The PRINTSTRING is
  3469. the string printed when a message of this class is processed by ‘fmtmsg’
  3470. (see above, ‘fmtsmg’ does not print the numeric value but instead the
  3471. string representation).
  3472. 
  3473. File: libc.info, Node: Adding Severity Classes, Next: Example, Prev: Printing Formatted Messages, Up: Formatted Messages
  3474. 12.22.2 Adding Severity Classes
  3475. -------------------------------
  3476. There is another possibility to introduce severity classes besides using
  3477. the environment variable ‘SEV_LEVEL’. This simplifies the task of
  3478. introducing new classes in a running program. One could use the
  3479. ‘setenv’ or ‘putenv’ function to set the environment variable, but this
  3480. is toilsome.
  3481. -- Function: int addseverity (int SEVERITY, const char *STRING)
  3482. Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock mem |
  3483. *Note POSIX Safety Concepts::.
  3484. This function allows the introduction of new severity classes which
  3485. can be addressed by the SEVERITY parameter of the ‘fmtmsg’
  3486. function. The SEVERITY parameter of ‘addseverity’ must match the
  3487. value for the parameter with the same name of ‘fmtmsg’, and STRING
  3488. is the string printed in the actual messages instead of the numeric
  3489. value.
  3490. If STRING is ‘NULL’ the severity class with the numeric value
  3491. according to SEVERITY is removed.
  3492. It is not possible to overwrite or remove one of the default
  3493. severity classes. All calls to ‘addseverity’ with SEVERITY set to
  3494. one of the values for the default classes will fail.
  3495. The return value is ‘MM_OK’ if the task was successfully performed.
  3496. If the return value is ‘MM_NOTOK’ something went wrong. This could
  3497. mean that no more memory is available or a class is not available
  3498. when it has to be removed.
  3499. This function is not specified in the X/Open Portability Guide
  3500. although the ‘fmtsmg’ function is. It is available on System V
  3501. systems.
  3502. 
  3503. File: libc.info, Node: Example, Prev: Adding Severity Classes, Up: Formatted Messages
  3504. 12.22.3 How to use ‘fmtmsg’ and ‘addseverity’
  3505. ---------------------------------------------
  3506. Here is a simple example program to illustrate the use of both functions
  3507. described in this section.
  3508. #include <fmtmsg.h>
  3509. int
  3510. main (void)
  3511. {
  3512. addseverity (5, "NOTE2");
  3513. fmtmsg (MM_PRINT, "only1field", MM_INFO, "text2", "action2", "tag2");
  3514. fmtmsg (MM_PRINT, "UX:cat", 5, "invalid syntax", "refer to manual",
  3515. "UX:cat:001");
  3516. fmtmsg (MM_PRINT, "label:foo", 6, "text", "action", "tag");
  3517. return 0;
  3518. }
  3519. The second call to ‘fmtmsg’ illustrates a use of this function as it
  3520. usually occurs on System V systems, which heavily use this function. It
  3521. seems worthwhile to give a short explanation here of how this system
  3522. works on System V. The value of the LABEL field (‘UX:cat’) says that the
  3523. error occurred in the Unix program ‘cat’. The explanation of the error
  3524. follows and the value for the ACTION parameter is ‘"refer to manual"’.
  3525. One could be more specific here, if necessary. The TAG field contains,
  3526. as proposed above, the value of the string given for the LABEL
  3527. parameter, and additionally a unique ID (‘001’ in this case). For a GNU
  3528. environment this string could contain a reference to the corresponding
  3529. node in the Info page for the program.
  3530. Running this program without specifying the ‘MSGVERB’ and ‘SEV_LEVEL’
  3531. function produces the following output:
  3532. UX:cat: NOTE2: invalid syntax
  3533. TO FIX: refer to manual UX:cat:001
  3534. We see the different fields of the message and how the extra glue
  3535. (the colons and the ‘TO FIX’ string) is printed. But only one of the
  3536. three calls to ‘fmtmsg’ produced output. The first call does not print
  3537. anything because the LABEL parameter is not in the correct form. The
  3538. string must contain two fields, separated by a colon (*note Printing
  3539. Formatted Messages::). The third ‘fmtmsg’ call produced no output since
  3540. the class with the numeric value ‘6’ is not defined. Although a class
  3541. with numeric value ‘5’ is also not defined by default, the call to
  3542. ‘addseverity’ introduces it and the second call to ‘fmtmsg’ produces the
  3543. above output.
  3544. When we change the environment of the program to contain
  3545. ‘SEV_LEVEL=XXX,6,NOTE’ when running it we get a different result:
  3546. UX:cat: NOTE2: invalid syntax
  3547. TO FIX: refer to manual UX:cat:001
  3548. label:foo: NOTE: text
  3549. TO FIX: action tag
  3550. Now the third call to ‘fmtmsg’ produced some output and we see how
  3551. the string ‘NOTE’ from the environment variable appears in the message.
  3552. Now we can reduce the output by specifying which fields we are
  3553. interested in. If we additionally set the environment variable
  3554. ‘MSGVERB’ to the value ‘severity:label:action’ we get the following
  3555. output:
  3556. UX:cat: NOTE2
  3557. TO FIX: refer to manual
  3558. label:foo: NOTE
  3559. TO FIX: action
  3560. I.e., the output produced by the TEXT and the TAG parameters to ‘fmtmsg’
  3561. vanished. Please also note that now there is no colon after the ‘NOTE’
  3562. and ‘NOTE2’ strings in the output. This is not necessary since there is
  3563. no more output on this line because the text is missing.
  3564. 
  3565. File: libc.info, Node: Low-Level I/O, Next: File System Interface, Prev: I/O on Streams, Up: Top
  3566. 13 Low-Level Input/Output
  3567. *************************
  3568. This chapter describes functions for performing low-level input/output
  3569. operations on file descriptors. These functions include the primitives
  3570. for the higher-level I/O functions described in *note I/O on Streams::,
  3571. as well as functions for performing low-level control operations for
  3572. which there are no equivalents on streams.
  3573. Stream-level I/O is more flexible and usually more convenient;
  3574. therefore, programmers generally use the descriptor-level functions only
  3575. when necessary. These are some of the usual reasons:
  3576. • For reading binary files in large chunks.
  3577. • For reading an entire file into core before parsing it.
  3578. • To perform operations other than data transfer, which can only be
  3579. done with a descriptor. (You can use ‘fileno’ to get the
  3580. descriptor corresponding to a stream.)
  3581. • To pass descriptors to a child process. (The child can create its
  3582. own stream to use a descriptor that it inherits, but cannot inherit
  3583. a stream directly.)
  3584. * Menu:
  3585. * Opening and Closing Files:: How to open and close file
  3586. descriptors.
  3587. * I/O Primitives:: Reading and writing data.
  3588. * File Position Primitive:: Setting a descriptor’s file
  3589. position.
  3590. * Descriptors and Streams:: Converting descriptor to stream
  3591. or vice-versa.
  3592. * Stream/Descriptor Precautions:: Precautions needed if you use both
  3593. descriptors and streams.
  3594. * Scatter-Gather:: Fast I/O to discontinuous buffers.
  3595. * Memory-mapped I/O:: Using files like memory.
  3596. * Waiting for I/O:: How to check for input or output
  3597. on multiple file descriptors.
  3598. * Synchronizing I/O:: Making sure all I/O actions completed.
  3599. * Asynchronous I/O:: Perform I/O in parallel.
  3600. * Control Operations:: Various other operations on file
  3601. descriptors.
  3602. * Duplicating Descriptors:: Fcntl commands for duplicating
  3603. file descriptors.
  3604. * Descriptor Flags:: Fcntl commands for manipulating
  3605. flags associated with file
  3606. descriptors.
  3607. * File Status Flags:: Fcntl commands for manipulating
  3608. flags associated with open files.
  3609. * File Locks:: Fcntl commands for implementing
  3610. file locking.
  3611. * Open File Description Locks:: Fcntl commands for implementing
  3612. open file description locking.
  3613. * Open File Description Locks Example:: An example of open file description lock
  3614. usage
  3615. * Interrupt Input:: Getting an asynchronous signal when
  3616. input arrives.
  3617. * IOCTLs:: Generic I/O Control operations.
  3618. 
  3619. File: libc.info, Node: Opening and Closing Files, Next: I/O Primitives, Up: Low-Level I/O
  3620. 13.1 Opening and Closing Files
  3621. ==============================
  3622. This section describes the primitives for opening and closing files
  3623. using file descriptors. The ‘open’ and ‘creat’ functions are declared
  3624. in the header file ‘fcntl.h’, while ‘close’ is declared in ‘unistd.h’.
  3625. -- Function: int open (const char *FILENAME, int FLAGS[, mode_t MODE])
  3626. Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
  3627. Concepts::.
  3628. The ‘open’ function creates and returns a new file descriptor for
  3629. the file named by FILENAME. Initially, the file position indicator
  3630. for the file is at the beginning of the file. The argument MODE
  3631. (*note Permission Bits::) is used only when a file is created, but
  3632. it doesn’t hurt to supply the argument in any case.
  3633. The FLAGS argument controls how the file is to be opened. This is
  3634. a bit mask; you create the value by the bitwise OR of the
  3635. appropriate parameters (using the ‘|’ operator in C). *Note File
  3636. Status Flags::, for the parameters available.
  3637. The normal return value from ‘open’ is a non-negative integer file
  3638. descriptor. In the case of an error, a value of -1 is returned
  3639. instead. In addition to the usual file name errors (*note File
  3640. Name Errors::), the following ‘errno’ error conditions are defined
  3641. for this function:
  3642. ‘EACCES’
  3643. The file exists but is not readable/writable as requested by
  3644. the FLAGS argument, or the file does not exist and the
  3645. directory is unwritable so it cannot be created.
  3646. ‘EEXIST’
  3647. Both ‘O_CREAT’ and ‘O_EXCL’ are set, and the named file
  3648. already exists.
  3649. ‘EINTR’
  3650. The ‘open’ operation was interrupted by a signal. *Note
  3651. Interrupted Primitives::.
  3652. ‘EISDIR’
  3653. The FLAGS argument specified write access, and the file is a
  3654. directory.
  3655. ‘EMFILE’
  3656. The process has too many files open. The maximum number of
  3657. file descriptors is controlled by the ‘RLIMIT_NOFILE’ resource
  3658. limit; *note Limits on Resources::.
  3659. ‘ENFILE’
  3660. The entire system, or perhaps the file system which contains
  3661. the directory, cannot support any additional open files at the
  3662. moment. (This problem cannot happen on GNU/Hurd systems.)
  3663. ‘ENOENT’
  3664. The named file does not exist, and ‘O_CREAT’ is not specified.
  3665. ‘ENOSPC’
  3666. The directory or file system that would contain the new file
  3667. cannot be extended, because there is no disk space left.
  3668. ‘ENXIO’
  3669. ‘O_NONBLOCK’ and ‘O_WRONLY’ are both set in the FLAGS
  3670. argument, the file named by FILENAME is a FIFO (*note Pipes
  3671. and FIFOs::), and no process has the file open for reading.
  3672. ‘EROFS’
  3673. The file resides on a read-only file system and any of
  3674. ‘O_WRONLY’, ‘O_RDWR’, and ‘O_TRUNC’ are set in the FLAGS
  3675. argument, or ‘O_CREAT’ is set and the file does not already
  3676. exist.
  3677. If on a 32 bit machine the sources are translated with
  3678. ‘_FILE_OFFSET_BITS == 64’ the function ‘open’ returns a file
  3679. descriptor opened in the large file mode which enables the file
  3680. handling functions to use files up to 2^63 bytes in size and offset
  3681. from −2^63 to 2^63. This happens transparently for the user since
  3682. all of the low-level file handling functions are equally replaced.
  3683. This function is a cancellation point in multi-threaded programs.
  3684. This is a problem if the thread allocates some resources (like
  3685. memory, file descriptors, semaphores or whatever) at the time
  3686. ‘open’ is called. If the thread gets canceled these resources stay
  3687. allocated until the program ends. To avoid this calls to ‘open’
  3688. should be protected using cancellation handlers.
  3689. The ‘open’ function is the underlying primitive for the ‘fopen’ and
  3690. ‘freopen’ functions, that create streams.
  3691. -- Function: int open64 (const char *FILENAME, int FLAGS[, mode_t
  3692. MODE])
  3693. Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
  3694. Concepts::.
  3695. This function is similar to ‘open’. It returns a file descriptor
  3696. which can be used to access the file named by FILENAME. The only
  3697. difference is that on 32 bit systems the file is opened in the
  3698. large file mode. I.e., file length and file offsets can exceed 31
  3699. bits.
  3700. When the sources are translated with ‘_FILE_OFFSET_BITS == 64’ this
  3701. function is actually available under the name ‘open’. I.e., the
  3702. new, extended API using 64 bit file sizes and offsets transparently
  3703. replaces the old API.
  3704. -- Obsolete function: int creat (const char *FILENAME, mode_t MODE)
  3705. Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
  3706. Concepts::.
  3707. This function is obsolete. The call:
  3708. creat (FILENAME, MODE)
  3709. is equivalent to:
  3710. open (FILENAME, O_WRONLY | O_CREAT | O_TRUNC, MODE)
  3711. If on a 32 bit machine the sources are translated with
  3712. ‘_FILE_OFFSET_BITS == 64’ the function ‘creat’ returns a file
  3713. descriptor opened in the large file mode which enables the file
  3714. handling functions to use files up to 2^63 in size and offset from
  3715. −2^63 to 2^63. This happens transparently for the user since all
  3716. of the low-level file handling functions are equally replaced.
  3717. -- Obsolete function: int creat64 (const char *FILENAME, mode_t MODE)
  3718. Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
  3719. Concepts::.
  3720. This function is similar to ‘creat’. It returns a file descriptor
  3721. which can be used to access the file named by FILENAME. The only
  3722. difference is that on 32 bit systems the file is opened in the
  3723. large file mode. I.e., file length and file offsets can exceed 31
  3724. bits.
  3725. To use this file descriptor one must not use the normal operations
  3726. but instead the counterparts named ‘*64’, e.g., ‘read64’.
  3727. When the sources are translated with ‘_FILE_OFFSET_BITS == 64’ this
  3728. function is actually available under the name ‘open’. I.e., the
  3729. new, extended API using 64 bit file sizes and offsets transparently
  3730. replaces the old API.
  3731. -- Function: int close (int FILEDES)
  3732. Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
  3733. Concepts::.
  3734. The function ‘close’ closes the file descriptor FILEDES. Closing a
  3735. file has the following consequences:
  3736. • The file descriptor is deallocated.
  3737. • Any record locks owned by the process on the file are
  3738. unlocked.
  3739. • When all file descriptors associated with a pipe or FIFO have
  3740. been closed, any unread data is discarded.
  3741. This function is a cancellation point in multi-threaded programs.
  3742. This is a problem if the thread allocates some resources (like
  3743. memory, file descriptors, semaphores or whatever) at the time
  3744. ‘close’ is called. If the thread gets canceled these resources
  3745. stay allocated until the program ends. To avoid this, calls to
  3746. ‘close’ should be protected using cancellation handlers.
  3747. The normal return value from ‘close’ is 0; a value of -1 is
  3748. returned in case of failure. The following ‘errno’ error
  3749. conditions are defined for this function:
  3750. ‘EBADF’
  3751. The FILEDES argument is not a valid file descriptor.
  3752. ‘EINTR’
  3753. The ‘close’ call was interrupted by a signal. *Note
  3754. Interrupted Primitives::. Here is an example of how to handle
  3755. ‘EINTR’ properly:
  3756. TEMP_FAILURE_RETRY (close (desc));
  3757. ‘ENOSPC’
  3758. ‘EIO’
  3759. ‘EDQUOT’
  3760. When the file is accessed by NFS, these errors from ‘write’
  3761. can sometimes not be detected until ‘close’. *Note I/O
  3762. Primitives::, for details on their meaning.
  3763. Please note that there is _no_ separate ‘close64’ function. This
  3764. is not necessary since this function does not determine nor depend
  3765. on the mode of the file. The kernel which performs the ‘close’
  3766. operation knows which mode the descriptor is used for and can
  3767. handle this situation.
  3768. To close a stream, call ‘fclose’ (*note Closing Streams::) instead of
  3769. trying to close its underlying file descriptor with ‘close’. This
  3770. flushes any buffered output and updates the stream object to indicate
  3771. that it is closed.
  3772. 
  3773. File: libc.info, Node: I/O Primitives, Next: File Position Primitive, Prev: Opening and Closing Files, Up: Low-Level I/O
  3774. 13.2 Input and Output Primitives
  3775. ================================
  3776. This section describes the functions for performing primitive input and
  3777. output operations on file descriptors: ‘read’, ‘write’, and ‘lseek’.
  3778. These functions are declared in the header file ‘unistd.h’.
  3779. -- Data Type: ssize_t
  3780. This data type is used to represent the sizes of blocks that can be
  3781. read or written in a single operation. It is similar to ‘size_t’,
  3782. but must be a signed type.
  3783. -- Function: ssize_t read (int FILEDES, void *BUFFER, size_t SIZE)
  3784. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3785. Concepts::.
  3786. The ‘read’ function reads up to SIZE bytes from the file with
  3787. descriptor FILEDES, storing the results in the BUFFER. (This is
  3788. not necessarily a character string, and no terminating null
  3789. character is added.)
  3790. The return value is the number of bytes actually read. This might
  3791. be less than SIZE; for example, if there aren’t that many bytes
  3792. left in the file or if there aren’t that many bytes immediately
  3793. available. The exact behavior depends on what kind of file it is.
  3794. Note that reading less than SIZE bytes is not an error.
  3795. A value of zero indicates end-of-file (except if the value of the
  3796. SIZE argument is also zero). This is not considered an error. If
  3797. you keep calling ‘read’ while at end-of-file, it will keep
  3798. returning zero and doing nothing else.
  3799. If ‘read’ returns at least one character, there is no way you can
  3800. tell whether end-of-file was reached. But if you did reach the
  3801. end, the next read will return zero.
  3802. In case of an error, ‘read’ returns -1. The following ‘errno’
  3803. error conditions are defined for this function:
  3804. ‘EAGAIN’
  3805. Normally, when no input is immediately available, ‘read’ waits
  3806. for some input. But if the ‘O_NONBLOCK’ flag is set for the
  3807. file (*note File Status Flags::), ‘read’ returns immediately
  3808. without reading any data, and reports this error.
  3809. *Compatibility Note:* Most versions of BSD Unix use a
  3810. different error code for this: ‘EWOULDBLOCK’. In the GNU C
  3811. Library, ‘EWOULDBLOCK’ is an alias for ‘EAGAIN’, so it doesn’t
  3812. matter which name you use.
  3813. On some systems, reading a large amount of data from a
  3814. character special file can also fail with ‘EAGAIN’ if the
  3815. kernel cannot find enough physical memory to lock down the
  3816. user’s pages. This is limited to devices that transfer with
  3817. direct memory access into the user’s memory, which means it
  3818. does not include terminals, since they always use separate
  3819. buffers inside the kernel. This problem never happens on
  3820. GNU/Hurd systems.
  3821. Any condition that could result in ‘EAGAIN’ can instead result
  3822. in a successful ‘read’ which returns fewer bytes than
  3823. requested. Calling ‘read’ again immediately would result in
  3824. ‘EAGAIN’.
  3825. ‘EBADF’
  3826. The FILEDES argument is not a valid file descriptor, or is not
  3827. open for reading.
  3828. ‘EINTR’
  3829. ‘read’ was interrupted by a signal while it was waiting for
  3830. input. *Note Interrupted Primitives::. A signal will not
  3831. necessarily cause ‘read’ to return ‘EINTR’; it may instead
  3832. result in a successful ‘read’ which returns fewer bytes than
  3833. requested.
  3834. ‘EIO’
  3835. For many devices, and for disk files, this error code
  3836. indicates a hardware error.
  3837. ‘EIO’ also occurs when a background process tries to read from
  3838. the controlling terminal, and the normal action of stopping
  3839. the process by sending it a ‘SIGTTIN’ signal isn’t working.
  3840. This might happen if the signal is being blocked or ignored,
  3841. or because the process group is orphaned. *Note Job
  3842. Control::, for more information about job control, and *note
  3843. Signal Handling::, for information about signals.
  3844. ‘EINVAL’
  3845. In some systems, when reading from a character or block
  3846. device, position and size offsets must be aligned to a
  3847. particular block size. This error indicates that the offsets
  3848. were not properly aligned.
  3849. Please note that there is no function named ‘read64’. This is not
  3850. necessary since this function does not directly modify or handle
  3851. the possibly wide file offset. Since the kernel handles this state
  3852. internally, the ‘read’ function can be used for all cases.
  3853. This function is a cancellation point in multi-threaded programs.
  3854. This is a problem if the thread allocates some resources (like
  3855. memory, file descriptors, semaphores or whatever) at the time
  3856. ‘read’ is called. If the thread gets canceled these resources stay
  3857. allocated until the program ends. To avoid this, calls to ‘read’
  3858. should be protected using cancellation handlers.
  3859. The ‘read’ function is the underlying primitive for all of the
  3860. functions that read from streams, such as ‘fgetc’.
  3861. -- Function: ssize_t pread (int FILEDES, void *BUFFER, size_t SIZE,
  3862. off_t OFFSET)
  3863. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3864. Concepts::.
  3865. The ‘pread’ function is similar to the ‘read’ function. The first
  3866. three arguments are identical, and the return values and error
  3867. codes also correspond.
  3868. The difference is the fourth argument and its handling. The data
  3869. block is not read from the current position of the file descriptor
  3870. ‘filedes’. Instead the data is read from the file starting at
  3871. position OFFSET. The position of the file descriptor itself is not
  3872. affected by the operation. The value is the same as before the
  3873. call.
  3874. When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ the
  3875. ‘pread’ function is in fact ‘pread64’ and the type ‘off_t’ has 64
  3876. bits, which makes it possible to handle files up to 2^63 bytes in
  3877. length.
  3878. The return value of ‘pread’ describes the number of bytes read. In
  3879. the error case it returns -1 like ‘read’ does and the error codes
  3880. are also the same, with these additions:
  3881. ‘EINVAL’
  3882. The value given for OFFSET is negative and therefore illegal.
  3883. ‘ESPIPE’
  3884. The file descriptor FILEDES is associated with a pipe or a
  3885. FIFO and this device does not allow positioning of the file
  3886. pointer.
  3887. The function is an extension defined in the Unix Single
  3888. Specification version 2.
  3889. -- Function: ssize_t pread64 (int FILEDES, void *BUFFER, size_t SIZE,
  3890. off64_t OFFSET)
  3891. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3892. Concepts::.
  3893. This function is similar to the ‘pread’ function. The difference
  3894. is that the OFFSET parameter is of type ‘off64_t’ instead of
  3895. ‘off_t’ which makes it possible on 32 bit machines to address files
  3896. larger than 2^31 bytes and up to 2^63 bytes. The file descriptor
  3897. ‘filedes’ must be opened using ‘open64’ since otherwise the large
  3898. offsets possible with ‘off64_t’ will lead to errors with a
  3899. descriptor in small file mode.
  3900. When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ on
  3901. a 32 bit machine this function is actually available under the name
  3902. ‘pread’ and so transparently replaces the 32 bit interface.
  3903. -- Function: ssize_t write (int FILEDES, const void *BUFFER, size_t
  3904. SIZE)
  3905. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3906. Concepts::.
  3907. The ‘write’ function writes up to SIZE bytes from BUFFER to the
  3908. file with descriptor FILEDES. The data in BUFFER is not
  3909. necessarily a character string and a null character is output like
  3910. any other character.
  3911. The return value is the number of bytes actually written. This may
  3912. be SIZE, but can always be smaller. Your program should always
  3913. call ‘write’ in a loop, iterating until all the data is written.
  3914. Once ‘write’ returns, the data is enqueued to be written and can be
  3915. read back right away, but it is not necessarily written out to
  3916. permanent storage immediately. You can use ‘fsync’ when you need
  3917. to be sure your data has been permanently stored before continuing.
  3918. (It is more efficient for the system to batch up consecutive writes
  3919. and do them all at once when convenient. Normally they will always
  3920. be written to disk within a minute or less.) Modern systems
  3921. provide another function ‘fdatasync’ which guarantees integrity
  3922. only for the file data and is therefore faster. You can use the
  3923. ‘O_FSYNC’ open mode to make ‘write’ always store the data to disk
  3924. before returning; *note Operating Modes::.
  3925. In the case of an error, ‘write’ returns -1. The following ‘errno’
  3926. error conditions are defined for this function:
  3927. ‘EAGAIN’
  3928. Normally, ‘write’ blocks until the write operation is
  3929. complete. But if the ‘O_NONBLOCK’ flag is set for the file
  3930. (*note Control Operations::), it returns immediately without
  3931. writing any data and reports this error. An example of a
  3932. situation that might cause the process to block on output is
  3933. writing to a terminal device that supports flow control, where
  3934. output has been suspended by receipt of a STOP character.
  3935. *Compatibility Note:* Most versions of BSD Unix use a
  3936. different error code for this: ‘EWOULDBLOCK’. In the GNU C
  3937. Library, ‘EWOULDBLOCK’ is an alias for ‘EAGAIN’, so it doesn’t
  3938. matter which name you use.
  3939. On some systems, writing a large amount of data from a
  3940. character special file can also fail with ‘EAGAIN’ if the
  3941. kernel cannot find enough physical memory to lock down the
  3942. user’s pages. This is limited to devices that transfer with
  3943. direct memory access into the user’s memory, which means it
  3944. does not include terminals, since they always use separate
  3945. buffers inside the kernel. This problem does not arise on
  3946. GNU/Hurd systems.
  3947. ‘EBADF’
  3948. The FILEDES argument is not a valid file descriptor, or is not
  3949. open for writing.
  3950. ‘EFBIG’
  3951. The size of the file would become larger than the
  3952. implementation can support.
  3953. ‘EINTR’
  3954. The ‘write’ operation was interrupted by a signal while it was
  3955. blocked waiting for completion. A signal will not necessarily
  3956. cause ‘write’ to return ‘EINTR’; it may instead result in a
  3957. successful ‘write’ which writes fewer bytes than requested.
  3958. *Note Interrupted Primitives::.
  3959. ‘EIO’
  3960. For many devices, and for disk files, this error code
  3961. indicates a hardware error.
  3962. ‘ENOSPC’
  3963. The device containing the file is full.
  3964. ‘EPIPE’
  3965. This error is returned when you try to write to a pipe or FIFO
  3966. that isn’t open for reading by any process. When this
  3967. happens, a ‘SIGPIPE’ signal is also sent to the process; see
  3968. *note Signal Handling::.
  3969. ‘EINVAL’
  3970. In some systems, when writing to a character or block device,
  3971. position and size offsets must be aligned to a particular
  3972. block size. This error indicates that the offsets were not
  3973. properly aligned.
  3974. Unless you have arranged to prevent ‘EINTR’ failures, you should
  3975. check ‘errno’ after each failing call to ‘write’, and if the error
  3976. was ‘EINTR’, you should simply repeat the call. *Note Interrupted
  3977. Primitives::. The easy way to do this is with the macro
  3978. ‘TEMP_FAILURE_RETRY’, as follows:
  3979. nbytes = TEMP_FAILURE_RETRY (write (desc, buffer, count));
  3980. Please note that there is no function named ‘write64’. This is not
  3981. necessary since this function does not directly modify or handle
  3982. the possibly wide file offset. Since the kernel handles this state
  3983. internally the ‘write’ function can be used for all cases.
  3984. This function is a cancellation point in multi-threaded programs.
  3985. This is a problem if the thread allocates some resources (like
  3986. memory, file descriptors, semaphores or whatever) at the time
  3987. ‘write’ is called. If the thread gets canceled these resources
  3988. stay allocated until the program ends. To avoid this, calls to
  3989. ‘write’ should be protected using cancellation handlers.
  3990. The ‘write’ function is the underlying primitive for all of the
  3991. functions that write to streams, such as ‘fputc’.
  3992. -- Function: ssize_t pwrite (int FILEDES, const void *BUFFER, size_t
  3993. SIZE, off_t OFFSET)
  3994. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  3995. Concepts::.
  3996. The ‘pwrite’ function is similar to the ‘write’ function. The
  3997. first three arguments are identical, and the return values and
  3998. error codes also correspond.
  3999. The difference is the fourth argument and its handling. The data
  4000. block is not written to the current position of the file descriptor
  4001. ‘filedes’. Instead the data is written to the file starting at
  4002. position OFFSET. The position of the file descriptor itself is not
  4003. affected by the operation. The value is the same as before the
  4004. call.
  4005. When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ the
  4006. ‘pwrite’ function is in fact ‘pwrite64’ and the type ‘off_t’ has 64
  4007. bits, which makes it possible to handle files up to 2^63 bytes in
  4008. length.
  4009. The return value of ‘pwrite’ describes the number of written bytes.
  4010. In the error case it returns -1 like ‘write’ does and the error
  4011. codes are also the same, with these additions:
  4012. ‘EINVAL’
  4013. The value given for OFFSET is negative and therefore illegal.
  4014. ‘ESPIPE’
  4015. The file descriptor FILEDES is associated with a pipe or a
  4016. FIFO and this device does not allow positioning of the file
  4017. pointer.
  4018. The function is an extension defined in the Unix Single
  4019. Specification version 2.
  4020. -- Function: ssize_t pwrite64 (int FILEDES, const void *BUFFER, size_t
  4021. SIZE, off64_t OFFSET)
  4022. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4023. Concepts::.
  4024. This function is similar to the ‘pwrite’ function. The difference
  4025. is that the OFFSET parameter is of type ‘off64_t’ instead of
  4026. ‘off_t’ which makes it possible on 32 bit machines to address files
  4027. larger than 2^31 bytes and up to 2^63 bytes. The file descriptor
  4028. ‘filedes’ must be opened using ‘open64’ since otherwise the large
  4029. offsets possible with ‘off64_t’ will lead to errors with a
  4030. descriptor in small file mode.
  4031. When the source file is compiled using ‘_FILE_OFFSET_BITS == 64’ on
  4032. a 32 bit machine this function is actually available under the name
  4033. ‘pwrite’ and so transparently replaces the 32 bit interface.
  4034. 
  4035. File: libc.info, Node: File Position Primitive, Next: Descriptors and Streams, Prev: I/O Primitives, Up: Low-Level I/O
  4036. 13.3 Setting the File Position of a Descriptor
  4037. ==============================================
  4038. Just as you can set the file position of a stream with ‘fseek’, you can
  4039. set the file position of a descriptor with ‘lseek’. This specifies the
  4040. position in the file for the next ‘read’ or ‘write’ operation. *Note
  4041. File Positioning::, for more information on the file position and what
  4042. it means.
  4043. To read the current file position value from a descriptor, use ‘lseek
  4044. (DESC, 0, SEEK_CUR)’.
  4045. -- Function: off_t lseek (int FILEDES, off_t OFFSET, int WHENCE)
  4046. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4047. Concepts::.
  4048. The ‘lseek’ function is used to change the file position of the
  4049. file with descriptor FILEDES.
  4050. The WHENCE argument specifies how the OFFSET should be interpreted,
  4051. in the same way as for the ‘fseek’ function, and it must be one of
  4052. the symbolic constants ‘SEEK_SET’, ‘SEEK_CUR’, or ‘SEEK_END’.
  4053. ‘SEEK_SET’
  4054. Specifies that OFFSET is a count of characters from the
  4055. beginning of the file.
  4056. ‘SEEK_CUR’
  4057. Specifies that OFFSET is a count of characters from the
  4058. current file position. This count may be positive or
  4059. negative.
  4060. ‘SEEK_END’
  4061. Specifies that OFFSET is a count of characters from the end of
  4062. the file. A negative count specifies a position within the
  4063. current extent of the file; a positive count specifies a
  4064. position past the current end. If you set the position past
  4065. the current end, and actually write data, you will extend the
  4066. file with zeros up to that position.
  4067. The return value from ‘lseek’ is normally the resulting file
  4068. position, measured in bytes from the beginning of the file. You
  4069. can use this feature together with ‘SEEK_CUR’ to read the current
  4070. file position.
  4071. If you want to append to the file, setting the file position to the
  4072. current end of file with ‘SEEK_END’ is not sufficient. Another
  4073. process may write more data after you seek but before you write,
  4074. extending the file so the position you write onto clobbers their
  4075. data. Instead, use the ‘O_APPEND’ operating mode; *note Operating
  4076. Modes::.
  4077. You can set the file position past the current end of the file.
  4078. This does not by itself make the file longer; ‘lseek’ never changes
  4079. the file. But subsequent output at that position will extend the
  4080. file. Characters between the previous end of file and the new
  4081. position are filled with zeros. Extending the file in this way can
  4082. create a “hole”: the blocks of zeros are not actually allocated on
  4083. disk, so the file takes up less space than it appears to; it is
  4084. then called a “sparse file”.
  4085. If the file position cannot be changed, or the operation is in some
  4086. way invalid, ‘lseek’ returns a value of -1. The following ‘errno’
  4087. error conditions are defined for this function:
  4088. ‘EBADF’
  4089. The FILEDES is not a valid file descriptor.
  4090. ‘EINVAL’
  4091. The WHENCE argument value is not valid, or the resulting file
  4092. offset is not valid. A file offset is invalid.
  4093. ‘ESPIPE’
  4094. The FILEDES corresponds to an object that cannot be
  4095. positioned, such as a pipe, FIFO or terminal device. (POSIX.1
  4096. specifies this error only for pipes and FIFOs, but on GNU
  4097. systems, you always get ‘ESPIPE’ if the object is not
  4098. seekable.)
  4099. When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ the
  4100. ‘lseek’ function is in fact ‘lseek64’ and the type ‘off_t’ has 64
  4101. bits which makes it possible to handle files up to 2^63 bytes in
  4102. length.
  4103. This function is a cancellation point in multi-threaded programs.
  4104. This is a problem if the thread allocates some resources (like
  4105. memory, file descriptors, semaphores or whatever) at the time
  4106. ‘lseek’ is called. If the thread gets canceled these resources
  4107. stay allocated until the program ends. To avoid this calls to
  4108. ‘lseek’ should be protected using cancellation handlers.
  4109. The ‘lseek’ function is the underlying primitive for the ‘fseek’,
  4110. ‘fseeko’, ‘ftell’, ‘ftello’ and ‘rewind’ functions, which operate
  4111. on streams instead of file descriptors.
  4112. -- Function: off64_t lseek64 (int FILEDES, off64_t OFFSET, int WHENCE)
  4113. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4114. Concepts::.
  4115. This function is similar to the ‘lseek’ function. The difference
  4116. is that the OFFSET parameter is of type ‘off64_t’ instead of
  4117. ‘off_t’ which makes it possible on 32 bit machines to address files
  4118. larger than 2^31 bytes and up to 2^63 bytes. The file descriptor
  4119. ‘filedes’ must be opened using ‘open64’ since otherwise the large
  4120. offsets possible with ‘off64_t’ will lead to errors with a
  4121. descriptor in small file mode.
  4122. When the source file is compiled with ‘_FILE_OFFSET_BITS == 64’ on
  4123. a 32 bits machine this function is actually available under the
  4124. name ‘lseek’ and so transparently replaces the 32 bit interface.
  4125. You can have multiple descriptors for the same file if you open the
  4126. file more than once, or if you duplicate a descriptor with ‘dup’.
  4127. Descriptors that come from separate calls to ‘open’ have independent
  4128. file positions; using ‘lseek’ on one descriptor has no effect on the
  4129. other. For example,
  4130. {
  4131. int d1, d2;
  4132. char buf[4];
  4133. d1 = open ("foo", O_RDONLY);
  4134. d2 = open ("foo", O_RDONLY);
  4135. lseek (d1, 1024, SEEK_SET);
  4136. read (d2, buf, 4);
  4137. }
  4138. will read the first four characters of the file ‘foo’. (The
  4139. error-checking code necessary for a real program has been omitted here
  4140. for brevity.)
  4141. By contrast, descriptors made by duplication share a common file
  4142. position with the original descriptor that was duplicated. Anything
  4143. which alters the file position of one of the duplicates, including
  4144. reading or writing data, affects all of them alike. Thus, for example,
  4145. {
  4146. int d1, d2, d3;
  4147. char buf1[4], buf2[4];
  4148. d1 = open ("foo", O_RDONLY);
  4149. d2 = dup (d1);
  4150. d3 = dup (d2);
  4151. lseek (d3, 1024, SEEK_SET);
  4152. read (d1, buf1, 4);
  4153. read (d2, buf2, 4);
  4154. }
  4155. will read four characters starting with the 1024’th character of ‘foo’,
  4156. and then four more characters starting with the 1028’th character.
  4157. -- Data Type: off_t
  4158. This is a signed integer type used to represent file sizes. In the
  4159. GNU C Library, this type is no narrower than ‘int’.
  4160. If the source is compiled with ‘_FILE_OFFSET_BITS == 64’ this type
  4161. is transparently replaced by ‘off64_t’.
  4162. -- Data Type: off64_t
  4163. This type is used similar to ‘off_t’. The difference is that even
  4164. on 32 bit machines, where the ‘off_t’ type would have 32 bits,
  4165. ‘off64_t’ has 64 bits and so is able to address files up to 2^63
  4166. bytes in length.
  4167. When compiling with ‘_FILE_OFFSET_BITS == 64’ this type is
  4168. available under the name ‘off_t’.
  4169. These aliases for the ‘SEEK_…’ constants exist for the sake of
  4170. compatibility with older BSD systems. They are defined in two different
  4171. header files: ‘fcntl.h’ and ‘sys/file.h’.
  4172. ‘L_SET’
  4173. An alias for ‘SEEK_SET’.
  4174. ‘L_INCR’
  4175. An alias for ‘SEEK_CUR’.
  4176. ‘L_XTND’
  4177. An alias for ‘SEEK_END’.
  4178. 
  4179. File: libc.info, Node: Descriptors and Streams, Next: Stream/Descriptor Precautions, Prev: File Position Primitive, Up: Low-Level I/O
  4180. 13.4 Descriptors and Streams
  4181. ============================
  4182. Given an open file descriptor, you can create a stream for it with the
  4183. ‘fdopen’ function. You can get the underlying file descriptor for an
  4184. existing stream with the ‘fileno’ function. These functions are
  4185. declared in the header file ‘stdio.h’.
  4186. -- Function: FILE * fdopen (int FILEDES, const char *OPENTYPE)
  4187. Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe mem lock |
  4188. *Note POSIX Safety Concepts::.
  4189. The ‘fdopen’ function returns a new stream for the file descriptor
  4190. FILEDES.
  4191. The OPENTYPE argument is interpreted in the same way as for the
  4192. ‘fopen’ function (*note Opening Streams::), except that the ‘b’
  4193. option is not permitted; this is because GNU systems make no
  4194. distinction between text and binary files. Also, ‘"w"’ and ‘"w+"’
  4195. do not cause truncation of the file; these have an effect only when
  4196. opening a file, and in this case the file has already been opened.
  4197. You must make sure that the OPENTYPE argument matches the actual
  4198. mode of the open file descriptor.
  4199. The return value is the new stream. If the stream cannot be
  4200. created (for example, if the modes for the file indicated by the
  4201. file descriptor do not permit the access specified by the OPENTYPE
  4202. argument), a null pointer is returned instead.
  4203. In some other systems, ‘fdopen’ may fail to detect that the modes
  4204. for file descriptors do not permit the access specified by
  4205. ‘opentype’. The GNU C Library always checks for this.
  4206. For an example showing the use of the ‘fdopen’ function, see *note
  4207. Creating a Pipe::.
  4208. -- Function: int fileno (FILE *STREAM)
  4209. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4210. Concepts::.
  4211. This function returns the file descriptor associated with the
  4212. stream STREAM. If an error is detected (for example, if the STREAM
  4213. is not valid) or if STREAM does not do I/O to a file, ‘fileno’
  4214. returns -1.
  4215. -- Function: int fileno_unlocked (FILE *STREAM)
  4216. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4217. Concepts::.
  4218. The ‘fileno_unlocked’ function is equivalent to the ‘fileno’
  4219. function except that it does not implicitly lock the stream if the
  4220. state is ‘FSETLOCKING_INTERNAL’.
  4221. This function is a GNU extension.
  4222. There are also symbolic constants defined in ‘unistd.h’ for the file
  4223. descriptors belonging to the standard streams ‘stdin’, ‘stdout’, and
  4224. ‘stderr’; see *note Standard Streams::.
  4225. ‘STDIN_FILENO’
  4226. This macro has value ‘0’, which is the file descriptor for standard
  4227. input.
  4228. ‘STDOUT_FILENO’
  4229. This macro has value ‘1’, which is the file descriptor for standard
  4230. output.
  4231. ‘STDERR_FILENO’
  4232. This macro has value ‘2’, which is the file descriptor for standard
  4233. error output.
  4234. 
  4235. File: libc.info, Node: Stream/Descriptor Precautions, Next: Scatter-Gather, Prev: Descriptors and Streams, Up: Low-Level I/O
  4236. 13.5 Dangers of Mixing Streams and Descriptors
  4237. ==============================================
  4238. You can have multiple file descriptors and streams (let’s call both
  4239. streams and descriptors “channels” for short) connected to the same
  4240. file, but you must take care to avoid confusion between channels. There
  4241. are two cases to consider: "linked" channels that share a single file
  4242. position value, and "independent" channels that have their own file
  4243. positions.
  4244. It’s best to use just one channel in your program for actual data
  4245. transfer to any given file, except when all the access is for input.
  4246. For example, if you open a pipe (something you can only do at the file
  4247. descriptor level), either do all I/O with the descriptor, or construct a
  4248. stream from the descriptor with ‘fdopen’ and then do all I/O with the
  4249. stream.
  4250. * Menu:
  4251. * Linked Channels:: Dealing with channels sharing a file position.
  4252. * Independent Channels:: Dealing with separately opened, unlinked channels.
  4253. * Cleaning Streams:: Cleaning a stream makes it safe to use
  4254. another channel.
  4255. 
  4256. File: libc.info, Node: Linked Channels, Next: Independent Channels, Up: Stream/Descriptor Precautions
  4257. 13.5.1 Linked Channels
  4258. ----------------------
  4259. Channels that come from a single opening share the same file position;
  4260. we call them "linked" channels. Linked channels result when you make a
  4261. stream from a descriptor using ‘fdopen’, when you get a descriptor from
  4262. a stream with ‘fileno’, when you copy a descriptor with ‘dup’ or ‘dup2’,
  4263. and when descriptors are inherited during ‘fork’. For files that don’t
  4264. support random access, such as terminals and pipes, _all_ channels are
  4265. effectively linked. On random-access files, all append-type output
  4266. streams are effectively linked to each other.
  4267. If you have been using a stream for I/O (or have just opened the
  4268. stream), and you want to do I/O using another channel (either a stream
  4269. or a descriptor) that is linked to it, you must first "clean up" the
  4270. stream that you have been using. *Note Cleaning Streams::.
  4271. Terminating a process, or executing a new program in the process,
  4272. destroys all the streams in the process. If descriptors linked to these
  4273. streams persist in other processes, their file positions become
  4274. undefined as a result. To prevent this, you must clean up the streams
  4275. before destroying them.
  4276. 
  4277. File: libc.info, Node: Independent Channels, Next: Cleaning Streams, Prev: Linked Channels, Up: Stream/Descriptor Precautions
  4278. 13.5.2 Independent Channels
  4279. ---------------------------
  4280. When you open channels (streams or descriptors) separately on a seekable
  4281. file, each channel has its own file position. These are called
  4282. "independent channels".
  4283. The system handles each channel independently. Most of the time,
  4284. this is quite predictable and natural (especially for input): each
  4285. channel can read or write sequentially at its own place in the file.
  4286. However, if some of the channels are streams, you must take these
  4287. precautions:
  4288. • You should clean an output stream after use, before doing anything
  4289. else that might read or write from the same part of the file.
  4290. • You should clean an input stream before reading data that may have
  4291. been modified using an independent channel. Otherwise, you might
  4292. read obsolete data that had been in the stream’s buffer.
  4293. If you do output to one channel at the end of the file, this will
  4294. certainly leave the other independent channels positioned somewhere
  4295. before the new end. You cannot reliably set their file positions to the
  4296. new end of file before writing, because the file can always be extended
  4297. by another process between when you set the file position and when you
  4298. write the data. Instead, use an append-type descriptor or stream; they
  4299. always output at the current end of the file. In order to make the
  4300. end-of-file position accurate, you must clean the output channel you
  4301. were using, if it is a stream.
  4302. It’s impossible for two channels to have separate file pointers for a
  4303. file that doesn’t support random access. Thus, channels for reading or
  4304. writing such files are always linked, never independent. Append-type
  4305. channels are also always linked. For these channels, follow the rules
  4306. for linked channels; see *note Linked Channels::.
  4307. 
  4308. File: libc.info, Node: Cleaning Streams, Prev: Independent Channels, Up: Stream/Descriptor Precautions
  4309. 13.5.3 Cleaning Streams
  4310. -----------------------
  4311. You can use ‘fflush’ to clean a stream in most cases.
  4312. You can skip the ‘fflush’ if you know the stream is already clean. A
  4313. stream is clean whenever its buffer is empty. For example, an
  4314. unbuffered stream is always clean. An input stream that is at
  4315. end-of-file is clean. A line-buffered stream is clean when the last
  4316. character output was a newline. However, a just-opened input stream
  4317. might not be clean, as its input buffer might not be empty.
  4318. There is one case in which cleaning a stream is impossible on most
  4319. systems. This is when the stream is doing input from a file that is not
  4320. random-access. Such streams typically read ahead, and when the file is
  4321. not random access, there is no way to give back the excess data already
  4322. read. When an input stream reads from a random-access file, ‘fflush’
  4323. does clean the stream, but leaves the file pointer at an unpredictable
  4324. place; you must set the file pointer before doing any further I/O.
  4325. Closing an output-only stream also does ‘fflush’, so this is a valid
  4326. way of cleaning an output stream.
  4327. You need not clean a stream before using its descriptor for control
  4328. operations such as setting terminal modes; these operations don’t affect
  4329. the file position and are not affected by it. You can use any
  4330. descriptor for these operations, and all channels are affected
  4331. simultaneously. However, text already “output” to a stream but still
  4332. buffered by the stream will be subject to the new terminal modes when
  4333. subsequently flushed. To make sure “past” output is covered by the
  4334. terminal settings that were in effect at the time, flush the output
  4335. streams for that terminal before setting the modes. *Note Terminal
  4336. Modes::.
  4337. 
  4338. File: libc.info, Node: Scatter-Gather, Next: Memory-mapped I/O, Prev: Stream/Descriptor Precautions, Up: Low-Level I/O
  4339. 13.6 Fast Scatter-Gather I/O
  4340. ============================
  4341. Some applications may need to read or write data to multiple buffers,
  4342. which are separated in memory. Although this can be done easily enough
  4343. with multiple calls to ‘read’ and ‘write’, it is inefficient because
  4344. there is overhead associated with each kernel call.
  4345. Instead, many platforms provide special high-speed primitives to
  4346. perform these "scatter-gather" operations in a single kernel call. The
  4347. GNU C Library will provide an emulation on any system that lacks these
  4348. primitives, so they are not a portability threat. They are defined in
  4349. ‘sys/uio.h’.
  4350. These functions are controlled with arrays of ‘iovec’ structures,
  4351. which describe the location and size of each buffer.
  4352. -- Data Type: struct iovec
  4353. The ‘iovec’ structure describes a buffer. It contains two fields:
  4354. ‘void *iov_base’
  4355. Contains the address of a buffer.
  4356. ‘size_t iov_len’
  4357. Contains the length of the buffer.
  4358. -- Function: ssize_t readv (int FILEDES, const struct iovec *VECTOR,
  4359. int COUNT)
  4360. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  4361. POSIX Safety Concepts::.
  4362. The ‘readv’ function reads data from FILEDES and scatters it into
  4363. the buffers described in VECTOR, which is taken to be COUNT
  4364. structures long. As each buffer is filled, data is sent to the
  4365. next.
  4366. Note that ‘readv’ is not guaranteed to fill all the buffers. It
  4367. may stop at any point, for the same reasons ‘read’ would.
  4368. The return value is a count of bytes (_not_ buffers) read, 0
  4369. indicating end-of-file, or -1 indicating an error. The possible
  4370. errors are the same as in ‘read’.
  4371. -- Function: ssize_t writev (int FILEDES, const struct iovec *VECTOR,
  4372. int COUNT)
  4373. Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
  4374. POSIX Safety Concepts::.
  4375. The ‘writev’ function gathers data from the buffers described in
  4376. VECTOR, which is taken to be COUNT structures long, and writes them
  4377. to ‘filedes’. As each buffer is written, it moves on to the next.
  4378. Like ‘readv’, ‘writev’ may stop midstream under the same conditions
  4379. ‘write’ would.
  4380. The return value is a count of bytes written, or -1 indicating an
  4381. error. The possible errors are the same as in ‘write’.
  4382. Note that if the buffers are small (under about 1kB), high-level
  4383. streams may be easier to use than these functions. However, ‘readv’ and
  4384. ‘writev’ are more efficient when the individual buffers themselves (as
  4385. opposed to the total output), are large. In that case, a high-level
  4386. stream would not be able to cache the data efficiently.
  4387. 
  4388. File: libc.info, Node: Memory-mapped I/O, Next: Waiting for I/O, Prev: Scatter-Gather, Up: Low-Level I/O
  4389. 13.7 Memory-mapped I/O
  4390. ======================
  4391. On modern operating systems, it is possible to "mmap" (pronounced
  4392. “em-map”) a file to a region of memory. When this is done, the file can
  4393. be accessed just like an array in the program.
  4394. This is more efficient than ‘read’ or ‘write’, as only the regions of
  4395. the file that a program actually accesses are loaded. Accesses to
  4396. not-yet-loaded parts of the mmapped region are handled in the same way
  4397. as swapped out pages.
  4398. Since mmapped pages can be stored back to their file when physical
  4399. memory is low, it is possible to mmap files orders of magnitude larger
  4400. than both the physical memory _and_ swap space. The only limit is
  4401. address space. The theoretical limit is 4GB on a 32-bit machine -
  4402. however, the actual limit will be smaller since some areas will be
  4403. reserved for other purposes. If the LFS interface is used the file size
  4404. on 32-bit systems is not limited to 2GB (offsets are signed which
  4405. reduces the addressable area of 4GB by half); the full 64-bit are
  4406. available.
  4407. Memory mapping only works on entire pages of memory. Thus, addresses
  4408. for mapping must be page-aligned, and length values will be rounded up.
  4409. To determine the size of a page the machine uses one should use
  4410. size_t page_size = (size_t) sysconf (_SC_PAGESIZE);
  4411. These functions are declared in ‘sys/mman.h’.
  4412. -- Function: void * mmap (void *ADDRESS, size_t LENGTH, int PROTECT,
  4413. int FLAGS, int FILEDES, off_t OFFSET)
  4414. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4415. Concepts::.
  4416. The ‘mmap’ function creates a new mapping, connected to bytes
  4417. (OFFSET) to (OFFSET + LENGTH - 1) in the file open on FILEDES. A
  4418. new reference for the file specified by FILEDES is created, which
  4419. is not removed by closing the file.
  4420. ADDRESS gives a preferred starting address for the mapping. ‘NULL’
  4421. expresses no preference. Any previous mapping at that address is
  4422. automatically removed. The address you give may still be changed,
  4423. unless you use the ‘MAP_FIXED’ flag.
  4424. PROTECT contains flags that control what kind of access is
  4425. permitted. They include ‘PROT_READ’, ‘PROT_WRITE’, and
  4426. ‘PROT_EXEC’, which permit reading, writing, and execution,
  4427. respectively. Inappropriate access will cause a segfault (*note
  4428. Program Error Signals::).
  4429. Note that most hardware designs cannot support write permission
  4430. without read permission, and many do not distinguish read and
  4431. execute permission. Thus, you may receive wider permissions than
  4432. you ask for, and mappings of write-only files may be denied even if
  4433. you do not use ‘PROT_READ’.
  4434. FLAGS contains flags that control the nature of the map. One of
  4435. ‘MAP_SHARED’ or ‘MAP_PRIVATE’ must be specified.
  4436. They include:
  4437. ‘MAP_PRIVATE’
  4438. This specifies that writes to the region should never be
  4439. written back to the attached file. Instead, a copy is made
  4440. for the process, and the region will be swapped normally if
  4441. memory runs low. No other process will see the changes.
  4442. Since private mappings effectively revert to ordinary memory
  4443. when written to, you must have enough virtual memory for a
  4444. copy of the entire mmapped region if you use this mode with
  4445. ‘PROT_WRITE’.
  4446. ‘MAP_SHARED’
  4447. This specifies that writes to the region will be written back
  4448. to the file. Changes made will be shared immediately with
  4449. other processes mmaping the same file.
  4450. Note that actual writing may take place at any time. You need
  4451. to use ‘msync’, described below, if it is important that other
  4452. processes using conventional I/O get a consistent view of the
  4453. file.
  4454. ‘MAP_FIXED’
  4455. This forces the system to use the exact mapping address
  4456. specified in ADDRESS and fail if it can’t.
  4457. ‘MAP_ANONYMOUS’
  4458. ‘MAP_ANON’
  4459. This flag tells the system to create an anonymous mapping, not
  4460. connected to a file. FILEDES and OFFSET are ignored, and the
  4461. region is initialized with zeros.
  4462. Anonymous maps are used as the basic primitive to extend the
  4463. heap on some systems. They are also useful to share data
  4464. between multiple tasks without creating a file.
  4465. On some systems using private anonymous mmaps is more
  4466. efficient than using ‘malloc’ for large blocks. This is not
  4467. an issue with the GNU C Library, as the included ‘malloc’
  4468. automatically uses ‘mmap’ where appropriate.
  4469. ‘mmap’ returns the address of the new mapping, or ‘MAP_FAILED’ for
  4470. an error.
  4471. Possible errors include:
  4472. ‘EINVAL’
  4473. Either ADDRESS was unusable, or inconsistent FLAGS were given.
  4474. ‘EACCES’
  4475. FILEDES was not open for the type of access specified in
  4476. PROTECT.
  4477. ‘ENOMEM’
  4478. Either there is not enough memory for the operation, or the
  4479. process is out of address space.
  4480. ‘ENODEV’
  4481. This file is of a type that doesn’t support mapping.
  4482. ‘ENOEXEC’
  4483. The file is on a filesystem that doesn’t support mapping.
  4484. -- Function: void * mmap64 (void *ADDRESS, size_t LENGTH, int PROTECT,
  4485. int FLAGS, int FILEDES, off64_t OFFSET)
  4486. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4487. Concepts::.
  4488. The ‘mmap64’ function is equivalent to the ‘mmap’ function but the
  4489. OFFSET parameter is of type ‘off64_t’. On 32-bit systems this
  4490. allows the file associated with the FILEDES descriptor to be larger
  4491. than 2GB. FILEDES must be a descriptor returned from a call to
  4492. ‘open64’ or ‘fopen64’ and ‘freopen64’ where the descriptor is
  4493. retrieved with ‘fileno’.
  4494. When the sources are translated with ‘_FILE_OFFSET_BITS == 64’ this
  4495. function is actually available under the name ‘mmap’. I.e., the
  4496. new, extended API using 64 bit file sizes and offsets transparently
  4497. replaces the old API.
  4498. -- Function: int munmap (void *ADDR, size_t LENGTH)
  4499. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4500. Concepts::.
  4501. ‘munmap’ removes any memory maps from (ADDR) to (ADDR + LENGTH).
  4502. LENGTH should be the length of the mapping.
  4503. It is safe to unmap multiple mappings in one command, or include
  4504. unmapped space in the range. It is also possible to unmap only
  4505. part of an existing mapping. However, only entire pages can be
  4506. removed. If LENGTH is not an even number of pages, it will be
  4507. rounded up.
  4508. It returns 0 for success and -1 for an error.
  4509. One error is possible:
  4510. ‘EINVAL’
  4511. The memory range given was outside the user mmap range or
  4512. wasn’t page aligned.
  4513. -- Function: int msync (void *ADDRESS, size_t LENGTH, int FLAGS)
  4514. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4515. Concepts::.
  4516. When using shared mappings, the kernel can write the file at any
  4517. time before the mapping is removed. To be certain data has
  4518. actually been written to the file and will be accessible to
  4519. non-memory-mapped I/O, it is necessary to use this function.
  4520. It operates on the region ADDRESS to (ADDRESS + LENGTH). It may be
  4521. used on part of a mapping or multiple mappings, however the region
  4522. given should not contain any unmapped space.
  4523. FLAGS can contain some options:
  4524. ‘MS_SYNC’
  4525. This flag makes sure the data is actually written _to disk_.
  4526. Normally ‘msync’ only makes sure that accesses to a file with
  4527. conventional I/O reflect the recent changes.
  4528. ‘MS_ASYNC’
  4529. This tells ‘msync’ to begin the synchronization, but not to
  4530. wait for it to complete.
  4531. ‘msync’ returns 0 for success and -1 for error. Errors include:
  4532. ‘EINVAL’
  4533. An invalid region was given, or the FLAGS were invalid.
  4534. ‘EFAULT’
  4535. There is no existing mapping in at least part of the given
  4536. region.
  4537. -- Function: void * mremap (void *ADDRESS, size_t LENGTH, size_t
  4538. NEW_LENGTH, int FLAG)
  4539. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4540. Concepts::.
  4541. This function can be used to change the size of an existing memory
  4542. area. ADDRESS and LENGTH must cover a region entirely mapped in
  4543. the same ‘mmap’ statement. A new mapping with the same
  4544. characteristics will be returned with the length NEW_LENGTH.
  4545. One option is possible, ‘MREMAP_MAYMOVE’. If it is given in FLAGS,
  4546. the system may remove the existing mapping and create a new one of
  4547. the desired length in another location.
  4548. The address of the resulting mapping is returned, or -1. Possible
  4549. error codes include:
  4550. ‘EFAULT’
  4551. There is no existing mapping in at least part of the original
  4552. region, or the region covers two or more distinct mappings.
  4553. ‘EINVAL’
  4554. The address given is misaligned or inappropriate.
  4555. ‘EAGAIN’
  4556. The region has pages locked, and if extended it would exceed
  4557. the process’s resource limit for locked pages. *Note Limits
  4558. on Resources::.
  4559. ‘ENOMEM’
  4560. The region is private writable, and insufficient virtual
  4561. memory is available to extend it. Also, this error will occur
  4562. if ‘MREMAP_MAYMOVE’ is not given and the extension would
  4563. collide with another mapped region.
  4564. This function is only available on a few systems. Except for
  4565. performing optional optimizations one should not rely on this function.
  4566. Not all file descriptors may be mapped. Sockets, pipes, and most
  4567. devices only allow sequential access and do not fit into the mapping
  4568. abstraction. In addition, some regular files may not be mmapable, and
  4569. older kernels may not support mapping at all. Thus, programs using
  4570. ‘mmap’ should have a fallback method to use should it fail. *Note
  4571. (standards)Mmap::.
  4572. -- Function: int madvise (void *ADDR, size_t LENGTH, int ADVICE)
  4573. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4574. Concepts::.
  4575. This function can be used to provide the system with ADVICE about
  4576. the intended usage patterns of the memory region starting at ADDR
  4577. and extending LENGTH bytes.
  4578. The valid BSD values for ADVICE are:
  4579. ‘MADV_NORMAL’
  4580. The region should receive no further special treatment.
  4581. ‘MADV_RANDOM’
  4582. The region will be accessed via random page references. The
  4583. kernel should page-in the minimal number of pages for each
  4584. page fault.
  4585. ‘MADV_SEQUENTIAL’
  4586. The region will be accessed via sequential page references.
  4587. This may cause the kernel to aggressively read-ahead,
  4588. expecting further sequential references after any page fault
  4589. within this region.
  4590. ‘MADV_WILLNEED’
  4591. The region will be needed. The pages within this region may
  4592. be pre-faulted in by the kernel.
  4593. ‘MADV_DONTNEED’
  4594. The region is no longer needed. The kernel may free these
  4595. pages, causing any changes to the pages to be lost, as well as
  4596. swapped out pages to be discarded.
  4597. The POSIX names are slightly different, but with the same meanings:
  4598. ‘POSIX_MADV_NORMAL’
  4599. This corresponds with BSD’s ‘MADV_NORMAL’.
  4600. ‘POSIX_MADV_RANDOM’
  4601. This corresponds with BSD’s ‘MADV_RANDOM’.
  4602. ‘POSIX_MADV_SEQUENTIAL’
  4603. This corresponds with BSD’s ‘MADV_SEQUENTIAL’.
  4604. ‘POSIX_MADV_WILLNEED’
  4605. This corresponds with BSD’s ‘MADV_WILLNEED’.
  4606. ‘POSIX_MADV_DONTNEED’
  4607. This corresponds with BSD’s ‘MADV_DONTNEED’.
  4608. ‘madvise’ returns 0 for success and -1 for error. Errors include:
  4609. ‘EINVAL’
  4610. An invalid region was given, or the ADVICE was invalid.
  4611. ‘EFAULT’
  4612. There is no existing mapping in at least part of the given
  4613. region.
  4614. -- Function: int shm_open (const char *NAME, int OFLAG, mode_t MODE)
  4615. Preliminary: | MT-Safe locale | AS-Unsafe init heap lock |
  4616. AC-Unsafe lock mem fd | *Note POSIX Safety Concepts::.
  4617. This function returns a file descriptor that can be used to
  4618. allocate shared memory via mmap. Unrelated processes can use same
  4619. NAME to create or open existing shared memory objects.
  4620. A NAME argument specifies the shared memory object to be opened.
  4621. In the GNU C Library it must be a string smaller than ‘NAME_MAX’
  4622. bytes starting with an optional slash but containing no other
  4623. slashes.
  4624. The semantics of OFLAG and MODE arguments is same as in ‘open’.
  4625. ‘shm_open’ returns the file descriptor on success or -1 on error.
  4626. On failure ‘errno’ is set.
  4627. -- Function: int shm_unlink (const char *NAME)
  4628. Preliminary: | MT-Safe locale | AS-Unsafe init heap lock |
  4629. AC-Unsafe lock mem fd | *Note POSIX Safety Concepts::.
  4630. This function is the inverse of ‘shm_open’ and removes the object
  4631. with the given NAME previously created by ‘shm_open’.
  4632. ‘shm_unlink’ returns 0 on success or -1 on error. On failure
  4633. ‘errno’ is set.
  4634. 
  4635. File: libc.info, Node: Waiting for I/O, Next: Synchronizing I/O, Prev: Memory-mapped I/O, Up: Low-Level I/O
  4636. 13.8 Waiting for Input or Output
  4637. ================================
  4638. Sometimes a program needs to accept input on multiple input channels
  4639. whenever input arrives. For example, some workstations may have devices
  4640. such as a digitizing tablet, function button box, or dial box that are
  4641. connected via normal asynchronous serial interfaces; good user interface
  4642. style requires responding immediately to input on any device. Another
  4643. example is a program that acts as a server to several other processes
  4644. via pipes or sockets.
  4645. You cannot normally use ‘read’ for this purpose, because this blocks
  4646. the program until input is available on one particular file descriptor;
  4647. input on other channels won’t wake it up. You could set nonblocking
  4648. mode and poll each file descriptor in turn, but this is very
  4649. inefficient.
  4650. A better solution is to use the ‘select’ function. This blocks the
  4651. program until input or output is ready on a specified set of file
  4652. descriptors, or until a timer expires, whichever comes first. This
  4653. facility is declared in the header file ‘sys/types.h’.
  4654. In the case of a server socket (*note Listening::), we say that
  4655. “input” is available when there are pending connections that could be
  4656. accepted (*note Accepting Connections::). ‘accept’ for server sockets
  4657. blocks and interacts with ‘select’ just as ‘read’ does for normal input.
  4658. The file descriptor sets for the ‘select’ function are specified as
  4659. ‘fd_set’ objects. Here is the description of the data type and some
  4660. macros for manipulating these objects.
  4661. -- Data Type: fd_set
  4662. The ‘fd_set’ data type represents file descriptor sets for the
  4663. ‘select’ function. It is actually a bit array.
  4664. -- Macro: int FD_SETSIZE
  4665. The value of this macro is the maximum number of file descriptors
  4666. that a ‘fd_set’ object can hold information about. On systems with
  4667. a fixed maximum number, ‘FD_SETSIZE’ is at least that number. On
  4668. some systems, including GNU, there is no absolute limit on the
  4669. number of descriptors open, but this macro still has a constant
  4670. value which controls the number of bits in an ‘fd_set’; if you get
  4671. a file descriptor with a value as high as ‘FD_SETSIZE’, you cannot
  4672. put that descriptor into an ‘fd_set’.
  4673. -- Macro: void FD_ZERO (fd_set *SET)
  4674. Preliminary: | MT-Safe race:set | AS-Safe | AC-Safe | *Note POSIX
  4675. Safety Concepts::.
  4676. This macro initializes the file descriptor set SET to be the empty
  4677. set.
  4678. -- Macro: void FD_SET (int FILEDES, fd_set *SET)
  4679. Preliminary: | MT-Safe race:set | AS-Safe | AC-Safe | *Note POSIX
  4680. Safety Concepts::.
  4681. This macro adds FILEDES to the file descriptor set SET.
  4682. The FILEDES parameter must not have side effects since it is
  4683. evaluated more than once.
  4684. -- Macro: void FD_CLR (int FILEDES, fd_set *SET)
  4685. Preliminary: | MT-Safe race:set | AS-Safe | AC-Safe | *Note POSIX
  4686. Safety Concepts::.
  4687. This macro removes FILEDES from the file descriptor set SET.
  4688. The FILEDES parameter must not have side effects since it is
  4689. evaluated more than once.
  4690. -- Macro: int FD_ISSET (int FILEDES, const fd_set *SET)
  4691. Preliminary: | MT-Safe race:set | AS-Safe | AC-Safe | *Note POSIX
  4692. Safety Concepts::.
  4693. This macro returns a nonzero value (true) if FILEDES is a member of
  4694. the file descriptor set SET, and zero (false) otherwise.
  4695. The FILEDES parameter must not have side effects since it is
  4696. evaluated more than once.
  4697. Next, here is the description of the ‘select’ function itself.
  4698. -- Function: int select (int NFDS, fd_set *READ-FDS, fd_set *WRITE-FDS,
  4699. fd_set *EXCEPT-FDS, struct timeval *TIMEOUT)
  4700. Preliminary: | MT-Safe race:read-fds race:write-fds race:except-fds
  4701. | AS-Safe | AC-Safe | *Note POSIX Safety Concepts::.
  4702. The ‘select’ function blocks the calling process until there is
  4703. activity on any of the specified sets of file descriptors, or until
  4704. the timeout period has expired.
  4705. The file descriptors specified by the READ-FDS argument are checked
  4706. to see if they are ready for reading; the WRITE-FDS file
  4707. descriptors are checked to see if they are ready for writing; and
  4708. the EXCEPT-FDS file descriptors are checked for exceptional
  4709. conditions. You can pass a null pointer for any of these arguments
  4710. if you are not interested in checking for that kind of condition.
  4711. A file descriptor is considered ready for reading if a ‘read’ call
  4712. will not block. This usually includes the read offset being at the
  4713. end of the file or there is an error to report. A server socket is
  4714. considered ready for reading if there is a pending connection which
  4715. can be accepted with ‘accept’; *note Accepting Connections::. A
  4716. client socket is ready for writing when its connection is fully
  4717. established; *note Connecting::.
  4718. “Exceptional conditions” does not mean errors—errors are reported
  4719. immediately when an erroneous system call is executed, and do not
  4720. constitute a state of the descriptor. Rather, they include
  4721. conditions such as the presence of an urgent message on a socket.
  4722. (*Note Sockets::, for information on urgent messages.)
  4723. The ‘select’ function checks only the first NFDS file descriptors.
  4724. The usual thing is to pass ‘FD_SETSIZE’ as the value of this
  4725. argument.
  4726. The TIMEOUT specifies the maximum time to wait. If you pass a null
  4727. pointer for this argument, it means to block indefinitely until one
  4728. of the file descriptors is ready. Otherwise, you should provide
  4729. the time in ‘struct timeval’ format; see *note High-Resolution
  4730. Calendar::. Specify zero as the time (a ‘struct timeval’
  4731. containing all zeros) if you want to find out which descriptors are
  4732. ready without waiting if none are ready.
  4733. The normal return value from ‘select’ is the total number of ready
  4734. file descriptors in all of the sets. Each of the argument sets is
  4735. overwritten with information about the descriptors that are ready
  4736. for the corresponding operation. Thus, to see if a particular
  4737. descriptor DESC has input, use ‘FD_ISSET (DESC, READ-FDS)’ after
  4738. ‘select’ returns.
  4739. If ‘select’ returns because the timeout period expires, it returns
  4740. a value of zero.
  4741. Any signal will cause ‘select’ to return immediately. So if your
  4742. program uses signals, you can’t rely on ‘select’ to keep waiting
  4743. for the full time specified. If you want to be sure of waiting for
  4744. a particular amount of time, you must check for ‘EINTR’ and repeat
  4745. the ‘select’ with a newly calculated timeout based on the current
  4746. time. See the example below. See also *note Interrupted
  4747. Primitives::.
  4748. If an error occurs, ‘select’ returns ‘-1’ and does not modify the
  4749. argument file descriptor sets. The following ‘errno’ error
  4750. conditions are defined for this function:
  4751. ‘EBADF’
  4752. One of the file descriptor sets specified an invalid file
  4753. descriptor.
  4754. ‘EINTR’
  4755. The operation was interrupted by a signal. *Note Interrupted
  4756. Primitives::.
  4757. ‘EINVAL’
  4758. The TIMEOUT argument is invalid; one of the components is
  4759. negative or too large.
  4760. *Portability Note:* The ‘select’ function is a BSD Unix feature.
  4761. Here is an example showing how you can use ‘select’ to establish a
  4762. timeout period for reading from a file descriptor. The ‘input_timeout’
  4763. function blocks the calling process until input is available on the file
  4764. descriptor, or until the timeout period expires.
  4765. #include <errno.h>
  4766. #include <stdio.h>
  4767. #include <unistd.h>
  4768. #include <sys/types.h>
  4769. #include <sys/time.h>
  4770. int
  4771. input_timeout (int filedes, unsigned int seconds)
  4772. {
  4773. fd_set set;
  4774. struct timeval timeout;
  4775. /* Initialize the file descriptor set. */
  4776. FD_ZERO (&set);
  4777. FD_SET (filedes, &set);
  4778. /* Initialize the timeout data structure. */
  4779. timeout.tv_sec = seconds;
  4780. timeout.tv_usec = 0;
  4781. /* ‘select’ returns 0 if timeout, 1 if input available, -1 if error. */
  4782. return TEMP_FAILURE_RETRY (select (FD_SETSIZE,
  4783. &set, NULL, NULL,
  4784. &timeout));
  4785. }
  4786. int
  4787. main (void)
  4788. {
  4789. fprintf (stderr, "select returned %d.\n",
  4790. input_timeout (STDIN_FILENO, 5));
  4791. return 0;
  4792. }
  4793. There is another example showing the use of ‘select’ to multiplex
  4794. input from multiple sockets in *note Server Example::.
  4795. 
  4796. File: libc.info, Node: Synchronizing I/O, Next: Asynchronous I/O, Prev: Waiting for I/O, Up: Low-Level I/O
  4797. 13.9 Synchronizing I/O operations
  4798. =================================
  4799. In most modern operating systems, the normal I/O operations are not
  4800. executed synchronously. I.e., even if a ‘write’ system call returns,
  4801. this does not mean the data is actually written to the media, e.g., the
  4802. disk.
  4803. In situations where synchronization points are necessary, you can use
  4804. special functions which ensure that all operations finish before they
  4805. return.
  4806. -- Function: void sync (void)
  4807. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4808. Concepts::.
  4809. A call to this function will not return as long as there is data
  4810. which has not been written to the device. All dirty buffers in the
  4811. kernel will be written and so an overall consistent system can be
  4812. achieved (if no other process in parallel writes data).
  4813. A prototype for ‘sync’ can be found in ‘unistd.h’.
  4814. Programs more often want to ensure that data written to a given file
  4815. is committed, rather than all data in the system. For this, ‘sync’ is
  4816. overkill.
  4817. -- Function: int fsync (int FILDES)
  4818. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4819. Concepts::.
  4820. The ‘fsync’ function can be used to make sure all data associated
  4821. with the open file FILDES is written to the device associated with
  4822. the descriptor. The function call does not return unless all
  4823. actions have finished.
  4824. A prototype for ‘fsync’ can be found in ‘unistd.h’.
  4825. This function is a cancellation point in multi-threaded programs.
  4826. This is a problem if the thread allocates some resources (like
  4827. memory, file descriptors, semaphores or whatever) at the time
  4828. ‘fsync’ is called. If the thread gets canceled these resources
  4829. stay allocated until the program ends. To avoid this, calls to
  4830. ‘fsync’ should be protected using cancellation handlers.
  4831. The return value of the function is zero if no error occurred.
  4832. Otherwise it is -1 and the global variable ERRNO is set to the
  4833. following values:
  4834. ‘EBADF’
  4835. The descriptor FILDES is not valid.
  4836. ‘EINVAL’
  4837. No synchronization is possible since the system does not
  4838. implement this.
  4839. Sometimes it is not even necessary to write all data associated with
  4840. a file descriptor. E.g., in database files which do not change in size
  4841. it is enough to write all the file content data to the device.
  4842. Meta-information, like the modification time etc., are not that
  4843. important and leaving such information uncommitted does not prevent a
  4844. successful recovery of the file in case of a problem.
  4845. -- Function: int fdatasync (int FILDES)
  4846. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  4847. Concepts::.
  4848. When a call to the ‘fdatasync’ function returns, it is ensured that
  4849. all of the file data is written to the device. For all pending I/O
  4850. operations, the parts guaranteeing data integrity finished.
  4851. Not all systems implement the ‘fdatasync’ operation. On systems
  4852. missing this functionality ‘fdatasync’ is emulated by a call to
  4853. ‘fsync’ since the performed actions are a superset of those
  4854. required by ‘fdatasync’.
  4855. The prototype for ‘fdatasync’ is in ‘unistd.h’.
  4856. The return value of the function is zero if no error occurred.
  4857. Otherwise it is -1 and the global variable ERRNO is set to the
  4858. following values:
  4859. ‘EBADF’
  4860. The descriptor FILDES is not valid.
  4861. ‘EINVAL’
  4862. No synchronization is possible since the system does not
  4863. implement this.
  4864. 
  4865. File: libc.info, Node: Asynchronous I/O, Next: Control Operations, Prev: Synchronizing I/O, Up: Low-Level I/O
  4866. 13.10 Perform I/O Operations in Parallel
  4867. ========================================
  4868. The POSIX.1b standard defines a new set of I/O operations which can
  4869. significantly reduce the time an application spends waiting for I/O. The
  4870. new functions allow a program to initiate one or more I/O operations and
  4871. then immediately resume normal work while the I/O operations are
  4872. executed in parallel. This functionality is available if the ‘unistd.h’
  4873. file defines the symbol ‘_POSIX_ASYNCHRONOUS_IO’.
  4874. These functions are part of the library with realtime functions named
  4875. ‘librt’. They are not actually part of the ‘libc’ binary. The
  4876. implementation of these functions can be done using support in the
  4877. kernel (if available) or using an implementation based on threads at
  4878. userlevel. In the latter case it might be necessary to link
  4879. applications with the thread library ‘libpthread’ in addition to
  4880. ‘librt’.
  4881. All AIO operations operate on files which were opened previously.
  4882. There might be arbitrarily many operations running for one file. The
  4883. asynchronous I/O operations are controlled using a data structure named
  4884. ‘struct aiocb’ ("AIO control block"). It is defined in ‘aio.h’ as
  4885. follows.
  4886. -- Data Type: struct aiocb
  4887. The POSIX.1b standard mandates that the ‘struct aiocb’ structure
  4888. contains at least the members described in the following table.
  4889. There might be more elements which are used by the implementation,
  4890. but depending upon these elements is not portable and is highly
  4891. deprecated.
  4892. ‘int aio_fildes’
  4893. This element specifies the file descriptor to be used for the
  4894. operation. It must be a legal descriptor, otherwise the
  4895. operation will fail.
  4896. The device on which the file is opened must allow the seek
  4897. operation. I.e., it is not possible to use any of the AIO
  4898. operations on devices like terminals where an ‘lseek’ call
  4899. would lead to an error.
  4900. ‘off_t aio_offset’
  4901. This element specifies the offset in the file at which the
  4902. operation (input or output) is performed. Since the
  4903. operations are carried out in arbitrary order and more than
  4904. one operation for one file descriptor can be started, one
  4905. cannot expect a current read/write position of the file
  4906. descriptor.
  4907. ‘volatile void *aio_buf’
  4908. This is a pointer to the buffer with the data to be written or
  4909. the place where the read data is stored.
  4910. ‘size_t aio_nbytes’
  4911. This element specifies the length of the buffer pointed to by
  4912. ‘aio_buf’.
  4913. ‘int aio_reqprio’
  4914. If the platform has defined ‘_POSIX_PRIORITIZED_IO’ and
  4915. ‘_POSIX_PRIORITY_SCHEDULING’, the AIO requests are processed
  4916. based on the current scheduling priority. The ‘aio_reqprio’
  4917. element can then be used to lower the priority of the AIO
  4918. operation.
  4919. ‘struct sigevent aio_sigevent’
  4920. This element specifies how the calling process is notified
  4921. once the operation terminates. If the ‘sigev_notify’ element
  4922. is ‘SIGEV_NONE’, no notification is sent. If it is
  4923. ‘SIGEV_SIGNAL’, the signal determined by ‘sigev_signo’ is
  4924. sent. Otherwise, ‘sigev_notify’ must be ‘SIGEV_THREAD’. In
  4925. this case, a thread is created which starts executing the
  4926. function pointed to by ‘sigev_notify_function’.
  4927. ‘int aio_lio_opcode’
  4928. This element is only used by the ‘lio_listio’ and
  4929. ‘lio_listio64’ functions. Since these functions allow an
  4930. arbitrary number of operations to start at once, and each
  4931. operation can be input or output (or nothing), the information
  4932. must be stored in the control block. The possible values are:
  4933. ‘LIO_READ’
  4934. Start a read operation. Read from the file at position
  4935. ‘aio_offset’ and store the next ‘aio_nbytes’ bytes in the
  4936. buffer pointed to by ‘aio_buf’.
  4937. ‘LIO_WRITE’
  4938. Start a write operation. Write ‘aio_nbytes’ bytes
  4939. starting at ‘aio_buf’ into the file starting at position
  4940. ‘aio_offset’.
  4941. ‘LIO_NOP’
  4942. Do nothing for this control block. This value is useful
  4943. sometimes when an array of ‘struct aiocb’ values contains
  4944. holes, i.e., some of the values must not be handled
  4945. although the whole array is presented to the ‘lio_listio’
  4946. function.
  4947. When the sources are compiled using ‘_FILE_OFFSET_BITS == 64’ on a
  4948. 32 bit machine, this type is in fact ‘struct aiocb64’, since the
  4949. LFS interface transparently replaces the ‘struct aiocb’ definition.
  4950. For use with the AIO functions defined in the LFS, there is a similar
  4951. type defined which replaces the types of the appropriate members with
  4952. larger types but otherwise is equivalent to ‘struct aiocb’.
  4953. Particularly, all member names are the same.
  4954. -- Data Type: struct aiocb64
  4955. ‘int aio_fildes’
  4956. This element specifies the file descriptor which is used for
  4957. the operation. It must be a legal descriptor since otherwise
  4958. the operation fails for obvious reasons.
  4959. The device on which the file is opened must allow the seek
  4960. operation. I.e., it is not possible to use any of the AIO
  4961. operations on devices like terminals where an ‘lseek’ call
  4962. would lead to an error.
  4963. ‘off64_t aio_offset’
  4964. This element specifies at which offset in the file the
  4965. operation (input or output) is performed. Since the operation
  4966. are carried in arbitrary order and more than one operation for
  4967. one file descriptor can be started, one cannot expect a
  4968. current read/write position of the file descriptor.
  4969. ‘volatile void *aio_buf’
  4970. This is a pointer to the buffer with the data to be written or
  4971. the place where the read data is stored.
  4972. ‘size_t aio_nbytes’
  4973. This element specifies the length of the buffer pointed to by
  4974. ‘aio_buf’.
  4975. ‘int aio_reqprio’
  4976. If for the platform ‘_POSIX_PRIORITIZED_IO’ and
  4977. ‘_POSIX_PRIORITY_SCHEDULING’ are defined the AIO requests are
  4978. processed based on the current scheduling priority. The
  4979. ‘aio_reqprio’ element can then be used to lower the priority
  4980. of the AIO operation.
  4981. ‘struct sigevent aio_sigevent’
  4982. This element specifies how the calling process is notified
  4983. once the operation terminates. If the ‘sigev_notify’ element
  4984. is ‘SIGEV_NONE’ no notification is sent. If it is
  4985. ‘SIGEV_SIGNAL’, the signal determined by ‘sigev_signo’ is
  4986. sent. Otherwise, ‘sigev_notify’ must be ‘SIGEV_THREAD’ in
  4987. which case a thread is created which starts executing the
  4988. function pointed to by ‘sigev_notify_function’.
  4989. ‘int aio_lio_opcode’
  4990. This element is only used by the ‘lio_listio’ and
  4991. ‘lio_listio64’ functions. Since these functions allow an
  4992. arbitrary number of operations to start at once, and since
  4993. each operation can be input or output (or nothing), the
  4994. information must be stored in the control block. See the
  4995. description of ‘struct aiocb’ for a description of the
  4996. possible values.
  4997. When the sources are compiled using ‘_FILE_OFFSET_BITS == 64’ on a
  4998. 32 bit machine, this type is available under the name ‘struct
  4999. aiocb64’, since the LFS transparently replaces the old interface.
  5000. * Menu:
  5001. * Asynchronous Reads/Writes:: Asynchronous Read and Write Operations.
  5002. * Status of AIO Operations:: Getting the Status of AIO Operations.
  5003. * Synchronizing AIO Operations:: Getting into a consistent state.
  5004. * Cancel AIO Operations:: Cancellation of AIO Operations.
  5005. * Configuration of AIO:: How to optimize the AIO implementation.
  5006. 
  5007. File: libc.info, Node: Asynchronous Reads/Writes, Next: Status of AIO Operations, Up: Asynchronous I/O
  5008. 13.10.1 Asynchronous Read and Write Operations
  5009. ----------------------------------------------
  5010. -- Function: int aio_read (struct aiocb *AIOCBP)
  5011. Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
  5012. *Note POSIX Safety Concepts::.
  5013. This function initiates an asynchronous read operation. It
  5014. immediately returns after the operation was enqueued or when an
  5015. error was encountered.
  5016. The first ‘aiocbp->aio_nbytes’ bytes of the file for which
  5017. ‘aiocbp->aio_fildes’ is a descriptor are written to the buffer
  5018. starting at ‘aiocbp->aio_buf’. Reading starts at the absolute
  5019. position ‘aiocbp->aio_offset’ in the file.
  5020. If prioritized I/O is supported by the platform the
  5021. ‘aiocbp->aio_reqprio’ value is used to adjust the priority before
  5022. the request is actually enqueued.
  5023. The calling process is notified about the termination of the read
  5024. request according to the ‘aiocbp->aio_sigevent’ value.
  5025. When ‘aio_read’ returns, the return value is zero if no error
  5026. occurred that can be found before the process is enqueued. If such
  5027. an early error is found, the function returns -1 and sets ‘errno’
  5028. to one of the following values:
  5029. ‘EAGAIN’
  5030. The request was not enqueued due to (temporarily) exceeded
  5031. resource limitations.
  5032. ‘ENOSYS’
  5033. The ‘aio_read’ function is not implemented.
  5034. ‘EBADF’
  5035. The ‘aiocbp->aio_fildes’ descriptor is not valid. This
  5036. condition need not be recognized before enqueueing the request
  5037. and so this error might also be signaled asynchronously.
  5038. ‘EINVAL’
  5039. The ‘aiocbp->aio_offset’ or ‘aiocbp->aio_reqpiro’ value is
  5040. invalid. This condition need not be recognized before
  5041. enqueueing the request and so this error might also be
  5042. signaled asynchronously.
  5043. If ‘aio_read’ returns zero, the current status of the request can
  5044. be queried using ‘aio_error’ and ‘aio_return’ functions. As long
  5045. as the value returned by ‘aio_error’ is ‘EINPROGRESS’ the operation
  5046. has not yet completed. If ‘aio_error’ returns zero, the operation
  5047. successfully terminated, otherwise the value is to be interpreted
  5048. as an error code. If the function terminated, the result of the
  5049. operation can be obtained using a call to ‘aio_return’. The
  5050. returned value is the same as an equivalent call to ‘read’ would
  5051. have returned. Possible error codes returned by ‘aio_error’ are:
  5052. ‘EBADF’
  5053. The ‘aiocbp->aio_fildes’ descriptor is not valid.
  5054. ‘ECANCELED’
  5055. The operation was canceled before the operation was finished
  5056. (*note Cancel AIO Operations::)
  5057. ‘EINVAL’
  5058. The ‘aiocbp->aio_offset’ value is invalid.
  5059. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
  5060. function is in fact ‘aio_read64’ since the LFS interface
  5061. transparently replaces the normal implementation.
  5062. -- Function: int aio_read64 (struct aiocb64 *AIOCBP)
  5063. Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
  5064. *Note POSIX Safety Concepts::.
  5065. This function is similar to the ‘aio_read’ function. The only
  5066. difference is that on 32 bit machines, the file descriptor should
  5067. be opened in the large file mode. Internally, ‘aio_read64’ uses
  5068. functionality equivalent to ‘lseek64’ (*note File Position
  5069. Primitive::) to position the file descriptor correctly for the
  5070. reading, as opposed to the ‘lseek’ functionality used in
  5071. ‘aio_read’.
  5072. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
  5073. function is available under the name ‘aio_read’ and so
  5074. transparently replaces the interface for small files on 32 bit
  5075. machines.
  5076. To write data asynchronously to a file, there exists an equivalent
  5077. pair of functions with a very similar interface.
  5078. -- Function: int aio_write (struct aiocb *AIOCBP)
  5079. Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
  5080. *Note POSIX Safety Concepts::.
  5081. This function initiates an asynchronous write operation. The
  5082. function call immediately returns after the operation was enqueued
  5083. or if before this happens an error was encountered.
  5084. The first ‘aiocbp->aio_nbytes’ bytes from the buffer starting at
  5085. ‘aiocbp->aio_buf’ are written to the file for which
  5086. ‘aiocbp->aio_fildes’ is a descriptor, starting at the absolute
  5087. position ‘aiocbp->aio_offset’ in the file.
  5088. If prioritized I/O is supported by the platform, the
  5089. ‘aiocbp->aio_reqprio’ value is used to adjust the priority before
  5090. the request is actually enqueued.
  5091. The calling process is notified about the termination of the read
  5092. request according to the ‘aiocbp->aio_sigevent’ value.
  5093. When ‘aio_write’ returns, the return value is zero if no error
  5094. occurred that can be found before the process is enqueued. If such
  5095. an early error is found the function returns -1 and sets ‘errno’ to
  5096. one of the following values.
  5097. ‘EAGAIN’
  5098. The request was not enqueued due to (temporarily) exceeded
  5099. resource limitations.
  5100. ‘ENOSYS’
  5101. The ‘aio_write’ function is not implemented.
  5102. ‘EBADF’
  5103. The ‘aiocbp->aio_fildes’ descriptor is not valid. This
  5104. condition may not be recognized before enqueueing the request,
  5105. and so this error might also be signaled asynchronously.
  5106. ‘EINVAL’
  5107. The ‘aiocbp->aio_offset’ or ‘aiocbp->aio_reqprio’ value is
  5108. invalid. This condition may not be recognized before
  5109. enqueueing the request and so this error might also be
  5110. signaled asynchronously.
  5111. In the case ‘aio_write’ returns zero, the current status of the
  5112. request can be queried using the ‘aio_error’ and ‘aio_return’
  5113. functions. As long as the value returned by ‘aio_error’ is
  5114. ‘EINPROGRESS’ the operation has not yet completed. If ‘aio_error’
  5115. returns zero, the operation successfully terminated, otherwise the
  5116. value is to be interpreted as an error code. If the function
  5117. terminated, the result of the operation can be obtained using a
  5118. call to ‘aio_return’. The returned value is the same as an
  5119. equivalent call to ‘read’ would have returned. Possible error
  5120. codes returned by ‘aio_error’ are:
  5121. ‘EBADF’
  5122. The ‘aiocbp->aio_fildes’ descriptor is not valid.
  5123. ‘ECANCELED’
  5124. The operation was canceled before the operation was finished.
  5125. (*note Cancel AIO Operations::)
  5126. ‘EINVAL’
  5127. The ‘aiocbp->aio_offset’ value is invalid.
  5128. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
  5129. function is in fact ‘aio_write64’ since the LFS interface
  5130. transparently replaces the normal implementation.
  5131. -- Function: int aio_write64 (struct aiocb64 *AIOCBP)
  5132. Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
  5133. *Note POSIX Safety Concepts::.
  5134. This function is similar to the ‘aio_write’ function. The only
  5135. difference is that on 32 bit machines the file descriptor should be
  5136. opened in the large file mode. Internally ‘aio_write64’ uses
  5137. functionality equivalent to ‘lseek64’ (*note File Position
  5138. Primitive::) to position the file descriptor correctly for the
  5139. writing, as opposed to the ‘lseek’ functionality used in
  5140. ‘aio_write’.
  5141. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
  5142. function is available under the name ‘aio_write’ and so
  5143. transparently replaces the interface for small files on 32 bit
  5144. machines.
  5145. Besides these functions with the more or less traditional interface,
  5146. POSIX.1b also defines a function which can initiate more than one
  5147. operation at a time, and which can handle freely mixed read and write
  5148. operations. It is therefore similar to a combination of ‘readv’ and
  5149. ‘writev’.
  5150. -- Function: int lio_listio (int MODE, struct aiocb *const LIST[], int
  5151. NENT, struct sigevent *SIG)
  5152. Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
  5153. *Note POSIX Safety Concepts::.
  5154. The ‘lio_listio’ function can be used to enqueue an arbitrary
  5155. number of read and write requests at one time. The requests can
  5156. all be meant for the same file, all for different files or every
  5157. solution in between.
  5158. ‘lio_listio’ gets the NENT requests from the array pointed to by
  5159. LIST. The operation to be performed is determined by the
  5160. ‘aio_lio_opcode’ member in each element of LIST. If this field is
  5161. ‘LIO_READ’ a read operation is enqueued, similar to a call of
  5162. ‘aio_read’ for this element of the array (except that the way the
  5163. termination is signalled is different, as we will see below). If
  5164. the ‘aio_lio_opcode’ member is ‘LIO_WRITE’ a write operation is
  5165. enqueued. Otherwise the ‘aio_lio_opcode’ must be ‘LIO_NOP’ in
  5166. which case this element of LIST is simply ignored. This
  5167. “operation” is useful in situations where one has a fixed array of
  5168. ‘struct aiocb’ elements from which only a few need to be handled at
  5169. a time. Another situation is where the ‘lio_listio’ call was
  5170. canceled before all requests are processed (*note Cancel AIO
  5171. Operations::) and the remaining requests have to be reissued.
  5172. The other members of each element of the array pointed to by ‘list’
  5173. must have values suitable for the operation as described in the
  5174. documentation for ‘aio_read’ and ‘aio_write’ above.
  5175. The MODE argument determines how ‘lio_listio’ behaves after having
  5176. enqueued all the requests. If MODE is ‘LIO_WAIT’ it waits until
  5177. all requests terminated. Otherwise MODE must be ‘LIO_NOWAIT’ and
  5178. in this case the function returns immediately after having enqueued
  5179. all the requests. In this case the caller gets a notification of
  5180. the termination of all requests according to the SIG parameter. If
  5181. SIG is ‘NULL’ no notification is sent. Otherwise a signal is sent
  5182. or a thread is started, just as described in the description for
  5183. ‘aio_read’ or ‘aio_write’.
  5184. If MODE is ‘LIO_WAIT’, the return value of ‘lio_listio’ is 0 when
  5185. all requests completed successfully. Otherwise the function
  5186. returns -1 and ‘errno’ is set accordingly. To find out which
  5187. request or requests failed one has to use the ‘aio_error’ function
  5188. on all the elements of the array LIST.
  5189. In case MODE is ‘LIO_NOWAIT’, the function returns 0 if all
  5190. requests were enqueued correctly. The current state of the
  5191. requests can be found using ‘aio_error’ and ‘aio_return’ as
  5192. described above. If ‘lio_listio’ returns -1 in this mode, the
  5193. global variable ‘errno’ is set accordingly. If a request did not
  5194. yet terminate, a call to ‘aio_error’ returns ‘EINPROGRESS’. If the
  5195. value is different, the request is finished and the error value (or
  5196. 0) is returned and the result of the operation can be retrieved
  5197. using ‘aio_return’.
  5198. Possible values for ‘errno’ are:
  5199. ‘EAGAIN’
  5200. The resources necessary to queue all the requests are not
  5201. available at the moment. The error status for each element of
  5202. LIST must be checked to determine which request failed.
  5203. Another reason could be that the system wide limit of AIO
  5204. requests is exceeded. This cannot be the case for the
  5205. implementation on GNU systems since no arbitrary limits exist.
  5206. ‘EINVAL’
  5207. The MODE parameter is invalid or NENT is larger than
  5208. ‘AIO_LISTIO_MAX’.
  5209. ‘EIO’
  5210. One or more of the request’s I/O operations failed. The error
  5211. status of each request should be checked to determine which
  5212. one failed.
  5213. ‘ENOSYS’
  5214. The ‘lio_listio’ function is not supported.
  5215. If the MODE parameter is ‘LIO_NOWAIT’ and the caller cancels a
  5216. request, the error status for this request returned by ‘aio_error’
  5217. is ‘ECANCELED’.
  5218. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
  5219. function is in fact ‘lio_listio64’ since the LFS interface
  5220. transparently replaces the normal implementation.
  5221. -- Function: int lio_listio64 (int MODE, struct aiocb64 *const LIST[],
  5222. int NENT, struct sigevent *SIG)
  5223. Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
  5224. *Note POSIX Safety Concepts::.
  5225. This function is similar to the ‘lio_listio’ function. The only
  5226. difference is that on 32 bit machines, the file descriptor should
  5227. be opened in the large file mode. Internally, ‘lio_listio64’ uses
  5228. functionality equivalent to ‘lseek64’ (*note File Position
  5229. Primitive::) to position the file descriptor correctly for the
  5230. reading or writing, as opposed to the ‘lseek’ functionality used in
  5231. ‘lio_listio’.
  5232. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
  5233. function is available under the name ‘lio_listio’ and so
  5234. transparently replaces the interface for small files on 32 bit
  5235. machines.
  5236. 
  5237. File: libc.info, Node: Status of AIO Operations, Next: Synchronizing AIO Operations, Prev: Asynchronous Reads/Writes, Up: Asynchronous I/O
  5238. 13.10.2 Getting the Status of AIO Operations
  5239. --------------------------------------------
  5240. As already described in the documentation of the functions in the last
  5241. section, it must be possible to get information about the status of an
  5242. I/O request. When the operation is performed truly asynchronously (as
  5243. with ‘aio_read’ and ‘aio_write’ and with ‘lio_listio’ when the mode is
  5244. ‘LIO_NOWAIT’), one sometimes needs to know whether a specific request
  5245. already terminated and if so, what the result was. The following two
  5246. functions allow you to get this kind of information.
  5247. -- Function: int aio_error (const struct aiocb *AIOCBP)
  5248. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  5249. Concepts::.
  5250. This function determines the error state of the request described
  5251. by the ‘struct aiocb’ variable pointed to by AIOCBP. If the
  5252. request has not yet terminated the value returned is always
  5253. ‘EINPROGRESS’. Once the request has terminated the value
  5254. ‘aio_error’ returns is either 0 if the request completed
  5255. successfully or it returns the value which would be stored in the
  5256. ‘errno’ variable if the request would have been done using ‘read’,
  5257. ‘write’, or ‘fsync’.
  5258. The function can return ‘ENOSYS’ if it is not implemented. It
  5259. could also return ‘EINVAL’ if the AIOCBP parameter does not refer
  5260. to an asynchronous operation whose return status is not yet known.
  5261. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
  5262. function is in fact ‘aio_error64’ since the LFS interface
  5263. transparently replaces the normal implementation.
  5264. -- Function: int aio_error64 (const struct aiocb64 *AIOCBP)
  5265. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  5266. Concepts::.
  5267. This function is similar to ‘aio_error’ with the only difference
  5268. that the argument is a reference to a variable of type ‘struct
  5269. aiocb64’.
  5270. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
  5271. function is available under the name ‘aio_error’ and so
  5272. transparently replaces the interface for small files on 32 bit
  5273. machines.
  5274. -- Function: ssize_t aio_return (struct aiocb *AIOCBP)
  5275. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  5276. Concepts::.
  5277. This function can be used to retrieve the return status of the
  5278. operation carried out by the request described in the variable
  5279. pointed to by AIOCBP. As long as the error status of this request
  5280. as returned by ‘aio_error’ is ‘EINPROGRESS’ the return value of
  5281. this function is undefined.
  5282. Once the request is finished this function can be used exactly once
  5283. to retrieve the return value. Following calls might lead to
  5284. undefined behavior. The return value itself is the value which
  5285. would have been returned by the ‘read’, ‘write’, or ‘fsync’ call.
  5286. The function can return ‘ENOSYS’ if it is not implemented. It
  5287. could also return ‘EINVAL’ if the AIOCBP parameter does not refer
  5288. to an asynchronous operation whose return status is not yet known.
  5289. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
  5290. function is in fact ‘aio_return64’ since the LFS interface
  5291. transparently replaces the normal implementation.
  5292. -- Function: ssize_t aio_return64 (struct aiocb64 *AIOCBP)
  5293. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  5294. Concepts::.
  5295. This function is similar to ‘aio_return’ with the only difference
  5296. that the argument is a reference to a variable of type ‘struct
  5297. aiocb64’.
  5298. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
  5299. function is available under the name ‘aio_return’ and so
  5300. transparently replaces the interface for small files on 32 bit
  5301. machines.
  5302. 
  5303. File: libc.info, Node: Synchronizing AIO Operations, Next: Cancel AIO Operations, Prev: Status of AIO Operations, Up: Asynchronous I/O
  5304. 13.10.3 Getting into a Consistent State
  5305. ---------------------------------------
  5306. When dealing with asynchronous operations it is sometimes necessary to
  5307. get into a consistent state. This would mean for AIO that one wants to
  5308. know whether a certain request or a group of requests were processed.
  5309. This could be done by waiting for the notification sent by the system
  5310. after the operation terminated, but this sometimes would mean wasting
  5311. resources (mainly computation time). Instead POSIX.1b defines two
  5312. functions which will help with most kinds of consistency.
  5313. The ‘aio_fsync’ and ‘aio_fsync64’ functions are only available if the
  5314. symbol ‘_POSIX_SYNCHRONIZED_IO’ is defined in ‘unistd.h’.
  5315. -- Function: int aio_fsync (int OP, struct aiocb *AIOCBP)
  5316. Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
  5317. *Note POSIX Safety Concepts::.
  5318. Calling this function forces all I/O operations queued at the time
  5319. of the function call operating on the file descriptor
  5320. ‘aiocbp->aio_fildes’ into the synchronized I/O completion state
  5321. (*note Synchronizing I/O::). The ‘aio_fsync’ function returns
  5322. immediately but the notification through the method described in
  5323. ‘aiocbp->aio_sigevent’ will happen only after all requests for this
  5324. file descriptor have terminated and the file is synchronized. This
  5325. also means that requests for this very same file descriptor which
  5326. are queued after the synchronization request are not affected.
  5327. If OP is ‘O_DSYNC’ the synchronization happens as with a call to
  5328. ‘fdatasync’. Otherwise OP should be ‘O_SYNC’ and the
  5329. synchronization happens as with ‘fsync’.
  5330. As long as the synchronization has not happened, a call to
  5331. ‘aio_error’ with the reference to the object pointed to by AIOCBP
  5332. returns ‘EINPROGRESS’. Once the synchronization is done
  5333. ‘aio_error’ return 0 if the synchronization was not successful.
  5334. Otherwise the value returned is the value to which the ‘fsync’ or
  5335. ‘fdatasync’ function would have set the ‘errno’ variable. In this
  5336. case nothing can be assumed about the consistency of the data
  5337. written to this file descriptor.
  5338. The return value of this function is 0 if the request was
  5339. successfully enqueued. Otherwise the return value is -1 and
  5340. ‘errno’ is set to one of the following values:
  5341. ‘EAGAIN’
  5342. The request could not be enqueued due to temporary lack of
  5343. resources.
  5344. ‘EBADF’
  5345. The file descriptor ‘AIOCBP->aio_fildes’ is not valid.
  5346. ‘EINVAL’
  5347. The implementation does not support I/O synchronization or the
  5348. OP parameter is other than ‘O_DSYNC’ and ‘O_SYNC’.
  5349. ‘ENOSYS’
  5350. This function is not implemented.
  5351. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
  5352. function is in fact ‘aio_fsync64’ since the LFS interface
  5353. transparently replaces the normal implementation.
  5354. -- Function: int aio_fsync64 (int OP, struct aiocb64 *AIOCBP)
  5355. Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
  5356. *Note POSIX Safety Concepts::.
  5357. This function is similar to ‘aio_fsync’ with the only difference
  5358. that the argument is a reference to a variable of type ‘struct
  5359. aiocb64’.
  5360. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
  5361. function is available under the name ‘aio_fsync’ and so
  5362. transparently replaces the interface for small files on 32 bit
  5363. machines.
  5364. Another method of synchronization is to wait until one or more
  5365. requests of a specific set terminated. This could be achieved by the
  5366. ‘aio_*’ functions to notify the initiating process about the termination
  5367. but in some situations this is not the ideal solution. In a program
  5368. which constantly updates clients somehow connected to the server it is
  5369. not always the best solution to go round robin since some connections
  5370. might be slow. On the other hand letting the ‘aio_*’ functions notify
  5371. the caller might also be not the best solution since whenever the
  5372. process works on preparing data for a client it makes no sense to be
  5373. interrupted by a notification since the new client will not be handled
  5374. before the current client is served. For situations like this
  5375. ‘aio_suspend’ should be used.
  5376. -- Function: int aio_suspend (const struct aiocb *const LIST[], int
  5377. NENT, const struct timespec *TIMEOUT)
  5378. Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
  5379. POSIX Safety Concepts::.
  5380. When calling this function, the calling thread is suspended until
  5381. at least one of the requests pointed to by the NENT elements of the
  5382. array LIST has completed. If any of the requests has already
  5383. completed at the time ‘aio_suspend’ is called, the function returns
  5384. immediately. Whether a request has terminated or not is determined
  5385. by comparing the error status of the request with ‘EINPROGRESS’.
  5386. If an element of LIST is ‘NULL’, the entry is simply ignored.
  5387. If no request has finished, the calling process is suspended. If
  5388. TIMEOUT is ‘NULL’, the process is not woken until a request has
  5389. finished. If TIMEOUT is not ‘NULL’, the process remains suspended
  5390. at least as long as specified in TIMEOUT. In this case,
  5391. ‘aio_suspend’ returns with an error.
  5392. The return value of the function is 0 if one or more requests from
  5393. the LIST have terminated. Otherwise the function returns -1 and
  5394. ‘errno’ is set to one of the following values:
  5395. ‘EAGAIN’
  5396. None of the requests from the LIST completed in the time
  5397. specified by TIMEOUT.
  5398. ‘EINTR’
  5399. A signal interrupted the ‘aio_suspend’ function. This signal
  5400. might also be sent by the AIO implementation while signalling
  5401. the termination of one of the requests.
  5402. ‘ENOSYS’
  5403. The ‘aio_suspend’ function is not implemented.
  5404. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
  5405. function is in fact ‘aio_suspend64’ since the LFS interface
  5406. transparently replaces the normal implementation.
  5407. -- Function: int aio_suspend64 (const struct aiocb64 *const LIST[], int
  5408. NENT, const struct timespec *TIMEOUT)
  5409. Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
  5410. POSIX Safety Concepts::.
  5411. This function is similar to ‘aio_suspend’ with the only difference
  5412. that the argument is a reference to a variable of type ‘struct
  5413. aiocb64’.
  5414. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ this
  5415. function is available under the name ‘aio_suspend’ and so
  5416. transparently replaces the interface for small files on 32 bit
  5417. machines.
  5418. 
  5419. File: libc.info, Node: Cancel AIO Operations, Next: Configuration of AIO, Prev: Synchronizing AIO Operations, Up: Asynchronous I/O
  5420. 13.10.4 Cancellation of AIO Operations
  5421. --------------------------------------
  5422. When one or more requests are asynchronously processed, it might be
  5423. useful in some situations to cancel a selected operation, e.g., if it
  5424. becomes obvious that the written data is no longer accurate and would
  5425. have to be overwritten soon. As an example, assume an application,
  5426. which writes data in files in a situation where new incoming data would
  5427. have to be written in a file which will be updated by an enqueued
  5428. request. The POSIX AIO implementation provides such a function, but
  5429. this function is not capable of forcing the cancellation of the request.
  5430. It is up to the implementation to decide whether it is possible to
  5431. cancel the operation or not. Therefore using this function is merely a
  5432. hint.
  5433. -- Function: int aio_cancel (int FILDES, struct aiocb *AIOCBP)
  5434. Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
  5435. *Note POSIX Safety Concepts::.
  5436. The ‘aio_cancel’ function can be used to cancel one or more
  5437. outstanding requests. If the AIOCBP parameter is ‘NULL’, the
  5438. function tries to cancel all of the outstanding requests which
  5439. would process the file descriptor FILDES (i.e., whose ‘aio_fildes’
  5440. member is FILDES). If AIOCBP is not ‘NULL’, ‘aio_cancel’ attempts
  5441. to cancel the specific request pointed to by AIOCBP.
  5442. For requests which were successfully canceled, the normal
  5443. notification about the termination of the request should take
  5444. place. I.e., depending on the ‘struct sigevent’ object which
  5445. controls this, nothing happens, a signal is sent or a thread is
  5446. started. If the request cannot be canceled, it terminates the
  5447. usual way after performing the operation.
  5448. After a request is successfully canceled, a call to ‘aio_error’
  5449. with a reference to this request as the parameter will return
  5450. ‘ECANCELED’ and a call to ‘aio_return’ will return -1. If the
  5451. request wasn’t canceled and is still running the error status is
  5452. still ‘EINPROGRESS’.
  5453. The return value of the function is ‘AIO_CANCELED’ if there were
  5454. requests which haven’t terminated and which were successfully
  5455. canceled. If there is one or more requests left which couldn’t be
  5456. canceled, the return value is ‘AIO_NOTCANCELED’. In this case
  5457. ‘aio_error’ must be used to find out which of the, perhaps
  5458. multiple, requests (if AIOCBP is ‘NULL’) weren’t successfully
  5459. canceled. If all requests already terminated at the time
  5460. ‘aio_cancel’ is called the return value is ‘AIO_ALLDONE’.
  5461. If an error occurred during the execution of ‘aio_cancel’ the
  5462. function returns -1 and sets ‘errno’ to one of the following
  5463. values.
  5464. ‘EBADF’
  5465. The file descriptor FILDES is not valid.
  5466. ‘ENOSYS’
  5467. ‘aio_cancel’ is not implemented.
  5468. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
  5469. function is in fact ‘aio_cancel64’ since the LFS interface
  5470. transparently replaces the normal implementation.
  5471. -- Function: int aio_cancel64 (int FILDES, struct aiocb64 *AIOCBP)
  5472. Preliminary: | MT-Safe | AS-Unsafe lock heap | AC-Unsafe lock mem |
  5473. *Note POSIX Safety Concepts::.
  5474. This function is similar to ‘aio_cancel’ with the only difference
  5475. that the argument is a reference to a variable of type ‘struct
  5476. aiocb64’.
  5477. When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’, this
  5478. function is available under the name ‘aio_cancel’ and so
  5479. transparently replaces the interface for small files on 32 bit
  5480. machines.
  5481. 
  5482. File: libc.info, Node: Configuration of AIO, Prev: Cancel AIO Operations, Up: Asynchronous I/O
  5483. 13.10.5 How to optimize the AIO implementation
  5484. ----------------------------------------------
  5485. The POSIX standard does not specify how the AIO functions are
  5486. implemented. They could be system calls, but it is also possible to
  5487. emulate them at userlevel.
  5488. At the time of writing, the available implementation is a user-level
  5489. implementation which uses threads for handling the enqueued requests.
  5490. While this implementation requires making some decisions about
  5491. limitations, hard limitations are something best avoided in the GNU C
  5492. Library. Therefore, the GNU C Library provides a means for tuning the
  5493. AIO implementation according to the individual use.
  5494. -- Data Type: struct aioinit
  5495. This data type is used to pass the configuration or tunable
  5496. parameters to the implementation. The program has to initialize
  5497. the members of this struct and pass it to the implementation using
  5498. the ‘aio_init’ function.
  5499. ‘int aio_threads’
  5500. This member specifies the maximal number of threads which may
  5501. be used at any one time.
  5502. ‘int aio_num’
  5503. This number provides an estimate on the maximal number of
  5504. simultaneously enqueued requests.
  5505. ‘int aio_locks’
  5506. Unused.
  5507. ‘int aio_usedba’
  5508. Unused.
  5509. ‘int aio_debug’
  5510. Unused.
  5511. ‘int aio_numusers’
  5512. Unused.
  5513. ‘int aio_reserved[2]’
  5514. Unused.
  5515. -- Function: void aio_init (const struct aioinit *INIT)
  5516. Preliminary: | MT-Safe | AS-Unsafe lock | AC-Unsafe lock | *Note
  5517. POSIX Safety Concepts::.
  5518. This function must be called before any other AIO function.
  5519. Calling it is completely voluntary, as it is only meant to help the
  5520. AIO implementation perform better.
  5521. Before calling ‘aio_init’, the members of a variable of type
  5522. ‘struct aioinit’ must be initialized. Then a reference to this
  5523. variable is passed as the parameter to ‘aio_init’ which itself may
  5524. or may not pay attention to the hints.
  5525. The function has no return value and no error cases are defined.
  5526. It is an extension which follows a proposal from the SGI
  5527. implementation in Irix 6. It is not covered by POSIX.1b or Unix98.
  5528. 
  5529. File: libc.info, Node: Control Operations, Next: Duplicating Descriptors, Prev: Asynchronous I/O, Up: Low-Level I/O
  5530. 13.11 Control Operations on Files
  5531. =================================
  5532. This section describes how you can perform various other operations on
  5533. file descriptors, such as inquiring about or setting flags describing
  5534. the status of the file descriptor, manipulating record locks, and the
  5535. like. All of these operations are performed by the function ‘fcntl’.
  5536. The second argument to the ‘fcntl’ function is a command that
  5537. specifies which operation to perform. The function and macros that name
  5538. various flags that are used with it are declared in the header file
  5539. ‘fcntl.h’. Many of these flags are also used by the ‘open’ function;
  5540. see *note Opening and Closing Files::.
  5541. -- Function: int fcntl (int FILEDES, int COMMAND, …)
  5542. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  5543. Concepts::.
  5544. The ‘fcntl’ function performs the operation specified by COMMAND on
  5545. the file descriptor FILEDES. Some commands require additional
  5546. arguments to be supplied. These additional arguments and the
  5547. return value and error conditions are given in the detailed
  5548. descriptions of the individual commands.
  5549. Briefly, here is a list of what the various commands are.
  5550. ‘F_DUPFD’
  5551. Duplicate the file descriptor (return another file descriptor
  5552. pointing to the same open file). *Note Duplicating
  5553. Descriptors::.
  5554. ‘F_GETFD’
  5555. Get flags associated with the file descriptor. *Note
  5556. Descriptor Flags::.
  5557. ‘F_SETFD’
  5558. Set flags associated with the file descriptor. *Note
  5559. Descriptor Flags::.
  5560. ‘F_GETFL’
  5561. Get flags associated with the open file. *Note File Status
  5562. Flags::.
  5563. ‘F_SETFL’
  5564. Set flags associated with the open file. *Note File Status
  5565. Flags::.
  5566. ‘F_GETLK’
  5567. Test a file lock. *Note File Locks::.
  5568. ‘F_SETLK’
  5569. Set or clear a file lock. *Note File Locks::.
  5570. ‘F_SETLKW’
  5571. Like ‘F_SETLK’, but wait for completion. *Note File Locks::.
  5572. ‘F_OFD_GETLK’
  5573. Test an open file description lock. *Note Open File
  5574. Description Locks::. Specific to Linux.
  5575. ‘F_OFD_SETLK’
  5576. Set or clear an open file description lock. *Note Open File
  5577. Description Locks::. Specific to Linux.
  5578. ‘F_OFD_SETLKW’
  5579. Like ‘F_OFD_SETLK’, but block until lock is acquired. *Note
  5580. Open File Description Locks::. Specific to Linux.
  5581. ‘F_GETOWN’
  5582. Get process or process group ID to receive ‘SIGIO’ signals.
  5583. *Note Interrupt Input::.
  5584. ‘F_SETOWN’
  5585. Set process or process group ID to receive ‘SIGIO’ signals.
  5586. *Note Interrupt Input::.
  5587. This function is a cancellation point in multi-threaded programs.
  5588. This is a problem if the thread allocates some resources (like
  5589. memory, file descriptors, semaphores or whatever) at the time
  5590. ‘fcntl’ is called. If the thread gets canceled these resources
  5591. stay allocated until the program ends. To avoid this calls to
  5592. ‘fcntl’ should be protected using cancellation handlers.
  5593. 
  5594. File: libc.info, Node: Duplicating Descriptors, Next: Descriptor Flags, Prev: Control Operations, Up: Low-Level I/O
  5595. 13.12 Duplicating Descriptors
  5596. =============================
  5597. You can "duplicate" a file descriptor, or allocate another file
  5598. descriptor that refers to the same open file as the original. Duplicate
  5599. descriptors share one file position and one set of file status flags
  5600. (*note File Status Flags::), but each has its own set of file descriptor
  5601. flags (*note Descriptor Flags::).
  5602. The major use of duplicating a file descriptor is to implement
  5603. "redirection" of input or output: that is, to change the file or pipe
  5604. that a particular file descriptor corresponds to.
  5605. You can perform this operation using the ‘fcntl’ function with the
  5606. ‘F_DUPFD’ command, but there are also convenient functions ‘dup’ and
  5607. ‘dup2’ for duplicating descriptors.
  5608. The ‘fcntl’ function and flags are declared in ‘fcntl.h’, while
  5609. prototypes for ‘dup’ and ‘dup2’ are in the header file ‘unistd.h’.
  5610. -- Function: int dup (int OLD)
  5611. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  5612. Concepts::.
  5613. This function copies descriptor OLD to the first available
  5614. descriptor number (the first number not currently open). It is
  5615. equivalent to ‘fcntl (OLD, F_DUPFD, 0)’.
  5616. -- Function: int dup2 (int OLD, int NEW)
  5617. Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
  5618. Concepts::.
  5619. This function copies the descriptor OLD to descriptor number NEW.
  5620. If OLD is an invalid descriptor, then ‘dup2’ does nothing; it does
  5621. not close NEW. Otherwise, the new duplicate of OLD replaces any
  5622. previous meaning of descriptor NEW, as if NEW were closed first.
  5623. If OLD and NEW are different numbers, and OLD is a valid descriptor
  5624. number, then ‘dup2’ is equivalent to:
  5625. close (NEW);
  5626. fcntl (OLD, F_DUPFD, NEW)
  5627. However, ‘dup2’ does this atomically; there is no instant in the
  5628. middle of calling ‘dup2’ at which NEW is closed and not yet a
  5629. duplicate of OLD.
  5630. -- Macro: int F_DUPFD
  5631. This macro is used as the COMMAND argument to ‘fcntl’, to copy the
  5632. file descriptor given as the first argument.
  5633. The form of the call in this case is:
  5634. fcntl (OLD, F_DUPFD, NEXT-FILEDES)
  5635. The NEXT-FILEDES argument is of type ‘int’ and specifies that the
  5636. file descriptor returned should be the next available one greater
  5637. than or equal to this value.
  5638. The return value from ‘fcntl’ with this command is normally the
  5639. value of the new file descriptor. A return value of -1 indicates
  5640. an error. The following ‘errno’ error conditions are defined for
  5641. this command:
  5642. ‘EBADF’
  5643. The OLD argument is invalid.
  5644. ‘EINVAL’
  5645. The NEXT-FILEDES argument is invalid.
  5646. ‘EMFILE’
  5647. There are no more file descriptors available—your program is
  5648. already using the maximum. In BSD and GNU, the maximum is
  5649. controlled by a resource limit that can be changed; *note
  5650. Limits on Resources::, for more information about the
  5651. ‘RLIMIT_NOFILE’ limit.
  5652. ‘ENFILE’ is not a possible error code for ‘dup2’ because ‘dup2’
  5653. does not create a new opening of a file; duplicate descriptors do
  5654. not count toward the limit which ‘ENFILE’ indicates. ‘EMFILE’ is
  5655. possible because it refers to the limit on distinct descriptor
  5656. numbers in use in one process.
  5657. Here is an example showing how to use ‘dup2’ to do redirection.
  5658. Typically, redirection of the standard streams (like ‘stdin’) is done by
  5659. a shell or shell-like program before calling one of the ‘exec’ functions
  5660. (*note Executing a File::) to execute a new program in a child process.
  5661. When the new program is executed, it creates and initializes the
  5662. standard streams to point to the corresponding file descriptors, before
  5663. its ‘main’ function is invoked.
  5664. So, to redirect standard input to a file, the shell could do
  5665. something like:
  5666. pid = fork ();
  5667. if (pid == 0)
  5668. {
  5669. char *filename;
  5670. char *program;
  5671. int file;
  5672. file = TEMP_FAILURE_RETRY (open (filename, O_RDONLY));
  5673. dup2 (file, STDIN_FILENO);
  5674. TEMP_FAILURE_RETRY (close (file));
  5675. execv (program, NULL);
  5676. }
  5677. There is also a more detailed example showing how to implement
  5678. redirection in the context of a pipeline of processes in *note Launching
  5679. Jobs::.
  5680. 
  5681. File: libc.info, Node: Descriptor Flags, Next: File Status Flags, Prev: Duplicating Descriptors, Up: Low-Level I/O
  5682. 13.13 File Descriptor Flags
  5683. ===========================
  5684. "File descriptor flags" are miscellaneous attributes of a file
  5685. descriptor. These flags are associated with particular file
  5686. descriptors, so that if you have created duplicate file descriptors from
  5687. a single opening of a file, each descriptor has its own set of flags.
  5688. Currently there is just one file descriptor flag: ‘FD_CLOEXEC’, which
  5689. causes the descriptor to be closed if you use any of the ‘exec…’
  5690. functions (*note Executing a File::).
  5691. The symbols in this section are defined in the header file ‘fcntl.h’.
  5692. -- Macro: int F_GETFD
  5693. This macro is used as the COMMAND argument to ‘fcntl’, to specify
  5694. that it should return the file descriptor flags associated with the
  5695. FILEDES argument.
  5696. The normal return value from ‘fcntl’ with this command is a
  5697. nonnegative number which can be interpreted as the bitwise OR of
  5698. the individual flags (except that currently there is only one flag
  5699. to use).
  5700. In case of an error, ‘fcntl’ returns -1. The following ‘errno’
  5701. error conditions are defined for this command:
  5702. ‘EBADF’
  5703. The FILEDES argument is invalid.
  5704. -- Macro: int F_SETFD
  5705. This macro is used as the COMMAND argument to ‘fcntl’, to specify
  5706. that it should set the file descriptor flags associated with the
  5707. FILEDES argument. This requires a third ‘int’ argument to specify
  5708. the new flags, so the form of the call is:
  5709. fcntl (FILEDES, F_SETFD, NEW-FLAGS)
  5710. The normal return value from ‘fcntl’ with this command is an
  5711. unspecified value other than -1, which indicates an error. The
  5712. flags and error conditions are the same as for the ‘F_GETFD’
  5713. command.
  5714. The following macro is defined for use as a file descriptor flag with
  5715. the ‘fcntl’ function. The value is an integer constant usable as a bit
  5716. mask value.
  5717. -- Macro: int FD_CLOEXEC
  5718. This flag specifies that the file descriptor should be closed when
  5719. an ‘exec’ function is invoked; see *note Executing a File::. When
  5720. a file descriptor is allocated (as with ‘open’ or ‘dup’), this bit
  5721. is initially cleared on the new file descriptor, meaning that
  5722. descriptor will survive into the new program after ‘exec’.
  5723. If you want to modify the file descriptor flags, you should get the
  5724. current flags with ‘F_GETFD’ and modify the value. Don’t assume that
  5725. the flags listed here are the only ones that are implemented; your
  5726. program may be run years from now and more flags may exist then. For
  5727. example, here is a function to set or clear the flag ‘FD_CLOEXEC’
  5728. without altering any other flags:
  5729. /* Set the ‘FD_CLOEXEC’ flag of DESC if VALUE is nonzero,
  5730. or clear the flag if VALUE is 0.
  5731. Return 0 on success, or -1 on error with ‘errno’ set. */
  5732. int
  5733. set_cloexec_flag (int desc, int value)
  5734. {
  5735. int oldflags = fcntl (desc, F_GETFD, 0);
  5736. /* If reading the flags failed, return error indication now. */
  5737. if (oldflags < 0)
  5738. return oldflags;
  5739. /* Set just the flag we want to set. */
  5740. if (value != 0)
  5741. oldflags |= FD_CLOEXEC;
  5742. else
  5743. oldflags &= ~FD_CLOEXEC;
  5744. /* Store modified flag word in the descriptor. */
  5745. return fcntl (desc, F_SETFD, oldflags);
  5746. }
  5747. 
  5748. File: libc.info, Node: File Status Flags, Next: File Locks, Prev: Descriptor Flags, Up: Low-Level I/O
  5749. 13.14 File Status Flags
  5750. =======================
  5751. "File status flags" are used to specify attributes of the opening of a
  5752. file. Unlike the file descriptor flags discussed in *note Descriptor
  5753. Flags::, the file status flags are shared by duplicated file descriptors
  5754. resulting from a single opening of the file. The file status flags are
  5755. specified with the FLAGS argument to ‘open’; *note Opening and Closing
  5756. Files::.
  5757. File status flags fall into three categories, which are described in
  5758. the following sections.
  5759. • *note Access Modes::, specify what type of access is allowed to the
  5760. file: reading, writing, or both. They are set by ‘open’ and are
  5761. returned by ‘fcntl’, but cannot be changed.
  5762. • *note Open-time Flags::, control details of what ‘open’ will do.
  5763. These flags are not preserved after the ‘open’ call.
  5764. • *note Operating Modes::, affect how operations such as ‘read’ and
  5765. ‘write’ are done. They are set by ‘open’, and can be fetched or
  5766. changed with ‘fcntl’.
  5767. The symbols in this section are defined in the header file ‘fcntl.h’.
  5768. * Menu:
  5769. * Access Modes:: Whether the descriptor can read or write.
  5770. * Open-time Flags:: Details of ‘open’.
  5771. * Operating Modes:: Special modes to control I/O operations.
  5772. * Getting File Status Flags:: Fetching and changing these flags.
  5773. 
  5774. File: libc.info, Node: Access Modes, Next: Open-time Flags, Up: File Status Flags
  5775. 13.14.1 File Access Modes
  5776. -------------------------
  5777. The file access modes allow a file descriptor to be used for reading,
  5778. writing, or both. (On GNU/Hurd systems, they can also allow none of
  5779. these, and allow execution of the file as a program.) The access modes
  5780. are chosen when the file is opened, and never change.
  5781. -- Macro: int O_RDONLY
  5782. Open the file for read access.
  5783. -- Macro: int O_WRONLY
  5784. Open the file for write access.
  5785. -- Macro: int O_RDWR
  5786. Open the file for both reading and writing.
  5787. On GNU/Hurd systems (and not on other systems), ‘O_RDONLY’ and
  5788. ‘O_WRONLY’ are independent bits that can be bitwise-ORed together, and
  5789. it is valid for either bit to be set or clear. This means that ‘O_RDWR’
  5790. is the same as ‘O_RDONLY|O_WRONLY’. A file access mode of zero is
  5791. permissible; it allows no operations that do input or output to the
  5792. file, but does allow other operations such as ‘fchmod’. On GNU/Hurd
  5793. systems, since “read-only” or “write-only” is a misnomer, ‘fcntl.h’
  5794. defines additional names for the file access modes. These names are
  5795. preferred when writing GNU-specific code. But most programs will want
  5796. to be portable to other POSIX.1 systems and should use the POSIX.1 names
  5797. above instead.
  5798. -- Macro: int O_READ
  5799. Open the file for reading. Same as ‘O_RDONLY’; only defined on
  5800. GNU.
  5801. -- Macro: int O_WRITE
  5802. Open the file for writing. Same as ‘O_WRONLY’; only defined on
  5803. GNU.
  5804. -- Macro: int O_EXEC
  5805. Open the file for executing. Only defined on GNU.
  5806. To determine the file access mode with ‘fcntl’, you must extract the
  5807. access mode bits from the retrieved file status flags. On GNU/Hurd
  5808. systems, you can just test the ‘O_READ’ and ‘O_WRITE’ bits in the flags
  5809. word. But in other POSIX.1 systems, reading and writing access modes
  5810. are not stored as distinct bit flags. The portable way to extract the
  5811. file access mode bits is with ‘O_ACCMODE’.
  5812. -- Macro: int O_ACCMODE
  5813. This macro stands for a mask that can be bitwise-ANDed with the
  5814. file status flag value to produce a value representing the file
  5815. access mode. The mode will be ‘O_RDONLY’, ‘O_WRONLY’, or ‘O_RDWR’.
  5816. (On GNU/Hurd systems it could also be zero, and it never includes
  5817. the ‘O_EXEC’ bit.)
  5818. 
  5819. File: libc.info, Node: Open-time Flags, Next: Operating Modes, Prev: Access Modes, Up: File Status Flags
  5820. 13.14.2 Open-time Flags
  5821. -----------------------
  5822. The open-time flags specify options affecting how ‘open’ will behave.
  5823. These options are not preserved once the file is open. The exception to
  5824. this is ‘O_NONBLOCK’, which is also an I/O operating mode and so it _is_
  5825. saved. *Note Opening and Closing Files::, for how to call ‘open’.
  5826. There are two sorts of options specified by open-time flags.
  5827. • "File name translation flags" affect how ‘open’ looks up the file
  5828. name to locate the file, and whether the file can be created.
  5829. • "Open-time action flags" specify extra operations that ‘open’ will
  5830. perform on the file once it is open.
  5831. Here are the file name translation flags.
  5832. -- Macro: int O_CREAT
  5833. If set, the file will be created if it doesn’t already exist.
  5834. -- Macro: int O_EXCL
  5835. If both ‘O_CREAT’ and ‘O_EXCL’ are set, then ‘open’ fails if the
  5836. specified file already exists. This is guaranteed to never clobber
  5837. an existing file.
  5838. -- Macro: int O_NONBLOCK
  5839. This prevents ‘open’ from blocking for a “long time” to open the
  5840. file. This is only meaningful for some kinds of files, usually
  5841. devices such as serial ports; when it is not meaningful, it is
  5842. harmless and ignored. Often, opening a port to a modem blocks
  5843. until the modem reports carrier detection; if ‘O_NONBLOCK’ is
  5844. specified, ‘open’ will return immediately without a carrier.
  5845. Note that the ‘O_NONBLOCK’ flag is overloaded as both an I/O
  5846. operating mode and a file name translation flag. This means that
  5847. specifying ‘O_NONBLOCK’ in ‘open’ also sets nonblocking I/O mode;
  5848. *note Operating Modes::. To open the file without blocking but do
  5849. normal I/O that blocks, you must call ‘open’ with ‘O_NONBLOCK’ set
  5850. and then call ‘fcntl’ to turn the bit off.
  5851. -- Macro: int O_NOCTTY
  5852. If the named file is a terminal device, don’t make it the
  5853. controlling terminal for the process. *Note Job Control::, for
  5854. information about what it means to be the controlling terminal.
  5855. On GNU/Hurd systems and 4.4 BSD, opening a file never makes it the
  5856. controlling terminal and ‘O_NOCTTY’ is zero. However, GNU/Linux
  5857. systems and some other systems use a nonzero value for ‘O_NOCTTY’
  5858. and set the controlling terminal when you open a file that is a
  5859. terminal device; so to be portable, use ‘O_NOCTTY’ when it is
  5860. important to avoid this.
  5861. The following three file name translation flags exist only on
  5862. GNU/Hurd systems.
  5863. -- Macro: int O_IGNORE_CTTY
  5864. Do not recognize the named file as the controlling terminal, even
  5865. if it refers to the process’s existing controlling terminal device.
  5866. Operations on the new file descriptor will never induce job control
  5867. signals. *Note Job Control::.
  5868. -- Macro: int O_NOLINK
  5869. If the named file is a symbolic link, open the link itself instead
  5870. of the file it refers to. (‘fstat’ on the new file descriptor will
  5871. return the information returned by ‘lstat’ on the link’s name.)
  5872. -- Macro: int O_NOTRANS
  5873. If the named file is specially translated, do not invoke the
  5874. translator. Open the bare file the translator itself sees.
  5875. The open-time action flags tell ‘open’ to do additional operations
  5876. which are not really related to opening the file. The reason to do them
  5877. as part of ‘open’ instead of in separate calls is that ‘open’ can do
  5878. them atomically.
  5879. -- Macro: int O_TRUNC
  5880. Truncate the file to zero length. This option is only useful for
  5881. regular files, not special files such as directories or FIFOs.
  5882. POSIX.1 requires that you open the file for writing to use
  5883. ‘O_TRUNC’. In BSD and GNU you must have permission to write the
  5884. file to truncate it, but you need not open for write access.
  5885. This is the only open-time action flag specified by POSIX.1. There
  5886. is no good reason for truncation to be done by ‘open’, instead of
  5887. by calling ‘ftruncate’ afterwards. The ‘O_TRUNC’ flag existed in
  5888. Unix before ‘ftruncate’ was invented, and is retained for backward
  5889. compatibility.
  5890. The remaining operating modes are BSD extensions. They exist only on
  5891. some systems. On other systems, these macros are not defined.
  5892. -- Macro: int O_SHLOCK
  5893. Acquire a shared lock on the file, as with ‘flock’. *Note File
  5894. Locks::.
  5895. If ‘O_CREAT’ is specified, the locking is done atomically when
  5896. creating the file. You are guaranteed that no other process will
  5897. get the lock on the new file first.
  5898. -- Macro: int O_EXLOCK
  5899. Acquire an exclusive lock on the file, as with ‘flock’. *Note File
  5900. Locks::. This is atomic like ‘O_SHLOCK’.