1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031303230333034303530363037303830393040304130423043304430453046304730483049305030513052305330543055305630573058305930603061306230633064306530663067306830693070307130723073307430753076307730783079308030813082308330843085308630873088308930903091309230933094309530963097309830993100310131023103310431053106310731083109311031113112311331143115311631173118311931203121312231233124312531263127312831293130313131323133313431353136313731383139314031413142314331443145314631473148314931503151315231533154315531563157315831593160316131623163316431653166316731683169317031713172317331743175317631773178317931803181318231833184318531863187318831893190319131923193319431953196319731983199320032013202320332043205320632073208320932103211321232133214321532163217321832193220322132223223322432253226322732283229323032313232323332343235323632373238323932403241324232433244324532463247324832493250325132523253325432553256325732583259326032613262326332643265326632673268326932703271327232733274327532763277327832793280328132823283328432853286328732883289329032913292329332943295329632973298329933003301330233033304330533063307330833093310331133123313331433153316331733183319332033213322332333243325332633273328332933303331333233333334333533363337333833393340334133423343334433453346334733483349335033513352335333543355335633573358335933603361336233633364336533663367336833693370337133723373337433753376337733783379338033813382338333843385338633873388338933903391339233933394339533963397339833993400340134023403340434053406340734083409341034113412341334143415341634173418341934203421342234233424342534263427342834293430343134323433343434353436343734383439344034413442344334443445344634473448344934503451345234533454345534563457345834593460346134623463346434653466346734683469347034713472347334743475347634773478347934803481348234833484348534863487348834893490349134923493349434953496349734983499350035013502350335043505350635073508350935103511351235133514351535163517351835193520352135223523352435253526352735283529353035313532353335343535353635373538353935403541354235433544354535463547354835493550355135523553355435553556355735583559356035613562356335643565356635673568356935703571357235733574357535763577357835793580358135823583358435853586358735883589359035913592359335943595359635973598359936003601360236033604360536063607360836093610361136123613361436153616361736183619362036213622362336243625362636273628362936303631363236333634363536363637363836393640364136423643364436453646364736483649365036513652365336543655365636573658365936603661366236633664366536663667366836693670367136723673367436753676367736783679368036813682368336843685368636873688368936903691369236933694369536963697369836993700370137023703370437053706370737083709371037113712371337143715371637173718371937203721372237233724372537263727372837293730373137323733373437353736373737383739374037413742374337443745374637473748374937503751375237533754375537563757375837593760376137623763376437653766376737683769377037713772377337743775377637773778377937803781378237833784378537863787378837893790379137923793379437953796379737983799380038013802380338043805380638073808380938103811381238133814381538163817381838193820382138223823382438253826382738283829383038313832383338343835383638373838383938403841384238433844384538463847384838493850385138523853385438553856385738583859386038613862386338643865386638673868386938703871387238733874387538763877387838793880388138823883388438853886388738883889389038913892389338943895389638973898389939003901390239033904390539063907390839093910391139123913391439153916391739183919392039213922392339243925392639273928392939303931393239333934393539363937393839393940394139423943394439453946394739483949395039513952395339543955395639573958395939603961396239633964396539663967396839693970397139723973397439753976397739783979398039813982398339843985398639873988398939903991399239933994399539963997399839994000400140024003400440054006400740084009401040114012401340144015401640174018401940204021402240234024402540264027402840294030403140324033403440354036403740384039404040414042404340444045404640474048404940504051405240534054405540564057405840594060406140624063406440654066406740684069407040714072407340744075407640774078407940804081408240834084408540864087408840894090409140924093409440954096409740984099410041014102410341044105410641074108410941104111411241134114411541164117411841194120412141224123412441254126412741284129413041314132413341344135413641374138413941404141414241434144414541464147414841494150415141524153415441554156415741584159416041614162416341644165416641674168416941704171417241734174417541764177417841794180418141824183418441854186418741884189419041914192419341944195419641974198419942004201420242034204420542064207420842094210421142124213421442154216421742184219422042214222422342244225422642274228422942304231423242334234423542364237423842394240424142424243424442454246424742484249425042514252425342544255425642574258425942604261426242634264426542664267426842694270427142724273427442754276427742784279428042814282428342844285428642874288428942904291429242934294429542964297429842994300430143024303430443054306430743084309431043114312431343144315431643174318431943204321432243234324432543264327432843294330433143324333433443354336433743384339434043414342434343444345434643474348434943504351435243534354435543564357435843594360436143624363436443654366436743684369437043714372437343744375437643774378437943804381438243834384438543864387438843894390439143924393439443954396439743984399440044014402440344044405440644074408440944104411441244134414441544164417441844194420442144224423442444254426442744284429443044314432443344344435443644374438443944404441444244434444444544464447444844494450445144524453445444554456445744584459446044614462446344644465446644674468446944704471447244734474447544764477447844794480448144824483448444854486448744884489449044914492449344944495449644974498449945004501450245034504450545064507450845094510451145124513451445154516451745184519452045214522452345244525452645274528452945304531453245334534453545364537453845394540454145424543454445454546454745484549455045514552455345544555455645574558455945604561456245634564456545664567456845694570457145724573457445754576457745784579458045814582458345844585458645874588458945904591459245934594459545964597459845994600460146024603460446054606460746084609461046114612461346144615461646174618461946204621462246234624462546264627462846294630463146324633463446354636463746384639464046414642464346444645464646474648464946504651465246534654465546564657465846594660466146624663466446654666466746684669467046714672467346744675467646774678467946804681468246834684468546864687468846894690469146924693469446954696469746984699470047014702470347044705470647074708470947104711471247134714471547164717471847194720472147224723472447254726472747284729473047314732473347344735473647374738473947404741474247434744474547464747474847494750475147524753475447554756475747584759476047614762476347644765476647674768476947704771477247734774477547764777477847794780478147824783478447854786478747884789479047914792479347944795479647974798479948004801480248034804480548064807480848094810481148124813481448154816481748184819482048214822482348244825482648274828482948304831483248334834483548364837483848394840484148424843484448454846484748484849485048514852485348544855485648574858485948604861486248634864486548664867486848694870487148724873487448754876487748784879488048814882488348844885488648874888488948904891489248934894489548964897489848994900490149024903490449054906490749084909491049114912491349144915491649174918491949204921492249234924492549264927492849294930493149324933493449354936493749384939494049414942494349444945494649474948494949504951495249534954495549564957495849594960496149624963496449654966496749684969497049714972497349744975497649774978497949804981498249834984498549864987498849894990499149924993499449954996499749984999500050015002500350045005500650075008500950105011501250135014501550165017501850195020502150225023502450255026502750285029503050315032503350345035503650375038503950405041504250435044504550465047504850495050505150525053505450555056505750585059506050615062506350645065506650675068506950705071507250735074507550765077507850795080508150825083508450855086508750885089509050915092509350945095509650975098509951005101510251035104510551065107510851095110511151125113511451155116511751185119512051215122512351245125512651275128512951305131513251335134513551365137513851395140514151425143514451455146514751485149515051515152515351545155515651575158515951605161516251635164516551665167516851695170517151725173517451755176517751785179518051815182518351845185518651875188518951905191519251935194519551965197519851995200520152025203520452055206520752085209521052115212521352145215521652175218521952205221522252235224522552265227522852295230523152325233523452355236523752385239524052415242524352445245524652475248524952505251525252535254525552565257525852595260526152625263526452655266526752685269527052715272527352745275527652775278527952805281528252835284528552865287528852895290529152925293529452955296529752985299530053015302530353045305530653075308530953105311531253135314531553165317531853195320532153225323532453255326532753285329533053315332533353345335533653375338533953405341534253435344534553465347534853495350535153525353535453555356535753585359536053615362536353645365536653675368536953705371537253735374537553765377537853795380538153825383538453855386538753885389539053915392539353945395539653975398539954005401540254035404540554065407540854095410541154125413541454155416541754185419542054215422542354245425542654275428542954305431543254335434543554365437543854395440544154425443544454455446544754485449545054515452545354545455545654575458545954605461546254635464546554665467546854695470547154725473547454755476547754785479548054815482548354845485548654875488548954905491549254935494549554965497549854995500550155025503550455055506550755085509551055115512551355145515551655175518551955205521552255235524552555265527552855295530553155325533553455355536553755385539554055415542554355445545554655475548554955505551555255535554555555565557555855595560556155625563556455655566556755685569557055715572557355745575557655775578557955805581558255835584558555865587558855895590559155925593559455955596559755985599560056015602560356045605560656075608560956105611561256135614561556165617561856195620562156225623562456255626562756285629563056315632563356345635563656375638563956405641564256435644564556465647564856495650565156525653565456555656565756585659566056615662566356645665566656675668566956705671567256735674567556765677567856795680568156825683568456855686568756885689569056915692569356945695569656975698569957005701570257035704570557065707570857095710571157125713571457155716571757185719572057215722572357245725572657275728572957305731573257335734573557365737573857395740574157425743574457455746574757485749575057515752575357545755575657575758575957605761576257635764576557665767576857695770577157725773577457755776577757785779578057815782578357845785578657875788578957905791579257935794579557965797579857995800580158025803580458055806580758085809581058115812581358145815581658175818581958205821582258235824582558265827582858295830583158325833583458355836583758385839584058415842584358445845584658475848584958505851585258535854585558565857585858595860586158625863586458655866586758685869587058715872587358745875587658775878587958805881588258835884588558865887588858895890589158925893589458955896589758985899590059015902590359045905590659075908590959105911591259135914591559165917591859195920592159225923592459255926592759285929593059315932593359345935593659375938593959405941594259435944594559465947594859495950595159525953595459555956595759585959596059615962596359645965596659675968596959705971597259735974597559765977597859795980598159825983598459855986598759885989599059915992599359945995599659975998599960006001600260036004600560066007600860096010601160126013601460156016601760186019602060216022602360246025602660276028602960306031603260336034603560366037603860396040604160426043604460456046604760486049605060516052605360546055605660576058605960606061606260636064606560666067606860696070607160726073607460756076607760786079608060816082608360846085608660876088608960906091609260936094609560966097609860996100610161026103610461056106610761086109611061116112611361146115611661176118611961206121612261236124612561266127612861296130613161326133613461356136613761386139614061416142614361446145614661476148614961506151615261536154615561566157615861596160616161626163616461656166616761686169617061716172617361746175617661776178617961806181618261836184618561866187618861896190619161926193619461956196619761986199620062016202620362046205620662076208620962106211621262136214621562166217621862196220622162226223622462256226622762286229623062316232623362346235623662376238623962406241624262436244624562466247624862496250625162526253625462556256625762586259626062616262626362646265626662676268626962706271627262736274627562766277627862796280628162826283628462856286628762886289629062916292629362946295629662976298629963006301630263036304630563066307630863096310631163126313631463156316631763186319632063216322632363246325632663276328632963306331633263336334633563366337633863396340634163426343634463456346634763486349635063516352635363546355635663576358635963606361636263636364636563666367636863696370637163726373637463756376637763786379638063816382638363846385638663876388638963906391639263936394639563966397639863996400640164026403640464056406640764086409641064116412641364146415641664176418641964206421642264236424642564266427642864296430643164326433643464356436643764386439644064416442644364446445644664476448644964506451645264536454645564566457645864596460646164626463646464656466646764686469647064716472647364746475647664776478647964806481648264836484648564866487648864896490649164926493649464956496649764986499650065016502650365046505650665076508650965106511651265136514651565166517651865196520652165226523652465256526652765286529653065316532653365346535653665376538653965406541654265436544654565466547654865496550655165526553655465556556655765586559656065616562656365646565656665676568656965706571657265736574657565766577657865796580658165826583658465856586658765886589659065916592659365946595659665976598659966006601660266036604660566066607660866096610661166126613661466156616661766186619662066216622662366246625662666276628662966306631663266336634663566366637663866396640664166426643664466456646664766486649665066516652665366546655665666576658665966606661666266636664666566666667666866696670667166726673667466756676667766786679668066816682668366846685668666876688668966906691669266936694669566966697669866996700670167026703670467056706670767086709671067116712671367146715671667176718671967206721672267236724672567266727672867296730673167326733673467356736673767386739674067416742674367446745674667476748674967506751675267536754675567566757675867596760676167626763676467656766676767686769677067716772677367746775677667776778677967806781678267836784678567866787678867896790679167926793679467956796679767986799680068016802680368046805680668076808680968106811681268136814681568166817681868196820682168226823682468256826682768286829683068316832683368346835683668376838683968406841684268436844684568466847684868496850685168526853685468556856685768586859686068616862686368646865686668676868686968706871687268736874687568766877687868796880688168826883688468856886688768886889689068916892689368946895689668976898689969006901690269036904690569066907690869096910691169126913691469156916691769186919692069216922692369246925692669276928692969306931693269336934693569366937693869396940694169426943694469456946694769486949695069516952695369546955695669576958695969606961696269636964696569666967696869696970697169726973697469756976697769786979698069816982698369846985698669876988698969906991699269936994699569966997699869997000700170027003700470057006700770087009701070117012701370147015701670177018701970207021702270237024702570267027702870297030703170327033703470357036703770387039704070417042704370447045704670477048704970507051705270537054705570567057705870597060706170627063706470657066706770687069707070717072707370747075707670777078707970807081708270837084708570867087708870897090709170927093709470957096709770987099710071017102710371047105710671077108710971107111711271137114711571167117711871197120712171227123712471257126712771287129713071317132713371347135713671377138713971407141714271437144714571467147714871497150715171527153715471557156715771587159716071617162716371647165716671677168716971707171717271737174717571767177717871797180718171827183718471857186718771887189719071917192719371947195719671977198719972007201720272037204720572067207720872097210721172127213 |
- 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: CPU Time, Next: Processor Time, Up: Processor And CPU Time
- 21.3.1 CPU Time Inquiry
- -----------------------
- To get a process’ CPU time, you can use the ‘clock’ function. This
- facility is declared in the header file ‘time.h’.
- In typical usage, you call the ‘clock’ function at the beginning and
- end of the interval you want to time, subtract the values, and then
- divide by ‘CLOCKS_PER_SEC’ (the number of clock ticks per second) to get
- processor time, like this:
- #include <time.h>
- clock_t start, end;
- double cpu_time_used;
- start = clock();
- … /* Do the work. */
- end = clock();
- cpu_time_used = ((double) (end - start)) / CLOCKS_PER_SEC;
- Do not use a single CPU time as an amount of time; it doesn’t work
- that way. Either do a subtraction as shown above or query processor
- time directly. *Note Processor Time::.
- Different computers and operating systems vary wildly in how they
- keep track of CPU time. It’s common for the internal processor clock to
- have a resolution somewhere between a hundredth and millionth of a
- second.
- -- Macro: int CLOCKS_PER_SEC
- The value of this macro is the number of clock ticks per second
- measured by the ‘clock’ function. POSIX requires that this value
- be one million independent of the actual resolution.
- -- Data Type: clock_t
- This is the type of the value returned by the ‘clock’ function.
- Values of type ‘clock_t’ are numbers of clock ticks.
- -- Function: clock_t clock (void)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function returns the calling process’ current CPU time. If
- the CPU time is not available or cannot be represented, ‘clock’
- returns the value ‘(clock_t)(-1)’.
- File: libc.info, Node: Processor Time, Prev: CPU Time, Up: Processor And CPU Time
- 21.3.2 Processor Time Inquiry
- -----------------------------
- The ‘times’ function returns information about a process’ consumption of
- processor time in a ‘struct tms’ object, in addition to the process’ CPU
- time. *Note Time Basics::. You should include the header file
- ‘sys/times.h’ to use this facility.
- -- Data Type: struct tms
- The ‘tms’ structure is used to return information about process
- times. It contains at least the following members:
- ‘clock_t tms_utime’
- This is the total processor time the calling process has used
- in executing the instructions of its program.
- ‘clock_t tms_stime’
- This is the processor time the system has used on behalf of
- the calling process.
- ‘clock_t tms_cutime’
- This is the sum of the ‘tms_utime’ values and the ‘tms_cutime’
- values of all terminated child processes of the calling
- process, whose status has been reported to the parent process
- by ‘wait’ or ‘waitpid’; see *note Process Completion::. In
- other words, it represents the total processor time used in
- executing the instructions of all the terminated child
- processes of the calling process, excluding child processes
- which have not yet been reported by ‘wait’ or ‘waitpid’.
- ‘clock_t tms_cstime’
- This is similar to ‘tms_cutime’, but represents the total
- processor time the system has used on behalf of all the
- terminated child processes of the calling process.
- All of the times are given in numbers of clock ticks. Unlike CPU
- time, these are the actual amounts of time; not relative to any
- event. *Note Creating a Process::.
- -- Macro: int CLK_TCK
- This is an obsolete name for the number of clock ticks per second.
- Use ‘sysconf (_SC_CLK_TCK)’ instead.
- -- Function: clock_t times (struct tms *BUFFER)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘times’ function stores the processor time information for the
- calling process in BUFFER.
- The return value is the number of clock ticks since an arbitrary
- point in the past, e.g. since system start-up. ‘times’ returns
- ‘(clock_t)(-1)’ to indicate failure.
- *Portability Note:* The ‘clock’ function described in *note CPU
- Time:: is specified by the ISO C standard. The ‘times’ function is a
- feature of POSIX.1. On GNU systems, the CPU time is defined to be
- equivalent to the sum of the ‘tms_utime’ and ‘tms_stime’ fields returned
- by ‘times’.
- File: libc.info, Node: Calendar Time, Next: Setting an Alarm, Prev: Processor And CPU Time, Up: Date and Time
- 21.4 Calendar Time
- ==================
- This section describes facilities for keeping track of calendar time.
- *Note Time Basics::.
- The GNU C Library represents calendar time three ways:
- • "Simple time" (the ‘time_t’ data type) is a compact representation,
- typically giving the number of seconds of elapsed time since some
- implementation-specific base time.
- • There is also a "high-resolution time" representation. Like simple
- time, this represents a calendar time as an elapsed time since a
- base time, but instead of measuring in whole seconds, it uses a
- ‘struct timeval’ data type, which includes fractions of a second.
- Use this time representation instead of simple time when you need
- greater precision.
- • "Local time" or "broken-down time" (the ‘struct tm’ data type)
- represents a calendar time as a set of components specifying the
- year, month, and so on in the Gregorian calendar, for a specific
- time zone. This calendar time representation is usually used only
- to communicate with people.
- * Menu:
- * Simple Calendar Time:: Facilities for manipulating calendar time.
- * High-Resolution Calendar:: A time representation with greater precision.
- * Broken-down Time:: Facilities for manipulating local time.
- * High Accuracy Clock:: Maintaining a high accuracy system clock.
- * Formatting Calendar Time:: Converting times to strings.
- * Parsing Date and Time:: Convert textual time and date information back
- into broken-down time values.
- * TZ Variable:: How users specify the time zone.
- * Time Zone Functions:: Functions to examine or specify the time zone.
- * Time Functions Example:: An example program showing use of some of
- the time functions.
- File: libc.info, Node: Simple Calendar Time, Next: High-Resolution Calendar, Up: Calendar Time
- 21.4.1 Simple Calendar Time
- ---------------------------
- This section describes the ‘time_t’ data type for representing calendar
- time as simple time, and the functions which operate on simple time
- objects. These facilities are declared in the header file ‘time.h’.
- -- Data Type: time_t
- This is the data type used to represent simple time. Sometimes, it
- also represents an elapsed time. When interpreted as a calendar
- time value, it represents the number of seconds elapsed since
- 00:00:00 on January 1, 1970, Coordinated Universal Time. (This
- calendar time is sometimes referred to as the "epoch".) POSIX
- requires that this count not include leap seconds, but on some
- systems this count includes leap seconds if you set ‘TZ’ to certain
- values (*note TZ Variable::).
- Note that a simple time has no concept of local time zone.
- Calendar Time T is the same instant in time regardless of where on
- the globe the computer is.
- In the GNU C Library, ‘time_t’ is equivalent to ‘long int’. In
- other systems, ‘time_t’ might be either an integer or
- floating-point type.
- The function ‘difftime’ tells you the elapsed time between two simple
- calendar times, which is not always as easy to compute as just
- subtracting. *Note Elapsed Time::.
- -- Function: time_t time (time_t *RESULT)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘time’ function returns the current calendar time as a value of
- type ‘time_t’. If the argument RESULT is not a null pointer, the
- calendar time value is also stored in ‘*RESULT’. If the current
- calendar time is not available, the value ‘(time_t)(-1)’ is
- returned.
- -- Function: int stime (const time_t *NEWTIME)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- ‘stime’ sets the system clock, i.e., it tells the system that the
- current calendar time is NEWTIME, where ‘newtime’ is interpreted as
- described in the above definition of ‘time_t’.
- ‘settimeofday’ is a newer function which sets the system clock to
- better than one second precision. ‘settimeofday’ is generally a
- better choice than ‘stime’. *Note High-Resolution Calendar::.
- Only the superuser can set the system clock.
- If the function succeeds, the return value is zero. Otherwise, it
- is ‘-1’ and ‘errno’ is set accordingly:
- ‘EPERM’
- The process is not superuser.
- File: libc.info, Node: High-Resolution Calendar, Next: Broken-down Time, Prev: Simple Calendar Time, Up: Calendar Time
- 21.4.2 High-Resolution Calendar
- -------------------------------
- The ‘time_t’ data type used to represent simple times has a resolution
- of only one second. Some applications need more precision.
- So, the GNU C Library also contains functions which are capable of
- representing calendar times to a higher resolution than one second. The
- functions and the associated data types described in this section are
- declared in ‘sys/time.h’.
- -- Data Type: struct timezone
- The ‘struct timezone’ structure is used to hold minimal information
- about the local time zone. It has the following members:
- ‘int tz_minuteswest’
- This is the number of minutes west of UTC.
- ‘int tz_dsttime’
- If nonzero, Daylight Saving Time applies during some part of
- the year.
- The ‘struct timezone’ type is obsolete and should never be used.
- Instead, use the facilities described in *note Time Zone
- Functions::.
- -- Function: int gettimeofday (struct timeval *TP, struct timezone
- *TZP)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘gettimeofday’ function returns the current calendar time as
- the elapsed time since the epoch in the ‘struct timeval’ structure
- indicated by TP. (*note Elapsed Time:: for a description of
- ‘struct timeval’). Information about the time zone is returned in
- the structure pointed to by TZP. If the TZP argument is a null
- pointer, time zone information is ignored.
- The return value is ‘0’ on success and ‘-1’ on failure. The
- following ‘errno’ error condition is defined for this function:
- ‘ENOSYS’
- The operating system does not support getting time zone
- information, and TZP is not a null pointer. GNU systems do
- not support using ‘struct timezone’ to represent time zone
- information; that is an obsolete feature of 4.3 BSD. Instead,
- use the facilities described in *note Time Zone Functions::.
- -- Function: int settimeofday (const struct timeval *TP, const struct
- timezone *TZP)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘settimeofday’ function sets the current calendar time in the
- system clock according to the arguments. As for ‘gettimeofday’,
- the calendar time is represented as the elapsed time since the
- epoch. As for ‘gettimeofday’, time zone information is ignored if
- TZP is a null pointer.
- You must be a privileged user in order to use ‘settimeofday’.
- Some kernels automatically set the system clock from some source
- such as a hardware clock when they start up. Others, including
- Linux, place the system clock in an “invalid” state (in which
- attempts to read the clock fail). A call of ‘stime’ removes the
- system clock from an invalid state, and system startup scripts
- typically run a program that calls ‘stime’.
- ‘settimeofday’ causes a sudden jump forwards or backwards, which
- can cause a variety of problems in a system. Use ‘adjtime’ (below)
- to make a smooth transition from one time to another by temporarily
- speeding up or slowing down the clock.
- With a Linux kernel, ‘adjtimex’ does the same thing and can also
- make permanent changes to the speed of the system clock so it
- doesn’t need to be corrected as often.
- The return value is ‘0’ on success and ‘-1’ on failure. The
- following ‘errno’ error conditions are defined for this function:
- ‘EPERM’
- This process cannot set the clock because it is not
- privileged.
- ‘ENOSYS’
- The operating system does not support setting time zone
- information, and TZP is not a null pointer.
- -- Function: int adjtime (const struct timeval *DELTA, struct timeval
- *OLDDELTA)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function speeds up or slows down the system clock in order to
- make a gradual adjustment. This ensures that the calendar time
- reported by the system clock is always monotonically increasing,
- which might not happen if you simply set the clock.
- The DELTA argument specifies a relative adjustment to be made to
- the clock time. If negative, the system clock is slowed down for a
- while until it has lost this much elapsed time. If positive, the
- system clock is speeded up for a while.
- If the OLDDELTA argument is not a null pointer, the ‘adjtime’
- function returns information about any previous time adjustment
- that has not yet completed.
- This function is typically used to synchronize the clocks of
- computers in a local network. You must be a privileged user to use
- it.
- With a Linux kernel, you can use the ‘adjtimex’ function to
- permanently change the clock speed.
- The return value is ‘0’ on success and ‘-1’ on failure. The
- following ‘errno’ error condition is defined for this function:
- ‘EPERM’
- You do not have privilege to set the time.
- *Portability Note:* The ‘gettimeofday’, ‘settimeofday’, and ‘adjtime’
- functions are derived from BSD.
- Symbols for the following function are declared in ‘sys/timex.h’.
- -- Function: int adjtimex (struct timex *TIMEX)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- ‘adjtimex’ is functionally identical to ‘ntp_adjtime’. *Note High
- Accuracy Clock::.
- This function is present only with a Linux kernel.
- File: libc.info, Node: Broken-down Time, Next: High Accuracy Clock, Prev: High-Resolution Calendar, Up: Calendar Time
- 21.4.3 Broken-down Time
- -----------------------
- Calendar time is represented by the usual GNU C Library functions as an
- elapsed time since a fixed base calendar time. This is convenient for
- computation, but has no relation to the way people normally think of
- calendar time. By contrast, "broken-down time" is a binary
- representation of calendar time separated into year, month, day, and so
- on. Broken-down time values are not useful for calculations, but they
- are useful for printing human readable time information.
- A broken-down time value is always relative to a choice of time zone,
- and it also indicates which time zone that is.
- The symbols in this section are declared in the header file ‘time.h’.
- -- Data Type: struct tm
- This is the data type used to represent a broken-down time. The
- structure contains at least the following members, which can appear
- in any order.
- ‘int tm_sec’
- This is the number of full seconds since the top of the minute
- (normally in the range ‘0’ through ‘59’, but the actual upper
- limit is ‘60’, to allow for leap seconds if leap second
- support is available).
- ‘int tm_min’
- This is the number of full minutes since the top of the hour
- (in the range ‘0’ through ‘59’).
- ‘int tm_hour’
- This is the number of full hours past midnight (in the range
- ‘0’ through ‘23’).
- ‘int tm_mday’
- This is the ordinal day of the month (in the range ‘1’ through
- ‘31’). Watch out for this one! As the only ordinal number in
- the structure, it is inconsistent with the rest of the
- structure.
- ‘int tm_mon’
- This is the number of full calendar months since the beginning
- of the year (in the range ‘0’ through ‘11’). Watch out for
- this one! People usually use ordinal numbers for
- month-of-year (where January = 1).
- ‘int tm_year’
- This is the number of full calendar years since 1900.
- ‘int tm_wday’
- This is the number of full days since Sunday (in the range ‘0’
- through ‘6’).
- ‘int tm_yday’
- This is the number of full days since the beginning of the
- year (in the range ‘0’ through ‘365’).
- ‘int tm_isdst’
- This is a flag that indicates whether Daylight Saving Time is
- (or was, or will be) in effect at the time described. The
- value is positive if Daylight Saving Time is in effect, zero
- if it is not, and negative if the information is not
- available.
- ‘long int tm_gmtoff’
- This field describes the time zone that was used to compute
- this broken-down time value, including any adjustment for
- daylight saving; it is the number of seconds that you must add
- to UTC to get local time. You can also think of this as the
- number of seconds east of UTC. For example, for U.S. Eastern
- Standard Time, the value is ‘-5*60*60’. The ‘tm_gmtoff’ field
- is derived from BSD and is a GNU library extension; it is not
- visible in a strict ISO C environment.
- ‘const char *tm_zone’
- This field is the name for the time zone that was used to
- compute this broken-down time value. Like ‘tm_gmtoff’, this
- field is a BSD and GNU extension, and is not visible in a
- strict ISO C environment.
- -- Function: struct tm * localtime (const time_t *TIME)
- Preliminary: | MT-Unsafe race:tmbuf env locale | AS-Unsafe heap
- lock | AC-Unsafe lock mem fd | *Note POSIX Safety Concepts::.
- The ‘localtime’ function converts the simple time pointed to by
- TIME to broken-down time representation, expressed relative to the
- user’s specified time zone.
- The return value is a pointer to a static broken-down time
- structure, which might be overwritten by subsequent calls to
- ‘ctime’, ‘gmtime’, or ‘localtime’. (But no other library function
- overwrites the contents of this object.)
- The return value is the null pointer if TIME cannot be represented
- as a broken-down time; typically this is because the year cannot
- fit into an ‘int’.
- Calling ‘localtime’ also sets the current time zone as if ‘tzset’
- were called. *Note Time Zone Functions::.
- Using the ‘localtime’ function is a big problem in multi-threaded
- programs. The result is returned in a static buffer and this is used in
- all threads. POSIX.1c introduced a variant of this function.
- -- Function: struct tm * localtime_r (const time_t *TIME, struct tm
- *RESULTP)
- Preliminary: | MT-Safe env locale | AS-Unsafe heap lock | AC-Unsafe
- lock mem fd | *Note POSIX Safety Concepts::.
- The ‘localtime_r’ function works just like the ‘localtime’
- function. It takes a pointer to a variable containing a simple
- time and converts it to the broken-down time format.
- But the result is not placed in a static buffer. Instead it is
- placed in the object of type ‘struct tm’ to which the parameter
- RESULTP points.
- If the conversion is successful the function returns a pointer to
- the object the result was written into, i.e., it returns RESULTP.
- -- Function: struct tm * gmtime (const time_t *TIME)
- Preliminary: | MT-Unsafe race:tmbuf env locale | AS-Unsafe heap
- lock | AC-Unsafe lock mem fd | *Note POSIX Safety Concepts::.
- This function is similar to ‘localtime’, except that the
- broken-down time is expressed as Coordinated Universal Time (UTC)
- (formerly called Greenwich Mean Time (GMT)) rather than relative to
- a local time zone.
- As for the ‘localtime’ function we have the problem that the result
- is placed in a static variable. POSIX.1c also provides a replacement
- for ‘gmtime’.
- -- Function: struct tm * gmtime_r (const time_t *TIME, struct tm
- *RESULTP)
- Preliminary: | MT-Safe env locale | AS-Unsafe heap lock | AC-Unsafe
- lock mem fd | *Note POSIX Safety Concepts::.
- This function is similar to ‘localtime_r’, except that it converts
- just like ‘gmtime’ the given time as Coordinated Universal Time.
- If the conversion is successful the function returns a pointer to
- the object the result was written into, i.e., it returns RESULTP.
- -- Function: time_t mktime (struct tm *BROKENTIME)
- Preliminary: | MT-Safe env locale | AS-Unsafe heap lock | AC-Unsafe
- lock mem fd | *Note POSIX Safety Concepts::.
- The ‘mktime’ function converts a broken-down time structure to a
- simple time representation. It also normalizes the contents of the
- broken-down time structure, and fills in some components based on
- the values of the others.
- The ‘mktime’ function ignores the specified contents of the
- ‘tm_wday’, ‘tm_yday’, ‘tm_gmtoff’, and ‘tm_zone’ members of the
- broken-down time structure. It uses the values of the other
- components to determine the calendar time; it’s permissible for
- these components to have unnormalized values outside their normal
- ranges. The last thing that ‘mktime’ does is adjust the components
- of the BROKENTIME structure, including the members that were
- initially ignored.
- If the specified broken-down time cannot be represented as a simple
- time, ‘mktime’ returns a value of ‘(time_t)(-1)’ and does not
- modify the contents of BROKENTIME.
- Calling ‘mktime’ also sets the current time zone as if ‘tzset’ were
- called; ‘mktime’ uses this information instead of BROKENTIME’s
- initial ‘tm_gmtoff’ and ‘tm_zone’ members. *Note Time Zone
- Functions::.
- -- Function: time_t timelocal (struct tm *BROKENTIME)
- Preliminary: | MT-Safe env locale | AS-Unsafe heap lock | AC-Unsafe
- lock mem fd | *Note POSIX Safety Concepts::.
- ‘timelocal’ is functionally identical to ‘mktime’, but more
- mnemonically named. Note that it is the inverse of the ‘localtime’
- function.
- *Portability note:* ‘mktime’ is essentially universally available.
- ‘timelocal’ is rather rare.
- -- Function: time_t timegm (struct tm *BROKENTIME)
- Preliminary: | MT-Safe env locale | AS-Unsafe heap lock | AC-Unsafe
- lock mem fd | *Note POSIX Safety Concepts::.
- ‘timegm’ is functionally identical to ‘mktime’ except it always
- takes the input values to be Coordinated Universal Time (UTC)
- regardless of any local time zone setting.
- Note that ‘timegm’ is the inverse of ‘gmtime’.
- *Portability note:* ‘mktime’ is essentially universally available.
- ‘timegm’ is rather rare. For the most portable conversion from a
- UTC broken-down time to a simple time, set the ‘TZ’ environment
- variable to UTC, call ‘mktime’, then set ‘TZ’ back.
- File: libc.info, Node: High Accuracy Clock, Next: Formatting Calendar Time, Prev: Broken-down Time, Up: Calendar Time
- 21.4.4 High Accuracy Clock
- --------------------------
- The ‘ntp_gettime’ and ‘ntp_adjtime’ functions provide an interface to
- monitor and manipulate the system clock to maintain high accuracy time.
- For example, you can fine tune the speed of the clock or synchronize it
- with another time source.
- A typical use of these functions is by a server implementing the
- Network Time Protocol to synchronize the clocks of multiple systems and
- high precision clocks.
- These functions are declared in ‘sys/timex.h’.
- -- Data Type: struct ntptimeval
- This structure is used for information about the system clock. It
- contains the following members:
- ‘struct timeval time’
- This is the current calendar time, expressed as the elapsed
- time since the epoch. The ‘struct timeval’ data type is
- described in *note Elapsed Time::.
- ‘long int maxerror’
- This is the maximum error, measured in microseconds. Unless
- updated via ‘ntp_adjtime’ periodically, this value will reach
- some platform-specific maximum value.
- ‘long int esterror’
- This is the estimated error, measured in microseconds. This
- value can be set by ‘ntp_adjtime’ to indicate the estimated
- offset of the system clock from the true calendar time.
- -- Function: int ntp_gettime (struct ntptimeval *TPTR)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘ntp_gettime’ function sets the structure pointed to by TPTR to
- current values. The elements of the structure afterwards contain
- the values the timer implementation in the kernel assumes. They
- might or might not be correct. If they are not, an ‘ntp_adjtime’
- call is necessary.
- The return value is ‘0’ on success and other values on failure.
- The following ‘errno’ error conditions are defined for this
- function:
- ‘TIME_ERROR’
- The precision clock model is not properly set up at the
- moment, thus the clock must be considered unsynchronized, and
- the values should be treated with care.
- -- Data Type: struct timex
- This structure is used to control and monitor the system clock. It
- contains the following members:
- ‘unsigned int modes’
- This variable controls whether and which values are set.
- Several symbolic constants have to be combined with _binary
- or_ to specify the effective mode. These constants start with
- ‘MOD_’.
- ‘long int offset’
- This value indicates the current offset of the system clock
- from the true calendar time. The value is given in
- microseconds. If bit ‘MOD_OFFSET’ is set in ‘modes’, the
- offset (and possibly other dependent values) can be set. The
- offset’s absolute value must not exceed ‘MAXPHASE’.
- ‘long int frequency’
- This value indicates the difference in frequency between the
- true calendar time and the system clock. The value is
- expressed as scaled PPM (parts per million, 0.0001%). The
- scaling is ‘1 << SHIFT_USEC’. The value can be set with bit
- ‘MOD_FREQUENCY’, but the absolute value must not exceed
- ‘MAXFREQ’.
- ‘long int maxerror’
- This is the maximum error, measured in microseconds. A new
- value can be set using bit ‘MOD_MAXERROR’. Unless updated via
- ‘ntp_adjtime’ periodically, this value will increase steadily
- and reach some platform-specific maximum value.
- ‘long int esterror’
- This is the estimated error, measured in microseconds. This
- value can be set using bit ‘MOD_ESTERROR’.
- ‘int status’
- This variable reflects the various states of the clock
- machinery. There are symbolic constants for the significant
- bits, starting with ‘STA_’. Some of these flags can be
- updated using the ‘MOD_STATUS’ bit.
- ‘long int constant’
- This value represents the bandwidth or stiffness of the PLL
- (phase locked loop) implemented in the kernel. The value can
- be changed using bit ‘MOD_TIMECONST’.
- ‘long int precision’
- This value represents the accuracy or the maximum error when
- reading the system clock. The value is expressed in
- microseconds.
- ‘long int tolerance’
- This value represents the maximum frequency error of the
- system clock in scaled PPM. This value is used to increase the
- ‘maxerror’ every second.
- ‘struct timeval time’
- The current calendar time.
- ‘long int tick’
- The elapsed time between clock ticks in microseconds. A clock
- tick is a periodic timer interrupt on which the system clock
- is based.
- ‘long int ppsfreq’
- This is the first of a few optional variables that are present
- only if the system clock can use a PPS (pulse per second)
- signal to discipline the system clock. The value is expressed
- in scaled PPM and it denotes the difference in frequency
- between the system clock and the PPS signal.
- ‘long int jitter’
- This value expresses a median filtered average of the PPS
- signal’s dispersion in microseconds.
- ‘int shift’
- This value is a binary exponent for the duration of the PPS
- calibration interval, ranging from ‘PPS_SHIFT’ to
- ‘PPS_SHIFTMAX’.
- ‘long int stabil’
- This value represents the median filtered dispersion of the
- PPS frequency in scaled PPM.
- ‘long int jitcnt’
- This counter represents the number of pulses where the jitter
- exceeded the allowed maximum ‘MAXTIME’.
- ‘long int calcnt’
- This counter reflects the number of successful calibration
- intervals.
- ‘long int errcnt’
- This counter represents the number of calibration errors
- (caused by large offsets or jitter).
- ‘long int stbcnt’
- This counter denotes the number of calibrations where the
- stability exceeded the threshold.
- -- Function: int ntp_adjtime (struct timex *TPTR)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘ntp_adjtime’ function sets the structure specified by TPTR to
- current values.
- In addition, ‘ntp_adjtime’ updates some settings to match what you
- pass to it in *TPTR. Use the ‘modes’ element of *TPTR to select
- what settings to update. You can set ‘offset’, ‘freq’, ‘maxerror’,
- ‘esterror’, ‘status’, ‘constant’, and ‘tick’.
- ‘modes’ = zero means set nothing.
- Only the superuser can update settings.
- The return value is ‘0’ on success and other values on failure.
- The following ‘errno’ error conditions are defined for this
- function:
- ‘TIME_ERROR’
- The high accuracy clock model is not properly set up at the
- moment, thus the clock must be considered unsynchronized, and
- the values should be treated with care. Another reason could
- be that the specified new values are not allowed.
- ‘EPERM’
- The process specified a settings update, but is not superuser.
- For more details see RFC1305 (Network Time Protocol, Version 3) and
- related documents.
- *Portability note:* Early versions of the GNU C Library did not
- have this function but did have the synonymous ‘adjtimex’.
- File: libc.info, Node: Formatting Calendar Time, Next: Parsing Date and Time, Prev: High Accuracy Clock, Up: Calendar Time
- 21.4.5 Formatting Calendar Time
- -------------------------------
- The functions described in this section format calendar time values as
- strings. These functions are declared in the header file ‘time.h’.
- -- Function: char * asctime (const struct tm *BROKENTIME)
- Preliminary: | MT-Unsafe race:asctime locale | AS-Unsafe | AC-Safe
- | *Note POSIX Safety Concepts::.
- The ‘asctime’ function converts the broken-down time value that
- BROKENTIME points to into a string in a standard format:
- "Tue May 21 13:46:22 1991\n"
- The abbreviations for the days of week are: ‘Sun’, ‘Mon’, ‘Tue’,
- ‘Wed’, ‘Thu’, ‘Fri’, and ‘Sat’.
- The abbreviations for the months are: ‘Jan’, ‘Feb’, ‘Mar’, ‘Apr’,
- ‘May’, ‘Jun’, ‘Jul’, ‘Aug’, ‘Sep’, ‘Oct’, ‘Nov’, and ‘Dec’.
- The return value points to a statically allocated string, which
- might be overwritten by subsequent calls to ‘asctime’ or ‘ctime’.
- (But no other library function overwrites the contents of this
- string.)
- -- Function: char * asctime_r (const struct tm *BROKENTIME, char
- *BUFFER)
- Preliminary: | MT-Safe locale | AS-Safe | AC-Safe | *Note POSIX
- Safety Concepts::.
- This function is similar to ‘asctime’ but instead of placing the
- result in a static buffer it writes the string in the buffer
- pointed to by the parameter BUFFER. This buffer should have room
- for at least 26 bytes, including the terminating null.
- If no error occurred the function returns a pointer to the string
- the result was written into, i.e., it returns BUFFER. Otherwise it
- returns ‘NULL’.
- -- Function: char * ctime (const time_t *TIME)
- Preliminary: | MT-Unsafe race:tmbuf race:asctime env locale |
- AS-Unsafe heap lock | AC-Unsafe lock mem fd | *Note POSIX Safety
- Concepts::.
- The ‘ctime’ function is similar to ‘asctime’, except that you
- specify the calendar time argument as a ‘time_t’ simple time value
- rather than in broken-down local time format. It is equivalent to
- asctime (localtime (TIME))
- Calling ‘ctime’ also sets the current time zone as if ‘tzset’ were
- called. *Note Time Zone Functions::.
- -- Function: char * ctime_r (const time_t *TIME, char *BUFFER)
- Preliminary: | MT-Safe env locale | AS-Unsafe heap lock | AC-Unsafe
- lock mem fd | *Note POSIX Safety Concepts::.
- This function is similar to ‘ctime’, but places the result in the
- string pointed to by BUFFER. It is equivalent to (written using
- gcc extensions, *note (gcc)Statement Exprs::):
- ({ struct tm tm; asctime_r (localtime_r (time, &tm), buf); })
- If no error occurred the function returns a pointer to the string
- the result was written into, i.e., it returns BUFFER. Otherwise it
- returns ‘NULL’.
- -- Function: size_t strftime (char *S, size_t SIZE, const char
- *TEMPLATE, const struct tm *BROKENTIME)
- Preliminary: | MT-Safe env locale | AS-Unsafe corrupt heap lock
- dlopen | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety
- Concepts::.
- This function is similar to the ‘sprintf’ function (*note Formatted
- Input::), but the conversion specifications that can appear in the
- format template TEMPLATE are specialized for printing components of
- the date and time BROKENTIME according to the locale currently
- specified for time conversion (*note Locales::) and the current
- time zone (*note Time Zone Functions::).
- Ordinary characters appearing in the TEMPLATE are copied to the
- output string S; this can include multibyte character sequences.
- Conversion specifiers are introduced by a ‘%’ character, followed
- by an optional flag which can be one of the following. These flags
- are all GNU extensions. The first three affect only the output of
- numbers:
- ‘_’
- The number is padded with spaces.
- ‘-’
- The number is not padded at all.
- ‘0’
- The number is padded with zeros even if the format specifies
- padding with spaces.
- ‘^’
- The output uses uppercase characters, but only if this is
- possible (*note Case Conversion::).
- The default action is to pad the number with zeros to keep it a
- constant width. Numbers that do not have a range indicated below
- are never padded, since there is no natural width for them.
- Following the flag an optional specification of the width is
- possible. This is specified in decimal notation. If the natural
- size of the output of the field has less than the specified number
- of characters, the result is written right adjusted and space
- padded to the given size.
- An optional modifier can follow the optional flag and width
- specification. The modifiers, which were first standardized by
- POSIX.2-1992 and by ISO C99, are:
- ‘E’
- Use the locale’s alternate representation for date and time.
- This modifier applies to the ‘%c’, ‘%C’, ‘%x’, ‘%X’, ‘%y’ and
- ‘%Y’ format specifiers. In a Japanese locale, for example,
- ‘%Ex’ might yield a date format based on the Japanese
- Emperors’ reigns.
- ‘O’
- Use the locale’s alternate numeric symbols for numbers. This
- modifier applies only to numeric format specifiers.
- If the format supports the modifier but no alternate representation
- is available, it is ignored.
- The conversion specifier ends with a format specifier taken from
- the following list. The whole ‘%’ sequence is replaced in the
- output string as follows:
- ‘%a’
- The abbreviated weekday name according to the current locale.
- ‘%A’
- The full weekday name according to the current locale.
- ‘%b’
- The abbreviated month name according to the current locale.
- ‘%B’
- The full month name according to the current locale.
- Using ‘%B’ together with ‘%d’ produces grammatically incorrect
- results for some locales.
- ‘%c’
- The preferred calendar time representation for the current
- locale.
- ‘%C’
- The century of the year. This is equivalent to the greatest
- integer not greater than the year divided by 100.
- This format was first standardized by POSIX.2-1992 and by
- ISO C99.
- ‘%d’
- The day of the month as a decimal number (range ‘01’ through
- ‘31’).
- ‘%D’
- The date using the format ‘%m/%d/%y’.
- This format was first standardized by POSIX.2-1992 and by
- ISO C99.
- ‘%e’
- The day of the month like with ‘%d’, but padded with spaces
- (range ‘ 1’ through ‘31’).
- This format was first standardized by POSIX.2-1992 and by
- ISO C99.
- ‘%F’
- The date using the format ‘%Y-%m-%d’. This is the form
- specified in the ISO 8601 standard and is the preferred form
- for all uses.
- This format was first standardized by ISO C99 and by
- POSIX.1-2001.
- ‘%g’
- The year corresponding to the ISO week number, but without the
- century (range ‘00’ through ‘99’). This has the same format
- and value as ‘%y’, except that if the ISO week number (see
- ‘%V’) belongs to the previous or next year, that year is used
- instead.
- This format was first standardized by ISO C99 and by
- POSIX.1-2001.
- ‘%G’
- The year corresponding to the ISO week number. This has the
- same format and value as ‘%Y’, except that if the ISO week
- number (see ‘%V’) belongs to the previous or next year, that
- year is used instead.
- This format was first standardized by ISO C99 and by
- POSIX.1-2001 but was previously available as a GNU extension.
- ‘%h’
- The abbreviated month name according to the current locale.
- The action is the same as for ‘%b’.
- This format was first standardized by POSIX.2-1992 and by
- ISO C99.
- ‘%H’
- The hour as a decimal number, using a 24-hour clock (range
- ‘00’ through ‘23’).
- ‘%I’
- The hour as a decimal number, using a 12-hour clock (range
- ‘01’ through ‘12’).
- ‘%j’
- The day of the year as a decimal number (range ‘001’ through
- ‘366’).
- ‘%k’
- The hour as a decimal number, using a 24-hour clock like ‘%H’,
- but padded with spaces (range ‘ 0’ through ‘23’).
- This format is a GNU extension.
- ‘%l’
- The hour as a decimal number, using a 12-hour clock like ‘%I’,
- but padded with spaces (range ‘ 1’ through ‘12’).
- This format is a GNU extension.
- ‘%m’
- The month as a decimal number (range ‘01’ through ‘12’).
- ‘%M’
- The minute as a decimal number (range ‘00’ through ‘59’).
- ‘%n’
- A single ‘\n’ (newline) character.
- This format was first standardized by POSIX.2-1992 and by
- ISO C99.
- ‘%p’
- Either ‘AM’ or ‘PM’, according to the given time value; or the
- corresponding strings for the current locale. Noon is treated
- as ‘PM’ and midnight as ‘AM’. In most locales ‘AM’/‘PM’
- format is not supported, in such cases ‘"%p"’ yields an empty
- string.
- ‘%P’
- Either ‘am’ or ‘pm’, according to the given time value; or the
- corresponding strings for the current locale, printed in
- lowercase characters. Noon is treated as ‘pm’ and midnight as
- ‘am’. In most locales ‘AM’/‘PM’ format is not supported, in
- such cases ‘"%P"’ yields an empty string.
- This format is a GNU extension.
- ‘%r’
- The complete calendar time using the AM/PM format of the
- current locale.
- This format was first standardized by POSIX.2-1992 and by
- ISO C99. In the POSIX locale, this format is equivalent to
- ‘%I:%M:%S %p’.
- ‘%R’
- The hour and minute in decimal numbers using the format
- ‘%H:%M’.
- This format was first standardized by ISO C99 and by
- POSIX.1-2001 but was previously available as a GNU extension.
- ‘%s’
- The number of seconds since the epoch, i.e., since 1970-01-01
- 00:00:00 UTC. Leap seconds are not counted unless leap second
- support is available.
- This format is a GNU extension.
- ‘%S’
- The seconds as a decimal number (range ‘00’ through ‘60’).
- ‘%t’
- A single ‘\t’ (tabulator) character.
- This format was first standardized by POSIX.2-1992 and by
- ISO C99.
- ‘%T’
- The time of day using decimal numbers using the format
- ‘%H:%M:%S’.
- This format was first standardized by POSIX.2-1992 and by
- ISO C99.
- ‘%u’
- The day of the week as a decimal number (range ‘1’ through
- ‘7’), Monday being ‘1’.
- This format was first standardized by POSIX.2-1992 and by
- ISO C99.
- ‘%U’
- The week number of the current year as a decimal number (range
- ‘00’ through ‘53’), starting with the first Sunday as the
- first day of the first week. Days preceding the first Sunday
- in the year are considered to be in week ‘00’.
- ‘%V’
- The ISO 8601:1988 week number as a decimal number (range ‘01’
- through ‘53’). ISO weeks start with Monday and end with
- Sunday. Week ‘01’ of a year is the first week which has the
- majority of its days in that year; this is equivalent to the
- week containing the year’s first Thursday, and it is also
- equivalent to the week containing January 4. Week ‘01’ of a
- year can contain days from the previous year. The week before
- week ‘01’ of a year is the last week (‘52’ or ‘53’) of the
- previous year even if it contains days from the new year.
- This format was first standardized by POSIX.2-1992 and by
- ISO C99.
- ‘%w’
- The day of the week as a decimal number (range ‘0’ through
- ‘6’), Sunday being ‘0’.
- ‘%W’
- The week number of the current year as a decimal number (range
- ‘00’ through ‘53’), starting with the first Monday as the
- first day of the first week. All days preceding the first
- Monday in the year are considered to be in week ‘00’.
- ‘%x’
- The preferred date representation for the current locale.
- ‘%X’
- The preferred time of day representation for the current
- locale.
- ‘%y’
- The year without a century as a decimal number (range ‘00’
- through ‘99’). This is equivalent to the year modulo 100.
- ‘%Y’
- The year as a decimal number, using the Gregorian calendar.
- Years before the year ‘1’ are numbered ‘0’, ‘-1’, and so on.
- ‘%z’
- RFC 822/ISO 8601:1988 style numeric time zone (e.g., ‘-0600’
- or ‘+0100’), or nothing if no time zone is determinable.
- This format was first standardized by ISO C99 and by
- POSIX.1-2001 but was previously available as a GNU extension.
- In the POSIX locale, a full RFC 822 timestamp is generated by
- the format ‘"%a, %d %b %Y %H:%M:%S %z"’ (or the equivalent
- ‘"%a, %d %b %Y %T %z"’).
- ‘%Z’
- The time zone abbreviation (empty if the time zone can’t be
- determined).
- ‘%%’
- A literal ‘%’ character.
- The SIZE parameter can be used to specify the maximum number of
- characters to be stored in the array S, including the terminating
- null character. If the formatted time requires more than SIZE
- characters, ‘strftime’ returns zero and the contents of the array S
- are undefined. Otherwise the return value indicates the number of
- characters placed in the array S, not including the terminating
- null character.
- _Warning:_ This convention for the return value which is prescribed
- in ISO C can lead to problems in some situations. For certain
- format strings and certain locales the output really can be the
- empty string and this cannot be discovered by testing the return
- value only. E.g., in most locales the AM/PM time format is not
- supported (most of the world uses the 24 hour time representation).
- In such locales ‘"%p"’ will return the empty string, i.e., the
- return value is zero. To detect situations like this something
- similar to the following code should be used:
- buf[0] = '\1';
- len = strftime (buf, bufsize, format, tp);
- if (len == 0 && buf[0] != '\0')
- {
- /* Something went wrong in the strftime call. */
- …
- }
- If S is a null pointer, ‘strftime’ does not actually write
- anything, but instead returns the number of characters it would
- have written.
- Calling ‘strftime’ also sets the current time zone as if ‘tzset’
- were called; ‘strftime’ uses this information instead of
- BROKENTIME’s ‘tm_gmtoff’ and ‘tm_zone’ members. *Note Time Zone
- Functions::.
- For an example of ‘strftime’, see *note Time Functions Example::.
- -- Function: size_t wcsftime (wchar_t *S, size_t SIZE, const wchar_t
- *TEMPLATE, const struct tm *BROKENTIME)
- Preliminary: | MT-Safe env locale | AS-Unsafe corrupt heap lock
- dlopen | AC-Unsafe corrupt lock mem fd | *Note POSIX Safety
- Concepts::.
- The ‘wcsftime’ function is equivalent to the ‘strftime’ function
- with the difference that it operates on wide character strings.
- The buffer where the result is stored, pointed to by S, must be an
- array of wide characters. The parameter SIZE which specifies the
- size of the output buffer gives the number of wide characters, not
- the number of bytes.
- Also the format string TEMPLATE is a wide character string. Since
- all characters needed to specify the format string are in the basic
- character set it is portably possible to write format strings in
- the C source code using the ‘L"…"’ notation. The parameter
- BROKENTIME has the same meaning as in the ‘strftime’ call.
- The ‘wcsftime’ function supports the same flags, modifiers, and
- format specifiers as the ‘strftime’ function.
- The return value of ‘wcsftime’ is the number of wide characters
- stored in ‘s’. When more characters would have to be written than
- can be placed in the buffer S the return value is zero, with the
- same problems indicated in the ‘strftime’ documentation.
- File: libc.info, Node: Parsing Date and Time, Next: TZ Variable, Prev: Formatting Calendar Time, Up: Calendar Time
- 21.4.6 Convert textual time and date information back
- -----------------------------------------------------
- The ISO C standard does not specify any functions which can convert the
- output of the ‘strftime’ function back into a binary format. This led
- to a variety of more-or-less successful implementations with different
- interfaces over the years. Then the Unix standard was extended by the
- addition of two functions: ‘strptime’ and ‘getdate’. Both have strange
- interfaces but at least they are widely available.
- * Menu:
- * Low-Level Time String Parsing:: Interpret string according to given format.
- * General Time String Parsing:: User-friendly function to parse data and
- time strings.
- File: libc.info, Node: Low-Level Time String Parsing, Next: General Time String Parsing, Up: Parsing Date and Time
- 21.4.6.1 Interpret string according to given format
- ...................................................
- The first function is rather low-level. It is nevertheless frequently
- used in software since it is better known. Its interface and
- implementation are heavily influenced by the ‘getdate’ function, which
- is defined and implemented in terms of calls to ‘strptime’.
- -- Function: char * strptime (const char *S, const char *FMT, struct tm
- *TP)
- Preliminary: | MT-Safe env locale | AS-Unsafe heap lock | AC-Unsafe
- lock mem fd | *Note POSIX Safety Concepts::.
- The ‘strptime’ function parses the input string S according to the
- format string FMT and stores its results in the structure TP.
- The input string could be generated by a ‘strftime’ call or
- obtained any other way. It does not need to be in a
- human-recognizable format; e.g. a date passed as ‘"02:1999:9"’ is
- acceptable, even though it is ambiguous without context. As long
- as the format string FMT matches the input string the function will
- succeed.
- The user has to make sure, though, that the input can be parsed in
- a unambiguous way. The string ‘"1999112"’ can be parsed using the
- format ‘"%Y%m%d"’ as 1999-1-12, 1999-11-2, or even 19991-1-2. It
- is necessary to add appropriate separators to reliably get results.
- The format string consists of the same components as the format
- string of the ‘strftime’ function. The only difference is that the
- flags ‘_’, ‘-’, ‘0’, and ‘^’ are not allowed. Several of the
- distinct formats of ‘strftime’ do the same work in ‘strptime’ since
- differences like case of the input do not matter. For reasons of
- symmetry all formats are supported, though.
- The modifiers ‘E’ and ‘O’ are also allowed everywhere the
- ‘strftime’ function allows them.
- The formats are:
- ‘%a’
- ‘%A’
- The weekday name according to the current locale, in
- abbreviated form or the full name.
- ‘%b’
- ‘%B’
- ‘%h’
- The month name according to the current locale, in abbreviated
- form or the full name.
- ‘%c’
- The date and time representation for the current locale.
- ‘%Ec’
- Like ‘%c’ but the locale’s alternative date and time format is
- used.
- ‘%C’
- The century of the year.
- It makes sense to use this format only if the format string
- also contains the ‘%y’ format.
- ‘%EC’
- The locale’s representation of the period.
- Unlike ‘%C’ it sometimes makes sense to use this format since
- some cultures represent years relative to the beginning of
- eras instead of using the Gregorian years.
- ‘%d’
- ‘%e’
- The day of the month as a decimal number (range ‘1’ through
- ‘31’). Leading zeroes are permitted but not required.
- ‘%Od’
- ‘%Oe’
- Same as ‘%d’ but using the locale’s alternative numeric
- symbols.
- Leading zeroes are permitted but not required.
- ‘%D’
- Equivalent to ‘%m/%d/%y’.
- ‘%F’
- Equivalent to ‘%Y-%m-%d’, which is the ISO 8601 date format.
- This is a GNU extension following an ISO C99 extension to
- ‘strftime’.
- ‘%g’
- The year corresponding to the ISO week number, but without the
- century (range ‘00’ through ‘99’).
- _Note:_ Currently, this is not fully implemented. The format
- is recognized, input is consumed but no field in TM is set.
- This format is a GNU extension following a GNU extension of
- ‘strftime’.
- ‘%G’
- The year corresponding to the ISO week number.
- _Note:_ Currently, this is not fully implemented. The format
- is recognized, input is consumed but no field in TM is set.
- This format is a GNU extension following a GNU extension of
- ‘strftime’.
- ‘%H’
- ‘%k’
- The hour as a decimal number, using a 24-hour clock (range
- ‘00’ through ‘23’).
- ‘%k’ is a GNU extension following a GNU extension of
- ‘strftime’.
- ‘%OH’
- Same as ‘%H’ but using the locale’s alternative numeric
- symbols.
- ‘%I’
- ‘%l’
- The hour as a decimal number, using a 12-hour clock (range
- ‘01’ through ‘12’).
- ‘%l’ is a GNU extension following a GNU extension of
- ‘strftime’.
- ‘%OI’
- Same as ‘%I’ but using the locale’s alternative numeric
- symbols.
- ‘%j’
- The day of the year as a decimal number (range ‘1’ through
- ‘366’).
- Leading zeroes are permitted but not required.
- ‘%m’
- The month as a decimal number (range ‘1’ through ‘12’).
- Leading zeroes are permitted but not required.
- ‘%Om’
- Same as ‘%m’ but using the locale’s alternative numeric
- symbols.
- ‘%M’
- The minute as a decimal number (range ‘0’ through ‘59’).
- Leading zeroes are permitted but not required.
- ‘%OM’
- Same as ‘%M’ but using the locale’s alternative numeric
- symbols.
- ‘%n’
- ‘%t’
- Matches any white space.
- ‘%p’
- ‘%P’
- The locale-dependent equivalent to ‘AM’ or ‘PM’.
- This format is not useful unless ‘%I’ or ‘%l’ is also used.
- Another complication is that the locale might not define these
- values at all and therefore the conversion fails.
- ‘%P’ is a GNU extension following a GNU extension to
- ‘strftime’.
- ‘%r’
- The complete time using the AM/PM format of the current
- locale.
- A complication is that the locale might not define this format
- at all and therefore the conversion fails.
- ‘%R’
- The hour and minute in decimal numbers using the format
- ‘%H:%M’.
- ‘%R’ is a GNU extension following a GNU extension to
- ‘strftime’.
- ‘%s’
- The number of seconds since the epoch, i.e., since 1970-01-01
- 00:00:00 UTC. Leap seconds are not counted unless leap second
- support is available.
- ‘%s’ is a GNU extension following a GNU extension to
- ‘strftime’.
- ‘%S’
- The seconds as a decimal number (range ‘0’ through ‘60’).
- Leading zeroes are permitted but not required.
- *NB:* The Unix specification says the upper bound on this
- value is ‘61’, a result of a decision to allow double leap
- seconds. You will not see the value ‘61’ because no minute
- has more than one leap second, but the myth persists.
- ‘%OS’
- Same as ‘%S’ but using the locale’s alternative numeric
- symbols.
- ‘%T’
- Equivalent to the use of ‘%H:%M:%S’ in this place.
- ‘%u’
- The day of the week as a decimal number (range ‘1’ through
- ‘7’), Monday being ‘1’.
- Leading zeroes are permitted but not required.
- _Note:_ Currently, this is not fully implemented. The format
- is recognized, input is consumed but no field in TM is set.
- ‘%U’
- The week number of the current year as a decimal number (range
- ‘0’ through ‘53’).
- Leading zeroes are permitted but not required.
- ‘%OU’
- Same as ‘%U’ but using the locale’s alternative numeric
- symbols.
- ‘%V’
- The ISO 8601:1988 week number as a decimal number (range ‘1’
- through ‘53’).
- Leading zeroes are permitted but not required.
- _Note:_ Currently, this is not fully implemented. The format
- is recognized, input is consumed but no field in TM is set.
- ‘%w’
- The day of the week as a decimal number (range ‘0’ through
- ‘6’), Sunday being ‘0’.
- Leading zeroes are permitted but not required.
- _Note:_ Currently, this is not fully implemented. The format
- is recognized, input is consumed but no field in TM is set.
- ‘%Ow’
- Same as ‘%w’ but using the locale’s alternative numeric
- symbols.
- ‘%W’
- The week number of the current year as a decimal number (range
- ‘0’ through ‘53’).
- Leading zeroes are permitted but not required.
- _Note:_ Currently, this is not fully implemented. The format
- is recognized, input is consumed but no field in TM is set.
- ‘%OW’
- Same as ‘%W’ but using the locale’s alternative numeric
- symbols.
- ‘%x’
- The date using the locale’s date format.
- ‘%Ex’
- Like ‘%x’ but the locale’s alternative data representation is
- used.
- ‘%X’
- The time using the locale’s time format.
- ‘%EX’
- Like ‘%X’ but the locale’s alternative time representation is
- used.
- ‘%y’
- The year without a century as a decimal number (range ‘0’
- through ‘99’).
- Leading zeroes are permitted but not required.
- Note that it is questionable to use this format without the
- ‘%C’ format. The ‘strptime’ function does regard input values
- in the range 68 to 99 as the years 1969 to 1999 and the values
- 0 to 68 as the years 2000 to 2068. But maybe this heuristic
- fails for some input data.
- Therefore it is best to avoid ‘%y’ completely and use ‘%Y’
- instead.
- ‘%Ey’
- The offset from ‘%EC’ in the locale’s alternative
- representation.
- ‘%Oy’
- The offset of the year (from ‘%C’) using the locale’s
- alternative numeric symbols.
- ‘%Y’
- The year as a decimal number, using the Gregorian calendar.
- ‘%EY’
- The full alternative year representation.
- ‘%z’
- The offset from GMT in ISO 8601/RFC822 format.
- ‘%Z’
- The timezone name.
- _Note:_ Currently, this is not fully implemented. The format
- is recognized, input is consumed but no field in TM is set.
- ‘%%’
- A literal ‘%’ character.
- All other characters in the format string must have a matching
- character in the input string. Exceptions are white spaces in the
- input string which can match zero or more whitespace characters in
- the format string.
- *Portability Note:* The XPG standard advises applications to use at
- least one whitespace character (as specified by ‘isspace’) or other
- non-alphanumeric characters between any two conversion
- specifications. The GNU C Library does not have this limitation
- but other libraries might have trouble parsing formats like
- ‘"%d%m%Y%H%M%S"’.
- The ‘strptime’ function processes the input string from right to
- left. Each of the three possible input elements (white space,
- literal, or format) are handled one after the other. If the input
- cannot be matched to the format string the function stops. The
- remainder of the format and input strings are not processed.
- The function returns a pointer to the first character it was unable
- to process. If the input string contains more characters than
- required by the format string the return value points right after
- the last consumed input character. If the whole input string is
- consumed the return value points to the ‘NULL’ byte at the end of
- the string. If an error occurs, i.e., ‘strptime’ fails to match
- all of the format string, the function returns ‘NULL’.
- The specification of the function in the XPG standard is rather
- vague, leaving out a few important pieces of information. Most
- importantly, it does not specify what happens to those elements of TM
- which are not directly initialized by the different formats. The
- implementations on different Unix systems vary here.
- The GNU C Library implementation does not touch those fields which
- are not directly initialized. Exceptions are the ‘tm_wday’ and
- ‘tm_yday’ elements, which are recomputed if any of the year, month, or
- date elements changed. This has two implications:
- • Before calling the ‘strptime’ function for a new input string, you
- should prepare the TM structure you pass. Normally this will mean
- initializing all values to zero. Alternatively, you can set all
- fields to values like ‘INT_MAX’, allowing you to determine which
- elements were set by the function call. Zero does not work here
- since it is a valid value for many of the fields.
- Careful initialization is necessary if you want to find out whether
- a certain field in TM was initialized by the function call.
- • You can construct a ‘struct tm’ value with several consecutive
- ‘strptime’ calls. A useful application of this is e.g. the
- parsing of two separate strings, one containing date information
- and the other time information. By parsing one after the other
- without clearing the structure in-between, you can construct a
- complete broken-down time.
- The following example shows a function which parses a string which
- contains the date information in either US style or ISO 8601 form:
- const char *
- parse_date (const char *input, struct tm *tm)
- {
- const char *cp;
- /* First clear the result structure. */
- memset (tm, '\0', sizeof (*tm));
- /* Try the ISO format first. */
- cp = strptime (input, "%F", tm);
- if (cp == NULL)
- {
- /* Does not match. Try the US form. */
- cp = strptime (input, "%D", tm);
- }
- return cp;
- }
- File: libc.info, Node: General Time String Parsing, Prev: Low-Level Time String Parsing, Up: Parsing Date and Time
- 21.4.6.2 A More User-friendly Way to Parse Times and Dates
- ..........................................................
- The Unix standard defines another function for parsing date strings.
- The interface is weird, but if the function happens to suit your
- application it is just fine. It is problematic to use this function in
- multi-threaded programs or libraries, since it returns a pointer to a
- static variable, and uses a global variable and global state (an
- environment variable).
- -- Variable: getdate_err
- This variable of type ‘int’ contains the error code of the last
- unsuccessful call to ‘getdate’. Defined values are:
- 1
- The environment variable ‘DATEMSK’ is not defined or null.
- 2
- The template file denoted by the ‘DATEMSK’ environment
- variable cannot be opened.
- 3
- Information about the template file cannot retrieved.
- 4
- The template file is not a regular file.
- 5
- An I/O error occurred while reading the template file.
- 6
- Not enough memory available to execute the function.
- 7
- The template file contains no matching template.
- 8
- The input date is invalid, but would match a template
- otherwise. This includes dates like February 31st, and dates
- which cannot be represented in a ‘time_t’ variable.
- -- Function: struct tm * getdate (const char *STRING)
- Preliminary: | MT-Unsafe race:getdate env locale | AS-Unsafe heap
- lock | AC-Unsafe lock mem fd | *Note POSIX Safety Concepts::.
- The interface to ‘getdate’ is the simplest possible for a function
- to parse a string and return the value. STRING is the input string
- and the result is returned in a statically-allocated variable.
- The details about how the string is processed are hidden from the
- user. In fact, they can be outside the control of the program.
- Which formats are recognized is controlled by the file named by the
- environment variable ‘DATEMSK’. This file should contain lines of
- valid format strings which could be passed to ‘strptime’.
- The ‘getdate’ function reads these format strings one after the
- other and tries to match the input string. The first line which
- completely matches the input string is used.
- Elements not initialized through the format string retain the
- values present at the time of the ‘getdate’ function call.
- The formats recognized by ‘getdate’ are the same as for ‘strptime’.
- See above for an explanation. There are only a few extensions to
- the ‘strptime’ behavior:
- • If the ‘%Z’ format is given the broken-down time is based on
- the current time of the timezone matched, not of the current
- timezone of the runtime environment.
- _Note_: This is not implemented (currently). The problem is
- that timezone names are not unique. If a fixed timezone is
- assumed for a given string (say ‘EST’ meaning US East Coast
- time), then uses for countries other than the USA will fail.
- So far we have found no good solution to this.
- • If only the weekday is specified the selected day depends on
- the current date. If the current weekday is greater than or
- equal to the ‘tm_wday’ value the current week’s day is chosen,
- otherwise the day next week is chosen.
- • A similar heuristic is used when only the month is given and
- not the year. If the month is greater than or equal to the
- current month, then the current year is used. Otherwise it
- wraps to next year. The first day of the month is assumed if
- one is not explicitly specified.
- • The current hour, minute, and second are used if the
- appropriate value is not set through the format.
- • If no date is given tomorrow’s date is used if the time is
- smaller than the current time. Otherwise today’s date is
- taken.
- It should be noted that the format in the template file need not
- only contain format elements. The following is a list of possible
- format strings (taken from the Unix standard):
- %m
- %A %B %d, %Y %H:%M:%S
- %A
- %B
- %m/%d/%y %I %p
- %d,%m,%Y %H:%M
- at %A the %dst of %B in %Y
- run job at %I %p,%B %dnd
- %A den %d. %B %Y %H.%M Uhr
- As you can see, the template list can contain very specific strings
- like ‘run job at %I %p,%B %dnd’. Using the above list of templates
- and assuming the current time is Mon Sep 22 12:19:47 EDT 1986, we
- can obtain the following results for the given input.
- Input Match Result
- Mon %a Mon Sep 22 12:19:47 EDT 1986
- Sun %a Sun Sep 28 12:19:47 EDT 1986
- Fri %a Fri Sep 26 12:19:47 EDT 1986
- September %B Mon Sep 1 12:19:47 EDT 1986
- January %B Thu Jan 1 12:19:47 EST 1987
- December %B Mon Dec 1 12:19:47 EST 1986
- Sep Mon %b %a Mon Sep 1 12:19:47 EDT 1986
- Jan Fri %b %a Fri Jan 2 12:19:47 EST 1987
- Dec Mon %b %a Mon Dec 1 12:19:47 EST 1986
- Jan Wed 1989 %b %a %Y Wed Jan 4 12:19:47 EST 1989
- Fri 9 %a %H Fri Sep 26 09:00:00 EDT 1986
- Feb 10:30 %b %H:%S Sun Feb 1 10:00:30 EST 1987
- 10:30 %H:%M Tue Sep 23 10:30:00 EDT 1986
- 13:30 %H:%M Mon Sep 22 13:30:00 EDT 1986
- The return value of the function is a pointer to a static variable
- of type ‘struct tm’, or a null pointer if an error occurred. The
- result is only valid until the next ‘getdate’ call, making this
- function unusable in multi-threaded applications.
- The ‘errno’ variable is _not_ changed. Error conditions are stored
- in the global variable ‘getdate_err’. See the description above
- for a list of the possible error values.
- _Warning:_ The ‘getdate’ function should _never_ be used in
- SUID-programs. The reason is obvious: using the ‘DATEMSK’
- environment variable you can get the function to open any arbitrary
- file and chances are high that with some bogus input (such as a
- binary file) the program will crash.
- -- Function: int getdate_r (const char *STRING, struct tm *TP)
- Preliminary: | MT-Safe env locale | AS-Unsafe heap lock | AC-Unsafe
- lock mem fd | *Note POSIX Safety Concepts::.
- The ‘getdate_r’ function is the reentrant counterpart of ‘getdate’.
- It does not use the global variable ‘getdate_err’ to signal an
- error, but instead returns an error code. The same error codes as
- described in the ‘getdate_err’ documentation above are used, with 0
- meaning success.
- Moreover, ‘getdate_r’ stores the broken-down time in the variable
- of type ‘struct tm’ pointed to by the second argument, rather than
- in a static variable.
- This function is not defined in the Unix standard. Nevertheless it
- is available on some other Unix systems as well.
- The warning against using ‘getdate’ in SUID-programs applies to
- ‘getdate_r’ as well.
- File: libc.info, Node: TZ Variable, Next: Time Zone Functions, Prev: Parsing Date and Time, Up: Calendar Time
- 21.4.7 Specifying the Time Zone with ‘TZ’
- -----------------------------------------
- In POSIX systems, a user can specify the time zone by means of the ‘TZ’
- environment variable. For information about how to set environment
- variables, see *note Environment Variables::. The functions for
- accessing the time zone are declared in ‘time.h’.
- You should not normally need to set ‘TZ’. If the system is
- configured properly, the default time zone will be correct. You might
- set ‘TZ’ if you are using a computer over a network from a different
- time zone, and would like times reported to you in the time zone local
- to you, rather than what is local to the computer.
- In POSIX.1 systems the value of the ‘TZ’ variable can be in one of
- three formats. With the GNU C Library, the most common format is the
- last one, which can specify a selection from a large database of time
- zone information for many regions of the world. The first two formats
- are used to describe the time zone information directly, which is both
- more cumbersome and less precise. But the POSIX.1 standard only
- specifies the details of the first two formats, so it is good to be
- familiar with them in case you come across a POSIX.1 system that doesn’t
- support a time zone information database.
- The first format is used when there is no Daylight Saving Time (or
- summer time) in the local time zone:
- STD OFFSET
- The STD string specifies the name of the time zone. It must be three
- or more characters long and must not contain a leading colon, embedded
- digits, commas, nor plus and minus signs. There is no space character
- separating the time zone name from the OFFSET, so these restrictions are
- necessary to parse the specification correctly.
- The OFFSET specifies the time value you must add to the local time to
- get a Coordinated Universal Time value. It has syntax like
- [‘+’|‘-’]HH[‘:’MM[‘:’SS]]. This is positive if the local time zone is
- west of the Prime Meridian and negative if it is east. The hour must be
- between ‘0’ and ‘24’, and the minute and seconds between ‘0’ and ‘59’.
- For example, here is how we would specify Eastern Standard Time, but
- without any Daylight Saving Time alternative:
- EST+5
- The second format is used when there is Daylight Saving Time:
- STD OFFSET DST [OFFSET]‘,’START[‘/’TIME]‘,’END[‘/’TIME]
- The initial STD and OFFSET specify the standard time zone, as
- described above. The DST string and OFFSET specify the name and offset
- for the corresponding Daylight Saving Time zone; if the OFFSET is
- omitted, it defaults to one hour ahead of standard time.
- The remainder of the specification describes when Daylight Saving
- Time is in effect. The START field is when Daylight Saving Time goes
- into effect and the END field is when the change is made back to
- standard time. The following formats are recognized for these fields:
- ‘JN’
- This specifies the Julian day, with N between ‘1’ and ‘365’.
- February 29 is never counted, even in leap years.
- ‘N’
- This specifies the Julian day, with N between ‘0’ and ‘365’.
- February 29 is counted in leap years.
- ‘MM.W.D’
- This specifies day D of week W of month M. The day D must be
- between ‘0’ (Sunday) and ‘6’. The week W must be between ‘1’ and
- ‘5’; week ‘1’ is the first week in which day D occurs, and week ‘5’
- specifies the _last_ D day in the month. The month M should be
- between ‘1’ and ‘12’.
- The TIME fields specify when, in the local time currently in effect,
- the change to the other time occurs. If omitted, the default is
- ‘02:00:00’. The hours part of the time fields can range from −167
- through 167; this is an extension to POSIX.1, which allows only the
- range 0 through 24.
- Here are some example ‘TZ’ values, including the appropriate Daylight
- Saving Time and its dates of applicability. In North American Eastern
- Standard Time (EST) and Eastern Daylight Time (EDT), the normal offset
- from UTC is 5 hours; since this is west of the prime meridian, the sign
- is positive. Summer time begins on March’s second Sunday at 2:00am, and
- ends on November’s first Sunday at 2:00am.
- EST+5EDT,M3.2.0/2,M11.1.0/2
- Israel Standard Time (IST) and Israel Daylight Time (IDT) are 2 hours
- ahead of the prime meridian in winter, springing forward an hour on
- March’s fourth Thursday at 26:00 (i.e., 02:00 on the first Friday on or
- after March 23), and falling back on October’s last Sunday at 02:00.
- IST-2IDT,M3.4.4/26,M10.5.0
- Western Argentina Summer Time (WARST) is 3 hours behind the prime
- meridian all year. There is a dummy fall-back transition on December 31
- at 25:00 daylight saving time (i.e., 24:00 standard time, equivalent to
- January 1 at 00:00 standard time), and a simultaneous spring-forward
- transition on January 1 at 00:00 standard time, so daylight saving time
- is in effect all year and the initial ‘WART’ is a placeholder.
- WART4WARST,J1/0,J365/25
- Western Greenland Time (WGT) and Western Greenland Summer Time (WGST)
- are 3 hours behind UTC in the winter. Its clocks follow the European
- Union rules of springing forward by one hour on March’s last Sunday at
- 01:00 UTC (−02:00 local time) and falling back on October’s last Sunday
- at 01:00 UTC (−01:00 local time).
- WGT3WGST,M3.5.0/-2,M10.5.0/-1
- The schedule of Daylight Saving Time in any particular jurisdiction
- has changed over the years. To be strictly correct, the conversion of
- dates and times in the past should be based on the schedule that was in
- effect then. However, this format has no facilities to let you specify
- how the schedule has changed from year to year. The most you can do is
- specify one particular schedule—usually the present day schedule—and
- this is used to convert any date, no matter when. For precise time zone
- specifications, it is best to use the time zone information database
- (see below).
- The third format looks like this:
- :CHARACTERS
- Each operating system interprets this format differently; in the GNU
- C Library, CHARACTERS is the name of a file which describes the time
- zone.
- If the ‘TZ’ environment variable does not have a value, the operation
- chooses a time zone by default. In the GNU C Library, the default time
- zone is like the specification ‘TZ=:/etc/localtime’ (or
- ‘TZ=:/usr/local/etc/localtime’, depending on how the GNU C Library was
- configured; *note Installation::). Other C libraries use their own rule
- for choosing the default time zone, so there is little we can say about
- them.
- If CHARACTERS begins with a slash, it is an absolute file name;
- otherwise the library looks for the file
- ‘/usr/share/zoneinfo/CHARACTERS’. The ‘zoneinfo’ directory contains
- data files describing local time zones in many different parts of the
- world. The names represent major cities, with subdirectories for
- geographical areas; for example, ‘America/New_York’, ‘Europe/London’,
- ‘Asia/Hong_Kong’. These data files are installed by the system
- administrator, who also sets ‘/etc/localtime’ to point to the data file
- for the local time zone. The files typically come from the Time Zone
- Database (http://www.iana.org/time-zones) of time zone and daylight
- saving time information for most regions of the world, which is
- maintained by a community of volunteers and put in the public domain.
- File: libc.info, Node: Time Zone Functions, Next: Time Functions Example, Prev: TZ Variable, Up: Calendar Time
- 21.4.8 Functions and Variables for Time Zones
- ---------------------------------------------
- -- Variable: char * tzname [2]
- The array ‘tzname’ contains two strings, which are the standard
- names of the pair of time zones (standard and Daylight Saving) that
- the user has selected. ‘tzname[0]’ is the name of the standard
- time zone (for example, ‘"EST"’), and ‘tzname[1]’ is the name for
- the time zone when Daylight Saving Time is in use (for example,
- ‘"EDT"’). These correspond to the STD and DST strings
- (respectively) from the ‘TZ’ environment variable. If Daylight
- Saving Time is never used, ‘tzname[1]’ is the empty string.
- The ‘tzname’ array is initialized from the ‘TZ’ environment
- variable whenever ‘tzset’, ‘ctime’, ‘strftime’, ‘mktime’, or
- ‘localtime’ is called. If multiple abbreviations have been used
- (e.g. ‘"EWT"’ and ‘"EDT"’ for U.S. Eastern War Time and Eastern
- Daylight Time), the array contains the most recent abbreviation.
- The ‘tzname’ array is required for POSIX.1 compatibility, but in
- GNU programs it is better to use the ‘tm_zone’ member of the
- broken-down time structure, since ‘tm_zone’ reports the correct
- abbreviation even when it is not the latest one.
- Though the strings are declared as ‘char *’ the user must refrain
- from modifying these strings. Modifying the strings will almost
- certainly lead to trouble.
- -- Function: void tzset (void)
- Preliminary: | MT-Safe env locale | AS-Unsafe heap lock | AC-Unsafe
- lock mem fd | *Note POSIX Safety Concepts::.
- The ‘tzset’ function initializes the ‘tzname’ variable from the
- value of the ‘TZ’ environment variable. It is not usually
- necessary for your program to call this function, because it is
- called automatically when you use the other time conversion
- functions that depend on the time zone.
- The following variables are defined for compatibility with System V
- Unix. Like ‘tzname’, these variables are set by calling ‘tzset’ or the
- other time conversion functions.
- -- Variable: long int timezone
- This contains the difference between UTC and the latest local
- standard time, in seconds west of UTC. For example, in the U.S.
- Eastern time zone, the value is ‘5*60*60’. Unlike the ‘tm_gmtoff’
- member of the broken-down time structure, this value is not
- adjusted for daylight saving, and its sign is reversed. In GNU
- programs it is better to use ‘tm_gmtoff’, since it contains the
- correct offset even when it is not the latest one.
- -- Variable: int daylight
- This variable has a nonzero value if Daylight Saving Time rules
- apply. A nonzero value does not necessarily mean that Daylight
- Saving Time is now in effect; it means only that Daylight Saving
- Time is sometimes in effect.
- File: libc.info, Node: Time Functions Example, Prev: Time Zone Functions, Up: Calendar Time
- 21.4.9 Time Functions Example
- -----------------------------
- Here is an example program showing the use of some of the calendar time
- functions.
- #include <time.h>
- #include <stdio.h>
- #define SIZE 256
- int
- main (void)
- {
- char buffer[SIZE];
- time_t curtime;
- struct tm *loctime;
- /* Get the current time. */
- curtime = time (NULL);
- /* Convert it to local time representation. */
- loctime = localtime (&curtime);
- /* Print out the date and time in the standard format. */
- fputs (asctime (loctime), stdout);
- /* Print it out in a nice format. */
- strftime (buffer, SIZE, "Today is %A, %B %d.\n", loctime);
- fputs (buffer, stdout);
- strftime (buffer, SIZE, "The time is %I:%M %p.\n", loctime);
- fputs (buffer, stdout);
- return 0;
- }
- It produces output like this:
- Wed Jul 31 13:02:36 1991
- Today is Wednesday, July 31.
- The time is 01:02 PM.
- File: libc.info, Node: Setting an Alarm, Next: Sleeping, Prev: Calendar Time, Up: Date and Time
- 21.5 Setting an Alarm
- =====================
- The ‘alarm’ and ‘setitimer’ functions provide a mechanism for a process
- to interrupt itself in the future. They do this by setting a timer;
- when the timer expires, the process receives a signal.
- Each process has three independent interval timers available:
- • A real-time timer that counts elapsed time. This timer sends a
- ‘SIGALRM’ signal to the process when it expires.
- • A virtual timer that counts processor time used by the process.
- This timer sends a ‘SIGVTALRM’ signal to the process when it
- expires.
- • A profiling timer that counts both processor time used by the
- process, and processor time spent in system calls on behalf of the
- process. This timer sends a ‘SIGPROF’ signal to the process when
- it expires.
- This timer is useful for profiling in interpreters. The interval
- timer mechanism does not have the fine granularity necessary for
- profiling native code.
- You can only have one timer of each kind set at any given time. If
- you set a timer that has not yet expired, that timer is simply reset to
- the new value.
- You should establish a handler for the appropriate alarm signal using
- ‘signal’ or ‘sigaction’ before issuing a call to ‘setitimer’ or ‘alarm’.
- Otherwise, an unusual chain of events could cause the timer to expire
- before your program establishes the handler. In this case it would be
- terminated, since termination is the default action for the alarm
- signals. *Note Signal Handling::.
- To be able to use the alarm function to interrupt a system call which
- might block otherwise indefinitely it is important to _not_ set the
- ‘SA_RESTART’ flag when registering the signal handler using ‘sigaction’.
- When not using ‘sigaction’ things get even uglier: the ‘signal’ function
- has fixed semantics with respect to restarts. The BSD semantics for
- this function is to set the flag. Therefore, if ‘sigaction’ for
- whatever reason cannot be used, it is necessary to use ‘sysv_signal’ and
- not ‘signal’.
- The ‘setitimer’ function is the primary means for setting an alarm.
- This facility is declared in the header file ‘sys/time.h’. The ‘alarm’
- function, declared in ‘unistd.h’, provides a somewhat simpler interface
- for setting the real-time timer.
- -- Data Type: struct itimerval
- This structure is used to specify when a timer should expire. It
- contains the following members:
- ‘struct timeval it_interval’
- This is the period between successive timer interrupts. If
- zero, the alarm will only be sent once.
- ‘struct timeval it_value’
- This is the period between now and the first timer interrupt.
- If zero, the alarm is disabled.
- The ‘struct timeval’ data type is described in *note Elapsed
- Time::.
- -- Function: int setitimer (int WHICH, const struct itimerval *NEW,
- struct itimerval *OLD)
- Preliminary: | MT-Safe timer | AS-Safe | AC-Safe | *Note POSIX
- Safety Concepts::.
- The ‘setitimer’ function sets the timer specified by WHICH
- according to NEW. The WHICH argument can have a value of
- ‘ITIMER_REAL’, ‘ITIMER_VIRTUAL’, or ‘ITIMER_PROF’.
- If OLD is not a null pointer, ‘setitimer’ returns information about
- any previous unexpired timer of the same kind in the structure it
- points to.
- The return value is ‘0’ on success and ‘-1’ on failure. The
- following ‘errno’ error conditions are defined for this function:
- ‘EINVAL’
- The timer period is too large.
- -- Function: int getitimer (int WHICH, struct itimerval *OLD)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘getitimer’ function stores information about the timer
- specified by WHICH in the structure pointed at by OLD.
- The return value and error conditions are the same as for
- ‘setitimer’.
- ‘ITIMER_REAL’
- This constant can be used as the WHICH argument to the ‘setitimer’
- and ‘getitimer’ functions to specify the real-time timer.
- ‘ITIMER_VIRTUAL’
- This constant can be used as the WHICH argument to the ‘setitimer’
- and ‘getitimer’ functions to specify the virtual timer.
- ‘ITIMER_PROF’
- This constant can be used as the WHICH argument to the ‘setitimer’
- and ‘getitimer’ functions to specify the profiling timer.
- -- Function: unsigned int alarm (unsigned int SECONDS)
- Preliminary: | MT-Safe timer | AS-Safe | AC-Safe | *Note POSIX
- Safety Concepts::.
- The ‘alarm’ function sets the real-time timer to expire in SECONDS
- seconds. If you want to cancel any existing alarm, you can do this
- by calling ‘alarm’ with a SECONDS argument of zero.
- The return value indicates how many seconds remain before the
- previous alarm would have been sent. If there was no previous
- alarm, ‘alarm’ returns zero.
- The ‘alarm’ function could be defined in terms of ‘setitimer’ like
- this:
- unsigned int
- alarm (unsigned int seconds)
- {
- struct itimerval old, new;
- new.it_interval.tv_usec = 0;
- new.it_interval.tv_sec = 0;
- new.it_value.tv_usec = 0;
- new.it_value.tv_sec = (long int) seconds;
- if (setitimer (ITIMER_REAL, &new, &old) < 0)
- return 0;
- else
- return old.it_value.tv_sec;
- }
- There is an example showing the use of the ‘alarm’ function in *note
- Handler Returns::.
- If you simply want your process to wait for a given number of
- seconds, you should use the ‘sleep’ function. *Note Sleeping::.
- You shouldn’t count on the signal arriving precisely when the timer
- expires. In a multiprocessing environment there is typically some
- amount of delay involved.
- *Portability Note:* The ‘setitimer’ and ‘getitimer’ functions are
- derived from BSD Unix, while the ‘alarm’ function is specified by the
- POSIX.1 standard. ‘setitimer’ is more powerful than ‘alarm’, but
- ‘alarm’ is more widely used.
- File: libc.info, Node: Sleeping, Prev: Setting an Alarm, Up: Date and Time
- 21.6 Sleeping
- =============
- The function ‘sleep’ gives a simple way to make the program wait for a
- short interval. If your program doesn’t use signals (except to
- terminate), then you can expect ‘sleep’ to wait reliably throughout the
- specified interval. Otherwise, ‘sleep’ can return sooner if a signal
- arrives; if you want to wait for a given interval regardless of signals,
- use ‘select’ (*note Waiting for I/O::) and don’t specify any descriptors
- to wait for.
- -- Function: unsigned int sleep (unsigned int SECONDS)
- Preliminary: | MT-Unsafe sig:SIGCHLD/linux | AS-Unsafe | AC-Unsafe
- | *Note POSIX Safety Concepts::.
- The ‘sleep’ function waits for SECONDS seconds or until a signal is
- delivered, whichever happens first.
- If ‘sleep’ returns because the requested interval is over, it
- returns a value of zero. If it returns because of delivery of a
- signal, its return value is the remaining time in the sleep
- interval.
- The ‘sleep’ function is declared in ‘unistd.h’.
- Resist the temptation to implement a sleep for a fixed amount of time
- by using the return value of ‘sleep’, when nonzero, to call ‘sleep’
- again. This will work with a certain amount of accuracy as long as
- signals arrive infrequently. But each signal can cause the eventual
- wakeup time to be off by an additional second or so. Suppose a few
- signals happen to arrive in rapid succession by bad luck—there is no
- limit on how much this could shorten or lengthen the wait.
- Instead, compute the calendar time at which the program should stop
- waiting, and keep trying to wait until that calendar time. This won’t
- be off by more than a second. With just a little more work, you can use
- ‘select’ and make the waiting period quite accurate. (Of course, heavy
- system load can cause additional unavoidable delays—unless the machine
- is dedicated to one application, there is no way you can avoid this.)
- On some systems, ‘sleep’ can do strange things if your program uses
- ‘SIGALRM’ explicitly. Even if ‘SIGALRM’ signals are being ignored or
- blocked when ‘sleep’ is called, ‘sleep’ might return prematurely on
- delivery of a ‘SIGALRM’ signal. If you have established a handler for
- ‘SIGALRM’ signals and a ‘SIGALRM’ signal is delivered while the process
- is sleeping, the action taken might be just to cause ‘sleep’ to return
- instead of invoking your handler. And, if ‘sleep’ is interrupted by
- delivery of a signal whose handler requests an alarm or alters the
- handling of ‘SIGALRM’, this handler and ‘sleep’ will interfere.
- On GNU systems, it is safe to use ‘sleep’ and ‘SIGALRM’ in the same
- program, because ‘sleep’ does not work by means of ‘SIGALRM’.
- -- Function: int nanosleep (const struct timespec *REQUESTED_TIME,
- struct timespec *REMAINING)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- If resolution to seconds is not enough the ‘nanosleep’ function can
- be used. As the name suggests the sleep interval can be specified
- in nanoseconds. The actual elapsed time of the sleep interval
- might be longer since the system rounds the elapsed time you
- request up to the next integer multiple of the actual resolution
- the system can deliver.
- *‘requested_time’ is the elapsed time of the interval you want to
- sleep.
- The function returns as *‘remaining’ the elapsed time left in the
- interval for which you requested to sleep. If the interval
- completed without getting interrupted by a signal, this is zero.
- ‘struct timespec’ is described in *Note Elapsed Time::.
- If the function returns because the interval is over the return
- value is zero. If the function returns -1 the global variable
- ERRNO is set to the following values:
- ‘EINTR’
- The call was interrupted because a signal was delivered to the
- thread. If the REMAINING parameter is not the null pointer
- the structure pointed to by REMAINING is updated to contain
- the remaining elapsed time.
- ‘EINVAL’
- The nanosecond value in the REQUESTED_TIME parameter contains
- an illegal value. Either the value is negative or greater
- than or equal to 1000 million.
- 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
- ‘nanosleep’ is called. If the thread gets canceled these resources
- stay allocated until the program ends. To avoid this calls to
- ‘nanosleep’ should be protected using cancellation handlers.
- The ‘nanosleep’ function is declared in ‘time.h’.
- File: libc.info, Node: Resource Usage And Limitation, Next: Non-Local Exits, Prev: Date and Time, Up: Top
- 22 Resource Usage And Limitation
- ********************************
- This chapter describes functions for examining how much of various kinds
- of resources (CPU time, memory, etc.) a process has used and getting
- and setting limits on future usage.
- * Menu:
- * Resource Usage:: Measuring various resources used.
- * Limits on Resources:: Specifying limits on resource usage.
- * Priority:: Reading or setting process run priority.
- * Memory Resources:: Querying memory available resources.
- * Processor Resources:: Learn about the processors available.
- File: libc.info, Node: Resource Usage, Next: Limits on Resources, Up: Resource Usage And Limitation
- 22.1 Resource Usage
- ===================
- The function ‘getrusage’ and the data type ‘struct rusage’ are used to
- examine the resource usage of a process. They are declared in
- ‘sys/resource.h’.
- -- Function: int getrusage (int PROCESSES, struct rusage *RUSAGE)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function reports resource usage totals for processes specified
- by PROCESSES, storing the information in ‘*RUSAGE’.
- In most systems, PROCESSES has only two valid values:
- ‘RUSAGE_SELF’
- Just the current process.
- ‘RUSAGE_CHILDREN’
- All child processes (direct and indirect) that have already
- terminated.
- The return value of ‘getrusage’ is zero for success, and ‘-1’ for
- failure.
- ‘EINVAL’
- The argument PROCESSES is not valid.
- One way of getting resource usage for a particular child process is
- with the function ‘wait4’, which returns totals for a child when it
- terminates. *Note BSD Wait Functions::.
- -- Data Type: struct rusage
- This data type stores various resource usage statistics. It has
- the following members, and possibly others:
- ‘struct timeval ru_utime’
- Time spent executing user instructions.
- ‘struct timeval ru_stime’
- Time spent in operating system code on behalf of PROCESSES.
- ‘long int ru_maxrss’
- The maximum resident set size used, in kilobytes. That is,
- the maximum number of kilobytes of physical memory that
- PROCESSES used simultaneously.
- ‘long int ru_ixrss’
- An integral value expressed in kilobytes times ticks of
- execution, which indicates the amount of memory used by text
- that was shared with other processes.
- ‘long int ru_idrss’
- An integral value expressed the same way, which is the amount
- of unshared memory used for data.
- ‘long int ru_isrss’
- An integral value expressed the same way, which is the amount
- of unshared memory used for stack space.
- ‘long int ru_minflt’
- The number of page faults which were serviced without
- requiring any I/O.
- ‘long int ru_majflt’
- The number of page faults which were serviced by doing I/O.
- ‘long int ru_nswap’
- The number of times PROCESSES was swapped entirely out of main
- memory.
- ‘long int ru_inblock’
- The number of times the file system had to read from the disk
- on behalf of PROCESSES.
- ‘long int ru_oublock’
- The number of times the file system had to write to the disk
- on behalf of PROCESSES.
- ‘long int ru_msgsnd’
- Number of IPC messages sent.
- ‘long int ru_msgrcv’
- Number of IPC messages received.
- ‘long int ru_nsignals’
- Number of signals received.
- ‘long int ru_nvcsw’
- The number of times PROCESSES voluntarily invoked a context
- switch (usually to wait for some service).
- ‘long int ru_nivcsw’
- The number of times an involuntary context switch took place
- (because a time slice expired, or another process of higher
- priority was scheduled).
- ‘vtimes’ is a historical function that does some of what ‘getrusage’
- does. ‘getrusage’ is a better choice.
- ‘vtimes’ and its ‘vtimes’ data structure are declared in
- ‘sys/vtimes.h’.
- -- Function: int vtimes (struct vtimes *CURRENT, struct vtimes *CHILD)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- ‘vtimes’ reports resource usage totals for a process.
- If CURRENT is non-null, ‘vtimes’ stores resource usage totals for
- the invoking process alone in the structure to which it points. If
- CHILD is non-null, ‘vtimes’ stores resource usage totals for all
- past children (which have terminated) of the invoking process in
- the structure to which it points.
- -- Data Type: struct vtimes
- This data type contains information about the resource usage
- of a process. Each member corresponds to a member of the
- ‘struct rusage’ data type described above.
- ‘vm_utime’
- User CPU time. Analogous to ‘ru_utime’ in ‘struct
- rusage’
- ‘vm_stime’
- System CPU time. Analogous to ‘ru_stime’ in ‘struct
- rusage’
- ‘vm_idsrss’
- Data and stack memory. The sum of the values that would
- be reported as ‘ru_idrss’ and ‘ru_isrss’ in ‘struct
- rusage’
- ‘vm_ixrss’
- Shared memory. Analogous to ‘ru_ixrss’ in ‘struct
- rusage’
- ‘vm_maxrss’
- Maximent resident set size. Analogous to ‘ru_maxrss’ in
- ‘struct rusage’
- ‘vm_majflt’
- Major page faults. Analogous to ‘ru_majflt’ in ‘struct
- rusage’
- ‘vm_minflt’
- Minor page faults. Analogous to ‘ru_minflt’ in ‘struct
- rusage’
- ‘vm_nswap’
- Swap count. Analogous to ‘ru_nswap’ in ‘struct rusage’
- ‘vm_inblk’
- Disk reads. Analogous to ‘ru_inblk’ in ‘struct rusage’
- ‘vm_oublk’
- Disk writes. Analogous to ‘ru_oublk’ in ‘struct rusage’
- The return value is zero if the function succeeds; ‘-1’ otherwise.
- An additional historical function for examining resource usage,
- ‘vtimes’, is supported but not documented here. It is declared in
- ‘sys/vtimes.h’.
- File: libc.info, Node: Limits on Resources, Next: Priority, Prev: Resource Usage, Up: Resource Usage And Limitation
- 22.2 Limiting Resource Usage
- ============================
- You can specify limits for the resource usage of a process. When the
- process tries to exceed a limit, it may get a signal, or the system call
- by which it tried to do so may fail, depending on the resource. Each
- process initially inherits its limit values from its parent, but it can
- subsequently change them.
- There are two per-process limits associated with a resource:
- "current limit"
- The current limit is the value the system will not allow usage to
- exceed. It is also called the “soft limit” because the process
- being limited can generally raise the current limit at will.
- "maximum limit"
- The maximum limit is the maximum value to which a process is
- allowed to set its current limit. It is also called the “hard
- limit” because there is no way for a process to get around it. A
- process may lower its own maximum limit, but only the superuser may
- increase a maximum limit.
- The symbols for use with ‘getrlimit’, ‘setrlimit’, ‘getrlimit64’, and
- ‘setrlimit64’ are defined in ‘sys/resource.h’.
- -- Function: int getrlimit (int RESOURCE, struct rlimit *RLP)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- Read the current and maximum limits for the resource RESOURCE and
- store them in ‘*RLP’.
- The return value is ‘0’ on success and ‘-1’ on failure. The only
- possible ‘errno’ error condition is ‘EFAULT’.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
- 32-bit system this function is in fact ‘getrlimit64’. Thus, the
- LFS interface transparently replaces the old interface.
- -- Function: int getrlimit64 (int RESOURCE, struct rlimit64 *RLP)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function is similar to ‘getrlimit’ but its second parameter is
- a pointer to a variable of type ‘struct rlimit64’, which allows it
- to read values which wouldn’t fit in the member of a ‘struct
- rlimit’.
- If the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
- 32-bit machine, this function is available under the name
- ‘getrlimit’ and so transparently replaces the old interface.
- -- Function: int setrlimit (int RESOURCE, const struct rlimit *RLP)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- Store the current and maximum limits for the resource RESOURCE in
- ‘*RLP’.
- The return value is ‘0’ on success and ‘-1’ on failure. The
- following ‘errno’ error condition is possible:
- ‘EPERM’
- • The process tried to raise a current limit beyond the
- maximum limit.
- • The process tried to raise a maximum limit, but is not
- superuser.
- When the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
- 32-bit system this function is in fact ‘setrlimit64’. Thus, the
- LFS interface transparently replaces the old interface.
- -- Function: int setrlimit64 (int RESOURCE, const struct rlimit64 *RLP)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function is similar to ‘setrlimit’ but its second parameter is
- a pointer to a variable of type ‘struct rlimit64’ which allows it
- to set values which wouldn’t fit in the member of a ‘struct
- rlimit’.
- If the sources are compiled with ‘_FILE_OFFSET_BITS == 64’ on a
- 32-bit machine this function is available under the name
- ‘setrlimit’ and so transparently replaces the old interface.
- -- Data Type: struct rlimit
- This structure is used with ‘getrlimit’ to receive limit values,
- and with ‘setrlimit’ to specify limit values for a particular
- process and resource. It has two fields:
- ‘rlim_t rlim_cur’
- The current limit
- ‘rlim_t rlim_max’
- The maximum limit.
- For ‘getrlimit’, the structure is an output; it receives the
- current values. For ‘setrlimit’, it specifies the new values.
- For the LFS functions a similar type is defined in ‘sys/resource.h’.
- -- Data Type: struct rlimit64
- This structure is analogous to the ‘rlimit’ structure above, but
- its components have wider ranges. It has two fields:
- ‘rlim64_t rlim_cur’
- This is analogous to ‘rlimit.rlim_cur’, but with a different
- type.
- ‘rlim64_t rlim_max’
- This is analogous to ‘rlimit.rlim_max’, but with a different
- type.
- Here is a list of resources for which you can specify a limit.
- Memory and file sizes are measured in bytes.
- ‘RLIMIT_CPU’
- The maximum amount of CPU time the process can use. If it runs for
- longer than this, it gets a signal: ‘SIGXCPU’. The value is
- measured in seconds. *Note Operation Error Signals::.
- ‘RLIMIT_FSIZE’
- The maximum size of file the process can create. Trying to write a
- larger file causes a signal: ‘SIGXFSZ’. *Note Operation Error
- Signals::.
- ‘RLIMIT_DATA’
- The maximum size of data memory for the process. If the process
- tries to allocate data memory beyond this amount, the allocation
- function fails.
- ‘RLIMIT_STACK’
- The maximum stack size for the process. If the process tries to
- extend its stack past this size, it gets a ‘SIGSEGV’ signal. *Note
- Program Error Signals::.
- ‘RLIMIT_CORE’
- The maximum size core file that this process can create. If the
- process terminates and would dump a core file larger than this,
- then no core file is created. So setting this limit to zero
- prevents core files from ever being created.
- ‘RLIMIT_RSS’
- The maximum amount of physical memory that this process should get.
- This parameter is a guide for the system’s scheduler and memory
- allocator; the system may give the process more memory when there
- is a surplus.
- ‘RLIMIT_MEMLOCK’
- The maximum amount of memory that can be locked into physical
- memory (so it will never be paged out).
- ‘RLIMIT_NPROC’
- The maximum number of processes that can be created with the same
- user ID. If you have reached the limit for your user ID, ‘fork’
- will fail with ‘EAGAIN’. *Note Creating a Process::.
- ‘RLIMIT_NOFILE’
- ‘RLIMIT_OFILE’
- The maximum number of files that the process can open. If it tries
- to open more files than this, its open attempt fails with ‘errno’
- ‘EMFILE’. *Note Error Codes::. Not all systems support this
- limit; GNU does, and 4.4 BSD does.
- ‘RLIMIT_AS’
- The maximum size of total memory that this process should get. If
- the process tries to allocate more memory beyond this amount with,
- for example, ‘brk’, ‘malloc’, ‘mmap’ or ‘sbrk’, the allocation
- function fails.
- ‘RLIM_NLIMITS’
- The number of different resource limits. Any valid RESOURCE
- operand must be less than ‘RLIM_NLIMITS’.
- -- Constant: rlim_t RLIM_INFINITY
- This constant stands for a value of “infinity” when supplied as the
- limit value in ‘setrlimit’.
- The following are historical functions to do some of what the
- functions above do. The functions above are better choices.
- ‘ulimit’ and the command symbols are declared in ‘ulimit.h’.
- -- Function: long int ulimit (int CMD, …)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- ‘ulimit’ gets the current limit or sets the current and maximum
- limit for a particular resource for the calling process according
- to the command CMD.
- If you are getting a limit, the command argument is the only
- argument. If you are setting a limit, there is a second argument:
- ‘long int’ LIMIT which is the value to which you are setting the
- limit.
- The CMD values and the operations they specify are:
- ‘GETFSIZE’
- Get the current limit on the size of a file, in units of 512
- bytes.
- ‘SETFSIZE’
- Set the current and maximum limit on the size of a file to
- LIMIT * 512 bytes.
- There are also some other CMD values that may do things on some
- systems, but they are not supported.
- Only the superuser may increase a maximum limit.
- When you successfully get a limit, the return value of ‘ulimit’ is
- that limit, which is never negative. When you successfully set a
- limit, the return value is zero. When the function fails, the
- return value is ‘-1’ and ‘errno’ is set according to the reason:
- ‘EPERM’
- A process tried to increase a maximum limit, but is not
- superuser.
- ‘vlimit’ and its resource symbols are declared in ‘sys/vlimit.h’.
- -- Function: int vlimit (int RESOURCE, int LIMIT)
- Preliminary: | MT-Unsafe race:setrlimit | AS-Unsafe | AC-Safe |
- *Note POSIX Safety Concepts::.
- ‘vlimit’ sets the current limit for a resource for a process.
- RESOURCE identifies the resource:
- ‘LIM_CPU’
- Maximum CPU time. Same as ‘RLIMIT_CPU’ for ‘setrlimit’.
- ‘LIM_FSIZE’
- Maximum file size. Same as ‘RLIMIT_FSIZE’ for ‘setrlimit’.
- ‘LIM_DATA’
- Maximum data memory. Same as ‘RLIMIT_DATA’ for ‘setrlimit’.
- ‘LIM_STACK’
- Maximum stack size. Same as ‘RLIMIT_STACK’ for ‘setrlimit’.
- ‘LIM_CORE’
- Maximum core file size. Same as ‘RLIMIT_COR’ for ‘setrlimit’.
- ‘LIM_MAXRSS’
- Maximum physical memory. Same as ‘RLIMIT_RSS’ for
- ‘setrlimit’.
- The return value is zero for success, and ‘-1’ with ‘errno’ set
- accordingly for failure:
- ‘EPERM’
- The process tried to set its current limit beyond its maximum
- limit.
- File: libc.info, Node: Priority, Next: Memory Resources, Prev: Limits on Resources, Up: Resource Usage And Limitation
- 22.3 Process CPU Priority And Scheduling
- ========================================
- When multiple processes simultaneously require CPU time, the system’s
- scheduling policy and process CPU priorities determine which processes
- get it. This section describes how that determination is made and GNU C
- Library functions to control it.
- It is common to refer to CPU scheduling simply as scheduling and a
- process’ CPU priority simply as the process’ priority, with the CPU
- resource being implied. Bear in mind, though, that CPU time is not the
- only resource a process uses or that processes contend for. In some
- cases, it is not even particularly important. Giving a process a high
- “priority” may have very little effect on how fast a process runs with
- respect to other processes. The priorities discussed in this section
- apply only to CPU time.
- CPU scheduling is a complex issue and different systems do it in
- wildly different ways. New ideas continually develop and find their way
- into the intricacies of the various systems’ scheduling algorithms.
- This section discusses the general concepts, some specifics of systems
- that commonly use the GNU C Library, and some standards.
- For simplicity, we talk about CPU contention as if there is only one
- CPU in the system. But all the same principles apply when a processor
- has multiple CPUs, and knowing that the number of processes that can run
- at any one time is equal to the number of CPUs, you can easily
- extrapolate the information.
- The functions described in this section are all defined by the
- POSIX.1 and POSIX.1b standards (the ‘sched…’ functions are POSIX.1b).
- However, POSIX does not define any semantics for the values that these
- functions get and set. In this chapter, the semantics are based on the
- Linux kernel’s implementation of the POSIX standard. As you will see,
- the Linux implementation is quite the inverse of what the authors of the
- POSIX syntax had in mind.
- * Menu:
- * Absolute Priority:: The first tier of priority. Posix
- * Realtime Scheduling:: Scheduling among the process nobility
- * Basic Scheduling Functions:: Get/set scheduling policy, priority
- * Traditional Scheduling:: Scheduling among the vulgar masses
- * CPU Affinity:: Limiting execution to certain CPUs
- File: libc.info, Node: Absolute Priority, Next: Realtime Scheduling, Up: Priority
- 22.3.1 Absolute Priority
- ------------------------
- Every process has an absolute priority, and it is represented by a
- number. The higher the number, the higher the absolute priority.
- On systems of the past, and most systems today, all processes have
- absolute priority 0 and this section is irrelevant. In that case, *Note
- Traditional Scheduling::. Absolute priorities were invented to
- accommodate realtime systems, in which it is vital that certain
- processes be able to respond to external events happening in real time,
- which means they cannot wait around while some other process that _wants
- to_, but doesn’t _need to_ run occupies the CPU.
- When two processes are in contention to use the CPU at any instant,
- the one with the higher absolute priority always gets it. This is true
- even if the process with the lower priority is already using the CPU
- (i.e., the scheduling is preemptive). Of course, we’re only talking
- about processes that are running or “ready to run,” which means they are
- ready to execute instructions right now. When a process blocks to wait
- for something like I/O, its absolute priority is irrelevant.
- *NB:* The term “runnable” is a synonym for “ready to run.”
- When two processes are running or ready to run and both have the same
- absolute priority, it’s more interesting. In that case, who gets the
- CPU is determined by the scheduling policy. If the processes have
- absolute priority 0, the traditional scheduling policy described in
- *note Traditional Scheduling:: applies. Otherwise, the policies
- described in *note Realtime Scheduling:: apply.
- You normally give an absolute priority above 0 only to a process that
- can be trusted not to hog the CPU. Such processes are designed to block
- (or terminate) after relatively short CPU runs.
- A process begins life with the same absolute priority as its parent
- process. Functions described in *note Basic Scheduling Functions:: can
- change it.
- Only a privileged process can change a process’ absolute priority to
- something other than ‘0’. Only a privileged process or the target
- process’ owner can change its absolute priority at all.
- POSIX requires absolute priority values used with the realtime
- scheduling policies to be consecutive with a range of at least 32. On
- Linux, they are 1 through 99. The functions ‘sched_get_priority_max’
- and ‘sched_set_priority_min’ portably tell you what the range is on a
- particular system.
- 22.3.1.1 Using Absolute Priority
- ................................
- One thing you must keep in mind when designing real time applications is
- that having higher absolute priority than any other process doesn’t
- guarantee the process can run continuously. Two things that can wreck a
- good CPU run are interrupts and page faults.
- Interrupt handlers live in that limbo between processes. The CPU is
- executing instructions, but they aren’t part of any process. An
- interrupt will stop even the highest priority process. So you must
- allow for slight delays and make sure that no device in the system has
- an interrupt handler that could cause too long a delay between
- instructions for your process.
- Similarly, a page fault causes what looks like a straightforward
- sequence of instructions to take a long time. The fact that other
- processes get to run while the page faults in is of no consequence,
- because as soon as the I/O is complete, the higher priority process will
- kick them out and run again, but the wait for the I/O itself could be a
- problem. To neutralize this threat, use ‘mlock’ or ‘mlockall’.
- There are a few ramifications of the absoluteness of this priority on
- a single-CPU system that you need to keep in mind when you choose to set
- a priority and also when you’re working on a program that runs with high
- absolute priority. Consider a process that has higher absolute priority
- than any other process in the system and due to a bug in its program, it
- gets into an infinite loop. It will never cede the CPU. You can’t run a
- command to kill it because your command would need to get the CPU in
- order to run. The errant program is in complete control. It controls
- the vertical, it controls the horizontal.
- There are two ways to avoid this: 1) keep a shell running somewhere
- with a higher absolute priority or 2) keep a controlling terminal
- attached to the high priority process group. All the priority in the
- world won’t stop an interrupt handler from running and delivering a
- signal to the process if you hit Control-C.
- Some systems use absolute priority as a means of allocating a fixed
- percentage of CPU time to a process. To do this, a super high priority
- privileged process constantly monitors the process’ CPU usage and raises
- its absolute priority when the process isn’t getting its entitled share
- and lowers it when the process is exceeding it.
- *NB:* The absolute priority is sometimes called the “static
- priority.” We don’t use that term in this manual because it misses the
- most important feature of the absolute priority: its absoluteness.
- File: libc.info, Node: Realtime Scheduling, Next: Basic Scheduling Functions, Prev: Absolute Priority, Up: Priority
- 22.3.2 Realtime Scheduling
- --------------------------
- Whenever two processes with the same absolute priority are ready to run,
- the kernel has a decision to make, because only one can run at a time.
- If the processes have absolute priority 0, the kernel makes this
- decision as described in *note Traditional Scheduling::. Otherwise, the
- decision is as described in this section.
- If two processes are ready to run but have different absolute
- priorities, the decision is much simpler, and is described in *note
- Absolute Priority::.
- Each process has a scheduling policy. For processes with absolute
- priority other than zero, there are two available:
- 1. First Come First Served
- 2. Round Robin
- The most sensible case is where all the processes with a certain
- absolute priority have the same scheduling policy. We’ll discuss that
- first.
- In Round Robin, processes share the CPU, each one running for a small
- quantum of time (“time slice”) and then yielding to another in a
- circular fashion. Of course, only processes that are ready to run and
- have the same absolute priority are in this circle.
- In First Come First Served, the process that has been waiting the
- longest to run gets the CPU, and it keeps it until it voluntarily
- relinquishes the CPU, runs out of things to do (blocks), or gets
- preempted by a higher priority process.
- First Come First Served, along with maximal absolute priority and
- careful control of interrupts and page faults, is the one to use when a
- process absolutely, positively has to run at full CPU speed or not at
- all.
- Judicious use of ‘sched_yield’ function invocations by processes with
- First Come First Served scheduling policy forms a good compromise
- between Round Robin and First Come First Served.
- To understand how scheduling works when processes of different
- scheduling policies occupy the same absolute priority, you have to know
- the nitty gritty details of how processes enter and exit the ready to
- run list.
- In both cases, the ready to run list is organized as a true queue,
- where a process gets pushed onto the tail when it becomes ready to run
- and is popped off the head when the scheduler decides to run it. Note
- that ready to run and running are two mutually exclusive states. When
- the scheduler runs a process, that process is no longer ready to run and
- no longer in the ready to run list. When the process stops running, it
- may go back to being ready to run again.
- The only difference between a process that is assigned the Round
- Robin scheduling policy and a process that is assigned First Come First
- Serve is that in the former case, the process is automatically booted
- off the CPU after a certain amount of time. When that happens, the
- process goes back to being ready to run, which means it enters the queue
- at the tail. The time quantum we’re talking about is small. Really
- small. This is not your father’s timesharing. For example, with the
- Linux kernel, the round robin time slice is a thousand times shorter
- than its typical time slice for traditional scheduling.
- A process begins life with the same scheduling policy as its parent
- process. Functions described in *note Basic Scheduling Functions:: can
- change it.
- Only a privileged process can set the scheduling policy of a process
- that has absolute priority higher than 0.
- File: libc.info, Node: Basic Scheduling Functions, Next: Traditional Scheduling, Prev: Realtime Scheduling, Up: Priority
- 22.3.3 Basic Scheduling Functions
- ---------------------------------
- This section describes functions in the GNU C Library for setting the
- absolute priority and scheduling policy of a process.
- *Portability Note:* On systems that have the functions in this
- section, the macro _POSIX_PRIORITY_SCHEDULING is defined in
- ‘<unistd.h>’.
- For the case that the scheduling policy is traditional scheduling,
- more functions to fine tune the scheduling are in *note Traditional
- Scheduling::.
- Don’t try to make too much out of the naming and structure of these
- functions. They don’t match the concepts described in this manual
- because the functions are as defined by POSIX.1b, but the implementation
- on systems that use the GNU C Library is the inverse of what the POSIX
- structure contemplates. The POSIX scheme assumes that the primary
- scheduling parameter is the scheduling policy and that the priority
- value, if any, is a parameter of the scheduling policy. In the
- implementation, though, the priority value is king and the scheduling
- policy, if anything, only fine tunes the effect of that priority.
- The symbols in this section are declared by including file ‘sched.h’.
- -- Data Type: struct sched_param
- This structure describes an absolute priority.
- ‘int sched_priority’
- absolute priority value
- -- Function: int sched_setscheduler (pid_t PID, int POLICY, const
- struct sched_param *PARAM)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function sets both the absolute priority and the scheduling
- policy for a process.
- It assigns the absolute priority value given by PARAM and the
- scheduling policy POLICY to the process with Process ID PID, or the
- calling process if PID is zero. If POLICY is negative,
- ‘sched_setscheduler’ keeps the existing scheduling policy.
- The following macros represent the valid values for POLICY:
- ‘SCHED_OTHER’
- Traditional Scheduling
- ‘SCHED_FIFO’
- First In First Out
- ‘SCHED_RR’
- Round Robin
- On success, the return value is ‘0’. Otherwise, it is ‘-1’ and
- ‘ERRNO’ is set accordingly. The ‘errno’ values specific to this
- function are:
- ‘EPERM’
- • The calling process does not have ‘CAP_SYS_NICE’
- permission and POLICY is not ‘SCHED_OTHER’ (or it’s
- negative and the existing policy is not ‘SCHED_OTHER’.
- • The calling process does not have ‘CAP_SYS_NICE’
- permission and its owner is not the target process’
- owner. I.e., the effective uid of the calling process is
- neither the effective nor the real uid of process PID.
- ‘ESRCH’
- There is no process with pid PID and PID is not zero.
- ‘EINVAL’
- • POLICY does not identify an existing scheduling policy.
- • The absolute priority value identified by *PARAM is
- outside the valid range for the scheduling policy POLICY
- (or the existing scheduling policy if POLICY is negative)
- or PARAM is null. ‘sched_get_priority_max’ and
- ‘sched_get_priority_min’ tell you what the valid range
- is.
- • PID is negative.
- -- Function: int sched_getscheduler (pid_t PID)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function returns the scheduling policy assigned to the process
- with Process ID (pid) PID, or the calling process if PID is zero.
- The return value is the scheduling policy. See
- ‘sched_setscheduler’ for the possible values.
- If the function fails, the return value is instead ‘-1’ and ‘errno’
- is set accordingly.
- The ‘errno’ values specific to this function are:
- ‘ESRCH’
- There is no process with pid PID and it is not zero.
- ‘EINVAL’
- PID is negative.
- Note that this function is not an exact mate to
- ‘sched_setscheduler’ because while that function sets the
- scheduling policy and the absolute priority, this function gets
- only the scheduling policy. To get the absolute priority, use
- ‘sched_getparam’.
- -- Function: int sched_setparam (pid_t PID, const struct sched_param
- *PARAM)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function sets a process’ absolute priority.
- It is functionally identical to ‘sched_setscheduler’ with POLICY =
- ‘-1’.
- -- Function: int sched_getparam (pid_t PID, struct sched_param *PARAM)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function returns a process’ absolute priority.
- PID is the Process ID (pid) of the process whose absolute priority
- you want to know.
- PARAM is a pointer to a structure in which the function stores the
- absolute priority of the process.
- On success, the return value is ‘0’. Otherwise, it is ‘-1’ and
- ‘errno’ is set accordingly. The ‘errno’ values specific to this
- function are:
- ‘ESRCH’
- There is no process with pid PID and it is not zero.
- ‘EINVAL’
- PID is negative.
- -- Function: int sched_get_priority_min (int POLICY)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function returns the lowest absolute priority value that is
- allowable for a process with scheduling policy POLICY.
- On Linux, it is 0 for SCHED_OTHER and 1 for everything else.
- On success, the return value is ‘0’. Otherwise, it is ‘-1’ and
- ‘ERRNO’ is set accordingly. The ‘errno’ values specific to this
- function are:
- ‘EINVAL’
- POLICY does not identify an existing scheduling policy.
- -- Function: int sched_get_priority_max (int POLICY)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function returns the highest absolute priority value that is
- allowable for a process that with scheduling policy POLICY.
- On Linux, it is 0 for SCHED_OTHER and 99 for everything else.
- On success, the return value is ‘0’. Otherwise, it is ‘-1’ and
- ‘ERRNO’ is set accordingly. The ‘errno’ values specific to this
- function are:
- ‘EINVAL’
- POLICY does not identify an existing scheduling policy.
- -- Function: int sched_rr_get_interval (pid_t PID, struct timespec
- *INTERVAL)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function returns the length of the quantum (time slice) used
- with the Round Robin scheduling policy, if it is used, for the
- process with Process ID PID.
- It returns the length of time as INTERVAL.
- With a Linux kernel, the round robin time slice is always 150
- microseconds, and PID need not even be a real pid.
- The return value is ‘0’ on success and in the pathological case
- that it fails, the return value is ‘-1’ and ‘errno’ is set
- accordingly. There is nothing specific that can go wrong with this
- function, so there are no specific ‘errno’ values.
- -- Function: int sched_yield (void)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function voluntarily gives up the process’ claim on the CPU.
- Technically, ‘sched_yield’ causes the calling process to be made
- immediately ready to run (as opposed to running, which is what it
- was before). This means that if it has absolute priority higher
- than 0, it gets pushed onto the tail of the queue of processes that
- share its absolute priority and are ready to run, and it will run
- again when its turn next arrives. If its absolute priority is 0,
- it is more complicated, but still has the effect of yielding the
- CPU to other processes.
- If there are no other processes that share the calling process’
- absolute priority, this function doesn’t have any effect.
- To the extent that the containing program is oblivious to what
- other processes in the system are doing and how fast it executes,
- this function appears as a no-op.
- The return value is ‘0’ on success and in the pathological case
- that it fails, the return value is ‘-1’ and ‘errno’ is set
- accordingly. There is nothing specific that can go wrong with this
- function, so there are no specific ‘errno’ values.
- File: libc.info, Node: Traditional Scheduling, Next: CPU Affinity, Prev: Basic Scheduling Functions, Up: Priority
- 22.3.4 Traditional Scheduling
- -----------------------------
- This section is about the scheduling among processes whose absolute
- priority is 0. When the system hands out the scraps of CPU time that
- are left over after the processes with higher absolute priority have
- taken all they want, the scheduling described herein determines who
- among the great unwashed processes gets them.
- * Menu:
- * Traditional Scheduling Intro::
- * Traditional Scheduling Functions::
- File: libc.info, Node: Traditional Scheduling Intro, Next: Traditional Scheduling Functions, Up: Traditional Scheduling
- 22.3.4.1 Introduction To Traditional Scheduling
- ...............................................
- Long before there was absolute priority (See *note Absolute Priority::),
- Unix systems were scheduling the CPU using this system. When POSIX came
- in like the Romans and imposed absolute priorities to accommodate the
- needs of realtime processing, it left the indigenous Absolute Priority
- Zero processes to govern themselves by their own familiar scheduling
- policy.
- Indeed, absolute priorities higher than zero are not available on
- many systems today and are not typically used when they are, being
- intended mainly for computers that do realtime processing. So this
- section describes the only scheduling many programmers need to be
- concerned about.
- But just to be clear about the scope of this scheduling: Any time a
- process with an absolute priority of 0 and a process with an absolute
- priority higher than 0 are ready to run at the same time, the one with
- absolute priority 0 does not run. If it’s already running when the
- higher priority ready-to-run process comes into existence, it stops
- immediately.
- In addition to its absolute priority of zero, every process has
- another priority, which we will refer to as "dynamic priority" because
- it changes over time. The dynamic priority is meaningless for processes
- with an absolute priority higher than zero.
- The dynamic priority sometimes determines who gets the next turn on
- the CPU. Sometimes it determines how long turns last. Sometimes it
- determines whether a process can kick another off the CPU.
- In Linux, the value is a combination of these things, but mostly it
- just determines the length of the time slice. The higher a process’
- dynamic priority, the longer a shot it gets on the CPU when it gets one.
- If it doesn’t use up its time slice before giving up the CPU to do
- something like wait for I/O, it is favored for getting the CPU back when
- it’s ready for it, to finish out its time slice. Other than that,
- selection of processes for new time slices is basically round robin.
- But the scheduler does throw a bone to the low priority processes: A
- process’ dynamic priority rises every time it is snubbed in the
- scheduling process. In Linux, even the fat kid gets to play.
- The fluctuation of a process’ dynamic priority is regulated by
- another value: The “nice” value. The nice value is an integer, usually
- in the range -20 to 20, and represents an upper limit on a process’
- dynamic priority. The higher the nice number, the lower that limit.
- On a typical Linux system, for example, a process with a nice value
- of 20 can get only 10 milliseconds on the CPU at a time, whereas a
- process with a nice value of -20 can achieve a high enough priority to
- get 400 milliseconds.
- The idea of the nice value is deferential courtesy. In the
- beginning, in the Unix garden of Eden, all processes shared equally in
- the bounty of the computer system. But not all processes really need
- the same share of CPU time, so the nice value gave a courteous process
- the ability to refuse its equal share of CPU time that others might
- prosper. Hence, the higher a process’ nice value, the nicer the process
- is. (Then a snake came along and offered some process a negative nice
- value and the system became the crass resource allocation system we know
- today.)
- Dynamic priorities tend upward and downward with an objective of
- smoothing out allocation of CPU time and giving quick response time to
- infrequent requests. But they never exceed their nice limits, so on a
- heavily loaded CPU, the nice value effectively determines how fast a
- process runs.
- In keeping with the socialistic heritage of Unix process priority, a
- process begins life with the same nice value as its parent process and
- can raise it at will. A process can also raise the nice value of any
- other process owned by the same user (or effective user). But only a
- privileged process can lower its nice value. A privileged process can
- also raise or lower another process’ nice value.
- GNU C Library functions for getting and setting nice values are
- described in *Note Traditional Scheduling Functions::.
- File: libc.info, Node: Traditional Scheduling Functions, Prev: Traditional Scheduling Intro, Up: Traditional Scheduling
- 22.3.4.2 Functions For Traditional Scheduling
- .............................................
- This section describes how you can read and set the nice value of a
- process. All these symbols are declared in ‘sys/resource.h’.
- The function and macro names are defined by POSIX, and refer to
- "priority," but the functions actually have to do with nice values, as
- the terms are used both in the manual and POSIX.
- The range of valid nice values depends on the kernel, but typically
- it runs from ‘-20’ to ‘20’. A lower nice value corresponds to higher
- priority for the process. These constants describe the range of
- priority values:
- ‘PRIO_MIN’
- The lowest valid nice value.
- ‘PRIO_MAX’
- The highest valid nice value.
- -- Function: int getpriority (int CLASS, int ID)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- Return the nice value of a set of processes; CLASS and ID specify
- which ones (see below). If the processes specified do not all have
- the same nice value, this returns the lowest value that any of them
- has.
- On success, the return value is ‘0’. Otherwise, it is ‘-1’ and
- ‘errno’ is set accordingly. The ‘errno’ values specific to this
- function are:
- ‘ESRCH’
- The combination of CLASS and ID does not match any existing
- process.
- ‘EINVAL’
- The value of CLASS is not valid.
- If the return value is ‘-1’, it could indicate failure, or it could
- be the nice value. The only way to make certain is to set ‘errno =
- 0’ before calling ‘getpriority’, then use ‘errno != 0’ afterward as
- the criterion for failure.
- -- Function: int setpriority (int CLASS, int ID, int NICEVAL)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- Set the nice value of a set of processes to NICEVAL; CLASS and ID
- specify which ones (see below).
- The return value is ‘0’ on success, and ‘-1’ on failure. The
- following ‘errno’ error condition are possible for this function:
- ‘ESRCH’
- The combination of CLASS and ID does not match any existing
- process.
- ‘EINVAL’
- The value of CLASS is not valid.
- ‘EPERM’
- The call would set the nice value of a process which is owned
- by a different user than the calling process (i.e., the target
- process’ real or effective uid does not match the calling
- process’ effective uid) and the calling process does not have
- ‘CAP_SYS_NICE’ permission.
- ‘EACCES’
- The call would lower the process’ nice value and the process
- does not have ‘CAP_SYS_NICE’ permission.
- The arguments CLASS and ID together specify a set of processes in
- which you are interested. These are the possible values of CLASS:
- ‘PRIO_PROCESS’
- One particular process. The argument ID is a process ID (pid).
- ‘PRIO_PGRP’
- All the processes in a particular process group. The argument ID
- is a process group ID (pgid).
- ‘PRIO_USER’
- All the processes owned by a particular user (i.e., whose real uid
- indicates the user). The argument ID is a user ID (uid).
- If the argument ID is 0, it stands for the calling process, its
- process group, or its owner (real uid), according to CLASS.
- -- Function: int nice (int INCREMENT)
- Preliminary: | MT-Unsafe race:setpriority | AS-Unsafe | AC-Safe |
- *Note POSIX Safety Concepts::.
- Increment the nice value of the calling process by INCREMENT. The
- return value is the new nice value on success, and ‘-1’ on failure.
- In the case of failure, ‘errno’ will be set to the same values as
- for ‘setpriority’.
- Here is an equivalent definition of ‘nice’:
- int
- nice (int increment)
- {
- int result, old = getpriority (PRIO_PROCESS, 0);
- result = setpriority (PRIO_PROCESS, 0, old + increment);
- if (result != -1)
- return old + increment;
- else
- return -1;
- }
- File: libc.info, Node: CPU Affinity, Prev: Traditional Scheduling, Up: Priority
- 22.3.5 Limiting execution to certain CPUs
- -----------------------------------------
- On a multi-processor system the operating system usually distributes the
- different processes which are runnable on all available CPUs in a way
- which allows the system to work most efficiently. Which processes and
- threads run can be to some extend be control with the scheduling
- functionality described in the last sections. But which CPU finally
- executes which process or thread is not covered.
- There are a number of reasons why a program might want to have
- control over this aspect of the system as well:
- • One thread or process is responsible for absolutely critical work
- which under no circumstances must be interrupted or hindered from
- making progress by other processes or threads using CPU resources.
- In this case the special process would be confined to a CPU which
- no other process or thread is allowed to use.
- • The access to certain resources (RAM, I/O ports) has different
- costs from different CPUs. This is the case in NUMA (Non-Uniform
- Memory Architecture) machines. Preferably memory should be
- accessed locally but this requirement is usually not visible to the
- scheduler. Therefore forcing a process or thread to the CPUs which
- have local access to the most-used memory helps to significantly
- boost the performance.
- • In controlled runtimes resource allocation and book-keeping work
- (for instance garbage collection) is performance local to
- processors. This can help to reduce locking costs if the resources
- do not have to be protected from concurrent accesses from different
- processors.
- The POSIX standard up to this date is of not much help to solve this
- problem. The Linux kernel provides a set of interfaces to allow
- specifying _affinity sets_ for a process. The scheduler will schedule
- the thread or process on CPUs specified by the affinity masks. The
- interfaces which the GNU C Library define follow to some extent the
- Linux kernel interface.
- -- Data Type: cpu_set_t
- This data set is a bitset where each bit represents a CPU. How the
- system’s CPUs are mapped to bits in the bitset is system dependent.
- The data type has a fixed size; in the unlikely case that the
- number of bits are not sufficient to describe the CPUs of the
- system a different interface has to be used.
- This type is a GNU extension and is defined in ‘sched.h’.
- To manipulate the bitset, to set and reset bits, a number of macros
- are defined. Some of the macros take a CPU number as a parameter. Here
- it is important to never exceed the size of the bitset. The following
- macro specifies the number of bits in the ‘cpu_set_t’ bitset.
- -- Macro: int CPU_SETSIZE
- The value of this macro is the maximum number of CPUs which can be
- handled with a ‘cpu_set_t’ object.
- The type ‘cpu_set_t’ should be considered opaque; all manipulation
- should happen via the next four macros.
- -- Macro: void CPU_ZERO (cpu_set_t *SET)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This macro initializes the CPU set SET to be the empty set.
- This macro is a GNU extension and is defined in ‘sched.h’.
- -- Macro: void CPU_SET (int CPU, cpu_set_t *SET)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This macro adds CPU to the CPU set SET.
- The CPU parameter must not have side effects since it is evaluated
- more than once.
- This macro is a GNU extension and is defined in ‘sched.h’.
- -- Macro: void CPU_CLR (int CPU, cpu_set_t *SET)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This macro removes CPU from the CPU set SET.
- The CPU parameter must not have side effects since it is evaluated
- more than once.
- This macro is a GNU extension and is defined in ‘sched.h’.
- -- Macro: int CPU_ISSET (int CPU, const cpu_set_t *SET)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This macro returns a nonzero value (true) if CPU is a member of the
- CPU set SET, and zero (false) otherwise.
- The CPU parameter must not have side effects since it is evaluated
- more than once.
- This macro is a GNU extension and is defined in ‘sched.h’.
- CPU bitsets can be constructed from scratch or the currently
- installed affinity mask can be retrieved from the system.
- -- Function: int sched_getaffinity (pid_t PID, size_t CPUSETSIZE,
- cpu_set_t *CPUSET)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function stores the CPU affinity mask for the process or
- thread with the ID PID in the CPUSETSIZE bytes long bitmap pointed
- to by CPUSET. If successful, the function always initializes all
- bits in the ‘cpu_set_t’ object and returns zero.
- If PID does not correspond to a process or thread on the system the
- or the function fails for some other reason, it returns ‘-1’ and
- ‘errno’ is set to represent the error condition.
- ‘ESRCH’
- No process or thread with the given ID found.
- ‘EFAULT’
- The pointer CPUSET does not point to a valid object.
- This function is a GNU extension and is declared in ‘sched.h’.
- Note that it is not portably possible to use this information to
- retrieve the information for different POSIX threads. A separate
- interface must be provided for that.
- -- Function: int sched_setaffinity (pid_t PID, size_t CPUSETSIZE, const
- cpu_set_t *CPUSET)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- This function installs the CPUSETSIZE bytes long affinity mask
- pointed to by CPUSET for the process or thread with the ID PID. If
- successful the function returns zero and the scheduler will in the
- future take the affinity information into account.
- If the function fails it will return ‘-1’ and ‘errno’ is set to the
- error code:
- ‘ESRCH’
- No process or thread with the given ID found.
- ‘EFAULT’
- The pointer CPUSET does not point to a valid object.
- ‘EINVAL’
- The bitset is not valid. This might mean that the affinity
- set might not leave a processor for the process or thread to
- run on.
- This function is a GNU extension and is declared in ‘sched.h’.
- File: libc.info, Node: Memory Resources, Next: Processor Resources, Prev: Priority, Up: Resource Usage And Limitation
- 22.4 Querying memory available resources
- ========================================
- The amount of memory available in the system and the way it is organized
- determines oftentimes the way programs can and have to work. For
- functions like ‘mmap’ it is necessary to know about the size of
- individual memory pages and knowing how much memory is available enables
- a program to select appropriate sizes for, say, caches. Before we get
- into these details a few words about memory subsystems in traditional
- Unix systems will be given.
- * Menu:
- * Memory Subsystem:: Overview about traditional Unix memory handling.
- * Query Memory Parameters:: How to get information about the memory
- subsystem?
- File: libc.info, Node: Memory Subsystem, Next: Query Memory Parameters, Up: Memory Resources
- 22.4.1 Overview about traditional Unix memory handling
- ------------------------------------------------------
- Unix systems normally provide processes virtual address spaces. This
- means that the addresses of the memory regions do not have to correspond
- directly to the addresses of the actual physical memory which stores the
- data. An extra level of indirection is introduced which translates
- virtual addresses into physical addresses. This is normally done by the
- hardware of the processor.
- Using a virtual address space has several advantages. The most
- important is process isolation. The different processes running on the
- system cannot interfere directly with each other. No process can write
- into the address space of another process (except when shared memory is
- used but then it is wanted and controlled).
- Another advantage of virtual memory is that the address space the
- processes see can actually be larger than the physical memory available.
- The physical memory can be extended by storage on an external media
- where the content of currently unused memory regions is stored. The
- address translation can then intercept accesses to these memory regions
- and make memory content available again by loading the data back into
- memory. This concept makes it necessary that programs which have to use
- lots of memory know the difference between available virtual address
- space and available physical memory. If the working set of virtual
- memory of all the processes is larger than the available physical memory
- the system will slow down dramatically due to constant swapping of
- memory content from the memory to the storage media and back. This is
- called “thrashing”.
- A final aspect of virtual memory which is important and follows from
- what is said in the last paragraph is the granularity of the virtual
- address space handling. When we said that the virtual address handling
- stores memory content externally it cannot do this on a byte-by-byte
- basis. The administrative overhead does not allow this (leaving alone
- the processor hardware). Instead several thousand bytes are handled
- together and form a "page". The size of each page is always a power of
- two bytes. The smallest page size in use today is 4096, with 8192,
- 16384, and 65536 being other popular sizes.
- File: libc.info, Node: Query Memory Parameters, Prev: Memory Subsystem, Up: Memory Resources
- 22.4.2 How to get information about the memory subsystem?
- ---------------------------------------------------------
- The page size of the virtual memory the process sees is essential to
- know in several situations. Some programming interfaces (e.g., ‘mmap’,
- *note Memory-mapped I/O::) require the user to provide information
- adjusted to the page size. In the case of ‘mmap’ it is necessary to
- provide a length argument which is a multiple of the page size. Another
- place where the knowledge about the page size is useful is in memory
- allocation. If one allocates pieces of memory in larger chunks which
- are then subdivided by the application code it is useful to adjust the
- size of the larger blocks to the page size. If the total memory
- requirement for the block is close (but not larger) to a multiple of the
- page size the kernel’s memory handling can work more effectively since
- it only has to allocate memory pages which are fully used. (To do this
- optimization it is necessary to know a bit about the memory allocator
- which will require a bit of memory itself for each block and this
- overhead must not push the total size over the page size multiple.)
- The page size traditionally was a compile time constant. But recent
- development of processors changed this. Processors now support
- different page sizes and they can possibly even vary among different
- processes on the same system. Therefore the system should be queried at
- runtime about the current page size and no assumptions (except about it
- being a power of two) should be made.
- The correct interface to query about the page size is ‘sysconf’
- (*note Sysconf Definition::) with the parameter ‘_SC_PAGESIZE’. There
- is a much older interface available, too.
- -- Function: int getpagesize (void)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘getpagesize’ function returns the page size of the process.
- This value is fixed for the runtime of the process but can vary in
- different runs of the application.
- The function is declared in ‘unistd.h’.
- Widely available on System V derived systems is a method to get
- information about the physical memory the system has. The call
- sysconf (_SC_PHYS_PAGES)
- returns the total number of pages of physical memory the system has.
- This does not mean all this memory is available. This information can
- be found using
- sysconf (_SC_AVPHYS_PAGES)
- These two values help to optimize applications. The value returned
- for ‘_SC_AVPHYS_PAGES’ is the amount of memory the application can use
- without hindering any other process (given that no other process
- increases its memory usage). The value returned for ‘_SC_PHYS_PAGES’ is
- more or less a hard limit for the working set. If all applications
- together constantly use more than that amount of memory the system is in
- trouble.
- The GNU C Library provides in addition to these already described way
- to get this information two functions. They are declared in the file
- ‘sys/sysinfo.h’. Programmers should prefer to use the ‘sysconf’ method
- described above.
- -- Function: long int get_phys_pages (void)
- Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock fd
- mem | *Note POSIX Safety Concepts::.
- The ‘get_phys_pages’ function returns the total number of pages of
- physical memory the system has. To get the amount of memory this
- number has to be multiplied by the page size.
- This function is a GNU extension.
- -- Function: long int get_avphys_pages (void)
- Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock fd
- mem | *Note POSIX Safety Concepts::.
- The ‘get_avphys_pages’ function returns the number of available
- pages of physical memory the system has. To get the amount of
- memory this number has to be multiplied by the page size.
- This function is a GNU extension.
- File: libc.info, Node: Processor Resources, Prev: Memory Resources, Up: Resource Usage And Limitation
- 22.5 Learn about the processors available
- =========================================
- The use of threads or processes with shared memory allows an application
- to take advantage of all the processing power a system can provide. If
- the task can be parallelized the optimal way to write an application is
- to have at any time as many processes running as there are processors.
- To determine the number of processors available to the system one can
- run
- sysconf (_SC_NPROCESSORS_CONF)
- which returns the number of processors the operating system configured.
- But it might be possible for the operating system to disable individual
- processors and so the call
- sysconf (_SC_NPROCESSORS_ONLN)
- returns the number of processors which are currently online (i.e.,
- available).
- For these two pieces of information the GNU C Library also provides
- functions to get the information directly. The functions are declared
- in ‘sys/sysinfo.h’.
- -- Function: int get_nprocs_conf (void)
- Preliminary: | MT-Safe | AS-Unsafe heap lock | AC-Unsafe lock fd
- mem | *Note POSIX Safety Concepts::.
- The ‘get_nprocs_conf’ function returns the number of processors the
- operating system configured.
- This function is a GNU extension.
- -- Function: int get_nprocs (void)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
- Concepts::.
- The ‘get_nprocs’ function returns the number of available
- processors.
- This function is a GNU extension.
- Before starting more threads it should be checked whether the
- processors are not already overused. Unix systems calculate something
- called the "load average". This is a number indicating how many
- processes were running. This number is an average over different
- periods of time (normally 1, 5, and 15 minutes).
- -- Function: int getloadavg (double LOADAVG[], int NELEM)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe fd | *Note POSIX Safety
- Concepts::.
- This function gets the 1, 5 and 15 minute load averages of the
- system. The values are placed in LOADAVG. ‘getloadavg’ will place
- at most NELEM elements into the array but never more than three
- elements. The return value is the number of elements written to
- LOADAVG, or -1 on error.
- This function is declared in ‘stdlib.h’.
- File: libc.info, Node: Non-Local Exits, Next: Signal Handling, Prev: Resource Usage And Limitation, Up: Top
- 23 Non-Local Exits
- ******************
- Sometimes when your program detects an unusual situation inside a deeply
- nested set of function calls, you would like to be able to immediately
- return to an outer level of control. This section describes how you can
- do such "non-local exits" using the ‘setjmp’ and ‘longjmp’ functions.
- * Menu:
- * Intro: Non-Local Intro. When and how to use these facilities.
- * Details: Non-Local Details. Functions for non-local exits.
- * Non-Local Exits and Signals:: Portability issues.
- * System V contexts:: Complete context control a la System V.
- File: libc.info, Node: Non-Local Intro, Next: Non-Local Details, Up: Non-Local Exits
- 23.1 Introduction to Non-Local Exits
- ====================================
- As an example of a situation where a non-local exit can be useful,
- suppose you have an interactive program that has a “main loop” that
- prompts for and executes commands. Suppose the “read” command reads
- input from a file, doing some lexical analysis and parsing of the input
- while processing it. If a low-level input error is detected, it would
- be useful to be able to return immediately to the “main loop” instead of
- having to make each of the lexical analysis, parsing, and processing
- phases all have to explicitly deal with error situations initially
- detected by nested calls.
- (On the other hand, if each of these phases has to do a substantial
- amount of cleanup when it exits—such as closing files, deallocating
- buffers or other data structures, and the like—then it can be more
- appropriate to do a normal return and have each phase do its own
- cleanup, because a non-local exit would bypass the intervening phases
- and their associated cleanup code entirely. Alternatively, you could
- use a non-local exit but do the cleanup explicitly either before or
- after returning to the “main loop”.)
- In some ways, a non-local exit is similar to using the ‘return’
- statement to return from a function. But while ‘return’ abandons only a
- single function call, transferring control back to the point at which it
- was called, a non-local exit can potentially abandon many levels of
- nested function calls.
- You identify return points for non-local exits by calling the
- function ‘setjmp’. This function saves information about the execution
- environment in which the call to ‘setjmp’ appears in an object of type
- ‘jmp_buf’. Execution of the program continues normally after the call
- to ‘setjmp’, but if an exit is later made to this return point by
- calling ‘longjmp’ with the corresponding ‘jmp_buf’ object, control is
- transferred back to the point where ‘setjmp’ was called. The return
- value from ‘setjmp’ is used to distinguish between an ordinary return
- and a return made by a call to ‘longjmp’, so calls to ‘setjmp’ usually
- appear in an ‘if’ statement.
- Here is how the example program described above might be set up:
- #include <setjmp.h>
- #include <stdlib.h>
- #include <stdio.h>
- jmp_buf main_loop;
- void
- abort_to_main_loop (int status)
- {
- longjmp (main_loop, status);
- }
- int
- main (void)
- {
- while (1)
- if (setjmp (main_loop))
- puts ("Back at main loop....");
- else
- do_command ();
- }
- void
- do_command (void)
- {
- char buffer[128];
- if (fgets (buffer, 128, stdin) == NULL)
- abort_to_main_loop (-1);
- else
- exit (EXIT_SUCCESS);
- }
- The function ‘abort_to_main_loop’ causes an immediate transfer of
- control back to the main loop of the program, no matter where it is
- called from.
- The flow of control inside the ‘main’ function may appear a little
- mysterious at first, but it is actually a common idiom with ‘setjmp’. A
- normal call to ‘setjmp’ returns zero, so the “else” clause of the
- conditional is executed. If ‘abort_to_main_loop’ is called somewhere
- within the execution of ‘do_command’, then it actually appears as if the
- _same_ call to ‘setjmp’ in ‘main’ were returning a second time with a
- value of ‘-1’.
- So, the general pattern for using ‘setjmp’ looks something like:
- if (setjmp (BUFFER))
- /* Code to clean up after premature return. */
- …
- else
- /* Code to be executed normally after setting up the return point. */
- …
- File: libc.info, Node: Non-Local Details, Next: Non-Local Exits and Signals, Prev: Non-Local Intro, Up: Non-Local Exits
- 23.2 Details of Non-Local Exits
- ===============================
- Here are the details on the functions and data structures used for
- performing non-local exits. These facilities are declared in
- ‘setjmp.h’.
- -- Data Type: jmp_buf
- Objects of type ‘jmp_buf’ hold the state information to be restored
- by a non-local exit. The contents of a ‘jmp_buf’ identify a
- specific place to return to.
- -- Macro: int setjmp (jmp_buf STATE)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- When called normally, ‘setjmp’ stores information about the
- execution state of the program in STATE and returns zero. If
- ‘longjmp’ is later used to perform a non-local exit to this STATE,
- ‘setjmp’ returns a nonzero value.
- -- Function: void longjmp (jmp_buf STATE, int VALUE)
- Preliminary: | MT-Safe | AS-Unsafe plugin corrupt lock/hurd |
- AC-Unsafe corrupt lock/hurd | *Note POSIX Safety Concepts::.
- This function restores current execution to the state saved in
- STATE, and continues execution from the call to ‘setjmp’ that
- established that return point. Returning from ‘setjmp’ by means of
- ‘longjmp’ returns the VALUE argument that was passed to ‘longjmp’,
- rather than ‘0’. (But if VALUE is given as ‘0’, ‘setjmp’ returns
- ‘1’).
- There are a lot of obscure but important restrictions on the use of
- ‘setjmp’ and ‘longjmp’. Most of these restrictions are present because
- non-local exits require a fair amount of magic on the part of the C
- compiler and can interact with other parts of the language in strange
- ways.
- The ‘setjmp’ function is actually a macro without an actual function
- definition, so you shouldn’t try to ‘#undef’ it or take its address. In
- addition, calls to ‘setjmp’ are safe in only the following contexts:
- • As the test expression of a selection or iteration statement (such
- as ‘if’, ‘switch’, or ‘while’).
- • As one operand of an equality or comparison operator that appears
- as the test expression of a selection or iteration statement. The
- other operand must be an integer constant expression.
- • As the operand of a unary ‘!’ operator, that appears as the test
- expression of a selection or iteration statement.
- • By itself as an expression statement.
- Return points are valid only during the dynamic extent of the
- function that called ‘setjmp’ to establish them. If you ‘longjmp’ to a
- return point that was established in a function that has already
- returned, unpredictable and disastrous things are likely to happen.
- You should use a nonzero VALUE argument to ‘longjmp’. While
- ‘longjmp’ refuses to pass back a zero argument as the return value from
- ‘setjmp’, this is intended as a safety net against accidental misuse and
- is not really good programming style.
- When you perform a non-local exit, accessible objects generally
- retain whatever values they had at the time ‘longjmp’ was called. The
- exception is that the values of automatic variables local to the
- function containing the ‘setjmp’ call that have been changed since the
- call to ‘setjmp’ are indeterminate, unless you have declared them
- ‘volatile’.
- File: libc.info, Node: Non-Local Exits and Signals, Next: System V contexts, Prev: Non-Local Details, Up: Non-Local Exits
- 23.3 Non-Local Exits and Signals
- ================================
- In BSD Unix systems, ‘setjmp’ and ‘longjmp’ also save and restore the
- set of blocked signals; see *note Blocking Signals::. However, the
- POSIX.1 standard requires ‘setjmp’ and ‘longjmp’ not to change the set
- of blocked signals, and provides an additional pair of functions
- (‘sigsetjmp’ and ‘siglongjmp’) to get the BSD behavior.
- The behavior of ‘setjmp’ and ‘longjmp’ in the GNU C Library is
- controlled by feature test macros; see *note Feature Test Macros::. The
- default in the GNU C Library is the POSIX.1 behavior rather than the BSD
- behavior.
- The facilities in this section are declared in the header file
- ‘setjmp.h’.
- -- Data Type: sigjmp_buf
- This is similar to ‘jmp_buf’, except that it can also store state
- information about the set of blocked signals.
- -- Function: int sigsetjmp (sigjmp_buf STATE, int SAVESIGS)
- Preliminary: | MT-Safe | AS-Unsafe lock/hurd | AC-Unsafe lock/hurd
- | *Note POSIX Safety Concepts::.
- This is similar to ‘setjmp’. If SAVESIGS is nonzero, the set of
- blocked signals is saved in STATE and will be restored if a
- ‘siglongjmp’ is later performed with this STATE.
- -- Function: void siglongjmp (sigjmp_buf STATE, int VALUE)
- Preliminary: | MT-Safe | AS-Unsafe plugin corrupt lock/hurd |
- AC-Unsafe corrupt lock/hurd | *Note POSIX Safety Concepts::.
- This is similar to ‘longjmp’ except for the type of its STATE
- argument. If the ‘sigsetjmp’ call that set this STATE used a
- nonzero SAVESIGS flag, ‘siglongjmp’ also restores the set of
- blocked signals.
- File: libc.info, Node: System V contexts, Prev: Non-Local Exits and Signals, Up: Non-Local Exits
- 23.4 Complete Context Control
- =============================
- The Unix standard provides one more set of functions to control the
- execution path and these functions are more powerful than those
- discussed in this chapter so far. These functions were part of the
- original System V API and by this route were added to the Unix API.
- Besides on branded Unix implementations these interfaces are not widely
- available. Not all platforms and/or architectures the GNU C Library is
- available on provide this interface. Use ‘configure’ to detect the
- availability.
- Similar to the ‘jmp_buf’ and ‘sigjmp_buf’ types used for the
- variables to contain the state of the ‘longjmp’ functions the interfaces
- of interest here have an appropriate type as well. Objects of this type
- are normally much larger since more information is contained. The type
- is also used in a few more places as we will see. The types and
- functions described in this section are all defined and declared
- respectively in the ‘ucontext.h’ header file.
- -- Data Type: ucontext_t
- The ‘ucontext_t’ type is defined as a structure with at least the
- following elements:
- ‘ucontext_t *uc_link’
- This is a pointer to the next context structure which is used
- if the context described in the current structure returns.
- ‘sigset_t uc_sigmask’
- Set of signals which are blocked when this context is used.
- ‘stack_t uc_stack’
- Stack used for this context. The value need not be (and
- normally is not) the stack pointer. *Note Signal Stack::.
- ‘mcontext_t uc_mcontext’
- This element contains the actual state of the process. The
- ‘mcontext_t’ type is also defined in this header but the
- definition should be treated as opaque. Any use of knowledge
- of the type makes applications less portable.
- Objects of this type have to be created by the user. The
- initialization and modification happens through one of the following
- functions:
- -- Function: int getcontext (ucontext_t *UCP)
- Preliminary: | MT-Safe race:ucp | AS-Safe | AC-Safe | *Note POSIX
- Safety Concepts::.
- The ‘getcontext’ function initializes the variable pointed to by
- UCP with the context of the calling thread. The context contains
- the content of the registers, the signal mask, and the current
- stack. Executing the contents would start at the point where the
- ‘getcontext’ call just returned.
- The function returns ‘0’ if successful. Otherwise it returns ‘-1’
- and sets ERRNO accordingly.
- The ‘getcontext’ function is similar to ‘setjmp’ but it does not
- provide an indication of whether ‘getcontext’ is returning for the first
- time or whether an initialized context has just been restored. If this
- is necessary the user has to determine this herself. This must be done
- carefully since the context contains registers which might contain
- register variables. This is a good situation to define variables with
- ‘volatile’.
- Once the context variable is initialized it can be used as is or it
- can be modified using the ‘makecontext’ function. The latter is
- normally done when implementing co-routines or similar constructs.
- -- Function: void makecontext (ucontext_t *UCP, void (*FUNC) (void),
- int ARGC, …)
- Preliminary: | MT-Safe race:ucp | AS-Safe | AC-Safe | *Note POSIX
- Safety Concepts::.
- The UCP parameter passed to ‘makecontext’ shall be initialized by a
- call to ‘getcontext’. The context will be modified in a way such
- that if the context is resumed it will start by calling the
- function ‘func’ which gets ARGC integer arguments passed. The
- integer arguments which are to be passed should follow the ARGC
- parameter in the call to ‘makecontext’.
- Before the call to this function the ‘uc_stack’ and ‘uc_link’
- element of the UCP structure should be initialized. The ‘uc_stack’
- element describes the stack which is used for this context. No two
- contexts which are used at the same time should use the same memory
- region for a stack.
- The ‘uc_link’ element of the object pointed to by UCP should be a
- pointer to the context to be executed when the function FUNC
- returns or it should be a null pointer. See ‘setcontext’ for more
- information about the exact use.
- While allocating the memory for the stack one has to be careful.
- Most modern processors keep track of whether a certain memory region is
- allowed to contain code which is executed or not. Data segments and
- heap memory are normally not tagged to allow this. The result is that
- programs would fail. Examples for such code include the calling
- sequences the GNU C compiler generates for calls to nested functions.
- Safe ways to allocate stacks correctly include using memory on the
- original thread’s stack or explicitly allocating memory tagged for
- execution using (*note Memory-mapped I/O::).
- *Compatibility note*: The current Unix standard is very imprecise
- about the way the stack is allocated. All implementations seem to agree
- that the ‘uc_stack’ element must be used but the values stored in the
- elements of the ‘stack_t’ value are unclear. The GNU C Library and most
- other Unix implementations require the ‘ss_sp’ value of the ‘uc_stack’
- element to point to the base of the memory region allocated for the
- stack and the size of the memory region is stored in ‘ss_size’. There
- are implementations out there which require ‘ss_sp’ to be set to the
- value the stack pointer will have (which can, depending on the direction
- the stack grows, be different). This difference makes the ‘makecontext’
- function hard to use and it requires detection of the platform at
- compile time.
- -- Function: int setcontext (const ucontext_t *UCP)
- Preliminary: | MT-Safe race:ucp | AS-Unsafe corrupt | AC-Unsafe
- corrupt | *Note POSIX Safety Concepts::.
- The ‘setcontext’ function restores the context described by UCP.
- The context is not modified and can be reused as often as wanted.
- If the context was created by ‘getcontext’ execution resumes with
- the registers filled with the same values and the same stack as if
- the ‘getcontext’ call just returned.
- If the context was modified with a call to ‘makecontext’ execution
- continues with the function passed to ‘makecontext’ which gets the
- specified parameters passed. If this function returns execution is
- resumed in the context which was referenced by the ‘uc_link’
- element of the context structure passed to ‘makecontext’ at the
- time of the call. If ‘uc_link’ was a null pointer the application
- terminates normally with an exit status value of ‘EXIT_SUCCESS’
- (*note Program Termination::).
- If the context was created by a call to a signal handler or from
- any other source then the behaviour of ‘setcontext’ is unspecified.
- Since the context contains information about the stack no two
- threads should use the same context at the same time. The result
- in most cases would be disastrous.
- The ‘setcontext’ function does not return unless an error occurred
- in which case it returns ‘-1’.
- The ‘setcontext’ function simply replaces the current context with
- the one described by the UCP parameter. This is often useful but there
- are situations where the current context has to be preserved.
- -- Function: int swapcontext (ucontext_t *restrict OUCP, const
- ucontext_t *restrict UCP)
- Preliminary: | MT-Safe race:oucp race:ucp | AS-Unsafe corrupt |
- AC-Unsafe corrupt | *Note POSIX Safety Concepts::.
- The ‘swapcontext’ function is similar to ‘setcontext’ but instead
- of just replacing the current context the latter is first saved in
- the object pointed to by OUCP as if this was a call to
- ‘getcontext’. The saved context would resume after the call to
- ‘swapcontext’.
- Once the current context is saved the context described in UCP is
- installed and execution continues as described in this context.
- If ‘swapcontext’ succeeds the function does not return unless the
- context OUCP is used without prior modification by ‘makecontext’.
- The return value in this case is ‘0’. If the function fails it
- returns ‘-1’ and sets ERRNO accordingly.
- Example for SVID Context Handling
- =================================
- The easiest way to use the context handling functions is as a
- replacement for ‘setjmp’ and ‘longjmp’. The context contains on most
- platforms more information which may lead to fewer surprises but this
- also means using these functions is more expensive (besides being less
- portable).
- int
- random_search (int n, int (*fp) (int, ucontext_t *))
- {
- volatile int cnt = 0;
- ucontext_t uc;
- /* Safe current context. */
- if (getcontext (&uc) < 0)
- return -1;
- /* If we have not tried N times try again. */
- if (cnt++ < n)
- /* Call the function with a new random number
- and the context. */
- if (fp (rand (), &uc) != 0)
- /* We found what we were looking for. */
- return 1;
- /* Not found. */
- return 0;
- }
- Using contexts in such a way enables emulating exception handling.
- The search functions passed in the FP parameter could be very large,
- nested, and complex which would make it complicated (or at least would
- require a lot of code) to leave the function with an error value which
- has to be passed down to the caller. By using the context it is
- possible to leave the search function in one step and allow restarting
- the search which also has the nice side effect that it can be
- significantly faster.
- Something which is harder to implement with ‘setjmp’ and ‘longjmp’ is
- to switch temporarily to a different execution path and then resume
- where execution was stopped.
- #include <signal.h>
- #include <stdio.h>
- #include <stdlib.h>
- #include <ucontext.h>
- #include <sys/time.h>
- /* Set by the signal handler. */
- static volatile int expired;
- /* The contexts. */
- static ucontext_t uc[3];
- /* We do only a certain number of switches. */
- static int switches;
- /* This is the function doing the work. It is just a
- skeleton, real code has to be filled in. */
- static void
- f (int n)
- {
- int m = 0;
- while (1)
- {
- /* This is where the work would be done. */
- if (++m % 100 == 0)
- {
- putchar ('.');
- fflush (stdout);
- }
- /* Regularly the EXPIRE variable must be checked. */
- if (expired)
- {
- /* We do not want the program to run forever. */
- if (++switches == 20)
- return;
- printf ("\nswitching from %d to %d\n", n, 3 - n);
- expired = 0;
- /* Switch to the other context, saving the current one. */
- swapcontext (&uc[n], &uc[3 - n]);
- }
- }
- }
- /* This is the signal handler which simply set the variable. */
- void
- handler (int signal)
- {
- expired = 1;
- }
- int
- main (void)
- {
- struct sigaction sa;
- struct itimerval it;
- char st1[8192];
- char st2[8192];
- /* Initialize the data structures for the interval timer. */
- sa.sa_flags = SA_RESTART;
- sigfillset (&sa.sa_mask);
- sa.sa_handler = handler;
- it.it_interval.tv_sec = 0;
- it.it_interval.tv_usec = 1;
- it.it_value = it.it_interval;
- /* Install the timer and get the context we can manipulate. */
- if (sigaction (SIGPROF, &sa, NULL) < 0
- || setitimer (ITIMER_PROF, &it, NULL) < 0
- || getcontext (&uc[1]) == -1
- || getcontext (&uc[2]) == -1)
- abort ();
- /* Create a context with a separate stack which causes the
- function ‘f’ to be call with the parameter ‘1’.
- Note that the ‘uc_link’ points to the main context
- which will cause the program to terminate once the function
- return. */
- uc[1].uc_link = &uc[0];
- uc[1].uc_stack.ss_sp = st1;
- uc[1].uc_stack.ss_size = sizeof st1;
- makecontext (&uc[1], (void (*) (void)) f, 1, 1);
- /* Similarly, but ‘2’ is passed as the parameter to ‘f’. */
- uc[2].uc_link = &uc[0];
- uc[2].uc_stack.ss_sp = st2;
- uc[2].uc_stack.ss_size = sizeof st2;
- makecontext (&uc[2], (void (*) (void)) f, 1, 2);
- /* Start running. */
- swapcontext (&uc[0], &uc[1]);
- putchar ('\n');
- return 0;
- }
- This an example how the context functions can be used to implement
- co-routines or cooperative multi-threading. All that has to be done is
- to call every once in a while ‘swapcontext’ to continue running a
- different context. It is not recommended to do the context switching
- from the signal handler directly since leaving the signal handler via
- ‘setcontext’ if the signal was delivered during code that was not
- asynchronous signal safe could lead to problems. Setting a variable in
- the signal handler and checking it in the body of the functions which
- are executed is a safer approach. Since ‘swapcontext’ is saving the
- current context it is possible to have multiple different scheduling
- points in the code. Execution will always resume where it was left.
- File: libc.info, Node: Signal Handling, Next: Program Basics, Prev: Non-Local Exits, Up: Top
- 24 Signal Handling
- ******************
- A "signal" is a software interrupt delivered to a process. The
- operating system uses signals to report exceptional situations to an
- executing program. Some signals report errors such as references to
- invalid memory addresses; others report asynchronous events, such as
- disconnection of a phone line.
- The GNU C Library defines a variety of signal types, each for a
- particular kind of event. Some kinds of events make it inadvisable or
- impossible for the program to proceed as usual, and the corresponding
- signals normally abort the program. Other kinds of signals that report
- harmless events are ignored by default.
- If you anticipate an event that causes signals, you can define a
- handler function and tell the operating system to run it when that
- particular type of signal arrives.
- Finally, one process can send a signal to another process; this
- allows a parent process to abort a child, or two related processes to
- communicate and synchronize.
- * Menu:
- * Concepts of Signals:: Introduction to the signal facilities.
- * Standard Signals:: Particular kinds of signals with
- standard names and meanings.
- * Signal Actions:: Specifying what happens when a
- particular signal is delivered.
- * Defining Handlers:: How to write a signal handler function.
- * Interrupted Primitives:: Signal handlers affect use of ‘open’,
- ‘read’, ‘write’ and other functions.
- * Generating Signals:: How to send a signal to a process.
- * Blocking Signals:: Making the system hold signals temporarily.
- * Waiting for a Signal:: Suspending your program until a signal
- arrives.
- * Signal Stack:: Using a Separate Signal Stack.
- * BSD Signal Handling:: Additional functions for backward
- compatibility with BSD.
- File: libc.info, Node: Concepts of Signals, Next: Standard Signals, Up: Signal Handling
- 24.1 Basic Concepts of Signals
- ==============================
- This section explains basic concepts of how signals are generated, what
- happens after a signal is delivered, and how programs can handle
- signals.
- * Menu:
- * Kinds of Signals:: Some examples of what can cause a signal.
- * Signal Generation:: Concepts of why and how signals occur.
- * Delivery of Signal:: Concepts of what a signal does to the
- process.
- File: libc.info, Node: Kinds of Signals, Next: Signal Generation, Up: Concepts of Signals
- 24.1.1 Some Kinds of Signals
- ----------------------------
- A signal reports the occurrence of an exceptional event. These are some
- of the events that can cause (or "generate", or "raise") a signal:
- • A program error such as dividing by zero or issuing an address
- outside the valid range.
- • A user request to interrupt or terminate the program. Most
- environments are set up to let a user suspend the program by typing
- ‘C-z’, or terminate it with ‘C-c’. Whatever key sequence is used,
- the operating system sends the proper signal to interrupt the
- process.
- • The termination of a child process.
- • Expiration of a timer or alarm.
- • A call to ‘kill’ or ‘raise’ by the same process.
- • A call to ‘kill’ from another process. Signals are a limited but
- useful form of interprocess communication.
- • An attempt to perform an I/O operation that cannot be done.
- Examples are reading from a pipe that has no writer (*note Pipes
- and FIFOs::), and reading or writing to a terminal in certain
- situations (*note Job Control::).
- Each of these kinds of events (excepting explicit calls to ‘kill’ and
- ‘raise’) generates its own particular kind of signal. The various kinds
- of signals are listed and described in detail in *note Standard
- Signals::.
- File: libc.info, Node: Signal Generation, Next: Delivery of Signal, Prev: Kinds of Signals, Up: Concepts of Signals
- 24.1.2 Concepts of Signal Generation
- ------------------------------------
- In general, the events that generate signals fall into three major
- categories: errors, external events, and explicit requests.
- An error means that a program has done something invalid and cannot
- continue execution. But not all kinds of errors generate signals—in
- fact, most do not. For example, opening a nonexistent file is an error,
- but it does not raise a signal; instead, ‘open’ returns ‘-1’. In
- general, errors that are necessarily associated with certain library
- functions are reported by returning a value that indicates an error.
- The errors which raise signals are those which can happen anywhere in
- the program, not just in library calls. These include division by zero
- and invalid memory addresses.
- An external event generally has to do with I/O or other processes.
- These include the arrival of input, the expiration of a timer, and the
- termination of a child process.
- An explicit request means the use of a library function such as
- ‘kill’ whose purpose is specifically to generate a signal.
- Signals may be generated "synchronously" or "asynchronously". A
- synchronous signal pertains to a specific action in the program, and is
- delivered (unless blocked) during that action. Most errors generate
- signals synchronously, and so do explicit requests by a process to
- generate a signal for that same process. On some machines, certain
- kinds of hardware errors (usually floating-point exceptions) are not
- reported completely synchronously, but may arrive a few instructions
- later.
- Asynchronous signals are generated by events outside the control of
- the process that receives them. These signals arrive at unpredictable
- times during execution. External events generate signals
- asynchronously, and so do explicit requests that apply to some other
- process.
- A given type of signal is either typically synchronous or typically
- asynchronous. For example, signals for errors are typically synchronous
- because errors generate signals synchronously. But any type of signal
- can be generated synchronously or asynchronously with an explicit
- request.
- File: libc.info, Node: Delivery of Signal, Prev: Signal Generation, Up: Concepts of Signals
- 24.1.3 How Signals Are Delivered
- --------------------------------
- When a signal is generated, it becomes "pending". Normally it remains
- pending for just a short period of time and then is "delivered" to the
- process that was signaled. However, if that kind of signal is currently
- "blocked", it may remain pending indefinitely—until signals of that kind
- are "unblocked". Once unblocked, it will be delivered immediately.
- *Note Blocking Signals::.
- When the signal is delivered, whether right away or after a long
- delay, the "specified action" for that signal is taken. For certain
- signals, such as ‘SIGKILL’ and ‘SIGSTOP’, the action is fixed, but for
- most signals, the program has a choice: ignore the signal, specify a
- "handler function", or accept the "default action" for that kind of
- signal. The program specifies its choice using functions such as
- ‘signal’ or ‘sigaction’ (*note Signal Actions::). We sometimes say that
- a handler "catches" the signal. While the handler is running, that
- particular signal is normally blocked.
- If the specified action for a kind of signal is to ignore it, then
- any such signal which is generated is discarded immediately. This
- happens even if the signal is also blocked at the time. A signal
- discarded in this way will never be delivered, not even if the program
- subsequently specifies a different action for that kind of signal and
- then unblocks it.
- If a signal arrives which the program has neither handled nor
- ignored, its "default action" takes place. Each kind of signal has its
- own default action, documented below (*note Standard Signals::). For
- most kinds of signals, the default action is to terminate the process.
- For certain kinds of signals that represent “harmless” events, the
- default action is to do nothing.
- When a signal terminates a process, its parent process can determine
- the cause of termination by examining the termination status code
- reported by the ‘wait’ or ‘waitpid’ functions. (This is discussed in
- more detail in *note Process Completion::.) The information it can get
- includes the fact that termination was due to a signal and the kind of
- signal involved. If a program you run from a shell is terminated by a
- signal, the shell typically prints some kind of error message.
- The signals that normally represent program errors have a special
- property: when one of these signals terminates the process, it also
- writes a "core dump file" which records the state of the process at the
- time of termination. You can examine the core dump with a debugger to
- investigate what caused the error.
- If you raise a “program error” signal by explicit request, and this
- terminates the process, it makes a core dump file just as if the signal
- had been due directly to an error.
- File: libc.info, Node: Standard Signals, Next: Signal Actions, Prev: Concepts of Signals, Up: Signal Handling
- 24.2 Standard Signals
- =====================
- This section lists the names for various standard kinds of signals and
- describes what kind of event they mean. Each signal name is a macro
- which stands for a positive integer—the "signal number" for that kind of
- signal. Your programs should never make assumptions about the numeric
- code for a particular kind of signal, but rather refer to them always by
- the names defined here. This is because the number for a given kind of
- signal can vary from system to system, but the meanings of the names are
- standardized and fairly uniform.
- The signal names are defined in the header file ‘signal.h’.
- -- Macro: int NSIG
- The value of this symbolic constant is the total number of signals
- defined. Since the signal numbers are allocated consecutively,
- ‘NSIG’ is also one greater than the largest defined signal number.
- * Menu:
- * Program Error Signals:: Used to report serious program errors.
- * Termination Signals:: Used to interrupt and/or terminate the
- program.
- * Alarm Signals:: Used to indicate expiration of timers.
- * Asynchronous I/O Signals:: Used to indicate input is available.
- * Job Control Signals:: Signals used to support job control.
- * Operation Error Signals:: Used to report operational system errors.
- * Miscellaneous Signals:: Miscellaneous Signals.
- * Signal Messages:: Printing a message describing a signal.
- File: libc.info, Node: Program Error Signals, Next: Termination Signals, Up: Standard Signals
- 24.2.1 Program Error Signals
- ----------------------------
- The following signals are generated when a serious program error is
- detected by the operating system or the computer itself. In general,
- all of these signals are indications that your program is seriously
- broken in some way, and there’s usually no way to continue the
- computation which encountered the error.
- Some programs handle program error signals in order to tidy up before
- terminating; for example, programs that turn off echoing of terminal
- input should handle program error signals in order to turn echoing back
- on. The handler should end by specifying the default action for the
- signal that happened and then reraising it; this will cause the program
- to terminate with that signal, as if it had not had a handler. (*Note
- Termination in Handler::.)
- Termination is the sensible ultimate outcome from a program error in
- most programs. However, programming systems such as Lisp that can load
- compiled user programs might need to keep executing even if a user
- program incurs an error. These programs have handlers which use
- ‘longjmp’ to return control to the command level.
- The default action for all of these signals is to cause the process
- to terminate. If you block or ignore these signals or establish
- handlers for them that return normally, your program will probably break
- horribly when such signals happen, unless they are generated by ‘raise’
- or ‘kill’ instead of a real error.
- When one of these program error signals terminates a process, it also
- writes a "core dump file" which records the state of the process at the
- time of termination. The core dump file is named ‘core’ and is written
- in whichever directory is current in the process at the time. (On
- GNU/Hurd systems, you can specify the file name for core dumps with the
- environment variable ‘COREFILE’.) The purpose of core dump files is so
- that you can examine them with a debugger to investigate what caused the
- error.
- -- Macro: int SIGFPE
- The ‘SIGFPE’ signal reports a fatal arithmetic error. Although the
- name is derived from “floating-point exception”, this signal
- actually covers all arithmetic errors, including division by zero
- and overflow. If a program stores integer data in a location which
- is then used in a floating-point operation, this often causes an
- “invalid operation” exception, because the processor cannot
- recognize the data as a floating-point number.
- Actual floating-point exceptions are a complicated subject because
- there are many types of exceptions with subtly different meanings,
- and the ‘SIGFPE’ signal doesn’t distinguish between them. The
- ‘IEEE Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std
- 754-1985 and ANSI/IEEE Std 854-1987)’ defines various
- floating-point exceptions and requires conforming computer systems
- to report their occurrences. However, this standard does not
- specify how the exceptions are reported, or what kinds of handling
- and control the operating system can offer to the programmer.
- BSD systems provide the ‘SIGFPE’ handler with an extra argument that
- distinguishes various causes of the exception. In order to access this
- argument, you must define the handler to accept two arguments, which
- means you must cast it to a one-argument function type in order to
- establish the handler. The GNU C Library does provide this extra
- argument, but the value is meaningful only on operating systems that
- provide the information (BSD systems and GNU systems).
- ‘FPE_INTOVF_TRAP’
- Integer overflow (impossible in a C program unless you enable
- overflow trapping in a hardware-specific fashion).
- ‘FPE_INTDIV_TRAP’
- Integer division by zero.
- ‘FPE_SUBRNG_TRAP’
- Subscript-range (something that C programs never check for).
- ‘FPE_FLTOVF_TRAP’
- Floating overflow trap.
- ‘FPE_FLTDIV_TRAP’
- Floating/decimal division by zero.
- ‘FPE_FLTUND_TRAP’
- Floating underflow trap. (Trapping on floating underflow is not
- normally enabled.)
- ‘FPE_DECOVF_TRAP’
- Decimal overflow trap. (Only a few machines have decimal
- arithmetic and C never uses it.)
- -- Macro: int SIGILL
- The name of this signal is derived from “illegal instruction”; it
- usually means your program is trying to execute garbage or a
- privileged instruction. Since the C compiler generates only valid
- instructions, ‘SIGILL’ typically indicates that the executable file
- is corrupted, or that you are trying to execute data. Some common
- ways of getting into the latter situation are by passing an invalid
- object where a pointer to a function was expected, or by writing
- past the end of an automatic array (or similar problems with
- pointers to automatic variables) and corrupting other data on the
- stack such as the return address of a stack frame.
- ‘SIGILL’ can also be generated when the stack overflows, or when
- the system has trouble running the handler for a signal.
- -- Macro: int SIGSEGV
- This signal is generated when a program tries to read or write
- outside the memory that is allocated for it, or to write memory
- that can only be read. (Actually, the signals only occur when the
- program goes far enough outside to be detected by the system’s
- memory protection mechanism.) The name is an abbreviation for
- “segmentation violation”.
- Common ways of getting a ‘SIGSEGV’ condition include dereferencing
- a null or uninitialized pointer, or when you use a pointer to step
- through an array, but fail to check for the end of the array. It
- varies among systems whether dereferencing a null pointer generates
- ‘SIGSEGV’ or ‘SIGBUS’.
- -- Macro: int SIGBUS
- This signal is generated when an invalid pointer is dereferenced.
- Like ‘SIGSEGV’, this signal is typically the result of
- dereferencing an uninitialized pointer. The difference between the
- two is that ‘SIGSEGV’ indicates an invalid access to valid memory,
- while ‘SIGBUS’ indicates an access to an invalid address. In
- particular, ‘SIGBUS’ signals often result from dereferencing a
- misaligned pointer, such as referring to a four-word integer at an
- address not divisible by four. (Each kind of computer has its own
- requirements for address alignment.)
- The name of this signal is an abbreviation for “bus error”.
- -- Macro: int SIGABRT
- This signal indicates an error detected by the program itself and
- reported by calling ‘abort’. *Note Aborting a Program::.
- -- Macro: int SIGIOT
- Generated by the PDP-11 “iot” instruction. On most machines, this
- is just another name for ‘SIGABRT’.
- -- Macro: int SIGTRAP
- Generated by the machine’s breakpoint instruction, and possibly
- other trap instructions. This signal is used by debuggers. Your
- program will probably only see ‘SIGTRAP’ if it is somehow executing
- bad instructions.
- -- Macro: int SIGEMT
- Emulator trap; this results from certain unimplemented instructions
- which might be emulated in software, or the operating system’s
- failure to properly emulate them.
- -- Macro: int SIGSYS
- Bad system call; that is to say, the instruction to trap to the
- operating system was executed, but the code number for the system
- call to perform was invalid.
- File: libc.info, Node: Termination Signals, Next: Alarm Signals, Prev: Program Error Signals, Up: Standard Signals
- 24.2.2 Termination Signals
- --------------------------
- These signals are all used to tell a process to terminate, in one way or
- another. They have different names because they’re used for slightly
- different purposes, and programs might want to handle them differently.
- The reason for handling these signals is usually so your program can
- tidy up as appropriate before actually terminating. For example, you
- might want to save state information, delete temporary files, or restore
- the previous terminal modes. Such a handler should end by specifying
- the default action for the signal that happened and then reraising it;
- this will cause the program to terminate with that signal, as if it had
- not had a handler. (*Note Termination in Handler::.)
- The (obvious) default action for all of these signals is to cause the
- process to terminate.
- -- Macro: int SIGTERM
- The ‘SIGTERM’ signal is a generic signal used to cause program
- termination. Unlike ‘SIGKILL’, this signal can be blocked,
- handled, and ignored. It is the normal way to politely ask a
- program to terminate.
- The shell command ‘kill’ generates ‘SIGTERM’ by default.
- -- Macro: int SIGINT
- The ‘SIGINT’ (“program interrupt”) signal is sent when the user
- types the INTR character (normally ‘C-c’). *Note Special
- Characters::, for information about terminal driver support for
- ‘C-c’.
- -- Macro: int SIGQUIT
- The ‘SIGQUIT’ signal is similar to ‘SIGINT’, except that it’s
- controlled by a different key—the QUIT character, usually ‘C-\’—and
- produces a core dump when it terminates the process, just like a
- program error signal. You can think of this as a program error
- condition “detected” by the user.
- *Note Program Error Signals::, for information about core dumps.
- *Note Special Characters::, for information about terminal driver
- support.
- Certain kinds of cleanups are best omitted in handling ‘SIGQUIT’.
- For example, if the program creates temporary files, it should
- handle the other termination requests by deleting the temporary
- files. But it is better for ‘SIGQUIT’ not to delete them, so that
- the user can examine them in conjunction with the core dump.
- -- Macro: int SIGKILL
- The ‘SIGKILL’ signal is used to cause immediate program
- termination. It cannot be handled or ignored, and is therefore
- always fatal. It is also not possible to block this signal.
- This signal is usually generated only by explicit request. Since
- it cannot be handled, you should generate it only as a last resort,
- after first trying a less drastic method such as ‘C-c’ or
- ‘SIGTERM’. If a process does not respond to any other termination
- signals, sending it a ‘SIGKILL’ signal will almost always cause it
- to go away.
- In fact, if ‘SIGKILL’ fails to terminate a process, that by itself
- constitutes an operating system bug which you should report.
- The system will generate ‘SIGKILL’ for a process itself under some
- unusual conditions where the program cannot possibly continue to
- run (even to run a signal handler).
- -- Macro: int SIGHUP
- The ‘SIGHUP’ (“hang-up”) signal is used to report that the user’s
- terminal is disconnected, perhaps because a network or telephone
- connection was broken. For more information about this, see *note
- Control Modes::.
- This signal is also used to report the termination of the
- controlling process on a terminal to jobs associated with that
- session; this termination effectively disconnects all processes in
- the session from the controlling terminal. For more information,
- see *note Termination Internals::.
- File: libc.info, Node: Alarm Signals, Next: Asynchronous I/O Signals, Prev: Termination Signals, Up: Standard Signals
- 24.2.3 Alarm Signals
- --------------------
- These signals are used to indicate the expiration of timers. *Note
- Setting an Alarm::, for information about functions that cause these
- signals to be sent.
- The default behavior for these signals is to cause program
- termination. This default is rarely useful, but no other default would
- be useful; most of the ways of using these signals would require handler
- functions in any case.
- -- Macro: int SIGALRM
- This signal typically indicates expiration of a timer that measures
- real or clock time. It is used by the ‘alarm’ function, for
- example.
- -- Macro: int SIGVTALRM
- This signal typically indicates expiration of a timer that measures
- CPU time used by the current process. The name is an abbreviation
- for “virtual time alarm”.
- -- Macro: int SIGPROF
- This signal typically indicates expiration of a timer that measures
- both CPU time used by the current process, and CPU time expended on
- behalf of the process by the system. Such a timer is used to
- implement code profiling facilities, hence the name of this signal.
- File: libc.info, Node: Asynchronous I/O Signals, Next: Job Control Signals, Prev: Alarm Signals, Up: Standard Signals
- 24.2.4 Asynchronous I/O Signals
- -------------------------------
- The signals listed in this section are used in conjunction with
- asynchronous I/O facilities. You have to take explicit action by
- calling ‘fcntl’ to enable a particular file descriptor to generate these
- signals (*note Interrupt Input::). The default action for these signals
- is to ignore them.
- -- Macro: int SIGIO
- This signal is sent when a file descriptor is ready to perform
- input or output.
- On most operating systems, terminals and sockets are the only kinds
- of files that can generate ‘SIGIO’; other kinds, including ordinary
- files, never generate ‘SIGIO’ even if you ask them to.
- On GNU systems ‘SIGIO’ will always be generated properly if you
- successfully set asynchronous mode with ‘fcntl’.
- -- Macro: int SIGURG
- This signal is sent when “urgent” or out-of-band data arrives on a
- socket. *Note Out-of-Band Data::.
- -- Macro: int SIGPOLL
- This is a System V signal name, more or less similar to ‘SIGIO’.
- It is defined only for compatibility.
- File: libc.info, Node: Job Control Signals, Next: Operation Error Signals, Prev: Asynchronous I/O Signals, Up: Standard Signals
- 24.2.5 Job Control Signals
- --------------------------
- These signals are used to support job control. If your system doesn’t
- support job control, then these macros are defined but the signals
- themselves can’t be raised or handled.
- You should generally leave these signals alone unless you really
- understand how job control works. *Note Job Control::.
- -- Macro: int SIGCHLD
- This signal is sent to a parent process whenever one of its child
- processes terminates or stops.
- The default action for this signal is to ignore it. If you
- establish a handler for this signal while there are child processes
- that have terminated but not reported their status via ‘wait’ or
- ‘waitpid’ (*note Process Completion::), whether your new handler
- applies to those processes or not depends on the particular
- operating system.
- -- Macro: int SIGCLD
- This is an obsolete name for ‘SIGCHLD’.
- -- Macro: int SIGCONT
- You can send a ‘SIGCONT’ signal to a process to make it continue.
- This signal is special—it always makes the process continue if it
- is stopped, before the signal is delivered. The default behavior
- is to do nothing else. You cannot block this signal. You can set
- a handler, but ‘SIGCONT’ always makes the process continue
- regardless.
- Most programs have no reason to handle ‘SIGCONT’; they simply
- resume execution without realizing they were ever stopped. You can
- use a handler for ‘SIGCONT’ to make a program do something special
- when it is stopped and continued—for example, to reprint a prompt
- when it is suspended while waiting for input.
- -- Macro: int SIGSTOP
- The ‘SIGSTOP’ signal stops the process. It cannot be handled,
- ignored, or blocked.
- -- Macro: int SIGTSTP
- The ‘SIGTSTP’ signal is an interactive stop signal. Unlike
- ‘SIGSTOP’, this signal can be handled and ignored.
- Your program should handle this signal if you have a special need
- to leave files or system tables in a secure state when a process is
- stopped. For example, programs that turn off echoing should handle
- ‘SIGTSTP’ so they can turn echoing back on before stopping.
- This signal is generated when the user types the SUSP character
- (normally ‘C-z’). For more information about terminal driver
- support, see *note Special Characters::.
- -- Macro: int SIGTTIN
- A process cannot read from the user’s terminal while it is running
- as a background job. When any process in a background job tries to
- read from the terminal, all of the processes in the job are sent a
- ‘SIGTTIN’ signal. The default action for this signal is to stop
- the process. For more information about how this interacts with
- the terminal driver, see *note Access to the Terminal::.
- -- Macro: int SIGTTOU
- This is similar to ‘SIGTTIN’, but is generated when a process in a
- background job attempts to write to the terminal or set its modes.
- Again, the default action is to stop the process. ‘SIGTTOU’ is
- only generated for an attempt to write to the terminal if the
- ‘TOSTOP’ output mode is set; *note Output Modes::.
- While a process is stopped, no more signals can be delivered to it
- until it is continued, except ‘SIGKILL’ signals and (obviously)
- ‘SIGCONT’ signals. The signals are marked as pending, but not delivered
- until the process is continued. The ‘SIGKILL’ signal always causes
- termination of the process and can’t be blocked, handled or ignored.
- You can ignore ‘SIGCONT’, but it always causes the process to be
- continued anyway if it is stopped. Sending a ‘SIGCONT’ signal to a
- process causes any pending stop signals for that process to be
- discarded. Likewise, any pending ‘SIGCONT’ signals for a process are
- discarded when it receives a stop signal.
- When a process in an orphaned process group (*note Orphaned Process
- Groups::) receives a ‘SIGTSTP’, ‘SIGTTIN’, or ‘SIGTTOU’ signal and does
- not handle it, the process does not stop. Stopping the process would
- probably not be very useful, since there is no shell program that will
- notice it stop and allow the user to continue it. What happens instead
- depends on the operating system you are using. Some systems may do
- nothing; others may deliver another signal instead, such as ‘SIGKILL’ or
- ‘SIGHUP’. On GNU/Hurd systems, the process dies with ‘SIGKILL’; this
- avoids the problem of many stopped, orphaned processes lying around the
- system.
- File: libc.info, Node: Operation Error Signals, Next: Miscellaneous Signals, Prev: Job Control Signals, Up: Standard Signals
- 24.2.6 Operation Error Signals
- ------------------------------
- These signals are used to report various errors generated by an
- operation done by the program. They do not necessarily indicate a
- programming error in the program, but an error that prevents an
- operating system call from completing. The default action for all of
- them is to cause the process to terminate.
- -- Macro: int SIGPIPE
- Broken pipe. If you use pipes or FIFOs, you have to design your
- application so that one process opens the pipe for reading before
- another starts writing. If the reading process never starts, or
- terminates unexpectedly, writing to the pipe or FIFO raises a
- ‘SIGPIPE’ signal. If ‘SIGPIPE’ is blocked, handled or ignored, the
- offending call fails with ‘EPIPE’ instead.
- Pipes and FIFO special files are discussed in more detail in *note
- Pipes and FIFOs::.
- Another cause of ‘SIGPIPE’ is when you try to output to a socket
- that isn’t connected. *Note Sending Data::.
- -- Macro: int SIGLOST
- Resource lost. This signal is generated when you have an advisory
- lock on an NFS file, and the NFS server reboots and forgets about
- your lock.
- On GNU/Hurd systems, ‘SIGLOST’ is generated when any server program
- dies unexpectedly. It is usually fine to ignore the signal;
- whatever call was made to the server that died just returns an
- error.
- -- Macro: int SIGXCPU
- CPU time limit exceeded. This signal is generated when the process
- exceeds its soft resource limit on CPU time. *Note Limits on
- Resources::.
- -- Macro: int SIGXFSZ
- File size limit exceeded. This signal is generated when the
- process attempts to extend a file so it exceeds the process’s soft
- resource limit on file size. *Note Limits on Resources::.
- File: libc.info, Node: Miscellaneous Signals, Next: Signal Messages, Prev: Operation Error Signals, Up: Standard Signals
- 24.2.7 Miscellaneous Signals
- ----------------------------
- These signals are used for various other purposes. In general, they
- will not affect your program unless it explicitly uses them for
- something.
- -- Macro: int SIGUSR1
- -- Macro: int SIGUSR2
- The ‘SIGUSR1’ and ‘SIGUSR2’ signals are set aside for you to use
- any way you want. They’re useful for simple interprocess
- communication, if you write a signal handler for them in the
- program that receives the signal.
- There is an example showing the use of ‘SIGUSR1’ and ‘SIGUSR2’ in
- *note Signaling Another Process::.
- The default action is to terminate the process.
- -- Macro: int SIGWINCH
- Window size change. This is generated on some systems (including
- GNU) when the terminal driver’s record of the number of rows and
- columns on the screen is changed. The default action is to ignore
- it.
- If a program does full-screen display, it should handle ‘SIGWINCH’.
- When the signal arrives, it should fetch the new screen size and
- reformat its display accordingly.
- -- Macro: int SIGINFO
- Information request. On 4.4 BSD and GNU/Hurd systems, this signal
- is sent to all the processes in the foreground process group of the
- controlling terminal when the user types the STATUS character in
- canonical mode; *note Signal Characters::.
- If the process is the leader of the process group, the default
- action is to print some status information about the system and
- what the process is doing. Otherwise the default is to do nothing.
- File: libc.info, Node: Signal Messages, Prev: Miscellaneous Signals, Up: Standard Signals
- 24.2.8 Signal Messages
- ----------------------
- We mentioned above that the shell prints a message describing the signal
- that terminated a child process. The clean way to print a message
- describing a signal is to use the functions ‘strsignal’ and ‘psignal’.
- These functions use a signal number to specify which kind of signal to
- describe. The signal number may come from the termination status of a
- child process (*note Process Completion::) or it may come from a signal
- handler in the same process.
- -- Function: char * strsignal (int SIGNUM)
- Preliminary: | MT-Unsafe race:strsignal locale | AS-Unsafe init
- i18n corrupt heap | AC-Unsafe init corrupt mem | *Note POSIX Safety
- Concepts::.
- This function returns a pointer to a statically-allocated string
- containing a message describing the signal SIGNUM. You should not
- modify the contents of this string; and, since it can be rewritten
- on subsequent calls, you should save a copy of it if you need to
- reference it later.
- This function is a GNU extension, declared in the header file
- ‘string.h’.
- -- Function: void psignal (int SIGNUM, const char *MESSAGE)
- Preliminary: | MT-Safe locale | AS-Unsafe corrupt i18n heap |
- AC-Unsafe lock corrupt mem | *Note POSIX Safety Concepts::.
- This function prints a message describing the signal SIGNUM to the
- standard error output stream ‘stderr’; see *note Standard
- Streams::.
- If you call ‘psignal’ with a MESSAGE that is either a null pointer
- or an empty string, ‘psignal’ just prints the message corresponding
- to SIGNUM, adding a trailing newline.
- If you supply a non-null MESSAGE argument, then ‘psignal’ prefixes
- its output with this string. It adds a colon and a space character
- to separate the MESSAGE from the string corresponding to SIGNUM.
- This function is a BSD feature, declared in the header file
- ‘signal.h’.
- There is also an array ‘sys_siglist’ which contains the messages for
- the various signal codes. This array exists on BSD systems, unlike
- ‘strsignal’.
- File: libc.info, Node: Signal Actions, Next: Defining Handlers, Prev: Standard Signals, Up: Signal Handling
- 24.3 Specifying Signal Actions
- ==============================
- The simplest way to change the action for a signal is to use the
- ‘signal’ function. You can specify a built-in action (such as to ignore
- the signal), or you can "establish a handler".
- The GNU C Library also implements the more versatile ‘sigaction’
- facility. This section describes both facilities and gives suggestions
- on which to use when.
- * Menu:
- * Basic Signal Handling:: The simple ‘signal’ function.
- * Advanced Signal Handling:: The more powerful ‘sigaction’ function.
- * Signal and Sigaction:: How those two functions interact.
- * Sigaction Function Example:: An example of using the sigaction function.
- * Flags for Sigaction:: Specifying options for signal handling.
- * Initial Signal Actions:: How programs inherit signal actions.
- File: libc.info, Node: Basic Signal Handling, Next: Advanced Signal Handling, Up: Signal Actions
- 24.3.1 Basic Signal Handling
- ----------------------------
- The ‘signal’ function provides a simple interface for establishing an
- action for a particular signal. The function and associated macros are
- declared in the header file ‘signal.h’.
- -- Data Type: sighandler_t
- This is the type of signal handler functions. Signal handlers take
- one integer argument specifying the signal number, and have return
- type ‘void’. So, you should define handler functions like this:
- void HANDLER (int signum) { … }
- The name ‘sighandler_t’ for this data type is a GNU extension.
- -- Function: sighandler_t signal (int SIGNUM, sighandler_t ACTION)
- Preliminary: | MT-Safe sigintr | AS-Safe | AC-Safe | *Note POSIX
- Safety Concepts::.
- The ‘signal’ function establishes ACTION as the action for the
- signal SIGNUM.
- The first argument, SIGNUM, identifies the signal whose behavior
- you want to control, and should be a signal number. The proper way
- to specify a signal number is with one of the symbolic signal names
- (*note Standard Signals::)—don’t use an explicit number, because
- the numerical code for a given kind of signal may vary from
- operating system to operating system.
- The second argument, ACTION, specifies the action to use for the
- signal SIGNUM. This can be one of the following:
- ‘SIG_DFL’
- ‘SIG_DFL’ specifies the default action for the particular
- signal. The default actions for various kinds of signals are
- stated in *note Standard Signals::.
- ‘SIG_IGN’
- ‘SIG_IGN’ specifies that the signal should be ignored.
- Your program generally should not ignore signals that
- represent serious events or that are normally used to request
- termination. You cannot ignore the ‘SIGKILL’ or ‘SIGSTOP’
- signals at all. You can ignore program error signals like
- ‘SIGSEGV’, but ignoring the error won’t enable the program to
- continue executing meaningfully. Ignoring user requests such
- as ‘SIGINT’, ‘SIGQUIT’, and ‘SIGTSTP’ is unfriendly.
- When you do not wish signals to be delivered during a certain
- part of the program, the thing to do is to block them, not
- ignore them. *Note Blocking Signals::.
- ‘HANDLER’
- Supply the address of a handler function in your program, to
- specify running this handler as the way to deliver the signal.
- For more information about defining signal handler functions,
- see *note Defining Handlers::.
- If you set the action for a signal to ‘SIG_IGN’, or if you set it
- to ‘SIG_DFL’ and the default action is to ignore that signal, then
- any pending signals of that type are discarded (even if they are
- blocked). Discarding the pending signals means that they will
- never be delivered, not even if you subsequently specify another
- action and unblock this kind of signal.
- The ‘signal’ function returns the action that was previously in
- effect for the specified SIGNUM. You can save this value and
- restore it later by calling ‘signal’ again.
- If ‘signal’ can’t honor the request, it returns ‘SIG_ERR’ instead.
- The following ‘errno’ error conditions are defined for this
- function:
- ‘EINVAL’
- You specified an invalid SIGNUM; or you tried to ignore or
- provide a handler for ‘SIGKILL’ or ‘SIGSTOP’.
- *Compatibility Note:* A problem encountered when working with the
- ‘signal’ function is that it has different semantics on BSD and SVID
- systems. The difference is that on SVID systems the signal handler is
- deinstalled after signal delivery. On BSD systems the handler must be
- explicitly deinstalled. In the GNU C Library we use the BSD version by
- default. To use the SVID version you can either use the function
- ‘sysv_signal’ (see below) or use the ‘_XOPEN_SOURCE’ feature select
- macro (*note Feature Test Macros::). In general, use of these functions
- should be avoided because of compatibility problems. It is better to
- use ‘sigaction’ if it is available since the results are much more
- reliable.
- Here is a simple example of setting up a handler to delete temporary
- files when certain fatal signals happen:
- #include <signal.h>
- void
- termination_handler (int signum)
- {
- struct temp_file *p;
- for (p = temp_file_list; p; p = p->next)
- unlink (p->name);
- }
- int
- main (void)
- {
- …
- if (signal (SIGINT, termination_handler) == SIG_IGN)
- signal (SIGINT, SIG_IGN);
- if (signal (SIGHUP, termination_handler) == SIG_IGN)
- signal (SIGHUP, SIG_IGN);
- if (signal (SIGTERM, termination_handler) == SIG_IGN)
- signal (SIGTERM, SIG_IGN);
- …
- }
- Note that if a given signal was previously set to be ignored, this code
- avoids altering that setting. This is because non-job-control shells
- often ignore certain signals when starting children, and it is important
- for the children to respect this.
- We do not handle ‘SIGQUIT’ or the program error signals in this
- example because these are designed to provide information for debugging
- (a core dump), and the temporary files may give useful information.
- -- Function: sighandler_t sysv_signal (int SIGNUM, sighandler_t ACTION)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ‘sysv_signal’ implements the behavior of the standard ‘signal’
- function as found on SVID systems. The difference to BSD systems
- is that the handler is deinstalled after a delivery of a signal.
- *Compatibility Note:* As said above for ‘signal’, this function
- should be avoided when possible. ‘sigaction’ is the preferred
- method.
- -- Function: sighandler_t ssignal (int SIGNUM, sighandler_t ACTION)
- Preliminary: | MT-Safe sigintr | AS-Safe | AC-Safe | *Note POSIX
- Safety Concepts::.
- The ‘ssignal’ function does the same thing as ‘signal’; it is
- provided only for compatibility with SVID.
- -- Macro: sighandler_t SIG_ERR
- The value of this macro is used as the return value from ‘signal’
- to indicate an error.
- File: libc.info, Node: Advanced Signal Handling, Next: Signal and Sigaction, Prev: Basic Signal Handling, Up: Signal Actions
- 24.3.2 Advanced Signal Handling
- -------------------------------
- The ‘sigaction’ function has the same basic effect as ‘signal’: to
- specify how a signal should be handled by the process. However,
- ‘sigaction’ offers more control, at the expense of more complexity. In
- particular, ‘sigaction’ allows you to specify additional flags to
- control when the signal is generated and how the handler is invoked.
- The ‘sigaction’ function is declared in ‘signal.h’.
- -- Data Type: struct sigaction
- Structures of type ‘struct sigaction’ are used in the ‘sigaction’
- function to specify all the information about how to handle a
- particular signal. This structure contains at least the following
- members:
- ‘sighandler_t sa_handler’
- This is used in the same way as the ACTION argument to the
- ‘signal’ function. The value can be ‘SIG_DFL’, ‘SIG_IGN’, or
- a function pointer. *Note Basic Signal Handling::.
- ‘sigset_t sa_mask’
- This specifies a set of signals to be blocked while the
- handler runs. Blocking is explained in *note Blocking for
- Handler::. Note that the signal that was delivered is
- automatically blocked by default before its handler is
- started; this is true regardless of the value in ‘sa_mask’.
- If you want that signal not to be blocked within its handler,
- you must write code in the handler to unblock it.
- ‘int sa_flags’
- This specifies various flags which can affect the behavior of
- the signal. These are described in more detail in *note Flags
- for Sigaction::.
- -- Function: int sigaction (int SIGNUM, const struct sigaction
- *restrict ACTION, struct sigaction *restrict OLD-ACTION)
- Preliminary: | MT-Safe | AS-Safe | AC-Safe | *Note POSIX Safety
- Concepts::.
- The ACTION argument is used to set up a new action for the signal
- SIGNUM, while the OLD-ACTION argument is used to return information
- about the action previously associated with this signal. (In other
- words, OLD-ACTION has the same purpose as the ‘signal’ function’s
- return value—you can check to see what the old action in effect for
- the signal was, and restore it later if you want.)
- Either ACTION or OLD-ACTION can be a null pointer. If OLD-ACTION
- is a null pointer, this simply suppresses the return of information
- about the old action. If ACTION is a null pointer, the action
- associated with the signal SIGNUM is unchanged; this allows you to
- inquire about how a signal is being handled without changing that
- handling.
- The return value from ‘sigaction’ is zero if it succeeds, and ‘-1’
- on failure. The following ‘errno’ error conditions are defined for
- this function:
- ‘EINVAL’
- The SIGNUM argument is not valid, or you are trying to trap or
- ignore ‘SIGKILL’ or ‘SIGSTOP’.
- File: libc.info, Node: Signal and Sigaction, Next: Sigaction Function Example, Prev: Advanced Signal Handling, Up: Signal Actions
- 24.3.3 Interaction of ‘signal’ and ‘sigaction’
- ----------------------------------------------
- It’s possible to use both the ‘signal’ and ‘sigaction’ functions within
- a single program, but you have to be careful because they can interact
- in slightly strange ways.
- The ‘sigaction’ function specifies more information than the ‘signal’
- function, so the return value from ‘signal’ cannot express the full
- range of ‘sigaction’ possibilities. Therefore, if you use ‘signal’ to
- save and later reestablish an action, it may not be able to reestablish
- properly a handler that was established with ‘sigaction’.
- To avoid having problems as a result, always use ‘sigaction’ to save
- and restore a handler if your program uses ‘sigaction’ at all. Since
- ‘sigaction’ is more general, it can properly save and reestablish any
- action, regardless of whether it was established originally with
- ‘signal’ or ‘sigaction’.
- On some systems if you establish an action with ‘signal’ and then
- examine it with ‘sigaction’, the handler address that you get may not be
- the same as what you specified with ‘signal’. It may not even be
- suitable for use as an action argument with ‘signal’. But you can rely
- on using it as an argument to ‘sigaction’. This problem never happens
- on GNU systems.
- So, you’re better off using one or the other of the mechanisms
- consistently within a single program.
- *Portability Note:* The basic ‘signal’ function is a feature of
- ISO C, while ‘sigaction’ is part of the POSIX.1 standard. If you are
- concerned about portability to non-POSIX systems, then you should use
- the ‘signal’ function instead.
- File: libc.info, Node: Sigaction Function Example, Next: Flags for Sigaction, Prev: Signal and Sigaction, Up: Signal Actions
- 24.3.4 ‘sigaction’ Function Example
- -----------------------------------
- In *note Basic Signal Handling::, we gave an example of establishing a
- simple handler for termination signals using ‘signal’. Here is an
- equivalent example using ‘sigaction’:
- #include <signal.h>
- void
- termination_handler (int signum)
- {
- struct temp_file *p;
- for (p = temp_file_list; p; p = p->next)
- unlink (p->name);
- }
- int
- main (void)
- {
- …
- struct sigaction new_action, old_action;
- /* Set up the structure to specify the new action. */
- new_action.sa_handler = termination_handler;
- sigemptyset (&new_action.sa_mask);
- new_action.sa_flags = 0;
- sigaction (SIGINT, NULL, &old_action);
- if (old_action.sa_handler != SIG_IGN)
- sigaction (SIGINT, &new_action, NULL);
- sigaction (SIGHUP, NULL, &old_action);
- if (old_action.sa_handler != SIG_IGN)
- sigaction (SIGHUP, &new_action, NULL);
- sigaction (SIGTERM, NULL, &old_action);
- if (old_action.sa_handler != SIG_IGN)
- sigaction (SIGTERM, &new_action, NULL);
- …
- }
- The program just loads the ‘new_action’ structure with the desired
- parameters and passes it in the ‘sigaction’ call. The usage of
- ‘sigemptyset’ is described later; see *note Blocking Signals::.
- As in the example using ‘signal’, we avoid handling signals
- previously set to be ignored. Here we can avoid altering the signal
- handler even momentarily, by using the feature of ‘sigaction’ that lets
- us examine the current action without specifying a new one.
- Here is another example. It retrieves information about the current
- action for ‘SIGINT’ without changing that action.
- struct sigaction query_action;
- if (sigaction (SIGINT, NULL, &query_action) < 0)
- /* ‘sigaction’ returns -1 in case of error. */
- else if (query_action.sa_handler == SIG_DFL)
- /* ‘SIGINT’ is handled in the default, fatal manner. */
- else if (query_action.sa_handler == SIG_IGN)
- /* ‘SIGINT’ is ignored. */
- else
- /* A programmer-defined signal handler is in effect. */
|