123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185418641874188418941904191419241934194419541964197419841994200420142024203420442054206420742084209421042114212421342144215421642174218421942204221422242234224422542264227422842294230423142324233423442354236423742384239424042414242424342444245424642474248424942504251425242534254425542564257425842594260426142624263426442654266426742684269427042714272427342744275427642774278427942804281428242834284428542864287428842894290429142924293429442954296429742984299430043014302430343044305430643074308430943104311431243134314431543164317431843194320432143224323432443254326432743284329433043314332433343344335433643374338433943404341434243434344434543464347434843494350435143524353435443554356435743584359436043614362436343644365436643674368436943704371437243734374437543764377437843794380438143824383438443854386438743884389439043914392439343944395439643974398439944004401440244034404440544064407440844094410441144124413441444154416441744184419442044214422442344244425442644274428442944304431443244334434443544364437443844394440444144424443444444454446444744484449445044514452445344544455445644574458445944604461446244634464446544664467446844694470447144724473447444754476447744784479448044814482448344844485448644874488448944904491449244934494449544964497449844994500450145024503450445054506450745084509451045114512451345144515451645174518451945204521452245234524452545264527452845294530453145324533453445354536453745384539454045414542454345444545454645474548454945504551455245534554455545564557455845594560456145624563456445654566456745684569457045714572457345744575457645774578457945804581458245834584458545864587458845894590459145924593459445954596459745984599460046014602460346044605460646074608460946104611461246134614461546164617461846194620462146224623462446254626462746284629463046314632463346344635463646374638463946404641464246434644464546464647464846494650465146524653465446554656465746584659466046614662466346644665466646674668466946704671467246734674467546764677467846794680468146824683468446854686468746884689469046914692469346944695469646974698469947004701470247034704470547064707470847094710471147124713471447154716471747184719472047214722472347244725472647274728472947304731473247334734473547364737473847394740474147424743474447454746474747484749475047514752475347544755475647574758475947604761476247634764476547664767476847694770477147724773477447754776477747784779478047814782478347844785478647874788478947904791479247934794479547964797479847994800480148024803480448054806480748084809481048114812481348144815481648174818481948204821482248234824482548264827482848294830483148324833483448354836483748384839484048414842484348444845484648474848484948504851485248534854485548564857485848594860486148624863486448654866486748684869487048714872487348744875487648774878487948804881488248834884488548864887488848894890489148924893489448954896489748984899490049014902490349044905490649074908490949104911491249134914491549164917491849194920492149224923492449254926492749284929493049314932493349344935493649374938493949404941494249434944494549464947494849494950495149524953495449554956495749584959496049614962496349644965496649674968496949704971497249734974497549764977497849794980498149824983498449854986498749884989499049914992499349944995499649974998499950005001500250035004500550065007500850095010501150125013501450155016501750185019502050215022502350245025502650275028502950305031503250335034503550365037503850395040504150425043504450455046504750485049505050515052505350545055505650575058505950605061506250635064506550665067506850695070507150725073507450755076507750785079508050815082508350845085508650875088508950905091509250935094509550965097509850995100510151025103510451055106510751085109511051115112511351145115511651175118511951205121512251235124512551265127512851295130513151325133513451355136513751385139514051415142514351445145514651475148514951505151515251535154515551565157515851595160516151625163516451655166516751685169517051715172517351745175517651775178517951805181518251835184518551865187518851895190519151925193519451955196519751985199520052015202520352045205520652075208520952105211521252135214521552165217521852195220522152225223522452255226522752285229523052315232523352345235523652375238523952405241524252435244524552465247524852495250525152525253525452555256525752585259526052615262526352645265526652675268526952705271527252735274527552765277527852795280528152825283528452855286528752885289529052915292529352945295529652975298529953005301530253035304530553065307530853095310531153125313531453155316531753185319532053215322532353245325532653275328532953305331533253335334533553365337533853395340534153425343534453455346534753485349535053515352535353545355535653575358535953605361536253635364536553665367536853695370537153725373537453755376537753785379538053815382538353845385538653875388538953905391539253935394539553965397539853995400540154025403540454055406540754085409541054115412541354145415541654175418541954205421542254235424542554265427542854295430543154325433543454355436543754385439544054415442544354445445544654475448544954505451545254535454545554565457545854595460546154625463546454655466546754685469547054715472547354745475547654775478547954805481548254835484548554865487548854895490549154925493549454955496549754985499550055015502550355045505550655075508550955105511551255135514551555165517551855195520552155225523552455255526552755285529553055315532553355345535553655375538553955405541554255435544554555465547554855495550555155525553555455555556555755585559556055615562556355645565556655675568556955705571557255735574557555765577557855795580558155825583558455855586558755885589559055915592559355945595559655975598559956005601560256035604560556065607560856095610561156125613561456155616561756185619562056215622562356245625562656275628562956305631563256335634563556365637563856395640564156425643564456455646564756485649565056515652565356545655565656575658565956605661566256635664566556665667566856695670567156725673567456755676567756785679568056815682568356845685568656875688568956905691569256935694569556965697569856995700570157025703570457055706570757085709571057115712571357145715571657175718571957205721572257235724572557265727572857295730573157325733573457355736573757385739574057415742574357445745574657475748574957505751575257535754575557565757575857595760576157625763576457655766576757685769577057715772577357745775577657775778577957805781578257835784578557865787578857895790579157925793579457955796579757985799580058015802580358045805580658075808580958105811581258135814581558165817581858195820582158225823582458255826582758285829583058315832583358345835583658375838583958405841584258435844584558465847584858495850585158525853585458555856585758585859586058615862586358645865586658675868586958705871587258735874587558765877587858795880588158825883588458855886588758885889589058915892589358945895589658975898589959005901590259035904590559065907590859095910591159125913591459155916591759185919592059215922592359245925592659275928592959305931593259335934593559365937593859395940594159425943594459455946594759485949595059515952595359545955595659575958595959605961596259635964596559665967596859695970597159725973597459755976597759785979598059815982598359845985598659875988598959905991599259935994599559965997599859996000600160026003600460056006600760086009601060116012601360146015601660176018601960206021602260236024602560266027602860296030603160326033603460356036603760386039604060416042604360446045604660476048604960506051605260536054605560566057605860596060606160626063606460656066606760686069607060716072607360746075607660776078607960806081608260836084608560866087608860896090609160926093609460956096609760986099610061016102610361046105610661076108610961106111611261136114611561166117611861196120612161226123612461256126612761286129613061316132613361346135613661376138613961406141614261436144614561466147614861496150615161526153615461556156615761586159616061616162616361646165616661676168616961706171617261736174617561766177617861796180618161826183618461856186618761886189619061916192619361946195619661976198619962006201620262036204620562066207620862096210621162126213621462156216621762186219622062216222622362246225622662276228622962306231623262336234623562366237623862396240624162426243624462456246624762486249625062516252625362546255625662576258625962606261626262636264626562666267626862696270627162726273627462756276627762786279628062816282628362846285628662876288628962906291629262936294629562966297629862996300630163026303630463056306630763086309631063116312631363146315631663176318631963206321632263236324632563266327632863296330633163326333633463356336633763386339634063416342634363446345634663476348634963506351635263536354635563566357635863596360636163626363636463656366636763686369637063716372637363746375637663776378637963806381638263836384638563866387638863896390639163926393639463956396639763986399640064016402640364046405640664076408640964106411641264136414641564166417641864196420642164226423642464256426642764286429643064316432643364346435643664376438643964406441644264436444644564466447644864496450645164526453645464556456645764586459646064616462646364646465646664676468646964706471647264736474647564766477647864796480648164826483648464856486648764886489649064916492649364946495649664976498649965006501650265036504650565066507650865096510651165126513651465156516651765186519652065216522652365246525652665276528652965306531653265336534653565366537653865396540654165426543654465456546654765486549655065516552655365546555655665576558655965606561656265636564656565666567656865696570657165726573657465756576657765786579658065816582658365846585658665876588658965906591659265936594659565966597659865996600660166026603660466056606660766086609661066116612661366146615661666176618661966206621662266236624662566266627662866296630663166326633663466356636663766386639664066416642664366446645664666476648664966506651665266536654665566566657665866596660666166626663666466656666666766686669667066716672667366746675667666776678667966806681668266836684668566866687668866896690669166926693669466956696669766986699670067016702670367046705670667076708670967106711671267136714671567166717671867196720672167226723672467256726672767286729673067316732673367346735673667376738673967406741674267436744674567466747674867496750675167526753675467556756675767586759676067616762676367646765676667676768676967706771677267736774677567766777677867796780678167826783678467856786678767886789679067916792679367946795679667976798679968006801680268036804680568066807680868096810681168126813681468156816681768186819682068216822682368246825682668276828682968306831683268336834683568366837683868396840684168426843684468456846684768486849685068516852685368546855685668576858685968606861686268636864686568666867686868696870687168726873687468756876687768786879688068816882688368846885688668876888688968906891689268936894689568966897689868996900690169026903690469056906690769086909691069116912691369146915691669176918691969206921692269236924692569266927692869296930693169326933693469356936693769386939694069416942694369446945694669476948694969506951695269536954695569566957695869596960696169626963696469656966696769686969697069716972697369746975697669776978697969806981698269836984698569866987698869896990699169926993699469956996699769986999700070017002700370047005700670077008700970107011701270137014701570167017701870197020702170227023702470257026702770287029703070317032703370347035703670377038703970407041704270437044704570467047704870497050705170527053705470557056705770587059706070617062706370647065706670677068706970707071707270737074707570767077707870797080708170827083708470857086708770887089709070917092709370947095709670977098709971007101710271037104710571067107710871097110711171127113711471157116711771187119712071217122712371247125712671277128712971307131713271337134713571367137713871397140714171427143714471457146714771487149715071517152715371547155715671577158715971607161716271637164716571667167716871697170717171727173717471757176717771787179718071817182718371847185718671877188718971907191719271937194719571967197719871997200720172027203720472057206720772087209721072117212721372147215721672177218721972207221722272237224722572267227722872297230723172327233723472357236723772387239724072417242724372447245724672477248724972507251725272537254725572567257725872597260726172627263726472657266726772687269727072717272727372747275727672777278727972807281728272837284728572867287728872897290729172927293729472957296729772987299730073017302730373047305730673077308730973107311731273137314731573167317731873197320732173227323732473257326732773287329733073317332733373347335733673377338733973407341734273437344734573467347734873497350735173527353735473557356735773587359736073617362736373647365736673677368736973707371737273737374737573767377737873797380738173827383738473857386738773887389739073917392739373947395739673977398739974007401740274037404740574067407740874097410741174127413741474157416741774187419742074217422 |
- This is libc.info, produced by makeinfo version 5.2 from libc.texinfo.
- This file documents the GNU C Library.
- This is ‘The GNU C Library Reference Manual’, for version 2.25.
- Copyright © 1993–2017 Free Software Foundation, Inc.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.3 or
- any later version published by the Free Software Foundation; with the
- Invariant Sections being “Free Software Needs Free Documentation” and
- “GNU Lesser General Public License”, the Front-Cover texts being “A GNU
- Manual”, and with the Back-Cover Texts as in (a) below. A copy of the
- license is included in the section entitled "GNU Free Documentation
- License".
- (a) The FSF’s Back-Cover Text is: “You have the freedom to copy and
- modify this GNU manual. Buying copies from the FSF supports it in
- developing GNU and promoting software freedom.”
- INFO-DIR-SECTION Software libraries
- START-INFO-DIR-ENTRY
- * Libc: (libc). C library.
- END-INFO-DIR-ENTRY
- INFO-DIR-SECTION GNU C library functions and macros
- START-INFO-DIR-ENTRY
- * a64l: (libc)Encode Binary Data.
- * abort: (libc)Aborting a Program.
- * abs: (libc)Absolute Value.
- * accept: (libc)Accepting Connections.
- * access: (libc)Testing File Access.
- * acosf: (libc)Inverse Trig Functions.
- * acoshf: (libc)Hyperbolic Functions.
- * acosh: (libc)Hyperbolic Functions.
- * acoshl: (libc)Hyperbolic Functions.
- * acos: (libc)Inverse Trig Functions.
- * acosl: (libc)Inverse Trig Functions.
- * addmntent: (libc)mtab.
- * addseverity: (libc)Adding Severity Classes.
- * adjtime: (libc)High-Resolution Calendar.
- * adjtimex: (libc)High-Resolution Calendar.
- * aio_cancel64: (libc)Cancel AIO Operations.
- * aio_cancel: (libc)Cancel AIO Operations.
- * aio_error64: (libc)Status of AIO Operations.
- * aio_error: (libc)Status of AIO Operations.
- * aio_fsync64: (libc)Synchronizing AIO Operations.
- * aio_fsync: (libc)Synchronizing AIO Operations.
- * aio_init: (libc)Configuration of AIO.
- * aio_read64: (libc)Asynchronous Reads/Writes.
- * aio_read: (libc)Asynchronous Reads/Writes.
- * aio_return64: (libc)Status of AIO Operations.
- * aio_return: (libc)Status of AIO Operations.
- * aio_suspend64: (libc)Synchronizing AIO Operations.
- * aio_suspend: (libc)Synchronizing AIO Operations.
- * aio_write64: (libc)Asynchronous Reads/Writes.
- * aio_write: (libc)Asynchronous Reads/Writes.
- * alarm: (libc)Setting an Alarm.
- * aligned_alloc: (libc)Aligned Memory Blocks.
- * alloca: (libc)Variable Size Automatic.
- * alphasort64: (libc)Scanning Directory Content.
- * alphasort: (libc)Scanning Directory Content.
- * ALTWERASE: (libc)Local Modes.
- * ARG_MAX: (libc)General Limits.
- * argp_error: (libc)Argp Helper Functions.
- * ARGP_ERR_UNKNOWN: (libc)Argp Parser Functions.
- * argp_failure: (libc)Argp Helper Functions.
- * argp_help: (libc)Argp Help.
- * argp_parse: (libc)Argp.
- * argp_state_help: (libc)Argp Helper Functions.
- * argp_usage: (libc)Argp Helper Functions.
- * argz_add: (libc)Argz Functions.
- * argz_add_sep: (libc)Argz Functions.
- * argz_append: (libc)Argz Functions.
- * argz_count: (libc)Argz Functions.
- * argz_create: (libc)Argz Functions.
- * argz_create_sep: (libc)Argz Functions.
- * argz_delete: (libc)Argz Functions.
- * argz_extract: (libc)Argz Functions.
- * argz_insert: (libc)Argz Functions.
- * argz_next: (libc)Argz Functions.
- * argz_replace: (libc)Argz Functions.
- * argz_stringify: (libc)Argz Functions.
- * asctime: (libc)Formatting Calendar Time.
- * asctime_r: (libc)Formatting Calendar Time.
- * asinf: (libc)Inverse Trig Functions.
- * asinhf: (libc)Hyperbolic Functions.
- * asinh: (libc)Hyperbolic Functions.
- * asinhl: (libc)Hyperbolic Functions.
- * asin: (libc)Inverse Trig Functions.
- * asinl: (libc)Inverse Trig Functions.
- * asprintf: (libc)Dynamic Output.
- * assert: (libc)Consistency Checking.
- * assert_perror: (libc)Consistency Checking.
- * atan2f: (libc)Inverse Trig Functions.
- * atan2: (libc)Inverse Trig Functions.
- * atan2l: (libc)Inverse Trig Functions.
- * atanf: (libc)Inverse Trig Functions.
- * atanhf: (libc)Hyperbolic Functions.
- * atanh: (libc)Hyperbolic Functions.
- * atanhl: (libc)Hyperbolic Functions.
- * atan: (libc)Inverse Trig Functions.
- * atanl: (libc)Inverse Trig Functions.
- * atexit: (libc)Cleanups on Exit.
- * atof: (libc)Parsing of Floats.
- * atoi: (libc)Parsing of Integers.
- * atol: (libc)Parsing of Integers.
- * atoll: (libc)Parsing of Integers.
- * backtrace: (libc)Backtraces.
- * backtrace_symbols_fd: (libc)Backtraces.
- * backtrace_symbols: (libc)Backtraces.
- * basename: (libc)Finding Tokens in a String.
- * basename: (libc)Finding Tokens in a String.
- * BC_BASE_MAX: (libc)Utility Limits.
- * BC_DIM_MAX: (libc)Utility Limits.
- * bcmp: (libc)String/Array Comparison.
- * bcopy: (libc)Copying Strings and Arrays.
- * BC_SCALE_MAX: (libc)Utility Limits.
- * BC_STRING_MAX: (libc)Utility Limits.
- * bind: (libc)Setting Address.
- * bind_textdomain_codeset: (libc)Charset conversion in gettext.
- * bindtextdomain: (libc)Locating gettext catalog.
- * BRKINT: (libc)Input Modes.
- * brk: (libc)Resizing the Data Segment.
- * bsearch: (libc)Array Search Function.
- * btowc: (libc)Converting a Character.
- * BUFSIZ: (libc)Controlling Buffering.
- * bzero: (libc)Copying Strings and Arrays.
- * cabsf: (libc)Absolute Value.
- * cabs: (libc)Absolute Value.
- * cabsl: (libc)Absolute Value.
- * cacosf: (libc)Inverse Trig Functions.
- * cacoshf: (libc)Hyperbolic Functions.
- * cacosh: (libc)Hyperbolic Functions.
- * cacoshl: (libc)Hyperbolic Functions.
- * cacos: (libc)Inverse Trig Functions.
- * cacosl: (libc)Inverse Trig Functions.
- * calloc: (libc)Allocating Cleared Space.
- * canonicalize_file_name: (libc)Symbolic Links.
- * canonicalizef: (libc)FP Bit Twiddling.
- * canonicalize: (libc)FP Bit Twiddling.
- * canonicalizel: (libc)FP Bit Twiddling.
- * cargf: (libc)Operations on Complex.
- * carg: (libc)Operations on Complex.
- * cargl: (libc)Operations on Complex.
- * casinf: (libc)Inverse Trig Functions.
- * casinhf: (libc)Hyperbolic Functions.
- * casinh: (libc)Hyperbolic Functions.
- * casinhl: (libc)Hyperbolic Functions.
- * casin: (libc)Inverse Trig Functions.
- * casinl: (libc)Inverse Trig Functions.
- * catanf: (libc)Inverse Trig Functions.
- * catanhf: (libc)Hyperbolic Functions.
- * catanh: (libc)Hyperbolic Functions.
- * catanhl: (libc)Hyperbolic Functions.
- * catan: (libc)Inverse Trig Functions.
- * catanl: (libc)Inverse Trig Functions.
- * catclose: (libc)The catgets Functions.
- * catgets: (libc)The catgets Functions.
- * catopen: (libc)The catgets Functions.
- * cbc_crypt: (libc)DES Encryption.
- * cbrtf: (libc)Exponents and Logarithms.
- * cbrt: (libc)Exponents and Logarithms.
- * cbrtl: (libc)Exponents and Logarithms.
- * ccosf: (libc)Trig Functions.
- * ccoshf: (libc)Hyperbolic Functions.
- * ccosh: (libc)Hyperbolic Functions.
- * ccoshl: (libc)Hyperbolic Functions.
- * ccos: (libc)Trig Functions.
- * ccosl: (libc)Trig Functions.
- * CCTS_OFLOW: (libc)Control Modes.
- * ceilf: (libc)Rounding Functions.
- * ceil: (libc)Rounding Functions.
- * ceill: (libc)Rounding Functions.
- * cexpf: (libc)Exponents and Logarithms.
- * cexp: (libc)Exponents and Logarithms.
- * cexpl: (libc)Exponents and Logarithms.
- * cfgetispeed: (libc)Line Speed.
- * cfgetospeed: (libc)Line Speed.
- * cfmakeraw: (libc)Noncanonical Input.
- * cfree: (libc)Freeing after Malloc.
- * cfsetispeed: (libc)Line Speed.
- * cfsetospeed: (libc)Line Speed.
- * cfsetspeed: (libc)Line Speed.
- * chdir: (libc)Working Directory.
- * CHILD_MAX: (libc)General Limits.
- * chmod: (libc)Setting Permissions.
- * chown: (libc)File Owner.
- * CIGNORE: (libc)Control Modes.
- * cimagf: (libc)Operations on Complex.
- * cimag: (libc)Operations on Complex.
- * cimagl: (libc)Operations on Complex.
- * clearenv: (libc)Environment Access.
- * clearerr: (libc)Error Recovery.
- * clearerr_unlocked: (libc)Error Recovery.
- * CLK_TCK: (libc)Processor Time.
- * CLOCAL: (libc)Control Modes.
- * clock: (libc)CPU Time.
- * CLOCKS_PER_SEC: (libc)CPU Time.
- * clog10f: (libc)Exponents and Logarithms.
- * clog10: (libc)Exponents and Logarithms.
- * clog10l: (libc)Exponents and Logarithms.
- * clogf: (libc)Exponents and Logarithms.
- * clog: (libc)Exponents and Logarithms.
- * clogl: (libc)Exponents and Logarithms.
- * closedir: (libc)Reading/Closing Directory.
- * close: (libc)Opening and Closing Files.
- * closelog: (libc)closelog.
- * COLL_WEIGHTS_MAX: (libc)Utility Limits.
- * _Complex_I: (libc)Complex Numbers.
- * confstr: (libc)String Parameters.
- * conjf: (libc)Operations on Complex.
- * conj: (libc)Operations on Complex.
- * conjl: (libc)Operations on Complex.
- * connect: (libc)Connecting.
- * copysignf: (libc)FP Bit Twiddling.
- * copysign: (libc)FP Bit Twiddling.
- * copysignl: (libc)FP Bit Twiddling.
- * cosf: (libc)Trig Functions.
- * coshf: (libc)Hyperbolic Functions.
- * cosh: (libc)Hyperbolic Functions.
- * coshl: (libc)Hyperbolic Functions.
- * cos: (libc)Trig Functions.
- * cosl: (libc)Trig Functions.
- * cpowf: (libc)Exponents and Logarithms.
- * cpow: (libc)Exponents and Logarithms.
- * cpowl: (libc)Exponents and Logarithms.
- * cprojf: (libc)Operations on Complex.
- * cproj: (libc)Operations on Complex.
- * cprojl: (libc)Operations on Complex.
- * CPU_CLR: (libc)CPU Affinity.
- * CPU_ISSET: (libc)CPU Affinity.
- * CPU_SET: (libc)CPU Affinity.
- * CPU_SETSIZE: (libc)CPU Affinity.
- * CPU_ZERO: (libc)CPU Affinity.
- * CREAD: (libc)Control Modes.
- * crealf: (libc)Operations on Complex.
- * creal: (libc)Operations on Complex.
- * creall: (libc)Operations on Complex.
- * creat64: (libc)Opening and Closing Files.
- * creat: (libc)Opening and Closing Files.
- * CRTS_IFLOW: (libc)Control Modes.
- * crypt: (libc)crypt.
- * crypt_r: (libc)crypt.
- * CS5: (libc)Control Modes.
- * CS6: (libc)Control Modes.
- * CS7: (libc)Control Modes.
- * CS8: (libc)Control Modes.
- * csinf: (libc)Trig Functions.
- * csinhf: (libc)Hyperbolic Functions.
- * csinh: (libc)Hyperbolic Functions.
- * csinhl: (libc)Hyperbolic Functions.
- * csin: (libc)Trig Functions.
- * csinl: (libc)Trig Functions.
- * CSIZE: (libc)Control Modes.
- * csqrtf: (libc)Exponents and Logarithms.
- * csqrt: (libc)Exponents and Logarithms.
- * csqrtl: (libc)Exponents and Logarithms.
- * CSTOPB: (libc)Control Modes.
- * ctanf: (libc)Trig Functions.
- * ctanhf: (libc)Hyperbolic Functions.
- * ctanh: (libc)Hyperbolic Functions.
- * ctanhl: (libc)Hyperbolic Functions.
- * ctan: (libc)Trig Functions.
- * ctanl: (libc)Trig Functions.
- * ctermid: (libc)Identifying the Terminal.
- * ctime: (libc)Formatting Calendar Time.
- * ctime_r: (libc)Formatting Calendar Time.
- * cuserid: (libc)Who Logged In.
- * dcgettext: (libc)Translation with gettext.
- * dcngettext: (libc)Advanced gettext functions.
- * DES_FAILED: (libc)DES Encryption.
- * des_setparity: (libc)DES Encryption.
- * dgettext: (libc)Translation with gettext.
- * difftime: (libc)Elapsed Time.
- * dirfd: (libc)Opening a Directory.
- * dirname: (libc)Finding Tokens in a String.
- * div: (libc)Integer Division.
- * dngettext: (libc)Advanced gettext functions.
- * drand48: (libc)SVID Random.
- * drand48_r: (libc)SVID Random.
- * dremf: (libc)Remainder Functions.
- * drem: (libc)Remainder Functions.
- * dreml: (libc)Remainder Functions.
- * DTTOIF: (libc)Directory Entries.
- * dup2: (libc)Duplicating Descriptors.
- * dup: (libc)Duplicating Descriptors.
- * E2BIG: (libc)Error Codes.
- * EACCES: (libc)Error Codes.
- * EADDRINUSE: (libc)Error Codes.
- * EADDRNOTAVAIL: (libc)Error Codes.
- * EADV: (libc)Error Codes.
- * EAFNOSUPPORT: (libc)Error Codes.
- * EAGAIN: (libc)Error Codes.
- * EALREADY: (libc)Error Codes.
- * EAUTH: (libc)Error Codes.
- * EBACKGROUND: (libc)Error Codes.
- * EBADE: (libc)Error Codes.
- * EBADFD: (libc)Error Codes.
- * EBADF: (libc)Error Codes.
- * EBADMSG: (libc)Error Codes.
- * EBADR: (libc)Error Codes.
- * EBADRPC: (libc)Error Codes.
- * EBADRQC: (libc)Error Codes.
- * EBADSLT: (libc)Error Codes.
- * EBFONT: (libc)Error Codes.
- * EBUSY: (libc)Error Codes.
- * ECANCELED: (libc)Error Codes.
- * ecb_crypt: (libc)DES Encryption.
- * ECHILD: (libc)Error Codes.
- * ECHOCTL: (libc)Local Modes.
- * ECHOE: (libc)Local Modes.
- * ECHOKE: (libc)Local Modes.
- * ECHOK: (libc)Local Modes.
- * ECHO: (libc)Local Modes.
- * ECHONL: (libc)Local Modes.
- * ECHOPRT: (libc)Local Modes.
- * ECHRNG: (libc)Error Codes.
- * ECOMM: (libc)Error Codes.
- * ECONNABORTED: (libc)Error Codes.
- * ECONNREFUSED: (libc)Error Codes.
- * ECONNRESET: (libc)Error Codes.
- * ecvt: (libc)System V Number Conversion.
- * ecvt_r: (libc)System V Number Conversion.
- * EDEADLK: (libc)Error Codes.
- * EDEADLOCK: (libc)Error Codes.
- * EDESTADDRREQ: (libc)Error Codes.
- * EDIED: (libc)Error Codes.
- * ED: (libc)Error Codes.
- * EDOM: (libc)Error Codes.
- * EDOTDOT: (libc)Error Codes.
- * EDQUOT: (libc)Error Codes.
- * EEXIST: (libc)Error Codes.
- * EFAULT: (libc)Error Codes.
- * EFBIG: (libc)Error Codes.
- * EFTYPE: (libc)Error Codes.
- * EGRATUITOUS: (libc)Error Codes.
- * EGREGIOUS: (libc)Error Codes.
- * EHOSTDOWN: (libc)Error Codes.
- * EHOSTUNREACH: (libc)Error Codes.
- * EHWPOISON: (libc)Error Codes.
- * EIDRM: (libc)Error Codes.
- * EIEIO: (libc)Error Codes.
- * EILSEQ: (libc)Error Codes.
- * EINPROGRESS: (libc)Error Codes.
- * EINTR: (libc)Error Codes.
- * EINVAL: (libc)Error Codes.
- * EIO: (libc)Error Codes.
- * EISCONN: (libc)Error Codes.
- * EISDIR: (libc)Error Codes.
- * EISNAM: (libc)Error Codes.
- * EKEYEXPIRED: (libc)Error Codes.
- * EKEYREJECTED: (libc)Error Codes.
- * EKEYREVOKED: (libc)Error Codes.
- * EL2HLT: (libc)Error Codes.
- * EL2NSYNC: (libc)Error Codes.
- * EL3HLT: (libc)Error Codes.
- * EL3RST: (libc)Error Codes.
- * ELIBACC: (libc)Error Codes.
- * ELIBBAD: (libc)Error Codes.
- * ELIBEXEC: (libc)Error Codes.
- * ELIBMAX: (libc)Error Codes.
- * ELIBSCN: (libc)Error Codes.
- * ELNRNG: (libc)Error Codes.
- * ELOOP: (libc)Error Codes.
- * EMEDIUMTYPE: (libc)Error Codes.
- * EMFILE: (libc)Error Codes.
- * EMLINK: (libc)Error Codes.
- * EMSGSIZE: (libc)Error Codes.
- * EMULTIHOP: (libc)Error Codes.
- * ENAMETOOLONG: (libc)Error Codes.
- * ENAVAIL: (libc)Error Codes.
- * encrypt: (libc)DES Encryption.
- * encrypt_r: (libc)DES Encryption.
- * endfsent: (libc)fstab.
- * endgrent: (libc)Scanning All Groups.
- * endhostent: (libc)Host Names.
- * endmntent: (libc)mtab.
- * endnetent: (libc)Networks Database.
- * endnetgrent: (libc)Lookup Netgroup.
- * endprotoent: (libc)Protocols Database.
- * endpwent: (libc)Scanning All Users.
- * endservent: (libc)Services Database.
- * endutent: (libc)Manipulating the Database.
- * endutxent: (libc)XPG Functions.
- * ENEEDAUTH: (libc)Error Codes.
- * ENETDOWN: (libc)Error Codes.
- * ENETRESET: (libc)Error Codes.
- * ENETUNREACH: (libc)Error Codes.
- * ENFILE: (libc)Error Codes.
- * ENOANO: (libc)Error Codes.
- * ENOBUFS: (libc)Error Codes.
- * ENOCSI: (libc)Error Codes.
- * ENODATA: (libc)Error Codes.
- * ENODEV: (libc)Error Codes.
- * ENOENT: (libc)Error Codes.
- * ENOEXEC: (libc)Error Codes.
- * ENOKEY: (libc)Error Codes.
- * ENOLCK: (libc)Error Codes.
- * ENOLINK: (libc)Error Codes.
- * ENOMEDIUM: (libc)Error Codes.
- * ENOMEM: (libc)Error Codes.
- * ENOMSG: (libc)Error Codes.
- * ENONET: (libc)Error Codes.
- * ENOPKG: (libc)Error Codes.
- * ENOPROTOOPT: (libc)Error Codes.
- * ENOSPC: (libc)Error Codes.
- * ENOSR: (libc)Error Codes.
- * ENOSTR: (libc)Error Codes.
- * ENOSYS: (libc)Error Codes.
- * ENOTBLK: (libc)Error Codes.
- * ENOTCONN: (libc)Error Codes.
- * ENOTDIR: (libc)Error Codes.
- * ENOTEMPTY: (libc)Error Codes.
- * ENOTNAM: (libc)Error Codes.
- * ENOTRECOVERABLE: (libc)Error Codes.
- * ENOTSOCK: (libc)Error Codes.
- * ENOTSUP: (libc)Error Codes.
- * ENOTTY: (libc)Error Codes.
- * ENOTUNIQ: (libc)Error Codes.
- * envz_add: (libc)Envz Functions.
- * envz_entry: (libc)Envz Functions.
- * envz_get: (libc)Envz Functions.
- * envz_merge: (libc)Envz Functions.
- * envz_remove: (libc)Envz Functions.
- * envz_strip: (libc)Envz Functions.
- * ENXIO: (libc)Error Codes.
- * EOF: (libc)EOF and Errors.
- * EOPNOTSUPP: (libc)Error Codes.
- * EOVERFLOW: (libc)Error Codes.
- * EOWNERDEAD: (libc)Error Codes.
- * EPERM: (libc)Error Codes.
- * EPFNOSUPPORT: (libc)Error Codes.
- * EPIPE: (libc)Error Codes.
- * EPROCLIM: (libc)Error Codes.
- * EPROCUNAVAIL: (libc)Error Codes.
- * EPROGMISMATCH: (libc)Error Codes.
- * EPROGUNAVAIL: (libc)Error Codes.
- * EPROTO: (libc)Error Codes.
- * EPROTONOSUPPORT: (libc)Error Codes.
- * EPROTOTYPE: (libc)Error Codes.
- * EQUIV_CLASS_MAX: (libc)Utility Limits.
- * erand48: (libc)SVID Random.
- * erand48_r: (libc)SVID Random.
- * ERANGE: (libc)Error Codes.
- * EREMCHG: (libc)Error Codes.
- * EREMOTEIO: (libc)Error Codes.
- * EREMOTE: (libc)Error Codes.
- * ERESTART: (libc)Error Codes.
- * erfcf: (libc)Special Functions.
- * erfc: (libc)Special Functions.
- * erfcl: (libc)Special Functions.
- * erff: (libc)Special Functions.
- * ERFKILL: (libc)Error Codes.
- * erf: (libc)Special Functions.
- * erfl: (libc)Special Functions.
- * EROFS: (libc)Error Codes.
- * ERPCMISMATCH: (libc)Error Codes.
- * err: (libc)Error Messages.
- * errno: (libc)Checking for Errors.
- * error_at_line: (libc)Error Messages.
- * error: (libc)Error Messages.
- * errx: (libc)Error Messages.
- * ESHUTDOWN: (libc)Error Codes.
- * ESOCKTNOSUPPORT: (libc)Error Codes.
- * ESPIPE: (libc)Error Codes.
- * ESRCH: (libc)Error Codes.
- * ESRMNT: (libc)Error Codes.
- * ESTALE: (libc)Error Codes.
- * ESTRPIPE: (libc)Error Codes.
- * ETIMEDOUT: (libc)Error Codes.
- * ETIME: (libc)Error Codes.
- * ETOOMANYREFS: (libc)Error Codes.
- * ETXTBSY: (libc)Error Codes.
- * EUCLEAN: (libc)Error Codes.
- * EUNATCH: (libc)Error Codes.
- * EUSERS: (libc)Error Codes.
- * EWOULDBLOCK: (libc)Error Codes.
- * EXDEV: (libc)Error Codes.
- * execle: (libc)Executing a File.
- * execl: (libc)Executing a File.
- * execlp: (libc)Executing a File.
- * execve: (libc)Executing a File.
- * execv: (libc)Executing a File.
- * execvp: (libc)Executing a File.
- * EXFULL: (libc)Error Codes.
- * EXIT_FAILURE: (libc)Exit Status.
- * exit: (libc)Normal Termination.
- * _exit: (libc)Termination Internals.
- * _Exit: (libc)Termination Internals.
- * EXIT_SUCCESS: (libc)Exit Status.
- * exp10f: (libc)Exponents and Logarithms.
- * exp10: (libc)Exponents and Logarithms.
- * exp10l: (libc)Exponents and Logarithms.
- * exp2f: (libc)Exponents and Logarithms.
- * exp2: (libc)Exponents and Logarithms.
- * exp2l: (libc)Exponents and Logarithms.
- * expf: (libc)Exponents and Logarithms.
- * exp: (libc)Exponents and Logarithms.
- * explicit_bzero: (libc)Erasing Sensitive Data.
- * expl: (libc)Exponents and Logarithms.
- * expm1f: (libc)Exponents and Logarithms.
- * expm1: (libc)Exponents and Logarithms.
- * expm1l: (libc)Exponents and Logarithms.
- * EXPR_NEST_MAX: (libc)Utility Limits.
- * fabsf: (libc)Absolute Value.
- * fabs: (libc)Absolute Value.
- * fabsl: (libc)Absolute Value.
- * __fbufsize: (libc)Controlling Buffering.
- * fchdir: (libc)Working Directory.
- * fchmod: (libc)Setting Permissions.
- * fchown: (libc)File Owner.
- * fcloseall: (libc)Closing Streams.
- * fclose: (libc)Closing Streams.
- * fcntl: (libc)Control Operations.
- * fcvt: (libc)System V Number Conversion.
- * fcvt_r: (libc)System V Number Conversion.
- * fdatasync: (libc)Synchronizing I/O.
- * FD_CLOEXEC: (libc)Descriptor Flags.
- * FD_CLR: (libc)Waiting for I/O.
- * fdimf: (libc)Misc FP Arithmetic.
- * fdim: (libc)Misc FP Arithmetic.
- * fdiml: (libc)Misc FP Arithmetic.
- * FD_ISSET: (libc)Waiting for I/O.
- * fdopendir: (libc)Opening a Directory.
- * fdopen: (libc)Descriptors and Streams.
- * FD_SET: (libc)Waiting for I/O.
- * FD_SETSIZE: (libc)Waiting for I/O.
- * F_DUPFD: (libc)Duplicating Descriptors.
- * FD_ZERO: (libc)Waiting for I/O.
- * feclearexcept: (libc)Status bit operations.
- * fedisableexcept: (libc)Control Functions.
- * feenableexcept: (libc)Control Functions.
- * fegetenv: (libc)Control Functions.
- * fegetexceptflag: (libc)Status bit operations.
- * fegetexcept: (libc)Control Functions.
- * fegetmode: (libc)Control Functions.
- * fegetround: (libc)Rounding.
- * feholdexcept: (libc)Control Functions.
- * feof: (libc)EOF and Errors.
- * feof_unlocked: (libc)EOF and Errors.
- * feraiseexcept: (libc)Status bit operations.
- * ferror: (libc)EOF and Errors.
- * ferror_unlocked: (libc)EOF and Errors.
- * fesetenv: (libc)Control Functions.
- * fesetexceptflag: (libc)Status bit operations.
- * fesetexcept: (libc)Status bit operations.
- * fesetmode: (libc)Control Functions.
- * fesetround: (libc)Rounding.
- * FE_SNANS_ALWAYS_SIGNAL: (libc)Infinity and NaN.
- * fetestexceptflag: (libc)Status bit operations.
- * fetestexcept: (libc)Status bit operations.
- * feupdateenv: (libc)Control Functions.
- * fflush: (libc)Flushing Buffers.
- * fflush_unlocked: (libc)Flushing Buffers.
- * fgetc: (libc)Character Input.
- * fgetc_unlocked: (libc)Character Input.
- * F_GETFD: (libc)Descriptor Flags.
- * F_GETFL: (libc)Getting File Status Flags.
- * fgetgrent: (libc)Scanning All Groups.
- * fgetgrent_r: (libc)Scanning All Groups.
- * F_GETLK: (libc)File Locks.
- * F_GETOWN: (libc)Interrupt Input.
- * fgetpos64: (libc)Portable Positioning.
- * fgetpos: (libc)Portable Positioning.
- * fgetpwent: (libc)Scanning All Users.
- * fgetpwent_r: (libc)Scanning All Users.
- * fgets: (libc)Line Input.
- * fgets_unlocked: (libc)Line Input.
- * fgetwc: (libc)Character Input.
- * fgetwc_unlocked: (libc)Character Input.
- * fgetws: (libc)Line Input.
- * fgetws_unlocked: (libc)Line Input.
- * FILENAME_MAX: (libc)Limits for Files.
- * fileno: (libc)Descriptors and Streams.
- * fileno_unlocked: (libc)Descriptors and Streams.
- * finitef: (libc)Floating Point Classes.
- * finite: (libc)Floating Point Classes.
- * finitel: (libc)Floating Point Classes.
- * __flbf: (libc)Controlling Buffering.
- * flockfile: (libc)Streams and Threads.
- * floorf: (libc)Rounding Functions.
- * floor: (libc)Rounding Functions.
- * floorl: (libc)Rounding Functions.
- * _flushlbf: (libc)Flushing Buffers.
- * FLUSHO: (libc)Local Modes.
- * fmaf: (libc)Misc FP Arithmetic.
- * fma: (libc)Misc FP Arithmetic.
- * fmal: (libc)Misc FP Arithmetic.
- * fmaxf: (libc)Misc FP Arithmetic.
- * fmax: (libc)Misc FP Arithmetic.
- * fmaxl: (libc)Misc FP Arithmetic.
- * fmaxmagf: (libc)Misc FP Arithmetic.
- * fmaxmag: (libc)Misc FP Arithmetic.
- * fmaxmagl: (libc)Misc FP Arithmetic.
- * fmemopen: (libc)String Streams.
- * fminf: (libc)Misc FP Arithmetic.
- * fmin: (libc)Misc FP Arithmetic.
- * fminl: (libc)Misc FP Arithmetic.
- * fminmagf: (libc)Misc FP Arithmetic.
- * fminmag: (libc)Misc FP Arithmetic.
- * fminmagl: (libc)Misc FP Arithmetic.
- * fmodf: (libc)Remainder Functions.
- * fmod: (libc)Remainder Functions.
- * fmodl: (libc)Remainder Functions.
- * fmtmsg: (libc)Printing Formatted Messages.
- * fnmatch: (libc)Wildcard Matching.
- * F_OFD_GETLK: (libc)Open File Description Locks.
- * F_OFD_SETLK: (libc)Open File Description Locks.
- * F_OFD_SETLKW: (libc)Open File Description Locks.
- * F_OK: (libc)Testing File Access.
- * fopen64: (libc)Opening Streams.
- * fopencookie: (libc)Streams and Cookies.
- * fopen: (libc)Opening Streams.
- * FOPEN_MAX: (libc)Opening Streams.
- * fork: (libc)Creating a Process.
- * forkpty: (libc)Pseudo-Terminal Pairs.
- * fpathconf: (libc)Pathconf.
- * fpclassify: (libc)Floating Point Classes.
- * __fpending: (libc)Controlling Buffering.
- * FP_ILOGB0: (libc)Exponents and Logarithms.
- * FP_ILOGBNAN: (libc)Exponents and Logarithms.
- * FP_LLOGB0: (libc)Exponents and Logarithms.
- * FP_LLOGBNAN: (libc)Exponents and Logarithms.
- * fprintf: (libc)Formatted Output Functions.
- * __fpurge: (libc)Flushing Buffers.
- * fputc: (libc)Simple Output.
- * fputc_unlocked: (libc)Simple Output.
- * fputs: (libc)Simple Output.
- * fputs_unlocked: (libc)Simple Output.
- * fputwc: (libc)Simple Output.
- * fputwc_unlocked: (libc)Simple Output.
- * fputws: (libc)Simple Output.
- * fputws_unlocked: (libc)Simple Output.
- * __freadable: (libc)Opening Streams.
- * __freading: (libc)Opening Streams.
- * fread: (libc)Block Input/Output.
- * fread_unlocked: (libc)Block Input/Output.
- * free: (libc)Freeing after Malloc.
- * freopen64: (libc)Opening Streams.
- * freopen: (libc)Opening Streams.
- * frexpf: (libc)Normalization Functions.
- * frexp: (libc)Normalization Functions.
- * frexpl: (libc)Normalization Functions.
- * fromfpf: (libc)Rounding Functions.
- * fromfp: (libc)Rounding Functions.
- * fromfpl: (libc)Rounding Functions.
- * fromfpxf: (libc)Rounding Functions.
- * fromfpx: (libc)Rounding Functions.
- * fromfpxl: (libc)Rounding Functions.
- * fscanf: (libc)Formatted Input Functions.
- * fseek: (libc)File Positioning.
- * fseeko64: (libc)File Positioning.
- * fseeko: (libc)File Positioning.
- * F_SETFD: (libc)Descriptor Flags.
- * F_SETFL: (libc)Getting File Status Flags.
- * F_SETLK: (libc)File Locks.
- * F_SETLKW: (libc)File Locks.
- * __fsetlocking: (libc)Streams and Threads.
- * F_SETOWN: (libc)Interrupt Input.
- * fsetpos64: (libc)Portable Positioning.
- * fsetpos: (libc)Portable Positioning.
- * fstat64: (libc)Reading Attributes.
- * fstat: (libc)Reading Attributes.
- * fsync: (libc)Synchronizing I/O.
- * ftell: (libc)File Positioning.
- * ftello64: (libc)File Positioning.
- * ftello: (libc)File Positioning.
- * ftruncate64: (libc)File Size.
- * ftruncate: (libc)File Size.
- * ftrylockfile: (libc)Streams and Threads.
- * ftw64: (libc)Working with Directory Trees.
- * ftw: (libc)Working with Directory Trees.
- * funlockfile: (libc)Streams and Threads.
- * futimes: (libc)File Times.
- * fwide: (libc)Streams and I18N.
- * fwprintf: (libc)Formatted Output Functions.
- * __fwritable: (libc)Opening Streams.
- * fwrite: (libc)Block Input/Output.
- * fwrite_unlocked: (libc)Block Input/Output.
- * __fwriting: (libc)Opening Streams.
- * fwscanf: (libc)Formatted Input Functions.
- * gammaf: (libc)Special Functions.
- * gamma: (libc)Special Functions.
- * gammal: (libc)Special Functions.
- * __gconv_end_fct: (libc)glibc iconv Implementation.
- * __gconv_fct: (libc)glibc iconv Implementation.
- * __gconv_init_fct: (libc)glibc iconv Implementation.
- * gcvt: (libc)System V Number Conversion.
- * getauxval: (libc)Auxiliary Vector.
- * get_avphys_pages: (libc)Query Memory Parameters.
- * getchar: (libc)Character Input.
- * getchar_unlocked: (libc)Character Input.
- * getc: (libc)Character Input.
- * getcontext: (libc)System V contexts.
- * getc_unlocked: (libc)Character Input.
- * get_current_dir_name: (libc)Working Directory.
- * getcwd: (libc)Working Directory.
- * getdate: (libc)General Time String Parsing.
- * getdate_r: (libc)General Time String Parsing.
- * getdelim: (libc)Line Input.
- * getdomainnname: (libc)Host Identification.
- * getegid: (libc)Reading Persona.
- * getentropy: (libc)Unpredictable Bytes.
- * getenv: (libc)Environment Access.
- * geteuid: (libc)Reading Persona.
- * getfsent: (libc)fstab.
- * getfsfile: (libc)fstab.
- * getfsspec: (libc)fstab.
- * getgid: (libc)Reading Persona.
- * getgrent: (libc)Scanning All Groups.
- * getgrent_r: (libc)Scanning All Groups.
- * getgrgid: (libc)Lookup Group.
- * getgrgid_r: (libc)Lookup Group.
- * getgrnam: (libc)Lookup Group.
- * getgrnam_r: (libc)Lookup Group.
- * getgrouplist: (libc)Setting Groups.
- * getgroups: (libc)Reading Persona.
- * gethostbyaddr: (libc)Host Names.
- * gethostbyaddr_r: (libc)Host Names.
- * gethostbyname2: (libc)Host Names.
- * gethostbyname2_r: (libc)Host Names.
- * gethostbyname: (libc)Host Names.
- * gethostbyname_r: (libc)Host Names.
- * gethostent: (libc)Host Names.
- * gethostid: (libc)Host Identification.
- * gethostname: (libc)Host Identification.
- * getitimer: (libc)Setting an Alarm.
- * getline: (libc)Line Input.
- * getloadavg: (libc)Processor Resources.
- * getlogin: (libc)Who Logged In.
- * getmntent: (libc)mtab.
- * getmntent_r: (libc)mtab.
- * getnetbyaddr: (libc)Networks Database.
- * getnetbyname: (libc)Networks Database.
- * getnetent: (libc)Networks Database.
- * getnetgrent: (libc)Lookup Netgroup.
- * getnetgrent_r: (libc)Lookup Netgroup.
- * get_nprocs_conf: (libc)Processor Resources.
- * get_nprocs: (libc)Processor Resources.
- * getopt: (libc)Using Getopt.
- * getopt_long: (libc)Getopt Long Options.
- * getopt_long_only: (libc)Getopt Long Options.
- * getpagesize: (libc)Query Memory Parameters.
- * getpass: (libc)getpass.
- * getpayloadf: (libc)FP Bit Twiddling.
- * getpayload: (libc)FP Bit Twiddling.
- * getpayloadl: (libc)FP Bit Twiddling.
- * getpeername: (libc)Who is Connected.
- * getpgid: (libc)Process Group Functions.
- * getpgrp: (libc)Process Group Functions.
- * get_phys_pages: (libc)Query Memory Parameters.
- * getpid: (libc)Process Identification.
- * getppid: (libc)Process Identification.
- * getpriority: (libc)Traditional Scheduling Functions.
- * getprotobyname: (libc)Protocols Database.
- * getprotobynumber: (libc)Protocols Database.
- * getprotoent: (libc)Protocols Database.
- * getpt: (libc)Allocation.
- * getpwent: (libc)Scanning All Users.
- * getpwent_r: (libc)Scanning All Users.
- * getpwnam: (libc)Lookup User.
- * getpwnam_r: (libc)Lookup User.
- * getpwuid: (libc)Lookup User.
- * getpwuid_r: (libc)Lookup User.
- * getrandom: (libc)Unpredictable Bytes.
- * getrlimit64: (libc)Limits on Resources.
- * getrlimit: (libc)Limits on Resources.
- * getrusage: (libc)Resource Usage.
- * getservbyname: (libc)Services Database.
- * getservbyport: (libc)Services Database.
- * getservent: (libc)Services Database.
- * getsid: (libc)Process Group Functions.
- * gets: (libc)Line Input.
- * getsockname: (libc)Reading Address.
- * getsockopt: (libc)Socket Option Functions.
- * getsubopt: (libc)Suboptions.
- * gettext: (libc)Translation with gettext.
- * gettimeofday: (libc)High-Resolution Calendar.
- * getuid: (libc)Reading Persona.
- * getumask: (libc)Setting Permissions.
- * getutent: (libc)Manipulating the Database.
- * getutent_r: (libc)Manipulating the Database.
- * getutid: (libc)Manipulating the Database.
- * getutid_r: (libc)Manipulating the Database.
- * getutline: (libc)Manipulating the Database.
- * getutline_r: (libc)Manipulating the Database.
- * getutmp: (libc)XPG Functions.
- * getutmpx: (libc)XPG Functions.
- * getutxent: (libc)XPG Functions.
- * getutxid: (libc)XPG Functions.
- * getutxline: (libc)XPG Functions.
- * getwchar: (libc)Character Input.
- * getwchar_unlocked: (libc)Character Input.
- * getwc: (libc)Character Input.
- * getwc_unlocked: (libc)Character Input.
- * getwd: (libc)Working Directory.
- * getw: (libc)Character Input.
- * glob64: (libc)Calling Glob.
- * globfree64: (libc)More Flags for Globbing.
- * globfree: (libc)More Flags for Globbing.
- * glob: (libc)Calling Glob.
- * gmtime: (libc)Broken-down Time.
- * gmtime_r: (libc)Broken-down Time.
- * grantpt: (libc)Allocation.
- * gsignal: (libc)Signaling Yourself.
- * gtty: (libc)BSD Terminal Modes.
- * hasmntopt: (libc)mtab.
- * hcreate: (libc)Hash Search Function.
- * hcreate_r: (libc)Hash Search Function.
- * hdestroy: (libc)Hash Search Function.
- * hdestroy_r: (libc)Hash Search Function.
- * hsearch: (libc)Hash Search Function.
- * hsearch_r: (libc)Hash Search Function.
- * htonl: (libc)Byte Order.
- * htons: (libc)Byte Order.
- * HUGE_VALF: (libc)Math Error Reporting.
- * HUGE_VAL: (libc)Math Error Reporting.
- * HUGE_VALL: (libc)Math Error Reporting.
- * HUPCL: (libc)Control Modes.
- * hypotf: (libc)Exponents and Logarithms.
- * hypot: (libc)Exponents and Logarithms.
- * hypotl: (libc)Exponents and Logarithms.
- * ICANON: (libc)Local Modes.
- * iconv_close: (libc)Generic Conversion Interface.
- * iconv: (libc)Generic Conversion Interface.
- * iconv_open: (libc)Generic Conversion Interface.
- * ICRNL: (libc)Input Modes.
- * IEXTEN: (libc)Local Modes.
- * if_freenameindex: (libc)Interface Naming.
- * if_indextoname: (libc)Interface Naming.
- * if_nameindex: (libc)Interface Naming.
- * if_nametoindex: (libc)Interface Naming.
- * IFNAMSIZ: (libc)Interface Naming.
- * IFTODT: (libc)Directory Entries.
- * IGNBRK: (libc)Input Modes.
- * IGNCR: (libc)Input Modes.
- * IGNPAR: (libc)Input Modes.
- * I: (libc)Complex Numbers.
- * ilogbf: (libc)Exponents and Logarithms.
- * ilogb: (libc)Exponents and Logarithms.
- * ilogbl: (libc)Exponents and Logarithms.
- * _Imaginary_I: (libc)Complex Numbers.
- * imaxabs: (libc)Absolute Value.
- * IMAXBEL: (libc)Input Modes.
- * imaxdiv: (libc)Integer Division.
- * in6addr_any: (libc)Host Address Data Type.
- * in6addr_loopback: (libc)Host Address Data Type.
- * INADDR_ANY: (libc)Host Address Data Type.
- * INADDR_BROADCAST: (libc)Host Address Data Type.
- * INADDR_LOOPBACK: (libc)Host Address Data Type.
- * INADDR_NONE: (libc)Host Address Data Type.
- * index: (libc)Search Functions.
- * inet_addr: (libc)Host Address Functions.
- * inet_aton: (libc)Host Address Functions.
- * inet_lnaof: (libc)Host Address Functions.
- * inet_makeaddr: (libc)Host Address Functions.
- * inet_netof: (libc)Host Address Functions.
- * inet_network: (libc)Host Address Functions.
- * inet_ntoa: (libc)Host Address Functions.
- * inet_ntop: (libc)Host Address Functions.
- * inet_pton: (libc)Host Address Functions.
- * INFINITY: (libc)Infinity and NaN.
- * initgroups: (libc)Setting Groups.
- * initstate: (libc)BSD Random.
- * initstate_r: (libc)BSD Random.
- * INLCR: (libc)Input Modes.
- * innetgr: (libc)Netgroup Membership.
- * INPCK: (libc)Input Modes.
- * ioctl: (libc)IOCTLs.
- * _IOFBF: (libc)Controlling Buffering.
- * _IOLBF: (libc)Controlling Buffering.
- * _IONBF: (libc)Controlling Buffering.
- * IPPORT_RESERVED: (libc)Ports.
- * IPPORT_USERRESERVED: (libc)Ports.
- * isalnum: (libc)Classification of Characters.
- * isalpha: (libc)Classification of Characters.
- * isascii: (libc)Classification of Characters.
- * isatty: (libc)Is It a Terminal.
- * isblank: (libc)Classification of Characters.
- * iscanonical: (libc)Floating Point Classes.
- * iscntrl: (libc)Classification of Characters.
- * isdigit: (libc)Classification of Characters.
- * iseqsig: (libc)FP Comparison Functions.
- * isfinite: (libc)Floating Point Classes.
- * isgraph: (libc)Classification of Characters.
- * isgreaterequal: (libc)FP Comparison Functions.
- * isgreater: (libc)FP Comparison Functions.
- * ISIG: (libc)Local Modes.
- * isinff: (libc)Floating Point Classes.
- * isinf: (libc)Floating Point Classes.
- * isinfl: (libc)Floating Point Classes.
- * islessequal: (libc)FP Comparison Functions.
- * islessgreater: (libc)FP Comparison Functions.
- * isless: (libc)FP Comparison Functions.
- * islower: (libc)Classification of Characters.
- * isnanf: (libc)Floating Point Classes.
- * isnan: (libc)Floating Point Classes.
- * isnan: (libc)Floating Point Classes.
- * isnanl: (libc)Floating Point Classes.
- * isnormal: (libc)Floating Point Classes.
- * isprint: (libc)Classification of Characters.
- * ispunct: (libc)Classification of Characters.
- * issignaling: (libc)Floating Point Classes.
- * isspace: (libc)Classification of Characters.
- * issubnormal: (libc)Floating Point Classes.
- * ISTRIP: (libc)Input Modes.
- * isunordered: (libc)FP Comparison Functions.
- * isupper: (libc)Classification of Characters.
- * iswalnum: (libc)Classification of Wide Characters.
- * iswalpha: (libc)Classification of Wide Characters.
- * iswblank: (libc)Classification of Wide Characters.
- * iswcntrl: (libc)Classification of Wide Characters.
- * iswctype: (libc)Classification of Wide Characters.
- * iswdigit: (libc)Classification of Wide Characters.
- * iswgraph: (libc)Classification of Wide Characters.
- * iswlower: (libc)Classification of Wide Characters.
- * iswprint: (libc)Classification of Wide Characters.
- * iswpunct: (libc)Classification of Wide Characters.
- * iswspace: (libc)Classification of Wide Characters.
- * iswupper: (libc)Classification of Wide Characters.
- * iswxdigit: (libc)Classification of Wide Characters.
- * isxdigit: (libc)Classification of Characters.
- * iszero: (libc)Floating Point Classes.
- * IXANY: (libc)Input Modes.
- * IXOFF: (libc)Input Modes.
- * IXON: (libc)Input Modes.
- * j0f: (libc)Special Functions.
- * j0: (libc)Special Functions.
- * j0l: (libc)Special Functions.
- * j1f: (libc)Special Functions.
- * j1: (libc)Special Functions.
- * j1l: (libc)Special Functions.
- * jnf: (libc)Special Functions.
- * jn: (libc)Special Functions.
- * jnl: (libc)Special Functions.
- * jrand48: (libc)SVID Random.
- * jrand48_r: (libc)SVID Random.
- * kill: (libc)Signaling Another Process.
- * killpg: (libc)Signaling Another Process.
- * l64a: (libc)Encode Binary Data.
- * labs: (libc)Absolute Value.
- * lcong48: (libc)SVID Random.
- * lcong48_r: (libc)SVID Random.
- * L_ctermid: (libc)Identifying the Terminal.
- * L_cuserid: (libc)Who Logged In.
- * ldexpf: (libc)Normalization Functions.
- * ldexp: (libc)Normalization Functions.
- * ldexpl: (libc)Normalization Functions.
- * ldiv: (libc)Integer Division.
- * lfind: (libc)Array Search Function.
- * lgammaf: (libc)Special Functions.
- * lgammaf_r: (libc)Special Functions.
- * lgamma: (libc)Special Functions.
- * lgammal: (libc)Special Functions.
- * lgammal_r: (libc)Special Functions.
- * lgamma_r: (libc)Special Functions.
- * LINE_MAX: (libc)Utility Limits.
- * link: (libc)Hard Links.
- * LINK_MAX: (libc)Limits for Files.
- * lio_listio64: (libc)Asynchronous Reads/Writes.
- * lio_listio: (libc)Asynchronous Reads/Writes.
- * listen: (libc)Listening.
- * llabs: (libc)Absolute Value.
- * lldiv: (libc)Integer Division.
- * llogbf: (libc)Exponents and Logarithms.
- * llogb: (libc)Exponents and Logarithms.
- * llogbl: (libc)Exponents and Logarithms.
- * llrintf: (libc)Rounding Functions.
- * llrint: (libc)Rounding Functions.
- * llrintl: (libc)Rounding Functions.
- * llroundf: (libc)Rounding Functions.
- * llround: (libc)Rounding Functions.
- * llroundl: (libc)Rounding Functions.
- * localeconv: (libc)The Lame Way to Locale Data.
- * localtime: (libc)Broken-down Time.
- * localtime_r: (libc)Broken-down Time.
- * log10f: (libc)Exponents and Logarithms.
- * log10: (libc)Exponents and Logarithms.
- * log10l: (libc)Exponents and Logarithms.
- * log1pf: (libc)Exponents and Logarithms.
- * log1p: (libc)Exponents and Logarithms.
- * log1pl: (libc)Exponents and Logarithms.
- * log2f: (libc)Exponents and Logarithms.
- * log2: (libc)Exponents and Logarithms.
- * log2l: (libc)Exponents and Logarithms.
- * logbf: (libc)Exponents and Logarithms.
- * logb: (libc)Exponents and Logarithms.
- * logbl: (libc)Exponents and Logarithms.
- * logf: (libc)Exponents and Logarithms.
- * login: (libc)Logging In and Out.
- * login_tty: (libc)Logging In and Out.
- * log: (libc)Exponents and Logarithms.
- * logl: (libc)Exponents and Logarithms.
- * logout: (libc)Logging In and Out.
- * logwtmp: (libc)Logging In and Out.
- * longjmp: (libc)Non-Local Details.
- * lrand48: (libc)SVID Random.
- * lrand48_r: (libc)SVID Random.
- * lrintf: (libc)Rounding Functions.
- * lrint: (libc)Rounding Functions.
- * lrintl: (libc)Rounding Functions.
- * lroundf: (libc)Rounding Functions.
- * lround: (libc)Rounding Functions.
- * lroundl: (libc)Rounding Functions.
- * lsearch: (libc)Array Search Function.
- * lseek64: (libc)File Position Primitive.
- * lseek: (libc)File Position Primitive.
- * lstat64: (libc)Reading Attributes.
- * lstat: (libc)Reading Attributes.
- * L_tmpnam: (libc)Temporary Files.
- * lutimes: (libc)File Times.
- * madvise: (libc)Memory-mapped I/O.
- * makecontext: (libc)System V contexts.
- * mallinfo: (libc)Statistics of Malloc.
- * malloc: (libc)Basic Allocation.
- * mallopt: (libc)Malloc Tunable Parameters.
- * MAX_CANON: (libc)Limits for Files.
- * MAX_INPUT: (libc)Limits for Files.
- * MAXNAMLEN: (libc)Limits for Files.
- * MAXSYMLINKS: (libc)Symbolic Links.
- * MB_CUR_MAX: (libc)Selecting the Conversion.
- * mblen: (libc)Non-reentrant Character Conversion.
- * MB_LEN_MAX: (libc)Selecting the Conversion.
- * mbrlen: (libc)Converting a Character.
- * mbrtowc: (libc)Converting a Character.
- * mbsinit: (libc)Keeping the state.
- * mbsnrtowcs: (libc)Converting Strings.
- * mbsrtowcs: (libc)Converting Strings.
- * mbstowcs: (libc)Non-reentrant String Conversion.
- * mbtowc: (libc)Non-reentrant Character Conversion.
- * mcheck: (libc)Heap Consistency Checking.
- * MDMBUF: (libc)Control Modes.
- * memalign: (libc)Aligned Memory Blocks.
- * memccpy: (libc)Copying Strings and Arrays.
- * memchr: (libc)Search Functions.
- * memcmp: (libc)String/Array Comparison.
- * memcpy: (libc)Copying Strings and Arrays.
- * memfrob: (libc)Trivial Encryption.
- * memmem: (libc)Search Functions.
- * memmove: (libc)Copying Strings and Arrays.
- * mempcpy: (libc)Copying Strings and Arrays.
- * memrchr: (libc)Search Functions.
- * memset: (libc)Copying Strings and Arrays.
- * mkdir: (libc)Creating Directories.
- * mkdtemp: (libc)Temporary Files.
- * mkfifo: (libc)FIFO Special Files.
- * mknod: (libc)Making Special Files.
- * mkstemp: (libc)Temporary Files.
- * mktemp: (libc)Temporary Files.
- * mktime: (libc)Broken-down Time.
- * mlockall: (libc)Page Lock Functions.
- * mlock: (libc)Page Lock Functions.
- * mmap64: (libc)Memory-mapped I/O.
- * mmap: (libc)Memory-mapped I/O.
- * modff: (libc)Rounding Functions.
- * modf: (libc)Rounding Functions.
- * modfl: (libc)Rounding Functions.
- * mount: (libc)Mount-Unmount-Remount.
- * mprobe: (libc)Heap Consistency Checking.
- * mrand48: (libc)SVID Random.
- * mrand48_r: (libc)SVID Random.
- * mremap: (libc)Memory-mapped I/O.
- * MSG_DONTROUTE: (libc)Socket Data Options.
- * MSG_OOB: (libc)Socket Data Options.
- * MSG_PEEK: (libc)Socket Data Options.
- * msync: (libc)Memory-mapped I/O.
- * mtrace: (libc)Tracing malloc.
- * munlockall: (libc)Page Lock Functions.
- * munlock: (libc)Page Lock Functions.
- * munmap: (libc)Memory-mapped I/O.
- * muntrace: (libc)Tracing malloc.
- * NAME_MAX: (libc)Limits for Files.
- * nanf: (libc)FP Bit Twiddling.
- * nan: (libc)FP Bit Twiddling.
- * NAN: (libc)Infinity and NaN.
- * nanl: (libc)FP Bit Twiddling.
- * nanosleep: (libc)Sleeping.
- * NCCS: (libc)Mode Data Types.
- * nearbyintf: (libc)Rounding Functions.
- * nearbyint: (libc)Rounding Functions.
- * nearbyintl: (libc)Rounding Functions.
- * nextafterf: (libc)FP Bit Twiddling.
- * nextafter: (libc)FP Bit Twiddling.
- * nextafterl: (libc)FP Bit Twiddling.
- * nextdownf: (libc)FP Bit Twiddling.
- * nextdown: (libc)FP Bit Twiddling.
- * nextdownl: (libc)FP Bit Twiddling.
- * nexttowardf: (libc)FP Bit Twiddling.
- * nexttoward: (libc)FP Bit Twiddling.
- * nexttowardl: (libc)FP Bit Twiddling.
- * nextupf: (libc)FP Bit Twiddling.
- * nextup: (libc)FP Bit Twiddling.
- * nextupl: (libc)FP Bit Twiddling.
- * nftw64: (libc)Working with Directory Trees.
- * nftw: (libc)Working with Directory Trees.
- * ngettext: (libc)Advanced gettext functions.
- * NGROUPS_MAX: (libc)General Limits.
- * nice: (libc)Traditional Scheduling Functions.
- * nl_langinfo: (libc)The Elegant and Fast Way.
- * NOFLSH: (libc)Local Modes.
- * NOKERNINFO: (libc)Local Modes.
- * nrand48: (libc)SVID Random.
- * nrand48_r: (libc)SVID Random.
- * NSIG: (libc)Standard Signals.
- * ntohl: (libc)Byte Order.
- * ntohs: (libc)Byte Order.
- * ntp_adjtime: (libc)High Accuracy Clock.
- * ntp_gettime: (libc)High Accuracy Clock.
- * NULL: (libc)Null Pointer Constant.
- * O_ACCMODE: (libc)Access Modes.
- * O_APPEND: (libc)Operating Modes.
- * O_ASYNC: (libc)Operating Modes.
- * obstack_1grow_fast: (libc)Extra Fast Growing.
- * obstack_1grow: (libc)Growing Objects.
- * obstack_alignment_mask: (libc)Obstacks Data Alignment.
- * obstack_alloc: (libc)Allocation in an Obstack.
- * obstack_base: (libc)Status of an Obstack.
- * obstack_blank_fast: (libc)Extra Fast Growing.
- * obstack_blank: (libc)Growing Objects.
- * obstack_chunk_size: (libc)Obstack Chunks.
- * obstack_copy0: (libc)Allocation in an Obstack.
- * obstack_copy: (libc)Allocation in an Obstack.
- * obstack_finish: (libc)Growing Objects.
- * obstack_free: (libc)Freeing Obstack Objects.
- * obstack_grow0: (libc)Growing Objects.
- * obstack_grow: (libc)Growing Objects.
- * obstack_init: (libc)Preparing for Obstacks.
- * obstack_int_grow_fast: (libc)Extra Fast Growing.
- * obstack_int_grow: (libc)Growing Objects.
- * obstack_next_free: (libc)Status of an Obstack.
- * obstack_object_size: (libc)Growing Objects.
- * obstack_object_size: (libc)Status of an Obstack.
- * obstack_printf: (libc)Dynamic Output.
- * obstack_ptr_grow_fast: (libc)Extra Fast Growing.
- * obstack_ptr_grow: (libc)Growing Objects.
- * obstack_room: (libc)Extra Fast Growing.
- * obstack_vprintf: (libc)Variable Arguments Output.
- * O_CREAT: (libc)Open-time Flags.
- * O_EXCL: (libc)Open-time Flags.
- * O_EXEC: (libc)Access Modes.
- * O_EXLOCK: (libc)Open-time Flags.
- * offsetof: (libc)Structure Measurement.
- * O_FSYNC: (libc)Operating Modes.
- * O_IGNORE_CTTY: (libc)Open-time Flags.
- * O_NDELAY: (libc)Operating Modes.
- * on_exit: (libc)Cleanups on Exit.
- * ONLCR: (libc)Output Modes.
- * O_NOATIME: (libc)Operating Modes.
- * O_NOCTTY: (libc)Open-time Flags.
- * ONOEOT: (libc)Output Modes.
- * O_NOLINK: (libc)Open-time Flags.
- * O_NONBLOCK: (libc)Open-time Flags.
- * O_NONBLOCK: (libc)Operating Modes.
- * O_NOTRANS: (libc)Open-time Flags.
- * open64: (libc)Opening and Closing Files.
- * opendir: (libc)Opening a Directory.
- * open: (libc)Opening and Closing Files.
- * openlog: (libc)openlog.
- * OPEN_MAX: (libc)General Limits.
- * open_memstream: (libc)String Streams.
- * openpty: (libc)Pseudo-Terminal Pairs.
- * OPOST: (libc)Output Modes.
- * O_RDONLY: (libc)Access Modes.
- * O_RDWR: (libc)Access Modes.
- * O_READ: (libc)Access Modes.
- * O_SHLOCK: (libc)Open-time Flags.
- * O_SYNC: (libc)Operating Modes.
- * O_TRUNC: (libc)Open-time Flags.
- * O_WRITE: (libc)Access Modes.
- * O_WRONLY: (libc)Access Modes.
- * OXTABS: (libc)Output Modes.
- * PA_FLAG_MASK: (libc)Parsing a Template String.
- * PARENB: (libc)Control Modes.
- * PARMRK: (libc)Input Modes.
- * PARODD: (libc)Control Modes.
- * parse_printf_format: (libc)Parsing a Template String.
- * pathconf: (libc)Pathconf.
- * PATH_MAX: (libc)Limits for Files.
- * _PATH_UTMP: (libc)Manipulating the Database.
- * _PATH_WTMP: (libc)Manipulating the Database.
- * pause: (libc)Using Pause.
- * pclose: (libc)Pipe to a Subprocess.
- * PENDIN: (libc)Local Modes.
- * perror: (libc)Error Messages.
- * PF_FILE: (libc)Local Namespace Details.
- * PF_INET6: (libc)Internet Namespace.
- * PF_INET: (libc)Internet Namespace.
- * PF_LOCAL: (libc)Local Namespace Details.
- * PF_UNIX: (libc)Local Namespace Details.
- * PIPE_BUF: (libc)Limits for Files.
- * pipe: (libc)Creating a Pipe.
- * popen: (libc)Pipe to a Subprocess.
- * _POSIX2_C_DEV: (libc)System Options.
- * _POSIX2_C_VERSION: (libc)Version Supported.
- * _POSIX2_FORT_DEV: (libc)System Options.
- * _POSIX2_FORT_RUN: (libc)System Options.
- * _POSIX2_LOCALEDEF: (libc)System Options.
- * _POSIX2_SW_DEV: (libc)System Options.
- * _POSIX_CHOWN_RESTRICTED: (libc)Options for Files.
- * posix_fallocate64: (libc)Storage Allocation.
- * posix_fallocate: (libc)Storage Allocation.
- * _POSIX_JOB_CONTROL: (libc)System Options.
- * posix_memalign: (libc)Aligned Memory Blocks.
- * _POSIX_NO_TRUNC: (libc)Options for Files.
- * _POSIX_SAVED_IDS: (libc)System Options.
- * _POSIX_VDISABLE: (libc)Options for Files.
- * _POSIX_VERSION: (libc)Version Supported.
- * pow10f: (libc)Exponents and Logarithms.
- * pow10: (libc)Exponents and Logarithms.
- * pow10l: (libc)Exponents and Logarithms.
- * powf: (libc)Exponents and Logarithms.
- * pow: (libc)Exponents and Logarithms.
- * powl: (libc)Exponents and Logarithms.
- * __ppc_get_timebase_freq: (libc)PowerPC.
- * __ppc_get_timebase: (libc)PowerPC.
- * __ppc_mdoio: (libc)PowerPC.
- * __ppc_mdoom: (libc)PowerPC.
- * __ppc_set_ppr_low: (libc)PowerPC.
- * __ppc_set_ppr_med_high: (libc)PowerPC.
- * __ppc_set_ppr_med: (libc)PowerPC.
- * __ppc_set_ppr_med_low: (libc)PowerPC.
- * __ppc_set_ppr_very_low: (libc)PowerPC.
- * __ppc_yield: (libc)PowerPC.
- * pread64: (libc)I/O Primitives.
- * pread: (libc)I/O Primitives.
- * printf: (libc)Formatted Output Functions.
- * printf_size_info: (libc)Predefined Printf Handlers.
- * printf_size: (libc)Predefined Printf Handlers.
- * psignal: (libc)Signal Messages.
- * pthread_getattr_default_np: (libc)Default Thread Attributes.
- * pthread_getspecific: (libc)Thread-specific Data.
- * pthread_key_create: (libc)Thread-specific Data.
- * pthread_key_delete: (libc)Thread-specific Data.
- * pthread_setattr_default_np: (libc)Default Thread Attributes.
- * pthread_setspecific: (libc)Thread-specific Data.
- * P_tmpdir: (libc)Temporary Files.
- * ptsname: (libc)Allocation.
- * ptsname_r: (libc)Allocation.
- * putchar: (libc)Simple Output.
- * putchar_unlocked: (libc)Simple Output.
- * putc: (libc)Simple Output.
- * putc_unlocked: (libc)Simple Output.
- * putenv: (libc)Environment Access.
- * putpwent: (libc)Writing a User Entry.
- * puts: (libc)Simple Output.
- * pututline: (libc)Manipulating the Database.
- * pututxline: (libc)XPG Functions.
- * putwchar: (libc)Simple Output.
- * putwchar_unlocked: (libc)Simple Output.
- * putwc: (libc)Simple Output.
- * putwc_unlocked: (libc)Simple Output.
- * putw: (libc)Simple Output.
- * pwrite64: (libc)I/O Primitives.
- * pwrite: (libc)I/O Primitives.
- * qecvt: (libc)System V Number Conversion.
- * qecvt_r: (libc)System V Number Conversion.
- * qfcvt: (libc)System V Number Conversion.
- * qfcvt_r: (libc)System V Number Conversion.
- * qgcvt: (libc)System V Number Conversion.
- * qsort: (libc)Array Sort Function.
- * raise: (libc)Signaling Yourself.
- * rand: (libc)ISO Random.
- * RAND_MAX: (libc)ISO Random.
- * random: (libc)BSD Random.
- * random_r: (libc)BSD Random.
- * rand_r: (libc)ISO Random.
- * rawmemchr: (libc)Search Functions.
- * readdir64: (libc)Reading/Closing Directory.
- * readdir64_r: (libc)Reading/Closing Directory.
- * readdir: (libc)Reading/Closing Directory.
- * readdir_r: (libc)Reading/Closing Directory.
- * read: (libc)I/O Primitives.
- * readlink: (libc)Symbolic Links.
- * readv: (libc)Scatter-Gather.
- * realloc: (libc)Changing Block Size.
- * realpath: (libc)Symbolic Links.
- * recvfrom: (libc)Receiving Datagrams.
- * recv: (libc)Receiving Data.
- * recvmsg: (libc)Receiving Datagrams.
- * RE_DUP_MAX: (libc)General Limits.
- * regcomp: (libc)POSIX Regexp Compilation.
- * regerror: (libc)Regexp Cleanup.
- * regexec: (libc)Matching POSIX Regexps.
- * regfree: (libc)Regexp Cleanup.
- * register_printf_function: (libc)Registering New Conversions.
- * remainderf: (libc)Remainder Functions.
- * remainder: (libc)Remainder Functions.
- * remainderl: (libc)Remainder Functions.
- * remove: (libc)Deleting Files.
- * rename: (libc)Renaming Files.
- * rewinddir: (libc)Random Access Directory.
- * rewind: (libc)File Positioning.
- * rindex: (libc)Search Functions.
- * rintf: (libc)Rounding Functions.
- * rint: (libc)Rounding Functions.
- * rintl: (libc)Rounding Functions.
- * RLIM_INFINITY: (libc)Limits on Resources.
- * rmdir: (libc)Deleting Files.
- * R_OK: (libc)Testing File Access.
- * roundevenf: (libc)Rounding Functions.
- * roundeven: (libc)Rounding Functions.
- * roundevenl: (libc)Rounding Functions.
- * roundf: (libc)Rounding Functions.
- * round: (libc)Rounding Functions.
- * roundl: (libc)Rounding Functions.
- * rpmatch: (libc)Yes-or-No Questions.
- * SA_NOCLDSTOP: (libc)Flags for Sigaction.
- * SA_ONSTACK: (libc)Flags for Sigaction.
- * SA_RESTART: (libc)Flags for Sigaction.
- * sbrk: (libc)Resizing the Data Segment.
- * scalbf: (libc)Normalization Functions.
- * scalb: (libc)Normalization Functions.
- * scalbl: (libc)Normalization Functions.
- * scalblnf: (libc)Normalization Functions.
- * scalbln: (libc)Normalization Functions.
- * scalblnl: (libc)Normalization Functions.
- * scalbnf: (libc)Normalization Functions.
- * scalbn: (libc)Normalization Functions.
- * scalbnl: (libc)Normalization Functions.
- * scandir64: (libc)Scanning Directory Content.
- * scandir: (libc)Scanning Directory Content.
- * scanf: (libc)Formatted Input Functions.
- * sched_getaffinity: (libc)CPU Affinity.
- * sched_getparam: (libc)Basic Scheduling Functions.
- * sched_get_priority_max: (libc)Basic Scheduling Functions.
- * sched_get_priority_min: (libc)Basic Scheduling Functions.
- * sched_getscheduler: (libc)Basic Scheduling Functions.
- * sched_rr_get_interval: (libc)Basic Scheduling Functions.
- * sched_setaffinity: (libc)CPU Affinity.
- * sched_setparam: (libc)Basic Scheduling Functions.
- * sched_setscheduler: (libc)Basic Scheduling Functions.
- * sched_yield: (libc)Basic Scheduling Functions.
- * secure_getenv: (libc)Environment Access.
- * seed48: (libc)SVID Random.
- * seed48_r: (libc)SVID Random.
- * SEEK_CUR: (libc)File Positioning.
- * seekdir: (libc)Random Access Directory.
- * SEEK_END: (libc)File Positioning.
- * SEEK_SET: (libc)File Positioning.
- * select: (libc)Waiting for I/O.
- * sem_close: (libc)Semaphores.
- * semctl: (libc)Semaphores.
- * sem_destroy: (libc)Semaphores.
- * semget: (libc)Semaphores.
- * sem_getvalue: (libc)Semaphores.
- * sem_init: (libc)Semaphores.
- * sem_open: (libc)Semaphores.
- * semop: (libc)Semaphores.
- * sem_post: (libc)Semaphores.
- * semtimedop: (libc)Semaphores.
- * sem_timedwait: (libc)Semaphores.
- * sem_trywait: (libc)Semaphores.
- * sem_unlink: (libc)Semaphores.
- * sem_wait: (libc)Semaphores.
- * send: (libc)Sending Data.
- * sendmsg: (libc)Receiving Datagrams.
- * sendto: (libc)Sending Datagrams.
- * setbuffer: (libc)Controlling Buffering.
- * setbuf: (libc)Controlling Buffering.
- * setcontext: (libc)System V contexts.
- * setdomainname: (libc)Host Identification.
- * setegid: (libc)Setting Groups.
- * setenv: (libc)Environment Access.
- * seteuid: (libc)Setting User ID.
- * setfsent: (libc)fstab.
- * setgid: (libc)Setting Groups.
- * setgrent: (libc)Scanning All Groups.
- * setgroups: (libc)Setting Groups.
- * sethostent: (libc)Host Names.
- * sethostid: (libc)Host Identification.
- * sethostname: (libc)Host Identification.
- * setitimer: (libc)Setting an Alarm.
- * setjmp: (libc)Non-Local Details.
- * setkey: (libc)DES Encryption.
- * setkey_r: (libc)DES Encryption.
- * setlinebuf: (libc)Controlling Buffering.
- * setlocale: (libc)Setting the Locale.
- * setlogmask: (libc)setlogmask.
- * setmntent: (libc)mtab.
- * setnetent: (libc)Networks Database.
- * setnetgrent: (libc)Lookup Netgroup.
- * setpayloadf: (libc)FP Bit Twiddling.
- * setpayload: (libc)FP Bit Twiddling.
- * setpayloadl: (libc)FP Bit Twiddling.
- * setpayloadsigf: (libc)FP Bit Twiddling.
- * setpayloadsig: (libc)FP Bit Twiddling.
- * setpayloadsigl: (libc)FP Bit Twiddling.
- * setpgid: (libc)Process Group Functions.
- * setpgrp: (libc)Process Group Functions.
- * setpriority: (libc)Traditional Scheduling Functions.
- * setprotoent: (libc)Protocols Database.
- * setpwent: (libc)Scanning All Users.
- * setregid: (libc)Setting Groups.
- * setreuid: (libc)Setting User ID.
- * setrlimit64: (libc)Limits on Resources.
- * setrlimit: (libc)Limits on Resources.
- * setservent: (libc)Services Database.
- * setsid: (libc)Process Group Functions.
- * setsockopt: (libc)Socket Option Functions.
- * setstate: (libc)BSD Random.
- * setstate_r: (libc)BSD Random.
- * settimeofday: (libc)High-Resolution Calendar.
- * setuid: (libc)Setting User ID.
- * setutent: (libc)Manipulating the Database.
- * setutxent: (libc)XPG Functions.
- * setvbuf: (libc)Controlling Buffering.
- * shm_open: (libc)Memory-mapped I/O.
- * shm_unlink: (libc)Memory-mapped I/O.
- * shutdown: (libc)Closing a Socket.
- * S_IFMT: (libc)Testing File Type.
- * SIGABRT: (libc)Program Error Signals.
- * sigaction: (libc)Advanced Signal Handling.
- * sigaddset: (libc)Signal Sets.
- * SIGALRM: (libc)Alarm Signals.
- * sigaltstack: (libc)Signal Stack.
- * sigblock: (libc)BSD Signal Handling.
- * SIGBUS: (libc)Program Error Signals.
- * SIGCHLD: (libc)Job Control Signals.
- * SIGCLD: (libc)Job Control Signals.
- * SIGCONT: (libc)Job Control Signals.
- * sigdelset: (libc)Signal Sets.
- * sigemptyset: (libc)Signal Sets.
- * SIGEMT: (libc)Program Error Signals.
- * SIG_ERR: (libc)Basic Signal Handling.
- * sigfillset: (libc)Signal Sets.
- * SIGFPE: (libc)Program Error Signals.
- * SIGHUP: (libc)Termination Signals.
- * SIGILL: (libc)Program Error Signals.
- * SIGINFO: (libc)Miscellaneous Signals.
- * siginterrupt: (libc)BSD Signal Handling.
- * SIGINT: (libc)Termination Signals.
- * SIGIO: (libc)Asynchronous I/O Signals.
- * SIGIOT: (libc)Program Error Signals.
- * sigismember: (libc)Signal Sets.
- * SIGKILL: (libc)Termination Signals.
- * siglongjmp: (libc)Non-Local Exits and Signals.
- * SIGLOST: (libc)Operation Error Signals.
- * sigmask: (libc)BSD Signal Handling.
- * signal: (libc)Basic Signal Handling.
- * signbit: (libc)FP Bit Twiddling.
- * significandf: (libc)Normalization Functions.
- * significand: (libc)Normalization Functions.
- * significandl: (libc)Normalization Functions.
- * sigpause: (libc)BSD Signal Handling.
- * sigpending: (libc)Checking for Pending Signals.
- * SIGPIPE: (libc)Operation Error Signals.
- * SIGPOLL: (libc)Asynchronous I/O Signals.
- * sigprocmask: (libc)Process Signal Mask.
- * SIGPROF: (libc)Alarm Signals.
- * SIGQUIT: (libc)Termination Signals.
- * SIGSEGV: (libc)Program Error Signals.
- * sigsetjmp: (libc)Non-Local Exits and Signals.
- * sigsetmask: (libc)BSD Signal Handling.
- * sigstack: (libc)Signal Stack.
- * SIGSTOP: (libc)Job Control Signals.
- * sigsuspend: (libc)Sigsuspend.
- * SIGSYS: (libc)Program Error Signals.
- * SIGTERM: (libc)Termination Signals.
- * SIGTRAP: (libc)Program Error Signals.
- * SIGTSTP: (libc)Job Control Signals.
- * SIGTTIN: (libc)Job Control Signals.
- * SIGTTOU: (libc)Job Control Signals.
- * SIGURG: (libc)Asynchronous I/O Signals.
- * SIGUSR1: (libc)Miscellaneous Signals.
- * SIGUSR2: (libc)Miscellaneous Signals.
- * SIGVTALRM: (libc)Alarm Signals.
- * SIGWINCH: (libc)Miscellaneous Signals.
- * SIGXCPU: (libc)Operation Error Signals.
- * SIGXFSZ: (libc)Operation Error Signals.
- * sincosf: (libc)Trig Functions.
- * sincos: (libc)Trig Functions.
- * sincosl: (libc)Trig Functions.
- * sinf: (libc)Trig Functions.
- * sinhf: (libc)Hyperbolic Functions.
- * sinh: (libc)Hyperbolic Functions.
- * sinhl: (libc)Hyperbolic Functions.
- * sin: (libc)Trig Functions.
- * sinl: (libc)Trig Functions.
- * S_ISBLK: (libc)Testing File Type.
- * S_ISCHR: (libc)Testing File Type.
- * S_ISDIR: (libc)Testing File Type.
- * S_ISFIFO: (libc)Testing File Type.
- * S_ISLNK: (libc)Testing File Type.
- * S_ISREG: (libc)Testing File Type.
- * S_ISSOCK: (libc)Testing File Type.
- * sleep: (libc)Sleeping.
- * SNANF: (libc)Infinity and NaN.
- * SNAN: (libc)Infinity and NaN.
- * SNANL: (libc)Infinity and NaN.
- * snprintf: (libc)Formatted Output Functions.
- * SOCK_DGRAM: (libc)Communication Styles.
- * socket: (libc)Creating a Socket.
- * socketpair: (libc)Socket Pairs.
- * SOCK_RAW: (libc)Communication Styles.
- * SOCK_RDM: (libc)Communication Styles.
- * SOCK_SEQPACKET: (libc)Communication Styles.
- * SOCK_STREAM: (libc)Communication Styles.
- * SOL_SOCKET: (libc)Socket-Level Options.
- * sprintf: (libc)Formatted Output Functions.
- * sqrtf: (libc)Exponents and Logarithms.
- * sqrt: (libc)Exponents and Logarithms.
- * sqrtl: (libc)Exponents and Logarithms.
- * srand48: (libc)SVID Random.
- * srand48_r: (libc)SVID Random.
- * srand: (libc)ISO Random.
- * srandom: (libc)BSD Random.
- * srandom_r: (libc)BSD Random.
- * sscanf: (libc)Formatted Input Functions.
- * ssignal: (libc)Basic Signal Handling.
- * SSIZE_MAX: (libc)General Limits.
- * stat64: (libc)Reading Attributes.
- * stat: (libc)Reading Attributes.
- * stime: (libc)Simple Calendar Time.
- * stpcpy: (libc)Copying Strings and Arrays.
- * stpncpy: (libc)Truncating Strings.
- * strcasecmp: (libc)String/Array Comparison.
- * strcasestr: (libc)Search Functions.
- * strcat: (libc)Concatenating Strings.
- * strchr: (libc)Search Functions.
- * strchrnul: (libc)Search Functions.
- * strcmp: (libc)String/Array Comparison.
- * strcoll: (libc)Collation Functions.
- * strcpy: (libc)Copying Strings and Arrays.
- * strcspn: (libc)Search Functions.
- * strdupa: (libc)Copying Strings and Arrays.
- * strdup: (libc)Copying Strings and Arrays.
- * STREAM_MAX: (libc)General Limits.
- * strerror: (libc)Error Messages.
- * strerror_r: (libc)Error Messages.
- * strfmon: (libc)Formatting Numbers.
- * strfromd: (libc)Printing of Floats.
- * strfromf: (libc)Printing of Floats.
- * strfroml: (libc)Printing of Floats.
- * strfry: (libc)strfry.
- * strftime: (libc)Formatting Calendar Time.
- * strlen: (libc)String Length.
- * strncasecmp: (libc)String/Array Comparison.
- * strncat: (libc)Truncating Strings.
- * strncmp: (libc)String/Array Comparison.
- * strncpy: (libc)Truncating Strings.
- * strndupa: (libc)Truncating Strings.
- * strndup: (libc)Truncating Strings.
- * strnlen: (libc)String Length.
- * strpbrk: (libc)Search Functions.
- * strptime: (libc)Low-Level Time String Parsing.
- * strrchr: (libc)Search Functions.
- * strsep: (libc)Finding Tokens in a String.
- * strsignal: (libc)Signal Messages.
- * strspn: (libc)Search Functions.
- * strstr: (libc)Search Functions.
- * strtod: (libc)Parsing of Floats.
- * strtof: (libc)Parsing of Floats.
- * strtoimax: (libc)Parsing of Integers.
- * strtok: (libc)Finding Tokens in a String.
- * strtok_r: (libc)Finding Tokens in a String.
- * strtold: (libc)Parsing of Floats.
- * strtol: (libc)Parsing of Integers.
- * strtoll: (libc)Parsing of Integers.
- * strtoq: (libc)Parsing of Integers.
- * strtoul: (libc)Parsing of Integers.
- * strtoull: (libc)Parsing of Integers.
- * strtoumax: (libc)Parsing of Integers.
- * strtouq: (libc)Parsing of Integers.
- * strverscmp: (libc)String/Array Comparison.
- * strxfrm: (libc)Collation Functions.
- * stty: (libc)BSD Terminal Modes.
- * S_TYPEISMQ: (libc)Testing File Type.
- * S_TYPEISSEM: (libc)Testing File Type.
- * S_TYPEISSHM: (libc)Testing File Type.
- * SUN_LEN: (libc)Local Namespace Details.
- * swapcontext: (libc)System V contexts.
- * swprintf: (libc)Formatted Output Functions.
- * swscanf: (libc)Formatted Input Functions.
- * symlink: (libc)Symbolic Links.
- * sync: (libc)Synchronizing I/O.
- * syscall: (libc)System Calls.
- * sysconf: (libc)Sysconf Definition.
- * sysctl: (libc)System Parameters.
- * syslog: (libc)syslog; vsyslog.
- * system: (libc)Running a Command.
- * sysv_signal: (libc)Basic Signal Handling.
- * tanf: (libc)Trig Functions.
- * tanhf: (libc)Hyperbolic Functions.
- * tanh: (libc)Hyperbolic Functions.
- * tanhl: (libc)Hyperbolic Functions.
- * tan: (libc)Trig Functions.
- * tanl: (libc)Trig Functions.
- * tcdrain: (libc)Line Control.
- * tcflow: (libc)Line Control.
- * tcflush: (libc)Line Control.
- * tcgetattr: (libc)Mode Functions.
- * tcgetpgrp: (libc)Terminal Access Functions.
- * tcgetsid: (libc)Terminal Access Functions.
- * tcsendbreak: (libc)Line Control.
- * tcsetattr: (libc)Mode Functions.
- * tcsetpgrp: (libc)Terminal Access Functions.
- * tdelete: (libc)Tree Search Function.
- * tdestroy: (libc)Tree Search Function.
- * telldir: (libc)Random Access Directory.
- * tempnam: (libc)Temporary Files.
- * textdomain: (libc)Locating gettext catalog.
- * tfind: (libc)Tree Search Function.
- * tgammaf: (libc)Special Functions.
- * tgamma: (libc)Special Functions.
- * tgammal: (libc)Special Functions.
- * timegm: (libc)Broken-down Time.
- * time: (libc)Simple Calendar Time.
- * timelocal: (libc)Broken-down Time.
- * times: (libc)Processor Time.
- * tmpfile64: (libc)Temporary Files.
- * tmpfile: (libc)Temporary Files.
- * TMP_MAX: (libc)Temporary Files.
- * tmpnam: (libc)Temporary Files.
- * tmpnam_r: (libc)Temporary Files.
- * toascii: (libc)Case Conversion.
- * _tolower: (libc)Case Conversion.
- * tolower: (libc)Case Conversion.
- * TOSTOP: (libc)Local Modes.
- * totalorderf: (libc)FP Comparison Functions.
- * totalorder: (libc)FP Comparison Functions.
- * totalorderl: (libc)FP Comparison Functions.
- * totalordermagf: (libc)FP Comparison Functions.
- * totalordermag: (libc)FP Comparison Functions.
- * totalordermagl: (libc)FP Comparison Functions.
- * _toupper: (libc)Case Conversion.
- * toupper: (libc)Case Conversion.
- * towctrans: (libc)Wide Character Case Conversion.
- * towlower: (libc)Wide Character Case Conversion.
- * towupper: (libc)Wide Character Case Conversion.
- * truncate64: (libc)File Size.
- * truncate: (libc)File Size.
- * truncf: (libc)Rounding Functions.
- * trunc: (libc)Rounding Functions.
- * truncl: (libc)Rounding Functions.
- * tsearch: (libc)Tree Search Function.
- * ttyname: (libc)Is It a Terminal.
- * ttyname_r: (libc)Is It a Terminal.
- * twalk: (libc)Tree Search Function.
- * TZNAME_MAX: (libc)General Limits.
- * tzset: (libc)Time Zone Functions.
- * ufromfpf: (libc)Rounding Functions.
- * ufromfp: (libc)Rounding Functions.
- * ufromfpl: (libc)Rounding Functions.
- * ufromfpxf: (libc)Rounding Functions.
- * ufromfpx: (libc)Rounding Functions.
- * ufromfpxl: (libc)Rounding Functions.
- * ulimit: (libc)Limits on Resources.
- * umask: (libc)Setting Permissions.
- * umount2: (libc)Mount-Unmount-Remount.
- * umount: (libc)Mount-Unmount-Remount.
- * uname: (libc)Platform Type.
- * ungetc: (libc)How Unread.
- * ungetwc: (libc)How Unread.
- * unlink: (libc)Deleting Files.
- * unlockpt: (libc)Allocation.
- * unsetenv: (libc)Environment Access.
- * updwtmp: (libc)Manipulating the Database.
- * utime: (libc)File Times.
- * utimes: (libc)File Times.
- * utmpname: (libc)Manipulating the Database.
- * utmpxname: (libc)XPG Functions.
- * va_arg: (libc)Argument Macros.
- * __va_copy: (libc)Argument Macros.
- * va_copy: (libc)Argument Macros.
- * va_end: (libc)Argument Macros.
- * valloc: (libc)Aligned Memory Blocks.
- * vasprintf: (libc)Variable Arguments Output.
- * va_start: (libc)Argument Macros.
- * VDISCARD: (libc)Other Special.
- * VDSUSP: (libc)Signal Characters.
- * VEOF: (libc)Editing Characters.
- * VEOL2: (libc)Editing Characters.
- * VEOL: (libc)Editing Characters.
- * VERASE: (libc)Editing Characters.
- * verr: (libc)Error Messages.
- * verrx: (libc)Error Messages.
- * versionsort64: (libc)Scanning Directory Content.
- * versionsort: (libc)Scanning Directory Content.
- * vfork: (libc)Creating a Process.
- * vfprintf: (libc)Variable Arguments Output.
- * vfscanf: (libc)Variable Arguments Input.
- * vfwprintf: (libc)Variable Arguments Output.
- * vfwscanf: (libc)Variable Arguments Input.
- * VINTR: (libc)Signal Characters.
- * VKILL: (libc)Editing Characters.
- * vlimit: (libc)Limits on Resources.
- * VLNEXT: (libc)Other Special.
- * VMIN: (libc)Noncanonical Input.
- * vprintf: (libc)Variable Arguments Output.
- * VQUIT: (libc)Signal Characters.
- * VREPRINT: (libc)Editing Characters.
- * vscanf: (libc)Variable Arguments Input.
- * vsnprintf: (libc)Variable Arguments Output.
- * vsprintf: (libc)Variable Arguments Output.
- * vsscanf: (libc)Variable Arguments Input.
- * VSTART: (libc)Start/Stop Characters.
- * VSTATUS: (libc)Other Special.
- * VSTOP: (libc)Start/Stop Characters.
- * VSUSP: (libc)Signal Characters.
- * vswprintf: (libc)Variable Arguments Output.
- * vswscanf: (libc)Variable Arguments Input.
- * vsyslog: (libc)syslog; vsyslog.
- * VTIME: (libc)Noncanonical Input.
- * vtimes: (libc)Resource Usage.
- * vwarn: (libc)Error Messages.
- * vwarnx: (libc)Error Messages.
- * VWERASE: (libc)Editing Characters.
- * vwprintf: (libc)Variable Arguments Output.
- * vwscanf: (libc)Variable Arguments Input.
- * wait3: (libc)BSD Wait Functions.
- * wait4: (libc)Process Completion.
- * wait: (libc)Process Completion.
- * waitpid: (libc)Process Completion.
- * warn: (libc)Error Messages.
- * warnx: (libc)Error Messages.
- * WCHAR_MAX: (libc)Extended Char Intro.
- * WCHAR_MIN: (libc)Extended Char Intro.
- * WCOREDUMP: (libc)Process Completion Status.
- * wcpcpy: (libc)Copying Strings and Arrays.
- * wcpncpy: (libc)Truncating Strings.
- * wcrtomb: (libc)Converting a Character.
- * wcscasecmp: (libc)String/Array Comparison.
- * wcscat: (libc)Concatenating Strings.
- * wcschr: (libc)Search Functions.
- * wcschrnul: (libc)Search Functions.
- * wcscmp: (libc)String/Array Comparison.
- * wcscoll: (libc)Collation Functions.
- * wcscpy: (libc)Copying Strings and Arrays.
- * wcscspn: (libc)Search Functions.
- * wcsdup: (libc)Copying Strings and Arrays.
- * wcsftime: (libc)Formatting Calendar Time.
- * wcslen: (libc)String Length.
- * wcsncasecmp: (libc)String/Array Comparison.
- * wcsncat: (libc)Truncating Strings.
- * wcsncmp: (libc)String/Array Comparison.
- * wcsncpy: (libc)Truncating Strings.
- * wcsnlen: (libc)String Length.
- * wcsnrtombs: (libc)Converting Strings.
- * wcspbrk: (libc)Search Functions.
- * wcsrchr: (libc)Search Functions.
- * wcsrtombs: (libc)Converting Strings.
- * wcsspn: (libc)Search Functions.
- * wcsstr: (libc)Search Functions.
- * wcstod: (libc)Parsing of Floats.
- * wcstof: (libc)Parsing of Floats.
- * wcstoimax: (libc)Parsing of Integers.
- * wcstok: (libc)Finding Tokens in a String.
- * wcstold: (libc)Parsing of Floats.
- * wcstol: (libc)Parsing of Integers.
- * wcstoll: (libc)Parsing of Integers.
- * wcstombs: (libc)Non-reentrant String Conversion.
- * wcstoq: (libc)Parsing of Integers.
- * wcstoul: (libc)Parsing of Integers.
- * wcstoull: (libc)Parsing of Integers.
- * wcstoumax: (libc)Parsing of Integers.
- * wcstouq: (libc)Parsing of Integers.
- * wcswcs: (libc)Search Functions.
- * wcsxfrm: (libc)Collation Functions.
- * wctob: (libc)Converting a Character.
- * wctomb: (libc)Non-reentrant Character Conversion.
- * wctrans: (libc)Wide Character Case Conversion.
- * wctype: (libc)Classification of Wide Characters.
- * WEOF: (libc)EOF and Errors.
- * WEOF: (libc)Extended Char Intro.
- * WEXITSTATUS: (libc)Process Completion Status.
- * WIFEXITED: (libc)Process Completion Status.
- * WIFSIGNALED: (libc)Process Completion Status.
- * WIFSTOPPED: (libc)Process Completion Status.
- * wmemchr: (libc)Search Functions.
- * wmemcmp: (libc)String/Array Comparison.
- * wmemcpy: (libc)Copying Strings and Arrays.
- * wmemmove: (libc)Copying Strings and Arrays.
- * wmempcpy: (libc)Copying Strings and Arrays.
- * wmemset: (libc)Copying Strings and Arrays.
- * W_OK: (libc)Testing File Access.
- * wordexp: (libc)Calling Wordexp.
- * wordfree: (libc)Calling Wordexp.
- * wprintf: (libc)Formatted Output Functions.
- * write: (libc)I/O Primitives.
- * writev: (libc)Scatter-Gather.
- * wscanf: (libc)Formatted Input Functions.
- * WSTOPSIG: (libc)Process Completion Status.
- * WTERMSIG: (libc)Process Completion Status.
- * X_OK: (libc)Testing File Access.
- * y0f: (libc)Special Functions.
- * y0: (libc)Special Functions.
- * y0l: (libc)Special Functions.
- * y1f: (libc)Special Functions.
- * y1: (libc)Special Functions.
- * y1l: (libc)Special Functions.
- * ynf: (libc)Special Functions.
- * yn: (libc)Special Functions.
- * ynl: (libc)Special Functions.
- END-INFO-DIR-ENTRY
- File: libc.info, Node: Flags for Sigaction, Next: Initial Signal Actions, Prev: Sigaction Function Example, Up: Signal Actions
- 24.3.5 Flags for ‘sigaction’
- ----------------------------
- The ‘sa_flags’ member of the ‘sigaction’ structure is a catch-all for
- special features. Most of the time, ‘SA_RESTART’ is a good value to use
- for this field.
- The value of ‘sa_flags’ is interpreted as a bit mask. Thus, you
- should choose the flags you want to set, OR those flags together, and
- store the result in the ‘sa_flags’ member of your ‘sigaction’ structure.
- Each signal number has its own set of flags. Each call to
- ‘sigaction’ affects one particular signal number, and the flags that you
- specify apply only to that particular signal.
- In the GNU C Library, establishing a handler with ‘signal’ sets all
- the flags to zero except for ‘SA_RESTART’, whose value depends on the
- settings you have made with ‘siginterrupt’. *Note Interrupted
- Primitives::, to see what this is about.
- These macros are defined in the header file ‘signal.h’.
- -- Macro: int SA_NOCLDSTOP
- This flag is meaningful only for the ‘SIGCHLD’ signal. When the
- flag is set, the system delivers the signal for a terminated child
- process but not for one that is stopped. By default, ‘SIGCHLD’ is
- delivered for both terminated children and stopped children.
- Setting this flag for a signal other than ‘SIGCHLD’ has no effect.
- -- Macro: int SA_ONSTACK
- If this flag is set for a particular signal number, the system uses
- the signal stack when delivering that kind of signal. *Note Signal
- Stack::. If a signal with this flag arrives and you have not set a
- signal stack, the system terminates the program with ‘SIGILL’.
- -- Macro: int SA_RESTART
- This flag controls what happens when a signal is delivered during
- certain primitives (such as ‘open’, ‘read’ or ‘write’), and the
- signal handler returns normally. There are two alternatives: the
- library function can resume, or it can return failure with error
- code ‘EINTR’.
- The choice is controlled by the ‘SA_RESTART’ flag for the
- particular kind of signal that was delivered. If the flag is set,
- returning from a handler resumes the library function. If the flag
- is clear, returning from a handler makes the function fail. *Note
- Interrupted Primitives::.
- File: libc.info, Node: Initial Signal Actions, Prev: Flags for Sigaction, Up: Signal Actions
- 24.3.6 Initial Signal Actions
- -----------------------------
- When a new process is created (*note Creating a Process::), it inherits
- handling of signals from its parent process. However, when you load a
- new process image using the ‘exec’ function (*note Executing a File::),
- any signals that you’ve defined your own handlers for revert to their
- ‘SIG_DFL’ handling. (If you think about it a little, this makes sense;
- the handler functions from the old program are specific to that program,
- and aren’t even present in the address space of the new program image.)
- Of course, the new program can establish its own handlers.
- When a program is run by a shell, the shell normally sets the initial
- actions for the child process to ‘SIG_DFL’ or ‘SIG_IGN’, as appropriate.
- It’s a good idea to check to make sure that the shell has not set up an
- initial action of ‘SIG_IGN’ before you establish your own signal
- handlers.
- Here is an example of how to establish a handler for ‘SIGHUP’, but
- not if ‘SIGHUP’ is currently ignored:
- …
- struct sigaction temp;
- sigaction (SIGHUP, NULL, &temp);
- if (temp.sa_handler != SIG_IGN)
- {
- temp.sa_handler = handle_sighup;
- sigemptyset (&temp.sa_mask);
- sigaction (SIGHUP, &temp, NULL);
- }
- File: libc.info, Node: Defining Handlers, Next: Interrupted Primitives, Prev: Signal Actions, Up: Signal Handling
- 24.4 Defining Signal Handlers
- =============================
- This section describes how to write a signal handler function that can
- be established with the ‘signal’ or ‘sigaction’ functions.
- A signal handler is just a function that you compile together with
- the rest of the program. Instead of directly invoking the function, you
- use ‘signal’ or ‘sigaction’ to tell the operating system to call it when
- a signal arrives. This is known as "establishing" the handler. *Note
- Signal Actions::.
- There are two basic strategies you can use in signal handler
- functions:
- • You can have the handler function note that the signal arrived by
- tweaking some global data structures, and then return normally.
- • You can have the handler function terminate the program or transfer
- control to a point where it can recover from the situation that
- caused the signal.
- You need to take special care in writing handler functions because
- they can be called asynchronously. That is, a handler might be called
- at any point in the program, unpredictably. If two signals arrive
- during a very short interval, one handler can run within another. This
- section describes what your handler should do, and what you should
- avoid.
- * Menu:
- * Handler Returns:: Handlers that return normally, and what
- this means.
- * Termination in Handler:: How handler functions terminate a program.
- * Longjmp in Handler:: Nonlocal transfer of control out of a
- signal handler.
- * Signals in Handler:: What happens when signals arrive while
- the handler is already occupied.
- * Merged Signals:: When a second signal arrives before the
- first is handled.
- * Nonreentrancy:: Do not call any functions unless you know they
- are reentrant with respect to signals.
- * Atomic Data Access:: A single handler can run in the middle of
- reading or writing a single object.
- File: libc.info, Node: Handler Returns, Next: Termination in Handler, Up: Defining Handlers
- 24.4.1 Signal Handlers that Return
- ----------------------------------
- Handlers which return normally are usually used for signals such as
- ‘SIGALRM’ and the I/O and interprocess communication signals. But a
- handler for ‘SIGINT’ might also return normally after setting a flag
- that tells the program to exit at a convenient time.
- It is not safe to return normally from the handler for a program
- error signal, because the behavior of the program when the handler
- function returns is not defined after a program error. *Note Program
- Error Signals::.
- Handlers that return normally must modify some global variable in
- order to have any effect. Typically, the variable is one that is
- examined periodically by the program during normal operation. Its data
- type should be ‘sig_atomic_t’ for reasons described in *note Atomic Data
- Access::.
- Here is a simple example of such a program. It executes the body of
- the loop until it has noticed that a ‘SIGALRM’ signal has arrived. This
- technique is useful because it allows the iteration in progress when the
- signal arrives to complete before the loop exits.
- #include <signal.h>
- #include <stdio.h>
- #include <stdlib.h>
- /* This flag controls termination of the main loop. */
- volatile sig_atomic_t keep_going = 1;
- /* The signal handler just clears the flag and re-enables itself. */
- void
- catch_alarm (int sig)
- {
- keep_going = 0;
- signal (sig, catch_alarm);
- }
- void
- do_stuff (void)
- {
- puts ("Doing stuff while waiting for alarm....");
- }
- int
- main (void)
- {
- /* Establish a handler for SIGALRM signals. */
- signal (SIGALRM, catch_alarm);
- /* Set an alarm to go off in a little while. */
- alarm (2);
- /* Check the flag once in a while to see when to quit. */
- while (keep_going)
- do_stuff ();
- return EXIT_SUCCESS;
- }
- File: libc.info, Node: Termination in Handler, Next: Longjmp in Handler, Prev: Handler Returns, Up: Defining Handlers
- 24.4.2 Handlers That Terminate the Process
- ------------------------------------------
- Handler functions that terminate the program are typically used to cause
- orderly cleanup or recovery from program error signals and interactive
- interrupts.
- The cleanest way for a handler to terminate the process is to raise
- the same signal that ran the handler in the first place. Here is how to
- do this:
- volatile sig_atomic_t fatal_error_in_progress = 0;
- void
- fatal_error_signal (int sig)
- {
- /* Since this handler is established for more than one kind of signal,
- it might still get invoked recursively by delivery of some other kind
- of signal. Use a static variable to keep track of that. */
- if (fatal_error_in_progress)
- raise (sig);
- fatal_error_in_progress = 1;
- /* Now do the clean up actions:
- - reset terminal modes
- - kill child processes
- - remove lock files */
- …
- /* Now reraise the signal. We reactivate the signal’s
- default handling, which is to terminate the process.
- We could just call ‘exit’ or ‘abort’,
- but reraising the signal sets the return status
- from the process correctly. */
- signal (sig, SIG_DFL);
- raise (sig);
- }
- File: libc.info, Node: Longjmp in Handler, Next: Signals in Handler, Prev: Termination in Handler, Up: Defining Handlers
- 24.4.3 Nonlocal Control Transfer in Handlers
- --------------------------------------------
- You can do a nonlocal transfer of control out of a signal handler using
- the ‘setjmp’ and ‘longjmp’ facilities (*note Non-Local Exits::).
- When the handler does a nonlocal control transfer, the part of the
- program that was running will not continue. If this part of the program
- was in the middle of updating an important data structure, the data
- structure will remain inconsistent. Since the program does not
- terminate, the inconsistency is likely to be noticed later on.
- There are two ways to avoid this problem. One is to block the signal
- for the parts of the program that update important data structures.
- Blocking the signal delays its delivery until it is unblocked, once the
- critical updating is finished. *Note Blocking Signals::.
- The other way is to re-initialize the crucial data structures in the
- signal handler, or to make their values consistent.
- Here is a rather schematic example showing the reinitialization of
- one global variable.
- #include <signal.h>
- #include <setjmp.h>
- jmp_buf return_to_top_level;
- volatile sig_atomic_t waiting_for_input;
- void
- handle_sigint (int signum)
- {
- /* We may have been waiting for input when the signal arrived,
- but we are no longer waiting once we transfer control. */
- waiting_for_input = 0;
- longjmp (return_to_top_level, 1);
- }
- int
- main (void)
- {
- …
- signal (SIGINT, sigint_handler);
- …
- while (1) {
- prepare_for_command ();
- if (setjmp (return_to_top_level) == 0)
- read_and_execute_command ();
- }
- }
- /* Imagine this is a subroutine used by various commands. */
- char *
- read_data ()
- {
- if (input_from_terminal) {
- waiting_for_input = 1;
- …
- waiting_for_input = 0;
- } else {
- …
- }
- }
- File: libc.info, Node: Signals in Handler, Next: Merged Signals, Prev: Longjmp in Handler, Up: Defining Handlers
- 24.4.4 Signals Arriving While a Handler Runs
- --------------------------------------------
- What happens if another signal arrives while your signal handler
- function is running?
- When the handler for a particular signal is invoked, that signal is
- automatically blocked until the handler returns. That means that if two
- signals of the same kind arrive close together, the second one will be
- held until the first has been handled. (The handler can explicitly
- unblock the signal using ‘sigprocmask’, if you want to allow more
- signals of this type to arrive; see *note Process Signal Mask::.)
- However, your handler can still be interrupted by delivery of another
- kind of signal. To avoid this, you can use the ‘sa_mask’ member of the
- action structure passed to ‘sigaction’ to explicitly specify which
- signals should be blocked while the signal handler runs. These signals
- are in addition to the signal for which the handler was invoked, and any
- other signals that are normally blocked by the process. *Note Blocking
- for Handler::.
- When the handler returns, the set of blocked signals is restored to
- the value it had before the handler ran. So using ‘sigprocmask’ inside
- the handler only affects what signals can arrive during the execution of
- the handler itself, not what signals can arrive once the handler
- returns.
- *Portability Note:* Always use ‘sigaction’ to establish a handler for
- a signal that you expect to receive asynchronously, if you want your
- program to work properly on System V Unix. On this system, the handling
- of a signal whose handler was established with ‘signal’ automatically
- sets the signal’s action back to ‘SIG_DFL’, and the handler must
- re-establish itself each time it runs. This practice, while
- inconvenient, does work when signals cannot arrive in succession.
- However, if another signal can arrive right away, it may arrive before
- the handler can re-establish itself. Then the second signal would
- receive the default handling, which could terminate the process.
- File: libc.info, Node: Merged Signals, Next: Nonreentrancy, Prev: Signals in Handler, Up: Defining Handlers
- 24.4.5 Signals Close Together Merge into One
- --------------------------------------------
- If multiple signals of the same type are delivered to your process
- before your signal handler has a chance to be invoked at all, the
- handler may only be invoked once, as if only a single signal had
- arrived. In effect, the signals merge into one. This situation can
- arise when the signal is blocked, or in a multiprocessing environment
- where the system is busy running some other processes while the signals
- are delivered. This means, for example, that you cannot reliably use a
- signal handler to count signals. The only distinction you can reliably
- make is whether at least one signal has arrived since a given time in
- the past.
- Here is an example of a handler for ‘SIGCHLD’ that compensates for
- the fact that the number of signals received may not equal the number of
- child processes that generate them. It assumes that the program keeps
- track of all the child processes with a chain of structures as follows:
- struct process
- {
- struct process *next;
- /* The process ID of this child. */
- int pid;
- /* The descriptor of the pipe or pseudo terminal
- on which output comes from this child. */
- int input_descriptor;
- /* Nonzero if this process has stopped or terminated. */
- sig_atomic_t have_status;
- /* The status of this child; 0 if running,
- otherwise a status value from ‘waitpid’. */
- int status;
- };
- struct process *process_list;
- This example also uses a flag to indicate whether signals have
- arrived since some time in the past—whenever the program last cleared it
- to zero.
- /* Nonzero means some child’s status has changed
- so look at ‘process_list’ for the details. */
- int process_status_change;
- Here is the handler itself:
- void
- sigchld_handler (int signo)
- {
- int old_errno = errno;
- while (1) {
- register int pid;
- int w;
- struct process *p;
- /* Keep asking for a status until we get a definitive result. */
- do
- {
- errno = 0;
- pid = waitpid (WAIT_ANY, &w, WNOHANG | WUNTRACED);
- }
- while (pid <= 0 && errno == EINTR);
- if (pid <= 0) {
- /* A real failure means there are no more
- stopped or terminated child processes, so return. */
- errno = old_errno;
- return;
- }
- /* Find the process that signaled us, and record its status. */
- for (p = process_list; p; p = p->next)
- if (p->pid == pid) {
- p->status = w;
- /* Indicate that the ‘status’ field
- has data to look at. We do this only after storing it. */
- p->have_status = 1;
- /* If process has terminated, stop waiting for its output. */
- if (WIFSIGNALED (w) || WIFEXITED (w))
- if (p->input_descriptor)
- FD_CLR (p->input_descriptor, &input_wait_mask);
- /* The program should check this flag from time to time
- to see if there is any news in ‘process_list’. */
- ++process_status_change;
- }
- /* Loop around to handle all the processes
- that have something to tell us. */
- }
- }
- Here is the proper way to check the flag ‘process_status_change’:
- if (process_status_change) {
- struct process *p;
- process_status_change = 0;
- for (p = process_list; p; p = p->next)
- if (p->have_status) {
- … Examine ‘p->status’ …
- }
- }
- It is vital to clear the flag before examining the list; otherwise, if a
- signal were delivered just before the clearing of the flag, and after
- the appropriate element of the process list had been checked, the status
- change would go unnoticed until the next signal arrived to set the flag
- again. You could, of course, avoid this problem by blocking the signal
- while scanning the list, but it is much more elegant to guarantee
- correctness by doing things in the right order.
- The loop which checks process status avoids examining ‘p->status’
- until it sees that status has been validly stored. This is to make sure
- that the status cannot change in the middle of accessing it. Once
- ‘p->have_status’ is set, it means that the child process is stopped or
- terminated, and in either case, it cannot stop or terminate again until
- the program has taken notice. *Note Atomic Usage::, for more
- information about coping with interruptions during accesses of a
- variable.
- Here is another way you can test whether the handler has run since
- the last time you checked. This technique uses a counter which is never
- changed outside the handler. Instead of clearing the count, the program
- remembers the previous value and sees whether it has changed since the
- previous check. The advantage of this method is that different parts of
- the program can check independently, each part checking whether there
- has been a signal since that part last checked.
- sig_atomic_t process_status_change;
- sig_atomic_t last_process_status_change;
- …
- {
- sig_atomic_t prev = last_process_status_change;
- last_process_status_change = process_status_change;
- if (last_process_status_change != prev) {
- struct process *p;
- for (p = process_list; p; p = p->next)
- if (p->have_status) {
- … Examine ‘p->status’ …
- }
- }
- }
- File: libc.info, Node: Nonreentrancy, Next: Atomic Data Access, Prev: Merged Signals, Up: Defining Handlers
- 24.4.6 Signal Handling and Nonreentrant Functions
- -------------------------------------------------
- Handler functions usually don’t do very much. The best practice is to
- write a handler that does nothing but set an external variable that the
- program checks regularly, and leave all serious work to the program.
- This is best because the handler can be called asynchronously, at
- unpredictable times—perhaps in the middle of a primitive function, or
- even between the beginning and the end of a C operator that requires
- multiple instructions. The data structures being manipulated might
- therefore be in an inconsistent state when the handler function is
- invoked. Even copying one ‘int’ variable into another can take two
- instructions on most machines.
- This means you have to be very careful about what you do in a signal
- handler.
- • If your handler needs to access any global variables from your
- program, declare those variables ‘volatile’. This tells the
- compiler that the value of the variable might change
- asynchronously, and inhibits certain optimizations that would be
- invalidated by such modifications.
- • If you call a function in the handler, make sure it is "reentrant"
- with respect to signals, or else make sure that the signal cannot
- interrupt a call to a related function.
- A function can be non-reentrant if it uses memory that is not on the
- stack.
- • If a function uses a static variable or a global variable, or a
- dynamically-allocated object that it finds for itself, then it is
- non-reentrant and any two calls to the function can interfere.
- For example, suppose that the signal handler uses ‘gethostbyname’.
- This function returns its value in a static object, reusing the
- same object each time. If the signal happens to arrive during a
- call to ‘gethostbyname’, or even after one (while the program is
- still using the value), it will clobber the value that the program
- asked for.
- However, if the program does not use ‘gethostbyname’ or any other
- function that returns information in the same object, or if it
- always blocks signals around each use, then you are safe.
- There are a large number of library functions that return values in
- a fixed object, always reusing the same object in this fashion, and
- all of them cause the same problem. Function descriptions in this
- manual always mention this behavior.
- • If a function uses and modifies an object that you supply, then it
- is potentially non-reentrant; two calls can interfere if they use
- the same object.
- This case arises when you do I/O using streams. Suppose that the
- signal handler prints a message with ‘fprintf’. Suppose that the
- program was in the middle of an ‘fprintf’ call using the same
- stream when the signal was delivered. Both the signal handler’s
- message and the program’s data could be corrupted, because both
- calls operate on the same data structure—the stream itself.
- However, if you know that the stream that the handler uses cannot
- possibly be used by the program at a time when signals can arrive,
- then you are safe. It is no problem if the program uses some other
- stream.
- • On most systems, ‘malloc’ and ‘free’ are not reentrant, because
- they use a static data structure which records what memory blocks
- are free. As a result, no library functions that allocate or free
- memory are reentrant. This includes functions that allocate space
- to store a result.
- The best way to avoid the need to allocate memory in a handler is
- to allocate in advance space for signal handlers to use.
- The best way to avoid freeing memory in a handler is to flag or
- record the objects to be freed, and have the program check from
- time to time whether anything is waiting to be freed. But this
- must be done with care, because placing an object on a chain is not
- atomic, and if it is interrupted by another signal handler that
- does the same thing, you could “lose” one of the objects.
- • Any function that modifies ‘errno’ is non-reentrant, but you can
- correct for this: in the handler, save the original value of
- ‘errno’ and restore it before returning normally. This prevents
- errors that occur within the signal handler from being confused
- with errors from system calls at the point the program is
- interrupted to run the handler.
- This technique is generally applicable; if you want to call in a
- handler a function that modifies a particular object in memory, you
- can make this safe by saving and restoring that object.
- • Merely reading from a memory object is safe provided that you can
- deal with any of the values that might appear in the object at a
- time when the signal can be delivered. Keep in mind that
- assignment to some data types requires more than one instruction,
- which means that the handler could run “in the middle of” an
- assignment to the variable if its type is not atomic. *Note Atomic
- Data Access::.
- • Merely writing into a memory object is safe as long as a sudden
- change in the value, at any time when the handler might run, will
- not disturb anything.
- File: libc.info, Node: Atomic Data Access, Prev: Nonreentrancy, Up: Defining Handlers
- 24.4.7 Atomic Data Access and Signal Handling
- ---------------------------------------------
- Whether the data in your application concerns atoms, or mere text, you
- have to be careful about the fact that access to a single datum is not
- necessarily "atomic". This means that it can take more than one
- instruction to read or write a single object. In such cases, a signal
- handler might be invoked in the middle of reading or writing the object.
- There are three ways you can cope with this problem. You can use
- data types that are always accessed atomically; you can carefully
- arrange that nothing untoward happens if an access is interrupted, or
- you can block all signals around any access that had better not be
- interrupted (*note Blocking Signals::).
- * Menu:
- * Non-atomic Example:: A program illustrating interrupted access.
- * Types: Atomic Types. Data types that guarantee no interruption.
- * Usage: Atomic Usage. Proving that interruption is harmless.
- File: libc.info, Node: Non-atomic Example, Next: Atomic Types, Up: Atomic Data Access
- 24.4.7.1 Problems with Non-Atomic Access
- ........................................
- Here is an example which shows what can happen if a signal handler runs
- in the middle of modifying a variable. (Interrupting the reading of a
- variable can also lead to paradoxical results, but here we only show
- writing.)
- #include <signal.h>
- #include <stdio.h>
- volatile struct two_words { int a, b; } memory;
- void
- handler(int signum)
- {
- printf ("%d,%d\n", memory.a, memory.b);
- alarm (1);
- }
- int
- main (void)
- {
- static struct two_words zeros = { 0, 0 }, ones = { 1, 1 };
- signal (SIGALRM, handler);
- memory = zeros;
- alarm (1);
- while (1)
- {
- memory = zeros;
- memory = ones;
- }
- }
- This program fills ‘memory’ with zeros, ones, zeros, ones,
- alternating forever; meanwhile, once per second, the alarm signal
- handler prints the current contents. (Calling ‘printf’ in the handler
- is safe in this program because it is certainly not being called outside
- the handler when the signal happens.)
- Clearly, this program can print a pair of zeros or a pair of ones.
- But that’s not all it can do! On most machines, it takes several
- instructions to store a new value in ‘memory’, and the value is stored
- one word at a time. If the signal is delivered in between these
- instructions, the handler might find that ‘memory.a’ is zero and
- ‘memory.b’ is one (or vice versa).
- On some machines it may be possible to store a new value in ‘memory’
- with just one instruction that cannot be interrupted. On these
- machines, the handler will always print two zeros or two ones.
- File: libc.info, Node: Atomic Types, Next: Atomic Usage, Prev: Non-atomic Example, Up: Atomic Data Access
- 24.4.7.2 Atomic Types
- .....................
- To avoid uncertainty about interrupting access to a variable, you can
- use a particular data type for which access is always atomic:
- ‘sig_atomic_t’. Reading and writing this data type is guaranteed to
- happen in a single instruction, so there’s no way for a handler to run
- “in the middle” of an access.
- The type ‘sig_atomic_t’ is always an integer data type, but which one
- it is, and how many bits it contains, may vary from machine to machine.
- -- Data Type: sig_atomic_t
- This is an integer data type. Objects of this type are always
- accessed atomically.
- In practice, you can assume that ‘int’ is atomic. You can also
- assume that pointer types are atomic; that is very convenient. Both of
- these assumptions are true on all of the machines that the GNU C Library
- supports and on all POSIX systems we know of.
- File: libc.info, Node: Atomic Usage, Prev: Atomic Types, Up: Atomic Data Access
- 24.4.7.3 Atomic Usage Patterns
- ..............................
- Certain patterns of access avoid any problem even if an access is
- interrupted. For example, a flag which is set by the handler, and
- tested and cleared by the main program from time to time, is always safe
- even if access actually requires two instructions. To show that this is
- so, we must consider each access that could be interrupted, and show
- that there is no problem if it is interrupted.
- An interrupt in the middle of testing the flag is safe because either
- it’s recognized to be nonzero, in which case the precise value doesn’t
- matter, or it will be seen to be nonzero the next time it’s tested.
- An interrupt in the middle of clearing the flag is no problem because
- either the value ends up zero, which is what happens if a signal comes
- in just before the flag is cleared, or the value ends up nonzero, and
- subsequent events occur as if the signal had come in just after the flag
- was cleared. As long as the code handles both of these cases properly,
- it can also handle a signal in the middle of clearing the flag. (This
- is an example of the sort of reasoning you need to do to figure out
- whether non-atomic usage is safe.)
- Sometimes you can ensure uninterrupted access to one object by
- protecting its use with another object, perhaps one whose type
- guarantees atomicity. *Note Merged Signals::, for an example.
- File: libc.info, Node: Interrupted Primitives, Next: Generating Signals, Prev: Defining Handlers, Up: Signal Handling
- 24.5 Primitives Interrupted by Signals
- ======================================
- A signal can arrive and be handled while an I/O primitive such as ‘open’
- or ‘read’ is waiting for an I/O device. If the signal handler returns,
- the system faces the question: what should happen next?
- POSIX specifies one approach: make the primitive fail right away.
- The error code for this kind of failure is ‘EINTR’. This is flexible,
- but usually inconvenient. Typically, POSIX applications that use signal
- handlers must check for ‘EINTR’ after each library function that can
- return it, in order to try the call again. Often programmers forget to
- check, which is a common source of error.
- The GNU C Library provides a convenient way to retry a call after a
- temporary failure, with the macro ‘TEMP_FAILURE_RETRY’:
- -- Macro: TEMP_FAILURE_RETRY (EXPRESSION)
- This macro evaluates EXPRESSION once, and examines its value as
- type ‘long int’. If the value equals ‘-1’, that indicates a
- failure and ‘errno’ should be set to show what kind of failure. If
- it fails and reports error code ‘EINTR’, ‘TEMP_FAILURE_RETRY’
- evaluates it again, and over and over until the result is not a
- temporary failure.
- The value returned by ‘TEMP_FAILURE_RETRY’ is whatever value
- EXPRESSION produced.
- BSD avoids ‘EINTR’ entirely and provides a more convenient approach:
- to restart the interrupted primitive, instead of making it fail. If you
- choose this approach, you need not be concerned with ‘EINTR’.
- You can choose either approach with the GNU C Library. If you use
- ‘sigaction’ to establish a signal handler, you can specify how that
- handler should behave. If you specify the ‘SA_RESTART’ flag, return
- from that handler will resume a primitive; otherwise, return from that
- handler will cause ‘EINTR’. *Note Flags for Sigaction::.
- Another way to specify the choice is with the ‘siginterrupt’
- function. *Note BSD Signal Handling::.
- When you don’t specify with ‘sigaction’ or ‘siginterrupt’ what a
- particular handler should do, it uses a default choice. The default
- choice in the GNU C Library is to make primitives fail with ‘EINTR’.
- The description of each primitive affected by this issue lists
- ‘EINTR’ among the error codes it can return.
- There is one situation where resumption never happens no matter which
- choice you make: when a data-transfer function such as ‘read’ or ‘write’
- is interrupted by a signal after transferring part of the data. In this
- case, the function returns the number of bytes already transferred,
- indicating partial success.
- This might at first appear to cause unreliable behavior on
- record-oriented devices (including datagram sockets; *note Datagrams::),
- where splitting one ‘read’ or ‘write’ into two would read or write two
- records. Actually, there is no problem, because interruption after a
- partial transfer cannot happen on such devices; they always transfer an
- entire record in one burst, with no waiting once data transfer has
- started.
- File: libc.info, Node: Generating Signals, Next: Blocking Signals, Prev: Interrupted Primitives, Up: Signal Handling
- 24.6 Generating Signals
- =======================
- Besides signals that are generated as a result of a hardware trap or
- interrupt, your program can explicitly send signals to itself or to
- another process.
- * Menu:
- * Signaling Yourself:: A process can send a signal to itself.
- * Signaling Another Process:: Send a signal to another process.
- * Permission for kill:: Permission for using ‘kill’.
- * Kill Example:: Using ‘kill’ for Communication.
- File: libc.info, Node: Signaling Yourself, Next: Signaling Another Process, Up: Generating Signals
- 24.6.1 Signaling Yourself
- -------------------------
- A process can send itself a signal with the ‘raise’ function. This
- function is declared in ‘signal.h’.
- -- Function: int raise (int SIGNUM)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘raise’ function sends the signal SIGNUM to the calling
- process. It returns zero if successful and a nonzero value if it
- fails. About the only reason for failure would be if the value of
- SIGNUM is invalid.
- -- Function: int gsignal (int SIGNUM)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘gsignal’ function does the same thing as ‘raise’; it is
- provided only for compatibility with SVID.
- One convenient use for ‘raise’ is to reproduce the default behavior
- of a signal that you have trapped. For instance, suppose a user of your
- program types the SUSP character (usually ‘C-z’; *note Special
- Characters::) to send it an interactive stop signal (‘SIGTSTP’), and you
- want to clean up some internal data buffers before stopping. You might
- set this up like this:
- #include <signal.h>
- /* When a stop signal arrives, set the action back to the default
- and then resend the signal after doing cleanup actions. */
- void
- tstp_handler (int sig)
- {
- signal (SIGTSTP, SIG_DFL);
- /* Do cleanup actions here. */
- …
- raise (SIGTSTP);
- }
- /* When the process is continued again, restore the signal handler. */
- void
- cont_handler (int sig)
- {
- signal (SIGCONT, cont_handler);
- signal (SIGTSTP, tstp_handler);
- }
- /* Enable both handlers during program initialization. */
- int
- main (void)
- {
- signal (SIGCONT, cont_handler);
- signal (SIGTSTP, tstp_handler);
- …
- }
- *Portability note:* ‘raise’ was invented by the ISO C committee.
- Older systems may not support it, so using ‘kill’ may be more portable.
- *Note Signaling Another Process::.
- File: libc.info, Node: Signaling Another Process, Next: Permission for kill, Prev: Signaling Yourself, Up: Generating Signals
- 24.6.2 Signaling Another Process
- --------------------------------
- The ‘kill’ function can be used to send a signal to another process. In
- spite of its name, it can be used for a lot of things other than causing
- a process to terminate. Some examples of situations where you might
- want to send signals between processes are:
- • A parent process starts a child to perform a task—perhaps having
- the child running an infinite loop—and then terminates the child
- when the task is no longer needed.
- • A process executes as part of a group, and needs to terminate or
- notify the other processes in the group when an error or other
- event occurs.
- • Two processes need to synchronize while working together.
- This section assumes that you know a little bit about how processes
- work. For more information on this subject, see *note Processes::.
- The ‘kill’ function is declared in ‘signal.h’.
- -- Function: int kill (pid_t PID, int SIGNUM)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘kill’ function sends the signal SIGNUM to the process or
- process group specified by PID. Besides the signals listed in
- *note Standard Signals::, SIGNUM can also have a value of zero to
- check the validity of the PID.
- The PID specifies the process or process group to receive the
- signal:
- ‘PID > 0’
- The process whose identifier is PID.
- ‘PID == 0’
- All processes in the same process group as the sender.
- ‘PID < -1’
- The process group whose identifier is −PID.
- ‘PID == -1’
- If the process is privileged, send the signal to all processes
- except for some special system processes. Otherwise, send the
- signal to all processes with the same effective user ID.
- A process can send a signal to itself with a call like
- ‘kill (getpid(), SIGNUM)’. If ‘kill’ is used by a process to send
- a signal to itself, and the signal is not blocked, then ‘kill’
- delivers at least one signal (which might be some other pending
- unblocked signal instead of the signal SIGNUM) to that process
- before it returns.
- The return value from ‘kill’ is zero if the signal can be sent
- successfully. Otherwise, no signal is sent, and a value of ‘-1’ is
- returned. If PID specifies sending a signal to several processes,
- ‘kill’ succeeds if it can send the signal to at least one of them.
- There’s no way you can tell which of the processes got the signal
- or whether all of them did.
- The following ‘errno’ error conditions are defined for this
- function:
- ‘EINVAL’
- The SIGNUM argument is an invalid or unsupported number.
- ‘EPERM’
- You do not have the privilege to send a signal to the process
- or any of the processes in the process group named by PID.
- ‘ESRCH’
- The PID argument does not refer to an existing process or
- group.
- -- Function: int killpg (int PGID, int SIGNUM)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This is similar to ‘kill’, but sends signal SIGNUM to the process
- group PGID. This function is provided for compatibility with BSD;
- using ‘kill’ to do this is more portable.
- As a simple example of ‘kill’, the call ‘kill (getpid (), SIG)’ has
- the same effect as ‘raise (SIG)’.
- File: libc.info, Node: Permission for kill, Next: Kill Example, Prev: Signaling Another Process, Up: Generating Signals
- 24.6.3 Permission for using ‘kill’
- ----------------------------------
- There are restrictions that prevent you from using ‘kill’ to send
- signals to any random process. These are intended to prevent antisocial
- behavior such as arbitrarily killing off processes belonging to another
- user. In typical use, ‘kill’ is used to pass signals between parent,
- child, and sibling processes, and in these situations you normally do
- have permission to send signals. The only common exception is when you
- run a setuid program in a child process; if the program changes its real
- UID as well as its effective UID, you may not have permission to send a
- signal. The ‘su’ program does this.
- Whether a process has permission to send a signal to another process
- is determined by the user IDs of the two processes. This concept is
- discussed in detail in *note Process Persona::.
- Generally, for a process to be able to send a signal to another
- process, either the sending process must belong to a privileged user
- (like ‘root’), or the real or effective user ID of the sending process
- must match the real or effective user ID of the receiving process. If
- the receiving process has changed its effective user ID from the
- set-user-ID mode bit on its process image file, then the owner of the
- process image file is used in place of its current effective user ID. In
- some implementations, a parent process might be able to send signals to
- a child process even if the user ID’s don’t match, and other
- implementations might enforce other restrictions.
- The ‘SIGCONT’ signal is a special case. It can be sent if the sender
- is part of the same session as the receiver, regardless of user IDs.
- File: libc.info, Node: Kill Example, Prev: Permission for kill, Up: Generating Signals
- 24.6.4 Using ‘kill’ for Communication
- -------------------------------------
- Here is a longer example showing how signals can be used for
- interprocess communication. This is what the ‘SIGUSR1’ and ‘SIGUSR2’
- signals are provided for. Since these signals are fatal by default, the
- process that is supposed to receive them must trap them through ‘signal’
- or ‘sigaction’.
- In this example, a parent process forks a child process and then
- waits for the child to complete its initialization. The child process
- tells the parent when it is ready by sending it a ‘SIGUSR1’ signal,
- using the ‘kill’ function.
- #include <signal.h>
- #include <stdio.h>
- #include <sys/types.h>
- #include <unistd.h>
- /* When a ‘SIGUSR1’ signal arrives, set this variable. */
- volatile sig_atomic_t usr_interrupt = 0;
- void
- synch_signal (int sig)
- {
- usr_interrupt = 1;
- }
- /* The child process executes this function. */
- void
- child_function (void)
- {
- /* Perform initialization. */
- printf ("I'm here!!! My pid is %d.\n", (int) getpid ());
- /* Let parent know you’re done. */
- kill (getppid (), SIGUSR1);
- /* Continue with execution. */
- puts ("Bye, now....");
- exit (0);
- }
- int
- main (void)
- {
- struct sigaction usr_action;
- sigset_t block_mask;
- pid_t child_id;
- /* Establish the signal handler. */
- sigfillset (&block_mask);
- usr_action.sa_handler = synch_signal;
- usr_action.sa_mask = block_mask;
- usr_action.sa_flags = 0;
- sigaction (SIGUSR1, &usr_action, NULL);
- /* Create the child process. */
- child_id = fork ();
- if (child_id == 0)
- child_function (); /* Does not return. */
- /* Busy wait for the child to send a signal. */
- while (!usr_interrupt)
- ;
- /* Now continue execution. */
- puts ("That's all, folks!");
- return 0;
- }
- This example uses a busy wait, which is bad, because it wastes CPU
- cycles that other programs could otherwise use. It is better to ask the
- system to wait until the signal arrives. See the example in *note
- Waiting for a Signal::.
- File: libc.info, Node: Blocking Signals, Next: Waiting for a Signal, Prev: Generating Signals, Up: Signal Handling
- 24.7 Blocking Signals
- =====================
- Blocking a signal means telling the operating system to hold it and
- deliver it later. Generally, a program does not block signals
- indefinitely—it might as well ignore them by setting their actions to
- ‘SIG_IGN’. But it is useful to block signals briefly, to prevent them
- from interrupting sensitive operations. For instance:
- • You can use the ‘sigprocmask’ function to block signals while you
- modify global variables that are also modified by the handlers for
- these signals.
- • You can set ‘sa_mask’ in your ‘sigaction’ call to block certain
- signals while a particular signal handler runs. This way, the
- signal handler can run without being interrupted itself by signals.
- * Menu:
- * Why Block:: The purpose of blocking signals.
- * Signal Sets:: How to specify which signals to
- block.
- * Process Signal Mask:: Blocking delivery of signals to your
- process during normal execution.
- * Testing for Delivery:: Blocking to Test for Delivery of
- a Signal.
- * Blocking for Handler:: Blocking additional signals while a
- handler is being run.
- * Checking for Pending Signals:: Checking for Pending Signals
- * Remembering a Signal:: How you can get almost the same
- effect as blocking a signal, by
- handling it and setting a flag
- to be tested later.
- File: libc.info, Node: Why Block, Next: Signal Sets, Up: Blocking Signals
- 24.7.1 Why Blocking Signals is Useful
- -------------------------------------
- Temporary blocking of signals with ‘sigprocmask’ gives you a way to
- prevent interrupts during critical parts of your code. If signals
- arrive in that part of the program, they are delivered later, after you
- unblock them.
- One example where this is useful is for sharing data between a signal
- handler and the rest of the program. If the type of the data is not
- ‘sig_atomic_t’ (*note Atomic Data Access::), then the signal handler
- could run when the rest of the program has only half finished reading or
- writing the data. This would lead to confusing consequences.
- To make the program reliable, you can prevent the signal handler from
- running while the rest of the program is examining or modifying that
- data—by blocking the appropriate signal around the parts of the program
- that touch the data.
- Blocking signals is also necessary when you want to perform a certain
- action only if a signal has not arrived. Suppose that the handler for
- the signal sets a flag of type ‘sig_atomic_t’; you would like to test
- the flag and perform the action if the flag is not set. This is
- unreliable. Suppose the signal is delivered immediately after you test
- the flag, but before the consequent action: then the program will
- perform the action even though the signal has arrived.
- The only way to test reliably for whether a signal has yet arrived is
- to test while the signal is blocked.
- File: libc.info, Node: Signal Sets, Next: Process Signal Mask, Prev: Why Block, Up: Blocking Signals
- 24.7.2 Signal Sets
- ------------------
- All of the signal blocking functions use a data structure called a
- "signal set" to specify what signals are affected. Thus, every activity
- involves two stages: creating the signal set, and then passing it as an
- argument to a library function.
- These facilities are declared in the header file ‘signal.h’.
- -- Data Type: sigset_t
- The ‘sigset_t’ data type is used to represent a signal set.
- Internally, it may be implemented as either an integer or structure
- type.
- For portability, use only the functions described in this section
- to initialize, change, and retrieve information from ‘sigset_t’
- objects—don’t try to manipulate them directly.
- There are two ways to initialize a signal set. You can initially
- specify it to be empty with ‘sigemptyset’ and then add specified signals
- individually. Or you can specify it to be full with ‘sigfillset’ and
- then delete specified signals individually.
- You must always initialize the signal set with one of these two
- functions before using it in any other way. Don’t try to set all the
- signals explicitly because the ‘sigset_t’ object might include some
- other information (like a version field) that needs to be initialized as
- well. (In addition, it’s not wise to put into your program an
- assumption that the system has no signals aside from the ones you know
- about.)
- -- Function: int sigemptyset (sigset_t *SET)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function initializes the signal set SET to exclude all of the
- defined signals. It always returns ‘0’.
- -- Function: int sigfillset (sigset_t *SET)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function initializes the signal set SET to include all of the
- defined signals. Again, the return value is ‘0’.
- -- Function: int sigaddset (sigset_t *SET, int SIGNUM)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function adds the signal SIGNUM to the signal set SET. All
- ‘sigaddset’ does is modify SET; it does not block or unblock any
- signals.
- The return value is ‘0’ on success and ‘-1’ on failure. The
- following ‘errno’ error condition is defined for this function:
- ‘EINVAL’
- The SIGNUM argument doesn’t specify a valid signal.
- -- Function: int sigdelset (sigset_t *SET, int SIGNUM)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function removes the signal SIGNUM from the signal set SET.
- All ‘sigdelset’ does is modify SET; it does not block or unblock
- any signals. The return value and error conditions are the same as
- for ‘sigaddset’.
- Finally, there is a function to test what signals are in a signal
- set:
- -- Function: int sigismember (const sigset_t *SET, int SIGNUM)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘sigismember’ function tests whether the signal SIGNUM is a
- member of the signal set SET. It returns ‘1’ if the signal is in
- the set, ‘0’ if not, and ‘-1’ if there is an error.
- The following ‘errno’ error condition is defined for this function:
- ‘EINVAL’
- The SIGNUM argument doesn’t specify a valid signal.
- File: libc.info, Node: Process Signal Mask, Next: Testing for Delivery, Prev: Signal Sets, Up: Blocking Signals
- 24.7.3 Process Signal Mask
- --------------------------
- The collection of signals that are currently blocked is called the
- "signal mask". Each process has its own signal mask. When you create a
- new process (*note Creating a Process::), it inherits its parent’s mask.
- You can block or unblock signals with total flexibility by modifying the
- signal mask.
- The prototype for the ‘sigprocmask’ function is in ‘signal.h’.
- Note that you must not use ‘sigprocmask’ in multi-threaded processes,
- because each thread has its own signal mask and there is no single
- process signal mask. According to POSIX, the behavior of ‘sigprocmask’
- in a multi-threaded process is “unspecified”. Instead, use
- ‘pthread_sigmask’.
- -- Function: int sigprocmask (int HOW, const sigset_t *restrict SET,
- sigset_t *restrict OLDSET)
- Preliminary: | MT-Unsafe race:sigprocmask/bsd(SIG_UNBLOCK) |
- AS-Unsafe lock/hurd | AC-Unsafe lock/hurd | *Note POSIX Safety
- Concepts::.
- The ‘sigprocmask’ function is used to examine or change the calling
- process’s signal mask. The HOW argument determines how the signal
- mask is changed, and must be one of the following values:
- ‘SIG_BLOCK’
- Block the signals in ‘set’—add them to the existing mask. In
- other words, the new mask is the union of the existing mask
- and SET.
- ‘SIG_UNBLOCK’
- Unblock the signals in SET—remove them from the existing mask.
- ‘SIG_SETMASK’
- Use SET for the mask; ignore the previous value of the mask.
- The last argument, OLDSET, is used to return information about the
- old process signal mask. If you just want to change the mask
- without looking at it, pass a null pointer as the OLDSET argument.
- Similarly, if you want to know what’s in the mask without changing
- it, pass a null pointer for SET (in this case the HOW argument is
- not significant). The OLDSET argument is often used to remember
- the previous signal mask in order to restore it later. (Since the
- signal mask is inherited over ‘fork’ and ‘exec’ calls, you can’t
- predict what its contents are when your program starts running.)
- If invoking ‘sigprocmask’ causes any pending signals to be
- unblocked, at least one of those signals is delivered to the
- process before ‘sigprocmask’ returns. The order in which pending
- signals are delivered is not specified, but you can control the
- order explicitly by making multiple ‘sigprocmask’ calls to unblock
- various signals one at a time.
- The ‘sigprocmask’ function returns ‘0’ if successful, and ‘-1’ to
- indicate an error. The following ‘errno’ error conditions are
- defined for this function:
- ‘EINVAL’
- The HOW argument is invalid.
- You can’t block the ‘SIGKILL’ and ‘SIGSTOP’ signals, but if the
- signal set includes these, ‘sigprocmask’ just ignores them instead
- of returning an error status.
- Remember, too, that blocking program error signals such as ‘SIGFPE’
- leads to undesirable results for signals generated by an actual
- program error (as opposed to signals sent with ‘raise’ or ‘kill’).
- This is because your program may be too broken to be able to
- continue executing to a point where the signal is unblocked again.
- *Note Program Error Signals::.
- File: libc.info, Node: Testing for Delivery, Next: Blocking for Handler, Prev: Process Signal Mask, Up: Blocking Signals
- 24.7.4 Blocking to Test for Delivery of a Signal
- ------------------------------------------------
- Now for a simple example. Suppose you establish a handler for ‘SIGALRM’
- signals that sets a flag whenever a signal arrives, and your main
- program checks this flag from time to time and then resets it. You can
- prevent additional ‘SIGALRM’ signals from arriving in the meantime by
- wrapping the critical part of the code with calls to ‘sigprocmask’, like
- this:
- /* This variable is set by the SIGALRM signal handler. */
- volatile sig_atomic_t flag = 0;
- int
- main (void)
- {
- sigset_t block_alarm;
- …
- /* Initialize the signal mask. */
- sigemptyset (&block_alarm);
- sigaddset (&block_alarm, SIGALRM);
- while (1)
- {
- /* Check if a signal has arrived; if so, reset the flag. */
- sigprocmask (SIG_BLOCK, &block_alarm, NULL);
- if (flag)
- {
- ACTIONS-IF-NOT-ARRIVED
- flag = 0;
- }
- sigprocmask (SIG_UNBLOCK, &block_alarm, NULL);
- …
- }
- }
- File: libc.info, Node: Blocking for Handler, Next: Checking for Pending Signals, Prev: Testing for Delivery, Up: Blocking Signals
- 24.7.5 Blocking Signals for a Handler
- -------------------------------------
- When a signal handler is invoked, you usually want it to be able to
- finish without being interrupted by another signal. From the moment the
- handler starts until the moment it finishes, you must block signals that
- might confuse it or corrupt its data.
- When a handler function is invoked on a signal, that signal is
- automatically blocked (in addition to any other signals that are already
- in the process’s signal mask) during the time the handler is running.
- If you set up a handler for ‘SIGTSTP’, for instance, then the arrival of
- that signal forces further ‘SIGTSTP’ signals to wait during the
- execution of the handler.
- However, by default, other kinds of signals are not blocked; they can
- arrive during handler execution.
- The reliable way to block other kinds of signals during the execution
- of the handler is to use the ‘sa_mask’ member of the ‘sigaction’
- structure.
- Here is an example:
- #include <signal.h>
- #include <stddef.h>
- void catch_stop ();
- void
- install_handler (void)
- {
- struct sigaction setup_action;
- sigset_t block_mask;
- sigemptyset (&block_mask);
- /* Block other terminal-generated signals while handler runs. */
- sigaddset (&block_mask, SIGINT);
- sigaddset (&block_mask, SIGQUIT);
- setup_action.sa_handler = catch_stop;
- setup_action.sa_mask = block_mask;
- setup_action.sa_flags = 0;
- sigaction (SIGTSTP, &setup_action, NULL);
- }
- This is more reliable than blocking the other signals explicitly in
- the code for the handler. If you block signals explicitly in the
- handler, you can’t avoid at least a short interval at the beginning of
- the handler where they are not yet blocked.
- You cannot remove signals from the process’s current mask using this
- mechanism. However, you can make calls to ‘sigprocmask’ within your
- handler to block or unblock signals as you wish.
- In any case, when the handler returns, the system restores the mask
- that was in place before the handler was entered. If any signals that
- become unblocked by this restoration are pending, the process will
- receive those signals immediately, before returning to the code that was
- interrupted.
- File: libc.info, Node: Checking for Pending Signals, Next: Remembering a Signal, Prev: Blocking for Handler, Up: Blocking Signals
- 24.7.6 Checking for Pending Signals
- -----------------------------------
- You can find out which signals are pending at any time by calling
- ‘sigpending’. This function is declared in ‘signal.h’.
- -- Function: int sigpending (sigset_t *SET)
- Preliminary: | MT-Safe | AS-Unsafe lock/hurd | AC-Unsafe lock/hurd
- | *Note POSIX Safety Concepts::.
- The ‘sigpending’ function stores information about pending signals
- in SET. If there is a pending signal that is blocked from
- delivery, then that signal is a member of the returned set. (You
- can test whether a particular signal is a member of this set using
- ‘sigismember’; see *note Signal Sets::.)
- The return value is ‘0’ if successful, and ‘-1’ on failure.
- Testing whether a signal is pending is not often useful. Testing
- when that signal is not blocked is almost certainly bad design.
- Here is an example.
- #include <signal.h>
- #include <stddef.h>
- sigset_t base_mask, waiting_mask;
- sigemptyset (&base_mask);
- sigaddset (&base_mask, SIGINT);
- sigaddset (&base_mask, SIGTSTP);
- /* Block user interrupts while doing other processing. */
- sigprocmask (SIG_SETMASK, &base_mask, NULL);
- …
- /* After a while, check to see whether any signals are pending. */
- sigpending (&waiting_mask);
- if (sigismember (&waiting_mask, SIGINT)) {
- /* User has tried to kill the process. */
- }
- else if (sigismember (&waiting_mask, SIGTSTP)) {
- /* User has tried to stop the process. */
- }
- Remember that if there is a particular signal pending for your
- process, additional signals of that same type that arrive in the
- meantime might be discarded. For example, if a ‘SIGINT’ signal is
- pending when another ‘SIGINT’ signal arrives, your program will probably
- only see one of them when you unblock this signal.
- *Portability Note:* The ‘sigpending’ function is new in POSIX.1.
- Older systems have no equivalent facility.
- File: libc.info, Node: Remembering a Signal, Prev: Checking for Pending Signals, Up: Blocking Signals
- 24.7.7 Remembering a Signal to Act On Later
- -------------------------------------------
- Instead of blocking a signal using the library facilities, you can get
- almost the same results by making the handler set a flag to be tested
- later, when you “unblock”. Here is an example:
- /* If this flag is nonzero, don’t handle the signal right away. */
- volatile sig_atomic_t signal_pending;
- /* This is nonzero if a signal arrived and was not handled. */
- volatile sig_atomic_t defer_signal;
- void
- handler (int signum)
- {
- if (defer_signal)
- signal_pending = signum;
- else
- … /* “Really” handle the signal. */
- }
- …
- void
- update_mumble (int frob)
- {
- /* Prevent signals from having immediate effect. */
- defer_signal++;
- /* Now update ‘mumble’, without worrying about interruption. */
- mumble.a = 1;
- mumble.b = hack ();
- mumble.c = frob;
- /* We have updated ‘mumble’. Handle any signal that came in. */
- defer_signal--;
- if (defer_signal == 0 && signal_pending != 0)
- raise (signal_pending);
- }
- Note how the particular signal that arrives is stored in
- ‘signal_pending’. That way, we can handle several types of inconvenient
- signals with the same mechanism.
- We increment and decrement ‘defer_signal’ so that nested critical
- sections will work properly; thus, if ‘update_mumble’ were called with
- ‘signal_pending’ already nonzero, signals would be deferred not only
- within ‘update_mumble’, but also within the caller. This is also why we
- do not check ‘signal_pending’ if ‘defer_signal’ is still nonzero.
- The incrementing and decrementing of ‘defer_signal’ each require more
- than one instruction; it is possible for a signal to happen in the
- middle. But that does not cause any problem. If the signal happens
- early enough to see the value from before the increment or decrement,
- that is equivalent to a signal which came before the beginning of the
- increment or decrement, which is a case that works properly.
- It is absolutely vital to decrement ‘defer_signal’ before testing
- ‘signal_pending’, because this avoids a subtle bug. If we did these
- things in the other order, like this,
- if (defer_signal == 1 && signal_pending != 0)
- raise (signal_pending);
- defer_signal--;
- then a signal arriving in between the ‘if’ statement and the decrement
- would be effectively “lost” for an indefinite amount of time. The
- handler would merely set ‘defer_signal’, but the program having already
- tested this variable, it would not test the variable again.
- Bugs like these are called "timing errors". They are especially bad
- because they happen only rarely and are nearly impossible to reproduce.
- You can’t expect to find them with a debugger as you would find a
- reproducible bug. So it is worth being especially careful to avoid
- them.
- (You would not be tempted to write the code in this order, given the
- use of ‘defer_signal’ as a counter which must be tested along with
- ‘signal_pending’. After all, testing for zero is cleaner than testing
- for one. But if you did not use ‘defer_signal’ as a counter, and gave
- it values of zero and one only, then either order might seem equally
- simple. This is a further advantage of using a counter for
- ‘defer_signal’: it will reduce the chance you will write the code in the
- wrong order and create a subtle bug.)
- File: libc.info, Node: Waiting for a Signal, Next: Signal Stack, Prev: Blocking Signals, Up: Signal Handling
- 24.8 Waiting for a Signal
- =========================
- If your program is driven by external events, or uses signals for
- synchronization, then when it has nothing to do it should probably wait
- until a signal arrives.
- * Menu:
- * Using Pause:: The simple way, using ‘pause’.
- * Pause Problems:: Why the simple way is often not very good.
- * Sigsuspend:: Reliably waiting for a specific signal.
- File: libc.info, Node: Using Pause, Next: Pause Problems, Up: Waiting for a Signal
- 24.8.1 Using ‘pause’
- --------------------
- The simple way to wait until a signal arrives is to call ‘pause’.
- Please read about its disadvantages, in the following section, before
- you use it.
- -- Function: int pause (void)
- Preliminary: | MT-Unsafe race:sigprocmask/!bsd!linux | AS-Unsafe
- lock/hurd | AC-Unsafe lock/hurd | *Note POSIX Safety Concepts::.
- The ‘pause’ function suspends program execution until a signal
- arrives whose action is either to execute a handler function, or to
- terminate the process.
- If the signal causes a handler function to be executed, then
- ‘pause’ returns. This is considered an unsuccessful return (since
- “successful” behavior would be to suspend the program forever), so
- the return value is ‘-1’. Even if you specify that other
- primitives should resume when a system handler returns (*note
- Interrupted Primitives::), this has no effect on ‘pause’; it always
- fails when a signal is handled.
- The following ‘errno’ error conditions are defined for this
- function:
- ‘EINTR’
- The function was interrupted by delivery of a signal.
- If the signal causes program termination, ‘pause’ doesn’t return
- (obviously).
- This function is a cancellation point in multithreaded programs.
- This is a problem if the thread allocates some resources (like
- memory, file descriptors, semaphores or whatever) at the time
- ‘pause’ is called. If the thread gets cancelled these resources
- stay allocated until the program ends. To avoid this calls to
- ‘pause’ should be protected using cancellation handlers.
- The ‘pause’ function is declared in ‘unistd.h’.
- File: libc.info, Node: Pause Problems, Next: Sigsuspend, Prev: Using Pause, Up: Waiting for a Signal
- 24.8.2 Problems with ‘pause’
- ----------------------------
- The simplicity of ‘pause’ can conceal serious timing errors that can
- make a program hang mysteriously.
- It is safe to use ‘pause’ if the real work of your program is done by
- the signal handlers themselves, and the “main program” does nothing but
- call ‘pause’. Each time a signal is delivered, the handler will do the
- next batch of work that is to be done, and then return, so that the main
- loop of the program can call ‘pause’ again.
- You can’t safely use ‘pause’ to wait until one more signal arrives,
- and then resume real work. Even if you arrange for the signal handler
- to cooperate by setting a flag, you still can’t use ‘pause’ reliably.
- Here is an example of this problem:
- /* ‘usr_interrupt’ is set by the signal handler. */
- if (!usr_interrupt)
- pause ();
- /* Do work once the signal arrives. */
- …
- This has a bug: the signal could arrive after the variable
- ‘usr_interrupt’ is checked, but before the call to ‘pause’. If no
- further signals arrive, the process would never wake up again.
- You can put an upper limit on the excess waiting by using ‘sleep’ in
- a loop, instead of using ‘pause’. (*Note Sleeping::, for more about
- ‘sleep’.) Here is what this looks like:
- /* ‘usr_interrupt’ is set by the signal handler.
- while (!usr_interrupt)
- sleep (1);
- /* Do work once the signal arrives. */
- …
- For some purposes, that is good enough. But with a little more
- complexity, you can wait reliably until a particular signal handler is
- run, using ‘sigsuspend’. *Note Sigsuspend::.
- File: libc.info, Node: Sigsuspend, Prev: Pause Problems, Up: Waiting for a Signal
- 24.8.3 Using ‘sigsuspend’
- -------------------------
- The clean and reliable way to wait for a signal to arrive is to block it
- and then use ‘sigsuspend’. By using ‘sigsuspend’ in a loop, you can
- wait for certain kinds of signals, while letting other kinds of signals
- be handled by their handlers.
- -- Function: int sigsuspend (const sigset_t *SET)
- Preliminary: | MT-Unsafe race:sigprocmask/!bsd!linux | AS-Unsafe
- lock/hurd | AC-Unsafe lock/hurd | *Note POSIX Safety Concepts::.
- This function replaces the process’s signal mask with SET and then
- suspends the process until a signal is delivered whose action is
- either to terminate the process or invoke a signal handling
- function. In other words, the program is effectively suspended
- until one of the signals that is not a member of SET arrives.
- If the process is woken up by delivery of a signal that invokes a
- handler function, and the handler function returns, then
- ‘sigsuspend’ also returns.
- The mask remains SET only as long as ‘sigsuspend’ is waiting. The
- function ‘sigsuspend’ always restores the previous signal mask when
- it returns.
- The return value and error conditions are the same as for ‘pause’.
- With ‘sigsuspend’, you can replace the ‘pause’ or ‘sleep’ loop in the
- previous section with something completely reliable:
- sigset_t mask, oldmask;
- …
- /* Set up the mask of signals to temporarily block. */
- sigemptyset (&mask);
- sigaddset (&mask, SIGUSR1);
- …
- /* Wait for a signal to arrive. */
- sigprocmask (SIG_BLOCK, &mask, &oldmask);
- while (!usr_interrupt)
- sigsuspend (&oldmask);
- sigprocmask (SIG_UNBLOCK, &mask, NULL);
- This last piece of code is a little tricky. The key point to
- remember here is that when ‘sigsuspend’ returns, it resets the process’s
- signal mask to the original value, the value from before the call to
- ‘sigsuspend’—in this case, the ‘SIGUSR1’ signal is once again blocked.
- The second call to ‘sigprocmask’ is necessary to explicitly unblock this
- signal.
- One other point: you may be wondering why the ‘while’ loop is
- necessary at all, since the program is apparently only waiting for one
- ‘SIGUSR1’ signal. The answer is that the mask passed to ‘sigsuspend’
- permits the process to be woken up by the delivery of other kinds of
- signals, as well—for example, job control signals. If the process is
- woken up by a signal that doesn’t set ‘usr_interrupt’, it just suspends
- itself again until the “right” kind of signal eventually arrives.
- This technique takes a few more lines of preparation, but that is
- needed just once for each kind of wait criterion you want to use. The
- code that actually waits is just four lines.
- File: libc.info, Node: Signal Stack, Next: BSD Signal Handling, Prev: Waiting for a Signal, Up: Signal Handling
- 24.9 Using a Separate Signal Stack
- ==================================
- A signal stack is a special area of memory to be used as the execution
- stack during signal handlers. It should be fairly large, to avoid any
- danger that it will overflow in turn; the macro ‘SIGSTKSZ’ is defined to
- a canonical size for signal stacks. You can use ‘malloc’ to allocate
- the space for the stack. Then call ‘sigaltstack’ or ‘sigstack’ to tell
- the system to use that space for the signal stack.
- You don’t need to write signal handlers differently in order to use a
- signal stack. Switching from one stack to the other happens
- automatically. (Some non-GNU debuggers on some machines may get
- confused if you examine a stack trace while a handler that uses the
- signal stack is running.)
- There are two interfaces for telling the system to use a separate
- signal stack. ‘sigstack’ is the older interface, which comes from 4.2
- BSD. ‘sigaltstack’ is the newer interface, and comes from 4.4 BSD. The
- ‘sigaltstack’ interface has the advantage that it does not require your
- program to know which direction the stack grows, which depends on the
- specific machine and operating system.
- -- Data Type: stack_t
- This structure describes a signal stack. It contains the following
- members:
- ‘void *ss_sp’
- This points to the base of the signal stack.
- ‘size_t ss_size’
- This is the size (in bytes) of the signal stack which ‘ss_sp’
- points to. You should set this to however much space you
- allocated for the stack.
- There are two macros defined in ‘signal.h’ that you should use
- in calculating this size:
- ‘SIGSTKSZ’
- This is the canonical size for a signal stack. It is
- judged to be sufficient for normal uses.
- ‘MINSIGSTKSZ’
- This is the amount of signal stack space the operating
- system needs just to implement signal delivery. The size
- of a signal stack *must* be greater than this.
- For most cases, just using ‘SIGSTKSZ’ for ‘ss_size’ is
- sufficient. But if you know how much stack space your
- program’s signal handlers will need, you may want to use
- a different size. In this case, you should allocate
- ‘MINSIGSTKSZ’ additional bytes for the signal stack and
- increase ‘ss_size’ accordingly.
- ‘int ss_flags’
- This field contains the bitwise OR of these flags:
- ‘SS_DISABLE’
- This tells the system that it should not use the signal
- stack.
- ‘SS_ONSTACK’
- This is set by the system, and indicates that the signal
- stack is currently in use. If this bit is not set, then
- signals will be delivered on the normal user stack.
- -- Function: int sigaltstack (const stack_t *restrict STACK, stack_t
- *restrict OLDSTACK)
- Preliminary: | MT-Safe | AS-Unsafe lock/hurd | AC-Unsafe lock/hurd
- | *Note POSIX Safety Concepts::.
- The ‘sigaltstack’ function specifies an alternate stack for use
- during signal handling. When a signal is received by the process
- and its action indicates that the signal stack is used, the system
- arranges a switch to the currently installed signal stack while the
- handler for that signal is executed.
- If OLDSTACK is not a null pointer, information about the currently
- installed signal stack is returned in the location it points to.
- If STACK is not a null pointer, then this is installed as the new
- stack for use by signal handlers.
- The return value is ‘0’ on success and ‘-1’ on failure. If
- ‘sigaltstack’ fails, it sets ‘errno’ to one of these values:
- ‘EINVAL’
- You tried to disable a stack that was in fact currently in
- use.
- ‘ENOMEM’
- The size of the alternate stack was too small. It must be
- greater than ‘MINSIGSTKSZ’.
- Here is the older ‘sigstack’ interface. You should use ‘sigaltstack’
- instead on systems that have it.
- -- Data Type: struct sigstack
- This structure describes a signal stack. It contains the following
- members:
- ‘void *ss_sp’
- This is the stack pointer. If the stack grows downwards on
- your machine, this should point to the top of the area you
- allocated. If the stack grows upwards, it should point to the
- bottom.
- ‘int ss_onstack’
- This field is true if the process is currently using this
- stack.
- -- Function: int sigstack (struct sigstack *STACK, struct sigstack
- *OLDSTACK)
- Preliminary: | MT-Safe | AS-Unsafe lock/hurd | AC-Unsafe lock/hurd
- | *Note POSIX Safety Concepts::.
- The ‘sigstack’ function specifies an alternate stack for use during
- signal handling. When a signal is received by the process and its
- action indicates that the signal stack is used, the system arranges
- a switch to the currently installed signal stack while the handler
- for that signal is executed.
- If OLDSTACK is not a null pointer, information about the currently
- installed signal stack is returned in the location it points to.
- If STACK is not a null pointer, then this is installed as the new
- stack for use by signal handlers.
- The return value is ‘0’ on success and ‘-1’ on failure.
- File: libc.info, Node: BSD Signal Handling, Prev: Signal Stack, Up: Signal Handling
- 24.10 BSD Signal Handling
- =========================
- This section describes alternative signal handling functions derived
- from BSD Unix. These facilities were an advance, in their time; today,
- they are mostly obsolete, and supported mainly for compatibility with
- BSD Unix.
- There are many similarities between the BSD and POSIX signal handling
- facilities, because the POSIX facilities were inspired by the BSD
- facilities. Besides having different names for all the functions to
- avoid conflicts, the main difference between the two is that BSD Unix
- represents signal masks as an ‘int’ bit mask, rather than as a
- ‘sigset_t’ object.
- The BSD facilities are declared in ‘signal.h’.
- -- Function: int siginterrupt (int SIGNUM, int FAILFLAG)
- Preliminary: | MT-Unsafe const:sigintr | AS-Unsafe | AC-Unsafe
- corrupt | *Note POSIX Safety Concepts::.
- This function specifies which approach to use when certain
- primitives are interrupted by handling signal SIGNUM. If FAILFLAG
- is false, signal SIGNUM restarts primitives. If FAILFLAG is true,
- handling SIGNUM causes these primitives to fail with error code
- ‘EINTR’. *Note Interrupted Primitives::.
- -- Macro: int sigmask (int SIGNUM)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This macro returns a signal mask that has the bit for signal SIGNUM
- set. You can bitwise-OR the results of several calls to ‘sigmask’
- together to specify more than one signal. For example,
- (sigmask (SIGTSTP) | sigmask (SIGSTOP)
- | sigmask (SIGTTIN) | sigmask (SIGTTOU))
- specifies a mask that includes all the job-control stop signals.
- -- Function: int sigblock (int MASK)
- Preliminary: | MT-Safe | AS-Unsafe lock/hurd | AC-Unsafe lock/hurd
- | *Note POSIX Safety Concepts::.
- This function is equivalent to ‘sigprocmask’ (*note Process Signal
- Mask::) with a HOW argument of ‘SIG_BLOCK’: it adds the signals
- specified by MASK to the calling process’s set of blocked signals.
- The return value is the previous set of blocked signals.
- -- Function: int sigsetmask (int MASK)
- Preliminary: | MT-Safe | AS-Unsafe lock/hurd | AC-Unsafe lock/hurd
- | *Note POSIX Safety Concepts::.
- This function is equivalent to ‘sigprocmask’ (*note Process Signal
- Mask::) with a HOW argument of ‘SIG_SETMASK’: it sets the calling
- process’s signal mask to MASK. The return value is the previous
- set of blocked signals.
- -- Function: int sigpause (int MASK)
- Preliminary: | MT-Unsafe race:sigprocmask/!bsd!linux | AS-Unsafe
- lock/hurd | AC-Unsafe lock/hurd | *Note POSIX Safety Concepts::.
- This function is the equivalent of ‘sigsuspend’ (*note Waiting for
- a Signal::): it sets the calling process’s signal mask to MASK, and
- waits for a signal to arrive. On return the previous set of
- blocked signals is restored.
- File: libc.info, Node: Program Basics, Next: Processes, Prev: Signal Handling, Up: Top
- 25 The Basic Program/System Interface
- *************************************
- "Processes" are the primitive units for allocation of system resources.
- Each process has its own address space and (usually) one thread of
- control. A process executes a program; you can have multiple processes
- executing the same program, but each process has its own copy of the
- program within its own address space and executes it independently of
- the other copies. Though it may have multiple threads of control within
- the same program and a program may be composed of multiple logically
- separate modules, a process always executes exactly one program.
- Note that we are using a specific definition of “program” for the
- purposes of this manual, which corresponds to a common definition in the
- context of Unix systems. In popular usage, “program” enjoys a much
- broader definition; it can refer for example to a system’s kernel, an
- editor macro, a complex package of software, or a discrete section of
- code executing within a process.
- Writing the program is what this manual is all about. This chapter
- explains the most basic interface between your program and the system
- that runs, or calls, it. This includes passing of parameters (arguments
- and environment) from the system, requesting basic services from the
- system, and telling the system the program is done.
- A program starts another program with the ‘exec’ family of system
- calls. This chapter looks at program startup from the execee’s point of
- view. To see the event from the execor’s point of view, see *note
- Executing a File::.
- * Menu:
- * Program Arguments:: Parsing your program’s command-line arguments
- * Environment Variables:: Less direct parameters affecting your program
- * Auxiliary Vector:: Least direct parameters affecting your program
- * System Calls:: Requesting service from the system
- * Program Termination:: Telling the system you’re done; return status
- File: libc.info, Node: Program Arguments, Next: Environment Variables, Up: Program Basics
- 25.1 Program Arguments
- ======================
- The system starts a C program by calling the function ‘main’. It is up
- to you to write a function named ‘main’—otherwise, you won’t even be
- able to link your program without errors.
- In ISO C you can define ‘main’ either to take no arguments, or to
- take two arguments that represent the command line arguments to the
- program, like this:
- int main (int ARGC, char *ARGV[])
- The command line arguments are the whitespace-separated tokens given
- in the shell command used to invoke the program; thus, in ‘cat foo bar’,
- the arguments are ‘foo’ and ‘bar’. The only way a program can look at
- its command line arguments is via the arguments of ‘main’. If ‘main’
- doesn’t take arguments, then you cannot get at the command line.
- The value of the ARGC argument is the number of command line
- arguments. The ARGV argument is a vector of C strings; its elements are
- the individual command line argument strings. The file name of the
- program being run is also included in the vector as the first element;
- the value of ARGC counts this element. A null pointer always follows
- the last element: ‘ARGV[ARGC]’ is this null pointer.
- For the command ‘cat foo bar’, ARGC is 3 and ARGV has three elements,
- ‘"cat"’, ‘"foo"’ and ‘"bar"’.
- In Unix systems you can define ‘main’ a third way, using three
- arguments:
- int main (int ARGC, char *ARGV[], char *ENVP[])
- The first two arguments are just the same. The third argument ENVP
- gives the program’s environment; it is the same as the value of
- ‘environ’. *Note Environment Variables::. POSIX.1 does not allow this
- three-argument form, so to be portable it is best to write ‘main’ to
- take two arguments, and use the value of ‘environ’.
- * Menu:
- * Argument Syntax:: By convention, options start with a hyphen.
- * Parsing Program Arguments:: Ways to parse program options and arguments.
- File: libc.info, Node: Argument Syntax, Next: Parsing Program Arguments, Up: Program Arguments
- 25.1.1 Program Argument Syntax Conventions
- ------------------------------------------
- POSIX recommends these conventions for command line arguments. ‘getopt’
- (*note Getopt::) and ‘argp_parse’ (*note Argp::) make it easy to
- implement them.
- • Arguments are options if they begin with a hyphen delimiter (‘-’).
- • Multiple options may follow a hyphen delimiter in a single token if
- the options do not take arguments. Thus, ‘-abc’ is equivalent to
- ‘-a -b -c’.
- • Option names are single alphanumeric characters (as for ‘isalnum’;
- *note Classification of Characters::).
- • Certain options require an argument. For example, the ‘-o’ command
- of the ‘ld’ command requires an argument—an output file name.
- • An option and its argument may or may not appear as separate
- tokens. (In other words, the whitespace separating them is
- optional.) Thus, ‘-o foo’ and ‘-ofoo’ are equivalent.
- • Options typically precede other non-option arguments.
- The implementations of ‘getopt’ and ‘argp_parse’ in the GNU C
- Library normally make it appear as if all the option arguments were
- specified before all the non-option arguments for the purposes of
- parsing, even if the user of your program intermixed option and
- non-option arguments. They do this by reordering the elements of
- the ARGV array. This behavior is nonstandard; if you want to
- suppress it, define the ‘_POSIX_OPTION_ORDER’ environment variable.
- *Note Standard Environment::.
- • The argument ‘--’ terminates all options; any following arguments
- are treated as non-option arguments, even if they begin with a
- hyphen.
- • A token consisting of a single hyphen character is interpreted as
- an ordinary non-option argument. By convention, it is used to
- specify input from or output to the standard input and output
- streams.
- • Options may be supplied in any order, or appear multiple times.
- The interpretation is left up to the particular application
- program.
- GNU adds "long options" to these conventions. Long options consist
- of ‘--’ followed by a name made of alphanumeric characters and dashes.
- Option names are typically one to three words long, with hyphens to
- separate words. Users can abbreviate the option names as long as the
- abbreviations are unique.
- To specify an argument for a long option, write ‘--NAME=VALUE’. This
- syntax enables a long option to accept an argument that is itself
- optional.
- Eventually, GNU systems will provide completion for long option names
- in the shell.
- File: libc.info, Node: Parsing Program Arguments, Prev: Argument Syntax, Up: Program Arguments
- 25.1.2 Parsing Program Arguments
- --------------------------------
- If the syntax for the command line arguments to your program is simple
- enough, you can simply pick the arguments off from ARGV by hand. But
- unless your program takes a fixed number of arguments, or all of the
- arguments are interpreted in the same way (as file names, for example),
- you are usually better off using ‘getopt’ (*note Getopt::) or
- ‘argp_parse’ (*note Argp::) to do the parsing.
- ‘getopt’ is more standard (the short-option only version of it is a
- part of the POSIX standard), but using ‘argp_parse’ is often easier,
- both for very simple and very complex option structures, because it does
- more of the dirty work for you.
- * Menu:
- * Getopt:: Parsing program options using ‘getopt’.
- * Argp:: Parsing program options using ‘argp_parse’.
- * Suboptions:: Some programs need more detailed options.
- * Suboptions Example:: This shows how it could be done for ‘mount’.
- File: libc.info, Node: Getopt, Next: Argp, Up: Parsing Program Arguments
- 25.2 Parsing program options using ‘getopt’
- ===========================================
- The ‘getopt’ and ‘getopt_long’ functions automate some of the chore
- involved in parsing typical unix command line options.
- * Menu:
- * Using Getopt:: Using the ‘getopt’ function.
- * Example of Getopt:: An example of parsing options with ‘getopt’.
- * Getopt Long Options:: GNU suggests utilities accept long-named
- options; here is one way to do.
- * Getopt Long Option Example:: An example of using ‘getopt_long’.
- File: libc.info, Node: Using Getopt, Next: Example of Getopt, Up: Getopt
- 25.2.1 Using the ‘getopt’ function
- ----------------------------------
- Here are the details about how to call the ‘getopt’ function. To use
- this facility, your program must include the header file ‘unistd.h’.
- -- Variable: int opterr
- If the value of this variable is nonzero, then ‘getopt’ prints an
- error message to the standard error stream if it encounters an
- unknown option character or an option with a missing required
- argument. This is the default behavior. If you set this variable
- to zero, ‘getopt’ does not print any messages, but it still returns
- the character ‘?’ to indicate an error.
- -- Variable: int optopt
- When ‘getopt’ encounters an unknown option character or an option
- with a missing required argument, it stores that option character
- in this variable. You can use this for providing your own
- diagnostic messages.
- -- Variable: int optind
- This variable is set by ‘getopt’ to the index of the next element
- of the ARGV array to be processed. Once ‘getopt’ has found all of
- the option arguments, you can use this variable to determine where
- the remaining non-option arguments begin. The initial value of
- this variable is ‘1’.
- -- Variable: char * optarg
- This variable is set by ‘getopt’ to point at the value of the
- option argument, for those options that accept arguments.
- -- Function: int getopt (int ARGC, char *const *ARGV, const char
- *OPTIONS)
- Preliminary: | MT-Unsafe race:getopt env | AS-Unsafe heap i18n lock
- corrupt | AC-Unsafe mem lock corrupt | *Note POSIX Safety
- Concepts::.
- The ‘getopt’ function gets the next option argument from the
- argument list specified by the ARGV and ARGC arguments. Normally
- these values come directly from the arguments received by ‘main’.
- The OPTIONS argument is a string that specifies the option
- characters that are valid for this program. An option character in
- this string can be followed by a colon (‘:’) to indicate that it
- takes a required argument. If an option character is followed by
- two colons (‘::’), its argument is optional; this is a GNU
- extension.
- ‘getopt’ has three ways to deal with options that follow
- non-options ARGV elements. The special argument ‘--’ forces in all
- cases the end of option scanning.
- • The default is to permute the contents of ARGV while scanning
- it so that eventually all the non-options are at the end.
- This allows options to be given in any order, even with
- programs that were not written to expect this.
- • If the OPTIONS argument string begins with a hyphen (‘-’),
- this is treated specially. It permits arguments that are not
- options to be returned as if they were associated with option
- character ‘\1’.
- • POSIX demands the following behavior: the first non-option
- stops option processing. This mode is selected by either
- setting the environment variable ‘POSIXLY_CORRECT’ or
- beginning the OPTIONS argument string with a plus sign (‘+’).
- The ‘getopt’ function returns the option character for the next
- command line option. When no more option arguments are available,
- it returns ‘-1’. There may still be more non-option arguments; you
- must compare the external variable ‘optind’ against the ARGC
- parameter to check this.
- If the option has an argument, ‘getopt’ returns the argument by
- storing it in the variable OPTARG. You don’t ordinarily need to
- copy the ‘optarg’ string, since it is a pointer into the original
- ARGV array, not into a static area that might be overwritten.
- If ‘getopt’ finds an option character in ARGV that was not included
- in OPTIONS, or a missing option argument, it returns ‘?’ and sets
- the external variable ‘optopt’ to the actual option character. If
- the first character of OPTIONS is a colon (‘:’), then ‘getopt’
- returns ‘:’ instead of ‘?’ to indicate a missing option argument.
- In addition, if the external variable ‘opterr’ is nonzero (which is
- the default), ‘getopt’ prints an error message.
- File: libc.info, Node: Example of Getopt, Next: Getopt Long Options, Prev: Using Getopt, Up: Getopt
- 25.2.2 Example of Parsing Arguments with ‘getopt’
- -------------------------------------------------
- Here is an example showing how ‘getopt’ is typically used. The key
- points to notice are:
- • Normally, ‘getopt’ is called in a loop. When ‘getopt’ returns
- ‘-1’, indicating no more options are present, the loop terminates.
- • A ‘switch’ statement is used to dispatch on the return value from
- ‘getopt’. In typical use, each case just sets a variable that is
- used later in the program.
- • A second loop is used to process the remaining non-option
- arguments.
- #include <ctype.h>
- #include <stdio.h>
- #include <stdlib.h>
- #include <unistd.h>
- int
- main (int argc, char **argv)
- {
- int aflag = 0;
- int bflag = 0;
- char *cvalue = NULL;
- int index;
- int c;
- opterr = 0;
- while ((c = getopt (argc, argv, "abc:")) != -1)
- switch (c)
- {
- case 'a':
- aflag = 1;
- break;
- case 'b':
- bflag = 1;
- break;
- case 'c':
- cvalue = optarg;
- break;
- case '?':
- if (optopt == 'c')
- fprintf (stderr, "Option -%c requires an argument.\n", optopt);
- else if (isprint (optopt))
- fprintf (stderr, "Unknown option `-%c'.\n", optopt);
- else
- fprintf (stderr,
- "Unknown option character `\\x%x'.\n",
- optopt);
- return 1;
- default:
- abort ();
- }
- printf ("aflag = %d, bflag = %d, cvalue = %s\n",
- aflag, bflag, cvalue);
- for (index = optind; index < argc; index++)
- printf ("Non-option argument %s\n", argv[index]);
- return 0;
- }
- Here are some examples showing what this program prints with
- different combinations of arguments:
- % testopt
- aflag = 0, bflag = 0, cvalue = (null)
- % testopt -a -b
- aflag = 1, bflag = 1, cvalue = (null)
- % testopt -ab
- aflag = 1, bflag = 1, cvalue = (null)
- % testopt -c foo
- aflag = 0, bflag = 0, cvalue = foo
- % testopt -cfoo
- aflag = 0, bflag = 0, cvalue = foo
- % testopt arg1
- aflag = 0, bflag = 0, cvalue = (null)
- Non-option argument arg1
- % testopt -a arg1
- aflag = 1, bflag = 0, cvalue = (null)
- Non-option argument arg1
- % testopt -c foo arg1
- aflag = 0, bflag = 0, cvalue = foo
- Non-option argument arg1
- % testopt -a -- -b
- aflag = 1, bflag = 0, cvalue = (null)
- Non-option argument -b
- % testopt -a -
- aflag = 1, bflag = 0, cvalue = (null)
- Non-option argument -
- File: libc.info, Node: Getopt Long Options, Next: Getopt Long Option Example, Prev: Example of Getopt, Up: Getopt
- 25.2.3 Parsing Long Options with ‘getopt_long’
- ----------------------------------------------
- To accept GNU-style long options as well as single-character options,
- use ‘getopt_long’ instead of ‘getopt’. This function is declared in
- ‘getopt.h’, not ‘unistd.h’. You should make every program accept long
- options if it uses any options, for this takes little extra work and
- helps beginners remember how to use the program.
- -- Data Type: struct option
- This structure describes a single long option name for the sake of
- ‘getopt_long’. The argument LONGOPTS must be an array of these
- structures, one for each long option. Terminate the array with an
- element containing all zeros.
- The ‘struct option’ structure has these fields:
- ‘const char *name’
- This field is the name of the option. It is a string.
- ‘int has_arg’
- This field says whether the option takes an argument. It is
- an integer, and there are three legitimate values:
- ‘no_argument’, ‘required_argument’ and ‘optional_argument’.
- ‘int *flag’
- ‘int val’
- These fields control how to report or act on the option when
- it occurs.
- If ‘flag’ is a null pointer, then the ‘val’ is a value which
- identifies this option. Often these values are chosen to
- uniquely identify particular long options.
- If ‘flag’ is not a null pointer, it should be the address of
- an ‘int’ variable which is the flag for this option. The
- value in ‘val’ is the value to store in the flag to indicate
- that the option was seen.
- -- Function: int getopt_long (int ARGC, char *const *ARGV, const char
- *SHORTOPTS, const struct option *LONGOPTS, int *INDEXPTR)
- Preliminary: | MT-Unsafe race:getopt env | AS-Unsafe heap i18n lock
- corrupt | AC-Unsafe mem lock corrupt | *Note POSIX Safety
- Concepts::.
- Decode options from the vector ARGV (whose length is ARGC). The
- argument SHORTOPTS describes the short options to accept, just as
- it does in ‘getopt’. The argument LONGOPTS describes the long
- options to accept (see above).
- When ‘getopt_long’ encounters a short option, it does the same
- thing that ‘getopt’ would do: it returns the character code for the
- option, and stores the option’s argument (if it has one) in
- ‘optarg’.
- When ‘getopt_long’ encounters a long option, it takes actions based
- on the ‘flag’ and ‘val’ fields of the definition of that option.
- If ‘flag’ is a null pointer, then ‘getopt_long’ returns the
- contents of ‘val’ to indicate which option it found. You should
- arrange distinct values in the ‘val’ field for options with
- different meanings, so you can decode these values after
- ‘getopt_long’ returns. If the long option is equivalent to a short
- option, you can use the short option’s character code in ‘val’.
- If ‘flag’ is not a null pointer, that means this option should just
- set a flag in the program. The flag is a variable of type ‘int’
- that you define. Put the address of the flag in the ‘flag’ field.
- Put in the ‘val’ field the value you would like this option to
- store in the flag. In this case, ‘getopt_long’ returns ‘0’.
- For any long option, ‘getopt_long’ tells you the index in the array
- LONGOPTS of the options definition, by storing it into ‘*INDEXPTR’.
- You can get the name of the option with ‘LONGOPTS[*INDEXPTR].name’.
- So you can distinguish among long options either by the values in
- their ‘val’ fields or by their indices. You can also distinguish
- in this way among long options that set flags.
- When a long option has an argument, ‘getopt_long’ puts the argument
- value in the variable ‘optarg’ before returning. When the option
- has no argument, the value in ‘optarg’ is a null pointer. This is
- how you can tell whether an optional argument was supplied.
- When ‘getopt_long’ has no more options to handle, it returns ‘-1’,
- and leaves in the variable ‘optind’ the index in ARGV of the next
- remaining argument.
- Since long option names were used before ‘getopt_long’ was invented
- there are program interfaces which require programs to recognize options
- like ‘-option value’ instead of ‘--option value’. To enable these
- programs to use the GNU getopt functionality there is one more function
- available.
- -- Function: int getopt_long_only (int ARGC, char *const *ARGV, const
- char *SHORTOPTS, const struct option *LONGOPTS, int *INDEXPTR)
- Preliminary: | MT-Unsafe race:getopt env | AS-Unsafe heap i18n lock
- corrupt | AC-Unsafe mem lock corrupt | *Note POSIX Safety
- Concepts::.
- The ‘getopt_long_only’ function is equivalent to the ‘getopt_long’
- function but it allows the user of the application to pass long
- options with only ‘-’ instead of ‘--’. The ‘--’ prefix is still
- recognized but instead of looking through the short options if a
- ‘-’ is seen it is first tried whether this parameter names a long
- option. If not, it is parsed as a short option.
- Assuming ‘getopt_long_only’ is used starting an application with
- app -foo
- the ‘getopt_long_only’ will first look for a long option named
- ‘foo’. If this is not found, the short options ‘f’, ‘o’, and again
- ‘o’ are recognized.
- File: libc.info, Node: Getopt Long Option Example, Prev: Getopt Long Options, Up: Getopt
- 25.2.4 Example of Parsing Long Options with ‘getopt_long’
- ---------------------------------------------------------
- #include <stdio.h>
- #include <stdlib.h>
- #include <getopt.h>
- /* Flag set by ‘--verbose’. */
- static int verbose_flag;
- int
- main (int argc, char **argv)
- {
- int c;
- while (1)
- {
- static struct option long_options[] =
- {
- /* These options set a flag. */
- {"verbose", no_argument, &verbose_flag, 1},
- {"brief", no_argument, &verbose_flag, 0},
- /* These options don’t set a flag.
- We distinguish them by their indices. */
- {"add", no_argument, 0, 'a'},
- {"append", no_argument, 0, 'b'},
- {"delete", required_argument, 0, 'd'},
- {"create", required_argument, 0, 'c'},
- {"file", required_argument, 0, 'f'},
- {0, 0, 0, 0}
- };
- /* ‘getopt_long’ stores the option index here. */
- int option_index = 0;
- c = getopt_long (argc, argv, "abc:d:f:",
- long_options, &option_index);
- /* Detect the end of the options. */
- if (c == -1)
- break;
- switch (c)
- {
- case 0:
- /* If this option set a flag, do nothing else now. */
- if (long_options[option_index].flag != 0)
- break;
- printf ("option %s", long_options[option_index].name);
- if (optarg)
- printf (" with arg %s", optarg);
- printf ("\n");
- break;
- case 'a':
- puts ("option -a\n");
- break;
- case 'b':
- puts ("option -b\n");
- break;
- case 'c':
- printf ("option -c with value `%s'\n", optarg);
- break;
- case 'd':
- printf ("option -d with value `%s'\n", optarg);
- break;
- case 'f':
- printf ("option -f with value `%s'\n", optarg);
- break;
- case '?':
- /* ‘getopt_long’ already printed an error message. */
- break;
- default:
- abort ();
- }
- }
- /* Instead of reporting ‘--verbose’
- and ‘--brief’ as they are encountered,
- we report the final status resulting from them. */
- if (verbose_flag)
- puts ("verbose flag is set");
- /* Print any remaining command line arguments (not options). */
- if (optind < argc)
- {
- printf ("non-option ARGV-elements: ");
- while (optind < argc)
- printf ("%s ", argv[optind++]);
- putchar ('\n');
- }
- exit (0);
- }
- File: libc.info, Node: Argp, Next: Suboptions, Prev: Getopt, Up: Parsing Program Arguments
- 25.3 Parsing Program Options with Argp
- ======================================
- "Argp" is an interface for parsing unix-style argument vectors. *Note
- Program Arguments::.
- Argp provides features unavailable in the more commonly used ‘getopt’
- interface. These features include automatically producing output in
- response to the ‘--help’ and ‘--version’ options, as described in the
- GNU coding standards. Using argp makes it less likely that programmers
- will neglect to implement these additional options or keep them up to
- date.
- Argp also provides the ability to merge several independently defined
- option parsers into one, mediating conflicts between them and making the
- result appear seamless. A library can export an argp option parser that
- user programs might employ in conjunction with their own option parsers,
- resulting in less work for the user programs. Some programs may use
- only argument parsers exported by libraries, thereby achieving
- consistent and efficient option-parsing for abstractions implemented by
- the libraries.
- The header file ‘<argp.h>’ should be included to use argp.
- 25.3.1 The ‘argp_parse’ Function
- --------------------------------
- The main interface to argp is the ‘argp_parse’ function. In many cases,
- calling ‘argp_parse’ is the only argument-parsing code needed in ‘main’.
- *Note Program Arguments::.
- -- Function: error_t argp_parse (const struct argp *ARGP, int ARGC,
- char **ARGV, unsigned FLAGS, int *ARG_INDEX, void *INPUT)
- Preliminary: | MT-Unsafe race:argpbuf locale env | AS-Unsafe heap
- i18n lock corrupt | AC-Unsafe mem lock corrupt | *Note POSIX Safety
- Concepts::.
- The ‘argp_parse’ function parses the arguments in ARGV, of length
- ARGC, using the argp parser ARGP. *Note Argp Parsers::. Passing a
- null pointer for ARGP is the same as using a ‘struct argp’
- containing all zeros.
- FLAGS is a set of flag bits that modify the parsing behavior.
- *Note Argp Flags::. INPUT is passed through to the argp parser
- ARGP, and has meaning defined by ARGP. A typical usage is to pass
- a pointer to a structure which is used for specifying parameters to
- the parser and passing back the results.
- Unless the ‘ARGP_NO_EXIT’ or ‘ARGP_NO_HELP’ flags are included in
- FLAGS, calling ‘argp_parse’ may result in the program exiting.
- This behavior is true if an error is detected, or when an unknown
- option is encountered. *Note Program Termination::.
- If ARG_INDEX is non-null, the index of the first unparsed option in
- ARGV is returned as a value.
- The return value is zero for successful parsing, or an error code
- (*note Error Codes::) if an error is detected. Different argp
- parsers may return arbitrary error codes, but the standard error
- codes are: ‘ENOMEM’ if a memory allocation error occurred, or
- ‘EINVAL’ if an unknown option or option argument is encountered.
- * Menu:
- * Globals: Argp Global Variables. Global argp parameters.
- * Parsers: Argp Parsers. Defining parsers for use with ‘argp_parse’.
- * Flags: Argp Flags. Flags that modify the behavior of ‘argp_parse’.
- * Help: Argp Help. Printing help messages when not parsing.
- * Examples: Argp Examples. Simple examples of programs using argp.
- * Customization: Argp User Customization.
- Users may control the ‘--help’ output format.
- File: libc.info, Node: Argp Global Variables, Next: Argp Parsers, Up: Argp
- 25.3.2 Argp Global Variables
- ----------------------------
- These variables make it easy for user programs to implement the
- ‘--version’ option and provide a bug-reporting address in the ‘--help’
- output. These are implemented in argp by default.
- -- Variable: const char * argp_program_version
- If defined or set by the user program to a non-zero value, then a
- ‘--version’ option is added when parsing with ‘argp_parse’, which
- will print the ‘--version’ string followed by a newline and exit.
- The exception to this is if the ‘ARGP_NO_EXIT’ flag is used.
- -- Variable: const char * argp_program_bug_address
- If defined or set by the user program to a non-zero value,
- ‘argp_program_bug_address’ should point to a string that will be
- printed at the end of the standard output for the ‘--help’ option,
- embedded in a sentence that says ‘Report bugs to ADDRESS.’.
- -- Variable: argp_program_version_hook
- If defined or set by the user program to a non-zero value, a
- ‘--version’ option is added when parsing with ‘arg_parse’, which
- prints the program version and exits with a status of zero. This
- is not the case if the ‘ARGP_NO_HELP’ flag is used. If the
- ‘ARGP_NO_EXIT’ flag is set, the exit behavior of the program is
- suppressed or modified, as when the argp parser is going to be used
- by other programs.
- It should point to a function with this type of signature:
- void PRINT-VERSION (FILE *STREAM, struct argp_state *STATE)
- *Note Argp Parsing State::, for an explanation of STATE.
- This variable takes precedence over ‘argp_program_version’, and is
- useful if a program has version information not easily expressed in
- a simple string.
- -- Variable: error_t argp_err_exit_status
- This is the exit status used when argp exits due to a parsing
- error. If not defined or set by the user program, this defaults
- to: ‘EX_USAGE’ from ‘<sysexits.h>’.
- File: libc.info, Node: Argp Parsers, Next: Argp Flags, Prev: Argp Global Variables, Up: Argp
- 25.3.3 Specifying Argp Parsers
- ------------------------------
- The first argument to the ‘argp_parse’ function is a pointer to a
- ‘struct argp’, which is known as an "argp parser":
- -- Data Type: struct argp
- This structure specifies how to parse a given set of options and
- arguments, perhaps in conjunction with other argp parsers. It has
- the following fields:
- ‘const struct argp_option *options’
- A pointer to a vector of ‘argp_option’ structures specifying
- which options this argp parser understands; it may be zero if
- there are no options at all. *Note Argp Option Vectors::.
- ‘argp_parser_t parser’
- A pointer to a function that defines actions for this parser;
- it is called for each option parsed, and at other well-defined
- points in the parsing process. A value of zero is the same as
- a pointer to a function that always returns
- ‘ARGP_ERR_UNKNOWN’. *Note Argp Parser Functions::.
- ‘const char *args_doc’
- If non-zero, a string describing what non-option arguments are
- called by this parser. This is only used to print the
- ‘Usage:’ message. If it contains newlines, the strings
- separated by them are considered alternative usage patterns
- and printed on separate lines. Lines after the first are
- prefixed by ‘ or: ’ instead of ‘Usage:’.
- ‘const char *doc’
- If non-zero, a string containing extra text to be printed
- before and after the options in a long help message, with the
- two sections separated by a vertical tab (‘'\v'’, ‘'\013'’)
- character. By convention, the documentation before the
- options is just a short string explaining what the program
- does. Documentation printed after the options describe
- behavior in more detail.
- ‘const struct argp_child *children’
- A pointer to a vector of ‘argp_child’ structures. This
- pointer specifies which additional argp parsers should be
- combined with this one. *Note Argp Children::.
- ‘char *(*help_filter)(int KEY, const char *TEXT, void *INPUT)’
- If non-zero, a pointer to a function that filters the output
- of help messages. *Note Argp Help Filtering::.
- ‘const char *argp_domain’
- If non-zero, the strings used in the argp library are
- translated using the domain described by this string. If
- zero, the current default domain is used.
- Of the above group, ‘options’, ‘parser’, ‘args_doc’, and the ‘doc’
- fields are usually all that are needed. If an argp parser is defined as
- an initialized C variable, only the fields used need be specified in the
- initializer. The rest will default to zero due to the way C structure
- initialization works. This design is exploited in most argp structures;
- the most-used fields are grouped near the beginning, the unused fields
- left unspecified.
- * Menu:
- * Options: Argp Option Vectors. Specifying options in an argp parser.
- * Argp Parser Functions:: Defining actions for an argp parser.
- * Children: Argp Children. Combining multiple argp parsers.
- * Help Filtering: Argp Help Filtering. Customizing help output for an argp parser.
- File: libc.info, Node: Argp Option Vectors, Next: Argp Parser Functions, Prev: Argp Parsers, Up: Argp Parsers
- 25.3.4 Specifying Options in an Argp Parser
- -------------------------------------------
- The ‘options’ field in a ‘struct argp’ points to a vector of ‘struct
- argp_option’ structures, each of which specifies an option that the argp
- parser supports. Multiple entries may be used for a single option
- provided it has multiple names. This should be terminated by an entry
- with zero in all fields. Note that when using an initialized C array
- for options, writing ‘{ 0 }’ is enough to achieve this.
- -- Data Type: struct argp_option
- This structure specifies a single option that an argp parser
- understands, as well as how to parse and document that option. It
- has the following fields:
- ‘const char *name’
- The long name for this option, corresponding to the long
- option ‘--NAME’; this field may be zero if this option _only_
- has a short name. To specify multiple names for an option,
- additional entries may follow this one, with the
- ‘OPTION_ALIAS’ flag set. *Note Argp Option Flags::.
- ‘int key’
- The integer key provided by the current option to the option
- parser. If KEY has a value that is a printable ASCII
- character (i.e., ‘isascii (KEY)’ is true), it _also_ specifies
- a short option ‘-CHAR’, where CHAR is the ASCII character with
- the code KEY.
- ‘const char *arg’
- If non-zero, this is the name of an argument associated with
- this option, which must be provided (e.g., with the
- ‘--NAME=VALUE’ or ‘-CHAR VALUE’ syntaxes), unless the
- ‘OPTION_ARG_OPTIONAL’ flag (*note Argp Option Flags::) is set,
- in which case it _may_ be provided.
- ‘int flags’
- Flags associated with this option, some of which are referred
- to above. *Note Argp Option Flags::.
- ‘const char *doc’
- A documentation string for this option, for printing in help
- messages.
- If both the ‘name’ and ‘key’ fields are zero, this string will
- be printed tabbed left from the normal option column, making
- it useful as a group header. This will be the first thing
- printed in its group. In this usage, it’s conventional to end
- the string with a ‘:’ character.
- ‘int group’
- Group identity for this option.
- In a long help message, options are sorted alphabetically
- within each group, and the groups presented in the order 0, 1,
- 2, …, N, −M, …, −2, −1.
- Every entry in an options array with this field 0 will inherit
- the group number of the previous entry, or zero if it’s the
- first one. If it’s a group header with ‘name’ and ‘key’
- fields both zero, the previous entry + 1 is the default.
- Automagic options such as ‘--help’ are put into group −1.
- Note that because of C structure initialization rules, this
- field often need not be specified, because 0 is the correct
- value.
- * Menu:
- * Flags: Argp Option Flags. Flags for options.
- File: libc.info, Node: Argp Option Flags, Up: Argp Option Vectors
- 25.3.4.1 Flags for Argp Options
- ...............................
- The following flags may be or’d together in the ‘flags’ field of a
- ‘struct argp_option’. These flags control various aspects of how that
- option is parsed or displayed in help messages:
- ‘OPTION_ARG_OPTIONAL’
- The argument associated with this option is optional.
- ‘OPTION_HIDDEN’
- This option isn’t displayed in any help messages.
- ‘OPTION_ALIAS’
- This option is an alias for the closest previous non-alias option.
- This means that it will be displayed in the same help entry, and
- will inherit fields other than ‘name’ and ‘key’ from the option
- being aliased.
- ‘OPTION_DOC’
- This option isn’t actually an option and should be ignored by the
- actual option parser. It is an arbitrary section of documentation
- that should be displayed in much the same manner as the options.
- This is known as a "documentation option".
- If this flag is set, then the option ‘name’ field is displayed
- unmodified (e.g., no ‘--’ prefix is added) at the left-margin where
- a _short_ option would normally be displayed, and this
- documentation string is left in its usual place. For purposes of
- sorting, any leading whitespace and punctuation is ignored, unless
- the first non-whitespace character is ‘-’. This entry is displayed
- after all options, after ‘OPTION_DOC’ entries with a leading ‘-’,
- in the same group.
- ‘OPTION_NO_USAGE’
- This option shouldn’t be included in ‘long’ usage messages, but
- should still be included in other help messages. This is intended
- for options that are completely documented in an argp’s ‘args_doc’
- field. *Note Argp Parsers::. Including this option in the generic
- usage list would be redundant, and should be avoided.
- For instance, if ‘args_doc’ is ‘"FOO BAR\n-x BLAH"’, and the ‘-x’
- option’s purpose is to distinguish these two cases, ‘-x’ should
- probably be marked ‘OPTION_NO_USAGE’.
- File: libc.info, Node: Argp Parser Functions, Next: Argp Children, Prev: Argp Option Vectors, Up: Argp Parsers
- 25.3.5 Argp Parser Functions
- ----------------------------
- The function pointed to by the ‘parser’ field in a ‘struct argp’ (*note
- Argp Parsers::) defines what actions take place in response to each
- option or argument parsed. It is also used as a hook, allowing a parser
- to perform tasks at certain other points during parsing.
- Argp parser functions have the following type signature:
- error_t PARSER (int KEY, char *ARG, struct argp_state *STATE)
- where the arguments are as follows:
- KEY
- For each option that is parsed, PARSER is called with a value of
- KEY from that option’s ‘key’ field in the option vector. *Note
- Argp Option Vectors::. PARSER is also called at other times with
- special reserved keys, such as ‘ARGP_KEY_ARG’ for non-option
- arguments. *Note Argp Special Keys::.
- ARG
- If KEY is an option, ARG is its given value. This defaults to zero
- if no value is specified. Only options that have a non-zero ‘arg’
- field can ever have a value. These must _always_ have a value
- unless the ‘OPTION_ARG_OPTIONAL’ flag is specified. If the input
- being parsed specifies a value for an option that doesn’t allow
- one, an error results before PARSER ever gets called.
- If KEY is ‘ARGP_KEY_ARG’, ARG is a non-option argument. Other
- special keys always have a zero ARG.
- STATE
- STATE points to a ‘struct argp_state’, containing useful
- information about the current parsing state for use by PARSER.
- *Note Argp Parsing State::.
- When PARSER is called, it should perform whatever action is
- appropriate for KEY, and return ‘0’ for success, ‘ARGP_ERR_UNKNOWN’ if
- the value of KEY is not handled by this parser function, or a unix error
- code if a real error occurred. *Note Error Codes::.
- -- Macro: int ARGP_ERR_UNKNOWN
- Argp parser functions should return ‘ARGP_ERR_UNKNOWN’ for any KEY
- value they do not recognize, or for non-option arguments (‘KEY ==
- ARGP_KEY_ARG’) that they are not equipped to handle.
- A typical parser function uses a switch statement on KEY:
- error_t
- parse_opt (int key, char *arg, struct argp_state *state)
- {
- switch (key)
- {
- case OPTION_KEY:
- ACTION
- break;
- …
- default:
- return ARGP_ERR_UNKNOWN;
- }
- return 0;
- }
- * Menu:
- * Keys: Argp Special Keys. Special values for the KEY argument.
- * State: Argp Parsing State. What the STATE argument refers to.
- * Functions: Argp Helper Functions. Functions to help during argp parsing.
- File: libc.info, Node: Argp Special Keys, Next: Argp Parsing State, Up: Argp Parser Functions
- 25.3.5.1 Special Keys for Argp Parser Functions
- ...............................................
- In addition to key values corresponding to user options, the KEY
- argument to argp parser functions may have a number of other special
- values. In the following example ARG and STATE refer to parser function
- arguments. *Note Argp Parser Functions::.
- ‘ARGP_KEY_ARG’
- This is not an option at all, but rather a command line argument,
- whose value is pointed to by ARG.
- When there are multiple parser functions in play due to argp
- parsers being combined, it’s impossible to know which one will
- handle a specific argument. Each is called until one returns 0 or
- an error other than ‘ARGP_ERR_UNKNOWN’; if an argument is not
- handled, ‘argp_parse’ immediately returns success, without parsing
- any more arguments.
- Once a parser function returns success for this key, that fact is
- recorded, and the ‘ARGP_KEY_NO_ARGS’ case won’t be used.
- _However_, if while processing the argument a parser function
- decrements the ‘next’ field of its STATE argument, the option won’t
- be considered processed; this is to allow you to actually modify
- the argument, perhaps into an option, and have it processed again.
- ‘ARGP_KEY_ARGS’
- If a parser function returns ‘ARGP_ERR_UNKNOWN’ for ‘ARGP_KEY_ARG’,
- it is immediately called again with the key ‘ARGP_KEY_ARGS’, which
- has a similar meaning, but is slightly more convenient for
- consuming all remaining arguments. ARG is 0, and the tail of the
- argument vector may be found at ‘STATE->argv + STATE->next’. If
- success is returned for this key, and ‘STATE->next’ is unchanged,
- all remaining arguments are considered to have been consumed.
- Otherwise, the amount by which ‘STATE->next’ has been adjusted
- indicates how many were used. Here’s an example that uses both,
- for different args:
- …
- case ARGP_KEY_ARG:
- if (STATE->arg_num == 0)
- /* First argument */
- first_arg = ARG;
- else
- /* Let the next case parse it. */
- return ARGP_KEY_UNKNOWN;
- break;
- case ARGP_KEY_ARGS:
- remaining_args = STATE->argv + STATE->next;
- num_remaining_args = STATE->argc - STATE->next;
- break;
- ‘ARGP_KEY_END’
- This indicates that there are no more command line arguments.
- Parser functions are called in a different order, children first.
- This allows each parser to clean up its state for the parent.
- ‘ARGP_KEY_NO_ARGS’
- Because it’s common to do some special processing if there aren’t
- any non-option args, parser functions are called with this key if
- they didn’t successfully process any non-option arguments. This is
- called just before ‘ARGP_KEY_END’, where more general validity
- checks on previously parsed arguments take place.
- ‘ARGP_KEY_INIT’
- This is passed in before any parsing is done. Afterwards, the
- values of each element of the ‘child_input’ field of STATE, if any,
- are copied to each child’s state to be the initial value of the
- ‘input’ when _their_ parsers are called.
- ‘ARGP_KEY_SUCCESS’
- Passed in when parsing has successfully been completed, even if
- arguments remain.
- ‘ARGP_KEY_ERROR’
- Passed in if an error has occurred and parsing is terminated. In
- this case a call with a key of ‘ARGP_KEY_SUCCESS’ is never made.
- ‘ARGP_KEY_FINI’
- The final key ever seen by any parser, even after
- ‘ARGP_KEY_SUCCESS’ and ‘ARGP_KEY_ERROR’. Any resources allocated
- by ‘ARGP_KEY_INIT’ may be freed here. At times, certain resources
- allocated are to be returned to the caller after a successful
- parse. In that case, those particular resources can be freed in
- the ‘ARGP_KEY_ERROR’ case.
- In all cases, ‘ARGP_KEY_INIT’ is the first key seen by parser
- functions, and ‘ARGP_KEY_FINI’ the last, unless an error was returned by
- the parser for ‘ARGP_KEY_INIT’. Other keys can occur in one the
- following orders. OPT refers to an arbitrary option key:
- OPT… ‘ARGP_KEY_NO_ARGS’ ‘ARGP_KEY_END’ ‘ARGP_KEY_SUCCESS’
- The arguments being parsed did not contain any non-option
- arguments.
- ( OPT | ‘ARGP_KEY_ARG’ )… ‘ARGP_KEY_END’ ‘ARGP_KEY_SUCCESS’
- All non-option arguments were successfully handled by a parser
- function. There may be multiple parser functions if multiple argp
- parsers were combined.
- ( OPT | ‘ARGP_KEY_ARG’ )… ‘ARGP_KEY_SUCCESS’
- Some non-option argument went unrecognized.
- This occurs when every parser function returns ‘ARGP_KEY_UNKNOWN’
- for an argument, in which case parsing stops at that argument if
- ARG_INDEX is a null pointer. Otherwise an error occurs.
- In all cases, if a non-null value for ARG_INDEX gets passed to
- ‘argp_parse’, the index of the first unparsed command-line argument is
- passed back in that value.
- If an error occurs and is either detected by argp or because a parser
- function returned an error value, each parser is called with
- ‘ARGP_KEY_ERROR’. No further calls are made, except the final call with
- ‘ARGP_KEY_FINI’.
- File: libc.info, Node: Argp Parsing State, Next: Argp Helper Functions, Prev: Argp Special Keys, Up: Argp Parser Functions
- 25.3.5.2 Argp Parsing State
- ...........................
- The third argument to argp parser functions (*note Argp Parser
- Functions::) is a pointer to a ‘struct argp_state’, which contains
- information about the state of the option parsing.
- -- Data Type: struct argp_state
- This structure has the following fields, which may be modified as
- noted:
- ‘const struct argp *const root_argp’
- The top level argp parser being parsed. Note that this is
- often _not_ the same ‘struct argp’ passed into ‘argp_parse’ by
- the invoking program. *Note Argp::. It is an internal argp
- parser that contains options implemented by ‘argp_parse’
- itself, such as ‘--help’.
- ‘int argc’
- ‘char **argv’
- The argument vector being parsed. This may be modified.
- ‘int next’
- The index in ‘argv’ of the next argument to be parsed. This
- may be modified.
- One way to consume all remaining arguments in the input is to
- set ‘STATE->next = STATE->argc’, perhaps after recording the
- value of the ‘next’ field to find the consumed arguments. The
- current option can be re-parsed immediately by decrementing
- this field, then modifying ‘STATE->argv[STATE->next]’ to
- reflect the option that should be reexamined.
- ‘unsigned flags’
- The flags supplied to ‘argp_parse’. These may be modified,
- although some flags may only take effect when ‘argp_parse’ is
- first invoked. *Note Argp Flags::.
- ‘unsigned arg_num’
- While calling a parsing function with the KEY argument
- ‘ARGP_KEY_ARG’, this represents the number of the current arg,
- starting at 0. It is incremented after each ‘ARGP_KEY_ARG’
- call returns. At all other times, this is the number of
- ‘ARGP_KEY_ARG’ arguments that have been processed.
- ‘int quoted’
- If non-zero, the index in ‘argv’ of the first argument
- following a special ‘--’ argument. This prevents anything
- that follows from being interpreted as an option. It is only
- set after argument parsing has proceeded past this point.
- ‘void *input’
- An arbitrary pointer passed in from the caller of
- ‘argp_parse’, in the INPUT argument.
- ‘void **child_inputs’
- These are values that will be passed to child parsers. This
- vector will be the same length as the number of children in
- the current parser. Each child parser will be given the value
- of ‘STATE->child_inputs[I]’ as _its_ ‘STATE->input’ field,
- where I is the index of the child in the this parser’s
- ‘children’ field. *Note Argp Children::.
- ‘void *hook’
- For the parser function’s use. Initialized to 0, but
- otherwise ignored by argp.
- ‘char *name’
- The name used when printing messages. This is initialized to
- ‘argv[0]’, or ‘program_invocation_name’ if ‘argv[0]’ is
- unavailable.
- ‘FILE *err_stream’
- ‘FILE *out_stream’
- The stdio streams used when argp prints. Error messages are
- printed to ‘err_stream’, all other output, such as ‘--help’
- output) to ‘out_stream’. These are initialized to ‘stderr’
- and ‘stdout’ respectively. *Note Standard Streams::.
- ‘void *pstate’
- Private, for use by the argp implementation.
- File: libc.info, Node: Argp Helper Functions, Prev: Argp Parsing State, Up: Argp Parser Functions
- 25.3.5.3 Functions For Use in Argp Parsers
- ..........................................
- Argp provides a number of functions available to the user of argp (*note
- Argp Parser Functions::), mostly for producing error messages. These
- take as their first argument the STATE argument to the parser function.
- *Note Argp Parsing State::.
- -- Function: void argp_usage (const struct argp_state *STATE)
- Preliminary: | MT-Unsafe race:argpbuf env locale | AS-Unsafe heap
- i18n corrupt | AC-Unsafe mem corrupt lock | *Note POSIX Safety
- Concepts::.
- Outputs the standard usage message for the argp parser referred to
- by STATE to ‘STATE->err_stream’ and terminates the program with
- ‘exit (argp_err_exit_status)’. *Note Argp Global Variables::.
- -- Function: void argp_error (const struct argp_state *STATE, const
- char *FMT, …)
- Preliminary: | MT-Unsafe race:argpbuf env locale | AS-Unsafe heap
- i18n corrupt | AC-Unsafe mem corrupt lock | *Note POSIX Safety
- Concepts::.
- Prints the printf format string FMT and following args, preceded by
- the program name and ‘:’, and followed by a ‘Try … --help’ message,
- and terminates the program with an exit status of
- ‘argp_err_exit_status’. *Note Argp Global Variables::.
- -- Function: void argp_failure (const struct argp_state *STATE, int
- STATUS, int ERRNUM, const char *FMT, …)
- Preliminary: | MT-Safe | AS-Unsafe corrupt heap | AC-Unsafe lock
- corrupt mem | *Note POSIX Safety Concepts::.
- Similar to the standard GNU error-reporting function ‘error’, this
- prints the program name and ‘:’, the printf format string FMT, and
- the appropriate following args. If it is non-zero, the standard
- unix error text for ERRNUM is printed. If STATUS is non-zero, it
- terminates the program with that value as its exit status.
- The difference between ‘argp_failure’ and ‘argp_error’ is that
- ‘argp_error’ is for _parsing errors_, whereas ‘argp_failure’ is for
- other problems that occur during parsing but don’t reflect a
- syntactic problem with the input, such as illegal values for
- options, bad phase of the moon, etc.
- -- Function: void argp_state_help (const struct argp_state *STATE, FILE
- *STREAM, unsigned FLAGS)
- Preliminary: | MT-Unsafe race:argpbuf env locale | AS-Unsafe heap
- i18n corrupt | AC-Unsafe mem corrupt lock | *Note POSIX Safety
- Concepts::.
- Outputs a help message for the argp parser referred to by STATE, to
- STREAM. The FLAGS argument determines what sort of help message is
- produced. *Note Argp Help Flags::.
- Error output is sent to ‘STATE->err_stream’, and the program name
- printed is ‘STATE->name’.
- The output or program termination behavior of these functions may be
- suppressed if the ‘ARGP_NO_EXIT’ or ‘ARGP_NO_ERRS’ flags are passed to
- ‘argp_parse’. *Note Argp Flags::.
- This behavior is useful if an argp parser is exported for use by
- other programs (e.g., by a library), and may be used in a context where
- it is not desirable to terminate the program in response to parsing
- errors. In argp parsers intended for such general use, and for the case
- where the program _doesn’t_ terminate, calls to any of these functions
- should be followed by code that returns the appropriate error code:
- if (BAD ARGUMENT SYNTAX)
- {
- argp_usage (STATE);
- return EINVAL;
- }
- If a parser function will _only_ be used when ‘ARGP_NO_EXIT’ is not set,
- the return may be omitted.
- File: libc.info, Node: Argp Children, Next: Argp Help Filtering, Prev: Argp Parser Functions, Up: Argp Parsers
- 25.3.6 Combining Multiple Argp Parsers
- --------------------------------------
- The ‘children’ field in a ‘struct argp’ enables other argp parsers to be
- combined with the referencing one for the parsing of a single set of
- arguments. This field should point to a vector of ‘struct argp_child’,
- which is terminated by an entry having a value of zero in the ‘argp’
- field.
- Where conflicts between combined parsers arise, as when two specify
- an option with the same name, the parser conflicts are resolved in favor
- of the parent argp parser(s), or the earlier of the argp parsers in the
- list of children.
- -- Data Type: struct argp_child
- An entry in the list of subsidiary argp parsers pointed to by the
- ‘children’ field in a ‘struct argp’. The fields are as follows:
- ‘const struct argp *argp’
- The child argp parser, or zero to end of the list.
- ‘int flags’
- Flags for this child.
- ‘const char *header’
- If non-zero, this is an optional header to be printed within
- help output before the child options. As a side-effect, a
- non-zero value forces the child options to be grouped
- together. To achieve this effect without actually printing a
- header string, use a value of ‘""’. As with header strings
- specified in an option entry, the conventional value of the
- last character is ‘:’. *Note Argp Option Vectors::.
- ‘int group’
- This is where the child options are grouped relative to the
- other ‘consolidated’ options in the parent argp parser. The
- values are the same as the ‘group’ field in ‘struct
- argp_option’. *Note Argp Option Vectors::. All
- child-groupings follow parent options at a particular group
- level. If both this field and ‘header’ are zero, then the
- child’s options aren’t grouped together, they are merged with
- parent options at the parent option group level.
- File: libc.info, Node: Argp Flags, Next: Argp Help, Prev: Argp Parsers, Up: Argp
- 25.3.7 Flags for ‘argp_parse’
- -----------------------------
- The default behavior of ‘argp_parse’ is designed to be convenient for
- the most common case of parsing program command line argument. To
- modify these defaults, the following flags may be or’d together in the
- FLAGS argument to ‘argp_parse’:
- ‘ARGP_PARSE_ARGV0’
- Don’t ignore the first element of the ARGV argument to
- ‘argp_parse’. Unless ‘ARGP_NO_ERRS’ is set, the first element of
- the argument vector is skipped for option parsing purposes, as it
- corresponds to the program name in a command line.
- ‘ARGP_NO_ERRS’
- Don’t print error messages for unknown options to ‘stderr’; unless
- this flag is set, ‘ARGP_PARSE_ARGV0’ is ignored, as ‘argv[0]’ is
- used as the program name in the error messages. This flag implies
- ‘ARGP_NO_EXIT’. This is based on the assumption that silent
- exiting upon errors is bad behavior.
- ‘ARGP_NO_ARGS’
- Don’t parse any non-option args. Normally these are parsed by
- calling the parse functions with a key of ‘ARGP_KEY_ARG’, the
- actual argument being the value. This flag needn’t normally be
- set, as the default behavior is to stop parsing as soon as an
- argument fails to be parsed. *Note Argp Parser Functions::.
- ‘ARGP_IN_ORDER’
- Parse options and arguments in the same order they occur on the
- command line. Normally they’re rearranged so that all options come
- first.
- ‘ARGP_NO_HELP’
- Don’t provide the standard long option ‘--help’, which ordinarily
- causes usage and option help information to be output to ‘stdout’
- and ‘exit (0)’.
- ‘ARGP_NO_EXIT’
- Don’t exit on errors, although they may still result in error
- messages.
- ‘ARGP_LONG_ONLY’
- Use the GNU getopt ‘long-only’ rules for parsing arguments. This
- allows long-options to be recognized with only a single ‘-’ (i.e.,
- ‘-help’). This results in a less useful interface, and its use is
- discouraged as it conflicts with the way most GNU programs work as
- well as the GNU coding standards.
- ‘ARGP_SILENT’
- Turns off any message-printing/exiting options, specifically
- ‘ARGP_NO_EXIT’, ‘ARGP_NO_ERRS’, and ‘ARGP_NO_HELP’.
- File: libc.info, Node: Argp Help Filtering, Prev: Argp Children, Up: Argp Parsers
- 25.3.8 Customizing Argp Help Output
- -----------------------------------
- The ‘help_filter’ field in a ‘struct argp’ is a pointer to a function
- that filters the text of help messages before displaying them. They
- have a function signature like:
- char *HELP-FILTER (int KEY, const char *TEXT, void *INPUT)
- Where KEY is either a key from an option, in which case TEXT is that
- option’s help text. *Note Argp Option Vectors::. Alternately, one of
- the special keys with names beginning with ‘ARGP_KEY_HELP_’ might be
- used, describing which other help text TEXT will contain. *Note Argp
- Help Filter Keys::.
- The function should return either TEXT if it remains as-is, or a
- replacement string allocated using ‘malloc’. This will be either be
- freed by argp or zero, which prints nothing. The value of TEXT is
- supplied _after_ any translation has been done, so if any of the
- replacement text needs translation, it will be done by the filter
- function. INPUT is either the input supplied to ‘argp_parse’ or it is
- zero, if ‘argp_help’ was called directly by the user.
- * Menu:
- * Keys: Argp Help Filter Keys. Special KEY values for help filter functions.
- File: libc.info, Node: Argp Help Filter Keys, Up: Argp Help Filtering
- 25.3.8.1 Special Keys for Argp Help Filter Functions
- ....................................................
- The following special values may be passed to an argp help filter
- function as the first argument in addition to key values for user
- options. They specify which help text the TEXT argument contains:
- ‘ARGP_KEY_HELP_PRE_DOC’
- The help text preceding options.
- ‘ARGP_KEY_HELP_POST_DOC’
- The help text following options.
- ‘ARGP_KEY_HELP_HEADER’
- The option header string.
- ‘ARGP_KEY_HELP_EXTRA’
- This is used after all other documentation; TEXT is zero for this
- key.
- ‘ARGP_KEY_HELP_DUP_ARGS_NOTE’
- The explanatory note printed when duplicate option arguments have
- been suppressed.
- ‘ARGP_KEY_HELP_ARGS_DOC’
- The argument doc string; formally the ‘args_doc’ field from the
- argp parser. *Note Argp Parsers::.
- File: libc.info, Node: Argp Help, Next: Argp Examples, Prev: Argp Flags, Up: Argp
- 25.3.9 The ‘argp_help’ Function
- -------------------------------
- Normally programs using argp need not be written with particular
- printing argument-usage-type help messages in mind as the standard
- ‘--help’ option is handled automatically by argp. Typical error cases
- can be handled using ‘argp_usage’ and ‘argp_error’. *Note Argp Helper
- Functions::. However, if it’s desirable to print a help message in some
- context other than parsing the program options, argp offers the
- ‘argp_help’ interface.
- -- Function: void argp_help (const struct argp *ARGP, FILE *STREAM,
- unsigned FLAGS, char *NAME)
- Preliminary: | MT-Unsafe race:argpbuf env locale | AS-Unsafe heap
- i18n corrupt | AC-Unsafe mem corrupt lock | *Note POSIX Safety
- Concepts::.
- This outputs a help message for the argp parser ARGP to STREAM.
- The type of messages printed will be determined by FLAGS.
- Any options such as ‘--help’ that are implemented automatically by
- argp itself will _not_ be present in the help output; for this
- reason it is best to use ‘argp_state_help’ if calling from within
- an argp parser function. *Note Argp Helper Functions::.
- * Menu:
- * Flags: Argp Help Flags. Specifying what sort of help message to print.
- File: libc.info, Node: Argp Help Flags, Up: Argp Help
- 25.3.10 Flags for the ‘argp_help’ Function
- ------------------------------------------
- When calling ‘argp_help’ (*note Argp Help::) or ‘argp_state_help’ (*note
- Argp Helper Functions::) the exact output is determined by the FLAGS
- argument. This should consist of any of the following flags, or’d
- together:
- ‘ARGP_HELP_USAGE’
- A unix ‘Usage:’ message that explicitly lists all options.
- ‘ARGP_HELP_SHORT_USAGE’
- A unix ‘Usage:’ message that displays an appropriate placeholder to
- indicate where the options go; useful for showing the non-option
- argument syntax.
- ‘ARGP_HELP_SEE’
- A ‘Try … for more help’ message; ‘…’ contains the program name and
- ‘--help’.
- ‘ARGP_HELP_LONG’
- A verbose option help message that gives each option available
- along with its documentation string.
- ‘ARGP_HELP_PRE_DOC’
- The part of the argp parser doc string preceding the verbose option
- help.
- ‘ARGP_HELP_POST_DOC’
- The part of the argp parser doc string that following the verbose
- option help.
- ‘ARGP_HELP_DOC’
- ‘(ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)’
- ‘ARGP_HELP_BUG_ADDR’
- A message that prints where to report bugs for this program, if the
- ‘argp_program_bug_address’ variable contains this information.
- ‘ARGP_HELP_LONG_ONLY’
- This will modify any output to reflect the ‘ARGP_LONG_ONLY’ mode.
- The following flags are only understood when used with
- ‘argp_state_help’. They control whether the function returns after
- printing its output, or terminates the program:
- ‘ARGP_HELP_EXIT_ERR’
- This will terminate the program with ‘exit (argp_err_exit_status)’.
- ‘ARGP_HELP_EXIT_OK’
- This will terminate the program with ‘exit (0)’.
- The following flags are combinations of the basic flags for printing
- standard messages:
- ‘ARGP_HELP_STD_ERR’
- Assuming that an error message for a parsing error has printed,
- this prints a message on how to get help, and terminates the
- program with an error.
- ‘ARGP_HELP_STD_USAGE’
- This prints a standard usage message and terminates the program
- with an error. This is used when no other specific error messages
- are appropriate or available.
- ‘ARGP_HELP_STD_HELP’
- This prints the standard response for a ‘--help’ option, and
- terminates the program successfully.
- File: libc.info, Node: Argp Examples, Next: Argp User Customization, Prev: Argp Help, Up: Argp
- 25.3.11 Argp Examples
- ---------------------
- These example programs demonstrate the basic usage of argp.
- * Menu:
- * 1: Argp Example 1. A minimal program using argp.
- * 2: Argp Example 2. A program using only default options.
- * 3: Argp Example 3. A simple program with user options.
- * 4: Argp Example 4. Combining multiple argp parsers.
- File: libc.info, Node: Argp Example 1, Next: Argp Example 2, Up: Argp Examples
- 25.3.11.1 A Minimal Program Using Argp
- ......................................
- This is perhaps the smallest program possible that uses argp. It won’t
- do much except give an error message and exit when there are any
- arguments, and prints a rather pointless message for ‘--help’.
- /* This is (probably) the smallest possible program that
- uses argp. It won’t do much except give an error
- messages and exit when there are any arguments, and print
- a (rather pointless) messages for –help. */
- #include <stdlib.h>
- #include <argp.h>
- int
- main (int argc, char **argv)
- {
- argp_parse (0, argc, argv, 0, 0, 0);
- exit (0);
- }
- File: libc.info, Node: Argp Example 2, Next: Argp Example 3, Prev: Argp Example 1, Up: Argp Examples
- 25.3.11.2 A Program Using Argp with Only Default Options
- ........................................................
- This program doesn’t use any options or arguments, it uses argp to be
- compliant with the GNU standard command line format.
- In addition to giving no arguments and implementing a ‘--help’
- option, this example has a ‘--version’ option, which will put the given
- documentation string and bug address in the ‘--help’ output, as per GNU
- standards.
- The variable ‘argp’ contains the argument parser specification.
- Adding fields to this structure is the way most parameters are passed to
- ‘argp_parse’. The first three fields are normally used, but they are
- not in this small program. There are also two global variables that
- argp can use defined here, ‘argp_program_version’ and
- ‘argp_program_bug_address’. They are considered global variables
- because they will almost always be constant for a given program, even if
- they use different argument parsers for various tasks.
- /* This program doesn’t use any options or arguments, but uses
- argp to be compliant with the GNU standard command line
- format.
- In addition to making sure no arguments are given, and
- implementing a –help option, this example will have a
- –version option, and will put the given documentation string
- and bug address in the –help output, as per GNU standards.
- The variable ARGP contains the argument parser specification;
- adding fields to this structure is the way most parameters are
- passed to argp_parse (the first three fields are usually used,
- but not in this small program). There are also two global
- variables that argp knows about defined here,
- ARGP_PROGRAM_VERSION and ARGP_PROGRAM_BUG_ADDRESS (they are
- global variables because they will almost always be constant
- for a given program, even if it uses different argument
- parsers for various tasks). */
- #include <stdlib.h>
- #include <argp.h>
- const char *argp_program_version =
- "argp-ex2 1.0";
- const char *argp_program_bug_address =
- "<bug-gnu-utils@gnu.org>";
- /* Program documentation. */
- static char doc[] =
- "Argp example #2 -- a pretty minimal program using argp";
- /* Our argument parser. The ‘options’, ‘parser’, and
- ‘args_doc’ fields are zero because we have neither options or
- arguments; ‘doc’ and ‘argp_program_bug_address’ will be
- used in the output for ‘--help’, and the ‘--version’
- option will print out ‘argp_program_version’. */
- static struct argp argp = { 0, 0, 0, doc };
- int
- main (int argc, char **argv)
- {
- argp_parse (&argp, argc, argv, 0, 0, 0);
- exit (0);
- }
- File: libc.info, Node: Argp Example 3, Next: Argp Example 4, Prev: Argp Example 2, Up: Argp Examples
- 25.3.11.3 A Program Using Argp with User Options
- ................................................
- This program uses the same features as example 2, adding user options
- and arguments.
- We now use the first four fields in ‘argp’ (*note Argp Parsers::) and
- specify ‘parse_opt’ as the parser function. *Note Argp Parser
- Functions::.
- Note that in this example, ‘main’ uses a structure to communicate
- with the ‘parse_opt’ function, a pointer to which it passes in the
- ‘input’ argument to ‘argp_parse’. *Note Argp::. It is retrieved by
- ‘parse_opt’ through the ‘input’ field in its ‘state’ argument. *Note
- Argp Parsing State::. Of course, it’s also possible to use global
- variables instead, but using a structure like this is somewhat more
- flexible and clean.
- /* This program uses the same features as example 2, and uses options and
- arguments.
- We now use the first four fields in ARGP, so here’s a description of them:
- OPTIONS – A pointer to a vector of struct argp_option (see below)
- PARSER – A function to parse a single option, called by argp
- ARGS_DOC – A string describing how the non-option arguments should look
- DOC – A descriptive string about this program; if it contains a
- vertical tab character (\v), the part after it will be
- printed *following* the options
- The function PARSER takes the following arguments:
- KEY – An integer specifying which option this is (taken
- from the KEY field in each struct argp_option), or
- a special key specifying something else; the only
- special keys we use here are ARGP_KEY_ARG, meaning
- a non-option argument, and ARGP_KEY_END, meaning
- that all arguments have been parsed
- ARG – For an option KEY, the string value of its
- argument, or NULL if it has none
- STATE– A pointer to a struct argp_state, containing
- various useful information about the parsing state; used here
- are the INPUT field, which reflects the INPUT argument to
- argp_parse, and the ARG_NUM field, which is the number of the
- current non-option argument being parsed
- It should return either 0, meaning success, ARGP_ERR_UNKNOWN, meaning the
- given KEY wasn’t recognized, or an errno value indicating some other
- error.
- Note that in this example, main uses a structure to communicate with the
- parse_opt function, a pointer to which it passes in the INPUT argument to
- argp_parse. Of course, it’s also possible to use global variables
- instead, but this is somewhat more flexible.
- The OPTIONS field contains a pointer to a vector of struct argp_option’s;
- that structure has the following fields (if you assign your option
- structures using array initialization like this example, unspecified
- fields will be defaulted to 0, and need not be specified):
- NAME – The name of this option’s long option (may be zero)
- KEY – The KEY to pass to the PARSER function when parsing this option,
- *and* the name of this option’s short option, if it is a
- printable ascii character
- ARG – The name of this option’s argument, if any
- FLAGS – Flags describing this option; some of them are:
- OPTION_ARG_OPTIONAL – The argument to this option is optional
- OPTION_ALIAS – This option is an alias for the
- previous option
- OPTION_HIDDEN – Don’t show this option in –help output
- DOC – A documentation string for this option, shown in –help output
- An options vector should be terminated by an option with all fields zero. */
- #include <stdlib.h>
- #include <argp.h>
- const char *argp_program_version =
- "argp-ex3 1.0";
- const char *argp_program_bug_address =
- "<bug-gnu-utils@gnu.org>";
- /* Program documentation. */
- static char doc[] =
- "Argp example #3 -- a program with options and arguments using argp";
- /* A description of the arguments we accept. */
- static char args_doc[] = "ARG1 ARG2";
- /* The options we understand. */
- static struct argp_option options[] = {
- {"verbose", 'v', 0, 0, "Produce verbose output" },
- {"quiet", 'q', 0, 0, "Don't produce any output" },
- {"silent", 's', 0, OPTION_ALIAS },
- {"output", 'o', "FILE", 0,
- "Output to FILE instead of standard output" },
- { 0 }
- };
- /* Used by ‘main’ to communicate with ‘parse_opt’. */
- struct arguments
- {
- char *args[2]; /* ARG1 & ARG2 */
- int silent, verbose;
- char *output_file;
- };
- /* Parse a single option. */
- static error_t
- parse_opt (int key, char *arg, struct argp_state *state)
- {
- /* Get the INPUT argument from ‘argp_parse’, which we
- know is a pointer to our arguments structure. */
- struct arguments *arguments = state->input;
- switch (key)
- {
- case 'q': case 's':
- arguments->silent = 1;
- break;
- case 'v':
- arguments->verbose = 1;
- break;
- case 'o':
- arguments->output_file = arg;
- break;
- case ARGP_KEY_ARG:
- if (state->arg_num >= 2)
- /* Too many arguments. */
- argp_usage (state);
- arguments->args[state->arg_num] = arg;
- break;
- case ARGP_KEY_END:
- if (state->arg_num < 2)
- /* Not enough arguments. */
- argp_usage (state);
- break;
- default:
- return ARGP_ERR_UNKNOWN;
- }
- return 0;
- }
- /* Our argp parser. */
- static struct argp argp = { options, parse_opt, args_doc, doc };
- int
- main (int argc, char **argv)
- {
- struct arguments arguments;
- /* Default values. */
- arguments.silent = 0;
- arguments.verbose = 0;
- arguments.output_file = "-";
- /* Parse our arguments; every option seen by ‘parse_opt’ will
- be reflected in ‘arguments’. */
- argp_parse (&argp, argc, argv, 0, 0, &arguments);
- printf ("ARG1 = %s\nARG2 = %s\nOUTPUT_FILE = %s\n"
- "VERBOSE = %s\nSILENT = %s\n",
- arguments.args[0], arguments.args[1],
- arguments.output_file,
- arguments.verbose ? "yes" : "no",
- arguments.silent ? "yes" : "no");
- exit (0);
- }
- File: libc.info, Node: Argp Example 4, Prev: Argp Example 3, Up: Argp Examples
- 25.3.11.4 A Program Using Multiple Combined Argp Parsers
- ........................................................
- This program uses the same features as example 3, but has more options,
- and presents more structure in the ‘--help’ output. It also illustrates
- how you can ‘steal’ the remainder of the input arguments past a certain
- point for programs that accept a list of items. It also illustrates the
- KEY value ‘ARGP_KEY_NO_ARGS’, which is only given if no non-option
- arguments were supplied to the program. *Note Argp Special Keys::.
- For structuring help output, two features are used: _headers_ and a
- two part option string. The _headers_ are entries in the options
- vector. *Note Argp Option Vectors::. The first four fields are zero.
- The two part documentation string are in the variable ‘doc’, which
- allows documentation both before and after the options. *Note Argp
- Parsers::, the two parts of ‘doc’ are separated by a vertical-tab
- character (‘'\v'’, or ‘'\013'’). By convention, the documentation
- before the options is a short string stating what the program does, and
- after any options it is longer, describing the behavior in more detail.
- All documentation strings are automatically filled for output, although
- newlines may be included to force a line break at a particular point.
- In addition, documentation strings are passed to the ‘gettext’ function,
- for possible translation into the current locale.
- /* This program uses the same features as example 3, but has more
- options, and somewhat more structure in the -help output. It
- also shows how you can ‘steal’ the remainder of the input
- arguments past a certain point, for programs that accept a
- list of items. It also shows the special argp KEY value
- ARGP_KEY_NO_ARGS, which is only given if no non-option
- arguments were supplied to the program.
- For structuring the help output, two features are used,
- *headers* which are entries in the options vector with the
- first four fields being zero, and a two part documentation
- string (in the variable DOC), which allows documentation both
- before and after the options; the two parts of DOC are
- separated by a vertical-tab character (’\v’, or ’\013’). By
- convention, the documentation before the options is just a
- short string saying what the program does, and that afterwards
- is longer, describing the behavior in more detail. All
- documentation strings are automatically filled for output,
- although newlines may be included to force a line break at a
- particular point. All documentation strings are also passed to
- the ‘gettext’ function, for possible translation into the
- current locale. */
- #include <stdlib.h>
- #include <error.h>
- #include <argp.h>
- const char *argp_program_version =
- "argp-ex4 1.0";
- const char *argp_program_bug_address =
- "<bug-gnu-utils@prep.ai.mit.edu>";
- /* Program documentation. */
- static char doc[] =
- "Argp example #4 -- a program with somewhat more complicated\
- options\
- \vThis part of the documentation comes *after* the options;\
- note that the text is automatically filled, but it's possible\
- to force a line-break, e.g.\n<-- here.";
- /* A description of the arguments we accept. */
- static char args_doc[] = "ARG1 [STRING...]";
- /* Keys for options without short-options. */
- #define OPT_ABORT 1 /* –abort */
- /* The options we understand. */
- static struct argp_option options[] = {
- {"verbose", 'v', 0, 0, "Produce verbose output" },
- {"quiet", 'q', 0, 0, "Don't produce any output" },
- {"silent", 's', 0, OPTION_ALIAS },
- {"output", 'o', "FILE", 0,
- "Output to FILE instead of standard output" },
- {0,0,0,0, "The following options should be grouped together:" },
- {"repeat", 'r', "COUNT", OPTION_ARG_OPTIONAL,
- "Repeat the output COUNT (default 10) times"},
- {"abort", OPT_ABORT, 0, 0, "Abort before showing any output"},
- { 0 }
- };
- /* Used by ‘main’ to communicate with ‘parse_opt’. */
- struct arguments
- {
- char *arg1; /* ARG1 */
- char **strings; /* [STRING…] */
- int silent, verbose, abort; /* ‘-s’, ‘-v’, ‘--abort’ */
- char *output_file; /* FILE arg to ‘--output’ */
- int repeat_count; /* COUNT arg to ‘--repeat’ */
- };
- /* Parse a single option. */
- static error_t
- parse_opt (int key, char *arg, struct argp_state *state)
- {
- /* Get the ‘input’ argument from ‘argp_parse’, which we
- know is a pointer to our arguments structure. */
- struct arguments *arguments = state->input;
- switch (key)
- {
- case 'q': case 's':
- arguments->silent = 1;
- break;
- case 'v':
- arguments->verbose = 1;
- break;
- case 'o':
- arguments->output_file = arg;
- break;
- case 'r':
- arguments->repeat_count = arg ? atoi (arg) : 10;
- break;
- case OPT_ABORT:
- arguments->abort = 1;
- break;
- case ARGP_KEY_NO_ARGS:
- argp_usage (state);
- case ARGP_KEY_ARG:
- /* Here we know that ‘state->arg_num == 0’, since we
- force argument parsing to end before any more arguments can
- get here. */
- arguments->arg1 = arg;
- /* Now we consume all the rest of the arguments.
- ‘state->next’ is the index in ‘state->argv’ of the
- next argument to be parsed, which is the first STRING
- we’re interested in, so we can just use
- ‘&state->argv[state->next]’ as the value for
- arguments->strings.
- _In addition_, by setting ‘state->next’ to the end
- of the arguments, we can force argp to stop parsing here and
- return. */
- arguments->strings = &state->argv[state->next];
- state->next = state->argc;
- break;
- default:
- return ARGP_ERR_UNKNOWN;
- }
- return 0;
- }
- /* Our argp parser. */
- static struct argp argp = { options, parse_opt, args_doc, doc };
- int
- main (int argc, char **argv)
- {
- int i, j;
- struct arguments arguments;
- /* Default values. */
- arguments.silent = 0;
- arguments.verbose = 0;
- arguments.output_file = "-";
- arguments.repeat_count = 1;
- arguments.abort = 0;
- /* Parse our arguments; every option seen by ‘parse_opt’ will be
- reflected in ‘arguments’. */
- argp_parse (&argp, argc, argv, 0, 0, &arguments);
- if (arguments.abort)
- error (10, 0, "ABORTED");
- for (i = 0; i < arguments.repeat_count; i++)
- {
- printf ("ARG1 = %s\n", arguments.arg1);
- printf ("STRINGS = ");
- for (j = 0; arguments.strings[j]; j++)
- printf (j == 0 ? "%s" : ", %s", arguments.strings[j]);
- printf ("\n");
- printf ("OUTPUT_FILE = %s\nVERBOSE = %s\nSILENT = %s\n",
- arguments.output_file,
- arguments.verbose ? "yes" : "no",
- arguments.silent ? "yes" : "no");
- }
- exit (0);
- }
- File: libc.info, Node: Argp User Customization, Prev: Argp Examples, Up: Argp
- 25.3.12 Argp User Customization
- -------------------------------
- The formatting of argp ‘--help’ output may be controlled to some extent
- by a program’s users, by setting the ‘ARGP_HELP_FMT’ environment
- variable to a comma-separated list of tokens. Whitespace is ignored:
- ‘dup-args’
- ‘no-dup-args’
- These turn "duplicate-argument-mode" on or off. In duplicate
- argument mode, if an option that accepts an argument has multiple
- names, the argument is shown for each name. Otherwise, it is only
- shown for the first long option. A note is subsequently printed so
- the user knows that it applies to other names as well. The default
- is ‘no-dup-args’, which is less consistent, but prettier.
- ‘dup-args-note’
- ‘no-dup-args-note’
- These will enable or disable the note informing the user of
- suppressed option argument duplication. The default is
- ‘dup-args-note’.
- ‘short-opt-col=N’
- This prints the first short option in column N. The default is 2.
- ‘long-opt-col=N’
- This prints the first long option in column N. The default is 6.
- ‘doc-opt-col=N’
- This prints ‘documentation options’ (*note Argp Option Flags::) in
- column N. The default is 2.
- ‘opt-doc-col=N’
- This prints the documentation for options starting in column N.
- The default is 29.
- ‘header-col=N’
- This will indent the group headers that document groups of options
- to column N. The default is 1.
- ‘usage-indent=N’
- This will indent continuation lines in ‘Usage:’ messages to column
- N. The default is 12.
- ‘rmargin=N’
- This will word wrap help output at or before column N. The default
- is 79.
- File: libc.info, Node: Suboptions, Next: Suboptions Example, Prev: Argp, Up: Parsing Program Arguments
- 25.3.12.1 Parsing of Suboptions
- ...............................
- Having a single level of options is sometimes not enough. There might
- be too many options which have to be available or a set of options is
- closely related.
- For this case some programs use suboptions. One of the most
- prominent programs is certainly ‘mount’(8). The ‘-o’ option take one
- argument which itself is a comma separated list of options. To ease the
- programming of code like this the function ‘getsubopt’ is available.
- -- Function: int getsubopt (char **OPTIONP, char *const *TOKENS, char
- **VALUEP)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The OPTIONP parameter must be a pointer to a variable containing
- the address of the string to process. When the function returns,
- the reference is updated to point to the next suboption or to the
- terminating ‘\0’ character if there are no more suboptions
- available.
- The TOKENS parameter references an array of strings containing the
- known suboptions. All strings must be ‘\0’ terminated and to mark
- the end a null pointer must be stored. When ‘getsubopt’ finds a
- possible legal suboption it compares it with all strings available
- in the TOKENS array and returns the index in the string as the
- indicator.
- In case the suboption has an associated value introduced by a ‘=’
- character, a pointer to the value is returned in VALUEP. The
- string is ‘\0’ terminated. If no argument is available VALUEP is
- set to the null pointer. By doing this the caller can check
- whether a necessary value is given or whether no unexpected value
- is present.
- In case the next suboption in the string is not mentioned in the
- TOKENS array the starting address of the suboption including a
- possible value is returned in VALUEP and the return value of the
- function is ‘-1’.
- File: libc.info, Node: Suboptions Example, Prev: Suboptions, Up: Parsing Program Arguments
- 25.3.13 Parsing of Suboptions Example
- -------------------------------------
- The code which might appear in the ‘mount’(8) program is a perfect
- example of the use of ‘getsubopt’:
- #include <stdio.h>
- #include <stdlib.h>
- #include <unistd.h>
- int do_all;
- const char *type;
- int read_size;
- int write_size;
- int read_only;
- enum
- {
- RO_OPTION = 0,
- RW_OPTION,
- READ_SIZE_OPTION,
- WRITE_SIZE_OPTION,
- THE_END
- };
- const char *mount_opts[] =
- {
- [RO_OPTION] = "ro",
- [RW_OPTION] = "rw",
- [READ_SIZE_OPTION] = "rsize",
- [WRITE_SIZE_OPTION] = "wsize",
- [THE_END] = NULL
- };
- int
- main (int argc, char **argv)
- {
- char *subopts, *value;
- int opt;
- while ((opt = getopt (argc, argv, "at:o:")) != -1)
- switch (opt)
- {
- case 'a':
- do_all = 1;
- break;
- case 't':
- type = optarg;
- break;
- case 'o':
- subopts = optarg;
- while (*subopts != '\0')
- switch (getsubopt (&subopts, mount_opts, &value))
- {
- case RO_OPTION:
- read_only = 1;
- break;
- case RW_OPTION:
- read_only = 0;
- break;
- case READ_SIZE_OPTION:
- if (value == NULL)
- abort ();
- read_size = atoi (value);
- break;
- case WRITE_SIZE_OPTION:
- if (value == NULL)
- abort ();
- write_size = atoi (value);
- break;
- default:
- /* Unknown suboption. */
- printf ("Unknown suboption `%s'\n", value);
- break;
- }
- break;
- default:
- abort ();
- }
- /* Do the real work. */
- return 0;
- }
- File: libc.info, Node: Environment Variables, Next: Auxiliary Vector, Prev: Program Arguments, Up: Program Basics
- 25.4 Environment Variables
- ==========================
- When a program is executed, it receives information about the context in
- which it was invoked in two ways. The first mechanism uses the ARGV and
- ARGC arguments to its ‘main’ function, and is discussed in *note Program
- Arguments::. The second mechanism uses "environment variables" and is
- discussed in this section.
- The ARGV mechanism is typically used to pass command-line arguments
- specific to the particular program being invoked. The environment, on
- the other hand, keeps track of information that is shared by many
- programs, changes infrequently, and that is less frequently used.
- The environment variables discussed in this section are the same
- environment variables that you set using assignments and the ‘export’
- command in the shell. Programs executed from the shell inherit all of
- the environment variables from the shell.
- Standard environment variables are used for information about the
- user’s home directory, terminal type, current locale, and so on; you can
- define additional variables for other purposes. The set of all
- environment variables that have values is collectively known as the
- "environment".
- Names of environment variables are case-sensitive and must not
- contain the character ‘=’. System-defined environment variables are
- invariably uppercase.
- The values of environment variables can be anything that can be
- represented as a string. A value must not contain an embedded null
- character, since this is assumed to terminate the string.
- * Menu:
- * Environment Access:: How to get and set the values of
- environment variables.
- * Standard Environment:: These environment variables have
- standard interpretations.
- File: libc.info, Node: Environment Access, Next: Standard Environment, Up: Environment Variables
- 25.4.1 Environment Access
- -------------------------
- The value of an environment variable can be accessed with the ‘getenv’
- function. This is declared in the header file ‘stdlib.h’.
- Libraries should use ‘secure_getenv’ instead of ‘getenv’, so that
- they do not accidentally use untrusted environment variables.
- Modifications of environment variables are not allowed in multi-threaded
- programs. The ‘getenv’ and ‘secure_getenv’ functions can be safely used
- in multi-threaded programs.
- -- Function: char * getenv (const char *NAME)
- Preliminary: | MT-Safe env | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function returns a string that is the value of the environment
- variable NAME. You must not modify this string. In some non-Unix
- systems not using the GNU C Library, it might be overwritten by
- subsequent calls to ‘getenv’ (but not by any other library
- function). If the environment variable NAME is not defined, the
- value is a null pointer.
- -- Function: char * secure_getenv (const char *NAME)
- Preliminary: | MT-Safe env | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function is similar to ‘getenv’, but it returns a null pointer
- if the environment is untrusted. This happens when the program
- file has SUID or SGID bits set. General-purpose libraries should
- always prefer this function over ‘getenv’ to avoid vulnerabilities
- if the library is referenced from a SUID/SGID program.
- This function is a GNU extension.
- -- Function: int putenv (char *STRING)
- Preliminary: | MT-Unsafe const:env | AS-Unsafe heap lock |
- AC-Unsafe corrupt lock mem | *Note POSIX Safety Concepts::.
- The ‘putenv’ function adds or removes definitions from the
- environment. If the STRING is of the form ‘NAME=VALUE’, the
- definition is added to the environment. Otherwise, the STRING is
- interpreted as the name of an environment variable, and any
- definition for this variable in the environment is removed.
- If the function is successful it returns ‘0’. Otherwise the return
- value is nonzero and ‘errno’ is set to indicate the error.
- The difference to the ‘setenv’ function is that the exact string
- given as the parameter STRING is put into the environment. If the
- user should change the string after the ‘putenv’ call this will
- reflect automatically in the environment. This also requires that
- STRING not be an automatic variable whose scope is left before the
- variable is removed from the environment. The same applies of
- course to dynamically allocated variables which are freed later.
- This function is part of the extended Unix interface. You should
- define _XOPEN_SOURCE before including any header.
- -- Function: int setenv (const char *NAME, const char *VALUE, int
- REPLACE)
- Preliminary: | MT-Unsafe const:env | AS-Unsafe heap lock |
- AC-Unsafe corrupt lock mem | *Note POSIX Safety Concepts::.
- The ‘setenv’ function can be used to add a new definition to the
- environment. The entry with the name NAME is replaced by the value
- ‘NAME=VALUE’. Please note that this is also true if VALUE is the
- empty string. To do this a new string is created and the strings
- NAME and VALUE are copied. A null pointer for the VALUE parameter
- is illegal. If the environment already contains an entry with key
- NAME the REPLACE parameter controls the action. If replace is
- zero, nothing happens. Otherwise the old entry is replaced by the
- new one.
- Please note that you cannot remove an entry completely using this
- function.
- If the function is successful it returns ‘0’. Otherwise the
- environment is unchanged and the return value is ‘-1’ and ‘errno’
- is set.
- This function was originally part of the BSD library but is now
- part of the Unix standard.
- -- Function: int unsetenv (const char *NAME)
- Preliminary: | MT-Unsafe const:env | AS-Unsafe lock | AC-Unsafe
- lock | *Note POSIX Safety Concepts::.
- Using this function one can remove an entry completely from the
- environment. If the environment contains an entry with the key
- NAME this whole entry is removed. A call to this function is
- equivalent to a call to ‘putenv’ when the VALUE part of the string
- is empty.
- The function returns ‘-1’ if NAME is a null pointer, points to an
- empty string, or points to a string containing a ‘=’ character. It
- returns ‘0’ if the call succeeded.
- This function was originally part of the BSD library but is now
- part of the Unix standard. The BSD version had no return value,
- though.
- There is one more function to modify the whole environment. This
- function is said to be used in the POSIX.9 (POSIX bindings for Fortran
- 77) and so one should expect it did made it into POSIX.1. But this
- never happened. But we still provide this function as a GNU extension
- to enable writing standard compliant Fortran environments.
- -- Function: int clearenv (void)
- Preliminary: | MT-Unsafe const:env | AS-Unsafe heap lock |
- AC-Unsafe lock mem | *Note POSIX Safety Concepts::.
- The ‘clearenv’ function removes all entries from the environment.
- Using ‘putenv’ and ‘setenv’ new entries can be added again later.
- If the function is successful it returns ‘0’. Otherwise the return
- value is nonzero.
- You can deal directly with the underlying representation of
- environment objects to add more variables to the environment (for
- example, to communicate with another program you are about to execute;
- *note Executing a File::).
- -- Variable: char ** environ
- The environment is represented as an array of strings. Each string
- is of the format ‘NAME=VALUE’. The order in which strings appear
- in the environment is not significant, but the same NAME must not
- appear more than once. The last element of the array is a null
- pointer.
- This variable is declared in the header file ‘unistd.h’.
- If you just want to get the value of an environment variable, use
- ‘getenv’.
- Unix systems, and GNU systems, pass the initial value of ‘environ’ as
- the third argument to ‘main’. *Note Program Arguments::.
- File: libc.info, Node: Standard Environment, Prev: Environment Access, Up: Environment Variables
- 25.4.2 Standard Environment Variables
- -------------------------------------
- These environment variables have standard meanings. This doesn’t mean
- that they are always present in the environment; but if these variables
- _are_ present, they have these meanings. You shouldn’t try to use these
- environment variable names for some other purpose.
- ‘HOME’
- This is a string representing the user’s "home directory", or
- initial default working directory.
- The user can set ‘HOME’ to any value. If you need to make sure to
- obtain the proper home directory for a particular user, you should
- not use ‘HOME’; instead, look up the user’s name in the user
- database (*note User Database::).
- For most purposes, it is better to use ‘HOME’, precisely because
- this lets the user specify the value.
- ‘LOGNAME’
- This is the name that the user used to log in. Since the value in
- the environment can be tweaked arbitrarily, this is not a reliable
- way to identify the user who is running a program; a function like
- ‘getlogin’ (*note Who Logged In::) is better for that purpose.
- For most purposes, it is better to use ‘LOGNAME’, precisely because
- this lets the user specify the value.
- ‘PATH’
- A "path" is a sequence of directory names which is used for
- searching for a file. The variable ‘PATH’ holds a path used for
- searching for programs to be run.
- The ‘execlp’ and ‘execvp’ functions (*note Executing a File::) use
- this environment variable, as do many shells and other utilities
- which are implemented in terms of those functions.
- The syntax of a path is a sequence of directory names separated by
- colons. An empty string instead of a directory name stands for the
- current directory (*note Working Directory::).
- A typical value for this environment variable might be a string
- like:
- :/bin:/etc:/usr/bin:/usr/new/X11:/usr/new:/usr/local/bin
- This means that if the user tries to execute a program named ‘foo’,
- the system will look for files named ‘foo’, ‘/bin/foo’, ‘/etc/foo’,
- and so on. The first of these files that exists is the one that is
- executed.
- ‘TERM’
- This specifies the kind of terminal that is receiving program
- output. Some programs can make use of this information to take
- advantage of special escape sequences or terminal modes supported
- by particular kinds of terminals. Many programs which use the
- termcap library (*note Find: (termcap)Finding a Terminal
- Description.) use the ‘TERM’ environment variable, for example.
- ‘TZ’
- This specifies the time zone. *Note TZ Variable::, for information
- about the format of this string and how it is used.
- ‘LANG’
- This specifies the default locale to use for attribute categories
- where neither ‘LC_ALL’ nor the specific environment variable for
- that category is set. *Note Locales::, for more information about
- locales.
- ‘LC_ALL’
- If this environment variable is set it overrides the selection for
- all the locales done using the other ‘LC_*’ environment variables.
- The value of the other ‘LC_*’ environment variables is simply
- ignored in this case.
- ‘LC_COLLATE’
- This specifies what locale to use for string sorting.
- ‘LC_CTYPE’
- This specifies what locale to use for character sets and character
- classification.
- ‘LC_MESSAGES’
- This specifies what locale to use for printing messages and to
- parse responses.
- ‘LC_MONETARY’
- This specifies what locale to use for formatting monetary values.
- ‘LC_NUMERIC’
- This specifies what locale to use for formatting numbers.
- ‘LC_TIME’
- This specifies what locale to use for formatting date/time values.
- ‘NLSPATH’
- This specifies the directories in which the ‘catopen’ function
- looks for message translation catalogs.
- ‘_POSIX_OPTION_ORDER’
- If this environment variable is defined, it suppresses the usual
- reordering of command line arguments by ‘getopt’ and ‘argp_parse’.
- *Note Argument Syntax::.
- File: libc.info, Node: Auxiliary Vector, Next: System Calls, Prev: Environment Variables, Up: Program Basics
- 25.5 Auxiliary Vector
- =====================
- When a program is executed, it receives information from the operating
- system about the environment in which it is operating. The form of this
- information is a table of key-value pairs, where the keys are from the
- set of ‘AT_’ values in ‘elf.h’. Some of the data is provided by the
- kernel for libc consumption, and may be obtained by ordinary interfaces,
- such as ‘sysconf’. However, on a platform-by-platform basis there may
- be information that is not available any other way.
- 25.5.1 Definition of ‘getauxval’
- --------------------------------
- -- Function: unsigned long int getauxval (unsigned long int TYPE)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function is used to inquire about the entries in the auxiliary
- vector. The TYPE argument should be one of the ‘AT_’ symbols
- defined in ‘elf.h’. If a matching entry is found, the value is
- returned; if the entry is not found, zero is returned and ‘errno’
- is set to ‘ENOENT’.
- For some platforms, the key ‘AT_HWCAP’ is the easiest way to inquire
- about any instruction set extensions available at runtime. In this
- case, there will (of necessity) be a platform-specific set of ‘HWCAP_’
- values masked together that describe the capabilities of the cpu on
- which the program is being executed.
- File: libc.info, Node: System Calls, Next: Program Termination, Prev: Auxiliary Vector, Up: Program Basics
- 25.6 System Calls
- =================
- A system call is a request for service that a program makes of the
- kernel. The service is generally something that only the kernel has the
- privilege to do, such as doing I/O. Programmers don’t normally need to
- be concerned with system calls because there are functions in the GNU C
- Library to do virtually everything that system calls do. These
- functions work by making system calls themselves. For example, there is
- a system call that changes the permissions of a file, but you don’t need
- to know about it because you can just use the GNU C Library’s ‘chmod’
- function.
- System calls are sometimes called kernel calls.
- However, there are times when you want to make a system call
- explicitly, and for that, the GNU C Library provides the ‘syscall’
- function. ‘syscall’ is harder to use and less portable than functions
- like ‘chmod’, but easier and more portable than coding the system call
- in assembler instructions.
- ‘syscall’ is most useful when you are working with a system call
- which is special to your system or is newer than the GNU C Library you
- are using. ‘syscall’ is implemented in an entirely generic way; the
- function does not know anything about what a particular system call does
- or even if it is valid.
- The description of ‘syscall’ in this section assumes a certain
- protocol for system calls on the various platforms on which the GNU C
- Library runs. That protocol is not defined by any strong authority, but
- we won’t describe it here either because anyone who is coding ‘syscall’
- probably won’t accept anything less than kernel and C library source
- code as a specification of the interface between them anyway.
- ‘syscall’ is declared in ‘unistd.h’.
- -- Function: long int syscall (long int SYSNO, …)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- ‘syscall’ performs a generic system call.
- SYSNO is the system call number. Each kind of system call is
- identified by a number. Macros for all the possible system call
- numbers are defined in ‘sys/syscall.h’
- The remaining arguments are the arguments for the system call, in
- order, and their meanings depend on the kind of system call. Each
- kind of system call has a definite number of arguments, from zero
- to five. If you code more arguments than the system call takes,
- the extra ones to the right are ignored.
- The return value is the return value from the system call, unless
- the system call failed. In that case, ‘syscall’ returns ‘-1’ and
- sets ‘errno’ to an error code that the system call returned. Note
- that system calls do not return ‘-1’ when they succeed.
- If you specify an invalid SYSNO, ‘syscall’ returns ‘-1’ with
- ‘errno’ = ‘ENOSYS’.
- Example:
- #include <unistd.h>
- #include <sys/syscall.h>
- #include <errno.h>
- …
- int rc;
- rc = syscall(SYS_chmod, "/etc/passwd", 0444);
- if (rc == -1)
- fprintf(stderr, "chmod failed, errno = %d\n", errno);
- This, if all the compatibility stars are aligned, is equivalent to
- the following preferable code:
- #include <sys/types.h>
- #include <sys/stat.h>
- #include <errno.h>
- …
- int rc;
- rc = chmod("/etc/passwd", 0444);
- if (rc == -1)
- fprintf(stderr, "chmod failed, errno = %d\n", errno);
- File: libc.info, Node: Program Termination, Prev: System Calls, Up: Program Basics
- 25.7 Program Termination
- ========================
- The usual way for a program to terminate is simply for its ‘main’
- function to return. The "exit status value" returned from the ‘main’
- function is used to report information back to the process’s parent
- process or shell.
- A program can also terminate normally by calling the ‘exit’ function.
- In addition, programs can be terminated by signals; this is discussed
- in more detail in *note Signal Handling::. The ‘abort’ function causes
- a signal that kills the program.
- * Menu:
- * Normal Termination:: If a program calls ‘exit’, a
- process terminates normally.
- * Exit Status:: The ‘exit status’ provides information
- about why the process terminated.
- * Cleanups on Exit:: A process can run its own cleanup
- functions upon normal termination.
- * Aborting a Program:: The ‘abort’ function causes
- abnormal program termination.
- * Termination Internals:: What happens when a process terminates.
- File: libc.info, Node: Normal Termination, Next: Exit Status, Up: Program Termination
- 25.7.1 Normal Termination
- -------------------------
- A process terminates normally when its program signals it is done by
- calling ‘exit’. Returning from ‘main’ is equivalent to calling ‘exit’,
- and the value that ‘main’ returns is used as the argument to ‘exit’.
- -- Function: void exit (int STATUS)
- Preliminary: | MT-Unsafe race:exit | AS-Unsafe corrupt | AC-Unsafe
- corrupt lock | *Note POSIX Safety Concepts::.
- The ‘exit’ function tells the system that the program is done,
- which causes it to terminate the process.
- STATUS is the program’s exit status, which becomes part of the
- process’ termination status. This function does not return.
- Normal termination causes the following actions:
- 1. Functions that were registered with the ‘atexit’ or ‘on_exit’
- functions are called in the reverse order of their registration.
- This mechanism allows your application to specify its own “cleanup”
- actions to be performed at program termination. Typically, this is
- used to do things like saving program state information in a file,
- or unlocking locks in shared data bases.
- 2. All open streams are closed, writing out any buffered output data.
- See *note Closing Streams::. In addition, temporary files opened
- with the ‘tmpfile’ function are removed; see *note Temporary
- Files::.
- 3. ‘_exit’ is called, terminating the program. *Note Termination
- Internals::.
- File: libc.info, Node: Exit Status, Next: Cleanups on Exit, Prev: Normal Termination, Up: Program Termination
- 25.7.2 Exit Status
- ------------------
- When a program exits, it can return to the parent process a small amount
- of information about the cause of termination, using the "exit status".
- This is a value between 0 and 255 that the exiting process passes as an
- argument to ‘exit’.
- Normally you should use the exit status to report very broad
- information about success or failure. You can’t provide a lot of detail
- about the reasons for the failure, and most parent processes would not
- want much detail anyway.
- There are conventions for what sorts of status values certain
- programs should return. The most common convention is simply 0 for
- success and 1 for failure. Programs that perform comparison use a
- different convention: they use status 1 to indicate a mismatch, and
- status 2 to indicate an inability to compare. Your program should
- follow an existing convention if an existing convention makes sense for
- it.
- A general convention reserves status values 128 and up for special
- purposes. In particular, the value 128 is used to indicate failure to
- execute another program in a subprocess. This convention is not
- universally obeyed, but it is a good idea to follow it in your programs.
- *Warning:* Don’t try to use the number of errors as the exit status.
- This is actually not very useful; a parent process would generally not
- care how many errors occurred. Worse than that, it does not work,
- because the status value is truncated to eight bits. Thus, if the
- program tried to report 256 errors, the parent would receive a report of
- 0 errors—that is, success.
- For the same reason, it does not work to use the value of ‘errno’ as
- the exit status—these can exceed 255.
- *Portability note:* Some non-POSIX systems use different conventions
- for exit status values. For greater portability, you can use the macros
- ‘EXIT_SUCCESS’ and ‘EXIT_FAILURE’ for the conventional status value for
- success and failure, respectively. They are declared in the file
- ‘stdlib.h’.
- -- Macro: int EXIT_SUCCESS
- This macro can be used with the ‘exit’ function to indicate
- successful program completion.
- On POSIX systems, the value of this macro is ‘0’. On other
- systems, the value might be some other (possibly non-constant)
- integer expression.
- -- Macro: int EXIT_FAILURE
- This macro can be used with the ‘exit’ function to indicate
- unsuccessful program completion in a general sense.
- On POSIX systems, the value of this macro is ‘1’. On other
- systems, the value might be some other (possibly non-constant)
- integer expression. Other nonzero status values also indicate
- failures. Certain programs use different nonzero status values to
- indicate particular kinds of "non-success". For example, ‘diff’
- uses status value ‘1’ to mean that the files are different, and ‘2’
- or more to mean that there was difficulty in opening the files.
- Don’t confuse a program’s exit status with a process’ termination
- status. There are lots of ways a process can terminate besides having
- its program finish. In the event that the process termination _is_
- caused by program termination (i.e., ‘exit’), though, the program’s exit
- status becomes part of the process’ termination status.
- File: libc.info, Node: Cleanups on Exit, Next: Aborting a Program, Prev: Exit Status, Up: Program Termination
- 25.7.3 Cleanups on Exit
- -----------------------
- Your program can arrange to run its own cleanup functions if normal
- termination happens. If you are writing a library for use in various
- application programs, then it is unreliable to insist that all
- applications call the library’s cleanup functions explicitly before
- exiting. It is much more robust to make the cleanup invisible to the
- application, by setting up a cleanup function in the library itself
- using ‘atexit’ or ‘on_exit’.
- -- Function: int atexit (void (*FUNCTION) (void))
- Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock mem |
- *Note POSIX Safety Concepts::.
- The ‘atexit’ function registers the function FUNCTION to be called
- at normal program termination. The FUNCTION is called with no
- arguments.
- The return value from ‘atexit’ is zero on success and nonzero if
- the function cannot be registered.
- -- Function: int on_exit (void (*FUNCTION)(int STATUS, void *ARG), void
- *ARG)
- Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock mem |
- *Note POSIX Safety Concepts::.
- This function is a somewhat more powerful variant of ‘atexit’. It
- accepts two arguments, a function FUNCTION and an arbitrary pointer
- ARG. At normal program termination, the FUNCTION is called with
- two arguments: the STATUS value passed to ‘exit’, and the ARG.
- This function is included in the GNU C Library only for
- compatibility for SunOS, and may not be supported by other
- implementations.
- Here’s a trivial program that illustrates the use of ‘exit’ and
- ‘atexit’:
- #include <stdio.h>
- #include <stdlib.h>
- void
- bye (void)
- {
- puts ("Goodbye, cruel world....");
- }
- int
- main (void)
- {
- atexit (bye);
- exit (EXIT_SUCCESS);
- }
- When this program is executed, it just prints the message and exits.
- File: libc.info, Node: Aborting a Program, Next: Termination Internals, Prev: Cleanups on Exit, Up: Program Termination
- 25.7.4 Aborting a Program
- -------------------------
- You can abort your program using the ‘abort’ function. The prototype
- for this function is in ‘stdlib.h’.
- -- Function: void abort (void)
- Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe lock corrupt
- | *Note POSIX Safety Concepts::.
- The ‘abort’ function causes abnormal program termination. This
- does not execute cleanup functions registered with ‘atexit’ or
- ‘on_exit’.
- This function actually terminates the process by raising a
- ‘SIGABRT’ signal, and your program can include a handler to
- intercept this signal; see *note Signal Handling::.
- *Future Change Warning:* Proposed Federal censorship regulations may
- prohibit us from giving you information about the possibility of calling
- this function. We would be required to say that this is not an
- acceptable way of terminating a program.
- File: libc.info, Node: Termination Internals, Prev: Aborting a Program, Up: Program Termination
- 25.7.5 Termination Internals
- ----------------------------
- The ‘_exit’ function is the primitive used for process termination by
- ‘exit’. It is declared in the header file ‘unistd.h’.
- -- Function: void _exit (int STATUS)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘_exit’ function is the primitive for causing a process to
- terminate with status STATUS. Calling this function does not
- execute cleanup functions registered with ‘atexit’ or ‘on_exit’.
- -- Function: void _Exit (int STATUS)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘_Exit’ function is the ISO C equivalent to ‘_exit’. The ISO C
- committee members were not sure whether the definitions of ‘_exit’
- and ‘_Exit’ were compatible so they have not used the POSIX name.
- This function was introduced in ISO C99 and is declared in
- ‘stdlib.h’.
- When a process terminates for any reason—either because the program
- terminates, or as a result of a signal—the following things happen:
- • All open file descriptors in the process are closed. *Note
- Low-Level I/O::. Note that streams are not flushed automatically
- when the process terminates; see *note I/O on Streams::.
- • A process exit status is saved to be reported back to the parent
- process via ‘wait’ or ‘waitpid’; see *note Process Completion::.
- If the program exited, this status includes as its low-order 8 bits
- the program exit status.
- • Any child processes of the process being terminated are assigned a
- new parent process. (On most systems, including GNU, this is the
- ‘init’ process, with process ID 1.)
- • A ‘SIGCHLD’ signal is sent to the parent process.
- • If the process is a session leader that has a controlling terminal,
- then a ‘SIGHUP’ signal is sent to each process in the foreground
- job, and the controlling terminal is disassociated from that
- session. *Note Job Control::.
- • If termination of a process causes a process group to become
- orphaned, and any member of that process group is stopped, then a
- ‘SIGHUP’ signal and a ‘SIGCONT’ signal are sent to each process in
- the group. *Note Job Control::.
- File: libc.info, Node: Processes, Next: Inter-Process Communication, Prev: Program Basics, Up: Top
- 26 Processes
- ************
- "Processes" are the primitive units for allocation of system resources.
- Each process has its own address space and (usually) one thread of
- control. A process executes a program; you can have multiple processes
- executing the same program, but each process has its own copy of the
- program within its own address space and executes it independently of
- the other copies.
- Processes are organized hierarchically. Each process has a "parent
- process" which explicitly arranged to create it. The processes created
- by a given parent are called its "child processes". A child inherits
- many of its attributes from the parent process.
- This chapter describes how a program can create, terminate, and
- control child processes. Actually, there are three distinct operations
- involved: creating a new child process, causing the new process to
- execute a program, and coordinating the completion of the child process
- with the original program.
- The ‘system’ function provides a simple, portable mechanism for
- running another program; it does all three steps automatically. If you
- need more control over the details of how this is done, you can use the
- primitive functions to do each step individually instead.
- * Menu:
- * Running a Command:: The easy way to run another program.
- * Process Creation Concepts:: An overview of the hard way to do it.
- * Process Identification:: How to get the process ID of a process.
- * Creating a Process:: How to fork a child process.
- * Executing a File:: How to make a process execute another program.
- * Process Completion:: How to tell when a child process has completed.
- * Process Completion Status:: How to interpret the status value
- returned from a child process.
- * BSD Wait Functions:: More functions, for backward compatibility.
- * Process Creation Example:: A complete example program.
- File: libc.info, Node: Running a Command, Next: Process Creation Concepts, Up: Processes
- 26.1 Running a Command
- ======================
- The easy way to run another program is to use the ‘system’ function.
- This function does all the work of running a subprogram, but it doesn’t
- give you much control over the details: you have to wait until the
- subprogram terminates before you can do anything else.
- -- Function: int system (const char *COMMAND)
- Preliminary: | MT-Safe | AS-Unsafe plugin heap lock | AC-Unsafe
- lock mem | *Note POSIX Safety Concepts::.
- This function executes COMMAND as a shell command. In the GNU C
- Library, it always uses the default shell ‘sh’ to run the command.
- In particular, it searches the directories in ‘PATH’ to find
- programs to execute. The return value is ‘-1’ if it wasn’t
- possible to create the shell process, and otherwise is the status
- of the shell process. *Note Process Completion::, for details on
- how this status code can be interpreted.
- If the COMMAND argument is a null pointer, a return value of zero
- indicates that no command processor is available.
- This function is a cancellation point in multi-threaded programs.
- This is a problem if the thread allocates some resources (like
- memory, file descriptors, semaphores or whatever) at the time
- ‘system’ is called. If the thread gets canceled these resources
- stay allocated until the program ends. To avoid this calls to
- ‘system’ should be protected using cancellation handlers.
- The ‘system’ function is declared in the header file ‘stdlib.h’.
- *Portability Note:* Some C implementations may not have any notion of
- a command processor that can execute other programs. You can determine
- whether a command processor exists by executing ‘system (NULL)’; if the
- return value is nonzero, a command processor is available.
- The ‘popen’ and ‘pclose’ functions (*note Pipe to a Subprocess::) are
- closely related to the ‘system’ function. They allow the parent process
- to communicate with the standard input and output channels of the
- command being executed.
- File: libc.info, Node: Process Creation Concepts, Next: Process Identification, Prev: Running a Command, Up: Processes
- 26.2 Process Creation Concepts
- ==============================
- This section gives an overview of processes and of the steps involved in
- creating a process and making it run another program.
- Each process is named by a "process ID" number. A unique process ID
- is allocated to each process when it is created. The "lifetime" of a
- process ends when its termination is reported to its parent process; at
- that time, all of the process resources, including its process ID, are
- freed.
- Processes are created with the ‘fork’ system call (so the operation
- of creating a new process is sometimes called "forking" a process). The
- "child process" created by ‘fork’ is a copy of the original "parent
- process", except that it has its own process ID.
- After forking a child process, both the parent and child processes
- continue to execute normally. If you want your program to wait for a
- child process to finish executing before continuing, you must do this
- explicitly after the fork operation, by calling ‘wait’ or ‘waitpid’
- (*note Process Completion::). These functions give you limited
- information about why the child terminated—for example, its exit status
- code.
- A newly forked child process continues to execute the same program as
- its parent process, at the point where the ‘fork’ call returns. You can
- use the return value from ‘fork’ to tell whether the program is running
- in the parent process or the child.
- Having several processes run the same program is only occasionally
- useful. But the child can execute another program using one of the
- ‘exec’ functions; see *note Executing a File::. The program that the
- process is executing is called its "process image". Starting execution
- of a new program causes the process to forget all about its previous
- process image; when the new program exits, the process exits too,
- instead of returning to the previous process image.
- File: libc.info, Node: Process Identification, Next: Creating a Process, Prev: Process Creation Concepts, Up: Processes
- 26.3 Process Identification
- ===========================
- The ‘pid_t’ data type represents process IDs. You can get the process
- ID of a process by calling ‘getpid’. The function ‘getppid’ returns the
- process ID of the parent of the current process (this is also known as
- the "parent process ID"). Your program should include the header files
- ‘unistd.h’ and ‘sys/types.h’ to use these functions.
- -- Data Type: pid_t
- The ‘pid_t’ data type is a signed integer type which is capable of
- representing a process ID. In the GNU C Library, this is an ‘int’.
- -- Function: pid_t getpid (void)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘getpid’ function returns the process ID of the current
- process.
- -- Function: pid_t getppid (void)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘getppid’ function returns the process ID of the parent of the
- current process.
- File: libc.info, Node: Creating a Process, Next: Executing a File, Prev: Process Identification, Up: Processes
- 26.4 Creating a Process
- =======================
- The ‘fork’ function is the primitive for creating a process. It is
- declared in the header file ‘unistd.h’.
- -- Function: pid_t fork (void)
- Preliminary: | MT-Safe | AS-Unsafe plugin | AC-Unsafe lock | *Note
- POSIX Safety Concepts::.
- The ‘fork’ function creates a new process.
- If the operation is successful, there are then both parent and
- child processes and both see ‘fork’ return, but with different
- values: it returns a value of ‘0’ in the child process and returns
- the child’s process ID in the parent process.
- If process creation failed, ‘fork’ returns a value of ‘-1’ in the
- parent process. The following ‘errno’ error conditions are defined
- for ‘fork’:
- ‘EAGAIN’
- There aren’t enough system resources to create another
- process, or the user already has too many processes running.
- This means exceeding the ‘RLIMIT_NPROC’ resource limit, which
- can usually be increased; *note Limits on Resources::.
- ‘ENOMEM’
- The process requires more space than the system can supply.
- The specific attributes of the child process that differ from the
- parent process are:
- • The child process has its own unique process ID.
- • The parent process ID of the child process is the process ID of its
- parent process.
- • The child process gets its own copies of the parent process’s open
- file descriptors. Subsequently changing attributes of the file
- descriptors in the parent process won’t affect the file descriptors
- in the child, and vice versa. *Note Control Operations::.
- However, the file position associated with each descriptor is
- shared by both processes; *note File Position::.
- • The elapsed processor times for the child process are set to zero;
- see *note Processor Time::.
- • The child doesn’t inherit file locks set by the parent process.
- *Note Control Operations::.
- • The child doesn’t inherit alarms set by the parent process. *Note
- Setting an Alarm::.
- • The set of pending signals (*note Delivery of Signal::) for the
- child process is cleared. (The child process inherits its mask of
- blocked signals and signal actions from the parent process.)
- -- Function: pid_t vfork (void)
- Preliminary: | MT-Safe | AS-Unsafe plugin | AC-Unsafe lock | *Note
- POSIX Safety Concepts::.
- The ‘vfork’ function is similar to ‘fork’ but on some systems it is
- more efficient; however, there are restrictions you must follow to
- use it safely.
- While ‘fork’ makes a complete copy of the calling process’s address
- space and allows both the parent and child to execute
- independently, ‘vfork’ does not make this copy. Instead, the child
- process created with ‘vfork’ shares its parent’s address space
- until it calls ‘_exit’ or one of the ‘exec’ functions. In the
- meantime, the parent process suspends execution.
- You must be very careful not to allow the child process created
- with ‘vfork’ to modify any global data or even local variables
- shared with the parent. Furthermore, the child process cannot
- return from (or do a long jump out of) the function that called
- ‘vfork’! This would leave the parent process’s control information
- very confused. If in doubt, use ‘fork’ instead.
- Some operating systems don’t really implement ‘vfork’. The GNU C
- Library permits you to use ‘vfork’ on all systems, but actually
- executes ‘fork’ if ‘vfork’ isn’t available. If you follow the
- proper precautions for using ‘vfork’, your program will still work
- even if the system uses ‘fork’ instead.
- File: libc.info, Node: Executing a File, Next: Process Completion, Prev: Creating a Process, Up: Processes
- 26.5 Executing a File
- =====================
- This section describes the ‘exec’ family of functions, for executing a
- file as a process image. You can use these functions to make a child
- process execute a new program after it has been forked.
- To see the effects of ‘exec’ from the point of view of the called
- program, see *note Program Basics::.
- The functions in this family differ in how you specify the arguments,
- but otherwise they all do the same thing. They are declared in the
- header file ‘unistd.h’.
- -- Function: int execv (const char *FILENAME, char *const ARGV[])
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘execv’ function executes the file named by FILENAME as a new
- process image.
- The ARGV argument is an array of null-terminated strings that is
- used to provide a value for the ‘argv’ argument to the ‘main’
- function of the program to be executed. The last element of this
- array must be a null pointer. By convention, the first element of
- this array is the file name of the program sans directory names.
- *Note Program Arguments::, for full details on how programs can
- access these arguments.
- The environment for the new process image is taken from the
- ‘environ’ variable of the current process image; see *note
- Environment Variables::, for information about environments.
- -- Function: int execl (const char *FILENAME, const char *ARG0, …)
- Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
- POSIX Safety Concepts::.
- This is similar to ‘execv’, but the ARGV strings are specified
- individually instead of as an array. A null pointer must be passed
- as the last such argument.
- -- Function: int execve (const char *FILENAME, char *const ARGV[], char
- *const ENV[])
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This is similar to ‘execv’, but permits you to specify the
- environment for the new program explicitly as the ENV argument.
- This should be an array of strings in the same format as for the
- ‘environ’ variable; see *note Environment Access::.
- -- Function: int execle (const char *FILENAME, const char *ARG0, …,
- char *const ENV[])
- Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | *Note
- POSIX Safety Concepts::.
- This is similar to ‘execl’, but permits you to specify the
- environment for the new program explicitly. The environment
- argument is passed following the null pointer that marks the last
- ARGV argument, and should be an array of strings in the same format
- as for the ‘environ’ variable.
- -- Function: int execvp (const char *FILENAME, char *const ARGV[])
- Preliminary: | MT-Safe env | AS-Unsafe heap | AC-Unsafe mem | *Note
- POSIX Safety Concepts::.
- The ‘execvp’ function is similar to ‘execv’, except that it
- searches the directories listed in the ‘PATH’ environment variable
- (*note Standard Environment::) to find the full file name of a file
- from FILENAME if FILENAME does not contain a slash.
- This function is useful for executing system utility programs,
- because it looks for them in the places that the user has chosen.
- Shells use it to run the commands that users type.
- -- Function: int execlp (const char *FILENAME, const char *ARG0, …)
- Preliminary: | MT-Safe env | AS-Unsafe heap | AC-Unsafe mem | *Note
- POSIX Safety Concepts::.
- This function is like ‘execl’, except that it performs the same
- file name searching as the ‘execvp’ function.
- The size of the argument list and environment list taken together
- must not be greater than ‘ARG_MAX’ bytes. *Note General Limits::. On
- GNU/Hurd systems, the size (which compares against ‘ARG_MAX’) includes,
- for each string, the number of characters in the string, plus the size
- of a ‘char *’, plus one, rounded up to a multiple of the size of a ‘char
- *’. Other systems may have somewhat different rules for counting.
- These functions normally don’t return, since execution of a new
- program causes the currently executing program to go away completely. A
- value of ‘-1’ is returned in the event of a failure. In addition to the
- usual file name errors (*note File Name Errors::), the following ‘errno’
- error conditions are defined for these functions:
- ‘E2BIG’
- The combined size of the new program’s argument list and
- environment list is larger than ‘ARG_MAX’ bytes. GNU/Hurd systems
- have no specific limit on the argument list size, so this error
- code cannot result, but you may get ‘ENOMEM’ instead if the
- arguments are too big for available memory.
- ‘ENOEXEC’
- The specified file can’t be executed because it isn’t in the right
- format.
- ‘ENOMEM’
- Executing the specified file requires more storage than is
- available.
- If execution of the new file succeeds, it updates the access time
- field of the file as if the file had been read. *Note File Times::, for
- more details about access times of files.
- The point at which the file is closed again is not specified, but is
- at some point before the process exits or before another process image
- is executed.
- Executing a new process image completely changes the contents of
- memory, copying only the argument and environment strings to new
- locations. But many other attributes of the process are unchanged:
- • The process ID and the parent process ID. *Note Process Creation
- Concepts::.
- • Session and process group membership. *Note Concepts of Job
- Control::.
- • Real user ID and group ID, and supplementary group IDs. *Note
- Process Persona::.
- • Pending alarms. *Note Setting an Alarm::.
- • Current working directory and root directory. *Note Working
- Directory::. On GNU/Hurd systems, the root directory is not copied
- when executing a setuid program; instead the system default root
- directory is used for the new program.
- • File mode creation mask. *Note Setting Permissions::.
- • Process signal mask; see *note Process Signal Mask::.
- • Pending signals; see *note Blocking Signals::.
- • Elapsed processor time associated with the process; see *note
- Processor Time::.
- If the set-user-ID and set-group-ID mode bits of the process image
- file are set, this affects the effective user ID and effective group ID
- (respectively) of the process. These concepts are discussed in detail
- in *note Process Persona::.
- Signals that are set to be ignored in the existing process image are
- also set to be ignored in the new process image. All other signals are
- set to the default action in the new process image. For more
- information about signals, see *note Signal Handling::.
- File descriptors open in the existing process image remain open in
- the new process image, unless they have the ‘FD_CLOEXEC’ (close-on-exec)
- flag set. The files that remain open inherit all attributes of the open
- file descriptors from the existing process image, including file locks.
- File descriptors are discussed in *note Low-Level I/O::.
- Streams, by contrast, cannot survive through ‘exec’ functions,
- because they are located in the memory of the process itself. The new
- process image has no streams except those it creates afresh. Each of
- the streams in the pre-‘exec’ process image has a descriptor inside it,
- and these descriptors do survive through ‘exec’ (provided that they do
- not have ‘FD_CLOEXEC’ set). The new process image can reconnect these
- to new streams using ‘fdopen’ (*note Descriptors and Streams::).
- File: libc.info, Node: Process Completion, Next: Process Completion Status, Prev: Executing a File, Up: Processes
- 26.6 Process Completion
- =======================
- The functions described in this section are used to wait for a child
- process to terminate or stop, and determine its status. These functions
- are declared in the header file ‘sys/wait.h’.
- -- Function: pid_t waitpid (pid_t PID, int *STATUS-PTR, int OPTIONS)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘waitpid’ function is used to request status information from a
- child process whose process ID is PID. Normally, the calling
- process is suspended until the child process makes status
- information available by terminating.
- Other values for the PID argument have special interpretations. A
- value of ‘-1’ or ‘WAIT_ANY’ requests status information for any
- child process; a value of ‘0’ or ‘WAIT_MYPGRP’ requests information
- for any child process in the same process group as the calling
- process; and any other negative value − PGID requests information
- for any child process whose process group ID is PGID.
- If status information for a child process is available immediately,
- this function returns immediately without waiting. If more than
- one eligible child process has status information available, one of
- them is chosen randomly, and its status is returned immediately.
- To get the status from the other eligible child processes, you need
- to call ‘waitpid’ again.
- The OPTIONS argument is a bit mask. Its value should be the
- bitwise OR (that is, the ‘|’ operator) of zero or more of the
- ‘WNOHANG’ and ‘WUNTRACED’ flags. You can use the ‘WNOHANG’ flag to
- indicate that the parent process shouldn’t wait; and the
- ‘WUNTRACED’ flag to request status information from stopped
- processes as well as processes that have terminated.
- The status information from the child process is stored in the
- object that STATUS-PTR points to, unless STATUS-PTR is a null
- pointer.
- This function is a cancellation point in multi-threaded programs.
- This is a problem if the thread allocates some resources (like
- memory, file descriptors, semaphores or whatever) at the time
- ‘waitpid’ is called. If the thread gets canceled these resources
- stay allocated until the program ends. To avoid this calls to
- ‘waitpid’ should be protected using cancellation handlers.
- The return value is normally the process ID of the child process
- whose status is reported. If there are child processes but none of
- them is waiting to be noticed, ‘waitpid’ will block until one is.
- However, if the ‘WNOHANG’ option was specified, ‘waitpid’ will
- return zero instead of blocking.
- If a specific PID to wait for was given to ‘waitpid’, it will
- ignore all other children (if any). Therefore if there are
- children waiting to be noticed but the child whose PID was
- specified is not one of them, ‘waitpid’ will block or return zero
- as described above.
- A value of ‘-1’ is returned in case of error. The following
- ‘errno’ error conditions are defined for this function:
- ‘EINTR’
- The function was interrupted by delivery of a signal to the
- calling process. *Note Interrupted Primitives::.
- ‘ECHILD’
- There are no child processes to wait for, or the specified PID
- is not a child of the calling process.
- ‘EINVAL’
- An invalid value was provided for the OPTIONS argument.
- These symbolic constants are defined as values for the PID argument
- to the ‘waitpid’ function.
- ‘WAIT_ANY’
- This constant macro (whose value is ‘-1’) specifies that ‘waitpid’
- should return status information about any child process.
- ‘WAIT_MYPGRP’
- This constant (with value ‘0’) specifies that ‘waitpid’ should
- return status information about any child process in the same
- process group as the calling process.
- These symbolic constants are defined as flags for the OPTIONS
- argument to the ‘waitpid’ function. You can bitwise-OR the flags
- together to obtain a value to use as the argument.
- ‘WNOHANG’
- This flag specifies that ‘waitpid’ should return immediately
- instead of waiting, if there is no child process ready to be
- noticed.
- ‘WUNTRACED’
- This flag specifies that ‘waitpid’ should report the status of any
- child processes that have been stopped as well as those that have
- terminated.
- -- Function: pid_t wait (int *STATUS-PTR)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This is a simplified version of ‘waitpid’, and is used to wait
- until any one child process terminates. The call:
- wait (&status)
- is exactly equivalent to:
- waitpid (-1, &status, 0)
- This function is a cancellation point in multi-threaded programs.
- This is a problem if the thread allocates some resources (like
- memory, file descriptors, semaphores or whatever) at the time
- ‘wait’ is called. If the thread gets canceled these resources stay
- allocated until the program ends. To avoid this calls to ‘wait’
- should be protected using cancellation handlers.
- -- Function: pid_t wait4 (pid_t PID, int *STATUS-PTR, int OPTIONS,
- struct rusage *USAGE)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- If USAGE is a null pointer, ‘wait4’ is equivalent to ‘waitpid (PID,
- STATUS-PTR, OPTIONS)’.
- If USAGE is not null, ‘wait4’ stores usage figures for the child
- process in ‘*RUSAGE’ (but only if the child has terminated, not if
- it has stopped). *Note Resource Usage::.
- This function is a BSD extension.
- Here’s an example of how to use ‘waitpid’ to get the status from all
- child processes that have terminated, without ever waiting. This
- function is designed to be a handler for ‘SIGCHLD’, the signal that
- indicates that at least one child process has terminated.
- void
- sigchld_handler (int signum)
- {
- int pid, status, serrno;
- serrno = errno;
- while (1)
- {
- pid = waitpid (WAIT_ANY, &status, WNOHANG);
- if (pid < 0)
- {
- perror ("waitpid");
- break;
- }
- if (pid == 0)
- break;
- notice_termination (pid, status);
- }
- errno = serrno;
- }
- File: libc.info, Node: Process Completion Status, Next: BSD Wait Functions, Prev: Process Completion, Up: Processes
- 26.7 Process Completion Status
- ==============================
- If the exit status value (*note Program Termination::) of the child
- process is zero, then the status value reported by ‘waitpid’ or ‘wait’
- is also zero. You can test for other kinds of information encoded in
- the returned status value using the following macros. These macros are
- defined in the header file ‘sys/wait.h’.
- -- Macro: int WIFEXITED (int STATUS)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This macro returns a nonzero value if the child process terminated
- normally with ‘exit’ or ‘_exit’.
- -- Macro: int WEXITSTATUS (int STATUS)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- If ‘WIFEXITED’ is true of STATUS, this macro returns the low-order
- 8 bits of the exit status value from the child process. *Note Exit
- Status::.
- -- Macro: int WIFSIGNALED (int STATUS)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This macro returns a nonzero value if the child process terminated
- because it received a signal that was not handled. *Note Signal
- Handling::.
- -- Macro: int WTERMSIG (int STATUS)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- If ‘WIFSIGNALED’ is true of STATUS, this macro returns the signal
- number of the signal that terminated the child process.
- -- Macro: int WCOREDUMP (int STATUS)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This macro returns a nonzero value if the child process terminated
- and produced a core dump.
- -- Macro: int WIFSTOPPED (int STATUS)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This macro returns a nonzero value if the child process is stopped.
- -- Macro: int WSTOPSIG (int STATUS)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- If ‘WIFSTOPPED’ is true of STATUS, this macro returns the signal
- number of the signal that caused the child process to stop.
- File: libc.info, Node: BSD Wait Functions, Next: Process Creation Example, Prev: Process Completion Status, Up: Processes
- 26.8 BSD Process Wait Function
- ==============================
- The GNU C Library also provides the ‘wait3’ function for compatibility
- with BSD. This function is declared in ‘sys/wait.h’. It is the
- predecessor to ‘wait4’, which is more flexible. ‘wait3’ is now
- obsolete.
- -- Function: pid_t wait3 (int *STATUS-PTR, int OPTIONS, struct rusage
- *USAGE)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- If USAGE is a null pointer, ‘wait3’ is equivalent to ‘waitpid (-1,
- STATUS-PTR, OPTIONS)’.
- If USAGE is not null, ‘wait3’ stores usage figures for the child
- process in ‘*RUSAGE’ (but only if the child has terminated, not if
- it has stopped). *Note Resource Usage::.
- File: libc.info, Node: Process Creation Example, Prev: BSD Wait Functions, Up: Processes
- 26.9 Process Creation Example
- =============================
- Here is an example program showing how you might write a function
- similar to the built-in ‘system’. It executes its COMMAND argument
- using the equivalent of ‘sh -c COMMAND’.
- #include <stddef.h>
- #include <stdlib.h>
- #include <unistd.h>
- #include <sys/types.h>
- #include <sys/wait.h>
- /* Execute the command using this shell program. */
- #define SHELL "/bin/sh"
- int
- my_system (const char *command)
- {
- int status;
- pid_t pid;
- pid = fork ();
- if (pid == 0)
- {
- /* This is the child process. Execute the shell command. */
- execl (SHELL, SHELL, "-c", command, NULL);
- _exit (EXIT_FAILURE);
- }
- else if (pid < 0)
- /* The fork failed. Report failure. */
- status = -1;
- else
- /* This is the parent process. Wait for the child to complete. */
- if (waitpid (pid, &status, 0) != pid)
- status = -1;
- return status;
- }
- There are a couple of things you should pay attention to in this
- example.
- Remember that the first ‘argv’ argument supplied to the program
- represents the name of the program being executed. That is why, in the
- call to ‘execl’, ‘SHELL’ is supplied once to name the program to execute
- and a second time to supply a value for ‘argv[0]’.
- The ‘execl’ call in the child process doesn’t return if it is
- successful. If it fails, you must do something to make the child
- process terminate. Just returning a bad status code with ‘return’ would
- leave two processes running the original program. Instead, the right
- behavior is for the child process to report failure to its parent
- process.
- Call ‘_exit’ to accomplish this. The reason for using ‘_exit’
- instead of ‘exit’ is to avoid flushing fully buffered streams such as
- ‘stdout’. The buffers of these streams probably contain data that was
- copied from the parent process by the ‘fork’, data that will be output
- eventually by the parent process. Calling ‘exit’ in the child would
- output the data twice. *Note Termination Internals::.
|