| 12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223122412251226122712281229123012311232123312341235123612371238123912401241124212431244124512461247124812491250125112521253125412551256125712581259126012611262126312641265126612671268126912701271127212731274127512761277127812791280128112821283128412851286128712881289129012911292129312941295129612971298129913001301130213031304130513061307130813091310131113121313131413151316131713181319132013211322132313241325132613271328132913301331133213331334133513361337133813391340134113421343134413451346134713481349135013511352135313541355135613571358135913601361136213631364136513661367136813691370137113721373137413751376137713781379138013811382138313841385138613871388138913901391139213931394139513961397139813991400140114021403140414051406140714081409141014111412141314141415141614171418141914201421142214231424142514261427142814291430143114321433143414351436143714381439144014411442144314441445144614471448144914501451145214531454145514561457145814591460146114621463146414651466146714681469147014711472147314741475147614771478147914801481148214831484148514861487148814891490149114921493149414951496149714981499150015011502150315041505150615071508150915101511151215131514151515161517151815191520152115221523152415251526152715281529153015311532153315341535153615371538153915401541154215431544154515461547154815491550155115521553155415551556155715581559156015611562156315641565156615671568156915701571157215731574157515761577157815791580158115821583158415851586158715881589159015911592159315941595159615971598159916001601160216031604160516061607160816091610161116121613161416151616161716181619162016211622162316241625162616271628162916301631163216331634163516361637163816391640164116421643164416451646164716481649165016511652165316541655165616571658165916601661166216631664166516661667166816691670167116721673167416751676167716781679168016811682168316841685168616871688168916901691169216931694169516961697169816991700170117021703170417051706170717081709171017111712171317141715171617171718171917201721172217231724172517261727172817291730173117321733173417351736173717381739174017411742174317441745174617471748174917501751175217531754175517561757175817591760176117621763176417651766176717681769177017711772177317741775177617771778177917801781178217831784178517861787178817891790179117921793179417951796179717981799180018011802180318041805180618071808180918101811181218131814181518161817181818191820182118221823182418251826182718281829183018311832183318341835183618371838183918401841184218431844184518461847184818491850185118521853185418551856185718581859186018611862186318641865186618671868186918701871187218731874187518761877187818791880188118821883188418851886188718881889189018911892189318941895189618971898189919001901190219031904190519061907190819091910191119121913191419151916191719181919192019211922192319241925192619271928192919301931193219331934193519361937193819391940194119421943194419451946194719481949195019511952195319541955195619571958195919601961196219631964196519661967196819691970197119721973197419751976197719781979198019811982198319841985198619871988198919901991199219931994199519961997199819992000200120022003200420052006200720082009201020112012201320142015201620172018201920202021202220232024202520262027202820292030203120322033203420352036203720382039204020412042204320442045204620472048204920502051205220532054205520562057205820592060206120622063206420652066206720682069207020712072207320742075207620772078207920802081208220832084208520862087208820892090209120922093209420952096209720982099210021012102210321042105210621072108210921102111211221132114211521162117211821192120212121222123212421252126212721282129213021312132213321342135213621372138213921402141214221432144214521462147214821492150215121522153215421552156215721582159216021612162216321642165216621672168216921702171217221732174217521762177217821792180218121822183218421852186218721882189219021912192219321942195219621972198219922002201220222032204220522062207220822092210221122122213221422152216221722182219222022212222222322242225222622272228222922302231223222332234223522362237223822392240224122422243224422452246224722482249225022512252225322542255225622572258225922602261226222632264226522662267226822692270227122722273227422752276227722782279228022812282228322842285228622872288228922902291229222932294229522962297229822992300230123022303230423052306230723082309231023112312231323142315231623172318231923202321232223232324232523262327232823292330233123322333233423352336233723382339234023412342234323442345234623472348234923502351235223532354235523562357235823592360236123622363236423652366236723682369237023712372237323742375237623772378237923802381238223832384238523862387238823892390239123922393239423952396239723982399240024012402240324042405240624072408240924102411241224132414241524162417241824192420242124222423242424252426242724282429243024312432243324342435243624372438243924402441244224432444244524462447244824492450245124522453245424552456245724582459246024612462246324642465246624672468246924702471247224732474247524762477247824792480248124822483248424852486248724882489249024912492249324942495249624972498249925002501250225032504250525062507250825092510251125122513251425152516251725182519252025212522252325242525252625272528252925302531253225332534253525362537253825392540254125422543254425452546254725482549255025512552255325542555255625572558255925602561256225632564256525662567256825692570257125722573257425752576257725782579258025812582258325842585258625872588258925902591259225932594259525962597259825992600260126022603260426052606260726082609261026112612261326142615261626172618261926202621262226232624262526262627262826292630263126322633263426352636263726382639264026412642264326442645264626472648264926502651265226532654265526562657265826592660266126622663266426652666266726682669267026712672267326742675267626772678267926802681268226832684268526862687268826892690269126922693269426952696269726982699270027012702270327042705270627072708270927102711271227132714271527162717271827192720272127222723272427252726272727282729273027312732273327342735273627372738273927402741274227432744274527462747274827492750275127522753275427552756275727582759276027612762276327642765276627672768276927702771277227732774277527762777277827792780278127822783278427852786278727882789279027912792279327942795279627972798279928002801280228032804280528062807280828092810281128122813281428152816281728182819282028212822282328242825282628272828282928302831283228332834283528362837283828392840284128422843284428452846284728482849285028512852285328542855285628572858285928602861286228632864286528662867286828692870287128722873287428752876287728782879288028812882288328842885288628872888288928902891289228932894289528962897289828992900290129022903290429052906290729082909291029112912291329142915291629172918291929202921292229232924292529262927292829292930293129322933293429352936293729382939294029412942294329442945294629472948294929502951295229532954295529562957295829592960296129622963296429652966296729682969297029712972297329742975297629772978297929802981298229832984298529862987298829892990299129922993299429952996299729982999300030013002300330043005300630073008300930103011301230133014301530163017301830193020302130223023302430253026302730283029303030313032303330343035303630373038303930403041304230433044304530463047304830493050305130523053305430553056305730583059306030613062306330643065306630673068306930703071307230733074307530763077307830793080308130823083308430853086308730883089309030913092309330943095309630973098309931003101310231033104310531063107310831093110311131123113311431153116311731183119312031213122312331243125312631273128312931303131313231333134313531363137313831393140314131423143314431453146314731483149315031513152315331543155315631573158315931603161316231633164316531663167316831693170317131723173317431753176317731783179318031813182318331843185318631873188318931903191319231933194319531963197319831993200320132023203320432053206320732083209321032113212321332143215321632173218321932203221322232233224322532263227322832293230323132323233323432353236323732383239324032413242324332443245324632473248324932503251325232533254325532563257325832593260326132623263326432653266326732683269327032713272327332743275327632773278327932803281328232833284328532863287328832893290329132923293329432953296329732983299330033013302330333043305330633073308330933103311331233133314331533163317331833193320332133223323332433253326332733283329333033313332333333343335333633373338333933403341334233433344334533463347334833493350335133523353335433553356335733583359336033613362336333643365336633673368336933703371337233733374337533763377337833793380338133823383338433853386338733883389339033913392339333943395339633973398339934003401340234033404340534063407340834093410341134123413341434153416341734183419342034213422342334243425342634273428342934303431343234333434343534363437343834393440344134423443344434453446344734483449345034513452345334543455345634573458345934603461346234633464346534663467346834693470347134723473347434753476347734783479348034813482348334843485348634873488348934903491349234933494349534963497349834993500350135023503350435053506350735083509351035113512351335143515351635173518351935203521352235233524352535263527352835293530353135323533353435353536353735383539354035413542354335443545354635473548354935503551355235533554355535563557355835593560356135623563356435653566356735683569357035713572357335743575357635773578357935803581358235833584358535863587358835893590359135923593359435953596359735983599360036013602360336043605360636073608360936103611361236133614361536163617361836193620362136223623362436253626362736283629363036313632363336343635363636373638363936403641364236433644364536463647364836493650365136523653365436553656365736583659366036613662366336643665366636673668366936703671367236733674367536763677367836793680368136823683368436853686368736883689369036913692369336943695369636973698369937003701370237033704370537063707370837093710371137123713371437153716371737183719372037213722372337243725372637273728372937303731373237333734373537363737373837393740374137423743374437453746374737483749375037513752375337543755375637573758375937603761376237633764376537663767376837693770377137723773377437753776377737783779378037813782378337843785378637873788378937903791379237933794379537963797379837993800380138023803380438053806380738083809381038113812381338143815381638173818381938203821382238233824382538263827382838293830383138323833383438353836383738383839384038413842384338443845384638473848384938503851385238533854385538563857385838593860386138623863386438653866386738683869387038713872387338743875387638773878387938803881388238833884388538863887388838893890389138923893389438953896389738983899390039013902390339043905390639073908390939103911391239133914391539163917391839193920392139223923392439253926392739283929393039313932393339343935393639373938393939403941394239433944394539463947394839493950395139523953395439553956395739583959396039613962396339643965396639673968396939703971397239733974397539763977397839793980398139823983398439853986398739883989399039913992399339943995399639973998399940004001400240034004400540064007400840094010401140124013401440154016401740184019402040214022402340244025402640274028402940304031403240334034403540364037403840394040404140424043404440454046404740484049405040514052405340544055405640574058405940604061406240634064406540664067406840694070407140724073407440754076407740784079408040814082408340844085408640874088408940904091409240934094409540964097409840994100410141024103410441054106410741084109411041114112411341144115411641174118411941204121412241234124412541264127412841294130413141324133413441354136413741384139414041414142414341444145414641474148414941504151415241534154415541564157415841594160416141624163416441654166416741684169417041714172417341744175417641774178417941804181418241834184418541864187418841894190419141924193419441954196419741984199420042014202420342044205420642074208420942104211421242134214421542164217421842194220422142224223422442254226422742284229423042314232423342344235423642374238423942404241424242434244424542464247424842494250425142524253425442554256425742584259426042614262426342644265426642674268426942704271427242734274427542764277427842794280428142824283428442854286428742884289429042914292429342944295429642974298429943004301430243034304430543064307430843094310431143124313431443154316431743184319432043214322432343244325432643274328432943304331433243334334433543364337433843394340434143424343434443454346434743484349435043514352435343544355435643574358435943604361436243634364436543664367436843694370437143724373437443754376437743784379438043814382438343844385438643874388438943904391439243934394439543964397439843994400440144024403440444054406440744084409441044114412441344144415441644174418441944204421442244234424442544264427442844294430443144324433443444354436443744384439444044414442444344444445444644474448444944504451445244534454445544564457445844594460446144624463446444654466446744684469447044714472447344744475447644774478447944804481448244834484448544864487448844894490449144924493449444954496449744984499450045014502450345044505450645074508450945104511451245134514451545164517451845194520452145224523452445254526452745284529453045314532453345344535453645374538453945404541454245434544454545464547454845494550455145524553455445554556455745584559456045614562456345644565456645674568456945704571457245734574457545764577457845794580458145824583458445854586458745884589459045914592459345944595459645974598459946004601460246034604460546064607460846094610461146124613461446154616461746184619462046214622462346244625462646274628462946304631463246334634463546364637463846394640464146424643464446454646464746484649465046514652465346544655465646574658465946604661466246634664466546664667466846694670467146724673467446754676467746784679468046814682468346844685468646874688468946904691469246934694469546964697469846994700470147024703470447054706470747084709471047114712471347144715471647174718471947204721472247234724472547264727472847294730473147324733473447354736473747384739474047414742474347444745474647474748474947504751475247534754475547564757475847594760476147624763476447654766476747684769477047714772477347744775477647774778477947804781478247834784478547864787478847894790479147924793479447954796479747984799480048014802480348044805480648074808480948104811481248134814481548164817481848194820482148224823482448254826482748284829483048314832483348344835483648374838483948404841484248434844484548464847484848494850485148524853485448554856485748584859486048614862486348644865486648674868486948704871487248734874487548764877487848794880488148824883488448854886488748884889489048914892489348944895489648974898489949004901490249034904490549064907490849094910491149124913491449154916491749184919492049214922492349244925492649274928492949304931493249334934493549364937493849394940494149424943494449454946494749484949495049514952495349544955495649574958495949604961496249634964496549664967496849694970497149724973497449754976497749784979498049814982498349844985498649874988498949904991499249934994499549964997499849995000500150025003500450055006500750085009501050115012501350145015501650175018501950205021502250235024502550265027502850295030503150325033503450355036503750385039504050415042504350445045504650475048504950505051505250535054505550565057505850595060506150625063506450655066506750685069507050715072507350745075507650775078507950805081508250835084508550865087508850895090509150925093509450955096509750985099510051015102510351045105510651075108510951105111511251135114511551165117511851195120512151225123512451255126512751285129513051315132513351345135513651375138513951405141514251435144514551465147514851495150515151525153515451555156515751585159516051615162516351645165516651675168516951705171517251735174517551765177517851795180518151825183518451855186518751885189519051915192519351945195519651975198519952005201520252035204520552065207520852095210521152125213521452155216521752185219522052215222522352245225522652275228522952305231523252335234523552365237523852395240524152425243524452455246524752485249525052515252525352545255525652575258525952605261526252635264526552665267526852695270527152725273527452755276527752785279528052815282528352845285528652875288528952905291529252935294529552965297529852995300530153025303530453055306530753085309531053115312531353145315531653175318531953205321532253235324532553265327532853295330533153325333533453355336533753385339534053415342534353445345534653475348534953505351535253535354535553565357535853595360536153625363536453655366536753685369537053715372537353745375537653775378537953805381538253835384538553865387538853895390539153925393539453955396539753985399540054015402540354045405540654075408540954105411541254135414541554165417541854195420542154225423542454255426542754285429543054315432543354345435543654375438543954405441544254435444544554465447544854495450545154525453545454555456545754585459546054615462546354645465546654675468546954705471547254735474547554765477547854795480548154825483548454855486548754885489549054915492549354945495549654975498549955005501550255035504550555065507550855095510551155125513551455155516551755185519552055215522552355245525552655275528552955305531553255335534553555365537553855395540554155425543554455455546554755485549555055515552555355545555555655575558555955605561556255635564556555665567556855695570557155725573557455755576557755785579558055815582558355845585558655875588558955905591559255935594559555965597559855995600560156025603560456055606560756085609561056115612561356145615561656175618561956205621562256235624562556265627562856295630563156325633563456355636563756385639564056415642564356445645564656475648564956505651565256535654565556565657565856595660566156625663566456655666566756685669567056715672567356745675567656775678567956805681568256835684568556865687568856895690569156925693569456955696569756985699570057015702570357045705570657075708570957105711571257135714571557165717571857195720572157225723572457255726572757285729573057315732573357345735573657375738573957405741574257435744574557465747574857495750575157525753575457555756575757585759576057615762576357645765576657675768576957705771577257735774577557765777577857795780578157825783578457855786578757885789579057915792579357945795579657975798579958005801580258035804580558065807580858095810581158125813581458155816581758185819582058215822582358245825582658275828582958305831583258335834583558365837583858395840584158425843584458455846584758485849585058515852585358545855585658575858585958605861586258635864586558665867586858695870587158725873587458755876587758785879588058815882588358845885588658875888588958905891589258935894589558965897589858995900590159025903590459055906590759085909591059115912591359145915591659175918591959205921592259235924592559265927592859295930593159325933593459355936593759385939594059415942594359445945594659475948594959505951595259535954595559565957595859595960596159625963596459655966596759685969597059715972597359745975597659775978597959805981598259835984598559865987598859895990599159925993599459955996599759985999600060016002600360046005600660076008600960106011601260136014601560166017601860196020602160226023602460256026602760286029603060316032603360346035603660376038603960406041604260436044604560466047604860496050605160526053605460556056605760586059606060616062606360646065606660676068606960706071607260736074607560766077607860796080608160826083608460856086608760886089609060916092609360946095609660976098609961006101610261036104610561066107610861096110611161126113611461156116611761186119612061216122612361246125612661276128612961306131613261336134613561366137613861396140614161426143614461456146614761486149615061516152615361546155615661576158615961606161616261636164616561666167616861696170617161726173617461756176617761786179618061816182618361846185618661876188618961906191619261936194619561966197619861996200620162026203620462056206620762086209621062116212621362146215621662176218621962206221622262236224622562266227622862296230623162326233623462356236623762386239624062416242624362446245624662476248624962506251625262536254625562566257625862596260626162626263626462656266626762686269627062716272627362746275627662776278627962806281628262836284628562866287628862896290629162926293629462956296629762986299630063016302630363046305630663076308630963106311631263136314631563166317631863196320632163226323632463256326632763286329633063316332633363346335633663376338633963406341634263436344634563466347634863496350635163526353635463556356635763586359636063616362636363646365636663676368636963706371637263736374637563766377637863796380638163826383638463856386638763886389639063916392639363946395639663976398639964006401640264036404640564066407640864096410641164126413641464156416641764186419642064216422642364246425642664276428642964306431643264336434643564366437643864396440644164426443644464456446644764486449645064516452645364546455645664576458645964606461646264636464646564666467646864696470647164726473647464756476647764786479648064816482648364846485648664876488648964906491649264936494649564966497649864996500650165026503650465056506650765086509651065116512651365146515651665176518651965206521652265236524652565266527652865296530653165326533653465356536653765386539654065416542654365446545654665476548654965506551655265536554655565566557655865596560656165626563656465656566656765686569657065716572657365746575657665776578657965806581658265836584658565866587658865896590659165926593659465956596659765986599660066016602660366046605660666076608660966106611661266136614661566166617661866196620662166226623662466256626662766286629663066316632663366346635663666376638663966406641664266436644664566466647664866496650665166526653665466556656665766586659666066616662666366646665666666676668666966706671667266736674667566766677667866796680668166826683668466856686668766886689669066916692669366946695669666976698669967006701670267036704670567066707670867096710671167126713671467156716671767186719672067216722672367246725672667276728672967306731673267336734673567366737673867396740674167426743674467456746674767486749675067516752675367546755675667576758675967606761676267636764676567666767676867696770677167726773677467756776677767786779678067816782678367846785678667876788678967906791679267936794679567966797679867996800680168026803680468056806680768086809681068116812681368146815681668176818681968206821682268236824682568266827682868296830683168326833683468356836683768386839684068416842684368446845684668476848684968506851685268536854685568566857685868596860686168626863686468656866686768686869687068716872687368746875687668776878687968806881688268836884688568866887688868896890689168926893689468956896689768986899690069016902690369046905690669076908690969106911691269136914691569166917691869196920692169226923692469256926692769286929693069316932693369346935693669376938693969406941694269436944694569466947694869496950695169526953695469556956695769586959696069616962696369646965696669676968696969706971697269736974697569766977697869796980698169826983698469856986698769886989699069916992699369946995699669976998699970007001700270037004700570067007700870097010701170127013701470157016701770187019702070217022702370247025702670277028702970307031703270337034703570367037703870397040704170427043704470457046704770487049705070517052705370547055705670577058705970607061706270637064706570667067706870697070707170727073707470757076707770787079708070817082708370847085708670877088708970907091709270937094709570967097709870997100710171027103710471057106710771087109711071117112711371147115711671177118711971207121712271237124712571267127712871297130713171327133713471357136713771387139714071417142714371447145714671477148714971507151715271537154715571567157715871597160716171627163716471657166716771687169717071717172717371747175717671777178717971807181718271837184718571867187718871897190719171927193719471957196719771987199720072017202720372047205720672077208720972107211721272137214721572167217721872197220722172227223722472257226722772287229723072317232723372347235723672377238723972407241724272437244724572467247724872497250725172527253725472557256725772587259726072617262726372647265726672677268726972707271727272737274727572767277727872797280728172827283728472857286728772887289729072917292729372947295729672977298729973007301730273037304730573067307730873097310731173127313731473157316731773187319732073217322732373247325732673277328732973307331733273337334733573367337733873397340734173427343734473457346734773487349735073517352735373547355735673577358735973607361736273637364736573667367736873697370737173727373737473757376737773787379738073817382738373847385738673877388738973907391739273937394739573967397739873997400740174027403740474057406740774087409741074117412741374147415741674177418741974207421742274237424742574267427742874297430743174327433743474357436743774387439744074417442744374447445744674477448744974507451745274537454745574567457745874597460746174627463746474657466746774687469747074717472747374747475747674777478747974807481748274837484748574867487748874897490749174927493749474957496749774987499750075017502750375047505750675077508750975107511751275137514751575167517751875197520752175227523752475257526752775287529753075317532753375347535753675377538753975407541754275437544754575467547754875497550755175527553755475557556755775587559756075617562756375647565756675677568756975707571757275737574757575767577757875797580758175827583758475857586758775887589759075917592759375947595759675977598759976007601760276037604760576067607760876097610761176127613761476157616761776187619762076217622762376247625762676277628762976307631763276337634763576367637763876397640764176427643764476457646764776487649765076517652765376547655765676577658765976607661766276637664766576667667766876697670767176727673767476757676767776787679768076817682768376847685768676877688768976907691769276937694769576967697769876997700770177027703770477057706770777087709771077117712771377147715771677177718771977207721772277237724772577267727772877297730773177327733773477357736773777387739774077417742774377447745774677477748774977507751775277537754775577567757775877597760776177627763776477657766776777687769777077717772777377747775777677777778777977807781778277837784778577867787778877897790779177927793779477957796779777987799780078017802780378047805780678077808780978107811781278137814781578167817781878197820782178227823782478257826782778287829783078317832783378347835783678377838783978407841784278437844784578467847784878497850785178527853785478557856785778587859786078617862786378647865786678677868786978707871787278737874787578767877787878797880788178827883788478857886788778887889789078917892789378947895789678977898789979007901790279037904790579067907790879097910791179127913791479157916791779187919792079217922792379247925792679277928792979307931793279337934793579367937793879397940794179427943794479457946794779487949795079517952795379547955795679577958795979607961796279637964796579667967796879697970797179727973797479757976797779787979798079817982798379847985798679877988798979907991799279937994799579967997799879998000800180028003800480058006800780088009801080118012801380148015801680178018801980208021802280238024802580268027802880298030803180328033803480358036803780388039804080418042804380448045804680478048804980508051805280538054805580568057805880598060806180628063806480658066806780688069807080718072807380748075807680778078807980808081808280838084808580868087808880898090809180928093809480958096809780988099810081018102810381048105810681078108810981108111811281138114811581168117811881198120812181228123812481258126812781288129813081318132813381348135813681378138813981408141814281438144814581468147814881498150815181528153815481558156815781588159816081618162816381648165816681678168816981708171817281738174817581768177817881798180818181828183818481858186818781888189819081918192819381948195819681978198819982008201820282038204820582068207820882098210821182128213821482158216821782188219822082218222822382248225822682278228822982308231823282338234823582368237823882398240824182428243824482458246824782488249825082518252825382548255825682578258825982608261826282638264826582668267826882698270827182728273827482758276827782788279828082818282828382848285828682878288828982908291829282938294829582968297829882998300830183028303830483058306830783088309831083118312831383148315831683178318831983208321832283238324832583268327832883298330833183328333833483358336833783388339834083418342834383448345834683478348834983508351835283538354835583568357835883598360836183628363836483658366836783688369837083718372837383748375837683778378837983808381838283838384838583868387838883898390839183928393839483958396839783988399840084018402840384048405840684078408840984108411841284138414841584168417841884198420842184228423842484258426842784288429843084318432843384348435843684378438843984408441844284438444844584468447844884498450845184528453845484558456845784588459846084618462846384648465846684678468846984708471847284738474847584768477847884798480848184828483848484858486848784888489849084918492849384948495849684978498849985008501850285038504850585068507850885098510851185128513851485158516851785188519852085218522852385248525852685278528852985308531853285338534853585368537853885398540854185428543854485458546854785488549855085518552855385548555855685578558855985608561856285638564856585668567856885698570857185728573857485758576857785788579858085818582858385848585858685878588858985908591859285938594859585968597859885998600860186028603860486058606860786088609861086118612861386148615861686178618861986208621862286238624862586268627862886298630863186328633863486358636863786388639864086418642864386448645864686478648864986508651865286538654865586568657865886598660866186628663866486658666866786688669867086718672867386748675867686778678867986808681868286838684868586868687868886898690869186928693869486958696869786988699870087018702870387048705870687078708870987108711871287138714871587168717871887198720872187228723872487258726872787288729873087318732873387348735873687378738873987408741874287438744874587468747874887498750875187528753875487558756875787588759876087618762876387648765876687678768876987708771877287738774877587768777877887798780878187828783878487858786878787888789879087918792879387948795879687978798879988008801880288038804880588068807880888098810881188128813881488158816881788188819882088218822882388248825882688278828882988308831883288338834883588368837883888398840884188428843884488458846884788488849885088518852885388548855885688578858885988608861886288638864886588668867886888698870887188728873887488758876887788788879888088818882888388848885888688878888888988908891889288938894889588968897889888998900890189028903890489058906890789088909891089118912891389148915891689178918891989208921892289238924892589268927892889298930893189328933893489358936893789388939894089418942894389448945894689478948894989508951895289538954895589568957895889598960896189628963896489658966896789688969897089718972897389748975897689778978897989808981898289838984898589868987898889898990899189928993899489958996899789988999900090019002900390049005900690079008900990109011901290139014901590169017901890199020902190229023902490259026902790289029903090319032903390349035903690379038903990409041904290439044904590469047904890499050905190529053905490559056905790589059906090619062906390649065906690679068906990709071907290739074907590769077907890799080908190829083908490859086908790889089909090919092909390949095909690979098909991009101910291039104910591069107910891099110911191129113911491159116911791189119912091219122912391249125912691279128912991309131913291339134913591369137913891399140914191429143914491459146914791489149915091519152915391549155915691579158915991609161916291639164916591669167916891699170917191729173917491759176917791789179918091819182918391849185918691879188918991909191919291939194919591969197919891999200920192029203920492059206920792089209921092119212921392149215921692179218921992209221922292239224922592269227922892299230923192329233923492359236923792389239924092419242924392449245924692479248924992509251925292539254925592569257925892599260926192629263926492659266926792689269927092719272927392749275927692779278927992809281928292839284928592869287928892899290929192929293929492959296929792989299930093019302930393049305930693079308930993109311931293139314931593169317931893199320932193229323932493259326932793289329933093319332933393349335933693379338933993409341934293439344934593469347934893499350935193529353935493559356935793589359936093619362936393649365936693679368936993709371937293739374937593769377937893799380938193829383938493859386938793889389939093919392939393949395939693979398939994009401940294039404940594069407940894099410941194129413941494159416941794189419942094219422942394249425942694279428942994309431943294339434943594369437943894399440944194429443944494459446944794489449945094519452945394549455945694579458945994609461946294639464946594669467946894699470947194729473947494759476947794789479948094819482948394849485948694879488948994909491949294939494949594969497949894999500950195029503950495059506950795089509951095119512951395149515951695179518951995209521952295239524952595269527952895299530953195329533953495359536953795389539954095419542954395449545954695479548954995509551955295539554955595569557955895599560956195629563956495659566956795689569957095719572957395749575957695779578957995809581958295839584958595869587958895899590959195929593959495959596959795989599960096019602960396049605960696079608960996109611961296139614961596169617961896199620962196229623962496259626962796289629963096319632963396349635963696379638963996409641964296439644964596469647964896499650965196529653965496559656965796589659966096619662966396649665966696679668966996709671967296739674967596769677967896799680968196829683968496859686968796889689969096919692969396949695969696979698969997009701970297039704970597069707970897099710971197129713971497159716971797189719972097219722972397249725972697279728972997309731973297339734973597369737973897399740974197429743974497459746974797489749975097519752975397549755975697579758975997609761976297639764976597669767976897699770977197729773977497759776977797789779978097819782978397849785978697879788978997909791979297939794979597969797979897999800980198029803980498059806980798089809981098119812981398149815981698179818981998209821982298239824982598269827982898299830983198329833983498359836983798389839984098419842984398449845984698479848984998509851985298539854985598569857985898599860986198629863986498659866986798689869987098719872987398749875987698779878987998809881988298839884988598869887988898899890989198929893989498959896989798989899990099019902990399049905990699079908990999109911991299139914991599169917991899199920992199229923992499259926992799289929993099319932993399349935993699379938993999409941994299439944994599469947994899499950995199529953995499559956995799589959996099619962996399649965996699679968996999709971997299739974997599769977997899799980998199829983998499859986998799889989999099919992999399949995999699979998999910000100011000210003100041000510006100071000810009100101001110012100131001410015100161001710018100191002010021100221002310024100251002610027100281002910030100311003210033100341003510036100371003810039100401004110042100431004410045100461004710048100491005010051100521005310054100551005610057100581005910060100611006210063100641006510066100671006810069100701007110072100731007410075100761007710078100791008010081100821008310084100851008610087100881008910090100911009210093100941009510096100971009810099101001010110102101031010410105101061010710108101091011010111101121011310114101151011610117101181011910120101211012210123101241012510126101271012810129101301013110132101331013410135101361013710138101391014010141101421014310144101451014610147101481014910150101511015210153101541015510156101571015810159101601016110162101631016410165101661016710168101691017010171101721017310174101751017610177101781017910180101811018210183101841018510186101871018810189101901019110192101931019410195101961019710198101991020010201102021020310204102051020610207102081020910210102111021210213102141021510216102171021810219102201022110222102231022410225102261022710228102291023010231102321023310234102351023610237102381023910240102411024210243102441024510246102471024810249102501025110252102531025410255102561025710258102591026010261102621026310264102651026610267102681026910270102711027210273102741027510276102771027810279102801028110282102831028410285102861028710288102891029010291102921029310294102951029610297102981029910300103011030210303103041030510306103071030810309103101031110312103131031410315103161031710318103191032010321103221032310324103251032610327103281032910330103311033210333103341033510336103371033810339103401034110342103431034410345103461034710348103491035010351103521035310354103551035610357103581035910360103611036210363103641036510366103671036810369103701037110372103731037410375103761037710378103791038010381103821038310384103851038610387103881038910390103911039210393103941039510396103971039810399104001040110402104031040410405104061040710408104091041010411104121041310414104151041610417104181041910420104211042210423104241042510426104271042810429104301043110432104331043410435104361043710438104391044010441104421044310444104451044610447104481044910450104511045210453104541045510456104571045810459104601046110462104631046410465104661046710468104691047010471104721047310474104751047610477104781047910480104811048210483104841048510486104871048810489104901049110492104931049410495104961049710498104991050010501105021050310504105051050610507105081050910510105111051210513105141051510516105171051810519105201052110522105231052410525105261052710528105291053010531105321053310534105351053610537105381053910540105411054210543105441054510546105471054810549105501055110552105531055410555105561055710558105591056010561105621056310564105651056610567105681056910570105711057210573105741057510576105771057810579105801058110582105831058410585105861058710588105891059010591105921059310594105951059610597105981059910600106011060210603106041060510606106071060810609106101061110612106131061410615106161061710618106191062010621106221062310624106251062610627106281062910630106311063210633106341063510636106371063810639106401064110642106431064410645106461064710648106491065010651106521065310654106551065610657106581065910660106611066210663106641066510666106671066810669106701067110672106731067410675106761067710678106791068010681106821068310684106851068610687106881068910690106911069210693106941069510696106971069810699107001070110702107031070410705107061070710708107091071010711107121071310714107151071610717107181071910720107211072210723107241072510726107271072810729107301073110732107331073410735107361073710738107391074010741107421074310744107451074610747107481074910750107511075210753107541075510756107571075810759107601076110762107631076410765107661076710768107691077010771107721077310774107751077610777107781077910780107811078210783107841078510786107871078810789107901079110792107931079410795107961079710798107991080010801108021080310804108051080610807108081080910810108111081210813108141081510816108171081810819108201082110822108231082410825108261082710828108291083010831108321083310834108351083610837108381083910840108411084210843108441084510846108471084810849108501085110852108531085410855108561085710858108591086010861108621086310864108651086610867108681086910870108711087210873108741087510876108771087810879108801088110882108831088410885108861088710888108891089010891108921089310894108951089610897108981089910900109011090210903109041090510906109071090810909109101091110912109131091410915109161091710918109191092010921109221092310924109251092610927109281092910930109311093210933109341093510936109371093810939109401094110942109431094410945109461094710948109491095010951109521095310954109551095610957109581095910960109611096210963109641096510966109671096810969109701097110972109731097410975109761097710978109791098010981109821098310984109851098610987109881098910990109911099210993109941099510996109971099810999110001100111002110031100411005110061100711008110091101011011110121101311014110151101611017110181101911020110211102211023110241102511026110271102811029110301103111032110331103411035110361103711038110391104011041110421104311044110451104611047110481104911050110511105211053110541105511056110571105811059110601106111062110631106411065110661106711068110691107011071110721107311074110751107611077110781107911080110811108211083110841108511086110871108811089110901109111092110931109411095110961109711098110991110011101111021110311104111051110611107111081110911110111111111211113111141111511116111171111811119111201112111122111231112411125111261112711128111291113011131111321113311134111351113611137111381113911140111411114211143111441114511146111471114811149111501115111152111531115411155111561115711158111591116011161111621116311164111651116611167111681116911170111711117211173111741117511176111771117811179111801118111182111831118411185111861118711188111891119011191111921119311194111951119611197111981119911200112011120211203112041120511206112071120811209112101121111212112131121411215112161121711218112191122011221112221122311224112251122611227112281122911230112311123211233112341123511236112371123811239112401124111242112431124411245112461124711248112491125011251112521125311254112551125611257112581125911260112611126211263112641126511266112671126811269112701127111272112731127411275112761127711278112791128011281112821128311284112851128611287112881128911290112911129211293112941129511296112971129811299113001130111302113031130411305113061130711308113091131011311113121131311314113151131611317113181131911320113211132211323113241132511326113271132811329113301133111332113331133411335113361133711338113391134011341113421134311344113451134611347113481134911350113511135211353113541135511356113571135811359113601136111362113631136411365113661136711368113691137011371113721137311374113751137611377113781137911380113811138211383113841138511386113871138811389113901139111392113931139411395113961139711398113991140011401114021140311404114051140611407114081140911410114111141211413114141141511416114171141811419114201142111422114231142411425114261142711428114291143011431114321143311434114351143611437114381143911440114411144211443114441144511446114471144811449114501145111452114531145411455114561145711458114591146011461114621146311464114651146611467114681146911470114711147211473114741147511476114771147811479114801148111482114831148411485114861148711488114891149011491114921149311494114951149611497114981149911500115011150211503115041150511506115071150811509115101151111512115131151411515115161151711518115191152011521115221152311524115251152611527115281152911530115311153211533115341153511536115371153811539115401154111542115431154411545115461154711548115491155011551115521155311554115551155611557115581155911560115611156211563115641156511566115671156811569115701157111572115731157411575115761157711578115791158011581115821158311584115851158611587115881158911590115911159211593115941159511596115971159811599116001160111602116031160411605116061160711608116091161011611116121161311614116151161611617116181161911620116211162211623116241162511626116271162811629116301163111632116331163411635116361163711638116391164011641116421164311644116451164611647116481164911650116511165211653116541165511656116571165811659116601166111662116631166411665116661166711668116691167011671116721167311674116751167611677116781167911680116811168211683116841168511686116871168811689116901169111692116931169411695116961169711698116991170011701117021170311704117051170611707117081170911710117111171211713117141171511716117171171811719117201172111722117231172411725117261172711728117291173011731117321173311734117351173611737117381173911740117411174211743117441174511746117471174811749117501175111752117531175411755117561175711758117591176011761117621176311764117651176611767117681176911770117711177211773117741177511776117771177811779117801178111782117831178411785117861178711788117891179011791117921179311794117951179611797117981179911800118011180211803118041180511806118071180811809118101181111812118131181411815118161181711818118191182011821118221182311824118251182611827118281182911830118311183211833118341183511836118371183811839118401184111842118431184411845118461184711848118491185011851118521185311854118551185611857118581185911860118611186211863118641186511866118671186811869118701187111872118731187411875118761187711878118791188011881118821188311884118851188611887118881188911890118911189211893118941189511896118971189811899119001190111902119031190411905119061190711908119091191011911119121191311914119151191611917119181191911920119211192211923119241192511926119271192811929119301193111932119331193411935119361193711938119391194011941119421194311944119451194611947119481194911950119511195211953119541195511956119571195811959119601196111962119631196411965119661196711968119691197011971119721197311974119751197611977119781197911980119811198211983119841198511986119871198811989119901199111992119931199411995119961199711998119991200012001120021200312004120051200612007120081200912010120111201212013120141201512016120171201812019120201202112022120231202412025120261202712028120291203012031120321203312034120351203612037120381203912040120411204212043120441204512046120471204812049120501205112052120531205412055120561205712058120591206012061120621206312064120651206612067120681206912070120711207212073120741207512076120771207812079120801208112082120831208412085120861208712088120891209012091120921209312094120951209612097120981209912100121011210212103121041210512106121071210812109121101211112112121131211412115121161211712118121191212012121121221212312124121251212612127121281212912130121311213212133121341213512136121371213812139121401214112142121431214412145121461214712148121491215012151121521215312154121551215612157121581215912160121611216212163121641216512166121671216812169121701217112172121731217412175121761217712178121791218012181121821218312184121851218612187121881218912190121911219212193121941219512196121971219812199122001220112202122031220412205122061220712208122091221012211122121221312214122151221612217122181221912220122211222212223122241222512226122271222812229122301223112232122331223412235122361223712238122391224012241122421224312244122451224612247122481224912250122511225212253122541225512256122571225812259122601226112262122631226412265122661226712268122691227012271122721227312274122751227612277122781227912280122811228212283122841228512286122871228812289122901229112292122931229412295122961229712298122991230012301123021230312304123051230612307123081230912310123111231212313123141231512316123171231812319123201232112322123231232412325123261232712328123291233012331123321233312334123351233612337123381233912340123411234212343123441234512346123471234812349123501235112352123531235412355123561235712358123591236012361123621236312364123651236612367123681236912370123711237212373123741237512376123771237812379123801238112382123831238412385123861238712388123891239012391123921239312394123951239612397123981239912400124011240212403124041240512406124071240812409124101241112412124131241412415124161241712418124191242012421124221242312424124251242612427124281242912430124311243212433124341243512436124371243812439124401244112442124431244412445124461244712448124491245012451124521245312454124551245612457124581245912460124611246212463124641246512466124671246812469124701247112472124731247412475124761247712478124791248012481124821248312484124851248612487124881248912490124911249212493124941249512496124971249812499125001250112502125031250412505125061250712508125091251012511125121251312514125151251612517125181251912520125211252212523125241252512526125271252812529125301253112532125331253412535125361253712538125391254012541125421254312544125451254612547125481254912550125511255212553125541255512556125571255812559125601256112562125631256412565125661256712568125691257012571125721257312574125751257612577125781257912580125811258212583125841258512586125871258812589125901259112592125931259412595125961259712598125991260012601126021260312604126051260612607126081260912610126111261212613126141261512616126171261812619126201262112622126231262412625126261262712628126291263012631126321263312634126351263612637126381263912640126411264212643126441264512646126471264812649126501265112652126531265412655126561265712658126591266012661126621266312664126651266612667126681266912670126711267212673126741267512676126771267812679126801268112682126831268412685126861268712688126891269012691126921269312694126951269612697126981269912700127011270212703127041270512706127071270812709127101271112712127131271412715127161271712718127191272012721127221272312724127251272612727127281272912730127311273212733127341273512736127371273812739127401274112742127431274412745127461274712748127491275012751127521275312754127551275612757127581275912760127611276212763127641276512766127671276812769127701277112772127731277412775127761277712778127791278012781127821278312784127851278612787127881278912790127911279212793127941279512796127971279812799128001280112802128031280412805128061280712808128091281012811128121281312814128151281612817128181281912820128211282212823128241282512826128271282812829128301283112832128331283412835128361283712838128391284012841128421284312844128451284612847128481284912850128511285212853128541285512856128571285812859128601286112862128631286412865128661286712868128691287012871128721287312874128751287612877128781287912880128811288212883128841288512886128871288812889128901289112892128931289412895128961289712898128991290012901129021290312904129051290612907129081290912910129111291212913129141291512916129171291812919129201292112922129231292412925129261292712928129291293012931129321293312934129351293612937129381293912940129411294212943129441294512946129471294812949129501295112952129531295412955129561295712958129591296012961129621296312964129651296612967129681296912970129711297212973129741297512976129771297812979129801298112982129831298412985129861298712988129891299012991129921299312994129951299612997129981299913000130011300213003130041300513006130071300813009130101301113012130131301413015130161301713018130191302013021130221302313024130251302613027130281302913030130311303213033130341303513036130371303813039130401304113042130431304413045130461304713048130491305013051130521305313054130551305613057130581305913060130611306213063130641306513066130671306813069130701307113072130731307413075130761307713078130791308013081130821308313084130851308613087130881308913090130911309213093130941309513096130971309813099131001310113102131031310413105131061310713108131091311013111131121311313114131151311613117131181311913120131211312213123131241312513126131271312813129131301313113132131331313413135131361313713138131391314013141131421314313144131451314613147131481314913150131511315213153131541315513156131571315813159131601316113162131631316413165131661316713168131691317013171131721317313174131751317613177131781317913180131811318213183131841318513186131871318813189131901319113192131931319413195131961319713198131991320013201132021320313204132051320613207132081320913210132111321213213132141321513216132171321813219132201322113222132231322413225132261322713228132291323013231132321323313234132351323613237132381323913240132411324213243132441324513246132471324813249132501325113252132531325413255132561325713258132591326013261132621326313264132651326613267132681326913270132711327213273132741327513276132771327813279132801328113282132831328413285132861328713288132891329013291132921329313294132951329613297132981329913300133011330213303133041330513306133071330813309133101331113312133131331413315133161331713318133191332013321133221332313324133251332613327133281332913330133311333213333133341333513336133371333813339133401334113342133431334413345133461334713348133491335013351133521335313354133551335613357133581335913360133611336213363133641336513366133671336813369133701337113372133731337413375133761337713378133791338013381133821338313384133851338613387133881338913390133911339213393133941339513396133971339813399134001340113402134031340413405134061340713408134091341013411134121341313414134151341613417134181341913420134211342213423134241342513426134271342813429134301343113432134331343413435134361343713438134391344013441134421344313444134451344613447134481344913450134511345213453134541345513456134571345813459134601346113462134631346413465134661346713468134691347013471134721347313474134751347613477134781347913480134811348213483134841348513486134871348813489134901349113492134931349413495134961349713498134991350013501135021350313504135051350613507135081350913510135111351213513135141351513516135171351813519135201352113522135231352413525135261352713528135291353013531135321353313534135351353613537135381353913540135411354213543135441354513546135471354813549135501355113552135531355413555135561355713558135591356013561135621356313564135651356613567135681356913570135711357213573135741357513576135771357813579135801358113582135831358413585135861358713588135891359013591135921359313594135951359613597135981359913600136011360213603136041360513606136071360813609136101361113612136131361413615136161361713618136191362013621136221362313624136251362613627136281362913630136311363213633136341363513636136371363813639136401364113642136431364413645136461364713648136491365013651136521365313654136551365613657136581365913660136611366213663136641366513666136671366813669136701367113672136731367413675136761367713678136791368013681136821368313684136851368613687136881368913690136911369213693136941369513696136971369813699137001370113702137031370413705137061370713708137091371013711137121371313714137151371613717137181371913720137211372213723137241372513726137271372813729137301373113732137331373413735137361373713738137391374013741137421374313744137451374613747137481374913750137511375213753137541375513756137571375813759137601376113762137631376413765137661376713768137691377013771137721377313774137751377613777137781377913780137811378213783137841378513786137871378813789137901379113792137931379413795137961379713798137991380013801138021380313804138051380613807138081380913810138111381213813138141381513816138171381813819138201382113822138231382413825138261382713828138291383013831138321383313834138351383613837138381383913840138411384213843138441384513846138471384813849138501385113852138531385413855138561385713858138591386013861138621386313864138651386613867138681386913870138711387213873138741387513876138771387813879138801388113882138831388413885138861388713888138891389013891138921389313894138951389613897138981389913900139011390213903139041390513906139071390813909139101391113912139131391413915139161391713918139191392013921139221392313924139251392613927139281392913930139311393213933139341393513936139371393813939139401394113942139431394413945139461394713948139491395013951139521395313954139551395613957139581395913960139611396213963139641396513966139671396813969139701397113972139731397413975139761397713978139791398013981139821398313984139851398613987139881398913990139911399213993139941399513996139971399813999140001400114002140031400414005140061400714008140091401014011140121401314014140151401614017140181401914020140211402214023140241402514026140271402814029140301403114032140331403414035140361403714038140391404014041140421404314044140451404614047140481404914050140511405214053140541405514056140571405814059140601406114062140631406414065140661406714068140691407014071140721407314074140751407614077140781407914080140811408214083140841408514086140871408814089140901409114092140931409414095140961409714098140991410014101141021410314104141051410614107141081410914110141111411214113141141411514116141171411814119141201412114122141231412414125141261412714128141291413014131141321413314134141351413614137141381413914140141411414214143141441414514146141471414814149141501415114152141531415414155141561415714158141591416014161141621416314164141651416614167141681416914170141711417214173141741417514176141771417814179141801418114182141831418414185141861418714188141891419014191141921419314194141951419614197141981419914200142011420214203142041420514206142071420814209142101421114212142131421414215142161421714218142191422014221142221422314224142251422614227142281422914230142311423214233142341423514236142371423814239142401424114242142431424414245142461424714248142491425014251142521425314254142551425614257142581425914260142611426214263142641426514266142671426814269142701427114272142731427414275142761427714278142791428014281142821428314284142851428614287142881428914290142911429214293142941429514296142971429814299143001430114302143031430414305143061430714308143091431014311143121431314314143151431614317143181431914320143211432214323143241432514326143271432814329143301433114332143331433414335143361433714338143391434014341143421434314344143451434614347143481434914350143511435214353143541435514356143571435814359143601436114362143631436414365143661436714368143691437014371143721437314374143751437614377143781437914380143811438214383143841438514386143871438814389143901439114392143931439414395143961439714398143991440014401144021440314404144051440614407144081440914410144111441214413144141441514416144171441814419144201442114422144231442414425144261442714428144291443014431144321443314434144351443614437144381443914440144411444214443144441444514446144471444814449144501445114452144531445414455144561445714458144591446014461144621446314464144651446614467144681446914470144711447214473144741447514476144771447814479144801448114482144831448414485144861448714488144891449014491144921449314494144951449614497144981449914500145011450214503145041450514506145071450814509145101451114512145131451414515145161451714518145191452014521145221452314524145251452614527145281452914530145311453214533145341453514536145371453814539145401454114542145431454414545145461454714548145491455014551145521455314554145551455614557145581455914560145611456214563145641456514566145671456814569145701457114572145731457414575145761457714578145791458014581145821458314584145851458614587145881458914590145911459214593145941459514596145971459814599146001460114602146031460414605146061460714608146091461014611146121461314614146151461614617146181461914620146211462214623146241462514626146271462814629146301463114632146331463414635146361463714638146391464014641146421464314644146451464614647146481464914650146511465214653146541465514656146571465814659146601466114662146631466414665146661466714668146691467014671146721467314674146751467614677146781467914680146811468214683146841468514686146871468814689146901469114692146931469414695146961469714698146991470014701147021470314704147051470614707147081470914710147111471214713147141471514716147171471814719147201472114722147231472414725147261472714728147291473014731147321473314734147351473614737147381473914740147411474214743147441474514746147471474814749147501475114752147531475414755147561475714758147591476014761147621476314764147651476614767147681476914770147711477214773147741477514776147771477814779147801478114782147831478414785147861478714788147891479014791147921479314794147951479614797147981479914800148011480214803148041480514806148071480814809148101481114812148131481414815148161481714818148191482014821148221482314824148251482614827148281482914830148311483214833148341483514836148371483814839148401484114842148431484414845148461484714848148491485014851148521485314854148551485614857148581485914860148611486214863148641486514866148671486814869148701487114872148731487414875148761487714878148791488014881148821488314884148851488614887148881488914890148911489214893148941489514896148971489814899149001490114902149031490414905149061490714908149091491014911149121491314914149151491614917149181491914920149211492214923149241492514926149271492814929149301493114932149331493414935149361493714938149391494014941149421494314944149451494614947149481494914950149511495214953149541495514956149571495814959149601496114962149631496414965149661496714968149691497014971149721497314974149751497614977149781497914980149811498214983149841498514986149871498814989149901499114992149931499414995149961499714998149991500015001150021500315004150051500615007150081500915010150111501215013150141501515016150171501815019150201502115022150231502415025150261502715028150291503015031150321503315034150351503615037150381503915040150411504215043150441504515046150471504815049150501505115052150531505415055150561505715058150591506015061150621506315064150651506615067150681506915070150711507215073150741507515076150771507815079150801508115082150831508415085150861508715088150891509015091150921509315094150951509615097150981509915100151011510215103151041510515106151071510815109151101511115112151131511415115151161511715118151191512015121151221512315124151251512615127151281512915130151311513215133151341513515136151371513815139151401514115142151431514415145151461514715148151491515015151151521515315154151551515615157151581515915160151611516215163151641516515166151671516815169151701517115172151731517415175151761517715178151791518015181151821518315184151851518615187151881518915190151911519215193151941519515196151971519815199152001520115202152031520415205152061520715208152091521015211152121521315214152151521615217152181521915220152211522215223152241522515226152271522815229152301523115232152331523415235152361523715238152391524015241152421524315244152451524615247152481524915250152511525215253152541525515256152571525815259152601526115262152631526415265152661526715268152691527015271152721527315274152751527615277152781527915280152811528215283152841528515286152871528815289152901529115292152931529415295152961529715298152991530015301153021530315304153051530615307153081530915310153111531215313153141531515316153171531815319153201532115322153231532415325153261532715328153291533015331153321533315334153351533615337153381533915340153411534215343153441534515346153471534815349153501535115352153531535415355153561535715358153591536015361153621536315364153651536615367153681536915370153711537215373153741537515376153771537815379153801538115382153831538415385153861538715388153891539015391153921539315394153951539615397153981539915400154011540215403154041540515406154071540815409154101541115412154131541415415154161541715418154191542015421154221542315424154251542615427154281542915430154311543215433154341543515436154371543815439154401544115442154431544415445154461544715448154491545015451154521545315454154551545615457154581545915460154611546215463154641546515466154671546815469154701547115472154731547415475154761547715478154791548015481154821548315484154851548615487154881548915490154911549215493154941549515496154971549815499155001550115502155031550415505155061550715508155091551015511155121551315514155151551615517155181551915520155211552215523155241552515526155271552815529155301553115532155331553415535155361553715538155391554015541155421554315544155451554615547155481554915550155511555215553155541555515556155571555815559155601556115562 |
- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
- <html>
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
- <title>Functions: </title>
- <meta name="generator" content="DocBook XSL Stylesheets V1.79.2">
- <link rel="home" href="index.html" title="">
- <link rel="up" href="ch01.html" title="GLib">
- <link rel="prev" href="re88.html" title="<GVariantType>">
- <meta name="generator" content="GTK-Doc V1.33.1 (XML mode)">
- <link rel="stylesheet" href="style.css" type="text/css">
- </head>
- <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
- <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
- <td width="100%" align="left" class="shortcuts"></td>
- <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
- <td><img src="up-insensitive.png" width="16" height="16" border="0"></td>
- <td><a accesskey="p" href="re88.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
- <td><img src="right-insensitive.png" width="16" height="16" border="0"></td>
- </tr></table>
- <div class="refentry">
- <a name="id-1.1.90"></a><div class="titlepage"></div>
- <div class="refnamediv">
- <h2>Functions</h2>
- <p>Functions</p>
- </div>
- <div class="refsect1">
- <a name="id-1.1.90.2"></a><h2>Functions</h2>
- <div class="refsect2">
- <a name="id-1.1.90.2.2"></a><h3>byte-array:free</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (byte-array:free array free-segment))
- </pre></div>
- <p>Undocumented</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.2.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>free_segment</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">free-segment</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>array</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">array</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>mem</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">mem</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.3"></a><h3>access</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (access filename mode))
- </pre></div>
- <p>A wrapper for the POSIX <code class="function">access()</code> function. This function is used to
- test a pathname for one or several of read, write or execute
- permissions, or just existence.
- </p>
- <p>On Windows, the file protection mechanism is not at all POSIX-like,
- and the underlying function in the C library only checks the
- FAT-style READONLY attribute, and does not look at the ACL of a
- file at all. This function is this in practise almost useless on
- Windows. Software that needs to handle file permissions on Windows
- more exactly should use the Win32 API.
- </p>
- <p>See your C library manual for more details about <code class="function">access()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.3.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>filename</p></td>
- <td class="parameter_description">
- <p>a pathname in the GLib file name encoding
- (UTF-8 on Windows)</p>
- <p>Passed as <code class="code">filename</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>mode</p></td>
- <td class="parameter_description">
- <p>as in <code class="function">access()</code></p>
- <p>Passed as <code class="code">mode</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.4"></a><h3>ascii-digit-value</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (ascii-digit-value c))
- </pre></div>
- <p>Determines the numeric value of a character as a decimal digit.
- Differs from <code class="function">g_unichar_digit_value()</code> because it takes a char, so
- there's no worry about sign extension if characters are signed.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.4.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>an ASCII character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.5"></a><h3>ascii-dtostr</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (ascii-dtostr buffer buf-len d))
- </pre></div>
- <p>Converts a <span class="type">gdouble</span> to a string, using the '.' as
- decimal point.
- </p>
- <p>This function generates enough precision that converting
- the string back using <code class="function">g_ascii_strtod()</code> gives the same machine-number
- (on machines with IEEE compatible 64bit doubles). It is
- guaranteed that the size of the resulting string will never
- be larger than <em class="parameter"><code>G_ASCII_DTOSTR_BUF_SIZE</code></em> bytes, including the terminating
- nul character, which is always added.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.5.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>buffer</p></td>
- <td class="parameter_description">
- <p>A buffer to place the resulting string in</p>
- <p>Passed as <code class="code">buffer</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>buf_len</p></td>
- <td class="parameter_description">
- <p>The length of the buffer.</p>
- <p>Passed as <code class="code">buf-len</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>d</p></td>
- <td class="parameter_description">
- <p>The <span class="type">gdouble</span> to convert</p>
- <p>Passed as <code class="code">d</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.6"></a><h3>ascii-formatd</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (ascii-formatd buffer buf-len format d))
- </pre></div>
- <p>Converts a <span class="type">gdouble</span> to a string, using the '.' as
- decimal point. To format the number you pass in
- a <code class="function">printf()</code>-style format string. Allowed conversion
- specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'.
- </p>
- <p>The returned buffer is guaranteed to be nul-terminated.
- </p>
- <p>If you just want to want to serialize the value into a
- string, use <code class="function">g_ascii_dtostr()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.6.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>buffer</p></td>
- <td class="parameter_description">
- <p>A buffer to place the resulting string in</p>
- <p>Passed as <code class="code">buffer</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>buf_len</p></td>
- <td class="parameter_description">
- <p>The length of the buffer.</p>
- <p>Passed as <code class="code">buf-len</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>format</p></td>
- <td class="parameter_description">
- <p>The <code class="function">printf()</code>-style format to use for the
- code to use for converting.</p>
- <p>Passed as <code class="code">format</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>d</p></td>
- <td class="parameter_description">
- <p>The <span class="type">gdouble</span> to convert</p>
- <p>Passed as <code class="code">d</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.7"></a><h3>ascii-strcasecmp</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (ascii-strcasecmp s1 s2))
- </pre></div>
- <p>Compare two strings, ignoring the case of ASCII characters.
- </p>
- <p>Unlike the BSD <code class="function">strcasecmp()</code> function, this only recognizes standard
- ASCII letters and ignores the locale, treating all non-ASCII
- bytes as if they are not letters.
- </p>
- <p>This function should be used only on strings that are known to be
- in encodings where the bytes corresponding to ASCII letters always
- represent themselves. This includes UTF-8 and the ISO-8859-*
- charsets, but not for instance double-byte encodings like the
- Windows Codepage 932, where the trailing bytes of double-byte
- characters include all ASCII letters. If you compare two CP932
- strings using this function, you will get false matches.
- </p>
- <p>Both <em class="parameter"><code>s1</code></em> and <em class="parameter"><code>s2</code></em> must be non-<code class="constant">NULL</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.7.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>s1</p></td>
- <td class="parameter_description">
- <p>string to compare with <em class="parameter"><code>s2</code></em></p>
- <p>Passed as <code class="code">s1</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>s2</p></td>
- <td class="parameter_description">
- <p>string to compare with <em class="parameter"><code>s1</code></em></p>
- <p>Passed as <code class="code">s2</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.8"></a><h3>ascii-strdown</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (ascii-strdown str len))
- </pre></div>
- <p>Converts all upper case ASCII letters to lower case ASCII letters.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.8.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>length of <em class="parameter"><code>str</code></em> in bytes, or -1 if <em class="parameter"><code>str</code></em> is nul-terminated</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.9"></a><h3>ascii-string-to-signed</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return out-num) (ascii-string-to-signed str base min max))
- </pre></div>
- <p>A convenience function for converting a string to a signed number.
- </p>
- <p>This function assumes that <em class="parameter"><code>str</code></em> contains only a number of the given
- <em class="parameter"><code>base</code></em> that is within inclusive bounds limited by <em class="parameter"><code>min</code></em> and <em class="parameter"><code>max</code></em>. If
- this is true, then the converted number is stored in <em class="parameter"><code>out_num</code></em>. An
- empty string is not a valid input. A string with leading or
- trailing whitespace is also an invalid input.
- </p>
- <p><em class="parameter"><code>base</code></em> can be between 2 and 36 inclusive. Hexadecimal numbers must
- not be prefixed with "0x" or "0X". Such a problem does not exist
- for octal numbers, since they were usually prefixed with a zero
- which does not change the value of the parsed number.
- </p>
- <p>Parsing failures result in an error with the <code class="constant">G_NUMBER_PARSER_ERROR</code>
- domain. If the input is invalid, the error code will be
- <code class="constant">G_NUMBER_PARSER_ERROR_INVALID</code>. If the parsed number is out of
- bounds - <code class="constant">G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS</code>.
- </p>
- <p>See <code class="function">g_ascii_strtoll()</code> if you have more complex needs such as
- parsing a string which starts with a number, but then has other
- characters.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.9.8"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>base</p></td>
- <td class="parameter_description">
- <p>base of a parsed number</p>
- <p>Passed as <code class="code">base</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>min</p></td>
- <td class="parameter_description">
- <p>a lower bound (inclusive)</p>
- <p>Passed as <code class="code">min</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>max</p></td>
- <td class="parameter_description">
- <p>an upper bound (inclusive)</p>
- <p>Passed as <code class="code">max</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>out_num</p></td>
- <td class="parameter_description">
- <p>a return location for a number</p>
- <p>Passed as <code class="code">out-num</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.10"></a><h3>ascii-string-to-unsigned</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return out-num) (ascii-string-to-unsigned str base min max))
- </pre></div>
- <p>A convenience function for converting a string to an unsigned number.
- </p>
- <p>This function assumes that <em class="parameter"><code>str</code></em> contains only a number of the given
- <em class="parameter"><code>base</code></em> that is within inclusive bounds limited by <em class="parameter"><code>min</code></em> and <em class="parameter"><code>max</code></em>. If
- this is true, then the converted number is stored in <em class="parameter"><code>out_num</code></em>. An
- empty string is not a valid input. A string with leading or
- trailing whitespace is also an invalid input. A string with a leading sign
- (<code class="code">-</code> or <code class="code">+</code>) is not a valid input for the unsigned parser.
- </p>
- <p><em class="parameter"><code>base</code></em> can be between 2 and 36 inclusive. Hexadecimal numbers must
- not be prefixed with "0x" or "0X". Such a problem does not exist
- for octal numbers, since they were usually prefixed with a zero
- which does not change the value of the parsed number.
- </p>
- <p>Parsing failures result in an error with the <code class="constant">G_NUMBER_PARSER_ERROR</code>
- domain. If the input is invalid, the error code will be
- <code class="constant">G_NUMBER_PARSER_ERROR_INVALID</code>. If the parsed number is out of
- bounds - <code class="constant">G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS</code>.
- </p>
- <p>See <code class="function">g_ascii_strtoull()</code> if you have more complex needs such as
- parsing a string which starts with a number, but then has other
- characters.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.10.8"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>base</p></td>
- <td class="parameter_description">
- <p>base of a parsed number</p>
- <p>Passed as <code class="code">base</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>min</p></td>
- <td class="parameter_description">
- <p>a lower bound (inclusive)</p>
- <p>Passed as <code class="code">min</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>max</p></td>
- <td class="parameter_description">
- <p>an upper bound (inclusive)</p>
- <p>Passed as <code class="code">max</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>out_num</p></td>
- <td class="parameter_description">
- <p>a return location for a number</p>
- <p>Passed as <code class="code">out-num</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.11"></a><h3>ascii-strncasecmp</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (ascii-strncasecmp s1 s2 n))
- </pre></div>
- <p>Compare <em class="parameter"><code>s1</code></em> and <em class="parameter"><code>s2</code></em>, ignoring the case of ASCII characters and any
- characters after the first <em class="parameter"><code>n</code></em> in each string.
- </p>
- <p>Unlike the BSD <code class="function">strcasecmp()</code> function, this only recognizes standard
- ASCII letters and ignores the locale, treating all non-ASCII
- characters as if they are not letters.
- </p>
- <p>The same warning as in <code class="function">g_ascii_strcasecmp()</code> applies: Use this
- function only on strings known to be in encodings where bytes
- corresponding to ASCII letters always represent themselves.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.11.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>s1</p></td>
- <td class="parameter_description">
- <p>string to compare with <em class="parameter"><code>s2</code></em></p>
- <p>Passed as <code class="code">s1</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>s2</p></td>
- <td class="parameter_description">
- <p>string to compare with <em class="parameter"><code>s1</code></em></p>
- <p>Passed as <code class="code">s2</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>n</p></td>
- <td class="parameter_description">
- <p>number of characters to compare</p>
- <p>Passed as <code class="code">n</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.12"></a><h3>ascii-strtod</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return endptr) (ascii-strtod nptr))
- </pre></div>
- <p>Converts a string to a <span class="type">gdouble</span> value.
- </p>
- <p>This function behaves like the standard <code class="function">strtod()</code> function
- does in the C locale. It does this without actually changing
- the current locale, since that would not be thread-safe.
- A limitation of the implementation is that this function
- will still accept localized versions of infinities and NANs.
- </p>
- <p>This function is typically used when reading configuration
- files or other non-user input that should be locale independent.
- To handle input from the user you should normally use the
- locale-sensitive system <code class="function">strtod()</code> function.
- </p>
- <p>To convert from a <span class="type">gdouble</span> to a string in a locale-insensitive
- way, use <code class="function">g_ascii_dtostr()</code>.
- </p>
- <p>If the correct value would cause overflow, plus or minus <code class="constant">HUGE_VAL</code>
- is returned (according to the sign of the value), and <code class="constant">ERANGE</code> is
- stored in <code class="constant">errno</code>. If the correct value would cause underflow,
- zero is returned and <code class="constant">ERANGE</code> is stored in <code class="constant">errno</code>.
- </p>
- <p>This function resets <code class="constant">errno</code> before calling <code class="function">strtod()</code> so that
- you can reliably detect overflow and underflow.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.12.9"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>nptr</p></td>
- <td class="parameter_description">
- <p>the string to convert to a numeric value.</p>
- <p>Passed as <code class="code">nptr</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>endptr</p></td>
- <td class="parameter_description">
- <p>if non-<code class="constant">NULL</code>, it returns the
- character after the last character used in the conversion.</p>
- <p>Passed as <code class="code">endptr</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.13"></a><h3>ascii-strtoll</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return endptr) (ascii-strtoll nptr base))
- </pre></div>
- <p>Converts a string to a <span class="type">gint64</span> value.
- This function behaves like the standard <code class="function">strtoll()</code> function
- does in the C locale. It does this without actually
- changing the current locale, since that would not be
- thread-safe.
- </p>
- <p>This function is typically used when reading configuration
- files or other non-user input that should be locale independent.
- To handle input from the user you should normally use the
- locale-sensitive system <code class="function">strtoll()</code> function.
- </p>
- <p>If the correct value would cause overflow, <code class="constant">G_MAXINT64</code> or <code class="constant">G_MININT64</code>
- is returned, and <code class="code">ERANGE</code> is stored in <code class="code">errno</code>.
- If the base is outside the valid range, zero is returned, and
- <code class="code">EINVAL</code> is stored in <code class="code">errno</code>. If the
- string conversion fails, zero is returned, and <em class="parameter"><code>endptr</code></em> returns <em class="parameter"><code>nptr</code></em>
- (if <em class="parameter"><code>endptr</code></em> is non-<code class="constant">NULL</code>).</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.13.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>nptr</p></td>
- <td class="parameter_description">
- <p>the string to convert to a numeric value.</p>
- <p>Passed as <code class="code">nptr</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>endptr</p></td>
- <td class="parameter_description">
- <p>if non-<code class="constant">NULL</code>, it returns the
- character after the last character used in the conversion.</p>
- <p>Passed as <code class="code">endptr</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>base</p></td>
- <td class="parameter_description">
- <p>to be used for the conversion, 2..36 or 0</p>
- <p>Passed as <code class="code">base</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.14"></a><h3>ascii-strtoull</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return endptr) (ascii-strtoull nptr base))
- </pre></div>
- <p>Converts a string to a <span class="type">guint64</span> value.
- This function behaves like the standard <code class="function">strtoull()</code> function
- does in the C locale. It does this without actually
- changing the current locale, since that would not be
- thread-safe.
- </p>
- <p>Note that input with a leading minus sign (<code class="code">-</code>) is accepted, and will return
- the negation of the parsed number, unless that would overflow a <span class="type">guint64</span>.
- Critically, this means you cannot assume that a short fixed length input will
- never result in a low return value, as the input could have a leading <code class="code">-</code>.
- </p>
- <p>This function is typically used when reading configuration
- files or other non-user input that should be locale independent.
- To handle input from the user you should normally use the
- locale-sensitive system <code class="function">strtoull()</code> function.
- </p>
- <p>If the correct value would cause overflow, <code class="constant">G_MAXUINT64</code>
- is returned, and <code class="code">ERANGE</code> is stored in <code class="code">errno</code>.
- If the base is outside the valid range, zero is returned, and
- <code class="code">EINVAL</code> is stored in <code class="code">errno</code>.
- If the string conversion fails, zero is returned, and <em class="parameter"><code>endptr</code></em> returns
- <em class="parameter"><code>nptr</code></em> (if <em class="parameter"><code>endptr</code></em> is non-<code class="constant">NULL</code>).</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.14.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>nptr</p></td>
- <td class="parameter_description">
- <p>the string to convert to a numeric value.</p>
- <p>Passed as <code class="code">nptr</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>endptr</p></td>
- <td class="parameter_description">
- <p>if non-<code class="constant">NULL</code>, it returns the
- character after the last character used in the conversion.</p>
- <p>Passed as <code class="code">endptr</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>base</p></td>
- <td class="parameter_description">
- <p>to be used for the conversion, 2..36 or 0</p>
- <p>Passed as <code class="code">base</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.15"></a><h3>ascii-strup</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (ascii-strup str len))
- </pre></div>
- <p>Converts all lower case ASCII letters to upper case ASCII letters.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.15.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>length of <em class="parameter"><code>str</code></em> in bytes, or -1 if <em class="parameter"><code>str</code></em> is nul-terminated</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.16"></a><h3>ascii-tolower</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (ascii-tolower c))
- </pre></div>
- <p>Convert a character to ASCII lower case.
- </p>
- <p>Unlike the standard C library <code class="function">tolower()</code> function, this only
- recognizes standard ASCII letters and ignores the locale, returning
- all non-ASCII characters unchanged, even if they are lower case
- letters in a particular character set. Also unlike the standard
- library function, this takes and returns a char, not an int, so
- don't call it on <code class="constant">EOF</code> but no need to worry about casting to <span class="type">guchar</span>
- before passing a possibly non-ASCII character in.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.16.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>any character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.17"></a><h3>ascii-toupper</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (ascii-toupper c))
- </pre></div>
- <p>Convert a character to ASCII upper case.
- </p>
- <p>Unlike the standard C library <code class="function">toupper()</code> function, this only
- recognizes standard ASCII letters and ignores the locale, returning
- all non-ASCII characters unchanged, even if they are upper case
- letters in a particular character set. Also unlike the standard
- library function, this takes and returns a char, not an int, so
- don't call it on <code class="constant">EOF</code> but no need to worry about casting to <span class="type">guchar</span>
- before passing a possibly non-ASCII character in.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.17.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>any character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.18"></a><h3>ascii-xdigit-value</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (ascii-xdigit-value c))
- </pre></div>
- <p>Determines the numeric value of a character as a hexadecimal
- digit. Differs from <code class="function">g_unichar_xdigit_value()</code> because it takes
- a char, so there's no worry about sign extension if characters
- are signed.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.18.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>an ASCII character.</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.19"></a><h3>assert-warning</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- ()
- (assert-warning log-domain file line pretty-function expression))
- </pre></div>
- <p>Undocumented</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.19.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>log_domain</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">log-domain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>file</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">file</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>line</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">line</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>pretty_function</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">pretty-function</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>expression</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">expression</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.20"></a><h3>assertion-message</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (assertion-message domain file line func message))
- </pre></div>
- <p>Undocumented</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.20.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>domain</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">domain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>file</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">file</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>line</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">line</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>func</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">func</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>message</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">message</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.21"></a><h3>assertion-message-cmpstr</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- ()
- (assertion-message-cmpstr domain file line func expr arg1 cmp arg2))
- </pre></div>
- <p>Undocumented</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.21.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>domain</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">domain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>file</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">file</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>line</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">line</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>func</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">func</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>expr</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">expr</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>arg1</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">arg1</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>cmp</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">cmp</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>arg2</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">arg2</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.22"></a><h3>assertion-message-cmpstrv</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- ()
- (assertion-message-cmpstrv
- domain
- file
- line
- func
- expr
- arg1
- arg2
- first-wrong-idx))
- </pre></div>
- <p>Undocumented</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.22.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>domain</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">domain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>file</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">file</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>line</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">line</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>func</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">func</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>expr</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">expr</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>arg1</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">arg1</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>arg2</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">arg2</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>first_wrong_idx</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">first-wrong-idx</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.23"></a><h3>assertion-message-error</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- ()
- (assertion-message-error
- domain
- file
- line
- func
- expr
- error
- error-domain
- error-code))
- </pre></div>
- <p>Undocumented</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.23.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>domain</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">domain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>file</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">file</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>line</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">line</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>func</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">func</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>expr</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">expr</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>error</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">error</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>error_domain</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">error-domain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>error_code</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">error-code</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.24"></a><h3>atomic-int-add</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-int-add atomic val))
- </pre></div>
- <p>Atomically adds <em class="parameter"><code>val</code></em> to the value of <em class="parameter"><code>atomic</code></em>.
- </p>
- <p>Think of this operation as an atomic version of
- <code class="code">{ tmp = *atomic; *atomic += val; return tmp; }</code>.
- </p>
- <p>This call acts as a full compiler and hardware memory barrier.
- </p>
- <p>Before version 2.30, this function did not return a value
- (but <code class="function">g_atomic_int_exchange_and_add()</code> did, and had the same meaning).</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.24.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>atomic</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gint</span> or <span class="type">guint</span></p>
- <p>Passed as <code class="code">atomic</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>val</p></td>
- <td class="parameter_description">
- <p>the value to add</p>
- <p>Passed as <code class="code">val</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.25"></a><h3>atomic-int-and</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-int-and atomic val))
- </pre></div>
- <p>Performs an atomic bitwise 'and' of the value of <em class="parameter"><code>atomic</code></em> and <em class="parameter"><code>val</code></em>,
- storing the result back in <em class="parameter"><code>atomic</code></em>.
- </p>
- <p>This call acts as a full compiler and hardware memory barrier.
- </p>
- <p>Think of this operation as an atomic version of
- <code class="code">{ tmp = *atomic; *atomic &= val; return tmp; }</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.25.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>atomic</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gint</span> or <span class="type">guint</span></p>
- <p>Passed as <code class="code">atomic</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>val</p></td>
- <td class="parameter_description">
- <p>the value to 'and'</p>
- <p>Passed as <code class="code">val</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.26"></a><h3>atomic-int-compare-and-exchange?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (atomic-int-compare-and-exchange? atomic oldval newval))
- </pre></div>
- <p>Compares <em class="parameter"><code>atomic</code></em> to <em class="parameter"><code>oldval</code></em> and, if equal, sets it to <em class="parameter"><code>newval</code></em>.
- If <em class="parameter"><code>atomic</code></em> was not equal to <em class="parameter"><code>oldval</code></em> then no change occurs.
- </p>
- <p>This compare and exchange is done atomically.
- </p>
- <p>Think of this operation as an atomic version of
- <code class="code">{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }</code>.
- </p>
- <p>This call acts as a full compiler and hardware memory barrier.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.26.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>atomic</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gint</span> or <span class="type">guint</span></p>
- <p>Passed as <code class="code">atomic</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>oldval</p></td>
- <td class="parameter_description">
- <p>the value to compare with</p>
- <p>Passed as <code class="code">oldval</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>newval</p></td>
- <td class="parameter_description">
- <p>the value to conditionally replace with</p>
- <p>Passed as <code class="code">newval</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.27"></a><h3>atomic-int-dec-and-test?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-int-dec-and-test? atomic))
- </pre></div>
- <p>Decrements the value of <em class="parameter"><code>atomic</code></em> by 1.
- </p>
- <p>Think of this operation as an atomic version of
- <code class="code">{ *atomic -= 1; return (*atomic == 0); }</code>.
- </p>
- <p>This call acts as a full compiler and hardware memory barrier.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.27.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>atomic</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gint</span> or <span class="type">guint</span></p>
- <p>Passed as <code class="code">atomic</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.28"></a><h3>atomic-int-get</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-int-get atomic))
- </pre></div>
- <p>Gets the current value of <em class="parameter"><code>atomic</code></em>.
- </p>
- <p>This call acts as a full compiler and hardware
- memory barrier (before the get).</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.28.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>atomic</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gint</span> or <span class="type">guint</span></p>
- <p>Passed as <code class="code">atomic</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.29"></a><h3>atomic-int-inc</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (atomic-int-inc atomic))
- </pre></div>
- <p>Increments the value of <em class="parameter"><code>atomic</code></em> by 1.
- </p>
- <p>Think of this operation as an atomic version of <code class="code">{ *atomic += 1; }</code>.
- </p>
- <p>This call acts as a full compiler and hardware memory barrier.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.29.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>atomic</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gint</span> or <span class="type">guint</span></p>
- <p>Passed as <code class="code">atomic</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.30"></a><h3>atomic-int-or</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-int-or atomic val))
- </pre></div>
- <p>Performs an atomic bitwise 'or' of the value of <em class="parameter"><code>atomic</code></em> and <em class="parameter"><code>val</code></em>,
- storing the result back in <em class="parameter"><code>atomic</code></em>.
- </p>
- <p>Think of this operation as an atomic version of
- <code class="code">{ tmp = *atomic; *atomic |= val; return tmp; }</code>.
- </p>
- <p>This call acts as a full compiler and hardware memory barrier.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.30.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>atomic</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gint</span> or <span class="type">guint</span></p>
- <p>Passed as <code class="code">atomic</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>val</p></td>
- <td class="parameter_description">
- <p>the value to 'or'</p>
- <p>Passed as <code class="code">val</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.31"></a><h3>atomic-int-set</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (atomic-int-set atomic newval))
- </pre></div>
- <p>Sets the value of <em class="parameter"><code>atomic</code></em> to <em class="parameter"><code>newval</code></em>.
- </p>
- <p>This call acts as a full compiler and hardware
- memory barrier (after the set).</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.31.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>atomic</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gint</span> or <span class="type">guint</span></p>
- <p>Passed as <code class="code">atomic</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>newval</p></td>
- <td class="parameter_description">
- <p>a new value to store</p>
- <p>Passed as <code class="code">newval</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.32"></a><h3>atomic-int-xor</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-int-xor atomic val))
- </pre></div>
- <p>Performs an atomic bitwise 'xor' of the value of <em class="parameter"><code>atomic</code></em> and <em class="parameter"><code>val</code></em>,
- storing the result back in <em class="parameter"><code>atomic</code></em>.
- </p>
- <p>Think of this operation as an atomic version of
- <code class="code">{ tmp = *atomic; *atomic ^= val; return tmp; }</code>.
- </p>
- <p>This call acts as a full compiler and hardware memory barrier.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.32.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>atomic</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gint</span> or <span class="type">guint</span></p>
- <p>Passed as <code class="code">atomic</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>val</p></td>
- <td class="parameter_description">
- <p>the value to 'xor'</p>
- <p>Passed as <code class="code">val</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.33"></a><h3>atomic-pointer-add</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-pointer-add atomic val))
- </pre></div>
- <p>Atomically adds <em class="parameter"><code>val</code></em> to the value of <em class="parameter"><code>atomic</code></em>.
- </p>
- <p>Think of this operation as an atomic version of
- <code class="code">{ tmp = *atomic; *atomic += val; return tmp; }</code>.
- </p>
- <p>This call acts as a full compiler and hardware memory barrier.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.33.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>atomic</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gpointer</span>-sized value</p>
- <p>Passed as <code class="code">atomic</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>val</p></td>
- <td class="parameter_description">
- <p>the value to add</p>
- <p>Passed as <code class="code">val</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.34"></a><h3>atomic-pointer-and</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-pointer-and atomic val))
- </pre></div>
- <p>Performs an atomic bitwise 'and' of the value of <em class="parameter"><code>atomic</code></em> and <em class="parameter"><code>val</code></em>,
- storing the result back in <em class="parameter"><code>atomic</code></em>.
- </p>
- <p>Think of this operation as an atomic version of
- <code class="code">{ tmp = *atomic; *atomic &= val; return tmp; }</code>.
- </p>
- <p>This call acts as a full compiler and hardware memory barrier.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.34.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>atomic</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gpointer</span>-sized value</p>
- <p>Passed as <code class="code">atomic</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>val</p></td>
- <td class="parameter_description">
- <p>the value to 'and'</p>
- <p>Passed as <code class="code">val</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.35"></a><h3>atomic-pointer-compare-and-exchange?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (atomic-pointer-compare-and-exchange? atomic oldval newval))
- </pre></div>
- <p>Compares <em class="parameter"><code>atomic</code></em> to <em class="parameter"><code>oldval</code></em> and, if equal, sets it to <em class="parameter"><code>newval</code></em>.
- If <em class="parameter"><code>atomic</code></em> was not equal to <em class="parameter"><code>oldval</code></em> then no change occurs.
- </p>
- <p>This compare and exchange is done atomically.
- </p>
- <p>Think of this operation as an atomic version of
- <code class="code">{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }</code>.
- </p>
- <p>This call acts as a full compiler and hardware memory barrier.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.35.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>atomic</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gpointer</span>-sized value</p>
- <p>Passed as <code class="code">atomic</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>oldval</p></td>
- <td class="parameter_description">
- <p>the value to compare with</p>
- <p>Passed as <code class="code">oldval</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>newval</p></td>
- <td class="parameter_description">
- <p>the value to conditionally replace with</p>
- <p>Passed as <code class="code">newval</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.36"></a><h3>atomic-pointer-get</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-pointer-get atomic))
- </pre></div>
- <p>Gets the current value of <em class="parameter"><code>atomic</code></em>.
- </p>
- <p>This call acts as a full compiler and hardware
- memory barrier (before the get).</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.36.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>atomic</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gpointer</span>-sized value</p>
- <p>Passed as <code class="code">atomic</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.37"></a><h3>atomic-pointer-or</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-pointer-or atomic val))
- </pre></div>
- <p>Performs an atomic bitwise 'or' of the value of <em class="parameter"><code>atomic</code></em> and <em class="parameter"><code>val</code></em>,
- storing the result back in <em class="parameter"><code>atomic</code></em>.
- </p>
- <p>Think of this operation as an atomic version of
- <code class="code">{ tmp = *atomic; *atomic |= val; return tmp; }</code>.
- </p>
- <p>This call acts as a full compiler and hardware memory barrier.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.37.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>atomic</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gpointer</span>-sized value</p>
- <p>Passed as <code class="code">atomic</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>val</p></td>
- <td class="parameter_description">
- <p>the value to 'or'</p>
- <p>Passed as <code class="code">val</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.38"></a><h3>atomic-pointer-set</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (atomic-pointer-set atomic newval))
- </pre></div>
- <p>Sets the value of <em class="parameter"><code>atomic</code></em> to <em class="parameter"><code>newval</code></em>.
- </p>
- <p>This call acts as a full compiler and hardware
- memory barrier (after the set).</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.38.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>atomic</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gpointer</span>-sized value</p>
- <p>Passed as <code class="code">atomic</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>newval</p></td>
- <td class="parameter_description">
- <p>a new value to store</p>
- <p>Passed as <code class="code">newval</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.39"></a><h3>atomic-pointer-xor</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-pointer-xor atomic val))
- </pre></div>
- <p>Performs an atomic bitwise 'xor' of the value of <em class="parameter"><code>atomic</code></em> and <em class="parameter"><code>val</code></em>,
- storing the result back in <em class="parameter"><code>atomic</code></em>.
- </p>
- <p>Think of this operation as an atomic version of
- <code class="code">{ tmp = *atomic; *atomic ^= val; return tmp; }</code>.
- </p>
- <p>This call acts as a full compiler and hardware memory barrier.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.39.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>atomic</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gpointer</span>-sized value</p>
- <p>Passed as <code class="code">atomic</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>val</p></td>
- <td class="parameter_description">
- <p>the value to 'xor'</p>
- <p>Passed as <code class="code">val</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.40"></a><h3>atomic-rc-box-acquire</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-rc-box-acquire mem-block))
- </pre></div>
- <p>Atomically acquires a reference on the data pointed by <em class="parameter"><code>mem_block</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.40.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>mem_block</p></td>
- <td class="parameter_description">
- <p>a pointer to reference counted data</p>
- <p>Passed as <code class="code">mem-block</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.41"></a><h3>atomic-rc-box-alloc</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-rc-box-alloc block-size))
- </pre></div>
- <p>Allocates <em class="parameter"><code>block_size</code></em> bytes of memory, and adds atomic
- reference counting semantics to it.
- </p>
- <p>The data will be freed when its reference count drops to
- zero.
- </p>
- <p>The allocated data is guaranteed to be suitably aligned for any
- built-in type.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.41.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>block_size</p></td>
- <td class="parameter_description">
- <p>the size of the allocation, must be greater than 0</p>
- <p>Passed as <code class="code">block-size</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.42"></a><h3>atomic-rc-box-alloc0</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-rc-box-alloc0 block-size))
- </pre></div>
- <p>Allocates <em class="parameter"><code>block_size</code></em> bytes of memory, and adds atomic
- reference counting semantics to it.
- </p>
- <p>The contents of the returned data is set to zero.
- </p>
- <p>The data will be freed when its reference count drops to
- zero.
- </p>
- <p>The allocated data is guaranteed to be suitably aligned for any
- built-in type.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.42.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>block_size</p></td>
- <td class="parameter_description">
- <p>the size of the allocation, must be greater than 0</p>
- <p>Passed as <code class="code">block-size</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.43"></a><h3>atomic-rc-box-dup</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-rc-box-dup block-size mem-block))
- </pre></div>
- <p>Allocates a new block of data with atomic reference counting
- semantics, and copies <em class="parameter"><code>block_size</code></em> bytes of <em class="parameter"><code>mem_block</code></em>
- into it.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.43.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>block_size</p></td>
- <td class="parameter_description">
- <p>the number of bytes to copy, must be greater than 0</p>
- <p>Passed as <code class="code">block-size</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>mem_block</p></td>
- <td class="parameter_description">
- <p>the memory to copy</p>
- <p>Passed as <code class="code">mem-block</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.44"></a><h3>atomic-rc-box-get-size</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-rc-box-get-size mem-block))
- </pre></div>
- <p>Retrieves the size of the reference counted data pointed by <em class="parameter"><code>mem_block</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.44.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>mem_block</p></td>
- <td class="parameter_description">
- <p>a pointer to reference counted data</p>
- <p>Passed as <code class="code">mem-block</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.45"></a><h3>atomic-rc-box-release</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (atomic-rc-box-release mem-block))
- </pre></div>
- <p>Atomically releases a reference on the data pointed by <em class="parameter"><code>mem_block</code></em>.
- </p>
- <p>If the reference was the last one, it will free the
- resources allocated for <em class="parameter"><code>mem_block</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.45.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>mem_block</p></td>
- <td class="parameter_description">
- <p>a pointer to reference counted data</p>
- <p>Passed as <code class="code">mem-block</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.46"></a><h3>atomic-rc-box-release-full</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (atomic-rc-box-release-full mem-block clear-func))
- </pre></div>
- <p>Atomically releases a reference on the data pointed by <em class="parameter"><code>mem_block</code></em>.
- </p>
- <p>If the reference was the last one, it will call <em class="parameter"><code>clear_func</code></em>
- to clear the contents of <em class="parameter"><code>mem_block</code></em>, and then will free the
- resources allocated for <em class="parameter"><code>mem_block</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.46.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>mem_block</p></td>
- <td class="parameter_description">
- <p>a pointer to reference counted data</p>
- <p>Passed as <code class="code">mem-block</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>clear_func</p></td>
- <td class="parameter_description">
- <p>a function to call when clearing the data</p>
- <p>Passed as <code class="code">clear-func</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.47"></a><h3>atomic-ref-count-compare?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-ref-count-compare? arc val))
- </pre></div>
- <p>Atomically compares the current value of <em class="parameter"><code>arc</code></em> with <em class="parameter"><code>val</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.47.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>arc</p></td>
- <td class="parameter_description">
- <p>the address of an atomic reference count variable</p>
- <p>Passed as <code class="code">arc</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>val</p></td>
- <td class="parameter_description">
- <p>the value to compare</p>
- <p>Passed as <code class="code">val</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.48"></a><h3>atomic-ref-count-dec?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (atomic-ref-count-dec? arc))
- </pre></div>
- <p>Atomically decreases the reference count.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.48.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>arc</p></td>
- <td class="parameter_description">
- <p>the address of an atomic reference count variable</p>
- <p>Passed as <code class="code">arc</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.49"></a><h3>atomic-ref-count-inc</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (atomic-ref-count-inc arc))
- </pre></div>
- <p>Atomically increases the reference count.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.49.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>arc</p></td>
- <td class="parameter_description">
- <p>the address of an atomic reference count variable</p>
- <p>Passed as <code class="code">arc</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.50"></a><h3>atomic-ref-count-init</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (atomic-ref-count-init arc))
- </pre></div>
- <p>Initializes a reference count variable.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.50.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>arc</p></td>
- <td class="parameter_description">
- <p>the address of an atomic reference count variable</p>
- <p>Passed as <code class="code">arc</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.51"></a><h3>base64-decode</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return out-len) (base64-decode text))
- </pre></div>
- <p>Decode a sequence of Base-64 encoded text into binary data. Note
- that the returned binary data is not necessarily zero-terminated,
- so it should not be used as a character string.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.51.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>text</p></td>
- <td class="parameter_description">
- <p>zero-terminated string with base64 text to decode</p>
- <p>Passed as <code class="code">text</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>out_len</p></td>
- <td class="parameter_description">
- <p>The length of the decoded data is written here</p>
- <p>Inferred from <code class="code">%return</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.52"></a><h3>base64-decode-inplace!</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return text out-len) (base64-decode-inplace! text))
- </pre></div>
- <p>Decode a sequence of Base-64 encoded text into binary data
- by overwriting the input data.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.52.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>text</p></td>
- <td class="parameter_description">
- <p>zero-terminated
- string with base64 text to decode</p>
- <p>Passed as <code class="code">text</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>out_len</p></td>
- <td class="parameter_description">
- <p>The length of the decoded data is written here</p>
- <p>Inferred from <code class="code">text</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.53"></a><h3>base64-encode</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (base64-encode data))
- </pre></div>
- <p>Encode a sequence of binary data into its Base-64 stringified
- representation.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.53.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>data</p></td>
- <td class="parameter_description">
- <p>the binary data to encode</p>
- <p>Passed as <code class="code">data</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>the length of <em class="parameter"><code>data</code></em></p>
- <p>Inferred from <code class="code">data</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.54"></a><h3>base64-encode-close</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return out state save)
- (base64-encode-close break-lines state save))
- </pre></div>
- <p>Flush the status from a sequence of calls to <code class="function">g_base64_encode_step()</code>.
- </p>
- <p>The output buffer must be large enough to fit all the data that will
- be written to it. It will need up to 4 bytes, or up to 5 bytes if
- line-breaking is enabled.
- </p>
- <p>The <em class="parameter"><code>out</code></em> array will not be automatically nul-terminated.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.54.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>break_lines</p></td>
- <td class="parameter_description">
- <p>whether to break long lines</p>
- <p>Passed as <code class="code">break-lines</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>out</p></td>
- <td class="parameter_description">
- <p>pointer to destination buffer</p>
- <p>Passed as <code class="code">out</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>state</p></td>
- <td class="parameter_description">
- <p>Saved state from <code class="function">g_base64_encode_step()</code></p>
- <p>Passed as <code class="code">state</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>save</p></td>
- <td class="parameter_description">
- <p>Saved state from <code class="function">g_base64_encode_step()</code></p>
- <p>Passed as <code class="code">save</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.55"></a><h3>base64-encode-step</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return out state save)
- (base64-encode-step in break-lines state save))
- </pre></div>
- <p>Incrementally encode a sequence of binary data into its Base-64 stringified
- representation. By calling this function multiple times you can convert
- data in chunks to avoid having to have the full encoded data in memory.
- </p>
- <p>When all of the data has been converted you must call
- <code class="function">g_base64_encode_close()</code> to flush the saved state.
- </p>
- <p>The output buffer must be large enough to fit all the data that will
- be written to it. Due to the way base64 encodes you will need
- at least: (<em class="parameter"><code>len</code></em> / 3 + 1) * 4 + 4 bytes (+ 4 may be needed in case of
- non-zero state). If you enable line-breaking you will need at least:
- ((<em class="parameter"><code>len</code></em> / 3 + 1) * 4 + 4) / 76 + 1 bytes of extra space.
- </p>
- <p><em class="parameter"><code>break_lines</code></em> is typically used when putting base64-encoded data in emails.
- It breaks the lines at 76 columns instead of putting all of the text on
- the same line. This avoids problems with long lines in the email system.
- Note however that it breaks the lines with <code class="code">LF</code> characters, not
- <code class="code">CR LF</code> sequences, so the result cannot be passed directly to SMTP
- or certain other protocols.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.55.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>in</p></td>
- <td class="parameter_description">
- <p>the binary data to encode</p>
- <p>Passed as <code class="code">in</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>the length of <em class="parameter"><code>in</code></em></p>
- <p>Inferred from <code class="code">in</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>break_lines</p></td>
- <td class="parameter_description">
- <p>whether to break long lines</p>
- <p>Passed as <code class="code">break-lines</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>out</p></td>
- <td class="parameter_description">
- <p>pointer to destination buffer</p>
- <p>Passed as <code class="code">out</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>state</p></td>
- <td class="parameter_description">
- <p>Saved state between steps, initialize to 0</p>
- <p>Passed as <code class="code">state</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>save</p></td>
- <td class="parameter_description">
- <p>Saved state between steps, initialize to 0</p>
- <p>Passed as <code class="code">save</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.56"></a><h3>bit-lock</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (bit-lock address lock-bit))
- </pre></div>
- <p>Sets the indicated <em class="parameter"><code>lock_bit</code></em> in <em class="parameter"><code>address</code></em>. If the bit is already
- set, this call will block until <code class="function">g_bit_unlock()</code> unsets the
- corresponding bit.
- </p>
- <p>Attempting to lock on two different bits within the same integer is
- not supported and will very probably cause deadlocks.
- </p>
- <p>The value of the bit that is set is (1u << <em class="parameter"><code>bit</code></em>). If <em class="parameter"><code>bit</code></em> is not
- between 0 and 31 then the result is undefined.
- </p>
- <p>This function accesses <em class="parameter"><code>address</code></em> atomically. All other accesses to
- <em class="parameter"><code>address</code></em> must be atomic in order for this function to work
- reliably.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.56.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>address</p></td>
- <td class="parameter_description">
- <p>a pointer to an integer</p>
- <p>Passed as <code class="code">address</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>lock_bit</p></td>
- <td class="parameter_description">
- <p>a bit value between 0 and 31</p>
- <p>Passed as <code class="code">lock-bit</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.57"></a><h3>bit-nth-lsf</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (bit-nth-lsf mask nth-bit))
- </pre></div>
- <p>Find the position of the first bit set in <em class="parameter"><code>mask</code></em>, searching
- from (but not including) <em class="parameter"><code>nth_bit</code></em> upwards. Bits are numbered
- from 0 (least significant) to sizeof(<span class="type">gulong</span>) * 8 - 1 (31 or 63,
- usually). To start searching from the 0th bit, set <em class="parameter"><code>nth_bit</code></em> to -1.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.57.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>mask</p></td>
- <td class="parameter_description">
- <p>a <span class="type">gulong</span> containing flags</p>
- <p>Passed as <code class="code">mask</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>nth_bit</p></td>
- <td class="parameter_description">
- <p>the index of the bit to start the search from</p>
- <p>Passed as <code class="code">nth-bit</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.58"></a><h3>bit-nth-msf</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (bit-nth-msf mask nth-bit))
- </pre></div>
- <p>Find the position of the first bit set in <em class="parameter"><code>mask</code></em>, searching
- from (but not including) <em class="parameter"><code>nth_bit</code></em> downwards. Bits are numbered
- from 0 (least significant) to sizeof(<span class="type">gulong</span>) * 8 - 1 (31 or 63,
- usually). To start searching from the last bit, set <em class="parameter"><code>nth_bit</code></em> to
- -1 or GLIB_SIZEOF_LONG * 8.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.58.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>mask</p></td>
- <td class="parameter_description">
- <p>a <span class="type">gulong</span> containing flags</p>
- <p>Passed as <code class="code">mask</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>nth_bit</p></td>
- <td class="parameter_description">
- <p>the index of the bit to start the search from</p>
- <p>Passed as <code class="code">nth-bit</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.59"></a><h3>bit-storage</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (bit-storage number))
- </pre></div>
- <p>Gets the number of bits used to hold <em class="parameter"><code>number</code></em>,
- e.g. if <em class="parameter"><code>number</code></em> is 4, 3 bits are needed.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.59.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>number</p></td>
- <td class="parameter_description">
- <p>a <span class="type">guint</span></p>
- <p>Passed as <code class="code">number</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.60"></a><h3>bit-trylock?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (bit-trylock? address lock-bit))
- </pre></div>
- <p>Sets the indicated <em class="parameter"><code>lock_bit</code></em> in <em class="parameter"><code>address</code></em>, returning <code class="constant">TRUE</code> if
- successful. If the bit is already set, returns <code class="constant">FALSE</code> immediately.
- </p>
- <p>Attempting to lock on two different bits within the same integer is
- not supported.
- </p>
- <p>The value of the bit that is set is (1u << <em class="parameter"><code>bit</code></em>). If <em class="parameter"><code>bit</code></em> is not
- between 0 and 31 then the result is undefined.
- </p>
- <p>This function accesses <em class="parameter"><code>address</code></em> atomically. All other accesses to
- <em class="parameter"><code>address</code></em> must be atomic in order for this function to work
- reliably.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.60.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>address</p></td>
- <td class="parameter_description">
- <p>a pointer to an integer</p>
- <p>Passed as <code class="code">address</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>lock_bit</p></td>
- <td class="parameter_description">
- <p>a bit value between 0 and 31</p>
- <p>Passed as <code class="code">lock-bit</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.61"></a><h3>bit-unlock</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (bit-unlock address lock-bit))
- </pre></div>
- <p>Clears the indicated <em class="parameter"><code>lock_bit</code></em> in <em class="parameter"><code>address</code></em>. If another thread is
- currently blocked in <code class="function">g_bit_lock()</code> on this same bit then it will be
- woken up.
- </p>
- <p>This function accesses <em class="parameter"><code>address</code></em> atomically. All other accesses to
- <em class="parameter"><code>address</code></em> must be atomic in order for this function to work
- reliably.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.61.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>address</p></td>
- <td class="parameter_description">
- <p>a pointer to an integer</p>
- <p>Passed as <code class="code">address</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>lock_bit</p></td>
- <td class="parameter_description">
- <p>a bit value between 0 and 31</p>
- <p>Passed as <code class="code">lock-bit</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.62"></a><h3>bookmark-file-error-quark</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (bookmark-file-error-quark))
- </pre></div>
- <p>Undocumented</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.63"></a><h3>build-filenamev</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (build-filenamev args))
- </pre></div>
- <p>Behaves exactly like <code class="function">g_build_filename()</code>, but takes the path elements
- as a string array, instead of varargs. This function is mainly
- meant for language bindings.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.63.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>args</p></td>
- <td class="parameter_description">
- <p><code class="constant">NULL</code>-terminated
- array of strings containing the path elements.</p>
- <p>Passed as <code class="code">args</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.64"></a><h3>build-pathv</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (build-pathv separator args))
- </pre></div>
- <p>Behaves exactly like <code class="function">g_build_path()</code>, but takes the path elements
- as a string array, instead of varargs. This function is mainly
- meant for language bindings.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.64.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>separator</p></td>
- <td class="parameter_description">
- <p>a string used to separator the elements of the path.</p>
- <p>Passed as <code class="code">separator</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>args</p></td>
- <td class="parameter_description">
- <p><code class="constant">NULL</code>-terminated
- array of strings containing the path elements.</p>
- <p>Passed as <code class="code">args</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.65"></a><h3>byte-array-free</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (byte-array-free array free-segment))
- </pre></div>
- <p>Frees the memory allocated by the <span class="type">GByteArray</span>. If <em class="parameter"><code>free_segment</code></em> is
- <code class="constant">TRUE</code> it frees the actual byte data. If the reference count of
- <em class="parameter"><code>array</code></em> is greater than one, the <span class="type">GByteArray</span> wrapper is preserved but
- the size of <em class="parameter"><code>array</code></em> will be set to zero.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.65.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>array</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GByteArray</span></p>
- <p>Passed as <code class="code">array</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>free_segment</p></td>
- <td class="parameter_description">
- <p>if <code class="constant">TRUE</code> the actual byte data is freed as well</p>
- <p>Passed as <code class="code">free-segment</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.66"></a><h3>byte-array-free-to-bytes</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (byte-array-free-to-bytes array))
- </pre></div>
- <p>Transfers the data from the <span class="type">GByteArray</span> into a new immutable <span class="type">GBytes</span>.
- </p>
- <p>The <span class="type">GByteArray</span> is freed unless the reference count of <em class="parameter"><code>array</code></em> is greater
- than one, the <span class="type">GByteArray</span> wrapper is preserved but the size of <em class="parameter"><code>array</code></em>
- will be set to zero.
- </p>
- <p>This is identical to using <code class="function">g_bytes_new_take()</code> and <code class="function">g_byte_array_free()</code>
- together.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.66.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>array</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GByteArray</span></p>
- <p>Passed as <code class="code">array</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.67"></a><h3>byte-array-new</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (byte-array-new))
- </pre></div>
- <p>Creates a new <span class="type">GByteArray</span> with a reference count of 1.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.68"></a><h3>byte-array-new-take</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (byte-array-new-take data))
- </pre></div>
- <p>Create byte array containing the data. The data will be owned by the array
- and will be freed with <code class="function">g_free()</code>, i.e. it could be allocated using <code class="function">g_strdup()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.68.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>data</p></td>
- <td class="parameter_description">
- <p>byte data for the array</p>
- <p>Passed as <code class="code">data</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>length of <em class="parameter"><code>data</code></em></p>
- <p>Inferred from <code class="code">data</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.69"></a><h3>byte-array-steal</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return len) (byte-array-steal array len))
- </pre></div>
- <p>Frees the data in the array and resets the size to zero, while
- the underlying array is preserved for use elsewhere and returned
- to the caller.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.69.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>array</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GByteArray</span>.</p>
- <p>Passed as <code class="code">array</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>pointer to retrieve the number of
- elements of the original array</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.70"></a><h3>byte-array-unref</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (byte-array-unref array))
- </pre></div>
- <p>Atomically decrements the reference count of <em class="parameter"><code>array</code></em> by one. If the
- reference count drops to 0, all memory allocated by the array is
- released. This function is thread-safe and may be called from any
- thread.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.70.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>array</p></td>
- <td class="parameter_description">
- <p>A <span class="type">GByteArray</span></p>
- <p>Passed as <code class="code">array</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.71"></a><h3>canonicalize-filename</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (canonicalize-filename filename relative-to))
- </pre></div>
- <p>Gets the canonical file name from <em class="parameter"><code>filename</code></em>. All triple slashes are turned into
- single slashes, and all <code class="code">..</code> and <code class="code">.</code>s resolved against <em class="parameter"><code>relative_to</code></em>.
- </p>
- <p>Symlinks are not followed, and the returned path is guaranteed to be absolute.
- </p>
- <p>If <em class="parameter"><code>filename</code></em> is an absolute path, <em class="parameter"><code>relative_to</code></em> is ignored. Otherwise,
- <em class="parameter"><code>relative_to</code></em> will be prepended to <em class="parameter"><code>filename</code></em> to make it absolute. <em class="parameter"><code>relative_to</code></em>
- must be an absolute path, or <code class="constant">NULL</code>. If <em class="parameter"><code>relative_to</code></em> is <code class="constant">NULL</code>, it'll fallback
- to <code class="function">g_get_current_dir()</code>.
- </p>
- <p>This function never fails, and will canonicalize file paths even if they don't
- exist.
- </p>
- <p>No file system I/O is done.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.71.8"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>filename</p></td>
- <td class="parameter_description">
- <p>the name of the file</p>
- <p>Passed as <code class="code">filename</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>relative_to</p></td>
- <td class="parameter_description">
- <p>the relative directory, or <code class="constant">NULL</code>
- to use the current working directory</p>
- <p>Passed as <code class="code">relative-to</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.72"></a><h3>chdir</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (chdir path))
- </pre></div>
- <p>A wrapper for the POSIX <code class="function">chdir()</code> function. The function changes the
- current directory of the process to <em class="parameter"><code>path</code></em>.
- </p>
- <p>See your C library manual for more details about <code class="function">chdir()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.72.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>path</p></td>
- <td class="parameter_description">
- <p>a pathname in the GLib file name encoding
- (UTF-8 on Windows)</p>
- <p>Passed as <code class="code">path</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.73"></a><h3>check-version</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (check-version required-major required-minor required-micro))
- </pre></div>
- <p>Checks that the GLib library in use is compatible with the
- given version. Generally you would pass in the constants
- <span class="type">GLIB_MAJOR_VERSION</span>, <span class="type">GLIB_MINOR_VERSION</span>, <span class="type">GLIB_MICRO_VERSION</span>
- as the three arguments to this function; that produces
- a check that the library in use is compatible with
- the version of GLib the application or module was compiled
- against.
- </p>
- <p>Compatibility is defined by two things: first the version
- of the running library is newer than the version
- <em class="parameter"><code>required_major</code></em>.required_minor.<em class="parameter"><code>required_micro</code></em>. Second
- the running library must be binary compatible with the
- version <em class="parameter"><code>required_major</code></em>.required_minor.<em class="parameter"><code>required_micro</code></em>
- (same major version.)</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.73.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>required_major</p></td>
- <td class="parameter_description">
- <p>the required major version</p>
- <p>Passed as <code class="code">required-major</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>required_minor</p></td>
- <td class="parameter_description">
- <p>the required minor version</p>
- <p>Passed as <code class="code">required-minor</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>required_micro</p></td>
- <td class="parameter_description">
- <p>the required micro version</p>
- <p>Passed as <code class="code">required-micro</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.74"></a><h3>checksum-type-get-length</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (checksum-type-get-length checksum-type))
- </pre></div>
- <p>Gets the length in bytes of digests of type <em class="parameter"><code>checksum_type</code></em></p>
- <div class="refsect3">
- <a name="id-1.1.90.2.74.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>checksum_type</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GChecksumType</span></p>
- <p>Passed as <code class="code">checksum-type</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.75"></a><h3>child-watch-add</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (child-watch-add priority pid function data notify))
- </pre></div>
- <p>Sets a function to be called when the child indicated by <em class="parameter"><code>pid</code></em>
- exits, at a default priority, <span class="type">G_PRIORITY_DEFAULT</span>.
- </p>
- <p>If you obtain <em class="parameter"><code>pid</code></em> from <code class="function">g_spawn_async()</code> or <code class="function">g_spawn_async_with_pipes()</code>
- you will need to pass <span class="type">G_SPAWN_DO_NOT_REAP_CHILD</span> as flag to
- the spawn function for the child watching to work.
- </p>
- <p>Note that on platforms where <span class="type">GPid</span> must be explicitly closed
- (see <code class="function">g_spawn_close_pid()</code>) <em class="parameter"><code>pid</code></em> must not be closed while the
- source is still active. Typically, you will want to call
- <code class="function">g_spawn_close_pid()</code> in the callback function for the source.
- </p>
- <p>GLib supports only a single callback per process id.
- On POSIX platforms, the same restrictions mentioned for
- <code class="function">g_child_watch_source_new()</code> apply to this function.
- </p>
- <p>This internally creates a main loop source using
- <code class="function">g_child_watch_source_new()</code> and attaches it to the main loop context
- using <code class="function">g_source_attach()</code>. You can do these steps manually if you
- need greater control.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.75.8"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>notify</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">notify</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>priority</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">priority</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>pid</p></td>
- <td class="parameter_description">
- <p>process id to watch. On POSIX the positive pid of a child
- process. On Windows a handle for a process (which doesn't have to be
- a child).</p>
- <p>Passed as <code class="code">pid</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>function</p></td>
- <td class="parameter_description">
- <p>function to call</p>
- <p>Passed as <code class="code">function</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>data</p></td>
- <td class="parameter_description">
- <p>data to pass to <em class="parameter"><code>function</code></em></p>
- <p>Passed as <code class="code">data</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.76"></a><h3>child-watch-source-new</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (child-watch-source-new pid))
- </pre></div>
- <p>Creates a new child_watch source.
- </p>
- <p>The source will not initially be associated with any <span class="type">GMainContext</span>
- and must be added to one with <code class="function">g_source_attach()</code> before it will be
- executed.
- </p>
- <p>Note that child watch sources can only be used in conjunction with
- <code class="code">g_spawn...</code> when the <code class="constant">G_SPAWN_DO_NOT_REAP_CHILD</code> flag is used.
- </p>
- <p>Note that on platforms where <span class="type">GPid</span> must be explicitly closed
- (see <code class="function">g_spawn_close_pid()</code>) <em class="parameter"><code>pid</code></em> must not be closed while the
- source is still active. Typically, you will want to call
- <code class="function">g_spawn_close_pid()</code> in the callback function for the source.
- </p>
- <p>On POSIX platforms, the following restrictions apply to this API
- due to limitations in POSIX process interfaces:
- </p>
- <p>* <em class="parameter"><code>pid</code></em> must be a child of this process
- * <em class="parameter"><code>pid</code></em> must be positive
- * the application must not call <code class="code">waitpid</code> with a non-positive
- first argument, for instance in another thread
- * the application must not wait for <em class="parameter"><code>pid</code></em> to exit by any other
- mechanism, including <code class="code">waitpid(pid, ...)</code> or a second child-watch
- source for the same <em class="parameter"><code>pid</code></em>
- * the application must not ignore SIGCHILD
- </p>
- <p>If any of those conditions are not met, this and related APIs will
- not work correctly. This can often be diagnosed via a GLib warning
- stating that <code class="code">ECHILD</code> was received by <code class="code">waitpid</code>.
- </p>
- <p>Calling <code class="code">waitpid</code> for specific processes other than <em class="parameter"><code>pid</code></em> remains a
- valid thing to do.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.76.11"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>pid</p></td>
- <td class="parameter_description">
- <p>process to watch. On POSIX the positive pid of a child process. On
- Windows a handle for a process (which doesn't have to be a child).</p>
- <p>Passed as <code class="code">pid</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.77"></a><h3>clear-error</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (clear-error))
- </pre></div>
- <p>If <em class="parameter"><code>err</code></em> or *<em class="parameter"><code>err</code></em> is <code class="constant">NULL</code>, does nothing. Otherwise,
- calls <code class="function">g_error_free()</code> on *<em class="parameter"><code>err</code></em> and sets *<em class="parameter"><code>err</code></em> to <code class="constant">NULL</code>.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.78"></a><h3>close?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (close? fd))
- </pre></div>
- <p>This wraps the <code class="function">close()</code> call; in case of error, <code class="constant">errno</code> will be
- preserved, but the error will also be stored as a <span class="type">GError</span> in <em class="parameter"><code>error</code></em>.
- </p>
- <p>Besides using <span class="type">GError</span>, there is another major reason to prefer this
- function over the call provided by the system; on Unix, it will
- attempt to correctly handle <code class="constant">EINTR</code>, which has platform-specific
- semantics.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.78.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>fd</p></td>
- <td class="parameter_description">
- <p>A file descriptor</p>
- <p>Passed as <code class="code">fd</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.79"></a><h3>compute-checksum-for-bytes</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (compute-checksum-for-bytes checksum-type data))
- </pre></div>
- <p>Computes the checksum for a binary <em class="parameter"><code>data</code></em>. This is a
- convenience wrapper for <code class="function">g_checksum_new()</code>, <code class="function">g_checksum_get_string()</code>
- and <code class="function">g_checksum_free()</code>.
- </p>
- <p>The hexadecimal string returned will be in lower case.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.79.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>checksum_type</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GChecksumType</span></p>
- <p>Passed as <code class="code">checksum-type</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>data</p></td>
- <td class="parameter_description">
- <p>binary blob to compute the digest of</p>
- <p>Passed as <code class="code">data</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.80"></a><h3>compute-checksum-for-data</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (compute-checksum-for-data checksum-type data))
- </pre></div>
- <p>Computes the checksum for a binary <em class="parameter"><code>data</code></em> of <em class="parameter"><code>length</code></em>. This is a
- convenience wrapper for <code class="function">g_checksum_new()</code>, <code class="function">g_checksum_get_string()</code>
- and <code class="function">g_checksum_free()</code>.
- </p>
- <p>The hexadecimal string returned will be in lower case.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.80.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>checksum_type</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GChecksumType</span></p>
- <p>Passed as <code class="code">checksum-type</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>data</p></td>
- <td class="parameter_description">
- <p>binary blob to compute the digest of</p>
- <p>Passed as <code class="code">data</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>length</p></td>
- <td class="parameter_description">
- <p>length of <em class="parameter"><code>data</code></em></p>
- <p>Inferred from <code class="code">data</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.81"></a><h3>compute-checksum-for-string</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (compute-checksum-for-string checksum-type str length))
- </pre></div>
- <p>Computes the checksum of a string.
- </p>
- <p>The hexadecimal string returned will be in lower case.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.81.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>checksum_type</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GChecksumType</span></p>
- <p>Passed as <code class="code">checksum-type</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>the string to compute the checksum of</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>length</p></td>
- <td class="parameter_description">
- <p>the length of the string, or -1 if the string is null-terminated.</p>
- <p>Passed as <code class="code">length</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.82"></a><h3>compute-hmac-for-bytes</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (compute-hmac-for-bytes digest-type key data))
- </pre></div>
- <p>Computes the HMAC for a binary <em class="parameter"><code>data</code></em>. This is a
- convenience wrapper for <code class="function">g_hmac_new()</code>, <code class="function">g_hmac_get_string()</code>
- and <code class="function">g_hmac_unref()</code>.
- </p>
- <p>The hexadecimal string returned will be in lower case.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.82.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>digest_type</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GChecksumType</span> to use for the HMAC</p>
- <p>Passed as <code class="code">digest-type</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>key</p></td>
- <td class="parameter_description">
- <p>the key to use in the HMAC</p>
- <p>Passed as <code class="code">key</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>data</p></td>
- <td class="parameter_description">
- <p>binary blob to compute the HMAC of</p>
- <p>Passed as <code class="code">data</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.83"></a><h3>compute-hmac-for-data</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (compute-hmac-for-data digest-type key data))
- </pre></div>
- <p>Computes the HMAC for a binary <em class="parameter"><code>data</code></em> of <em class="parameter"><code>length</code></em>. This is a
- convenience wrapper for <code class="function">g_hmac_new()</code>, <code class="function">g_hmac_get_string()</code>
- and <code class="function">g_hmac_unref()</code>.
- </p>
- <p>The hexadecimal string returned will be in lower case.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.83.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>digest_type</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GChecksumType</span> to use for the HMAC</p>
- <p>Passed as <code class="code">digest-type</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>key</p></td>
- <td class="parameter_description">
- <p>the key to use in the HMAC</p>
- <p>Passed as <code class="code">key</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>key_len</p></td>
- <td class="parameter_description">
- <p>the length of the key</p>
- <p>Inferred from <code class="code">key</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>data</p></td>
- <td class="parameter_description">
- <p>binary blob to compute the HMAC of</p>
- <p>Passed as <code class="code">data</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>length</p></td>
- <td class="parameter_description">
- <p>length of <em class="parameter"><code>data</code></em></p>
- <p>Inferred from <code class="code">data</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.84"></a><h3>compute-hmac-for-string</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (compute-hmac-for-string digest-type key str length))
- </pre></div>
- <p>Computes the HMAC for a string.
- </p>
- <p>The hexadecimal string returned will be in lower case.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.84.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>digest_type</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GChecksumType</span> to use for the HMAC</p>
- <p>Passed as <code class="code">digest-type</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>key</p></td>
- <td class="parameter_description">
- <p>the key to use in the HMAC</p>
- <p>Passed as <code class="code">key</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>key_len</p></td>
- <td class="parameter_description">
- <p>the length of the key</p>
- <p>Inferred from <code class="code">key</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>the string to compute the HMAC for</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>length</p></td>
- <td class="parameter_description">
- <p>the length of the string, or -1 if the string is nul-terminated</p>
- <p>Passed as <code class="code">length</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.85"></a><h3>convert</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return bytes-read bytes-written)
- (convert str to-codeset from-codeset))
- </pre></div>
- <p>Converts a string from one character set to another.
- </p>
- <p>Note that you should use <code class="function">g_iconv()</code> for streaming conversions.
- Despite the fact that <em class="parameter"><code>bytes_read</code></em> can return information about partial
- characters, the g_convert_... functions are not generally suitable
- for streaming. If the underlying converter maintains internal state,
- then this won't be preserved across successive calls to <code class="function">g_convert()</code>,
- <code class="function">g_convert_with_iconv()</code> or <code class="function">g_convert_with_fallback()</code>. (An example of
- this is the GNU C converter for CP1255 which does not emit a base
- character until it knows that the next character is not a mark that
- could combine with the base character.)
- </p>
- <p>Using extensions such as "//TRANSLIT" may not work (or may not work
- well) on many platforms. Consider using <code class="function">g_str_to_ascii()</code> instead.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.85.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>
- </p>
- <p>the string to convert.</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>the length of the string in bytes, or -1 if the string is
- nul-terminated (Note that some encodings may allow nul
- bytes to occur inside strings. In that case, using -1
- for the <em class="parameter"><code>len</code></em> parameter is unsafe)</p>
- <p>Inferred from <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>to_codeset</p></td>
- <td class="parameter_description">
- <p>name of character set into which to convert <em class="parameter"><code>str</code></em></p>
- <p>Passed as <code class="code">to-codeset</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>from_codeset</p></td>
- <td class="parameter_description">
- <p>character set of <em class="parameter"><code>str</code></em>.</p>
- <p>Passed as <code class="code">from-codeset</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>bytes_read</p></td>
- <td class="parameter_description">
- <p>location to store the number of bytes in
- the input string that were successfully converted, or <code class="constant">NULL</code>.
- Even if the conversion was successful, this may be
- less than <em class="parameter"><code>len</code></em> if there were partial characters
- at the end of the input. If the error
- <span class="type">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</span> occurs, the value
- stored will be the byte offset after the last valid
- input sequence.</p>
- <p>Passed as <code class="code">bytes-read</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>bytes_written</p></td>
- <td class="parameter_description">
- <p>the number of bytes stored in
- the output buffer (not including the terminating nul).</p>
- <p>Inferred from <code class="code">%return</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.86"></a><h3>convert-error-quark</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (convert-error-quark))
- </pre></div>
- <p>Undocumented</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.87"></a><h3>convert-with-fallback</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return bytes-read bytes-written)
- (convert-with-fallback str to-codeset from-codeset fallback))
- </pre></div>
- <p>Converts a string from one character set to another, possibly
- including fallback sequences for characters not representable
- in the output. Note that it is not guaranteed that the specification
- for the fallback sequences in <em class="parameter"><code>fallback</code></em> will be honored. Some
- systems may do an approximate conversion from <em class="parameter"><code>from_codeset</code></em>
- to <em class="parameter"><code>to_codeset</code></em> in their <code class="function">iconv()</code> functions,
- in which case GLib will simply return that approximate conversion.
- </p>
- <p>Note that you should use <code class="function">g_iconv()</code> for streaming conversions.
- Despite the fact that <em class="parameter"><code>bytes_read</code></em> can return information about partial
- characters, the g_convert_... functions are not generally suitable
- for streaming. If the underlying converter maintains internal state,
- then this won't be preserved across successive calls to <code class="function">g_convert()</code>,
- <code class="function">g_convert_with_iconv()</code> or <code class="function">g_convert_with_fallback()</code>. (An example of
- this is the GNU C converter for CP1255 which does not emit a base
- character until it knows that the next character is not a mark that
- could combine with the base character.)</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.87.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>
- </p>
- <p>the string to convert.</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>the length of the string in bytes, or -1 if the string is
- nul-terminated (Note that some encodings may allow nul
- bytes to occur inside strings. In that case, using -1
- for the <em class="parameter"><code>len</code></em> parameter is unsafe)</p>
- <p>Inferred from <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>to_codeset</p></td>
- <td class="parameter_description">
- <p>name of character set into which to convert <em class="parameter"><code>str</code></em></p>
- <p>Passed as <code class="code">to-codeset</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>from_codeset</p></td>
- <td class="parameter_description">
- <p>character set of <em class="parameter"><code>str</code></em>.</p>
- <p>Passed as <code class="code">from-codeset</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>fallback</p></td>
- <td class="parameter_description">
- <p>UTF-8 string to use in place of characters not
- present in the target encoding. (The string must be
- representable in the target encoding).
- If <code class="constant">NULL</code>, characters not in the target encoding will
- be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.</p>
- <p>Passed as <code class="code">fallback</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>bytes_read</p></td>
- <td class="parameter_description">
- <p>location to store the number of bytes in
- the input string that were successfully converted, or <code class="constant">NULL</code>.
- Even if the conversion was successful, this may be
- less than <em class="parameter"><code>len</code></em> if there were partial characters
- at the end of the input.</p>
- <p>Passed as <code class="code">bytes-read</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>bytes_written</p></td>
- <td class="parameter_description">
- <p>the number of bytes stored in
- the output buffer (not including the terminating nul).</p>
- <p>Inferred from <code class="code">%return</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.88"></a><h3>dataset-destroy</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (dataset-destroy dataset-location))
- </pre></div>
- <p>Destroys the dataset, freeing all memory allocated, and calling any
- destroy functions set for data elements.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.88.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>dataset_location</p></td>
- <td class="parameter_description">
- <p>the location identifying the dataset.</p>
- <p>Passed as <code class="code">dataset-location</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.89"></a><h3>dataset-foreach</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (dataset-foreach dataset-location func user-data))
- </pre></div>
- <p>Calls the given function for each data element which is associated
- with the given location. Note that this function is NOT thread-safe.
- So unless <em class="parameter"><code>dataset_location</code></em> can be protected from any modifications
- during invocation of this function, it should not be called.
- </p>
- <p><em class="parameter"><code>func</code></em> can make changes to the dataset, but the iteration will not
- reflect changes made during the <code class="function">g_dataset_foreach()</code> call, other
- than skipping over elements that are removed.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.89.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>dataset_location</p></td>
- <td class="parameter_description">
- <p>the location identifying the dataset.</p>
- <p>Passed as <code class="code">dataset-location</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>func</p></td>
- <td class="parameter_description">
- <p>the function to call for each data element.</p>
- <p>Passed as <code class="code">func</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>user_data</p></td>
- <td class="parameter_description">
- <p>user data to pass to the function.</p>
- <p>Passed as <code class="code">user-data</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.90"></a><h3>dataset-id-get-data</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (dataset-id-get-data dataset-location key-id))
- </pre></div>
- <p>Gets the data element corresponding to a <span class="type">GQuark</span>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.90.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>dataset_location</p></td>
- <td class="parameter_description">
- <p>the location identifying the dataset.</p>
- <p>Passed as <code class="code">dataset-location</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>key_id</p></td>
- <td class="parameter_description">
- <p>the <span class="type">GQuark</span> id to identify the data element.</p>
- <p>Passed as <code class="code">key-id</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.91"></a><h3>date-get-days-in-month</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (date-get-days-in-month month year))
- </pre></div>
- <p>Returns the number of days in a month, taking leap
- years into account.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.91.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>month</p></td>
- <td class="parameter_description">
- <p>month</p>
- <p>Passed as <code class="code">month</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>year</p></td>
- <td class="parameter_description">
- <p>year</p>
- <p>Passed as <code class="code">year</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.92"></a><h3>date-get-monday-weeks-in-year</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (date-get-monday-weeks-in-year year))
- </pre></div>
- <p>Returns the number of weeks in the year, where weeks
- are taken to start on Monday. Will be 52 or 53. The
- date must be valid. (Years always have 52 7-day periods,
- plus 1 or 2 extra days depending on whether it's a leap
- year. This function is basically telling you how many
- Mondays are in the year, i.e. there are 53 Mondays if
- one of the extra days happens to be a Monday.)</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.92.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>year</p></td>
- <td class="parameter_description">
- <p>a year</p>
- <p>Passed as <code class="code">year</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.93"></a><h3>date-get-sunday-weeks-in-year</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (date-get-sunday-weeks-in-year year))
- </pre></div>
- <p>Returns the number of weeks in the year, where weeks
- are taken to start on Sunday. Will be 52 or 53. The
- date must be valid. (Years always have 52 7-day periods,
- plus 1 or 2 extra days depending on whether it's a leap
- year. This function is basically telling you how many
- Sundays are in the year, i.e. there are 53 Sundays if
- one of the extra days happens to be a Sunday.)</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.93.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>year</p></td>
- <td class="parameter_description">
- <p>year to count weeks in</p>
- <p>Passed as <code class="code">year</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.94"></a><h3>date-is-leap-year?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (date-is-leap-year? year))
- </pre></div>
- <p>Returns <code class="constant">TRUE</code> if the year is a leap year.
- </p>
- <p>For the purposes of this function, leap year is every year
- divisible by 4 unless that year is divisible by 100. If it
- is divisible by 100 it would be a leap year only if that year
- is also divisible by 400.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.94.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>year</p></td>
- <td class="parameter_description">
- <p>year to check</p>
- <p>Passed as <code class="code">year</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.95"></a><h3>date-strftime</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (date-strftime s slen format date))
- </pre></div>
- <p>Generates a printed representation of the date, in a
- [locale][setlocale]-specific way.
- Works just like the platform's C library <code class="function">strftime()</code> function,
- but only accepts date-related formats; time-related formats
- give undefined results. Date must be valid. Unlike <code class="function">strftime()</code>
- (which uses the locale encoding), works on a UTF-8 format
- string and stores a UTF-8 result.
- </p>
- <p>This function does not provide any conversion specifiers in
- addition to those implemented by the platform's C library.
- For example, don't expect that using <code class="function">g_date_strftime()</code> would
- make the \%F provided by the C99 <code class="function">strftime()</code> work on Windows
- where the C library only complies to C89.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.95.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>s</p></td>
- <td class="parameter_description">
- <p>destination buffer</p>
- <p>Passed as <code class="code">s</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>slen</p></td>
- <td class="parameter_description">
- <p>buffer size</p>
- <p>Passed as <code class="code">slen</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>format</p></td>
- <td class="parameter_description">
- <p>format string</p>
- <p>Passed as <code class="code">format</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>date</p></td>
- <td class="parameter_description">
- <p>valid <span class="type">GDate</span></p>
- <p>Passed as <code class="code">date</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.96"></a><h3>date-time-compare</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (date-time-compare dt1 dt2))
- </pre></div>
- <p>A comparison function for <span class="type">GDateTimes</span> that is suitable
- as a <span class="type">GCompareFunc</span>. Both <span class="type">GDateTimes</span> must be non-<code class="constant">NULL</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.96.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>dt1</p></td>
- <td class="parameter_description">
- <p>first <span class="type">GDateTime</span> to compare</p>
- <p>Passed as <code class="code">dt1</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>dt2</p></td>
- <td class="parameter_description">
- <p>second <span class="type">GDateTime</span> to compare</p>
- <p>Passed as <code class="code">dt2</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.97"></a><h3>date-time-equal?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (date-time-equal? dt1 dt2))
- </pre></div>
- <p>Checks to see if <em class="parameter"><code>dt1</code></em> and <em class="parameter"><code>dt2</code></em> are equal.
- </p>
- <p>Equal here means that they represent the same moment after converting
- them to the same time zone.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.97.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>dt1</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GDateTime</span></p>
- <p>Passed as <code class="code">dt1</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>dt2</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GDateTime</span></p>
- <p>Passed as <code class="code">dt2</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.98"></a><h3>date-time-hash</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (date-time-hash datetime))
- </pre></div>
- <p>Hashes <em class="parameter"><code>datetime</code></em> into a <span class="type">guint</span>, suitable for use within <span class="type">GHashTable</span>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.98.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>datetime</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GDateTime</span></p>
- <p>Passed as <code class="code">datetime</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.99"></a><h3>date-valid-day?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (date-valid-day? day))
- </pre></div>
- <p>Returns <code class="constant">TRUE</code> if the day of the month is valid (a day is valid if it's
- between 1 and 31 inclusive).</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.99.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>day</p></td>
- <td class="parameter_description">
- <p>day to check</p>
- <p>Passed as <code class="code">day</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.100"></a><h3>date-valid-dmy?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (date-valid-dmy? day month year))
- </pre></div>
- <p>Returns <code class="constant">TRUE</code> if the day-month-year triplet forms a valid, existing day
- in the range of days <span class="type">GDate</span> understands (Year 1 or later, no more than
- a few thousand years in the future).</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.100.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>day</p></td>
- <td class="parameter_description">
- <p>day</p>
- <p>Passed as <code class="code">day</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>month</p></td>
- <td class="parameter_description">
- <p>month</p>
- <p>Passed as <code class="code">month</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>year</p></td>
- <td class="parameter_description">
- <p>year</p>
- <p>Passed as <code class="code">year</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.101"></a><h3>date-valid-julian?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (date-valid-julian? julian-date))
- </pre></div>
- <p>Returns <code class="constant">TRUE</code> if the Julian day is valid. Anything greater than zero
- is basically a valid Julian, though there is a 32-bit limit.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.101.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>julian_date</p></td>
- <td class="parameter_description">
- <p>Julian day to check</p>
- <p>Passed as <code class="code">julian-date</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.102"></a><h3>date-valid-month?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (date-valid-month? month))
- </pre></div>
- <p>Returns <code class="constant">TRUE</code> if the month value is valid. The 12 <span class="type">GDateMonth</span>
- enumeration values are the only valid months.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.102.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>month</p></td>
- <td class="parameter_description">
- <p>month</p>
- <p>Passed as <code class="code">month</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.103"></a><h3>date-valid-weekday?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (date-valid-weekday? weekday))
- </pre></div>
- <p>Returns <code class="constant">TRUE</code> if the weekday is valid. The seven <span class="type">GDateWeekday</span> enumeration
- values are the only valid weekdays.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.103.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>weekday</p></td>
- <td class="parameter_description">
- <p>weekday</p>
- <p>Passed as <code class="code">weekday</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.104"></a><h3>date-valid-year?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (date-valid-year? year))
- </pre></div>
- <p>Returns <code class="constant">TRUE</code> if the year is valid. Any year greater than 0 is valid,
- though there is a 16-bit limit to what <span class="type">GDate</span> will understand.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.104.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>year</p></td>
- <td class="parameter_description">
- <p>year</p>
- <p>Passed as <code class="code">year</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.105"></a><h3>dcgettext</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (dcgettext domain msgid category))
- </pre></div>
- <p>This is a variant of <code class="function">g_dgettext()</code> that allows specifying a locale
- category instead of always using <code class="code">LC_MESSAGES</code>. See <code class="function">g_dgettext()</code> for
- more information about how this functions differs from calling
- <code class="function">dcgettext()</code> directly.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.105.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>domain</p></td>
- <td class="parameter_description">
- <p>the translation domain to use, or <code class="constant">NULL</code> to use
- the domain set with <code class="function">textdomain()</code></p>
- <p>Passed as <code class="code">domain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>msgid</p></td>
- <td class="parameter_description">
- <p>message to translate</p>
- <p>Passed as <code class="code">msgid</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>category</p></td>
- <td class="parameter_description">
- <p>a locale category</p>
- <p>Passed as <code class="code">category</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.106"></a><h3>dgettext</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (dgettext domain msgid))
- </pre></div>
- <p>This function is a wrapper of <code class="function">dgettext()</code> which does not translate
- the message if the default domain as set with <code class="function">textdomain()</code> has no
- translations for the current locale.
- </p>
- <p>The advantage of using this function over <code class="function">dgettext()</code> proper is that
- libraries using this function (like GTK+) will not use translations
- if the application using the library does not have translations for
- the current locale. This results in a consistent English-only
- interface instead of one having partial translations. For this
- feature to work, the call to <code class="function">textdomain()</code> and <code class="function">setlocale()</code> should
- precede any <code class="function">g_dgettext()</code> invocations. For GTK+, it means calling
- <code class="function">textdomain()</code> before gtk_init or its variants.
- </p>
- <p>This function disables translations if and only if upon its first
- call all the following conditions hold:
- </p>
- <p>- <em class="parameter"><code>domain</code></em> is not <code class="constant">NULL</code>
- </p>
- <p>- <code class="function">textdomain()</code> has been called to set a default text domain
- </p>
- <p>- there is no translations available for the default text domain
- and the current locale
- </p>
- <p>- current locale is not "C" or any English locales (those
- starting with "en_")
- </p>
- <p>Note that this behavior may not be desired for example if an application
- has its untranslated messages in a language other than English. In those
- cases the application should call <code class="function">textdomain()</code> after initializing GTK+.
- </p>
- <p>Applications should normally not use this function directly,
- but use the <code class="function">_()</code> macro for translations.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.106.12"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>domain</p></td>
- <td class="parameter_description">
- <p>the translation domain to use, or <code class="constant">NULL</code> to use
- the domain set with <code class="function">textdomain()</code></p>
- <p>Passed as <code class="code">domain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>msgid</p></td>
- <td class="parameter_description">
- <p>message to translate</p>
- <p>Passed as <code class="code">msgid</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.107"></a><h3>dir-make-tmp</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (dir-make-tmp tmpl))
- </pre></div>
- <p>Creates a subdirectory in the preferred directory for temporary
- files (as returned by <code class="function">g_get_tmp_dir()</code>).
- </p>
- <p><em class="parameter"><code>tmpl</code></em> should be a string in the GLib file name encoding containing
- a sequence of six 'X' characters, as the parameter to <code class="function">g_mkstemp()</code>.
- However, unlike these functions, the template should only be a
- basename, no directory components are allowed. If template is
- <code class="constant">NULL</code>, a default template is used.
- </p>
- <p>Note that in contrast to <code class="function">g_mkdtemp()</code> (and <code class="function">mkdtemp()</code>) <em class="parameter"><code>tmpl</code></em> is not
- modified, and might thus be a read-only literal string.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.107.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>tmpl</p></td>
- <td class="parameter_description">
- <p>Template for directory name,
- as in <code class="function">g_mkdtemp()</code>, basename only, or <code class="constant">NULL</code> for a default template</p>
- <p>Passed as <code class="code">tmpl</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.108"></a><h3>direct-equal?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (direct-equal? v1 v2))
- </pre></div>
- <p>Compares two <span class="type">gpointer</span> arguments and returns <code class="constant">TRUE</code> if they are equal.
- It can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>key_equal_func</code></em>
- parameter, when using opaque pointers compared by pointer value as
- keys in a <span class="type">GHashTable</span>.
- </p>
- <p>This equality function is also appropriate for keys that are integers
- stored in pointers, such as <code class="code">GINT_TO_POINTER (n)</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.108.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>v1</p></td>
- <td class="parameter_description">
- <p>a key</p>
- <p>Passed as <code class="code">v1</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>v2</p></td>
- <td class="parameter_description">
- <p>a key to compare with <em class="parameter"><code>v1</code></em></p>
- <p>Passed as <code class="code">v2</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.109"></a><h3>direct-hash</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (direct-hash v))
- </pre></div>
- <p>Converts a gpointer to a hash value.
- It can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>hash_func</code></em> parameter,
- when using opaque pointers compared by pointer value as keys in a
- <span class="type">GHashTable</span>.
- </p>
- <p>This hash function is also appropriate for keys that are integers
- stored in pointers, such as <code class="code">GINT_TO_POINTER (n)</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.109.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>v</p></td>
- <td class="parameter_description">
- <p>a <span class="type">gpointer</span> key</p>
- <p>Passed as <code class="code">v</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.110"></a><h3>dngettext</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (dngettext domain msgid msgid-plural n))
- </pre></div>
- <p>This function is a wrapper of <code class="function">dngettext()</code> which does not translate
- the message if the default domain as set with <code class="function">textdomain()</code> has no
- translations for the current locale.
- </p>
- <p>See <code class="function">g_dgettext()</code> for details of how this differs from <code class="function">dngettext()</code>
- proper.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.110.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>domain</p></td>
- <td class="parameter_description">
- <p>the translation domain to use, or <code class="constant">NULL</code> to use
- the domain set with <code class="function">textdomain()</code></p>
- <p>Passed as <code class="code">domain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>msgid</p></td>
- <td class="parameter_description">
- <p>message to translate</p>
- <p>Passed as <code class="code">msgid</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>msgid_plural</p></td>
- <td class="parameter_description">
- <p>plural form of the message</p>
- <p>Passed as <code class="code">msgid-plural</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>n</p></td>
- <td class="parameter_description">
- <p>the quantity for which translation is needed</p>
- <p>Passed as <code class="code">n</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.111"></a><h3>double-equal?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (double-equal? v1 v2))
- </pre></div>
- <p>Compares the two <span class="type">gdouble</span> values being pointed to and returns
- <code class="constant">TRUE</code> if they are equal.
- It can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>key_equal_func</code></em>
- parameter, when using non-<code class="constant">NULL</code> pointers to doubles as keys in a
- <span class="type">GHashTable</span>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.111.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>v1</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gdouble</span> key</p>
- <p>Passed as <code class="code">v1</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>v2</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gdouble</span> key to compare with <em class="parameter"><code>v1</code></em></p>
- <p>Passed as <code class="code">v2</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.112"></a><h3>double-hash</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (double-hash v))
- </pre></div>
- <p>Converts a pointer to a <span class="type">gdouble</span> to a hash value.
- It can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>hash_func</code></em> parameter,
- It can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>hash_func</code></em> parameter,
- when using non-<code class="constant">NULL</code> pointers to doubles as keys in a <span class="type">GHashTable</span>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.112.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>v</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gdouble</span> key</p>
- <p>Passed as <code class="code">v</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.113"></a><h3>dpgettext</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (dpgettext domain msgctxtid msgidoffset))
- </pre></div>
- <p>This function is a variant of <code class="function">g_dgettext()</code> which supports
- a disambiguating message context. GNU gettext uses the
- '\004' character to separate the message context and
- message id in <em class="parameter"><code>msgctxtid</code></em>.
- If 0 is passed as <em class="parameter"><code>msgidoffset</code></em>, this function will fall back to
- trying to use the deprecated convention of using "|" as a separation
- character.
- </p>
- <p>This uses <code class="function">g_dgettext()</code> internally. See that functions for differences
- with <code class="function">dgettext()</code> proper.
- </p>
- <p>Applications should normally not use this function directly,
- but use the <code class="function">C_()</code> macro for translations with context.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.113.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>domain</p></td>
- <td class="parameter_description">
- <p>the translation domain to use, or <code class="constant">NULL</code> to use
- the domain set with <code class="function">textdomain()</code></p>
- <p>Passed as <code class="code">domain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>msgctxtid</p></td>
- <td class="parameter_description">
- <p>a combined message context and message id, separated
- by a \004 character</p>
- <p>Passed as <code class="code">msgctxtid</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>msgidoffset</p></td>
- <td class="parameter_description">
- <p>the offset of the message id in <em class="parameter"><code>msgctxid</code></em></p>
- <p>Passed as <code class="code">msgidoffset</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.114"></a><h3>dpgettext2</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (dpgettext2 domain context msgid))
- </pre></div>
- <p>This function is a variant of <code class="function">g_dgettext()</code> which supports
- a disambiguating message context. GNU gettext uses the
- '\004' character to separate the message context and
- message id in <em class="parameter"><code>msgctxtid</code></em>.
- </p>
- <p>This uses <code class="function">g_dgettext()</code> internally. See that functions for differences
- with <code class="function">dgettext()</code> proper.
- </p>
- <p>This function differs from <code class="function">C_()</code> in that it is not a macro and
- thus you may use non-string-literals as context and msgid arguments.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.114.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>domain</p></td>
- <td class="parameter_description">
- <p>the translation domain to use, or <code class="constant">NULL</code> to use
- the domain set with <code class="function">textdomain()</code></p>
- <p>Passed as <code class="code">domain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>context</p></td>
- <td class="parameter_description">
- <p>the message context</p>
- <p>Passed as <code class="code">context</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>msgid</p></td>
- <td class="parameter_description">
- <p>the message</p>
- <p>Passed as <code class="code">msgid</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.115"></a><h3>environ-getenv</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (environ-getenv envp variable))
- </pre></div>
- <p>Returns the value of the environment variable <em class="parameter"><code>variable</code></em> in the
- provided list <em class="parameter"><code>envp</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.115.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>envp</p></td>
- <td class="parameter_description">
- <p>
- </p>
- <p>an environment list (eg, as returned from <code class="function">g_get_environ()</code>), or <code class="constant">NULL</code>
- for an empty environment list</p>
- <p>Passed as <code class="code">envp</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>variable</p></td>
- <td class="parameter_description">
- <p>the environment variable to get</p>
- <p>Passed as <code class="code">variable</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.116"></a><h3>environ-setenv</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (environ-setenv envp variable value overwrite))
- </pre></div>
- <p>Sets the environment variable <em class="parameter"><code>variable</code></em> in the provided list
- <em class="parameter"><code>envp</code></em> to <em class="parameter"><code>value</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.116.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>envp</p></td>
- <td class="parameter_description">
- <p>
- </p>
- <p>an environment list that can be freed using <code class="function">g_strfreev()</code> (e.g., as
- returned from <code class="function">g_get_environ()</code>), or <code class="constant">NULL</code> for an empty
- environment list</p>
- <p>Passed as <code class="code">envp</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>variable</p></td>
- <td class="parameter_description">
- <p>the environment variable to set, must not
- contain '='</p>
- <p>Passed as <code class="code">variable</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>value</p></td>
- <td class="parameter_description">
- <p>the value for to set the variable to</p>
- <p>Passed as <code class="code">value</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>overwrite</p></td>
- <td class="parameter_description">
- <p>whether to change the variable if it already exists</p>
- <p>Passed as <code class="code">overwrite</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.117"></a><h3>environ-unsetenv</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (environ-unsetenv envp variable))
- </pre></div>
- <p>Removes the environment variable <em class="parameter"><code>variable</code></em> from the provided
- environment <em class="parameter"><code>envp</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.117.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>envp</p></td>
- <td class="parameter_description">
- <p>
- </p>
- <p>an environment list that can be freed using <code class="function">g_strfreev()</code> (e.g., as
- returned from <code class="function">g_get_environ()</code>), or <code class="constant">NULL</code> for an empty environment list</p>
- <p>Passed as <code class="code">envp</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>variable</p></td>
- <td class="parameter_description">
- <p>the environment variable to remove, must not
- contain '='</p>
- <p>Passed as <code class="code">variable</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.118"></a><h3>file-error-from-errno</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (file-error-from-errno err-no))
- </pre></div>
- <p>Gets a <span class="type">GFileError</span> constant based on the passed-in <em class="parameter"><code>err_no</code></em>.
- For example, if you pass in <code class="code">EEXIST</code> this function returns
- <span class="type">G_FILE_ERROR_EXIST</span>. Unlike <code class="code">errno</code> values, you can portably
- assume that all <span class="type">GFileError</span> values will exist.
- </p>
- <p>Normally a <span class="type">GFileError</span> value goes into a <span class="type">GError</span> returned
- from a function that manipulates files. So you would use
- <code class="function">g_file_error_from_errno()</code> when constructing a <span class="type">GError</span>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.118.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>err_no</p></td>
- <td class="parameter_description">
- <p>an "errno" value</p>
- <p>Passed as <code class="code">err-no</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.119"></a><h3>file-error-quark</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (file-error-quark))
- </pre></div>
- <p>Undocumented</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.120"></a><h3>file-get-contents</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return contents length) (file-get-contents filename))
- </pre></div>
- <p>Reads an entire file into allocated memory, with good error
- checking.
- </p>
- <p>If the call was successful, it returns <code class="constant">TRUE</code> and sets <em class="parameter"><code>contents</code></em> to the file
- contents and <em class="parameter"><code>length</code></em> to the length of the file contents in bytes. The string
- stored in <em class="parameter"><code>contents</code></em> will be nul-terminated, so for text files you can pass
- <code class="constant">NULL</code> for the <em class="parameter"><code>length</code></em> argument. If the call was not successful, it returns
- <code class="constant">FALSE</code> and sets <em class="parameter"><code>error</code></em>. The error domain is <span class="type">G_FILE_ERROR</span>. Possible error
- codes are those in the <span class="type">GFileError</span> enumeration. In the error case,
- <em class="parameter"><code>contents</code></em> is set to <code class="constant">NULL</code> and <em class="parameter"><code>length</code></em> is set to zero.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.120.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>filename</p></td>
- <td class="parameter_description">
- <p>name of a file to read contents from, in the GLib file name encoding</p>
- <p>Passed as <code class="code">filename</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>contents</p></td>
- <td class="parameter_description">
- <p>location to store an allocated string, use <code class="function">g_free()</code> to free
- the returned string</p>
- <p>Passed as <code class="code">contents</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>length</p></td>
- <td class="parameter_description">
- <p>location to store length in bytes of the contents, or <code class="constant">NULL</code></p>
- <p>Inferred from <code class="code">contents</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.121"></a><h3>file-open-tmp</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return name-used) (file-open-tmp tmpl))
- </pre></div>
- <p>Opens a file for writing in the preferred directory for temporary
- files (as returned by <code class="function">g_get_tmp_dir()</code>).
- </p>
- <p><em class="parameter"><code>tmpl</code></em> should be a string in the GLib file name encoding containing
- a sequence of six 'X' characters, as the parameter to <code class="function">g_mkstemp()</code>.
- However, unlike these functions, the template should only be a
- basename, no directory components are allowed. If template is
- <code class="constant">NULL</code>, a default template is used.
- </p>
- <p>Note that in contrast to <code class="function">g_mkstemp()</code> (and <code class="function">mkstemp()</code>) <em class="parameter"><code>tmpl</code></em> is not
- modified, and might thus be a read-only literal string.
- </p>
- <p>Upon success, and if <em class="parameter"><code>name_used</code></em> is non-<code class="constant">NULL</code>, the actual name used
- is returned in <em class="parameter"><code>name_used</code></em>. This string should be freed with <code class="function">g_free()</code>
- when not needed any longer. The returned name is in the GLib file
- name encoding.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.121.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>tmpl</p></td>
- <td class="parameter_description">
- <p>Template for file name, as in
- <code class="function">g_mkstemp()</code>, basename only, or <code class="constant">NULL</code> for a default template</p>
- <p>Passed as <code class="code">tmpl</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>name_used</p></td>
- <td class="parameter_description">
- <p>location to store actual name used,
- or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">name-used</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.122"></a><h3>file-read-link</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (file-read-link filename))
- </pre></div>
- <p>Reads the contents of the symbolic link <em class="parameter"><code>filename</code></em> like the POSIX
- <code class="function">readlink()</code> function. The returned string is in the encoding used
- for filenames. Use <code class="function">g_filename_to_utf8()</code> to convert it to UTF-8.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.122.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>filename</p></td>
- <td class="parameter_description">
- <p>the symbolic link</p>
- <p>Passed as <code class="code">filename</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.123"></a><h3>file-set-contents?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (file-set-contents? filename contents))
- </pre></div>
- <p>Writes all of <em class="parameter"><code>contents</code></em> to a file named <em class="parameter"><code>filename</code></em>. This is a convenience
- wrapper around calling <code class="function">g_file_set_contents()</code> with <code class="code">flags</code> set to
- <code class="code">G_FILE_SET_CONTENTS_CONSISTENT | G_FILE_SET_CONTENTS_ONLY_EXISTING</code> and
- <code class="code">mode</code> set to <code class="code">0666</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.123.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>filename</p></td>
- <td class="parameter_description">
- <p>name of a file to write <em class="parameter"><code>contents</code></em> to, in the GLib file name
- encoding</p>
- <p>Passed as <code class="code">filename</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>contents</p></td>
- <td class="parameter_description">
- <p>string to write to the file</p>
- <p>Passed as <code class="code">contents</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>length</p></td>
- <td class="parameter_description">
- <p>length of <em class="parameter"><code>contents</code></em>, or -1 if <em class="parameter"><code>contents</code></em> is a nul-terminated string</p>
- <p>Inferred from <code class="code">contents</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.124"></a><h3>file-set-contents-full?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (file-set-contents-full? filename contents flags mode))
- </pre></div>
- <p>Writes all of <em class="parameter"><code>contents</code></em> to a file named <em class="parameter"><code>filename</code></em>, with good error checking.
- If a file called <em class="parameter"><code>filename</code></em> already exists it will be overwritten.
- </p>
- <p><em class="parameter"><code>flags</code></em> control the properties of the write operation: whether it’s atomic,
- and what the tradeoff is between returning quickly or being resilient to
- system crashes.
- </p>
- <p>As this function performs file I/O, it is recommended to not call it anywhere
- where blocking would cause problems, such as in the main loop of a graphical
- application. In particular, if <em class="parameter"><code>flags</code></em> has any value other than
- <code class="constant">G_FILE_SET_CONTENTS_NONE</code> then this function may call <code class="code">fsync()</code>.
- </p>
- <p>If <code class="constant">G_FILE_SET_CONTENTS_CONSISTENT</code> is set in <em class="parameter"><code>flags</code></em>, the operation is atomic
- in the sense that it is first written to a temporary file which is then
- renamed to the final name.
- </p>
- <p>Notes:
- </p>
- <p>- On UNIX, if <em class="parameter"><code>filename</code></em> already exists hard links to <em class="parameter"><code>filename</code></em> will break.
- Also since the file is recreated, existing permissions, access control
- lists, metadata etc. may be lost. If <em class="parameter"><code>filename</code></em> is a symbolic link,
- the link itself will be replaced, not the linked file.
- </p>
- <p>- On UNIX, if <em class="parameter"><code>filename</code></em> already exists and is non-empty, and if the system
- supports it (via a journalling filesystem or equivalent), and if
- <code class="constant">G_FILE_SET_CONTENTS_CONSISTENT</code> is set in <em class="parameter"><code>flags</code></em>, the <code class="code">fsync()</code> call (or
- equivalent) will be used to ensure atomic replacement: <em class="parameter"><code>filename</code></em>
- will contain either its old contents or <em class="parameter"><code>contents</code></em>, even in the face of
- system power loss, the disk being unsafely removed, etc.
- </p>
- <p>- On UNIX, if <em class="parameter"><code>filename</code></em> does not already exist or is empty, there is a
- possibility that system power loss etc. after calling this function will
- leave <em class="parameter"><code>filename</code></em> empty or full of NUL bytes, depending on the underlying
- filesystem, unless <code class="constant">G_FILE_SET_CONTENTS_DURABLE</code> and
- <code class="constant">G_FILE_SET_CONTENTS_CONSISTENT</code> are set in <em class="parameter"><code>flags</code></em>.
- </p>
- <p>- On Windows renaming a file will not remove an existing file with the
- new name, so on Windows there is a race condition between the existing
- file being removed and the temporary file being renamed.
- </p>
- <p>- On Windows there is no way to remove a file that is open to some
- process, or mapped into memory. Thus, this function will fail if
- <em class="parameter"><code>filename</code></em> already exists and is open.
- </p>
- <p>If the call was successful, it returns <code class="constant">TRUE</code>. If the call was not successful,
- it returns <code class="constant">FALSE</code> and sets <em class="parameter"><code>error</code></em>. The error domain is <span class="type">G_FILE_ERROR</span>.
- Possible error codes are those in the <span class="type">GFileError</span> enumeration.
- </p>
- <p>Note that the name for the temporary file is constructed by appending up
- to 7 characters to <em class="parameter"><code>filename</code></em>.
- </p>
- <p>If the file didn’t exist before and is created, it will be given the
- permissions from <em class="parameter"><code>mode</code></em>. Otherwise, the permissions of the existing file may
- be changed to <em class="parameter"><code>mode</code></em> depending on <em class="parameter"><code>flags</code></em>, or they may remain unchanged.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.124.16"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>filename</p></td>
- <td class="parameter_description">
- <p>name of a file to write <em class="parameter"><code>contents</code></em> to, in the GLib file name
- encoding</p>
- <p>Passed as <code class="code">filename</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>contents</p></td>
- <td class="parameter_description">
- <p>string to write to the file</p>
- <p>Passed as <code class="code">contents</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>length</p></td>
- <td class="parameter_description">
- <p>length of <em class="parameter"><code>contents</code></em>, or -1 if <em class="parameter"><code>contents</code></em> is a nul-terminated string</p>
- <p>Inferred from <code class="code">contents</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>flags</p></td>
- <td class="parameter_description">
- <p>flags controlling the safety vs speed of the operation</p>
- <p>Passed as <code class="code">flags</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>mode</p></td>
- <td class="parameter_description">
- <p>file mode, as passed to <code class="code">open()</code>; typically this will be <code class="code">0666</code></p>
- <p>Passed as <code class="code">mode</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.125"></a><h3>file-test?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (file-test? filename test))
- </pre></div>
- <p>Returns <code class="constant">TRUE</code> if any of the tests in the bitfield <em class="parameter"><code>test</code></em> are
- <code class="constant">TRUE</code>. For example, <code class="code">(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)</code>
- will return <code class="constant">TRUE</code> if the file exists; the check whether it's a
- directory doesn't matter since the existence test is <code class="constant">TRUE</code>. With
- the current set of available tests, there's no point passing in
- more than one test at a time.
- </p>
- <p>Apart from <code class="constant">G_FILE_TEST_IS_SYMLINK</code> all tests follow symbolic links,
- so for a symbolic link to a regular file <code class="function">g_file_test()</code> will return
- <code class="constant">TRUE</code> for both <code class="constant">G_FILE_TEST_IS_SYMLINK</code> and <code class="constant">G_FILE_TEST_IS_REGULAR</code>.
- </p>
- <p>Note, that for a dangling symbolic link <code class="function">g_file_test()</code> will return
- <code class="constant">TRUE</code> for <code class="constant">G_FILE_TEST_IS_SYMLINK</code> and <code class="constant">FALSE</code> for all other flags.
- </p>
- <p>You should never use <code class="function">g_file_test()</code> to test whether it is safe
- to perform an operation, because there is always the possibility
- of the condition changing before you actually perform the operation.
- For example, you might think you could use <code class="constant">G_FILE_TEST_IS_SYMLINK</code>
- to know whether it is safe to write to a file without being
- tricked into writing into a different location. It doesn't work!
- </p>
- <div class="informalexample"><pre class="programlisting">
- // DON'T DO THIS
- if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK))
- {
- fd = g_open (filename, O_WRONLY);
- // write to fd
- }
- </pre></div>
- <p>Another thing to note is that <code class="constant">G_FILE_TEST_EXISTS</code> and
- <code class="constant">G_FILE_TEST_IS_EXECUTABLE</code> are implemented using the <code class="function">access()</code>
- system call. This usually doesn't matter, but if your program
- is setuid or setgid it means that these tests will give you
- the answer for the real user ID and group ID, rather than the
- effective user ID and group ID.
- </p>
- <p>On Windows, there are no symlinks, so testing for
- <code class="constant">G_FILE_TEST_IS_SYMLINK</code> will always return <code class="constant">FALSE</code>. Testing for
- <code class="constant">G_FILE_TEST_IS_EXECUTABLE</code> will just check that the file exists and
- its name indicates that it is executable, checking for well-known
- extensions and those listed in the <code class="code">PATHEXT</code> environment variable.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.125.9"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>filename</p></td>
- <td class="parameter_description">
- <p>a filename to test in the
- GLib file name encoding</p>
- <p>Passed as <code class="code">filename</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>test</p></td>
- <td class="parameter_description">
- <p>bitfield of <span class="type">GFileTest</span> flags</p>
- <p>Passed as <code class="code">test</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.126"></a><h3>filename-display-basename</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (filename-display-basename filename))
- </pre></div>
- <p>Returns the display basename for the particular filename, guaranteed
- to be valid UTF-8. The display name might not be identical to the filename,
- for instance there might be problems converting it to UTF-8, and some files
- can be translated in the display.
- </p>
- <p>If GLib cannot make sense of the encoding of <em class="parameter"><code>filename</code></em>, as a last resort it
- replaces unknown characters with U+FFFD, the Unicode replacement character.
- You can search the result for the UTF-8 encoding of this character (which is
- "\357\277\275" in octal notation) to find out if <em class="parameter"><code>filename</code></em> was in an invalid
- encoding.
- </p>
- <p>You must pass the whole absolute pathname to this functions so that
- translation of well known locations can be done.
- </p>
- <p>This function is preferred over <code class="function">g_filename_display_name()</code> if you know the
- whole path, as it allows translation.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.126.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>filename</p></td>
- <td class="parameter_description">
- <p>an absolute pathname in the
- GLib file name encoding</p>
- <p>Passed as <code class="code">filename</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.127"></a><h3>filename-display-name</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (filename-display-name filename))
- </pre></div>
- <p>Converts a filename into a valid UTF-8 string. The conversion is
- not necessarily reversible, so you should keep the original around
- and use the return value of this function only for display purposes.
- Unlike <code class="function">g_filename_to_utf8()</code>, the result is guaranteed to be non-<code class="constant">NULL</code>
- even if the filename actually isn't in the GLib file name encoding.
- </p>
- <p>If GLib cannot make sense of the encoding of <em class="parameter"><code>filename</code></em>, as a last resort it
- replaces unknown characters with U+FFFD, the Unicode replacement character.
- You can search the result for the UTF-8 encoding of this character (which is
- "\357\277\275" in octal notation) to find out if <em class="parameter"><code>filename</code></em> was in an invalid
- encoding.
- </p>
- <p>If you know the whole pathname of the file you should use
- <code class="function">g_filename_display_basename()</code>, since that allows location-based
- translation of filenames.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.127.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>filename</p></td>
- <td class="parameter_description">
- <p>a pathname hopefully in the
- GLib file name encoding</p>
- <p>Passed as <code class="code">filename</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.128"></a><h3>filename-from-uri</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return hostname) (filename-from-uri uri))
- </pre></div>
- <p>Converts an escaped ASCII-encoded URI to a local filename in the
- encoding used for filenames.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.128.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>uri</p></td>
- <td class="parameter_description">
- <p>a uri describing a filename (escaped, encoded in ASCII).</p>
- <p>Passed as <code class="code">uri</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>hostname</p></td>
- <td class="parameter_description">
- <p>Location to store hostname for the URI.
- If there is no hostname in the URI, <code class="constant">NULL</code> will be
- stored in this location.</p>
- <p>Passed as <code class="code">hostname</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.129"></a><h3>filename-from-utf8</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return bytes-read bytes-written)
- (filename-from-utf8 utf8string len))
- </pre></div>
- <p>Converts a string from UTF-8 to the encoding GLib uses for
- filenames. Note that on Windows GLib uses UTF-8 for filenames;
- on other platforms, this function indirectly depends on the
- [current locale][setlocale].
- </p>
- <p>The input string shall not contain nul characters even if the <em class="parameter"><code>len</code></em>
- argument is positive. A nul character found inside the string will result
- in error <code class="constant">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</code>. If the filename encoding is
- not UTF-8 and the conversion output contains a nul character, the error
- <code class="constant">G_CONVERT_ERROR_EMBEDDED_NUL</code> is set and the function returns <code class="constant">NULL</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.129.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>utf8string</p></td>
- <td class="parameter_description">
- <p>a UTF-8 encoded string.</p>
- <p>Passed as <code class="code">utf8string</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>the length of the string, or -1 if the string is
- nul-terminated.</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>bytes_read</p></td>
- <td class="parameter_description">
- <p>location to store the number of bytes in
- the input string that were successfully converted, or <code class="constant">NULL</code>.
- Even if the conversion was successful, this may be
- less than <em class="parameter"><code>len</code></em> if there were partial characters
- at the end of the input. If the error
- <code class="constant">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</code> occurs, the value
- stored will be the byte offset after the last valid
- input sequence.</p>
- <p>Passed as <code class="code">bytes-read</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>bytes_written</p></td>
- <td class="parameter_description">
- <p>the number of bytes stored in
- the output buffer (not including the terminating nul).</p>
- <p>Passed as <code class="code">bytes-written</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.130"></a><h3>filename-to-uri</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (filename-to-uri filename hostname))
- </pre></div>
- <p>Converts an absolute filename to an escaped ASCII-encoded URI, with the path
- component following Section 3.3. of RFC 2396.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.130.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>filename</p></td>
- <td class="parameter_description">
- <p>an absolute filename specified in the GLib file
- name encoding, which is the on-disk file name bytes on Unix, and UTF-8
- on Windows</p>
- <p>Passed as <code class="code">filename</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>hostname</p></td>
- <td class="parameter_description">
- <p>A UTF-8 encoded hostname, or <code class="constant">NULL</code> for none.</p>
- <p>Passed as <code class="code">hostname</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.131"></a><h3>filename-to-utf8</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return bytes-read bytes-written)
- (filename-to-utf8 opsysstring len))
- </pre></div>
- <p>Converts a string which is in the encoding used by GLib for
- filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8
- for filenames; on other platforms, this function indirectly depends on
- the [current locale][setlocale].
- </p>
- <p>The input string shall not contain nul characters even if the <em class="parameter"><code>len</code></em>
- argument is positive. A nul character found inside the string will result
- in error <code class="constant">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</code>.
- If the source encoding is not UTF-8 and the conversion output contains a
- nul character, the error <code class="constant">G_CONVERT_ERROR_EMBEDDED_NUL</code> is set and the
- function returns <code class="constant">NULL</code>. Use <code class="function">g_convert()</code> to produce output that
- may contain embedded nul characters.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.131.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>opsysstring</p></td>
- <td class="parameter_description">
- <p>a string in the encoding for filenames</p>
- <p>Passed as <code class="code">opsysstring</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>the length of the string, or -1 if the string is
- nul-terminated (Note that some encodings may allow nul
- bytes to occur inside strings. In that case, using -1
- for the <em class="parameter"><code>len</code></em> parameter is unsafe)</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>bytes_read</p></td>
- <td class="parameter_description">
- <p>location to store the number of bytes in the
- input string that were successfully converted, or <code class="constant">NULL</code>.
- Even if the conversion was successful, this may be
- less than <em class="parameter"><code>len</code></em> if there were partial characters
- at the end of the input. If the error
- <code class="constant">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</code> occurs, the value
- stored will be the byte offset after the last valid
- input sequence.</p>
- <p>Passed as <code class="code">bytes-read</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>bytes_written</p></td>
- <td class="parameter_description">
- <p>the number of bytes stored in the output
- buffer (not including the terminating nul).</p>
- <p>Passed as <code class="code">bytes-written</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.132"></a><h3>find-program-in-path</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (find-program-in-path program))
- </pre></div>
- <p>Locates the first executable named <em class="parameter"><code>program</code></em> in the user's path, in the
- same way that <code class="function">execvp()</code> would locate it. Returns an allocated string
- with the absolute path name, or <code class="constant">NULL</code> if the program is not found in
- the path. If <em class="parameter"><code>program</code></em> is already an absolute path, returns a copy of
- <em class="parameter"><code>program</code></em> if <em class="parameter"><code>program</code></em> exists and is executable, and <code class="constant">NULL</code> otherwise.
-
- On Windows, if <em class="parameter"><code>program</code></em> does not have a file type suffix, tries
- with the suffixes .exe, .cmd, .bat and .com, and the suffixes in
- the <code class="code">PATHEXT</code> environment variable.
- </p>
- <p>On Windows, it looks for the file in the same way as <code class="function">CreateProcess()</code>
- would. This means first in the directory where the executing
- program was loaded from, then in the current directory, then in the
- Windows 32-bit system directory, then in the Windows directory, and
- finally in the directories in the <code class="code">PATH</code> environment variable. If
- the program is found, the return value contains the full name
- including the type suffix.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.132.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>program</p></td>
- <td class="parameter_description">
- <p>a program name in the GLib file name encoding</p>
- <p>Passed as <code class="code">program</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.133"></a><h3>format-size</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (format-size size))
- </pre></div>
- <p>Formats a size (for example the size of a file) into a human readable
- string. Sizes are rounded to the nearest size prefix (kB, MB, GB)
- and are displayed rounded to the nearest tenth. E.g. the file size
- 3292528 bytes will be converted into the string "3.2 MB". The returned string
- is UTF-8, and may use a non-breaking space to separate the number and units,
- to ensure they aren’t separated when line wrapped.
- </p>
- <p>The prefix units base is 1000 (i.e. 1 kB is 1000 bytes).
- </p>
- <p>This string should be freed with <code class="function">g_free()</code> when not needed any longer.
- </p>
- <p>See <code class="function">g_format_size_full()</code> for more options about how the size might be
- formatted.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.133.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>size</p></td>
- <td class="parameter_description">
- <p>a size in bytes</p>
- <p>Passed as <code class="code">size</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.134"></a><h3>format-size-full</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (format-size-full size flags))
- </pre></div>
- <p>Formats a size.
- </p>
- <p>This function is similar to <code class="function">g_format_size()</code> but allows for flags
- that modify the output. See <span class="type">GFormatSizeFlags</span>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.134.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>size</p></td>
- <td class="parameter_description">
- <p>a size in bytes</p>
- <p>Passed as <code class="code">size</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>flags</p></td>
- <td class="parameter_description">
- <p><span class="type">GFormatSizeFlags</span> to modify the output</p>
- <p>Passed as <code class="code">flags</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.135"></a><h3>get-application-name</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-application-name))
- </pre></div>
- <p>Gets a human-readable name for the application, as set by
- <code class="function">g_set_application_name()</code>. This name should be localized if
- possible, and is intended for display to the user. Contrast with
- <code class="function">g_get_prgname()</code>, which gets a non-localized name. If
- <code class="function">g_set_application_name()</code> has not been called, returns the result of
- <code class="function">g_get_prgname()</code> (which may be <code class="constant">NULL</code> if <code class="function">g_set_prgname()</code> has also not
- been called).</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.136"></a><h3>get-charset</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return charset) (get-charset))
- </pre></div>
- <p>Obtains the character set for the [current locale][setlocale]; you
- might use this character set as an argument to <code class="function">g_convert()</code>, to convert
- from the current locale's encoding to some other encoding. (Frequently
- <code class="function">g_locale_to_utf8()</code> and <code class="function">g_locale_from_utf8()</code> are nice shortcuts, though.)
- </p>
- <p>On Windows the character set returned by this function is the
- so-called system default ANSI code-page. That is the character set
- used by the "narrow" versions of C library and Win32 functions that
- handle file names. It might be different from the character set
- used by the C library's current locale.
- </p>
- <p>On Linux, the character set is found by consulting <code class="function">nl_langinfo()</code> if
- available. If not, the environment variables <code class="code">LC_ALL</code>, <code class="code">LC_CTYPE</code>, <code class="code">LANG</code>
- and <code class="code">CHARSET</code> are queried in order.
- </p>
- <p>The return value is <code class="constant">TRUE</code> if the locale's encoding is UTF-8, in that
- case you can perhaps avoid calling <code class="function">g_convert()</code>.
- </p>
- <p>The string returned in <em class="parameter"><code>charset</code></em> is not allocated, and should not be
- freed.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.136.8"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>charset</p></td>
- <td class="parameter_description">
- <p>return location for character set
- name, or <code class="constant">NULL</code>.</p>
- <p>Passed as <code class="code">charset</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.137"></a><h3>get-codeset</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-codeset))
- </pre></div>
- <p>Gets the character set for the current locale.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.138"></a><h3>get-console-charset</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return charset) (get-console-charset))
- </pre></div>
- <p>Obtains the character set used by the console attached to the process,
- which is suitable for printing output to the terminal.
- </p>
- <p>Usually this matches the result returned by <code class="function">g_get_charset()</code>, but in
- environments where the locale's character set does not match the encoding
- of the console this function tries to guess a more suitable value instead.
- </p>
- <p>On Windows the character set returned by this function is the
- output code page used by the console associated with the calling process.
- If the codepage can't be determined (for example because there is no
- console attached) UTF-8 is assumed.
- </p>
- <p>The return value is <code class="constant">TRUE</code> if the locale's encoding is UTF-8, in that
- case you can perhaps avoid calling <code class="function">g_convert()</code>.
- </p>
- <p>The string returned in <em class="parameter"><code>charset</code></em> is not allocated, and should not be
- freed.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.138.8"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>charset</p></td>
- <td class="parameter_description">
- <p>return location for character set
- name, or <code class="constant">NULL</code>.</p>
- <p>Passed as <code class="code">charset</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.139"></a><h3>get-current-dir</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-current-dir))
- </pre></div>
- <p>Gets the current directory.
- </p>
- <p>The returned string should be freed when no longer needed.
- The encoding of the returned string is system defined.
- On Windows, it is always UTF-8.
- </p>
- <p>Since GLib 2.40, this function will return the value of the "PWD"
- environment variable if it is set and it happens to be the same as
- the current directory. This can make a difference in the case that
- the current directory is the target of a symbolic link.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.140"></a><h3>get-environ</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-environ))
- </pre></div>
- <p>Gets the list of environment variables for the current process.
- </p>
- <p>The list is <code class="constant">NULL</code> terminated and each item in the list is of the
- form 'NAME=VALUE'.
- </p>
- <p>This is equivalent to direct access to the 'environ' global variable,
- except portable.
- </p>
- <p>The return value is freshly allocated and it should be freed with
- <code class="function">g_strfreev()</code> when it is no longer needed.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.141"></a><h3>get-filename-charsets</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return filename-charsets) (get-filename-charsets))
- </pre></div>
- <p>Determines the preferred character sets used for filenames.
- The first character set from the <em class="parameter"><code>charsets</code></em> is the filename encoding, the
- subsequent character sets are used when trying to generate a displayable
- representation of a filename, see <code class="function">g_filename_display_name()</code>.
- </p>
- <p>On Unix, the character sets are determined by consulting the
- environment variables <code class="code">G_FILENAME_ENCODING</code> and <code class="code">G_BROKEN_FILENAMES</code>.
- On Windows, the character set used in the GLib API is always UTF-8
- and said environment variables have no effect.
- </p>
- <p><code class="code">G_FILENAME_ENCODING</code> may be set to a comma-separated list of
- character set names. The special token "\@locale" is taken
- to mean the character set for the [current locale][setlocale].
- If <code class="code">G_FILENAME_ENCODING</code> is not set, but <code class="code">G_BROKEN_FILENAMES</code> is,
- the character set of the current locale is taken as the filename
- encoding. If neither environment variable is set, UTF-8 is taken
- as the filename encoding, but the character set of the current locale
- is also put in the list of encodings.
- </p>
- <p>The returned <em class="parameter"><code>charsets</code></em> belong to GLib and must not be freed.
- </p>
- <p>Note that on Unix, regardless of the locale character set or
- <code class="code">G_FILENAME_ENCODING</code> value, the actual file names present
- on a system might be in any random encoding or just gibberish.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.141.8"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>filename_charsets</p></td>
- <td class="parameter_description">
- <p>
- </p>
- <p>return location for the <code class="constant">NULL</code>-terminated list of encoding names</p>
- <p>Passed as <code class="code">filename-charsets</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.142"></a><h3>get-home-dir</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-home-dir))
- </pre></div>
- <p>Gets the current user's home directory.
- </p>
- <p>As with most UNIX tools, this function will return the value of the
- <code class="code">HOME</code> environment variable if it is set to an existing absolute path
- name, falling back to the <code class="code">passwd</code> file in the case that it is unset.
- </p>
- <p>If the path given in <code class="code">HOME</code> is non-absolute, does not exist, or is
- not a directory, the result is undefined.
- </p>
- <p>Before version 2.36 this function would ignore the <code class="code">HOME</code> environment
- variable, taking the value from the <code class="code">passwd</code> database instead. This was
- changed to increase the compatibility of GLib with other programs (and
- the XDG basedir specification) and to increase testability of programs
- based on GLib (by making it easier to run them from test frameworks).
- </p>
- <p>If your program has a strong requirement for either the new or the
- old behaviour (and if you don't wish to increase your GLib
- dependency to ensure that the new behaviour is in effect) then you
- should either directly check the <code class="code">HOME</code> environment variable yourself
- or unset it before calling any functions in GLib.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.143"></a><h3>get-host-name</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-host-name))
- </pre></div>
- <p>Return a name for the machine.
- </p>
- <p>The returned name is not necessarily a fully-qualified domain name,
- or even present in DNS or some other name service at all. It need
- not even be unique on your local network or site, but usually it
- is. Callers should not rely on the return value having any specific
- properties like uniqueness for security purposes. Even if the name
- of the machine is changed while an application is running, the
- return value from this function does not change. The returned
- string is owned by GLib and should not be modified or freed. If no
- name can be determined, a default fixed string "localhost" is
- returned.
- </p>
- <p>The encoding of the returned string is UTF-8.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.144"></a><h3>get-language-names</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-language-names))
- </pre></div>
- <p>Computes a list of applicable locale names, which can be used to
- e.g. construct locale-dependent filenames or search paths. The returned
- list is sorted from most desirable to least desirable and always contains
- the default locale "C".
- </p>
- <p>For example, if LANGUAGE=de:en_US, then the returned list is
- "de", "en_US", "en", "C".
- </p>
- <p>This function consults the environment variables <code class="code">LANGUAGE</code>, <code class="code">LC_ALL</code>,
- <code class="code">LC_MESSAGES</code> and <code class="code">LANG</code> to find the list of locales specified by the
- user.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.145"></a><h3>get-language-names-with-category</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-language-names-with-category category-name))
- </pre></div>
- <p>Computes a list of applicable locale names with a locale category name,
- which can be used to construct the fallback locale-dependent filenames
- or search paths. The returned list is sorted from most desirable to
- least desirable and always contains the default locale "C".
- </p>
- <p>This function consults the environment variables <code class="code">LANGUAGE</code>, <code class="code">LC_ALL</code>,
- <em class="parameter"><code>category_name</code></em>, and <code class="code">LANG</code> to find the list of locales specified by the
- user.
- </p>
- <p><code class="function">g_get_language_names()</code> returns g_get_language_names_with_category("LC_MESSAGES").</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.145.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>category_name</p></td>
- <td class="parameter_description">
- <p>a locale category name</p>
- <p>Passed as <code class="code">category-name</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.146"></a><h3>get-locale-variants</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-locale-variants locale))
- </pre></div>
- <p>Returns a list of derived variants of <em class="parameter"><code>locale</code></em>, which can be used to
- e.g. construct locale-dependent filenames or search paths. The returned
- list is sorted from most desirable to least desirable.
- This function handles territory, charset and extra locale modifiers. See
- [<code class="code">setlocale(3)</code>](man:setlocale) for information about locales and their format.
- </p>
- <p><em class="parameter"><code>locale</code></em> itself is guaranteed to be returned in the output.
- </p>
- <p>For example, if <em class="parameter"><code>locale</code></em> is <code class="code">fr_BE</code>, then the returned list
- is <code class="code">fr_BE</code>, <code class="code">fr</code>. If <em class="parameter"><code>locale</code></em> is <code class="code">en_GB.UTF-8@euro</code>, then the returned list
- is <code class="code">en_GB.UTF-8@euro</code>, <code class="code">en_GB.UTF-8</code>, <code class="code">en_GB@euro</code>, <code class="code">en_GB</code>, <code class="code">en.UTF-8@euro</code>,
- <code class="code">en.UTF-8</code>, <code class="code">en@euro</code>, <code class="code">en</code>.
- </p>
- <p>If you need the list of variants for the current locale,
- use <code class="function">g_get_language_names()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.146.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>locale</p></td>
- <td class="parameter_description">
- <p>a locale identifier</p>
- <p>Passed as <code class="code">locale</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.147"></a><h3>get-monotonic-time</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-monotonic-time))
- </pre></div>
- <p>Queries the system monotonic time.
- </p>
- <p>The monotonic clock will always increase and doesn't suffer
- discontinuities when the user (or NTP) changes the system time. It
- may or may not continue to tick during times where the machine is
- suspended.
- </p>
- <p>We try to use the clock that corresponds as closely as possible to
- the passage of time as measured by system calls such as <code class="function">poll()</code> but it
- may not always be possible to do this.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.148"></a><h3>get-num-processors</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-num-processors))
- </pre></div>
- <p>Determine the approximate number of threads that the system will
- schedule simultaneously for this process. This is intended to be
- used as a parameter to <code class="function">g_thread_pool_new()</code> for CPU bound tasks and
- similar cases.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.149"></a><h3>get-os-info</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-os-info key-name))
- </pre></div>
- <p>Get information about the operating system.
- </p>
- <p>On Linux this comes from the <code class="code">/etc/os-release</code> file. On other systems, it may
- come from a variety of sources. You can either use the standard key names
- like <code class="constant">G_OS_INFO_KEY_NAME</code> or pass any UTF-8 string key name. For example,
- <code class="code">/etc/os-release</code> provides a number of other less commonly used values that may
- be useful. No key is guaranteed to be provided, so the caller should always
- check if the result is <code class="constant">NULL</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.149.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>key_name</p></td>
- <td class="parameter_description">
- <p>a key for the OS info being requested, for example <code class="constant">G_OS_INFO_KEY_NAME</code>.</p>
- <p>Passed as <code class="code">key-name</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.150"></a><h3>get-prgname</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-prgname))
- </pre></div>
- <p>Gets the name of the program. This name should not be localized,
- in contrast to <code class="function">g_get_application_name()</code>.
- </p>
- <p>If you are using <span class="type">GApplication</span> the program name is set in
- <code class="function">g_application_run()</code>. In case of GDK or GTK+ it is set in
- <code class="function">gdk_init()</code>, which is called by <code class="function">gtk_init()</code> and the
- <span class="type">“startup”</span> handler. The program name is found by
- taking the last component of <em class="parameter"><code>argv</code></em>[0].</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.151"></a><h3>get-real-name</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-real-name))
- </pre></div>
- <p>Gets the real name of the user. This usually comes from the user's
- entry in the <code class="code">passwd</code> file. The encoding of the returned string is
- system-defined. (On Windows, it is, however, always UTF-8.) If the
- real user name cannot be determined, the string "Unknown" is
- returned.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.152"></a><h3>get-real-time</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-real-time))
- </pre></div>
- <p>Queries the system wall-clock time.
- </p>
- <p>This call is functionally equivalent to <code class="function">g_get_current_time()</code> except
- that the return value is often more convenient than dealing with a
- <span class="type">GTimeVal</span>.
- </p>
- <p>You should only use this call if you are actually interested in the real
- wall-clock time. <code class="function">g_get_monotonic_time()</code> is probably more useful for
- measuring intervals.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.153"></a><h3>get-system-config-dirs</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-system-config-dirs))
- </pre></div>
- <p>Returns an ordered list of base directories in which to access
- system-wide configuration information.
- </p>
- <p>On UNIX platforms this is determined using the mechanisms described
- in the
- [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
- In this case the list of directories retrieved will be <code class="code">XDG_CONFIG_DIRS</code>.
- </p>
- <p>On Windows it follows XDG Base Directory Specification if <code class="code">XDG_CONFIG_DIRS</code> is defined.
- If <code class="code">XDG_CONFIG_DIRS</code> is undefined, the directory that contains application
- data for all users is used instead. A typical path is
- <code class="code">C:\Documents and Settings\All Users\Application Data</code>.
- This folder is used for application data
- that is not user specific. For example, an application can store
- a spell-check dictionary, a database of clip art, or a log file in the
- CSIDL_COMMON_APPDATA folder. This information will not roam and is available
- to anyone using the computer.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.154"></a><h3>get-system-data-dirs</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-system-data-dirs))
- </pre></div>
- <p>Returns an ordered list of base directories in which to access
- system-wide application data.
- </p>
- <p>On UNIX platforms this is determined using the mechanisms described
- in the
- [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec)
- In this case the list of directories retrieved will be <code class="code">XDG_DATA_DIRS</code>.
- </p>
- <p>On Windows it follows XDG Base Directory Specification if <code class="code">XDG_DATA_DIRS</code> is defined.
- If <code class="code">XDG_DATA_DIRS</code> is undefined,
- the first elements in the list are the Application Data
- and Documents folders for All Users. (These can be determined only
- on Windows 2000 or later and are not present in the list on other
- Windows versions.) See documentation for CSIDL_COMMON_APPDATA and
- CSIDL_COMMON_DOCUMENTS.
- </p>
- <p>Then follows the "share" subfolder in the installation folder for
- the package containing the DLL that calls this function, if it can
- be determined.
- </p>
- <p>Finally the list contains the "share" subfolder in the installation
- folder for GLib, and in the installation folder for the package the
- application's .exe file belongs to.
- </p>
- <p>The installation folders above are determined by looking up the
- folder where the module (DLL or EXE) in question is located. If the
- folder's name is "bin", its parent is used, otherwise the folder
- itself.
- </p>
- <p>Note that on Windows the returned list can vary depending on where
- this function is called.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.155"></a><h3>get-tmp-dir</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-tmp-dir))
- </pre></div>
- <p>Gets the directory to use for temporary files.
- </p>
- <p>On UNIX, this is taken from the <code class="code">TMPDIR</code> environment variable.
- If the variable is not set, <code class="code">P_tmpdir</code> is
- used, as defined by the system C library. Failing that, a
- hard-coded default of "/tmp" is returned.
- </p>
- <p>On Windows, the <code class="code">TEMP</code> environment variable is used, with the
- root directory of the Windows installation (eg: "C:\") used
- as a default.
- </p>
- <p>The encoding of the returned string is system-defined. On Windows,
- it is always UTF-8. The return value is never <code class="constant">NULL</code> or the empty
- string.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.156"></a><h3>get-user-cache-dir</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-user-cache-dir))
- </pre></div>
- <p>Returns a base directory in which to store non-essential, cached
- data specific to particular user.
- </p>
- <p>On UNIX platforms this is determined using the mechanisms described
- in the
- [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
- In this case the directory retrieved will be <code class="code">XDG_CACHE_HOME</code>.
- </p>
- <p>On Windows it follows XDG Base Directory Specification if <code class="code">XDG_CACHE_HOME</code> is defined.
- If <code class="code">XDG_CACHE_HOME</code> is undefined, the directory that serves as a common
- repository for temporary Internet files is used instead. A typical path is
- <code class="code">C:\Documents and Settings\username\Local Settings\Temporary Internet Files</code>.
- See the [documentation for <code class="code">CSIDL_INTERNET_CACHE</code>](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_internet_cache).</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.157"></a><h3>get-user-config-dir</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-user-config-dir))
- </pre></div>
- <p>Returns a base directory in which to store user-specific application
- configuration information such as user preferences and settings.
- </p>
- <p>On UNIX platforms this is determined using the mechanisms described
- in the
- [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
- In this case the directory retrieved will be <code class="code">XDG_CONFIG_HOME</code>.
- </p>
- <p>On Windows it follows XDG Base Directory Specification if <code class="code">XDG_CONFIG_HOME</code> is defined.
- If <code class="code">XDG_CONFIG_HOME</code> is undefined, the folder to use for local (as opposed
- to roaming) application data is used instead. See the
- [documentation for <code class="code">CSIDL_LOCAL_APPDATA</code>](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_local_appdata).
- Note that in this case on Windows it will be the same
- as what <code class="function">g_get_user_data_dir()</code> returns.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.158"></a><h3>get-user-data-dir</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-user-data-dir))
- </pre></div>
- <p>Returns a base directory in which to access application data such
- as icons that is customized for a particular user.
- </p>
- <p>On UNIX platforms this is determined using the mechanisms described
- in the
- [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
- In this case the directory retrieved will be <code class="code">XDG_DATA_HOME</code>.
- </p>
- <p>On Windows it follows XDG Base Directory Specification if <code class="code">XDG_DATA_HOME</code>
- is defined. If <code class="code">XDG_DATA_HOME</code> is undefined, the folder to use for local (as
- opposed to roaming) application data is used instead. See the
- [documentation for <code class="code">CSIDL_LOCAL_APPDATA</code>](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_local_appdata).
- Note that in this case on Windows it will be the same
- as what <code class="function">g_get_user_config_dir()</code> returns.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.159"></a><h3>get-user-name</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-user-name))
- </pre></div>
- <p>Gets the user name of the current user. The encoding of the returned
- string is system-defined. On UNIX, it might be the preferred file name
- encoding, or something else, and there is no guarantee that it is even
- consistent on a machine. On Windows, it is always UTF-8.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.160"></a><h3>get-user-runtime-dir</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-user-runtime-dir))
- </pre></div>
- <p>Returns a directory that is unique to the current user on the local
- system.
- </p>
- <p>This is determined using the mechanisms described
- in the
- [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
- This is the directory
- specified in the <code class="code">XDG_RUNTIME_DIR</code> environment variable.
- In the case that this variable is not set, we return the value of
- <code class="function">g_get_user_cache_dir()</code>, after verifying that it exists.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.161"></a><h3>get-user-special-dir</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (get-user-special-dir directory))
- </pre></div>
- <p>Returns the full path of a special directory using its logical id.
- </p>
- <p>On UNIX this is done using the XDG special user directories.
- For compatibility with existing practise, <code class="constant">G_USER_DIRECTORY_DESKTOP</code>
- falls back to <code class="code">$HOME/Desktop</code> when XDG special user directories have
- not been set up.
- </p>
- <p>Depending on the platform, the user might be able to change the path
- of the special directory without requiring the session to restart; GLib
- will not reflect any change once the special directories are loaded.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.161.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>directory</p></td>
- <td class="parameter_description">
- <p>the logical id of special directory</p>
- <p>Passed as <code class="code">directory</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.162"></a><h3>getenv</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (getenv variable))
- </pre></div>
- <p>Returns the value of an environment variable.
- </p>
- <p>On UNIX, the name and value are byte strings which might or might not
- be in some consistent character set and encoding. On Windows, they are
- in UTF-8.
- On Windows, in case the environment variable's value contains
- references to other environment variables, they are expanded.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.162.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>variable</p></td>
- <td class="parameter_description">
- <p>the environment variable to get</p>
- <p>Passed as <code class="code">variable</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.163"></a><h3>hash-table-add?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table-add? hash-table key))
- </pre></div>
- <p>This is a convenience function for using a <span class="type">GHashTable</span> as a set. It
- is equivalent to calling <code class="function">g_hash_table_replace()</code> with <em class="parameter"><code>key</code></em> as both the
- key and the value.
- </p>
- <p>In particular, this means that if <em class="parameter"><code>key</code></em> already exists in the hash table, then
- the old copy of <em class="parameter"><code>key</code></em> in the hash table is freed and <em class="parameter"><code>key</code></em> replaces it in the
- table.
- </p>
- <p>When a hash table only ever contains keys that have themselves as the
- corresponding value it is able to be stored more efficiently. See
- the discussion in the section description.
- </p>
- <p>Starting from GLib 2.40, this function returns a boolean value to
- indicate whether the newly added value was already in the hash table
- or not.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.163.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>hash_table</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GHashTable</span></p>
- <p>Passed as <code class="code">hash-table</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>key</p></td>
- <td class="parameter_description">
- <p>a key to insert</p>
- <p>Passed as <code class="code">key</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.164"></a><h3>hash-table-contains?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table-contains? hash-table key))
- </pre></div>
- <p>Checks if <em class="parameter"><code>key</code></em> is in <em class="parameter"><code>hash_table</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.164.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>hash_table</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GHashTable</span></p>
- <p>Passed as <code class="code">hash-table</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>key</p></td>
- <td class="parameter_description">
- <p>a key to check</p>
- <p>Passed as <code class="code">key</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.165"></a><h3>hash-table-destroy</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (hash-table-destroy hash-table))
- </pre></div>
- <p>Destroys all keys and values in the <span class="type">GHashTable</span> and decrements its
- reference count by 1. If keys and/or values are dynamically allocated,
- you should either free them first or create the <span class="type">GHashTable</span> with destroy
- notifiers using <code class="function">g_hash_table_new_full()</code>. In the latter case the destroy
- functions you supplied will be called on all keys and values during the
- destruction phase.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.165.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>hash_table</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GHashTable</span></p>
- <p>Passed as <code class="code">hash-table</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.166"></a><h3>hash-table-insert?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table-insert? hash-table key value))
- </pre></div>
- <p>Inserts a new key and value into a <span class="type">GHashTable</span>.
- </p>
- <p>If the key already exists in the <span class="type">GHashTable</span> its current
- value is replaced with the new value. If you supplied a
- <em class="parameter"><code>value_destroy_func</code></em> when creating the <span class="type">GHashTable</span>, the old
- value is freed using that function. If you supplied a
- <em class="parameter"><code>key_destroy_func</code></em> when creating the <span class="type">GHashTable</span>, the passed
- key is freed using that function.
- </p>
- <p>Starting from GLib 2.40, this function returns a boolean value to
- indicate whether the newly added value was already in the hash table
- or not.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.166.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>hash_table</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GHashTable</span></p>
- <p>Passed as <code class="code">hash-table</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>key</p></td>
- <td class="parameter_description">
- <p>a key to insert</p>
- <p>Passed as <code class="code">key</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>value</p></td>
- <td class="parameter_description">
- <p>the value to associate with the key</p>
- <p>Passed as <code class="code">value</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.167"></a><h3>hash-table-lookup</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table-lookup hash-table key))
- </pre></div>
- <p>Looks up a key in a <span class="type">GHashTable</span>. Note that this function cannot
- distinguish between a key that is not present and one which is present
- and has the value <code class="constant">NULL</code>. If you need this distinction, use
- <code class="function">g_hash_table_lookup_extended()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.167.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>hash_table</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GHashTable</span></p>
- <p>Passed as <code class="code">hash-table</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>key</p></td>
- <td class="parameter_description">
- <p>the key to look up</p>
- <p>Passed as <code class="code">key</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.168"></a><h3>hash-table-lookup-extended</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return orig-key value)
- (hash-table-lookup-extended hash-table lookup-key))
- </pre></div>
- <p>Looks up a key in the <span class="type">GHashTable</span>, returning the original key and the
- associated value and a <span class="type">gboolean</span> which is <code class="constant">TRUE</code> if the key was found. This
- is useful if you need to free the memory allocated for the original key,
- for example before calling <code class="function">g_hash_table_remove()</code>.
- </p>
- <p>You can actually pass <code class="constant">NULL</code> for <em class="parameter"><code>lookup_key</code></em> to test
- whether the <code class="constant">NULL</code> key exists, provided the hash and equal functions
- of <em class="parameter"><code>hash_table</code></em> are <code class="constant">NULL</code>-safe.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.168.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>hash_table</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GHashTable</span></p>
- <p>Passed as <code class="code">hash-table</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>lookup_key</p></td>
- <td class="parameter_description">
- <p>the key to look up</p>
- <p>Passed as <code class="code">lookup-key</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>orig_key</p></td>
- <td class="parameter_description">
- <p>return location for the original key</p>
- <p>Passed as <code class="code">orig-key</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>value</p></td>
- <td class="parameter_description">
- <p>return location for the value associated
- with the key</p>
- <p>Passed as <code class="code">value</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.169"></a><h3>hash-table-remove?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table-remove? hash-table key))
- </pre></div>
- <p>Removes a key and its associated value from a <span class="type">GHashTable</span>.
- </p>
- <p>If the <span class="type">GHashTable</span> was created using <code class="function">g_hash_table_new_full()</code>, the
- key and value are freed using the supplied destroy functions, otherwise
- you have to make sure that any dynamically allocated values are freed
- yourself.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.169.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>hash_table</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GHashTable</span></p>
- <p>Passed as <code class="code">hash-table</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>key</p></td>
- <td class="parameter_description">
- <p>the key to remove</p>
- <p>Passed as <code class="code">key</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.170"></a><h3>hash-table-remove-all</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (hash-table-remove-all hash-table))
- </pre></div>
- <p>Removes all keys and their associated values from a <span class="type">GHashTable</span>.
- </p>
- <p>If the <span class="type">GHashTable</span> was created using <code class="function">g_hash_table_new_full()</code>,
- the keys and values are freed using the supplied destroy functions,
- otherwise you have to make sure that any dynamically allocated
- values are freed yourself.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.170.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>hash_table</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GHashTable</span></p>
- <p>Passed as <code class="code">hash-table</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.171"></a><h3>hash-table-replace?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table-replace? hash-table key value))
- </pre></div>
- <p>Inserts a new key and value into a <span class="type">GHashTable</span> similar to
- <code class="function">g_hash_table_insert()</code>. The difference is that if the key
- already exists in the <span class="type">GHashTable</span>, it gets replaced by the
- new key. If you supplied a <em class="parameter"><code>value_destroy_func</code></em> when creating
- the <span class="type">GHashTable</span>, the old value is freed using that function.
- If you supplied a <em class="parameter"><code>key_destroy_func</code></em> when creating the
- <span class="type">GHashTable</span>, the old key is freed using that function.
- </p>
- <p>Starting from GLib 2.40, this function returns a boolean value to
- indicate whether the newly added value was already in the hash table
- or not.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.171.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>hash_table</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GHashTable</span></p>
- <p>Passed as <code class="code">hash-table</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>key</p></td>
- <td class="parameter_description">
- <p>a key to insert</p>
- <p>Passed as <code class="code">key</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>value</p></td>
- <td class="parameter_description">
- <p>the value to associate with the key</p>
- <p>Passed as <code class="code">value</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.172"></a><h3>hash-table-size</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table-size hash-table))
- </pre></div>
- <p>Returns the number of elements contained in the <span class="type">GHashTable</span>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.172.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>hash_table</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GHashTable</span></p>
- <p>Passed as <code class="code">hash-table</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.173"></a><h3>hash-table-steal?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table-steal? hash-table key))
- </pre></div>
- <p>Removes a key and its associated value from a <span class="type">GHashTable</span> without
- calling the key and value destroy functions.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.173.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>hash_table</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GHashTable</span></p>
- <p>Passed as <code class="code">hash-table</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>key</p></td>
- <td class="parameter_description">
- <p>the key to remove</p>
- <p>Passed as <code class="code">key</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.174"></a><h3>hash-table-steal-all</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (hash-table-steal-all hash-table))
- </pre></div>
- <p>Removes all keys and their associated values from a <span class="type">GHashTable</span>
- without calling the key and value destroy functions.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.174.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>hash_table</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GHashTable</span></p>
- <p>Passed as <code class="code">hash-table</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.175"></a><h3>hash-table-steal-extended</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return stolen-key stolen-value)
- (hash-table-steal-extended hash-table lookup-key))
- </pre></div>
- <p>Looks up a key in the <span class="type">GHashTable</span>, stealing the original key and the
- associated value and returning <code class="constant">TRUE</code> if the key was found. If the key was
- not found, <code class="constant">FALSE</code> is returned.
- </p>
- <p>If found, the stolen key and value are removed from the hash table without
- calling the key and value destroy functions, and ownership is transferred to
- the caller of this method; as with <code class="function">g_hash_table_steal()</code>.
- </p>
- <p>You can pass <code class="constant">NULL</code> for <em class="parameter"><code>lookup_key</code></em>, provided the hash and equal functions
- of <em class="parameter"><code>hash_table</code></em> are <code class="constant">NULL</code>-safe.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.175.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>hash_table</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GHashTable</span></p>
- <p>Passed as <code class="code">hash-table</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>lookup_key</p></td>
- <td class="parameter_description">
- <p>the key to look up</p>
- <p>Passed as <code class="code">lookup-key</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>stolen_key</p></td>
- <td class="parameter_description">
- <p>return location for the
- original key</p>
- <p>Passed as <code class="code">stolen-key</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>stolen_value</p></td>
- <td class="parameter_description">
- <p>return location
- for the value associated with the key</p>
- <p>Passed as <code class="code">stolen-value</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.176"></a><h3>hash-table-unref</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (hash-table-unref hash-table))
- </pre></div>
- <p>Atomically decrements the reference count of <em class="parameter"><code>hash_table</code></em> by one.
- If the reference count drops to 0, all keys and values will be
- destroyed, and all memory allocated by the hash table is released.
- This function is MT-safe and may be called from any thread.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.176.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>hash_table</p></td>
- <td class="parameter_description">
- <p>a valid <span class="type">GHashTable</span></p>
- <p>Passed as <code class="code">hash-table</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.177"></a><h3>hostname-is-ascii-encoded?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (hostname-is-ascii-encoded? hostname))
- </pre></div>
- <p>Tests if <em class="parameter"><code>hostname</code></em> contains segments with an ASCII-compatible
- encoding of an Internationalized Domain Name. If this returns
- <code class="constant">TRUE</code>, you should decode the hostname with <code class="function">g_hostname_to_unicode()</code>
- before displaying it to the user.
- </p>
- <p>Note that a hostname might contain a mix of encoded and unencoded
- segments, and so it is possible for <code class="function">g_hostname_is_non_ascii()</code> and
- <code class="function">g_hostname_is_ascii_encoded()</code> to both return <code class="constant">TRUE</code> for a name.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.177.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>hostname</p></td>
- <td class="parameter_description">
- <p>a hostname</p>
- <p>Passed as <code class="code">hostname</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.178"></a><h3>hostname-is-ip-address?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (hostname-is-ip-address? hostname))
- </pre></div>
- <p>Tests if <em class="parameter"><code>hostname</code></em> is the string form of an IPv4 or IPv6 address.
- (Eg, "192.168.0.1".)
- </p>
- <p>Since 2.66, IPv6 addresses with a zone-id are accepted (RFC6874).</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.178.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>hostname</p></td>
- <td class="parameter_description">
- <p>a hostname (or IP address in string form)</p>
- <p>Passed as <code class="code">hostname</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.179"></a><h3>hostname-is-non-ascii?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (hostname-is-non-ascii? hostname))
- </pre></div>
- <p>Tests if <em class="parameter"><code>hostname</code></em> contains Unicode characters. If this returns
- <code class="constant">TRUE</code>, you need to encode the hostname with <code class="function">g_hostname_to_ascii()</code>
- before using it in non-IDN-aware contexts.
- </p>
- <p>Note that a hostname might contain a mix of encoded and unencoded
- segments, and so it is possible for <code class="function">g_hostname_is_non_ascii()</code> and
- <code class="function">g_hostname_is_ascii_encoded()</code> to both return <code class="constant">TRUE</code> for a name.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.179.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>hostname</p></td>
- <td class="parameter_description">
- <p>a hostname</p>
- <p>Passed as <code class="code">hostname</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.180"></a><h3>hostname-to-ascii</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (hostname-to-ascii hostname))
- </pre></div>
- <p>Converts <em class="parameter"><code>hostname</code></em> to its canonical ASCII form; an ASCII-only
- string containing no uppercase letters and not ending with a
- trailing dot.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.180.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>hostname</p></td>
- <td class="parameter_description">
- <p>a valid UTF-8 or ASCII hostname</p>
- <p>Passed as <code class="code">hostname</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.181"></a><h3>hostname-to-unicode</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (hostname-to-unicode hostname))
- </pre></div>
- <p>Converts <em class="parameter"><code>hostname</code></em> to its canonical presentation form; a UTF-8
- string in Unicode normalization form C, containing no uppercase
- letters, no forbidden characters, and no ASCII-encoded segments,
- and not ending with a trailing dot.
- </p>
- <p>Of course if <em class="parameter"><code>hostname</code></em> is not an internationalized hostname, then
- the canonical presentation form will be entirely ASCII.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.181.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>hostname</p></td>
- <td class="parameter_description">
- <p>a valid UTF-8 or ASCII hostname</p>
- <p>Passed as <code class="code">hostname</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.182"></a><h3>idle-add</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (idle-add priority function data notify))
- </pre></div>
- <p>Adds a function to be called whenever there are no higher priority
- events pending to the default main loop. The function is given the
- default idle priority, <span class="type">G_PRIORITY_DEFAULT_IDLE</span>. If the function
- returns <code class="constant">FALSE</code> it is automatically removed from the list of event
- sources and will not be called again.
- </p>
- <p>See [memory management of sources][mainloop-memory-management] for details
- on how to handle the return value and memory management of <em class="parameter"><code>data</code></em>.
- </p>
- <p>This internally creates a main loop source using <code class="function">g_idle_source_new()</code>
- and attaches it to the global <span class="type">GMainContext</span> using <code class="function">g_source_attach()</code>, so
- the callback will be invoked in whichever thread is running that main
- context. You can do these steps manually if you need greater control or to
- use a custom main context.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.182.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>notify</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">notify</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>priority</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">priority</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>function</p></td>
- <td class="parameter_description">
- <p>function to call</p>
- <p>Passed as <code class="code">function</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>data</p></td>
- <td class="parameter_description">
- <p>data to pass to <em class="parameter"><code>function</code></em>.</p>
- <p>Passed as <code class="code">data</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.183"></a><h3>idle-remove-by-data?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (idle-remove-by-data? data))
- </pre></div>
- <p>Removes the idle function with the given data.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.183.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>data</p></td>
- <td class="parameter_description">
- <p>the data for the idle source's callback.</p>
- <p>Passed as <code class="code">data</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.184"></a><h3>idle-source-new</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (idle-source-new))
- </pre></div>
- <p>Creates a new idle source.
- </p>
- <p>The source will not initially be associated with any <span class="type">GMainContext</span>
- and must be added to one with <code class="function">g_source_attach()</code> before it will be
- executed. Note that the default priority for idle sources is
- <code class="constant">G_PRIORITY_DEFAULT_IDLE</code>, as compared to other sources which
- have a default priority of <code class="constant">G_PRIORITY_DEFAULT</code>.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.185"></a><h3>int64-equal?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (int64-equal? v1 v2))
- </pre></div>
- <p>Compares the two <span class="type">gint64</span> values being pointed to and returns
- <code class="constant">TRUE</code> if they are equal.
- It can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>key_equal_func</code></em>
- parameter, when using non-<code class="constant">NULL</code> pointers to 64-bit integers as keys in a
- <span class="type">GHashTable</span>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.185.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>v1</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gint64</span> key</p>
- <p>Passed as <code class="code">v1</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>v2</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gint64</span> key to compare with <em class="parameter"><code>v1</code></em></p>
- <p>Passed as <code class="code">v2</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.186"></a><h3>int64-hash</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (int64-hash v))
- </pre></div>
- <p>Converts a pointer to a <span class="type">gint64</span> to a hash value.
- </p>
- <p>It can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>hash_func</code></em> parameter,
- when using non-<code class="constant">NULL</code> pointers to 64-bit integer values as keys in a
- <span class="type">GHashTable</span>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.186.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>v</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gint64</span> key</p>
- <p>Passed as <code class="code">v</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.187"></a><h3>int-equal?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (int-equal? v1 v2))
- </pre></div>
- <p>Compares the two <span class="type">gint</span> values being pointed to and returns
- <code class="constant">TRUE</code> if they are equal.
- It can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>key_equal_func</code></em>
- parameter, when using non-<code class="constant">NULL</code> pointers to integers as keys in a
- <span class="type">GHashTable</span>.
- </p>
- <p>Note that this function acts on pointers to <span class="type">gint</span>, not on <span class="type">gint</span>
- directly: if your hash table's keys are of the form
- <code class="code">GINT_TO_POINTER (n)</code>, use <code class="function">g_direct_equal()</code> instead.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.187.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>v1</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gint</span> key</p>
- <p>Passed as <code class="code">v1</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>v2</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gint</span> key to compare with <em class="parameter"><code>v1</code></em></p>
- <p>Passed as <code class="code">v2</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.188"></a><h3>int-hash</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (int-hash v))
- </pre></div>
- <p>Converts a pointer to a <span class="type">gint</span> to a hash value.
- It can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>hash_func</code></em> parameter,
- when using non-<code class="constant">NULL</code> pointers to integer values as keys in a <span class="type">GHashTable</span>.
- </p>
- <p>Note that this function acts on pointers to <span class="type">gint</span>, not on <span class="type">gint</span>
- directly: if your hash table's keys are of the form
- <code class="code">GINT_TO_POINTER (n)</code>, use <code class="function">g_direct_hash()</code> instead.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.188.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>v</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gint</span> key</p>
- <p>Passed as <code class="code">v</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.189"></a><h3>intern-static-string</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (intern-static-string string))
- </pre></div>
- <p>Returns a canonical representation for <em class="parameter"><code>string</code></em>. Interned strings
- can be compared for equality by comparing the pointers, instead of
- using <code class="function">strcmp()</code>. <code class="function">g_intern_static_string()</code> does not copy the string,
- therefore <em class="parameter"><code>string</code></em> must not be freed or modified.
- </p>
- <p>This function must not be used before library constructors have finished
- running. In particular, this means it cannot be used to initialize global
- variables in C++.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.189.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>a static string</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.190"></a><h3>intern-string</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (intern-string string))
- </pre></div>
- <p>Returns a canonical representation for <em class="parameter"><code>string</code></em>. Interned strings
- can be compared for equality by comparing the pointers, instead of
- using <code class="function">strcmp()</code>.
- </p>
- <p>This function must not be used before library constructors have finished
- running. In particular, this means it cannot be used to initialize global
- variables in C++.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.190.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>a string</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.191"></a><h3>io-add-watch</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (io-add-watch channel priority condition func user-data notify))
- </pre></div>
- <p>Adds the <span class="type">GIOChannel</span> into the default main loop context
- with the default priority.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.191.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>notify</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">notify</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>priority</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">priority</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>channel</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GIOChannel</span></p>
- <p>Passed as <code class="code">channel</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>condition</p></td>
- <td class="parameter_description">
- <p>the condition to watch for</p>
- <p>Passed as <code class="code">condition</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>func</p></td>
- <td class="parameter_description">
- <p>the function to call when the condition is satisfied</p>
- <p>Passed as <code class="code">func</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>user_data</p></td>
- <td class="parameter_description">
- <p>user data to pass to <em class="parameter"><code>func</code></em></p>
- <p>Passed as <code class="code">user-data</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.192"></a><h3>io-channel-error-from-errno</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (io-channel-error-from-errno en))
- </pre></div>
- <p>Converts an <code class="code">errno</code> error number to a <span class="type">GIOChannelError</span>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.192.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>en</p></td>
- <td class="parameter_description">
- <p>an <code class="code">errno</code> error number, e.g. <code class="code">EINVAL</code></p>
- <p>Passed as <code class="code">en</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.193"></a><h3>io-channel-error-quark</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (io-channel-error-quark))
- </pre></div>
- <p>Undocumented</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.194"></a><h3>io-create-watch</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (io-create-watch channel condition))
- </pre></div>
- <p>Creates a <span class="type">GSource</span> that's dispatched when <em class="parameter"><code>condition</code></em> is met for the
- given <em class="parameter"><code>channel</code></em>. For example, if condition is <span class="type">G_IO_IN</span>, the source will
- be dispatched when there's data available for reading.
- </p>
- <p>The callback function invoked by the <span class="type">GSource</span> should be added with
- <code class="function">g_source_set_callback()</code>, but it has type <span class="type">GIOFunc</span> (not <span class="type">GSourceFunc</span>).
- </p>
- <p><code class="function">g_io_add_watch()</code> is a simpler interface to this same functionality, for
- the case where you want to add the source to the default main loop context
- at the default priority.
- </p>
- <p>On Windows, polling a <span class="type">GSource</span> created to watch a channel for a socket
- puts the socket in non-blocking mode. This is a side-effect of the
- implementation and unavoidable.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.194.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>channel</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GIOChannel</span> to watch</p>
- <p>Passed as <code class="code">channel</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>condition</p></td>
- <td class="parameter_description">
- <p>conditions to watch for</p>
- <p>Passed as <code class="code">condition</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.195"></a><h3>key-file-error-quark</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (key-file-error-quark))
- </pre></div>
- <p>Undocumented</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.196"></a><h3>listenv</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (listenv))
- </pre></div>
- <p>Gets the names of all variables set in the environment.
- </p>
- <p>Programs that want to be portable to Windows should typically use
- this function and <code class="function">g_getenv()</code> instead of using the environ array
- from the C library directly. On Windows, the strings in the environ
- array are in system codepage encoding, while in most of the typical
- use cases for environment variables in GLib-using programs you want
- the UTF-8 encoding that this function and <code class="function">g_getenv()</code> provide.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.197"></a><h3>locale-from-utf8</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return bytes-read bytes-written)
- (locale-from-utf8 utf8string len))
- </pre></div>
- <p>Converts a string from UTF-8 to the encoding used for strings by
- the C runtime (usually the same as that used by the operating
- system) in the [current locale][setlocale]. On Windows this means
- the system codepage.
- </p>
- <p>The input string shall not contain nul characters even if the <em class="parameter"><code>len</code></em>
- argument is positive. A nul character found inside the string will result
- in error <code class="constant">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</code>. Use <code class="function">g_convert()</code> to convert
- input that may contain embedded nul characters.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.197.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>utf8string</p></td>
- <td class="parameter_description">
- <p>a UTF-8 encoded string</p>
- <p>Passed as <code class="code">utf8string</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>the length of the string, or -1 if the string is
- nul-terminated.</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>bytes_read</p></td>
- <td class="parameter_description">
- <p>location to store the number of bytes in the
- input string that were successfully converted, or <code class="constant">NULL</code>.
- Even if the conversion was successful, this may be
- less than <em class="parameter"><code>len</code></em> if there were partial characters
- at the end of the input. If the error
- <code class="constant">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</code> occurs, the value
- stored will be the byte offset after the last valid
- input sequence.</p>
- <p>Passed as <code class="code">bytes-read</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>bytes_written</p></td>
- <td class="parameter_description">
- <p>the number of bytes stored in the output
- buffer (not including the terminating nul).</p>
- <p>Inferred from <code class="code">%return</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.198"></a><h3>locale-to-utf8</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return bytes-read bytes-written)
- (locale-to-utf8 opsysstring))
- </pre></div>
- <p>Converts a string which is in the encoding used for strings by
- the C runtime (usually the same as that used by the operating
- system) in the [current locale][setlocale] into a UTF-8 string.
- </p>
- <p>If the source encoding is not UTF-8 and the conversion output contains a
- nul character, the error <code class="constant">G_CONVERT_ERROR_EMBEDDED_NUL</code> is set and the
- function returns <code class="constant">NULL</code>.
- If the source encoding is UTF-8, an embedded nul character is treated with
- the <code class="constant">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</code> error for backward compatibility with
- earlier versions of this library. Use <code class="function">g_convert()</code> to produce output that
- may contain embedded nul characters.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.198.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>opsysstring</p></td>
- <td class="parameter_description">
- <p>a string in the
- encoding of the current locale. On Windows
- this means the system codepage.</p>
- <p>Passed as <code class="code">opsysstring</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>the length of the string, or -1 if the string is
- nul-terminated (Note that some encodings may allow nul
- bytes to occur inside strings. In that case, using -1
- for the <em class="parameter"><code>len</code></em> parameter is unsafe)</p>
- <p>Inferred from <code class="code">opsysstring</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>bytes_read</p></td>
- <td class="parameter_description">
- <p>location to store the number of bytes in the
- input string that were successfully converted, or <code class="constant">NULL</code>.
- Even if the conversion was successful, this may be
- less than <em class="parameter"><code>len</code></em> if there were partial characters
- at the end of the input. If the error
- <code class="constant">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</code> occurs, the value
- stored will be the byte offset after the last valid
- input sequence.</p>
- <p>Passed as <code class="code">bytes-read</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>bytes_written</p></td>
- <td class="parameter_description">
- <p>the number of bytes stored in the output
- buffer (not including the terminating nul).</p>
- <p>Passed as <code class="code">bytes-written</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.199"></a><h3>log-default-handler</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- ()
- (log-default-handler log-domain log-level message unused-data))
- </pre></div>
- <p>The default log handler set up by GLib; <code class="function">g_log_set_default_handler()</code>
- allows to install an alternate default log handler.
- This is used if no log handler has been set for the particular log
- domain and log level combination. It outputs the message to stderr
- or stdout and if the log level is fatal it calls <code class="function">G_BREAKPOINT()</code>. It automatically
- prints a new-line character after the message, so one does not need to be
- manually included in <em class="parameter"><code>message</code></em>.
- </p>
- <p>The behavior of this log handler can be influenced by a number of
- environment variables:
- </p>
- <p>- <code class="code">G_MESSAGES_PREFIXED</code>: A :-separated list of log levels for which
- messages should be prefixed by the program name and PID of the
- application.
- </p>
- <p>- <code class="code">G_MESSAGES_DEBUG</code>: A space-separated list of log domains for
- which debug and informational messages are printed. By default
- these messages are not printed.
- </p>
- <p>stderr is used for levels <code class="constant">G_LOG_LEVEL_ERROR</code>, <code class="constant">G_LOG_LEVEL_CRITICAL</code>,
- <code class="constant">G_LOG_LEVEL_WARNING</code> and <code class="constant">G_LOG_LEVEL_MESSAGE</code>. stdout is used for
- the rest.
- </p>
- <p>This has no effect if structured logging is enabled; see
- [Using Structured Logging][using-structured-logging].</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.199.9"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>log_domain</p></td>
- <td class="parameter_description">
- <p>the log domain of the message, or <code class="constant">NULL</code> for the
- default "" application domain</p>
- <p>Passed as <code class="code">log-domain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>log_level</p></td>
- <td class="parameter_description">
- <p>the level of the message</p>
- <p>Passed as <code class="code">log-level</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>message</p></td>
- <td class="parameter_description">
- <p>the message</p>
- <p>Passed as <code class="code">message</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>unused_data</p></td>
- <td class="parameter_description">
- <p>data passed from <code class="function">g_log()</code> which is unused</p>
- <p>Passed as <code class="code">unused-data</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.200"></a><h3>log-remove-handler</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (log-remove-handler log-domain handler-id))
- </pre></div>
- <p>Removes the log handler.
- </p>
- <p>This has no effect if structured logging is enabled; see
- [Using Structured Logging][using-structured-logging].</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.200.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>log_domain</p></td>
- <td class="parameter_description">
- <p>the log domain</p>
- <p>Passed as <code class="code">log-domain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>handler_id</p></td>
- <td class="parameter_description">
- <p>the id of the handler, which was returned
- in <code class="function">g_log_set_handler()</code></p>
- <p>Passed as <code class="code">handler-id</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.201"></a><h3>log-set-always-fatal</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (log-set-always-fatal fatal-mask))
- </pre></div>
- <p>Sets the message levels which are always fatal, in any log domain.
- When a message with any of these levels is logged the program terminates.
- You can only set the levels defined by GLib to be fatal.
- <code class="constant">G_LOG_LEVEL_ERROR</code> is always fatal.
- </p>
- <p>You can also make some message levels fatal at runtime by setting
- the <code class="code">G_DEBUG</code> environment variable (see
- [Running GLib Applications](glib-running.html)).
- </p>
- <p>Libraries should not call this function, as it affects all messages logged
- by a process, including those from other libraries.
- </p>
- <p>Structured log messages (using <code class="function">g_log_structured()</code> and
- <code class="function">g_log_structured_array()</code>) are fatal only if the default log writer is used;
- otherwise it is up to the writer function to determine which log messages
- are fatal. See [Using Structured Logging][using-structured-logging].</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.201.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>fatal_mask</p></td>
- <td class="parameter_description">
- <p>the mask containing bits set for each level
- of error which is to be fatal</p>
- <p>Passed as <code class="code">fatal-mask</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.202"></a><h3>log-set-fatal-mask</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (log-set-fatal-mask log-domain fatal-mask))
- </pre></div>
- <p>Sets the log levels which are fatal in the given domain.
- <code class="constant">G_LOG_LEVEL_ERROR</code> is always fatal.
- </p>
- <p>This has no effect on structured log messages (using <code class="function">g_log_structured()</code> or
- <code class="function">g_log_structured_array()</code>). To change the fatal behaviour for specific log
- messages, programs must install a custom log writer function using
- <code class="function">g_log_set_writer_func()</code>. See
- [Using Structured Logging][using-structured-logging].
- </p>
- <p>This function is mostly intended to be used with
- <code class="constant">G_LOG_LEVEL_CRITICAL</code>. You should typically not set
- <code class="constant">G_LOG_LEVEL_WARNING</code>, <code class="constant">G_LOG_LEVEL_MESSAGE</code>, <code class="constant">G_LOG_LEVEL_INFO</code> or
- <code class="constant">G_LOG_LEVEL_DEBUG</code> as fatal except inside of test programs.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.202.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>log_domain</p></td>
- <td class="parameter_description">
- <p>the log domain</p>
- <p>Passed as <code class="code">log-domain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>fatal_mask</p></td>
- <td class="parameter_description">
- <p>the new fatal mask</p>
- <p>Passed as <code class="code">fatal-mask</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.203"></a><h3>log-set-handler</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (log-set-handler log-domain log-levels log-func user-data destroy))
- </pre></div>
- <p>Sets the log handler for a domain and a set of log levels.
- To handle fatal and recursive messages the <em class="parameter"><code>log_levels</code></em> parameter
- must be combined with the <span class="type">G_LOG_FLAG_FATAL</span> and <span class="type">G_LOG_FLAG_RECURSION</span>
- bit flags.
- </p>
- <p>Note that since the <span class="type">G_LOG_LEVEL_ERROR</span> log level is always fatal, if
- you want to set a handler for this log level you must combine it with
- <span class="type">G_LOG_FLAG_FATAL</span>.
- </p>
- <p>This has no effect if structured logging is enabled; see
- [Using Structured Logging][using-structured-logging].
- </p>
- <p>Here is an example for adding a log handler for all warning messages
- in the default domain:
- </p>
- <div class="informalexample"><pre class="programlisting">
- g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
- | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
- </pre></div>
- <p>This example adds a log handler for all critical messages from GTK+:
- </p>
- <div class="informalexample"><pre class="programlisting">
- g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL
- | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
- </pre></div>
- <p>This example adds a log handler for all messages from GLib:
- </p>
- <div class="informalexample"><pre class="programlisting">
- g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
- | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
- </pre></div>
- <div class="refsect3">
- <a name="id-1.1.90.2.203.9"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>destroy</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">destroy</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>log_domain</p></td>
- <td class="parameter_description">
- <p>the log domain, or <code class="constant">NULL</code> for the default ""
- application domain</p>
- <p>Passed as <code class="code">log-domain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>log_levels</p></td>
- <td class="parameter_description">
- <p>the log levels to apply the log handler for.
- To handle fatal and recursive messages as well, combine
- the log levels with the <span class="type">G_LOG_FLAG_FATAL</span> and
- <span class="type">G_LOG_FLAG_RECURSION</span> bit flags.</p>
- <p>Passed as <code class="code">log-levels</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>log_func</p></td>
- <td class="parameter_description">
- <p>the log handler function</p>
- <p>Passed as <code class="code">log-func</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>user_data</p></td>
- <td class="parameter_description">
- <p>data passed to the log handler</p>
- <p>Passed as <code class="code">user-data</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.204"></a><h3>log-variant</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (log-variant log-domain log-level fields))
- </pre></div>
- <p>Log a message with structured data, accepting the data within a <span class="type">GVariant</span>. This
- version is especially useful for use in other languages, via introspection.
- </p>
- <p>The only mandatory item in the <em class="parameter"><code>fields</code></em> dictionary is the "MESSAGE" which must
- contain the text shown to the user.
- </p>
- <p>The values in the <em class="parameter"><code>fields</code></em> dictionary are likely to be of type String
- (<span class="type">G_VARIANT_TYPE_STRING</span>). Array of bytes (<span class="type">G_VARIANT_TYPE_BYTESTRING</span>) is also
- supported. In this case the message is handled as binary and will be forwarded
- to the log writer as such. The size of the array should not be higher than
- <code class="constant">G_MAXSSIZE</code>. Otherwise it will be truncated to this size. For other types
- <code class="function">g_variant_print()</code> will be used to convert the value into a string.
- </p>
- <p>For more details on its usage and about the parameters, see <code class="function">g_log_structured()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.204.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>log_domain</p></td>
- <td class="parameter_description">
- <p>log domain, usually <code class="constant">G_LOG_DOMAIN</code></p>
- <p>Passed as <code class="code">log-domain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>log_level</p></td>
- <td class="parameter_description">
- <p>log level, either from <span class="type">GLogLevelFlags</span>, or a user-defined
- level</p>
- <p>Passed as <code class="code">log-level</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>fields</p></td>
- <td class="parameter_description">
- <p>a dictionary (<span class="type">GVariant</span> of the type <code class="constant">G_VARIANT_TYPE_VARDICT</code>)
- containing the key-value pairs of message data.</p>
- <p>Passed as <code class="code">fields</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.205"></a><h3>log-writer-default-set-use-stderr</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (log-writer-default-set-use-stderr use-stderr))
- </pre></div>
- <p>Undocumented</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.205.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>use_stderr</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">use-stderr</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.206"></a><h3>log-writer-default-would-drop?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (log-writer-default-would-drop? log-level log-domain))
- </pre></div>
- <p>Undocumented</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.206.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>log_level</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">log-level</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>log_domain</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">log-domain</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.207"></a><h3>log-writer-is-journald?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (log-writer-is-journald? output-fd))
- </pre></div>
- <p>Check whether the given <em class="parameter"><code>output_fd</code></em> file descriptor is a connection to the
- systemd journal, or something else (like a log file or <code class="code">stdout</code> or
- <code class="code">stderr</code>).
- </p>
- <p>Invalid file descriptors are accepted and return <code class="constant">FALSE</code>, which allows for
- the following construct without needing any additional error handling:
- </p>
- <div class="informalexample"><pre class="programlisting">
- is_journald = g_log_writer_is_journald (fileno (stderr));
- </pre></div>
- <div class="refsect3">
- <a name="id-1.1.90.2.207.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>output_fd</p></td>
- <td class="parameter_description">
- <p>output file descriptor to check</p>
- <p>Passed as <code class="code">output-fd</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.208"></a><h3>log-writer-supports-color?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (log-writer-supports-color? output-fd))
- </pre></div>
- <p>Check whether the given <em class="parameter"><code>output_fd</code></em> file descriptor supports ANSI color
- escape sequences. If so, they can safely be used when formatting log
- messages.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.208.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>output_fd</p></td>
- <td class="parameter_description">
- <p>output file descriptor to check</p>
- <p>Passed as <code class="code">output-fd</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.209"></a><h3>main-context-default</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (main-context-default))
- </pre></div>
- <p>Returns the global default main context. This is the main context
- used for main loop functions when a main loop is not explicitly
- specified, and corresponds to the "main" main loop. See also
- <code class="function">g_main_context_get_thread_default()</code>.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.210"></a><h3>main-context-get-thread-default</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (main-context-get-thread-default))
- </pre></div>
- <p>Gets the thread-default <span class="type">GMainContext</span> for this thread. Asynchronous
- operations that want to be able to be run in contexts other than
- the default one should call this method or
- <code class="function">g_main_context_ref_thread_default()</code> to get a <span class="type">GMainContext</span> to add
- their <span class="type">GSources</span> to. (Note that even in single-threaded
- programs applications may sometimes want to temporarily push a
- non-default context, so it is not safe to assume that this will
- always return <code class="constant">NULL</code> if you are running in the default thread.)
- </p>
- <p>If you need to hold a reference on the context, use
- <code class="function">g_main_context_ref_thread_default()</code> instead.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.211"></a><h3>main-context-ref-thread-default</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (main-context-ref-thread-default))
- </pre></div>
- <p>Gets the thread-default <span class="type">GMainContext</span> for this thread, as with
- <code class="function">g_main_context_get_thread_default()</code>, but also adds a reference to
- it with <code class="function">g_main_context_ref()</code>. In addition, unlike
- <code class="function">g_main_context_get_thread_default()</code>, if the thread-default context
- is the global default context, this will return that <span class="type">GMainContext</span>
- (with a ref added to it) rather than returning <code class="constant">NULL</code>.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.212"></a><h3>main-current-source</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (main-current-source))
- </pre></div>
- <p>Returns the currently firing source for this thread.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.213"></a><h3>main-depth</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (main-depth))
- </pre></div>
- <p>Returns the depth of the stack of calls to
- <code class="function">g_main_context_dispatch()</code> on any <span class="type">GMainContext</span> in the current thread.
- That is, when called from the toplevel, it gives 0. When
- called from within a callback from <code class="function">g_main_context_iteration()</code>
- (or <code class="function">g_main_loop_run()</code>, etc.) it returns 1. When called from within
- a callback to a recursive call to <code class="function">g_main_context_iteration()</code>,
- it returns 2. And so forth.
- </p>
- <p>This function is useful in a situation like the following:
- Imagine an extremely simple "garbage collected" system.
- </p>
- <div class="informalexample"><pre class="programlisting">
- static GList *free_list;
- gpointer
- allocate_memory (gsize size)
- {
- gpointer result = g_malloc (size);
- free_list = g_list_prepend (free_list, result);
- return result;
- }
- void
- free_allocated_memory (void)
- {
- GList *l;
- for (l = free_list; l; l = l->next);
- g_free (l->data);
- g_list_free (free_list);
- free_list = NULL;
- }
- [...]
- while (TRUE);
- {
- g_main_context_iteration (NULL, TRUE);
- free_allocated_memory();
- }
- </pre></div>
- <p>This works from an application, however, if you want to do the same
- thing from a library, it gets more difficult, since you no longer
- control the main loop. You might think you can simply use an idle
- function to make the call to <code class="function">free_allocated_memory()</code>, but that
- doesn't work, since the idle function could be called from a
- recursive callback. This can be fixed by using <code class="function">g_main_depth()</code>
- </p>
- <div class="informalexample"><pre class="programlisting">
- gpointer
- allocate_memory (gsize size)
- {
- FreeListBlock *block = g_new (FreeListBlock, 1);
- block->mem = g_malloc (size);
- block->depth = g_main_depth ();
- free_list = g_list_prepend (free_list, block);
- return block->mem;
- }
- void
- free_allocated_memory (void)
- {
- GList *l;
-
- int depth = g_main_depth ();
- for (l = free_list; l; );
- {
- GList *next = l->next;
- FreeListBlock *block = l->data;
- if (block->depth > depth)
- {
- g_free (block->mem);
- g_free (block);
- free_list = g_list_delete_link (free_list, l);
- }
-
- l = next;
- }
- }
- </pre></div>
- <p>There is a temptation to use <code class="function">g_main_depth()</code> to solve
- problems with reentrancy. For instance, while waiting for data
- to be received from the network in response to a menu item,
- the menu item might be selected again. It might seem that
- one could make the menu item's callback return immediately
- and do nothing if <code class="function">g_main_depth()</code> returns a value greater than 1.
- However, this should be avoided since the user then sees selecting
- the menu item do nothing. Furthermore, you'll find yourself adding
- these checks all over your code, since there are doubtless many,
- many things that the user could do. Instead, you can use the
- following techniques:
- </p>
- <p>1. Use <code class="function">gtk_widget_set_sensitive()</code> or modal dialogs to prevent
- the user from interacting with elements while the main
- loop is recursing.
- </p>
- <p>2. Avoid main loop recursion in situations where you can't handle
- arbitrary callbacks. Instead, structure your code so that you
- simply return to the main loop and then get called again when
- there is more work to do.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.214"></a><h3>malloc</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (malloc n-bytes))
- </pre></div>
- <p>Allocates <em class="parameter"><code>n_bytes</code></em> bytes of memory.
- If <em class="parameter"><code>n_bytes</code></em> is 0 it returns <code class="constant">NULL</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.214.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>n_bytes</p></td>
- <td class="parameter_description">
- <p>the number of bytes to allocate</p>
- <p>Passed as <code class="code">n-bytes</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.215"></a><h3>malloc0</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (malloc0 n-bytes))
- </pre></div>
- <p>Allocates <em class="parameter"><code>n_bytes</code></em> bytes of memory, initialized to 0's.
- If <em class="parameter"><code>n_bytes</code></em> is 0 it returns <code class="constant">NULL</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.215.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>n_bytes</p></td>
- <td class="parameter_description">
- <p>the number of bytes to allocate</p>
- <p>Passed as <code class="code">n-bytes</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.216"></a><h3>malloc0-n</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (malloc0-n n-blocks n-block-bytes))
- </pre></div>
- <p>This function is similar to <code class="function">g_malloc0()</code>, allocating (<em class="parameter"><code>n_blocks</code></em> * <em class="parameter"><code>n_block_bytes</code></em>) bytes,
- but care is taken to detect possible overflow during multiplication.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.216.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>n_blocks</p></td>
- <td class="parameter_description">
- <p>the number of blocks to allocate</p>
- <p>Passed as <code class="code">n-blocks</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>n_block_bytes</p></td>
- <td class="parameter_description">
- <p>the size of each block in bytes</p>
- <p>Passed as <code class="code">n-block-bytes</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.217"></a><h3>malloc-n</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (malloc-n n-blocks n-block-bytes))
- </pre></div>
- <p>This function is similar to <code class="function">g_malloc()</code>, allocating (<em class="parameter"><code>n_blocks</code></em> * <em class="parameter"><code>n_block_bytes</code></em>) bytes,
- but care is taken to detect possible overflow during multiplication.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.217.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>n_blocks</p></td>
- <td class="parameter_description">
- <p>the number of blocks to allocate</p>
- <p>Passed as <code class="code">n-blocks</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>n_block_bytes</p></td>
- <td class="parameter_description">
- <p>the size of each block in bytes</p>
- <p>Passed as <code class="code">n-block-bytes</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.218"></a><h3>markup-error-quark</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (markup-error-quark))
- </pre></div>
- <p>Undocumented</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.219"></a><h3>markup-escape-text</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (markup-escape-text text length))
- </pre></div>
- <p>Escapes text so that the markup parser will parse it verbatim.
- Less than, greater than, ampersand, etc. are replaced with the
- corresponding entities. This function would typically be used
- when writing out a file to be parsed with the markup parser.
- </p>
- <p>Note that this function doesn't protect whitespace and line endings
- from being processed according to the XML rules for normalization
- of line endings and attribute values.
- </p>
- <p>Note also that this function will produce character references in
- the range of &#x1; ... &#x1f; for all control sequences
- except for tabstop, newline and carriage return. The character
- references in this range are not valid XML 1.0, but they are
- valid XML 1.1 and will be accepted by the GMarkup parser.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.219.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>text</p></td>
- <td class="parameter_description">
- <p>some valid UTF-8 text</p>
- <p>Passed as <code class="code">text</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>length</p></td>
- <td class="parameter_description">
- <p>length of <em class="parameter"><code>text</code></em> in bytes, or -1 if the text is nul-terminated</p>
- <p>Passed as <code class="code">length</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.220"></a><h3>memdup</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (memdup mem byte-size))
- </pre></div>
- <p>Allocates <em class="parameter"><code>byte_size</code></em> bytes of memory, and copies <em class="parameter"><code>byte_size</code></em> bytes into it
- from <em class="parameter"><code>mem</code></em>. If <em class="parameter"><code>mem</code></em> is <code class="constant">NULL</code> it returns <code class="constant">NULL</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.220.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>mem</p></td>
- <td class="parameter_description">
- <p>the memory to copy.</p>
- <p>Passed as <code class="code">mem</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>byte_size</p></td>
- <td class="parameter_description">
- <p>the number of bytes to copy.</p>
- <p>Passed as <code class="code">byte-size</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.221"></a><h3>memdup2</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (memdup2 mem byte-size))
- </pre></div>
- <p>Undocumented</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.221.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>mem</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">mem</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>byte_size</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">byte-size</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.222"></a><h3>mkdir-with-parents</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (mkdir-with-parents pathname mode))
- </pre></div>
- <p>Create a directory if it doesn't already exist. Create intermediate
- parent directories as needed, too.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.222.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>pathname</p></td>
- <td class="parameter_description">
- <p>a pathname in the GLib file name encoding</p>
- <p>Passed as <code class="code">pathname</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>mode</p></td>
- <td class="parameter_description">
- <p>permissions to use for newly created directories</p>
- <p>Passed as <code class="code">mode</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.223"></a><h3>nullify-pointer</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (nullify-pointer nullify-location))
- </pre></div>
- <p>Set the pointer at the specified location to <code class="constant">NULL</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.223.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>nullify_location</p></td>
- <td class="parameter_description">
- <p>the memory address of the pointer.</p>
- <p>Passed as <code class="code">nullify-location</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.224"></a><h3>number-parser-error-quark</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (number-parser-error-quark))
- </pre></div>
- <p>Undocumented</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.225"></a><h3>on-error-query</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (on-error-query prg-name))
- </pre></div>
- <p>Prompts the user with
- <code class="code">[E]xit, [H]alt, show [S]tack trace or [P]roceed</code>.
- This function is intended to be used for debugging use only.
- The following example shows how it can be used together with
- the <code class="function">g_log()</code> functions.
- </p>
- <div class="informalexample"><pre class="programlisting">
- #include <glib.h>
- static void
- log_handler (const gchar *log_domain,
- GLogLevelFlags log_level,
- const gchar *message,
- gpointer user_data)
- {
- g_log_default_handler (log_domain, log_level, message, user_data);
- g_on_error_query (MY_PROGRAM_NAME);
- }
- int
- main (int argc, char *argv[])
- {
- g_log_set_handler (MY_LOG_DOMAIN,
- G_LOG_LEVEL_WARNING |
- G_LOG_LEVEL_ERROR |
- G_LOG_LEVEL_CRITICAL,
- log_handler,
- NULL);
- ...
- </pre></div>
- <p>If "[E]xit" is selected, the application terminates with a call
- to _exit(0).
- </p>
- <p>If "[S]tack" trace is selected, <code class="function">g_on_error_stack_trace()</code> is called.
- This invokes gdb, which attaches to the current process and shows
- a stack trace. The prompt is then shown again.
- </p>
- <p>If "[P]roceed" is selected, the function returns.
- </p>
- <p>This function may cause different actions on non-UNIX platforms.
- </p>
- <p>On Windows consider using the <code class="code">G_DEBUGGER</code> environment
- variable (see [Running GLib Applications](glib-running.html)) and
- calling <code class="function">g_on_error_stack_trace()</code> instead.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.225.10"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>prg_name</p></td>
- <td class="parameter_description">
- <p>the program name, needed by gdb for the "[S]tack trace"
- option. If <em class="parameter"><code>prg_name</code></em> is <code class="constant">NULL</code>, <code class="function">g_get_prgname()</code> is called to get
- the program name (which will work correctly if <code class="function">gdk_init()</code> or
- <code class="function">gtk_init()</code> has been called)</p>
- <p>Passed as <code class="code">prg-name</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.226"></a><h3>on-error-stack-trace</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (on-error-stack-trace prg-name))
- </pre></div>
- <p>Invokes gdb, which attaches to the current process and shows a
- stack trace. Called by <code class="function">g_on_error_query()</code> when the "[S]tack trace"
- option is selected. You can get the current process's program name
- with <code class="function">g_get_prgname()</code>, assuming that you have called <code class="function">gtk_init()</code> or
- <code class="function">gdk_init()</code>.
- </p>
- <p>This function may cause different actions on non-UNIX platforms.
- </p>
- <p>When running on Windows, this function is *not* called by
- <code class="function">g_on_error_query()</code>. If called directly, it will raise an
- exception, which will crash the program. If the <code class="code">G_DEBUGGER</code> environment
- variable is set, a debugger will be invoked to attach and
- handle that exception (see [Running GLib Applications](glib-running.html)).</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.226.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>prg_name</p></td>
- <td class="parameter_description">
- <p>the program name, needed by gdb for the "[S]tack trace"
- option</p>
- <p>Passed as <code class="code">prg-name</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.227"></a><h3>once-init-enter?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (once-init-enter? location))
- </pre></div>
- <p>Function to be called when starting a critical initialization
- section. The argument <em class="parameter"><code>location</code></em> must point to a static
- 0-initialized variable that will be set to a value other than 0 at
- the end of the initialization section. In combination with
- <code class="function">g_once_init_leave()</code> and the unique address <em class="parameter"><code>value_location</code></em>, it can
- be ensured that an initialization section will be executed only once
- during a program's life time, and that concurrent threads are
- blocked until initialization completed. To be used in constructs
- like this:
- </p>
- <div class="informalexample"><pre class="programlisting">
- static gsize initialization_value = 0;
- if (g_once_init_enter (&initialization_value))
- {
- gsize setup_value = 42; // initialization code here
- g_once_init_leave (&initialization_value, setup_value);
- }
- // use initialization_value here
- </pre></div>
- <div class="refsect3">
- <a name="id-1.1.90.2.227.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>location</p></td>
- <td class="parameter_description">
- <p>location of a static initializable variable
- containing 0</p>
- <p>Passed as <code class="code">location</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.228"></a><h3>once-init-leave</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (once-init-leave location result))
- </pre></div>
- <p>Counterpart to <code class="function">g_once_init_enter()</code>. Expects a location of a static
- 0-initialized initialization variable, and an initialization value
- other than 0. Sets the variable to the initialization value, and
- releases concurrent threads blocking in <code class="function">g_once_init_enter()</code> on this
- initialization variable.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.228.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>location</p></td>
- <td class="parameter_description">
- <p>location of a static initializable variable
- containing 0</p>
- <p>Passed as <code class="code">location</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>result</p></td>
- <td class="parameter_description">
- <p>new non-0 value for *<em class="parameter"><code>value_location</code></em></p>
- <p>Passed as <code class="code">result</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.229"></a><h3>option-error-quark</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (option-error-quark))
- </pre></div>
- <p>Undocumented</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.230"></a><h3>path-get-basename</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (path-get-basename file-name))
- </pre></div>
- <p>Gets the last component of the filename.
- </p>
- <p>If <em class="parameter"><code>file_name</code></em> ends with a directory separator it gets the component
- before the last slash. If <em class="parameter"><code>file_name</code></em> consists only of directory
- separators (and on Windows, possibly a drive letter), a single
- separator is returned. If <em class="parameter"><code>file_name</code></em> is empty, it gets ".".</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.230.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>file_name</p></td>
- <td class="parameter_description">
- <p>the name of the file</p>
- <p>Passed as <code class="code">file-name</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.231"></a><h3>path-get-dirname</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (path-get-dirname file-name))
- </pre></div>
- <p>Gets the directory components of a file name. For example, the directory
- component of <code class="code">/usr/bin/test</code> is <code class="code">/usr/bin</code>. The directory component of <code class="code">/</code>
- is <code class="code">/</code>.
- </p>
- <p>If the file name has no directory components "." is returned.
- The returned string should be freed when no longer needed.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.231.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>file_name</p></td>
- <td class="parameter_description">
- <p>the name of the file</p>
- <p>Passed as <code class="code">file-name</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.232"></a><h3>path-is-absolute?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (path-is-absolute? file-name))
- </pre></div>
- <p>Returns <code class="constant">TRUE</code> if the given <em class="parameter"><code>file_name</code></em> is an absolute file name.
- Note that this is a somewhat vague concept on Windows.
- </p>
- <p>On POSIX systems, an absolute file name is well-defined. It always
- starts from the single root directory. For example "/usr/local".
- </p>
- <p>On Windows, the concepts of current drive and drive-specific
- current directory introduce vagueness. This function interprets as
- an absolute file name one that either begins with a directory
- separator such as "\Users\tml" or begins with the root on a drive,
- for example "C:\Windows". The first case also includes UNC paths
- such as "\\\\myserver\docs\foo". In all cases, either slashes or
- backslashes are accepted.
- </p>
- <p>Note that a file name relative to the current drive root does not
- truly specify a file uniquely over time and across processes, as
- the current drive is a per-process value and can be changed.
- </p>
- <p>File names relative the current directory on some specific drive,
- such as "D:foo/bar", are not interpreted as absolute by this
- function, but they obviously are not relative to the normal current
- directory as returned by <code class="function">getcwd()</code> or <code class="function">g_get_current_dir()</code>
- either. Such paths should be avoided, or need to be handled using
- Windows-specific code.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.232.8"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>file_name</p></td>
- <td class="parameter_description">
- <p>a file name</p>
- <p>Passed as <code class="code">file-name</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.233"></a><h3>path-skip-root</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (path-skip-root file-name))
- </pre></div>
- <p>Returns a pointer into <em class="parameter"><code>file_name</code></em> after the root component,
- i.e. after the "/" in UNIX or "C:\" under Windows. If <em class="parameter"><code>file_name</code></em>
- is not an absolute path it returns <code class="constant">NULL</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.233.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>file_name</p></td>
- <td class="parameter_description">
- <p>a file name</p>
- <p>Passed as <code class="code">file-name</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.234"></a><h3>pattern-match?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (pattern-match? pspec string-length string string-reversed))
- </pre></div>
- <p>Matches a string against a compiled pattern. Passing the correct
- length of the string given is mandatory. The reversed string can be
- omitted by passing <code class="constant">NULL</code>, this is more efficient if the reversed
- version of the string to be matched is not at hand, as
- <code class="function">g_pattern_match()</code> will only construct it if the compiled pattern
- requires reverse matches.
- </p>
- <p>Note that, if the user code will (possibly) match a string against a
- multitude of patterns containing wildcards, chances are high that
- some patterns will require a reversed string. In this case, it's
- more efficient to provide the reversed string to avoid multiple
- constructions thereof in the various calls to <code class="function">g_pattern_match()</code>.
- </p>
- <p>Note also that the reverse of a UTF-8 encoded string can in general
- not be obtained by <code class="function">g_strreverse()</code>. This works only if the string
- does not contain any multibyte characters. GLib offers the
- <code class="function">g_utf8_strreverse()</code> function to reverse UTF-8 encoded strings.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.234.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>pspec</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GPatternSpec</span></p>
- <p>Passed as <code class="code">pspec</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>string_length</p></td>
- <td class="parameter_description">
- <p>the length of <em class="parameter"><code>string</code></em> (in bytes, i.e. <code class="function">strlen()</code>,
- not <code class="function">g_utf8_strlen()</code>)</p>
- <p>Passed as <code class="code">string-length</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>the UTF-8 encoded string to match</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>string_reversed</p></td>
- <td class="parameter_description">
- <p>the reverse of <em class="parameter"><code>string</code></em> or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">string-reversed</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.235"></a><h3>pattern-match-simple?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (pattern-match-simple? pattern string))
- </pre></div>
- <p>Matches a string against a pattern given as a string. If this
- function is to be called in a loop, it's more efficient to compile
- the pattern once with <code class="function">g_pattern_spec_new()</code> and call
- <code class="function">g_pattern_match_string()</code> repeatedly.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.235.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>pattern</p></td>
- <td class="parameter_description">
- <p>the UTF-8 encoded pattern</p>
- <p>Passed as <code class="code">pattern</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>the UTF-8 encoded string to match</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.236"></a><h3>pattern-match-string?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (pattern-match-string? pspec string))
- </pre></div>
- <p>Matches a string against a compiled pattern. If the string is to be
- matched against more than one pattern, consider using
- <code class="function">g_pattern_match()</code> instead while supplying the reversed string.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.236.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>pspec</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GPatternSpec</span></p>
- <p>Passed as <code class="code">pspec</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>the UTF-8 encoded string to match</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.237"></a><h3>pointer-bit-lock</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (pointer-bit-lock address lock-bit))
- </pre></div>
- <p>This is equivalent to g_bit_lock, but working on pointers (or other
- pointer-sized values).
- </p>
- <p>For portability reasons, you may only lock on the bottom 32 bits of
- the pointer.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.237.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>address</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gpointer</span>-sized value</p>
- <p>Passed as <code class="code">address</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>lock_bit</p></td>
- <td class="parameter_description">
- <p>a bit value between 0 and 31</p>
- <p>Passed as <code class="code">lock-bit</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.238"></a><h3>pointer-bit-trylock?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (pointer-bit-trylock? address lock-bit))
- </pre></div>
- <p>This is equivalent to g_bit_trylock, but working on pointers (or
- other pointer-sized values).
- </p>
- <p>For portability reasons, you may only lock on the bottom 32 bits of
- the pointer.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.238.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>address</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gpointer</span>-sized value</p>
- <p>Passed as <code class="code">address</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>lock_bit</p></td>
- <td class="parameter_description">
- <p>a bit value between 0 and 31</p>
- <p>Passed as <code class="code">lock-bit</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.239"></a><h3>pointer-bit-unlock</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (pointer-bit-unlock address lock-bit))
- </pre></div>
- <p>This is equivalent to g_bit_unlock, but working on pointers (or other
- pointer-sized values).
- </p>
- <p>For portability reasons, you may only lock on the bottom 32 bits of
- the pointer.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.239.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>address</p></td>
- <td class="parameter_description">
- <p>a pointer to a <span class="type">gpointer</span>-sized value</p>
- <p>Passed as <code class="code">address</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>lock_bit</p></td>
- <td class="parameter_description">
- <p>a bit value between 0 and 31</p>
- <p>Passed as <code class="code">lock-bit</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.240"></a><h3>poll</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (poll fds nfds timeout))
- </pre></div>
- <p>Polls <em class="parameter"><code>fds</code></em>, as with the <code class="function">poll()</code> system call, but portably. (On
- systems that don't have <code class="function">poll()</code>, it is emulated using <code class="function">select()</code>.)
- This is used internally by <span class="type">GMainContext</span>, but it can be called
- directly if you need to block until a file descriptor is ready, but
- don't want to run the full main loop.
- </p>
- <p>Each element of <em class="parameter"><code>fds</code></em> is a <span class="type">GPollFD</span> describing a single file
- descriptor to poll. The <em class="parameter"><code>fd</code></em> field indicates the file descriptor,
- and the <em class="parameter"><code>events</code></em> field indicates the events to poll for. On return,
- the <em class="parameter"><code>revents</code></em> fields will be filled with the events that actually
- occurred.
- </p>
- <p>On POSIX systems, the file descriptors in <em class="parameter"><code>fds</code></em> can be any sort of
- file descriptor, but the situation is much more complicated on
- Windows. If you need to use <code class="function">g_poll()</code> in code that has to run on
- Windows, the easiest solution is to construct all of your
- <span class="type">GPollFDs</span> with <code class="function">g_io_channel_win32_make_pollfd()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.240.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>fds</p></td>
- <td class="parameter_description">
- <p>file descriptors to poll</p>
- <p>Passed as <code class="code">fds</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>nfds</p></td>
- <td class="parameter_description">
- <p>the number of file descriptors in <em class="parameter"><code>fds</code></em></p>
- <p>Passed as <code class="code">nfds</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>timeout</p></td>
- <td class="parameter_description">
- <p>amount of time to wait, in milliseconds, or -1 to wait forever</p>
- <p>Passed as <code class="code">timeout</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.241"></a><h3>prefix-error-literal</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (prefix-error-literal err prefix))
- </pre></div>
- <p>Undocumented</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.241.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>err</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">err</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>prefix</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">prefix</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.242"></a><h3>propagate-error</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (dest) (propagate-error src))
- </pre></div>
- <p>If <em class="parameter"><code>dest</code></em> is <code class="constant">NULL</code>, free <em class="parameter"><code>src</code></em>; otherwise, moves <em class="parameter"><code>src</code></em> into *<em class="parameter"><code>dest</code></em>.
- The error variable <em class="parameter"><code>dest</code></em> points to must be <code class="constant">NULL</code>.
- </p>
- <p><em class="parameter"><code>src</code></em> must be non-<code class="constant">NULL</code>.
- </p>
- <p>Note that <em class="parameter"><code>src</code></em> is no longer valid after this call. If you want
- to keep using the same GError*, you need to set it to <code class="constant">NULL</code>
- after calling this function on it.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.242.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>dest</p></td>
- <td class="parameter_description">
- <p>error return location</p>
- <p>Passed as <code class="code">dest</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>src</p></td>
- <td class="parameter_description">
- <p>error to move into the return location</p>
- <p>Passed as <code class="code">src</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.243"></a><h3>quark-from-static-string</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (quark-from-static-string string))
- </pre></div>
- <p>Gets the <span class="type">GQuark</span> identifying the given (static) string. If the
- string does not currently have an associated <span class="type">GQuark</span>, a new <span class="type">GQuark</span>
- is created, linked to the given string.
- </p>
- <p>Note that this function is identical to <code class="function">g_quark_from_string()</code> except
- that if a new <span class="type">GQuark</span> is created the string itself is used rather
- than a copy. This saves memory, but can only be used if the string
- will continue to exist until the program terminates. It can be used
- with statically allocated strings in the main program, but not with
- statically allocated memory in dynamically loaded modules, if you
- expect to ever unload the module again (e.g. do not use this
- function in GTK+ theme engines).
- </p>
- <p>This function must not be used before library constructors have finished
- running. In particular, this means it cannot be used to initialize global
- variables in C++.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.243.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>a string</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.244"></a><h3>quark-from-string</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (quark-from-string string))
- </pre></div>
- <p>Gets the <span class="type">GQuark</span> identifying the given string. If the string does
- not currently have an associated <span class="type">GQuark</span>, a new <span class="type">GQuark</span> is created,
- using a copy of the string.
- </p>
- <p>This function must not be used before library constructors have finished
- running. In particular, this means it cannot be used to initialize global
- variables in C++.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.244.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>a string</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.245"></a><h3>quark-to-string</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (quark-to-string quark))
- </pre></div>
- <p>Gets the string associated with the given <span class="type">GQuark</span>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.245.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>quark</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GQuark</span>.</p>
- <p>Passed as <code class="code">quark</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.246"></a><h3>quark-try-string</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (quark-try-string string))
- </pre></div>
- <p>Gets the <span class="type">GQuark</span> associated with the given string, or 0 if string is
- <code class="constant">NULL</code> or it has no associated <span class="type">GQuark</span>.
- </p>
- <p>If you want the GQuark to be created if it doesn't already exist,
- use <code class="function">g_quark_from_string()</code> or <code class="function">g_quark_from_static_string()</code>.
- </p>
- <p>This function must not be used before library constructors have finished
- running.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.246.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>a string</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.247"></a><h3>random-double</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (random-double))
- </pre></div>
- <p>Returns a random <span class="type">gdouble</span> equally distributed over the range [0..1).</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.248"></a><h3>random-double-range</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (random-double-range begin end))
- </pre></div>
- <p>Returns a random <span class="type">gdouble</span> equally distributed over the range
- [<em class="parameter"><code>begin</code></em>..<em class="parameter"><code>end</code></em>).</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.248.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>begin</p></td>
- <td class="parameter_description">
- <p>lower closed bound of the interval</p>
- <p>Passed as <code class="code">begin</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>end</p></td>
- <td class="parameter_description">
- <p>upper open bound of the interval</p>
- <p>Passed as <code class="code">end</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.249"></a><h3>random-int</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (random-int))
- </pre></div>
- <p>Return a random <span class="type">guint32</span> equally distributed over the range
- [0..2^32-1].</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.250"></a><h3>random-int-range</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (random-int-range begin end))
- </pre></div>
- <p>Returns a random <span class="type">gint32</span> equally distributed over the range
- [<em class="parameter"><code>begin</code></em>..<em class="parameter"><code>end</code></em>-1].</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.250.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>begin</p></td>
- <td class="parameter_description">
- <p>lower closed bound of the interval</p>
- <p>Passed as <code class="code">begin</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>end</p></td>
- <td class="parameter_description">
- <p>upper open bound of the interval</p>
- <p>Passed as <code class="code">end</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.251"></a><h3>random-set-seed</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (random-set-seed seed))
- </pre></div>
- <p>Sets the seed for the global random number generator, which is used
- by the g_random_* functions, to <em class="parameter"><code>seed</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.251.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>seed</p></td>
- <td class="parameter_description">
- <p>a value to reinitialize the global random number generator</p>
- <p>Passed as <code class="code">seed</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.252"></a><h3>rc-box-acquire</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (rc-box-acquire mem-block))
- </pre></div>
- <p>Acquires a reference on the data pointed by <em class="parameter"><code>mem_block</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.252.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>mem_block</p></td>
- <td class="parameter_description">
- <p>a pointer to reference counted data</p>
- <p>Passed as <code class="code">mem-block</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.253"></a><h3>rc-box-alloc</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (rc-box-alloc block-size))
- </pre></div>
- <p>Allocates <em class="parameter"><code>block_size</code></em> bytes of memory, and adds reference
- counting semantics to it.
- </p>
- <p>The data will be freed when its reference count drops to
- zero.
- </p>
- <p>The allocated data is guaranteed to be suitably aligned for any
- built-in type.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.253.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>block_size</p></td>
- <td class="parameter_description">
- <p>the size of the allocation, must be greater than 0</p>
- <p>Passed as <code class="code">block-size</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.254"></a><h3>rc-box-alloc0</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (rc-box-alloc0 block-size))
- </pre></div>
- <p>Allocates <em class="parameter"><code>block_size</code></em> bytes of memory, and adds reference
- counting semantics to it.
- </p>
- <p>The contents of the returned data is set to zero.
- </p>
- <p>The data will be freed when its reference count drops to
- zero.
- </p>
- <p>The allocated data is guaranteed to be suitably aligned for any
- built-in type.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.254.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>block_size</p></td>
- <td class="parameter_description">
- <p>the size of the allocation, must be greater than 0</p>
- <p>Passed as <code class="code">block-size</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.255"></a><h3>rc-box-dup</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (rc-box-dup block-size mem-block))
- </pre></div>
- <p>Allocates a new block of data with reference counting
- semantics, and copies <em class="parameter"><code>block_size</code></em> bytes of <em class="parameter"><code>mem_block</code></em>
- into it.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.255.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>block_size</p></td>
- <td class="parameter_description">
- <p>the number of bytes to copy, must be greater than 0</p>
- <p>Passed as <code class="code">block-size</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>mem_block</p></td>
- <td class="parameter_description">
- <p>the memory to copy</p>
- <p>Passed as <code class="code">mem-block</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.256"></a><h3>rc-box-get-size</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (rc-box-get-size mem-block))
- </pre></div>
- <p>Retrieves the size of the reference counted data pointed by <em class="parameter"><code>mem_block</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.256.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>mem_block</p></td>
- <td class="parameter_description">
- <p>a pointer to reference counted data</p>
- <p>Passed as <code class="code">mem-block</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.257"></a><h3>rc-box-release</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (rc-box-release mem-block))
- </pre></div>
- <p>Releases a reference on the data pointed by <em class="parameter"><code>mem_block</code></em>.
- </p>
- <p>If the reference was the last one, it will free the
- resources allocated for <em class="parameter"><code>mem_block</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.257.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>mem_block</p></td>
- <td class="parameter_description">
- <p>a pointer to reference counted data</p>
- <p>Passed as <code class="code">mem-block</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.258"></a><h3>rc-box-release-full</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (rc-box-release-full mem-block clear-func))
- </pre></div>
- <p>Releases a reference on the data pointed by <em class="parameter"><code>mem_block</code></em>.
- </p>
- <p>If the reference was the last one, it will call <em class="parameter"><code>clear_func</code></em>
- to clear the contents of <em class="parameter"><code>mem_block</code></em>, and then will free the
- resources allocated for <em class="parameter"><code>mem_block</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.258.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>mem_block</p></td>
- <td class="parameter_description">
- <p>a pointer to reference counted data</p>
- <p>Passed as <code class="code">mem-block</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>clear_func</p></td>
- <td class="parameter_description">
- <p>a function to call when clearing the data</p>
- <p>Passed as <code class="code">clear-func</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.259"></a><h3>realloc</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (realloc mem n-bytes))
- </pre></div>
- <p>Reallocates the memory pointed to by <em class="parameter"><code>mem</code></em>, so that it now has space for
- <em class="parameter"><code>n_bytes</code></em> bytes of memory. It returns the new address of the memory, which may
- have been moved. <em class="parameter"><code>mem</code></em> may be <code class="constant">NULL</code>, in which case it's considered to
- have zero-length. <em class="parameter"><code>n_bytes</code></em> may be 0, in which case <code class="constant">NULL</code> will be returned
- and <em class="parameter"><code>mem</code></em> will be freed unless it is <code class="constant">NULL</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.259.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>mem</p></td>
- <td class="parameter_description">
- <p>the memory to reallocate</p>
- <p>Passed as <code class="code">mem</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>n_bytes</p></td>
- <td class="parameter_description">
- <p>new size of the memory in bytes</p>
- <p>Passed as <code class="code">n-bytes</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.260"></a><h3>realloc-n</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (realloc-n mem n-blocks n-block-bytes))
- </pre></div>
- <p>This function is similar to <code class="function">g_realloc()</code>, allocating (<em class="parameter"><code>n_blocks</code></em> * <em class="parameter"><code>n_block_bytes</code></em>) bytes,
- but care is taken to detect possible overflow during multiplication.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.260.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>mem</p></td>
- <td class="parameter_description">
- <p>the memory to reallocate</p>
- <p>Passed as <code class="code">mem</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>n_blocks</p></td>
- <td class="parameter_description">
- <p>the number of blocks to allocate</p>
- <p>Passed as <code class="code">n-blocks</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>n_block_bytes</p></td>
- <td class="parameter_description">
- <p>the size of each block in bytes</p>
- <p>Passed as <code class="code">n-block-bytes</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.261"></a><h3>ref-count-compare?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (ref-count-compare? rc val))
- </pre></div>
- <p>Compares the current value of <em class="parameter"><code>rc</code></em> with <em class="parameter"><code>val</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.261.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>rc</p></td>
- <td class="parameter_description">
- <p>the address of a reference count variable</p>
- <p>Passed as <code class="code">rc</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>val</p></td>
- <td class="parameter_description">
- <p>the value to compare</p>
- <p>Passed as <code class="code">val</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.262"></a><h3>ref-count-dec?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (ref-count-dec? rc))
- </pre></div>
- <p>Decreases the reference count.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.262.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>rc</p></td>
- <td class="parameter_description">
- <p>the address of a reference count variable</p>
- <p>Passed as <code class="code">rc</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.263"></a><h3>ref-count-inc</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (ref-count-inc rc))
- </pre></div>
- <p>Increases the reference count.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.263.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>rc</p></td>
- <td class="parameter_description">
- <p>the address of a reference count variable</p>
- <p>Passed as <code class="code">rc</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.264"></a><h3>ref-count-init</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (ref-count-init rc))
- </pre></div>
- <p>Initializes a reference count variable.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.264.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>rc</p></td>
- <td class="parameter_description">
- <p>the address of a reference count variable</p>
- <p>Passed as <code class="code">rc</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.265"></a><h3>ref-string-acquire</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (ref-string-acquire str))
- </pre></div>
- <p>Acquires a reference on a string.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.265.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a reference counted string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.266"></a><h3>ref-string-length</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (ref-string-length str))
- </pre></div>
- <p>Retrieves the length of <em class="parameter"><code>str</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.266.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a reference counted string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.267"></a><h3>ref-string-new</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (ref-string-new str))
- </pre></div>
- <p>Creates a new reference counted string and copies the contents of <em class="parameter"><code>str</code></em>
- into it.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.267.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a NUL-terminated string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.268"></a><h3>ref-string-new-intern</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (ref-string-new-intern str))
- </pre></div>
- <p>Creates a new reference counted string and copies the content of <em class="parameter"><code>str</code></em>
- into it.
- </p>
- <p>If you call this function multiple times with the same <em class="parameter"><code>str</code></em>, or with
- the same contents of <em class="parameter"><code>str</code></em>, it will return a new reference, instead of
- creating a new string.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.268.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a NUL-terminated string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.269"></a><h3>ref-string-new-len</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (ref-string-new-len str len))
- </pre></div>
- <p>Creates a new reference counted string and copies the contents of <em class="parameter"><code>str</code></em>
- into it, up to <em class="parameter"><code>len</code></em> bytes.
- </p>
- <p>Since this function does not stop at nul bytes, it is the caller's
- responsibility to ensure that <em class="parameter"><code>str</code></em> has at least <em class="parameter"><code>len</code></em> addressable bytes.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.269.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>length of <em class="parameter"><code>str</code></em> to use, or -1 if <em class="parameter"><code>str</code></em> is nul-terminated</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.270"></a><h3>ref-string-release</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (ref-string-release str))
- </pre></div>
- <p>Releases a reference on a string; if it was the last reference, the
- resources allocated by the string are freed as well.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.270.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a reference counted string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.271"></a><h3>regex-check-replacement</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return has-references) (regex-check-replacement replacement))
- </pre></div>
- <p>Checks whether <em class="parameter"><code>replacement</code></em> is a valid replacement string
- (see <code class="function">g_regex_replace()</code>), i.e. that all escape sequences in
- it are valid.
- </p>
- <p>If <em class="parameter"><code>has_references</code></em> is not <code class="constant">NULL</code> then <em class="parameter"><code>replacement</code></em> is checked
- for pattern references. For instance, replacement text 'foo\n'
- does not contain references and may be evaluated without information
- about actual match, but '\0\1' (whole match followed by first
- subpattern) requires valid <span class="type">GMatchInfo</span> object.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.271.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>replacement</p></td>
- <td class="parameter_description">
- <p>the replacement string</p>
- <p>Passed as <code class="code">replacement</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>has_references</p></td>
- <td class="parameter_description">
- <p>location to store information about
- references in <em class="parameter"><code>replacement</code></em> or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">has-references</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.272"></a><h3>regex-error-quark</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (regex-error-quark))
- </pre></div>
- <p>Undocumented</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.273"></a><h3>regex-escape-nul</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (regex-escape-nul string length))
- </pre></div>
- <p>Escapes the nul characters in <em class="parameter"><code>string</code></em> to "\x00". It can be used
- to compile a regex with embedded nul characters.
- </p>
- <p>For completeness, <em class="parameter"><code>length</code></em> can be -1 for a nul-terminated string.
- In this case the output string will be of course equal to <em class="parameter"><code>string</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.273.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>the string to escape</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>length</p></td>
- <td class="parameter_description">
- <p>the length of <em class="parameter"><code>string</code></em></p>
- <p>Passed as <code class="code">length</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.274"></a><h3>regex-escape-string</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (regex-escape-string string))
- </pre></div>
- <p>Escapes the special characters used for regular expressions
- in <em class="parameter"><code>string</code></em>, for instance "a.b*c" becomes "a\.b\*c". This
- function is useful to dynamically generate regular expressions.
- </p>
- <p><em class="parameter"><code>string</code></em> can contain nul characters that are replaced with "\0",
- in this case remember to specify the correct length of <em class="parameter"><code>string</code></em>
- in <em class="parameter"><code>length</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.274.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>the string to escape</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>length</p></td>
- <td class="parameter_description">
- <p>the length of <em class="parameter"><code>string</code></em>, in bytes, or -1 if <em class="parameter"><code>string</code></em> is nul-terminated</p>
- <p>Inferred from <code class="code">string</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.275"></a><h3>regex-match-simple?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (regex-match-simple? pattern string compile-options match-options))
- </pre></div>
- <p>Scans for a match in <em class="parameter"><code>string</code></em> for <em class="parameter"><code>pattern</code></em>.
- </p>
- <p>This function is equivalent to <code class="function">g_regex_match()</code> but it does not
- require to compile the pattern with <code class="function">g_regex_new()</code>, avoiding some
- lines of code when you need just to do a match without extracting
- substrings, capture counts, and so on.
- </p>
- <p>If this function is to be called on the same <em class="parameter"><code>pattern</code></em> more than
- once, it's more efficient to compile the pattern once with
- <code class="function">g_regex_new()</code> and then use <code class="function">g_regex_match()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.275.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>pattern</p></td>
- <td class="parameter_description">
- <p>the regular expression</p>
- <p>Passed as <code class="code">pattern</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>the string to scan for matches</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>compile_options</p></td>
- <td class="parameter_description">
- <p>compile options for the regular expression, or 0</p>
- <p>Passed as <code class="code">compile-options</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>match_options</p></td>
- <td class="parameter_description">
- <p>match options, or 0</p>
- <p>Passed as <code class="code">match-options</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.276"></a><h3>regex-split-simple</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (regex-split-simple pattern string compile-options match-options))
- </pre></div>
- <p>Breaks the string on the pattern, and returns an array of
- the tokens. If the pattern contains capturing parentheses,
- then the text for each of the substrings will also be returned.
- If the pattern does not match anywhere in the string, then the
- whole string is returned as the first token.
- </p>
- <p>This function is equivalent to <code class="function">g_regex_split()</code> but it does
- not require to compile the pattern with <code class="function">g_regex_new()</code>, avoiding
- some lines of code when you need just to do a split without
- extracting substrings, capture counts, and so on.
- </p>
- <p>If this function is to be called on the same <em class="parameter"><code>pattern</code></em> more than
- once, it's more efficient to compile the pattern once with
- <code class="function">g_regex_new()</code> and then use <code class="function">g_regex_split()</code>.
- </p>
- <p>As a special case, the result of splitting the empty string ""
- is an empty vector, not a vector containing a single string.
- The reason for this special case is that being able to represent
- an empty vector is typically more useful than consistent handling
- of empty elements. If you do need to represent empty elements,
- you'll need to check for the empty string before calling this
- function.
- </p>
- <p>A pattern that can match empty strings splits <em class="parameter"><code>string</code></em> into
- separate characters wherever it matches the empty string between
- characters. For example splitting "ab c" using as a separator
- "\s*", you will get "a", "b" and "c".</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.276.8"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>pattern</p></td>
- <td class="parameter_description">
- <p>the regular expression</p>
- <p>Passed as <code class="code">pattern</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>the string to scan for matches</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>compile_options</p></td>
- <td class="parameter_description">
- <p>compile options for the regular expression, or 0</p>
- <p>Passed as <code class="code">compile-options</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>match_options</p></td>
- <td class="parameter_description">
- <p>match options, or 0</p>
- <p>Passed as <code class="code">match-options</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.277"></a><h3>reload-user-special-dirs-cache</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (reload-user-special-dirs-cache))
- </pre></div>
- <p>Resets the cache used for <code class="function">g_get_user_special_dir()</code>, so
- that the latest on-disk version is used. Call this only
- if you just changed the data on disk yourself.
- </p>
- <p>Due to thread safety issues this may cause leaking of strings
- that were previously returned from <code class="function">g_get_user_special_dir()</code>
- that can't be freed. We ensure to only leak the data for
- the directories that actually changed value though.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.278"></a><h3>rmdir</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (rmdir filename))
- </pre></div>
- <p>A wrapper for the POSIX <code class="function">rmdir()</code> function. The <code class="function">rmdir()</code> function
- deletes a directory from the filesystem.
- </p>
- <p>See your C library manual for more details about how <code class="function">rmdir()</code> works
- on your system.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.278.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>filename</p></td>
- <td class="parameter_description">
- <p>a pathname in the GLib file name encoding
- (UTF-8 on Windows)</p>
- <p>Passed as <code class="code">filename</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.279"></a><h3>set-application-name</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (set-application-name application-name))
- </pre></div>
- <p>Sets a human-readable name for the application. This name should be
- localized if possible, and is intended for display to the user.
- Contrast with <code class="function">g_set_prgname()</code>, which sets a non-localized name.
- <code class="function">g_set_prgname()</code> will be called automatically by <code class="function">gtk_init()</code>,
- but <code class="function">g_set_application_name()</code> will not.
- </p>
- <p>Note that for thread safety reasons, this function can only
- be called once.
- </p>
- <p>The application name will be used in contexts such as error messages,
- or when displaying an application's name in the task list.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.279.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>application_name</p></td>
- <td class="parameter_description">
- <p>localized name of the application</p>
- <p>Passed as <code class="code">application-name</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.280"></a><h3>set-error-literal</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (err) (set-error-literal domain code message))
- </pre></div>
- <p>Does nothing if <em class="parameter"><code>err</code></em> is <code class="constant">NULL</code>; if <em class="parameter"><code>err</code></em> is non-<code class="constant">NULL</code>, then *<em class="parameter"><code>err</code></em>
- must be <code class="constant">NULL</code>. A new <span class="type">GError</span> is created and assigned to *<em class="parameter"><code>err</code></em>.
- Unlike <code class="function">g_set_error()</code>, <em class="parameter"><code>message</code></em> is not a <code class="function">printf()</code>-style format string.
- Use this function if <em class="parameter"><code>message</code></em> contains text you don't have control over,
- that could include <code class="function">printf()</code> escape sequences.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.280.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>err</p></td>
- <td class="parameter_description">
- <p>a return location for a <span class="type">GError</span></p>
- <p>Passed as <code class="code">err</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>domain</p></td>
- <td class="parameter_description">
- <p>error domain</p>
- <p>Passed as <code class="code">domain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>code</p></td>
- <td class="parameter_description">
- <p>error code</p>
- <p>Passed as <code class="code">code</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>message</p></td>
- <td class="parameter_description">
- <p>error message</p>
- <p>Passed as <code class="code">message</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.281"></a><h3>set-prgname</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (set-prgname prgname))
- </pre></div>
- <p>Sets the name of the program. This name should not be localized,
- in contrast to <code class="function">g_set_application_name()</code>.
- </p>
- <p>If you are using <span class="type">GApplication</span> the program name is set in
- <code class="function">g_application_run()</code>. In case of GDK or GTK+ it is set in
- <code class="function">gdk_init()</code>, which is called by <code class="function">gtk_init()</code> and the
- <span class="type">“startup”</span> handler. The program name is found by
- taking the last component of <em class="parameter"><code>argv</code></em>[0].
- </p>
- <p>Note that for thread-safety reasons this function can only be called once.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.281.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>prgname</p></td>
- <td class="parameter_description">
- <p>the name of the program.</p>
- <p>Passed as <code class="code">prgname</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.282"></a><h3>setenv?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (setenv? variable value overwrite))
- </pre></div>
- <p>Sets an environment variable. On UNIX, both the variable's name and
- value can be arbitrary byte strings, except that the variable's name
- cannot contain '='. On Windows, they should be in UTF-8.
- </p>
- <p>Note that on some systems, when variables are overwritten, the memory
- used for the previous variables and its value isn't reclaimed.
- </p>
- <p>You should be mindful of the fact that environment variable handling
- in UNIX is not thread-safe, and your program may crash if one thread
- calls <code class="function">g_setenv()</code> while another thread is calling <code class="function">getenv()</code>. (And note
- that many functions, such as <code class="function">gettext()</code>, call <code class="function">getenv()</code> internally.)
- This function is only safe to use at the very start of your program,
- before creating any other threads (or creating objects that create
- worker threads of their own).
- </p>
- <p>If you need to set up the environment for a child process, you can
- use <code class="function">g_get_environ()</code> to get an environment array, modify that with
- <code class="function">g_environ_setenv()</code> and <code class="function">g_environ_unsetenv()</code>, and then pass that
- array directly to <code class="function">execvpe()</code>, <code class="function">g_spawn_async()</code>, or the like.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.282.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>variable</p></td>
- <td class="parameter_description">
- <p>the environment variable to set, must not
- contain '='.</p>
- <p>Passed as <code class="code">variable</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>value</p></td>
- <td class="parameter_description">
- <p>the value for to set the variable to.</p>
- <p>Passed as <code class="code">value</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>overwrite</p></td>
- <td class="parameter_description">
- <p>whether to change the variable if it already exists.</p>
- <p>Passed as <code class="code">overwrite</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.283"></a><h3>shell-error-quark</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (shell-error-quark))
- </pre></div>
- <p>Undocumented</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.284"></a><h3>shell-parse-argv</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return argcp argvp) (shell-parse-argv command-line))
- </pre></div>
- <p>Parses a command line into an argument vector, in much the same way
- the shell would, but without many of the expansions the shell would
- perform (variable expansion, globs, operators, filename expansion,
- etc. are not supported). The results are defined to be the same as
- those you would get from a UNIX98 /bin/sh, as long as the input
- contains none of the unsupported shell expansions. If the input
- does contain such expansions, they are passed through
- literally. Possible errors are those from the <span class="type">G_SHELL_ERROR</span>
- domain. Free the returned vector with <code class="function">g_strfreev()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.284.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>command_line</p></td>
- <td class="parameter_description">
- <p>command line to parse</p>
- <p>Passed as <code class="code">command-line</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>argcp</p></td>
- <td class="parameter_description">
- <p>return location for number of args</p>
- <p>Inferred from <code class="code">argvp</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>argvp</p></td>
- <td class="parameter_description">
- <p>
- </p>
- <p>return location for array of args</p>
- <p>Passed as <code class="code">argvp</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.285"></a><h3>shell-quote</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (shell-quote unquoted-string))
- </pre></div>
- <p>Quotes a string so that the shell (/bin/sh) will interpret the
- quoted string to mean <em class="parameter"><code>unquoted_string</code></em>. If you pass a filename to
- the shell, for example, you should first quote it with this
- function. The return value must be freed with <code class="function">g_free()</code>. The
- quoting style used is undefined (single or double quotes may be
- used).</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.285.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>unquoted_string</p></td>
- <td class="parameter_description">
- <p>a literal string</p>
- <p>Passed as <code class="code">unquoted-string</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.286"></a><h3>shell-unquote</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (shell-unquote quoted-string))
- </pre></div>
- <p>Unquotes a string as the shell (/bin/sh) would. Only handles
- quotes; if a string contains file globs, arithmetic operators,
- variables, backticks, redirections, or other special-to-the-shell
- features, the result will be different from the result a real shell
- would produce (the variables, backticks, etc. will be passed
- through literally instead of being expanded). This function is
- guaranteed to succeed if applied to the result of
- <code class="function">g_shell_quote()</code>. If it fails, it returns <code class="constant">NULL</code> and sets the
- error. The <em class="parameter"><code>quoted_string</code></em> need not actually contain quoted or
- escaped text; <code class="function">g_shell_unquote()</code> simply goes through the string and
- unquotes/unescapes anything that the shell would. Both single and
- double quotes are handled, as are escapes including escaped
- newlines. The return value must be freed with <code class="function">g_free()</code>. Possible
- errors are in the <span class="type">G_SHELL_ERROR</span> domain.
- </p>
- <p>Shell quoting rules are a bit strange. Single quotes preserve the
- literal string exactly. escape sequences are not allowed; not even
- \' - if you want a ' in the quoted text, you have to do something
- like 'foo'\''bar'. Double quotes allow $, `, ", \, and newline to
- be escaped with backslash. Otherwise double quotes preserve things
- literally.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.286.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>quoted_string</p></td>
- <td class="parameter_description">
- <p>shell-quoted string</p>
- <p>Passed as <code class="code">quoted-string</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.287"></a><h3>slice-alloc</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (slice-alloc block-size))
- </pre></div>
- <p>Allocates a block of memory from the slice allocator.
- The block address handed out can be expected to be aligned
- to at least 1 * sizeof (void*),
- though in general slices are 2 * sizeof (void*) bytes aligned,
- if a <code class="function">malloc()</code> fallback implementation is used instead,
- the alignment may be reduced in a libc dependent fashion.
- Note that the underlying slice allocation mechanism can
- be changed with the [<code class="code">G_SLICE=always-malloc</code>][G_SLICE]
- environment variable.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.287.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>block_size</p></td>
- <td class="parameter_description">
- <p>the number of bytes to allocate</p>
- <p>Passed as <code class="code">block-size</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.288"></a><h3>slice-alloc0</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (slice-alloc0 block-size))
- </pre></div>
- <p>Allocates a block of memory via <code class="function">g_slice_alloc()</code> and initializes
- the returned memory to 0. Note that the underlying slice allocation
- mechanism can be changed with the [<code class="code">G_SLICE=always-malloc</code>][G_SLICE]
- environment variable.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.288.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>block_size</p></td>
- <td class="parameter_description">
- <p>the number of bytes to allocate</p>
- <p>Passed as <code class="code">block-size</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.289"></a><h3>slice-copy</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (slice-copy block-size mem-block))
- </pre></div>
- <p>Allocates a block of memory from the slice allocator
- and copies <em class="parameter"><code>block_size</code></em> bytes into it from <em class="parameter"><code>mem_block</code></em>.
- </p>
- <p><em class="parameter"><code>mem_block</code></em> must be non-<code class="constant">NULL</code> if <em class="parameter"><code>block_size</code></em> is non-zero.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.289.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>block_size</p></td>
- <td class="parameter_description">
- <p>the number of bytes to allocate</p>
- <p>Passed as <code class="code">block-size</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>mem_block</p></td>
- <td class="parameter_description">
- <p>the memory to copy</p>
- <p>Passed as <code class="code">mem-block</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.290"></a><h3>slice-free1</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (slice-free1 block-size mem-block))
- </pre></div>
- <p>Frees a block of memory.
- </p>
- <p>The memory must have been allocated via <code class="function">g_slice_alloc()</code> or
- <code class="function">g_slice_alloc0()</code> and the <em class="parameter"><code>block_size</code></em> has to match the size
- specified upon allocation. Note that the exact release behaviour
- can be changed with the [<code class="code">G_DEBUG=gc-friendly</code>][G_DEBUG] environment
- variable, also see [<code class="code">G_SLICE</code>][G_SLICE] for related debugging options.
- </p>
- <p>If <em class="parameter"><code>mem_block</code></em> is <code class="constant">NULL</code>, this function does nothing.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.290.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>block_size</p></td>
- <td class="parameter_description">
- <p>the size of the block</p>
- <p>Passed as <code class="code">block-size</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>mem_block</p></td>
- <td class="parameter_description">
- <p>a pointer to the block to free</p>
- <p>Passed as <code class="code">mem-block</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.291"></a><h3>slice-free-chain-with-offset</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- ()
- (slice-free-chain-with-offset block-size mem-chain next-offset))
- </pre></div>
- <p>Frees a linked list of memory blocks of structure type <em class="parameter"><code>type</code></em>.
- </p>
- <p>The memory blocks must be equal-sized, allocated via
- <code class="function">g_slice_alloc()</code> or <code class="function">g_slice_alloc0()</code> and linked together by a
- <em class="parameter"><code>next</code></em> pointer (similar to <span class="type">GSList</span>). The offset of the <em class="parameter"><code>next</code></em>
- field in each block is passed as third argument.
- Note that the exact release behaviour can be changed with the
- [<code class="code">G_DEBUG=gc-friendly</code>][G_DEBUG] environment variable, also see
- [<code class="code">G_SLICE</code>][G_SLICE] for related debugging options.
- </p>
- <p>If <em class="parameter"><code>mem_chain</code></em> is <code class="constant">NULL</code>, this function does nothing.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.291.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>block_size</p></td>
- <td class="parameter_description">
- <p>the size of the blocks</p>
- <p>Passed as <code class="code">block-size</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>mem_chain</p></td>
- <td class="parameter_description">
- <p>a pointer to the first block of the chain</p>
- <p>Passed as <code class="code">mem-chain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>next_offset</p></td>
- <td class="parameter_description">
- <p>the offset of the <em class="parameter"><code>next</code></em> field in the blocks</p>
- <p>Passed as <code class="code">next-offset</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.292"></a><h3>slice-get-config</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (slice-get-config ckey))
- </pre></div>
- <p>Undocumented</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.292.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>ckey</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">ckey</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.293"></a><h3>slice-get-config-state</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (slice-get-config-state ckey address n-values))
- </pre></div>
- <p>Undocumented</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.293.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>ckey</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">ckey</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>address</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">address</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>n_values</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">n-values</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.294"></a><h3>slice-set-config</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (slice-set-config ckey value))
- </pre></div>
- <p>Undocumented</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.294.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>ckey</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">ckey</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>value</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">value</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.295"></a><h3>source-remove?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (source-remove? tag))
- </pre></div>
- <p>Removes the source with the given ID from the default main context. You must
- use <code class="function">g_source_destroy()</code> for sources added to a non-default main context.
- </p>
- <p>The ID of a <span class="type">GSource</span> is given by <code class="function">g_source_get_id()</code>, or will be
- returned by the functions <code class="function">g_source_attach()</code>, <code class="function">g_idle_add()</code>,
- <code class="function">g_idle_add_full()</code>, <code class="function">g_timeout_add()</code>, <code class="function">g_timeout_add_full()</code>,
- <code class="function">g_child_watch_add()</code>, <code class="function">g_child_watch_add_full()</code>, <code class="function">g_io_add_watch()</code>, and
- <code class="function">g_io_add_watch_full()</code>.
- </p>
- <p>It is a programmer error to attempt to remove a non-existent source.
- </p>
- <p>More specifically: source IDs can be reissued after a source has been
- destroyed and therefore it is never valid to use this function with a
- source ID which may have already been removed. An example is when
- scheduling an idle to run in another thread with <code class="function">g_idle_add()</code>: the
- idle may already have run and been removed by the time this function
- is called on its (now invalid) source ID. This source ID may have
- been reissued, leading to the operation being performed against the
- wrong source.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.295.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>tag</p></td>
- <td class="parameter_description">
- <p>the ID of the source to remove.</p>
- <p>Passed as <code class="code">tag</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.296"></a><h3>source-remove-by-user-data?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (source-remove-by-user-data? user-data))
- </pre></div>
- <p>Removes a source from the default main loop context given the user
- data for the callback. If multiple sources exist with the same user
- data, only one will be destroyed.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.296.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>user_data</p></td>
- <td class="parameter_description">
- <p>the user_data for the callback.</p>
- <p>Passed as <code class="code">user-data</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.297"></a><h3>source-set-name-by-id</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (source-set-name-by-id tag name))
- </pre></div>
- <p>Sets the name of a source using its ID.
- </p>
- <p>This is a convenience utility to set source names from the return
- value of <code class="function">g_idle_add()</code>, <code class="function">g_timeout_add()</code>, etc.
- </p>
- <p>It is a programmer error to attempt to set the name of a non-existent
- source.
- </p>
- <p>More specifically: source IDs can be reissued after a source has been
- destroyed and therefore it is never valid to use this function with a
- source ID which may have already been removed. An example is when
- scheduling an idle to run in another thread with <code class="function">g_idle_add()</code>: the
- idle may already have run and been removed by the time this function
- is called on its (now invalid) source ID. This source ID may have
- been reissued, leading to the operation being performed against the
- wrong source.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.297.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>tag</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GSource</span> ID</p>
- <p>Passed as <code class="code">tag</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>name</p></td>
- <td class="parameter_description">
- <p>debug name for the source</p>
- <p>Passed as <code class="code">name</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.298"></a><h3>spaced-primes-closest</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (spaced-primes-closest num))
- </pre></div>
- <p>Gets the smallest prime number from a built-in array of primes which
- is larger than <em class="parameter"><code>num</code></em>. This is used within GLib to calculate the optimum
- size of a <span class="type">GHashTable</span>.
- </p>
- <p>The built-in array of primes ranges from 11 to 13845163 such that
- each prime is approximately 1.5-2 times the previous prime.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.298.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>num</p></td>
- <td class="parameter_description">
- <p>a <span class="type">guint</span></p>
- <p>Passed as <code class="code">num</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.299"></a><h3>spawn-async</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return child-pid)
- (spawn-async working-directory argv envp flags child-setup user-data))
- </pre></div>
- <p>See <code class="function">g_spawn_async_with_pipes()</code> for a full description; this function
- simply calls the <code class="function">g_spawn_async_with_pipes()</code> without any pipes.
- </p>
- <p>You should call <code class="function">g_spawn_close_pid()</code> on the returned child process
- reference when you don't need it any more.
- </p>
- <p>If you are writing a GTK+ application, and the program you are spawning is a
- graphical application too, then to ensure that the spawned program opens its
- windows on the right screen, you may want to use <span class="type">GdkAppLaunchContext</span>,
- <span class="type">GAppLaunchContext</span>, or set the <code class="constant">DISPLAY</code> environment variable.
- </p>
- <p>Note that the returned <em class="parameter"><code>child_pid</code></em> on Windows is a handle to the child
- process and not its identifier. Process handles and process identifiers
- are different concepts on Windows.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.299.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>working_directory</p></td>
- <td class="parameter_description">
- <p>child's current working
- directory, or <code class="constant">NULL</code> to inherit parent's</p>
- <p>Passed as <code class="code">working-directory</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>argv</p></td>
- <td class="parameter_description">
- <p>
- </p>
- <p>child's argument vector</p>
- <p>Passed as <code class="code">argv</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>envp</p></td>
- <td class="parameter_description">
- <p>
- </p>
- <p>child's environment, or <code class="constant">NULL</code> to inherit parent's</p>
- <p>Passed as <code class="code">envp</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>flags</p></td>
- <td class="parameter_description">
- <p>flags from <span class="type">GSpawnFlags</span></p>
- <p>Passed as <code class="code">flags</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>child_setup</p></td>
- <td class="parameter_description">
- <p>function to run in the child just before <code class="function">exec()</code></p>
- <p>Passed as <code class="code">child-setup</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>user_data</p></td>
- <td class="parameter_description">
- <p>user data for <em class="parameter"><code>child_setup</code></em></p>
- <p>Passed as <code class="code">user-data</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>child_pid</p></td>
- <td class="parameter_description">
- <p>return location for child process reference, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">child-pid</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.300"></a><h3>spawn-async-with-fds</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return child-pid)
- (spawn-async-with-fds
- working-directory
- argv
- envp
- flags
- child-setup
- user-data
- stdin-fd
- stdout-fd
- stderr-fd))
- </pre></div>
- <p>Identical to <code class="function">g_spawn_async_with_pipes()</code> but instead of
- creating pipes for the stdin/stdout/stderr, you can pass existing
- file descriptors into this function through the <em class="parameter"><code>stdin_fd</code></em>,
- <em class="parameter"><code>stdout_fd</code></em> and <em class="parameter"><code>stderr_fd</code></em> parameters. The following <em class="parameter"><code>flags</code></em>
- also have their behaviour slightly tweaked as a result:
- </p>
- <p><code class="constant">G_SPAWN_STDOUT_TO_DEV_NULL</code> means that the child's standard output
- will be discarded, instead of going to the same location as the parent's
- standard output. If you use this flag, <em class="parameter"><code>standard_output</code></em> must be -1.
- <code class="constant">G_SPAWN_STDERR_TO_DEV_NULL</code> means that the child's standard error
- will be discarded, instead of going to the same location as the parent's
- standard error. If you use this flag, <em class="parameter"><code>standard_error</code></em> must be -1.
- <code class="constant">G_SPAWN_CHILD_INHERITS_STDIN</code> means that the child will inherit the parent's
- standard input (by default, the child's standard input is attached to
- /dev/null). If you use this flag, <em class="parameter"><code>standard_input</code></em> must be -1.
- </p>
- <p>It is valid to pass the same fd in multiple parameters (e.g. you can pass
- a single fd for both stdout and stderr).</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.300.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>working_directory</p></td>
- <td class="parameter_description">
- <p>child's current working directory, or <code class="constant">NULL</code> to inherit parent's, in the GLib file name encoding</p>
- <p>Passed as <code class="code">working-directory</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>argv</p></td>
- <td class="parameter_description">
- <p>child's argument vector, in the GLib file name encoding</p>
- <p>Passed as <code class="code">argv</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>envp</p></td>
- <td class="parameter_description">
- <p>child's environment, or <code class="constant">NULL</code> to inherit parent's, in the GLib file name encoding</p>
- <p>Passed as <code class="code">envp</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>flags</p></td>
- <td class="parameter_description">
- <p>flags from <span class="type">GSpawnFlags</span></p>
- <p>Passed as <code class="code">flags</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>child_setup</p></td>
- <td class="parameter_description">
- <p>function to run in the child just before <code class="function">exec()</code></p>
- <p>Passed as <code class="code">child-setup</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>user_data</p></td>
- <td class="parameter_description">
- <p>user data for <em class="parameter"><code>child_setup</code></em></p>
- <p>Passed as <code class="code">user-data</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>child_pid</p></td>
- <td class="parameter_description">
- <p>return location for child process ID, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">child-pid</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>stdin_fd</p></td>
- <td class="parameter_description">
- <p>file descriptor to use for child's stdin, or -1</p>
- <p>Passed as <code class="code">stdin-fd</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>stdout_fd</p></td>
- <td class="parameter_description">
- <p>file descriptor to use for child's stdout, or -1</p>
- <p>Passed as <code class="code">stdout-fd</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>stderr_fd</p></td>
- <td class="parameter_description">
- <p>file descriptor to use for child's stderr, or -1</p>
- <p>Passed as <code class="code">stderr-fd</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.301"></a><h3>spawn-async-with-pipes</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return child-pid standard-input standard-output standard-error)
- (spawn-async-with-pipes
- working-directory
- argv
- envp
- flags
- child-setup
- user-data))
- </pre></div>
- <p>Executes a child program asynchronously (your program will not
- block waiting for the child to exit). The child program is
- specified by the only argument that must be provided, <em class="parameter"><code>argv</code></em>.
- <em class="parameter"><code>argv</code></em> should be a <code class="constant">NULL</code>-terminated array of strings, to be passed
- as the argument vector for the child. The first string in <em class="parameter"><code>argv</code></em>
- is of course the name of the program to execute. By default, the
- name of the program must be a full path. If <em class="parameter"><code>flags</code></em> contains the
- <code class="constant">G_SPAWN_SEARCH_PATH</code> flag, the <code class="code">PATH</code> environment variable is
- used to search for the executable. If <em class="parameter"><code>flags</code></em> contains the
- <code class="constant">G_SPAWN_SEARCH_PATH_FROM_ENVP</code> flag, the <code class="code">PATH</code> variable from
- <em class="parameter"><code>envp</code></em> is used to search for the executable. If both the
- <code class="constant">G_SPAWN_SEARCH_PATH</code> and <code class="constant">G_SPAWN_SEARCH_PATH_FROM_ENVP</code> flags
- are set, the <code class="code">PATH</code> variable from <em class="parameter"><code>envp</code></em> takes precedence over
- the environment variable.
- </p>
- <p>If the program name is not a full path and <code class="constant">G_SPAWN_SEARCH_PATH</code> flag is not
- used, then the program will be run from the current directory (or
- <em class="parameter"><code>working_directory</code></em>, if specified); this might be unexpected or even
- dangerous in some cases when the current directory is world-writable.
- </p>
- <p>On Windows, note that all the string or string vector arguments to
- this function and the other g_spawn*() functions are in UTF-8, the
- GLib file name encoding. Unicode characters that are not part of
- the system codepage passed in these arguments will be correctly
- available in the spawned program only if it uses wide character API
- to retrieve its command line. For C programs built with Microsoft's
- tools it is enough to make the program have a <code class="function">wmain()</code> instead of
- <code class="function">main()</code>. <code class="function">wmain()</code> has a wide character argument vector as parameter.
- </p>
- <p>At least currently, mingw doesn't support <code class="function">wmain()</code>, so if you use
- mingw to develop the spawned program, it should call
- <code class="function">g_win32_get_command_line()</code> to get arguments in UTF-8.
- </p>
- <p>On Windows the low-level child process creation API <code class="function">CreateProcess()</code>
- doesn't use argument vectors, but a command line. The C runtime
- library's spawn*() family of functions (which <code class="function">g_spawn_async_with_pipes()</code>
- eventually calls) paste the argument vector elements together into
- a command line, and the C runtime startup code does a corresponding
- reconstruction of an argument vector from the command line, to be
- passed to <code class="function">main()</code>. Complications arise when you have argument vector
- elements that contain spaces or double quotes. The <code class="code">spawn*()</code> functions
- don't do any quoting or escaping, but on the other hand the startup
- code does do unquoting and unescaping in order to enable receiving
- arguments with embedded spaces or double quotes. To work around this
- asymmetry, <code class="function">g_spawn_async_with_pipes()</code> will do quoting and escaping on
- argument vector elements that need it before calling the C runtime
- <code class="function">spawn()</code> function.
- </p>
- <p>The returned <em class="parameter"><code>child_pid</code></em> on Windows is a handle to the child
- process, not its identifier. Process handles and process
- identifiers are different concepts on Windows.
- </p>
- <p><em class="parameter"><code>envp</code></em> is a <code class="constant">NULL</code>-terminated array of strings, where each string
- has the form <code class="code">KEY=VALUE</code>. This will become the child's environment.
- If <em class="parameter"><code>envp</code></em> is <code class="constant">NULL</code>, the child inherits its parent's environment.
- </p>
- <p><em class="parameter"><code>flags</code></em> should be the bitwise OR of any flags you want to affect the
- function's behaviour. The <code class="constant">G_SPAWN_DO_NOT_REAP_CHILD</code> means that the
- child will not automatically be reaped; you must use a child watch
- (<code class="function">g_child_watch_add()</code>) to be notified about the death of the child process,
- otherwise it will stay around as a zombie process until this process exits.
- Eventually you must call <code class="function">g_spawn_close_pid()</code> on the <em class="parameter"><code>child_pid</code></em>, in order to
- free resources which may be associated with the child process. (On Unix,
- using a child watch is equivalent to calling <code class="function">waitpid()</code> or handling
- the <code class="constant">SIGCHLD</code> signal manually. On Windows, calling <code class="function">g_spawn_close_pid()</code>
- is equivalent to calling <code class="function">CloseHandle()</code> on the process handle returned
- in <em class="parameter"><code>child_pid</code></em>). See <code class="function">g_child_watch_add()</code>.
- </p>
- <p>Open UNIX file descriptors marked as <code class="code">FD_CLOEXEC</code> will be automatically
- closed in the child process. <code class="constant">G_SPAWN_LEAVE_DESCRIPTORS_OPEN</code> means that
- other open file descriptors will be inherited by the child; otherwise all
- descriptors except stdin/stdout/stderr will be closed before calling <code class="function">exec()</code>
- in the child. <code class="constant">G_SPAWN_SEARCH_PATH</code> means that <em class="parameter"><code>argv</code></em>[0] need not be an
- absolute path, it will be looked for in the <code class="code">PATH</code> environment
- variable. <code class="constant">G_SPAWN_SEARCH_PATH_FROM_ENVP</code> means need not be an
- absolute path, it will be looked for in the <code class="code">PATH</code> variable from
- <em class="parameter"><code>envp</code></em>. If both <code class="constant">G_SPAWN_SEARCH_PATH</code> and <code class="constant">G_SPAWN_SEARCH_PATH_FROM_ENVP</code>
- are used, the value from <em class="parameter"><code>envp</code></em> takes precedence over the environment.
- <code class="constant">G_SPAWN_STDOUT_TO_DEV_NULL</code> means that the child's standard output
- will be discarded, instead of going to the same location as the parent's
- standard output. If you use this flag, <em class="parameter"><code>standard_output</code></em> must be <code class="constant">NULL</code>.
- <code class="constant">G_SPAWN_STDERR_TO_DEV_NULL</code> means that the child's standard error
- will be discarded, instead of going to the same location as the parent's
- standard error. If you use this flag, <em class="parameter"><code>standard_error</code></em> must be <code class="constant">NULL</code>.
- <code class="constant">G_SPAWN_CHILD_INHERITS_STDIN</code> means that the child will inherit the parent's
- standard input (by default, the child's standard input is attached to
- <code class="code">/dev/null</code>). If you use this flag, <em class="parameter"><code>standard_input</code></em> must be <code class="constant">NULL</code>.
- <code class="constant">G_SPAWN_FILE_AND_ARGV_ZERO</code> means that the first element of <em class="parameter"><code>argv</code></em> is
- the file to execute, while the remaining elements are the actual
- argument vector to pass to the file. Normally <code class="function">g_spawn_async_with_pipes()</code>
- uses <em class="parameter"><code>argv</code></em>[0] as the file to execute, and passes all of <em class="parameter"><code>argv</code></em> to the child.
- </p>
- <p><em class="parameter"><code>child_setup</code></em> and <em class="parameter"><code>user_data</code></em> are a function and user data. On POSIX
- platforms, the function is called in the child after GLib has
- performed all the setup it plans to perform (including creating
- pipes, closing file descriptors, etc.) but before calling <code class="function">exec()</code>.
- That is, <em class="parameter"><code>child_setup</code></em> is called just before calling <code class="function">exec()</code> in the
- child. Obviously actions taken in this function will only affect
- the child, not the parent.
- </p>
- <p>On Windows, there is no separate <code class="function">fork()</code> and <code class="function">exec()</code> functionality.
- Child processes are created and run with a single API call,
- <code class="function">CreateProcess()</code>. There is no sensible thing <em class="parameter"><code>child_setup</code></em>
- could be used for on Windows so it is ignored and not called.
- </p>
- <p>If non-<code class="constant">NULL</code>, <em class="parameter"><code>child_pid</code></em> will on Unix be filled with the child's
- process ID. You can use the process ID to send signals to the child,
- or to use <code class="function">g_child_watch_add()</code> (or <code class="function">waitpid()</code>) if you specified the
- <code class="constant">G_SPAWN_DO_NOT_REAP_CHILD</code> flag. On Windows, <em class="parameter"><code>child_pid</code></em> will be
- filled with a handle to the child process only if you specified the
- <code class="constant">G_SPAWN_DO_NOT_REAP_CHILD</code> flag. You can then access the child
- process using the Win32 API, for example wait for its termination
- with the WaitFor*() functions, or examine its exit code with
- <code class="function">GetExitCodeProcess()</code>. You should close the handle with <code class="function">CloseHandle()</code>
- or <code class="function">g_spawn_close_pid()</code> when you no longer need it.
- </p>
- <p>If non-<code class="constant">NULL</code>, the <em class="parameter"><code>standard_input</code></em>, <em class="parameter"><code>standard_output</code></em>, <em class="parameter"><code>standard_error</code></em>
- locations will be filled with file descriptors for writing to the child's
- standard input or reading from its standard output or standard error.
- The caller of <code class="function">g_spawn_async_with_pipes()</code> must close these file descriptors
- when they are no longer in use. If these parameters are <code class="constant">NULL</code>, the
- corresponding pipe won't be created.
- </p>
- <p>If <em class="parameter"><code>standard_input</code></em> is <code class="constant">NULL</code>, the child's standard input is attached to
- <code class="code">/dev/null</code> unless <code class="constant">G_SPAWN_CHILD_INHERITS_STDIN</code> is set.
- </p>
- <p>If <em class="parameter"><code>standard_error</code></em> is NULL, the child's standard error goes to the same
- location as the parent's standard error unless <code class="constant">G_SPAWN_STDERR_TO_DEV_NULL</code>
- is set.
- </p>
- <p>If <em class="parameter"><code>standard_output</code></em> is NULL, the child's standard output goes to the same
- location as the parent's standard output unless <code class="constant">G_SPAWN_STDOUT_TO_DEV_NULL</code>
- is set.
- </p>
- <p><em class="parameter"><code>error</code></em> can be <code class="constant">NULL</code> to ignore errors, or non-<code class="constant">NULL</code> to report errors.
- If an error is set, the function returns <code class="constant">FALSE</code>. Errors are reported
- even if they occur in the child (for example if the executable in
- <em class="parameter"><code>argv</code></em>[0] is not found). Typically the <code class="code">message</code> field of returned
- errors should be displayed to users. Possible errors are those from
- the <span class="type">G_SPAWN_ERROR</span> domain.
- </p>
- <p>If an error occurs, <em class="parameter"><code>child_pid</code></em>, <em class="parameter"><code>standard_input</code></em>, <em class="parameter"><code>standard_output</code></em>,
- and <em class="parameter"><code>standard_error</code></em> will not be filled with valid values.
- </p>
- <p>If <em class="parameter"><code>child_pid</code></em> is not <code class="constant">NULL</code> and an error does not occur then the returned
- process reference must be closed using <code class="function">g_spawn_close_pid()</code>.
- </p>
- <p>On modern UNIX platforms, GLib can use an efficient process launching
- codepath driven internally by <code class="function">posix_spawn()</code>. This has the advantage of
- avoiding the fork-time performance costs of cloning the parent process
- address space, and avoiding associated memory overcommit checks that are
- not relevant in the context of immediately executing a distinct process.
- This optimized codepath will be used provided that the following conditions
- are met:
- </p>
- <p>1. <code class="constant">G_SPAWN_DO_NOT_REAP_CHILD</code> is set
- 2. <code class="constant">G_SPAWN_LEAVE_DESCRIPTORS_OPEN</code> is set
- 3. <code class="constant">G_SPAWN_SEARCH_PATH_FROM_ENVP</code> is not set
- 4. <em class="parameter"><code>working_directory</code></em> is <code class="constant">NULL</code>
- 5. <em class="parameter"><code>child_setup</code></em> is <code class="constant">NULL</code>
- 6. The program is of a recognised binary format, or has a shebang. Otherwise, GLib will have to execute the program through the shell, which is not done using the optimized codepath.
- </p>
- <p>If you are writing a GTK+ application, and the program you are spawning is a
- graphical application too, then to ensure that the spawned program opens its
- windows on the right screen, you may want to use <span class="type">GdkAppLaunchContext</span>,
- <span class="type">GAppLaunchContext</span>, or set the <code class="constant">DISPLAY</code> environment variable.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.301.25"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>working_directory</p></td>
- <td class="parameter_description">
- <p>child's current working
- directory, or <code class="constant">NULL</code> to inherit parent's, in the GLib file name encoding</p>
- <p>Passed as <code class="code">working-directory</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>argv</p></td>
- <td class="parameter_description">
- <p>child's argument
- vector, in the GLib file name encoding</p>
- <p>Passed as <code class="code">argv</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>envp</p></td>
- <td class="parameter_description">
- <p>
- </p>
- <p>child's environment, or <code class="constant">NULL</code> to inherit parent's, in the GLib file
- name encoding</p>
- <p>Passed as <code class="code">envp</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>flags</p></td>
- <td class="parameter_description">
- <p>flags from <span class="type">GSpawnFlags</span></p>
- <p>Passed as <code class="code">flags</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>child_setup</p></td>
- <td class="parameter_description">
- <p>function to run in the child just before <code class="function">exec()</code></p>
- <p>Passed as <code class="code">child-setup</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>user_data</p></td>
- <td class="parameter_description">
- <p>user data for <em class="parameter"><code>child_setup</code></em></p>
- <p>Passed as <code class="code">user-data</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>child_pid</p></td>
- <td class="parameter_description">
- <p>return location for child process ID, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">child-pid</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>standard_input</p></td>
- <td class="parameter_description">
- <p>return location for file descriptor to write to child's stdin, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">standard-input</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>standard_output</p></td>
- <td class="parameter_description">
- <p>return location for file descriptor to read child's stdout, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">standard-output</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>standard_error</p></td>
- <td class="parameter_description">
- <p>return location for file descriptor to read child's stderr, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">standard-error</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.302"></a><h3>spawn-check-exit-status?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (spawn-check-exit-status? wait-status))
- </pre></div>
- <p>Set <em class="parameter"><code>error</code></em> if <em class="parameter"><code>exit_status</code></em> indicates the child exited abnormally
- (e.g. with a nonzero exit code, or via a fatal signal).
- </p>
- <p>The <code class="function">g_spawn_sync()</code> and <code class="function">g_child_watch_add()</code> family of APIs return an
- exit status for subprocesses encoded in a platform-specific way.
- On Unix, this is guaranteed to be in the same format <code class="function">waitpid()</code> returns,
- and on Windows it is guaranteed to be the result of <code class="function">GetExitCodeProcess()</code>.
- </p>
- <p>Prior to the introduction of this function in GLib 2.34, interpreting
- <em class="parameter"><code>exit_status</code></em> required use of platform-specific APIs, which is problematic
- for software using GLib as a cross-platform layer.
- </p>
- <p>Additionally, many programs simply want to determine whether or not
- the child exited successfully, and either propagate a <span class="type">GError</span> or
- print a message to standard error. In that common case, this function
- can be used. Note that the error message in <em class="parameter"><code>error</code></em> will contain
- human-readable information about the exit status.
- </p>
- <p>The <em class="parameter"><code>domain</code></em> and <em class="parameter"><code>code</code></em> of <em class="parameter"><code>error</code></em> have special semantics in the case
- where the process has an "exit code", as opposed to being killed by
- a signal. On Unix, this happens if <code class="function">WIFEXITED()</code> would be true of
- <em class="parameter"><code>exit_status</code></em>. On Windows, it is always the case.
- </p>
- <p>The special semantics are that the actual exit code will be the
- code set in <em class="parameter"><code>error</code></em>, and the domain will be <code class="constant">G_SPAWN_EXIT_ERROR</code>.
- This allows you to differentiate between different exit codes.
- </p>
- <p>If the process was terminated by some means other than an exit
- status, the domain will be <code class="constant">G_SPAWN_ERROR</code>, and the code will be
- <code class="constant">G_SPAWN_ERROR_FAILED</code>.
- </p>
- <p>This function just offers convenience; you can of course also check
- the available platform via a macro such as <code class="constant">G_OS_UNIX</code>, and use
- <code class="function">WIFEXITED()</code> and <code class="function">WEXITSTATUS()</code> on <em class="parameter"><code>exit_status</code></em> directly. Do not attempt
- to scan or parse the error message string; it may be translated and/or
- change in future versions of GLib.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.302.11"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>wait_status</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">wait-status</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.303"></a><h3>spawn-check-wait-status?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (spawn-check-wait-status? wait-status))
- </pre></div>
- <p>Undocumented</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.303.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>wait_status</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">wait-status</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.304"></a><h3>spawn-close-pid</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (spawn-close-pid pid))
- </pre></div>
- <p>On some platforms, notably Windows, the <span class="type">GPid</span> type represents a resource
- which must be closed to prevent resource leaking. <code class="function">g_spawn_close_pid()</code>
- is provided for this purpose. It should be used on all platforms, even
- though it doesn't do anything under UNIX.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.304.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>pid</p></td>
- <td class="parameter_description">
- <p>The process reference to close</p>
- <p>Passed as <code class="code">pid</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.305"></a><h3>spawn-command-line-async?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (spawn-command-line-async? command-line))
- </pre></div>
- <p>A simple version of <code class="function">g_spawn_async()</code> that parses a command line with
- <code class="function">g_shell_parse_argv()</code> and passes it to <code class="function">g_spawn_async()</code>. Runs a
- command line in the background. Unlike <code class="function">g_spawn_async()</code>, the
- <code class="constant">G_SPAWN_SEARCH_PATH</code> flag is enabled, other flags are not. Note
- that <code class="constant">G_SPAWN_SEARCH_PATH</code> can have security implications, so
- consider using <code class="function">g_spawn_async()</code> directly if appropriate. Possible
- errors are those from <code class="function">g_shell_parse_argv()</code> and <code class="function">g_spawn_async()</code>.
- </p>
- <p>The same concerns on Windows apply as for <code class="function">g_spawn_command_line_sync()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.305.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>command_line</p></td>
- <td class="parameter_description">
- <p>a command line</p>
- <p>Passed as <code class="code">command-line</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.306"></a><h3>spawn-command-line-sync</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return standard-output standard-error)
- (spawn-command-line-sync command-line wait-status))
- </pre></div>
- <p>A simple version of <code class="function">g_spawn_sync()</code> with little-used parameters
- removed, taking a command line instead of an argument vector. See
- <code class="function">g_spawn_sync()</code> for full details. <em class="parameter"><code>command_line</code></em> will be parsed by
- <code class="function">g_shell_parse_argv()</code>. Unlike <code class="function">g_spawn_sync()</code>, the <code class="constant">G_SPAWN_SEARCH_PATH</code> flag
- is enabled. Note that <code class="constant">G_SPAWN_SEARCH_PATH</code> can have security
- implications, so consider using <code class="function">g_spawn_sync()</code> directly if
- appropriate. Possible errors are those from <code class="function">g_spawn_sync()</code> and those
- from <code class="function">g_shell_parse_argv()</code>.
- </p>
- <p>If <em class="parameter"><code>exit_status</code></em> is non-<code class="constant">NULL</code>, the platform-specific exit status of
- the child is stored there; see the documentation of
- <code class="function">g_spawn_check_exit_status()</code> for how to use and interpret this.
- </p>
- <p>On Windows, please note the implications of <code class="function">g_shell_parse_argv()</code>
- parsing <em class="parameter"><code>command_line</code></em>. Parsing is done according to Unix shell rules, not
- Windows command interpreter rules.
- Space is a separator, and backslashes are
- special. Thus you cannot simply pass a <em class="parameter"><code>command_line</code></em> containing
- canonical Windows paths, like "c:\\program files\\app\\app.exe", as
- the backslashes will be eaten, and the space will act as a
- separator. You need to enclose such paths with single quotes, like
- "'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'".</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.306.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>command_line</p></td>
- <td class="parameter_description">
- <p>a command line</p>
- <p>Passed as <code class="code">command-line</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>standard_output</p></td>
- <td class="parameter_description">
- <p>return location for child output</p>
- <p>Passed as <code class="code">standard-output</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>standard_error</p></td>
- <td class="parameter_description">
- <p>return location for child errors</p>
- <p>Passed as <code class="code">standard-error</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>wait_status</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">wait-status</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.307"></a><h3>spawn-error-quark</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (spawn-error-quark))
- </pre></div>
- <p>Undocumented</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.308"></a><h3>spawn-exit-error-quark</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (spawn-exit-error-quark))
- </pre></div>
- <p>Undocumented</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.309"></a><h3>spawn-sync</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return standard-output standard-error)
- (spawn-sync
- working-directory
- argv
- envp
- flags
- child-setup
- user-data
- wait-status))
- </pre></div>
- <p>Executes a child synchronously (waits for the child to exit before returning).
- All output from the child is stored in <em class="parameter"><code>standard_output</code></em> and <em class="parameter"><code>standard_error</code></em>,
- if those parameters are non-<code class="constant">NULL</code>. Note that you must set the
- <code class="constant">G_SPAWN_STDOUT_TO_DEV_NULL</code> and <code class="constant">G_SPAWN_STDERR_TO_DEV_NULL</code> flags when
- passing <code class="constant">NULL</code> for <em class="parameter"><code>standard_output</code></em> and <em class="parameter"><code>standard_error</code></em>.
- </p>
- <p>If <em class="parameter"><code>exit_status</code></em> is non-<code class="constant">NULL</code>, the platform-specific exit status of
- the child is stored there; see the documentation of
- <code class="function">g_spawn_check_exit_status()</code> for how to use and interpret this.
- Note that it is invalid to pass <code class="constant">G_SPAWN_DO_NOT_REAP_CHILD</code> in
- <em class="parameter"><code>flags</code></em>, and on POSIX platforms, the same restrictions as for
- <code class="function">g_child_watch_source_new()</code> apply.
- </p>
- <p>If an error occurs, no data is returned in <em class="parameter"><code>standard_output</code></em>,
- <em class="parameter"><code>standard_error</code></em>, or <em class="parameter"><code>exit_status</code></em>.
- </p>
- <p>This function calls <code class="function">g_spawn_async_with_pipes()</code> internally; see that
- function for full details on the other parameters and details on
- how these functions work on Windows.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.309.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>working_directory</p></td>
- <td class="parameter_description">
- <p>child's current working
- directory, or <code class="constant">NULL</code> to inherit parent's</p>
- <p>Passed as <code class="code">working-directory</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>argv</p></td>
- <td class="parameter_description">
- <p>
- </p>
- <p>child's argument vector</p>
- <p>Passed as <code class="code">argv</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>envp</p></td>
- <td class="parameter_description">
- <p>
- </p>
- <p>child's environment, or <code class="constant">NULL</code> to inherit parent's</p>
- <p>Passed as <code class="code">envp</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>flags</p></td>
- <td class="parameter_description">
- <p>flags from <span class="type">GSpawnFlags</span></p>
- <p>Passed as <code class="code">flags</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>child_setup</p></td>
- <td class="parameter_description">
- <p>function to run in the child just before <code class="function">exec()</code></p>
- <p>Passed as <code class="code">child-setup</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>user_data</p></td>
- <td class="parameter_description">
- <p>user data for <em class="parameter"><code>child_setup</code></em></p>
- <p>Passed as <code class="code">user-data</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>standard_output</p></td>
- <td class="parameter_description">
- <p>return location for child output, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">standard-output</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>standard_error</p></td>
- <td class="parameter_description">
- <p>return location for child error messages, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">standard-error</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>wait_status</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">wait-status</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.310"></a><h3>stpcpy</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (stpcpy dest src))
- </pre></div>
- <p>Copies a nul-terminated string into the dest buffer, include the
- trailing nul, and return a pointer to the trailing nul byte.
- This is useful for concatenating multiple strings together
- without having to repeatedly scan for the end.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.310.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>dest</p></td>
- <td class="parameter_description">
- <p>destination buffer.</p>
- <p>Passed as <code class="code">dest</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>src</p></td>
- <td class="parameter_description">
- <p>source string.</p>
- <p>Passed as <code class="code">src</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.311"></a><h3>str-equal?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (str-equal? v1 v2))
- </pre></div>
- <p>Compares two strings for byte-by-byte equality and returns <code class="constant">TRUE</code>
- if they are equal. It can be passed to <code class="function">g_hash_table_new()</code> as the
- <em class="parameter"><code>key_equal_func</code></em> parameter, when using non-<code class="constant">NULL</code> strings as keys in a
- <span class="type">GHashTable</span>.
- </p>
- <p>This function is typically used for hash table comparisons, but can be used
- for general purpose comparisons of non-<code class="constant">NULL</code> strings. For a <code class="constant">NULL</code>-safe string
- comparison function, see <code class="function">g_strcmp0()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.311.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>v1</p></td>
- <td class="parameter_description">
- <p>a key</p>
- <p>Passed as <code class="code">v1</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>v2</p></td>
- <td class="parameter_description">
- <p>a key to compare with <em class="parameter"><code>v1</code></em></p>
- <p>Passed as <code class="code">v2</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.312"></a><h3>str-has-prefix?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (str-has-prefix? str prefix))
- </pre></div>
- <p>Looks whether the string <em class="parameter"><code>str</code></em> begins with <em class="parameter"><code>prefix</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.312.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a nul-terminated string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>prefix</p></td>
- <td class="parameter_description">
- <p>the nul-terminated prefix to look for</p>
- <p>Passed as <code class="code">prefix</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.313"></a><h3>str-has-suffix?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (str-has-suffix? str suffix))
- </pre></div>
- <p>Looks whether the string <em class="parameter"><code>str</code></em> ends with <em class="parameter"><code>suffix</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.313.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a nul-terminated string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>suffix</p></td>
- <td class="parameter_description">
- <p>the nul-terminated suffix to look for</p>
- <p>Passed as <code class="code">suffix</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.314"></a><h3>str-hash</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (str-hash v))
- </pre></div>
- <p>Converts a string to a hash value.
- </p>
- <p>This function implements the widely used "djb" hash apparently
- posted by Daniel Bernstein to comp.lang.c some time ago. The 32
- bit unsigned hash value starts at 5381 and for each byte 'c' in
- the string, is updated: <code class="code">hash = hash * 33 + c</code>. This function
- uses the signed value of each byte.
- </p>
- <p>It can be passed to <code class="function">g_hash_table_new()</code> as the <em class="parameter"><code>hash_func</code></em> parameter,
- when using non-<code class="constant">NULL</code> strings as keys in a <span class="type">GHashTable</span>.
- </p>
- <p>Note that this function may not be a perfect fit for all use cases.
- For example, it produces some hash collisions with strings as short
- as 2.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.314.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>v</p></td>
- <td class="parameter_description">
- <p>a string key</p>
- <p>Passed as <code class="code">v</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.315"></a><h3>str-is-ascii?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (str-is-ascii? str))
- </pre></div>
- <p>Determines if a string is pure ASCII. A string is pure ASCII if it
- contains no bytes with the high bit set.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.315.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.316"></a><h3>str-match-string?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (str-match-string? search-term potential-hit accept-alternates))
- </pre></div>
- <p>Checks if a search conducted for <em class="parameter"><code>search_term</code></em> should match
- <em class="parameter"><code>potential_hit</code></em>.
- </p>
- <p>This function calls <code class="function">g_str_tokenize_and_fold()</code> on both
- <em class="parameter"><code>search_term</code></em> and <em class="parameter"><code>potential_hit</code></em>. ASCII alternates are never taken
- for <em class="parameter"><code>search_term</code></em> but will be taken for <em class="parameter"><code>potential_hit</code></em> according to
- the value of <em class="parameter"><code>accept_alternates</code></em>.
- </p>
- <p>A hit occurs when each folded token in <em class="parameter"><code>search_term</code></em> is a prefix of a
- folded token from <em class="parameter"><code>potential_hit</code></em>.
- </p>
- <p>Depending on how you're performing the search, it will typically be
- faster to call <code class="function">g_str_tokenize_and_fold()</code> on each string in
- your corpus and build an index on the returned folded tokens, then
- call <code class="function">g_str_tokenize_and_fold()</code> on the search term and
- perform lookups into that index.
- </p>
- <p>As some examples, searching for ‘fred’ would match the potential hit
- ‘Smith, Fred’ and also ‘Frédéric’. Searching for ‘Fréd’ would match
- ‘Frédéric’ but not ‘Frederic’ (due to the one-directional nature of
- accent matching). Searching ‘fo’ would match ‘Foo’ and ‘Bar Foo
- Baz’, but not ‘SFO’ (because no word has ‘fo’ as a prefix).</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.316.8"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>search_term</p></td>
- <td class="parameter_description">
- <p>the search term from the user</p>
- <p>Passed as <code class="code">search-term</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>potential_hit</p></td>
- <td class="parameter_description">
- <p>the text that may be a hit</p>
- <p>Passed as <code class="code">potential-hit</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>accept_alternates</p></td>
- <td class="parameter_description">
- <p><code class="constant">TRUE</code> to accept ASCII alternates</p>
- <p>Passed as <code class="code">accept-alternates</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.317"></a><h3>str-to-ascii</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (str-to-ascii str from-locale))
- </pre></div>
- <p>Transliterate <em class="parameter"><code>str</code></em> to plain ASCII.
- </p>
- <p>For best results, <em class="parameter"><code>str</code></em> should be in composed normalised form.
- </p>
- <p>This function performs a reasonably good set of character
- replacements. The particular set of replacements that is done may
- change by version or even by runtime environment.
- </p>
- <p>If the source language of <em class="parameter"><code>str</code></em> is known, it can used to improve the
- accuracy of the translation by passing it as <em class="parameter"><code>from_locale</code></em>. It should
- be a valid POSIX locale string (of the form
- <code class="code">language[_territory][.codeset][@modifier]</code>).
- </p>
- <p>If <em class="parameter"><code>from_locale</code></em> is <code class="constant">NULL</code> then the current locale is used.
- </p>
- <p>If you want to do translation for no specific locale, and you want it
- to be done independently of the currently locale, specify <code class="code">"C"</code> for
- <em class="parameter"><code>from_locale</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.317.9"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a string, in UTF-8</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>from_locale</p></td>
- <td class="parameter_description">
- <p>the source locale, if known</p>
- <p>Passed as <code class="code">from-locale</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.318"></a><h3>str-tokenize-and-fold</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return ascii-alternates)
- (str-tokenize-and-fold string translit-locale))
- </pre></div>
- <p>Tokenises <em class="parameter"><code>string</code></em> and performs folding on each token.
- </p>
- <p>A token is a non-empty sequence of alphanumeric characters in the
- source string, separated by non-alphanumeric characters. An
- "alphanumeric" character for this purpose is one that matches
- <code class="function">g_unichar_isalnum()</code> or <code class="function">g_unichar_ismark()</code>.
- </p>
- <p>Each token is then (Unicode) normalised and case-folded. If
- <em class="parameter"><code>ascii_alternates</code></em> is non-<code class="constant">NULL</code> and some of the returned tokens
- contain non-ASCII characters, ASCII alternatives will be generated.
- </p>
- <p>The number of ASCII alternatives that are generated and the method
- for doing so is unspecified, but <em class="parameter"><code>translit_locale</code></em> (if specified) may
- improve the transliteration if the language of the source string is
- known.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.318.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>a string</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>translit_locale</p></td>
- <td class="parameter_description">
- <p>the language code (like 'de' or
- 'en_GB') from which <em class="parameter"><code>string</code></em> originates</p>
- <p>Passed as <code class="code">translit-locale</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>ascii_alternates</p></td>
- <td class="parameter_description">
- <p>a
- return location for ASCII alternates</p>
- <p>Passed as <code class="code">ascii-alternates</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.319"></a><h3>strcanon</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strcanon string valid-chars substitutor))
- </pre></div>
- <p>For each character in <em class="parameter"><code>string</code></em>, if the character is not in <em class="parameter"><code>valid_chars</code></em>,
- replaces the character with <em class="parameter"><code>substitutor</code></em>. Modifies <em class="parameter"><code>string</code></em> in place,
- and return <em class="parameter"><code>string</code></em> itself, not a copy. The return value is to allow
- nesting such as
- </p>
- <div class="informalexample"><pre class="programlisting">
- g_ascii_strup (g_strcanon (str, "abc", '?'))
- </pre></div>
- <p>In order to modify a copy, you may use <code class="code">g_strdup()</code>:
- </p>
- <div class="informalexample"><pre class="programlisting">
- reformatted = g_strcanon (g_strdup (const_str), "abc", '?');
- ...
- g_free (reformatted);
- </pre></div>
- <div class="refsect3">
- <a name="id-1.1.90.2.319.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>a nul-terminated array of bytes</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>valid_chars</p></td>
- <td class="parameter_description">
- <p>bytes permitted in <em class="parameter"><code>string</code></em></p>
- <p>Passed as <code class="code">valid-chars</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>substitutor</p></td>
- <td class="parameter_description">
- <p>replacement character for disallowed bytes</p>
- <p>Passed as <code class="code">substitutor</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.320"></a><h3>strchomp</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strchomp string))
- </pre></div>
- <p>Removes trailing whitespace from a string.
- </p>
- <p>This function doesn't allocate or reallocate any memory;
- it modifies <em class="parameter"><code>string</code></em> in place. Therefore, it cannot be used
- on statically allocated strings.
- </p>
- <p>The pointer to <em class="parameter"><code>string</code></em> is returned to allow the nesting of functions.
- </p>
- <p>Also see <code class="function">g_strchug()</code> and <code class="function">g_strstrip()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.320.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>a string to remove the trailing whitespace from</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.321"></a><h3>strchug</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strchug string))
- </pre></div>
- <p>Removes leading whitespace from a string, by moving the rest
- of the characters forward.
- </p>
- <p>This function doesn't allocate or reallocate any memory;
- it modifies <em class="parameter"><code>string</code></em> in place. Therefore, it cannot be used on
- statically allocated strings.
- </p>
- <p>The pointer to <em class="parameter"><code>string</code></em> is returned to allow the nesting of functions.
- </p>
- <p>Also see <code class="function">g_strchomp()</code> and <code class="function">g_strstrip()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.321.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>a string to remove the leading whitespace from</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.322"></a><h3>strcmp0</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strcmp0 str1 str2))
- </pre></div>
- <p>Compares <em class="parameter"><code>str1</code></em> and <em class="parameter"><code>str2</code></em> like <code class="function">strcmp()</code>. Handles <code class="constant">NULL</code>
- gracefully by sorting it before non-<code class="constant">NULL</code> strings.
- Comparing two <code class="constant">NULL</code> pointers returns 0.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.322.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str1</p></td>
- <td class="parameter_description">
- <p>a C string or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">str1</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>str2</p></td>
- <td class="parameter_description">
- <p>another C string or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">str2</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.323"></a><h3>strcompress</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strcompress source))
- </pre></div>
- <p>Replaces all escaped characters with their one byte equivalent.
- </p>
- <p>This function does the reverse conversion of <code class="function">g_strescape()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.323.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>source</p></td>
- <td class="parameter_description">
- <p>a string to compress</p>
- <p>Passed as <code class="code">source</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.324"></a><h3>strdelimit</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strdelimit string delimiters new-delimiter))
- </pre></div>
- <p>Converts any delimiter characters in <em class="parameter"><code>string</code></em> to <em class="parameter"><code>new_delimiter</code></em>.
- Any characters in <em class="parameter"><code>string</code></em> which are found in <em class="parameter"><code>delimiters</code></em> are
- changed to the <em class="parameter"><code>new_delimiter</code></em> character. Modifies <em class="parameter"><code>string</code></em> in place,
- and returns <em class="parameter"><code>string</code></em> itself, not a copy. The return value is to
- allow nesting such as
- </p>
- <div class="informalexample"><pre class="programlisting">
- g_ascii_strup (g_strdelimit (str, "abc", '?'))
- </pre></div>
- <p>In order to modify a copy, you may use <code class="code">g_strdup()</code>:
- </p>
- <div class="informalexample"><pre class="programlisting">
- reformatted = g_strdelimit (g_strdup (const_str), "abc", '?');
- ...
- g_free (reformatted);
- </pre></div>
- <div class="refsect3">
- <a name="id-1.1.90.2.324.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>the string to convert</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>delimiters</p></td>
- <td class="parameter_description">
- <p>a string containing the current delimiters,
- or <code class="constant">NULL</code> to use the standard delimiters defined in <span class="type">G_STR_DELIMITERS</span></p>
- <p>Passed as <code class="code">delimiters</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>new_delimiter</p></td>
- <td class="parameter_description">
- <p>the new delimiter character</p>
- <p>Passed as <code class="code">new-delimiter</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.325"></a><h3>strdup</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strdup str))
- </pre></div>
- <p>Duplicates a string. If <em class="parameter"><code>str</code></em> is <code class="constant">NULL</code> it returns <code class="constant">NULL</code>.
- The returned string should be freed with <code class="function">g_free()</code>
- when no longer needed.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.325.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>the string to duplicate</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.326"></a><h3>strerror</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strerror errnum))
- </pre></div>
- <p>Returns a string corresponding to the given error code, e.g. "no
- such process". Unlike <code class="function">strerror()</code>, this always returns a string in
- UTF-8 encoding, and the pointer is guaranteed to remain valid for
- the lifetime of the process.
- </p>
- <p>Note that the string may be translated according to the current locale.
- </p>
- <p>The value of <code class="constant">errno</code> will not be changed by this function. However, it may
- be changed by intermediate function calls, so you should save its value
- as soon as the call returns:
- </p>
- <div class="informalexample"><pre class="programlisting">
- int saved_errno;
- ret = read (blah);
- saved_errno = errno;
- g_strerror (saved_errno);
- </pre></div>
- <div class="refsect3">
- <a name="id-1.1.90.2.326.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>errnum</p></td>
- <td class="parameter_description">
- <p>the system error number. See the standard C <code class="constant">errno</code>
- documentation</p>
- <p>Passed as <code class="code">errnum</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.327"></a><h3>strescape</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strescape source exceptions))
- </pre></div>
- <p>Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\'
- and '"' in the string <em class="parameter"><code>source</code></em> by inserting a '\' before
- them. Additionally all characters in the range 0x01-0x1F (everything
- below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are
- replaced with a '\' followed by their octal representation.
- Characters supplied in <em class="parameter"><code>exceptions</code></em> are not escaped.
- </p>
- <p><code class="function">g_strcompress()</code> does the reverse conversion.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.327.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>source</p></td>
- <td class="parameter_description">
- <p>a string to escape</p>
- <p>Passed as <code class="code">source</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>exceptions</p></td>
- <td class="parameter_description">
- <p>a string of characters not to escape in <em class="parameter"><code>source</code></em></p>
- <p>Passed as <code class="code">exceptions</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.328"></a><h3>strfreev</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (strfreev str-array))
- </pre></div>
- <p>Frees a <code class="constant">NULL</code>-terminated array of strings, as well as each
- string it contains.
- </p>
- <p>If <em class="parameter"><code>str_array</code></em> is <code class="constant">NULL</code>, this function simply returns.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.328.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>str_array</p></td>
- <td class="parameter_description">
- <p>a <code class="constant">NULL</code>-terminated array of strings to free</p>
- <p>Passed as <code class="code">str-array</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.329"></a><h3>string-new</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (string-new init))
- </pre></div>
- <p>Creates a new <span class="type">GString</span>, initialized with the given string.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.329.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>init</p></td>
- <td class="parameter_description">
- <p>the initial text to copy into the string, or <code class="constant">NULL</code> to
- start with an empty string</p>
- <p>Passed as <code class="code">init</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.330"></a><h3>string-new-len</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (string-new-len init len))
- </pre></div>
- <p>Creates a new <span class="type">GString</span> with <em class="parameter"><code>len</code></em> bytes of the <em class="parameter"><code>init</code></em> buffer.
- Because a length is provided, <em class="parameter"><code>init</code></em> need not be nul-terminated,
- and can contain embedded nul bytes.
- </p>
- <p>Since this function does not stop at nul bytes, it is the caller's
- responsibility to ensure that <em class="parameter"><code>init</code></em> has at least <em class="parameter"><code>len</code></em> addressable
- bytes.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.330.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>init</p></td>
- <td class="parameter_description">
- <p>initial contents of the string</p>
- <p>Passed as <code class="code">init</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>length of <em class="parameter"><code>init</code></em> to use</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.331"></a><h3>string-sized-new</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (string-sized-new dfl-size))
- </pre></div>
- <p>Creates a new <span class="type">GString</span>, with enough space for <em class="parameter"><code>dfl_size</code></em>
- bytes. This is useful if you are going to add a lot of
- text to the string and don't want it to be reallocated
- too often.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.331.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>dfl_size</p></td>
- <td class="parameter_description">
- <p>the default size of the space allocated to
- hold the string</p>
- <p>Passed as <code class="code">dfl-size</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.332"></a><h3>strip-context</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strip-context msgid msgval))
- </pre></div>
- <p>An auxiliary function for <code class="function">gettext()</code> support (see <code class="function">Q_()</code>).</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.332.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>msgid</p></td>
- <td class="parameter_description">
- <p>a string</p>
- <p>Passed as <code class="code">msgid</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>msgval</p></td>
- <td class="parameter_description">
- <p>another string</p>
- <p>Passed as <code class="code">msgval</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.333"></a><h3>strjoinv</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strjoinv separator str-array))
- </pre></div>
- <p>Joins a number of strings together to form one long string, with the
- optional <em class="parameter"><code>separator</code></em> inserted between each of them. The returned string
- should be freed with <code class="function">g_free()</code>.
- </p>
- <p>If <em class="parameter"><code>str_array</code></em> has no items, the return value will be an
- empty string. If <em class="parameter"><code>str_array</code></em> contains a single item, <em class="parameter"><code>separator</code></em> will not
- appear in the resulting string.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.333.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>separator</p></td>
- <td class="parameter_description">
- <p>a string to insert between each of the
- strings, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">separator</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>str_array</p></td>
- <td class="parameter_description">
- <p>a <code class="constant">NULL</code>-terminated array of strings to join</p>
- <p>Passed as <code class="code">str-array</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.334"></a><h3>strlcat</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strlcat dest src dest-size))
- </pre></div>
- <p>Portability wrapper that calls <code class="function">strlcat()</code> on systems which have it,
- and emulates it otherwise. Appends nul-terminated <em class="parameter"><code>src</code></em> string to <em class="parameter"><code>dest</code></em>,
- guaranteeing nul-termination for <em class="parameter"><code>dest</code></em>. The total size of <em class="parameter"><code>dest</code></em> won't
- exceed <em class="parameter"><code>dest_size</code></em>.
- </p>
- <p>At most <em class="parameter"><code>dest_size</code></em> - 1 characters will be copied. Unlike <code class="function">strncat()</code>,
- <em class="parameter"><code>dest_size</code></em> is the full size of dest, not the space left over. This
- function does not allocate memory. It always nul-terminates (unless
- <em class="parameter"><code>dest_size</code></em> == 0 or there were no nul characters in the <em class="parameter"><code>dest_size</code></em>
- characters of dest to start with).
- </p>
- <p>Caveat: this is supposedly a more secure alternative to <code class="function">strcat()</code> or
- <code class="function">strncat()</code>, but for real security <code class="function">g_strconcat()</code> is harder to mess up.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.334.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>dest</p></td>
- <td class="parameter_description">
- <p>destination buffer, already containing one nul-terminated string</p>
- <p>Passed as <code class="code">dest</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>src</p></td>
- <td class="parameter_description">
- <p>source buffer</p>
- <p>Passed as <code class="code">src</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>dest_size</p></td>
- <td class="parameter_description">
- <p>length of <em class="parameter"><code>dest</code></em> buffer in bytes (not length of existing string
- inside <em class="parameter"><code>dest</code></em>)</p>
- <p>Passed as <code class="code">dest-size</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.335"></a><h3>strlcpy</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strlcpy dest src dest-size))
- </pre></div>
- <p>Portability wrapper that calls <code class="function">strlcpy()</code> on systems which have it,
- and emulates <code class="function">strlcpy()</code> otherwise. Copies <em class="parameter"><code>src</code></em> to <em class="parameter"><code>dest</code></em>; <em class="parameter"><code>dest</code></em> is
- guaranteed to be nul-terminated; <em class="parameter"><code>src</code></em> must be nul-terminated;
- <em class="parameter"><code>dest_size</code></em> is the buffer size, not the number of bytes to copy.
- </p>
- <p>At most <em class="parameter"><code>dest_size</code></em> - 1 characters will be copied. Always nul-terminates
- (unless <em class="parameter"><code>dest_size</code></em> is 0). This function does not allocate memory. Unlike
- <code class="function">strncpy()</code>, this function doesn't pad <em class="parameter"><code>dest</code></em> (so it's often faster). It
- returns the size of the attempted result, strlen (src), so if
- <em class="parameter"><code>retval</code></em> >= <em class="parameter"><code>dest_size</code></em>, truncation occurred.
- </p>
- <p>Caveat: <code class="function">strlcpy()</code> is supposedly more secure than <code class="function">strcpy()</code> or <code class="function">strncpy()</code>,
- but if you really want to avoid screwups, <code class="function">g_strdup()</code> is an even better
- idea.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.335.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>dest</p></td>
- <td class="parameter_description">
- <p>destination buffer</p>
- <p>Passed as <code class="code">dest</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>src</p></td>
- <td class="parameter_description">
- <p>source buffer</p>
- <p>Passed as <code class="code">src</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>dest_size</p></td>
- <td class="parameter_description">
- <p>length of <em class="parameter"><code>dest</code></em> in bytes</p>
- <p>Passed as <code class="code">dest-size</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.336"></a><h3>strndup</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strndup str n))
- </pre></div>
- <p>Duplicates the first <em class="parameter"><code>n</code></em> bytes of a string, returning a newly-allocated
- buffer <em class="parameter"><code>n</code></em> + 1 bytes long which will always be nul-terminated. If <em class="parameter"><code>str</code></em>
- is less than <em class="parameter"><code>n</code></em> bytes long the buffer is padded with nuls. If <em class="parameter"><code>str</code></em> is
- <code class="constant">NULL</code> it returns <code class="constant">NULL</code>. The returned value should be freed when no longer
- needed.
- </p>
- <p>To copy a number of characters from a UTF-8 encoded string,
- use <code class="function">g_utf8_strncpy()</code> instead.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.336.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>the string to duplicate</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>n</p></td>
- <td class="parameter_description">
- <p>the maximum number of bytes to copy from <em class="parameter"><code>str</code></em></p>
- <p>Passed as <code class="code">n</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.337"></a><h3>strnfill</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strnfill length fill-char))
- </pre></div>
- <p>Creates a new string <em class="parameter"><code>length</code></em> bytes long filled with <em class="parameter"><code>fill_char</code></em>.
- The returned string should be freed when no longer needed.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.337.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>length</p></td>
- <td class="parameter_description">
- <p>the length of the new string</p>
- <p>Passed as <code class="code">length</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>fill_char</p></td>
- <td class="parameter_description">
- <p>the byte to fill the string with</p>
- <p>Passed as <code class="code">fill-char</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.338"></a><h3>strreverse</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strreverse string))
- </pre></div>
- <p>Reverses all of the bytes in a string. For example,
- <code class="code">g_strreverse ("abcdef")</code> will result in "fedcba".
- </p>
- <p>Note that <code class="function">g_strreverse()</code> doesn't work on UTF-8 strings
- containing multibyte characters. For that purpose, use
- <code class="function">g_utf8_strreverse()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.338.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>the string to reverse</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.339"></a><h3>strrstr</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strrstr haystack needle))
- </pre></div>
- <p>Searches the string <em class="parameter"><code>haystack</code></em> for the last occurrence
- of the string <em class="parameter"><code>needle</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.339.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>haystack</p></td>
- <td class="parameter_description">
- <p>a nul-terminated string</p>
- <p>Passed as <code class="code">haystack</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>needle</p></td>
- <td class="parameter_description">
- <p>the nul-terminated string to search for</p>
- <p>Passed as <code class="code">needle</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.340"></a><h3>strrstr-len</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strrstr-len haystack haystack-len needle))
- </pre></div>
- <p>Searches the string <em class="parameter"><code>haystack</code></em> for the last occurrence
- of the string <em class="parameter"><code>needle</code></em>, limiting the length of the search
- to <em class="parameter"><code>haystack_len</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.340.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>haystack</p></td>
- <td class="parameter_description">
- <p>a nul-terminated string</p>
- <p>Passed as <code class="code">haystack</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>haystack_len</p></td>
- <td class="parameter_description">
- <p>the maximum length of <em class="parameter"><code>haystack</code></em></p>
- <p>Passed as <code class="code">haystack-len</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>needle</p></td>
- <td class="parameter_description">
- <p>the nul-terminated string to search for</p>
- <p>Passed as <code class="code">needle</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.341"></a><h3>strsignal</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strsignal signum))
- </pre></div>
- <p>Returns a string describing the given signal, e.g. "Segmentation fault".
- You should use this function in preference to <code class="function">strsignal()</code>, because it
- returns a string in UTF-8 encoding, and since not all platforms support
- the <code class="function">strsignal()</code> function.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.341.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>signum</p></td>
- <td class="parameter_description">
- <p>the signal number. See the <code class="code">signal</code> documentation</p>
- <p>Passed as <code class="code">signum</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.342"></a><h3>strstr-len</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strstr-len haystack haystack-len needle))
- </pre></div>
- <p>Searches the string <em class="parameter"><code>haystack</code></em> for the first occurrence
- of the string <em class="parameter"><code>needle</code></em>, limiting the length of the search
- to <em class="parameter"><code>haystack_len</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.342.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>haystack</p></td>
- <td class="parameter_description">
- <p>a string</p>
- <p>Passed as <code class="code">haystack</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>haystack_len</p></td>
- <td class="parameter_description">
- <p>the maximum length of <em class="parameter"><code>haystack</code></em>. Note that -1 is
- a valid length, if <em class="parameter"><code>haystack</code></em> is nul-terminated, meaning it will
- search through the whole string.</p>
- <p>Passed as <code class="code">haystack-len</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>needle</p></td>
- <td class="parameter_description">
- <p>the string to search for</p>
- <p>Passed as <code class="code">needle</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.343"></a><h3>strtod</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return endptr) (strtod nptr))
- </pre></div>
- <p>Converts a string to a <span class="type">gdouble</span> value.
- It calls the standard <code class="function">strtod()</code> function to handle the conversion, but
- if the string is not completely converted it attempts the conversion
- again with <code class="function">g_ascii_strtod()</code>, and returns the best match.
- </p>
- <p>This function should seldom be used. The normal situation when reading
- numbers not for human consumption is to use <code class="function">g_ascii_strtod()</code>. Only when
- you know that you must expect both locale formatted and C formatted numbers
- should you use this. Make sure that you don't pass strings such as comma
- separated lists of values, since the commas may be interpreted as a decimal
- point in some locales, causing unexpected results.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.343.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>nptr</p></td>
- <td class="parameter_description">
- <p>the string to convert to a numeric value.</p>
- <p>Passed as <code class="code">nptr</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>endptr</p></td>
- <td class="parameter_description">
- <p>if non-<code class="constant">NULL</code>, it returns the
- character after the last character used in the conversion.</p>
- <p>Passed as <code class="code">endptr</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.344"></a><h3>strv-contains?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strv-contains? strv str))
- </pre></div>
- <p>Checks if <em class="parameter"><code>strv</code></em> contains <em class="parameter"><code>str</code></em>. <em class="parameter"><code>strv</code></em> must not be <code class="constant">NULL</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.344.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>strv</p></td>
- <td class="parameter_description">
- <p>a <code class="constant">NULL</code>-terminated array of strings</p>
- <p>Passed as <code class="code">strv</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.345"></a><h3>strv-equal?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strv-equal? strv1 strv2))
- </pre></div>
- <p>Checks if <em class="parameter"><code>strv1</code></em> and <em class="parameter"><code>strv2</code></em> contain exactly the same elements in exactly the
- same order. Elements are compared using <code class="function">g_str_equal()</code>. To match independently
- of order, sort the arrays first (using <code class="function">g_qsort_with_data()</code> or similar).
- </p>
- <p>Two empty arrays are considered equal. Neither <em class="parameter"><code>strv1</code></em> not <em class="parameter"><code>strv2</code></em> may be
- <code class="constant">NULL</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.345.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>strv1</p></td>
- <td class="parameter_description">
- <p>a <code class="constant">NULL</code>-terminated array of strings</p>
- <p>Passed as <code class="code">strv1</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>strv2</p></td>
- <td class="parameter_description">
- <p>another <code class="constant">NULL</code>-terminated array of strings</p>
- <p>Passed as <code class="code">strv2</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.346"></a><h3>strv-get-type</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strv-get-type))
- </pre></div>
- <p>Undocumented</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.347"></a><h3>strv-length</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (strv-length str-array))
- </pre></div>
- <p>Returns the length of the given <code class="constant">NULL</code>-terminated
- string array <em class="parameter"><code>str_array</code></em>. <em class="parameter"><code>str_array</code></em> must not be <code class="constant">NULL</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.347.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>str_array</p></td>
- <td class="parameter_description">
- <p>a <code class="constant">NULL</code>-terminated array of strings</p>
- <p>Passed as <code class="code">str-array</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.348"></a><h3>test-add-data-func</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (test-add-data-func testpath test-data test-func))
- </pre></div>
- <p>Create a new test case, similar to <code class="function">g_test_create_case()</code>. However
- the test is assumed to use no fixture, and test suites are automatically
- created on the fly and added to the root fixture, based on the
- slash-separated portions of <em class="parameter"><code>testpath</code></em>. The <em class="parameter"><code>test_data</code></em> argument
- will be passed as first argument to <em class="parameter"><code>test_func</code></em>.
- </p>
- <p>If <em class="parameter"><code>testpath</code></em> includes the component "subprocess" anywhere in it,
- the test will be skipped by default, and only run if explicitly
- required via the <code class="code">-p</code> command-line option or <code class="function">g_test_trap_subprocess()</code>.
- </p>
- <p>No component of <em class="parameter"><code>testpath</code></em> may start with a dot (<code class="code">.</code>) if the
- <code class="constant">G_TEST_OPTION_ISOLATE_DIRS</code> option is being used; and it is recommended to
- do so even if it isn’t.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.348.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>testpath</p></td>
- <td class="parameter_description">
- <p>/-separated test case path name for the test.</p>
- <p>Passed as <code class="code">testpath</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>test_data</p></td>
- <td class="parameter_description">
- <p>Test data argument for the test function.</p>
- <p>Passed as <code class="code">test-data</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>test_func</p></td>
- <td class="parameter_description">
- <p>The test function to invoke for this test.</p>
- <p>Passed as <code class="code">test-func</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.349"></a><h3>test-add-data-func-full</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- ()
- (test-add-data-func-full testpath test-data test-func data-free-func))
- </pre></div>
- <p>Create a new test case, as with <code class="function">g_test_add_data_func()</code>, but freeing
- <em class="parameter"><code>test_data</code></em> after the test run is complete.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.349.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>testpath</p></td>
- <td class="parameter_description">
- <p>/-separated test case path name for the test.</p>
- <p>Passed as <code class="code">testpath</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>test_data</p></td>
- <td class="parameter_description">
- <p>Test data argument for the test function.</p>
- <p>Passed as <code class="code">test-data</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>test_func</p></td>
- <td class="parameter_description">
- <p>The test function to invoke for this test.</p>
- <p>Passed as <code class="code">test-func</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>data_free_func</p></td>
- <td class="parameter_description">
- <p><span class="type">GDestroyNotify</span> for <em class="parameter"><code>test_data</code></em>.</p>
- <p>Passed as <code class="code">data-free-func</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.350"></a><h3>test-add-func</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (test-add-func testpath test-func))
- </pre></div>
- <p>Create a new test case, similar to <code class="function">g_test_create_case()</code>. However
- the test is assumed to use no fixture, and test suites are automatically
- created on the fly and added to the root fixture, based on the
- slash-separated portions of <em class="parameter"><code>testpath</code></em>.
- </p>
- <p>If <em class="parameter"><code>testpath</code></em> includes the component "subprocess" anywhere in it,
- the test will be skipped by default, and only run if explicitly
- required via the <code class="code">-p</code> command-line option or <code class="function">g_test_trap_subprocess()</code>.
- </p>
- <p>No component of <em class="parameter"><code>testpath</code></em> may start with a dot (<code class="code">.</code>) if the
- <code class="constant">G_TEST_OPTION_ISOLATE_DIRS</code> option is being used; and it is recommended to
- do so even if it isn’t.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.350.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>testpath</p></td>
- <td class="parameter_description">
- <p>/-separated test case path name for the test.</p>
- <p>Passed as <code class="code">testpath</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>test_func</p></td>
- <td class="parameter_description">
- <p>The test function to invoke for this test.</p>
- <p>Passed as <code class="code">test-func</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.351"></a><h3>test-assert-expected-messages-internal</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- ()
- (test-assert-expected-messages-internal domain file line func))
- </pre></div>
- <p>Undocumented</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.351.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>domain</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">domain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>file</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">file</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>line</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">line</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>func</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">func</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.352"></a><h3>test-bug</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (test-bug bug-uri-snippet))
- </pre></div>
- <p>This function adds a message to test reports that
- associates a bug URI with a test case.
- Bug URIs are constructed from a base URI set with <code class="function">g_test_bug_base()</code>
- and <em class="parameter"><code>bug_uri_snippet</code></em>. If <code class="function">g_test_bug_base()</code> has not been called, it is
- assumed to be the empty string, so a full URI can be provided to
- <code class="function">g_test_bug()</code> instead.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.352.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>bug_uri_snippet</p></td>
- <td class="parameter_description">
- <p>Bug specific bug tracker URI portion.</p>
- <p>Passed as <code class="code">bug-uri-snippet</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.353"></a><h3>test-bug-base</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (test-bug-base uri-pattern))
- </pre></div>
- <p>Specify the base URI for bug reports.
- </p>
- <p>The base URI is used to construct bug report messages for
- <code class="function">g_test_message()</code> when <code class="function">g_test_bug()</code> is called.
- Calling this function outside of a test case sets the
- default base URI for all test cases. Calling it from within
- a test case changes the base URI for the scope of the test
- case only.
- Bug URIs are constructed by appending a bug specific URI
- portion to <em class="parameter"><code>uri_pattern</code></em>, or by replacing the special string
- '\%s' within <em class="parameter"><code>uri_pattern</code></em> if that is present.
- </p>
- <p>If <code class="function">g_test_bug_base()</code> is not called, bug URIs are formed solely
- from the value provided by <code class="function">g_test_bug()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.353.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>uri_pattern</p></td>
- <td class="parameter_description">
- <p>the base pattern for bug URIs</p>
- <p>Passed as <code class="code">uri-pattern</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.354"></a><h3>test-expect-message</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (test-expect-message log-domain log-level pattern))
- </pre></div>
- <p>Indicates that a message with the given <em class="parameter"><code>log_domain</code></em> and <em class="parameter"><code>log_level</code></em>,
- with text matching <em class="parameter"><code>pattern</code></em>, is expected to be logged. When this
- message is logged, it will not be printed, and the test case will
- not abort.
- </p>
- <p>This API may only be used with the old logging API (<code class="function">g_log()</code> without
- <code class="constant">G_LOG_USE_STRUCTURED</code> defined). It will not work with the structured logging
- API. See [Testing for Messages][testing-for-messages].
- </p>
- <p>Use <code class="function">g_test_assert_expected_messages()</code> to assert that all
- previously-expected messages have been seen and suppressed.
- </p>
- <p>You can call this multiple times in a row, if multiple messages are
- expected as a result of a single call. (The messages must appear in
- the same order as the calls to <code class="function">g_test_expect_message()</code>.)
- </p>
- <p>For example:
- </p>
- <div class="informalexample"><pre class="programlisting">
- // g_main_context_push_thread_default() should fail if the
- // context is already owned by another thread.
- g_test_expect_message (G_LOG_DOMAIN,
- G_LOG_LEVEL_CRITICAL,
- "assertion*acquired_context*failed");
- g_main_context_push_thread_default (bad_context);
- g_test_assert_expected_messages ();
- </pre></div>
- <p>Note that you cannot use this to test <code class="function">g_error()</code> messages, since
- <code class="function">g_error()</code> intentionally never returns even if the program doesn't
- abort; use <code class="function">g_test_trap_subprocess()</code> in this case.
- </p>
- <p>If messages at <code class="constant">G_LOG_LEVEL_DEBUG</code> are emitted, but not explicitly
- expected via <code class="function">g_test_expect_message()</code> then they will be ignored.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.354.11"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>log_domain</p></td>
- <td class="parameter_description">
- <p>the log domain of the message</p>
- <p>Passed as <code class="code">log-domain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>log_level</p></td>
- <td class="parameter_description">
- <p>the log level of the message</p>
- <p>Passed as <code class="code">log-level</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>pattern</p></td>
- <td class="parameter_description">
- <p>a glob-style [pattern][glib-Glob-style-pattern-matching]</p>
- <p>Passed as <code class="code">pattern</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.355"></a><h3>test-fail</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (test-fail))
- </pre></div>
- <p>Indicates that a test failed. This function can be called
- multiple times from the same test. You can use this function
- if your test failed in a recoverable way.
- </p>
- <p>Do not use this function if the failure of a test could cause
- other tests to malfunction.
- </p>
- <p>Calling this function will not stop the test from running, you
- need to return from the test function yourself. So you can
- produce additional diagnostic messages or even continue running
- the test.
- </p>
- <p>If not called from inside a test, this function does nothing.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.356"></a><h3>test-failed?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (test-failed?))
- </pre></div>
- <p>Returns whether a test has already failed. This will
- be the case when <code class="function">g_test_fail()</code>, <code class="function">g_test_incomplete()</code>
- or <code class="function">g_test_skip()</code> have been called, but also if an
- assertion has failed.
- </p>
- <p>This can be useful to return early from a test if
- continuing after a failed assertion might be harmful.
- </p>
- <p>The return value of this function is only meaningful
- if it is called from inside a test function.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.357"></a><h3>test-get-dir</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (test-get-dir file-type))
- </pre></div>
- <p>Gets the pathname of the directory containing test files of the type
- specified by <em class="parameter"><code>file_type</code></em>.
- </p>
- <p>This is approximately the same as calling g_test_build_filename("."),
- but you don't need to free the return value.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.357.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>file_type</p></td>
- <td class="parameter_description">
- <p>the type of file (built vs. distributed)</p>
- <p>Passed as <code class="code">file-type</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.358"></a><h3>test-get-path</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (test-get-path))
- </pre></div>
- <p>Undocumented</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.359"></a><h3>test-incomplete</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (test-incomplete msg))
- </pre></div>
- <p>Indicates that a test failed because of some incomplete
- functionality. This function can be called multiple times
- from the same test.
- </p>
- <p>Calling this function will not stop the test from running, you
- need to return from the test function yourself. So you can
- produce additional diagnostic messages or even continue running
- the test.
- </p>
- <p>If not called from inside a test, this function does nothing.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.359.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>msg</p></td>
- <td class="parameter_description">
- <p>explanation</p>
- <p>Passed as <code class="code">msg</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.360"></a><h3>test-log-type-name</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (test-log-type-name log-type))
- </pre></div>
- <p>Undocumented</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.360.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>log_type</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">log-type</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.361"></a><h3>test-queue-destroy</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (test-queue-destroy destroy-func destroy-data))
- </pre></div>
- <p>This function enqueus a callback <em class="parameter"><code>destroy_func</code></em> to be executed
- during the next test case teardown phase. This is most useful
- to auto destruct allocated test resources at the end of a test run.
- Resources are released in reverse queue order, that means enqueueing
- callback A before callback B will cause <code class="function">B()</code> to be called before
- <code class="function">A()</code> during teardown.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.361.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>destroy_func</p></td>
- <td class="parameter_description">
- <p>Destroy callback for teardown phase.</p>
- <p>Passed as <code class="code">destroy-func</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>destroy_data</p></td>
- <td class="parameter_description">
- <p>Destroy callback data.</p>
- <p>Passed as <code class="code">destroy-data</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.362"></a><h3>test-queue-free</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (test-queue-free gfree-pointer))
- </pre></div>
- <p>Enqueue a pointer to be released with <code class="function">g_free()</code> during the next
- teardown phase. This is equivalent to calling <code class="function">g_test_queue_destroy()</code>
- with a destroy callback of <code class="function">g_free()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.362.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>gfree_pointer</p></td>
- <td class="parameter_description">
- <p>the pointer to be stored.</p>
- <p>Passed as <code class="code">gfree-pointer</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.363"></a><h3>test-rand-double</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (test-rand-double))
- </pre></div>
- <p>Get a reproducible random floating point number,
- see <code class="function">g_test_rand_int()</code> for details on test case random numbers.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.364"></a><h3>test-rand-double-range</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (test-rand-double-range range-start range-end))
- </pre></div>
- <p>Get a reproducible random floating pointer number out of a specified range,
- see <code class="function">g_test_rand_int()</code> for details on test case random numbers.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.364.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>range_start</p></td>
- <td class="parameter_description">
- <p>the minimum value returned by this function</p>
- <p>Passed as <code class="code">range-start</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>range_end</p></td>
- <td class="parameter_description">
- <p>the minimum value not returned by this function</p>
- <p>Passed as <code class="code">range-end</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.365"></a><h3>test-rand-int</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (test-rand-int))
- </pre></div>
- <p>Get a reproducible random integer number.
- </p>
- <p>The random numbers generated by the g_test_rand_*() family of functions
- change with every new test program start, unless the --seed option is
- given when starting test programs.
- </p>
- <p>For individual test cases however, the random number generator is
- reseeded, to avoid dependencies between tests and to make --seed
- effective for all test cases.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.366"></a><h3>test-rand-int-range</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (test-rand-int-range begin end))
- </pre></div>
- <p>Get a reproducible random integer number out of a specified range,
- see <code class="function">g_test_rand_int()</code> for details on test case random numbers.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.366.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>begin</p></td>
- <td class="parameter_description">
- <p>the minimum value returned by this function</p>
- <p>Passed as <code class="code">begin</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>end</p></td>
- <td class="parameter_description">
- <p>the smallest value not to be returned by this function</p>
- <p>Passed as <code class="code">end</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.367"></a><h3>test-run</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (test-run))
- </pre></div>
- <p>Runs all tests under the toplevel suite which can be retrieved
- with <code class="function">g_test_get_root()</code>. Similar to <code class="function">g_test_run_suite()</code>, the test
- cases to be run are filtered according to test path arguments
- (<code class="code">-p testpath</code> and <code class="code">-s testpath</code>) as parsed by <code class="function">g_test_init()</code>.
- <code class="function">g_test_run_suite()</code> or <code class="function">g_test_run()</code> may only be called once in a
- program.
- </p>
- <p>In general, the tests and sub-suites within each suite are run in
- the order in which they are defined. However, note that prior to
- GLib 2.36, there was a bug in the <code class="code">g_test_add_*</code>
- functions which caused them to create multiple suites with the same
- name, meaning that if you created tests "/foo/simple",
- "/bar/simple", and "/foo/using-bar" in that order, they would get
- run in that order (since <code class="function">g_test_run()</code> would run the first "/foo"
- suite, then the "/bar" suite, then the second "/foo" suite). As of
- 2.36, this bug is fixed, and adding the tests in that order would
- result in a running order of "/foo/simple", "/foo/using-bar",
- "/bar/simple". If this new ordering is sub-optimal (because it puts
- more-complicated tests before simpler ones, making it harder to
- figure out exactly what has failed), you can fix it by changing the
- test paths to group tests by suite in a way that will result in the
- desired running order. Eg, "/simple/foo", "/simple/bar",
- "/complex/foo-using-bar".
- </p>
- <p>However, you should never make the actual result of a test depend
- on the order that tests are run in. If you need to ensure that some
- particular code runs before or after a given test case, use
- <code class="function">g_test_add()</code>, which lets you specify setup and teardown functions.
- </p>
- <p>If all tests are skipped or marked as incomplete (expected failures),
- this function will return 0 if producing TAP output, or 77 (treated
- as "skip test" by Automake) otherwise.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.368"></a><h3>test-set-nonfatal-assertions</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (test-set-nonfatal-assertions))
- </pre></div>
- <p>Changes the behaviour of the various <code class="code">g_assert_*()</code> macros,
- <code class="function">g_test_assert_expected_messages()</code> and the various
- <code class="code">g_test_trap_assert_*()</code> macros to not abort to program, but instead
- call <code class="function">g_test_fail()</code> and continue. (This also changes the behavior of
- <code class="function">g_test_fail()</code> so that it will not cause the test program to abort
- after completing the failed test.)
- </p>
- <p>Note that the <code class="function">g_assert_not_reached()</code> and <code class="function">g_assert()</code> macros are not
- affected by this.
- </p>
- <p>This function can only be called after <code class="function">g_test_init()</code>.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.369"></a><h3>test-skip</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (test-skip msg))
- </pre></div>
- <p>Indicates that a test was skipped.
- </p>
- <p>Calling this function will not stop the test from running, you
- need to return from the test function yourself. So you can
- produce additional diagnostic messages or even continue running
- the test.
- </p>
- <p>If not called from inside a test, this function does nothing.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.369.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>msg</p></td>
- <td class="parameter_description">
- <p>explanation</p>
- <p>Passed as <code class="code">msg</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.370"></a><h3>test-subprocess?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (test-subprocess?))
- </pre></div>
- <p>Returns <code class="constant">TRUE</code> (after <code class="function">g_test_init()</code> has been called) if the test
- program is running under <code class="function">g_test_trap_subprocess()</code>.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.371"></a><h3>test-summary</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (test-summary summary))
- </pre></div>
- <p>Set the summary for a test, which describes what the test checks, and how it
- goes about checking it. This may be included in test report output, and is
- useful documentation for anyone reading the source code or modifying a test
- in future. It must be a single line.
- </p>
- <p>This should be called at the top of a test function.
- </p>
- <p>For example:
- </p>
- <div class="informalexample"><pre class="programlisting">
- static void
- test_array_sort (void)
- {
- g_test_summary ("Test my_array_sort() sorts the array correctly and stably, "
- "including testing zero length and one-element arrays.");
- …
- }
- </pre></div>
- <div class="refsect3">
- <a name="id-1.1.90.2.371.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>summary</p></td>
- <td class="parameter_description">
- <p>One or two sentences summarising what the test checks, and how it
- checks it.</p>
- <p>Passed as <code class="code">summary</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.372"></a><h3>test-timer-elapsed</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (test-timer-elapsed))
- </pre></div>
- <p>Get the time since the last start of the timer with <code class="function">g_test_timer_start()</code>.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.373"></a><h3>test-timer-last</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (test-timer-last))
- </pre></div>
- <p>Report the last result of <code class="function">g_test_timer_elapsed()</code>.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.374"></a><h3>test-timer-start</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (test-timer-start))
- </pre></div>
- <p>Start a timing test. Call <code class="function">g_test_timer_elapsed()</code> when the task is supposed
- to be done. Call this function again to restart the timer.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.375"></a><h3>test-trap-assertions</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- ()
- (test-trap-assertions domain file line func assertion-flags pattern))
- </pre></div>
- <p>Undocumented</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.375.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>domain</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">domain</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>file</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">file</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>line</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">line</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>func</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">func</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>assertion_flags</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">assertion-flags</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>pattern</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">pattern</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.376"></a><h3>test-trap-has-passed?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (test-trap-has-passed?))
- </pre></div>
- <p>Check the result of the last <code class="function">g_test_trap_subprocess()</code> call.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.377"></a><h3>test-trap-reached-timeout?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (test-trap-reached-timeout?))
- </pre></div>
- <p>Check the result of the last <code class="function">g_test_trap_subprocess()</code> call.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.378"></a><h3>test-trap-subprocess</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (test-trap-subprocess test-path usec-timeout test-flags))
- </pre></div>
- <p>Respawns the test program to run only <em class="parameter"><code>test_path</code></em> in a subprocess.
- This can be used for a test case that might not return, or that
- might abort.
- </p>
- <p>If <em class="parameter"><code>test_path</code></em> is <code class="constant">NULL</code> then the same test is re-run in a subprocess.
- You can use <code class="function">g_test_subprocess()</code> to determine whether the test is in
- a subprocess or not.
- </p>
- <p><em class="parameter"><code>test_path</code></em> can also be the name of the parent test, followed by
- "`/subprocess/<code class="code">" and then a name for the specific subtest (or just
- ending with "</code>/subprocess`" if the test only has one child test);
- tests with names of this form will automatically be skipped in the
- parent process.
- </p>
- <p>If <em class="parameter"><code>usec_timeout</code></em> is non-0, the test subprocess is aborted and
- considered failing if its run time exceeds it.
- </p>
- <p>The subprocess behavior can be configured with the
- <span class="type">GTestSubprocessFlags</span> flags.
- </p>
- <p>You can use methods such as <code class="function">g_test_trap_assert_passed()</code>,
- <code class="function">g_test_trap_assert_failed()</code>, and <code class="function">g_test_trap_assert_stderr()</code> to
- check the results of the subprocess. (But note that
- <code class="function">g_test_trap_assert_stdout()</code> and <code class="function">g_test_trap_assert_stderr()</code>
- cannot be used if <em class="parameter"><code>test_flags</code></em> specifies that the child should
- inherit the parent stdout/stderr.)
- </p>
- <p>If your <code class="code">main ()</code> needs to behave differently in
- the subprocess, you can call <code class="function">g_test_subprocess()</code> (after calling
- <code class="function">g_test_init()</code>) to see whether you are in a subprocess.
- </p>
- <p>The following example tests that calling
- <code class="code">my_object_new(1000000)</code> will abort with an error
- message.
- </p>
- <div class="informalexample"><pre class="programlisting">
- static void
- test_create_large_object (void)
- {
- if (g_test_subprocess ())
- {
- my_object_new (1000000);
- return;
- }
- // Reruns this same test in a subprocess
- g_test_trap_subprocess (NULL, 0, 0);
- g_test_trap_assert_failed ();
- g_test_trap_assert_stderr ("*ERROR*too large*");
- }
- int
- main (int argc, char **argv)
- {
- g_test_init (&argc, &argv, NULL);
- g_test_add_func ("/myobject/create_large_object",
- test_create_large_object);
- return g_test_run ();
- }
- </pre></div>
- <div class="refsect3">
- <a name="id-1.1.90.2.378.12"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>test_path</p></td>
- <td class="parameter_description">
- <p>Test to run in a subprocess</p>
- <p>Passed as <code class="code">test-path</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>usec_timeout</p></td>
- <td class="parameter_description">
- <p>Timeout for the subprocess test in micro seconds.</p>
- <p>Passed as <code class="code">usec-timeout</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>test_flags</p></td>
- <td class="parameter_description">
- <p>Flags to modify subprocess behaviour.</p>
- <p>Passed as <code class="code">test-flags</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.379"></a><h3>thread-error-quark</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (thread-error-quark))
- </pre></div>
- <p>Undocumented</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.380"></a><h3>thread-exit</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (thread-exit retval))
- </pre></div>
- <p>Terminates the current thread.
- </p>
- <p>If another thread is waiting for us using <code class="function">g_thread_join()</code> then the
- waiting thread will be woken up and get <em class="parameter"><code>retval</code></em> as the return value
- of <code class="function">g_thread_join()</code>.
- </p>
- <p>Calling <code class="function">g_thread_exit()</code> with a parameter <em class="parameter"><code>retval</code></em> is equivalent to
- returning <em class="parameter"><code>retval</code></em> from the function <em class="parameter"><code>func</code></em>, as given to <code class="function">g_thread_new()</code>.
- </p>
- <p>You must only call <code class="function">g_thread_exit()</code> from a thread that you created
- yourself with <code class="function">g_thread_new()</code> or related APIs. You must not call
- this function from a thread created with another threading library
- or or from within a <span class="type">GThreadPool</span>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.380.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>retval</p></td>
- <td class="parameter_description">
- <p>the return value of this thread</p>
- <p>Passed as <code class="code">retval</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.381"></a><h3>thread-pool-get-max-idle-time</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (thread-pool-get-max-idle-time))
- </pre></div>
- <p>This function will return the maximum <em class="parameter"><code>interval</code></em> that a
- thread will wait in the thread pool for new tasks before
- being stopped.
- </p>
- <p>If this function returns 0, threads waiting in the thread
- pool for new work are not stopped.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.382"></a><h3>thread-pool-get-max-unused-threads</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (thread-pool-get-max-unused-threads))
- </pre></div>
- <p>Returns the maximal allowed number of unused threads.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.383"></a><h3>thread-pool-get-num-unused-threads</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (thread-pool-get-num-unused-threads))
- </pre></div>
- <p>Returns the number of currently unused threads.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.384"></a><h3>thread-pool-set-max-idle-time</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (thread-pool-set-max-idle-time interval))
- </pre></div>
- <p>This function will set the maximum <em class="parameter"><code>interval</code></em> that a thread
- waiting in the pool for new tasks can be idle for before
- being stopped. This function is similar to calling
- <code class="function">g_thread_pool_stop_unused_threads()</code> on a regular timeout,
- except this is done on a per thread basis.
- </p>
- <p>By setting <em class="parameter"><code>interval</code></em> to 0, idle threads will not be stopped.
- </p>
- <p>The default value is 15000 (15 seconds).</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.384.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>interval</p></td>
- <td class="parameter_description">
- <p>the maximum <em class="parameter"><code>interval</code></em> (in milliseconds)
- a thread can be idle</p>
- <p>Passed as <code class="code">interval</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.385"></a><h3>thread-pool-set-max-unused-threads</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (thread-pool-set-max-unused-threads max-threads))
- </pre></div>
- <p>Sets the maximal number of unused threads to <em class="parameter"><code>max_threads</code></em>.
- If <em class="parameter"><code>max_threads</code></em> is -1, no limit is imposed on the number
- of unused threads.
- </p>
- <p>The default value is 2.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.385.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>max_threads</p></td>
- <td class="parameter_description">
- <p>maximal number of unused threads</p>
- <p>Passed as <code class="code">max-threads</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.386"></a><h3>thread-pool-stop-unused-threads</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (thread-pool-stop-unused-threads))
- </pre></div>
- <p>Stops all currently unused threads. This does not change the
- maximal number of unused threads. This function can be used to
- regularly stop all unused threads e.g. from <code class="function">g_timeout_add()</code>.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.387"></a><h3>thread-self</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (thread-self))
- </pre></div>
- <p>This function returns the <span class="type">GThread</span> corresponding to the
- current thread. Note that this function does not increase
- the reference count of the returned struct.
- </p>
- <p>This function will return a <span class="type">GThread</span> even for threads that
- were not created by GLib (i.e. those created by other threading
- APIs). This may be useful for thread identification purposes
- (i.e. comparisons) but you must not use GLib functions (such
- as <code class="function">g_thread_join()</code>) on these threads.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.388"></a><h3>thread-yield</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (thread-yield))
- </pre></div>
- <p>Causes the calling thread to voluntarily relinquish the CPU, so
- that other threads can run.
- </p>
- <p>This function is often used as a method to make busy wait less evil.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.389"></a><h3>timeout-add</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (timeout-add priority interval function data notify))
- </pre></div>
- <p>Sets a function to be called at regular intervals, with the default
- priority, <span class="type">G_PRIORITY_DEFAULT</span>. The function is called repeatedly
- until it returns <code class="constant">FALSE</code>, at which point the timeout is automatically
- destroyed and the function will not be called again. The first call
- to the function will be at the end of the first <em class="parameter"><code>interval</code></em>.
- </p>
- <p>Note that timeout functions may be delayed, due to the processing of other
- event sources. Thus they should not be relied on for precise timing.
- After each call to the timeout function, the time of the next
- timeout is recalculated based on the current time and the given interval
- (it does not try to 'catch up' time lost in delays).
- </p>
- <p>See [memory management of sources][mainloop-memory-management] for details
- on how to handle the return value and memory management of <em class="parameter"><code>data</code></em>.
- </p>
- <p>If you want to have a timer in the "seconds" range and do not care
- about the exact time of the first call of the timer, use the
- <code class="function">g_timeout_add_seconds()</code> function; this function allows for more
- optimizations and more efficient system power usage.
- </p>
- <p>This internally creates a main loop source using <code class="function">g_timeout_source_new()</code>
- and attaches it to the global <span class="type">GMainContext</span> using <code class="function">g_source_attach()</code>, so
- the callback will be invoked in whichever thread is running that main
- context. You can do these steps manually if you need greater control or to
- use a custom main context.
- </p>
- <p>It is safe to call this function from any thread.
- </p>
- <p>The interval given is in terms of monotonic time, not wall clock
- time. See <code class="function">g_get_monotonic_time()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.389.10"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>notify</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">notify</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>priority</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">priority</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>interval</p></td>
- <td class="parameter_description">
- <p>the time between calls to the function, in milliseconds
- (1/1000ths of a second)</p>
- <p>Passed as <code class="code">interval</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>function</p></td>
- <td class="parameter_description">
- <p>function to call</p>
- <p>Passed as <code class="code">function</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>data</p></td>
- <td class="parameter_description">
- <p>data to pass to <em class="parameter"><code>function</code></em></p>
- <p>Passed as <code class="code">data</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.390"></a><h3>timeout-add-seconds</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (timeout-add-seconds priority interval function data notify))
- </pre></div>
- <p>Sets a function to be called at regular intervals with the default
- priority, <span class="type">G_PRIORITY_DEFAULT</span>. The function is called repeatedly until
- it returns <code class="constant">FALSE</code>, at which point the timeout is automatically destroyed
- and the function will not be called again.
- </p>
- <p>This internally creates a main loop source using
- <code class="function">g_timeout_source_new_seconds()</code> and attaches it to the main loop context
- using <code class="function">g_source_attach()</code>. You can do these steps manually if you need
- greater control. Also see <code class="function">g_timeout_add_seconds_full()</code>.
- </p>
- <p>It is safe to call this function from any thread.
- </p>
- <p>Note that the first call of the timer may not be precise for timeouts
- of one second. If you need finer precision and have such a timeout,
- you may want to use <code class="function">g_timeout_add()</code> instead.
- </p>
- <p>See [memory management of sources][mainloop-memory-management] for details
- on how to handle the return value and memory management of <em class="parameter"><code>data</code></em>.
- </p>
- <p>The interval given is in terms of monotonic time, not wall clock
- time. See <code class="function">g_get_monotonic_time()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.390.9"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>notify</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">notify</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>priority</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">priority</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>interval</p></td>
- <td class="parameter_description">
- <p>the time between calls to the function, in seconds</p>
- <p>Passed as <code class="code">interval</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>function</p></td>
- <td class="parameter_description">
- <p>function to call</p>
- <p>Passed as <code class="code">function</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>data</p></td>
- <td class="parameter_description">
- <p>data to pass to <em class="parameter"><code>function</code></em></p>
- <p>Passed as <code class="code">data</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.391"></a><h3>timeout-source-new</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (timeout-source-new interval))
- </pre></div>
- <p>Creates a new timeout source.
- </p>
- <p>The source will not initially be associated with any <span class="type">GMainContext</span>
- and must be added to one with <code class="function">g_source_attach()</code> before it will be
- executed.
- </p>
- <p>The interval given is in terms of monotonic time, not wall clock
- time. See <code class="function">g_get_monotonic_time()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.391.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>interval</p></td>
- <td class="parameter_description">
- <p>the timeout interval in milliseconds.</p>
- <p>Passed as <code class="code">interval</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.392"></a><h3>timeout-source-new-seconds</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (timeout-source-new-seconds interval))
- </pre></div>
- <p>Creates a new timeout source.
- </p>
- <p>The source will not initially be associated with any <span class="type">GMainContext</span>
- and must be added to one with <code class="function">g_source_attach()</code> before it will be
- executed.
- </p>
- <p>The scheduling granularity/accuracy of this timeout source will be
- in seconds.
- </p>
- <p>The interval given is in terms of monotonic time, not wall clock time.
- See <code class="function">g_get_monotonic_time()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.392.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>interval</p></td>
- <td class="parameter_description">
- <p>the timeout interval in seconds</p>
- <p>Passed as <code class="code">interval</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.393"></a><h3>try-malloc</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (try-malloc n-bytes))
- </pre></div>
- <p>Attempts to allocate <em class="parameter"><code>n_bytes</code></em>, and returns <code class="constant">NULL</code> on failure.
- Contrast with <code class="function">g_malloc()</code>, which aborts the program on failure.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.393.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>n_bytes</p></td>
- <td class="parameter_description">
- <p>number of bytes to allocate.</p>
- <p>Passed as <code class="code">n-bytes</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.394"></a><h3>try-malloc0</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (try-malloc0 n-bytes))
- </pre></div>
- <p>Attempts to allocate <em class="parameter"><code>n_bytes</code></em>, initialized to 0's, and returns <code class="constant">NULL</code> on
- failure. Contrast with <code class="function">g_malloc0()</code>, which aborts the program on failure.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.394.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>n_bytes</p></td>
- <td class="parameter_description">
- <p>number of bytes to allocate</p>
- <p>Passed as <code class="code">n-bytes</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.395"></a><h3>try-malloc0-n</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (try-malloc0-n n-blocks n-block-bytes))
- </pre></div>
- <p>This function is similar to <code class="function">g_try_malloc0()</code>, allocating (<em class="parameter"><code>n_blocks</code></em> * <em class="parameter"><code>n_block_bytes</code></em>) bytes,
- but care is taken to detect possible overflow during multiplication.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.395.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>n_blocks</p></td>
- <td class="parameter_description">
- <p>the number of blocks to allocate</p>
- <p>Passed as <code class="code">n-blocks</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>n_block_bytes</p></td>
- <td class="parameter_description">
- <p>the size of each block in bytes</p>
- <p>Passed as <code class="code">n-block-bytes</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.396"></a><h3>try-malloc-n</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (try-malloc-n n-blocks n-block-bytes))
- </pre></div>
- <p>This function is similar to <code class="function">g_try_malloc()</code>, allocating (<em class="parameter"><code>n_blocks</code></em> * <em class="parameter"><code>n_block_bytes</code></em>) bytes,
- but care is taken to detect possible overflow during multiplication.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.396.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>n_blocks</p></td>
- <td class="parameter_description">
- <p>the number of blocks to allocate</p>
- <p>Passed as <code class="code">n-blocks</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>n_block_bytes</p></td>
- <td class="parameter_description">
- <p>the size of each block in bytes</p>
- <p>Passed as <code class="code">n-block-bytes</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.397"></a><h3>try-realloc</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (try-realloc mem n-bytes))
- </pre></div>
- <p>Attempts to realloc <em class="parameter"><code>mem</code></em> to a new size, <em class="parameter"><code>n_bytes</code></em>, and returns <code class="constant">NULL</code>
- on failure. Contrast with <code class="function">g_realloc()</code>, which aborts the program
- on failure.
- </p>
- <p>If <em class="parameter"><code>mem</code></em> is <code class="constant">NULL</code>, behaves the same as <code class="function">g_try_malloc()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.397.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>mem</p></td>
- <td class="parameter_description">
- <p>previously-allocated memory, or <code class="constant">NULL</code>.</p>
- <p>Passed as <code class="code">mem</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>n_bytes</p></td>
- <td class="parameter_description">
- <p>number of bytes to allocate.</p>
- <p>Passed as <code class="code">n-bytes</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.398"></a><h3>try-realloc-n</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (try-realloc-n mem n-blocks n-block-bytes))
- </pre></div>
- <p>This function is similar to <code class="function">g_try_realloc()</code>, allocating (<em class="parameter"><code>n_blocks</code></em> * <em class="parameter"><code>n_block_bytes</code></em>) bytes,
- but care is taken to detect possible overflow during multiplication.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.398.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>mem</p></td>
- <td class="parameter_description">
- <p>previously-allocated memory, or <code class="constant">NULL</code>.</p>
- <p>Passed as <code class="code">mem</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>n_blocks</p></td>
- <td class="parameter_description">
- <p>the number of blocks to allocate</p>
- <p>Passed as <code class="code">n-blocks</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>n_block_bytes</p></td>
- <td class="parameter_description">
- <p>the size of each block in bytes</p>
- <p>Passed as <code class="code">n-block-bytes</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.399"></a><h3>ucs4-to-utf16</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return items-read items-written)
- (ucs4-to-utf16 str len items-read items-written))
- </pre></div>
- <p>Convert a string from UCS-4 to UTF-16. A 0 character will be
- added to the result after the converted text.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.399.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a UCS-4 encoded string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>the maximum length (number of characters) of <em class="parameter"><code>str</code></em> to use.
- If <em class="parameter"><code>len</code></em> < 0, then the string is nul-terminated.</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>items_read</p></td>
- <td class="parameter_description">
- <p>location to store number of
- bytes read, or <code class="constant">NULL</code>. If an error occurs then the index of the invalid
- input is stored here.</p>
- <p>Passed as <code class="code">items-read</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>items_written</p></td>
- <td class="parameter_description">
- <p>location to store number
- of <span class="type">gunichar2</span> written, or <code class="constant">NULL</code>. The value stored here does not include
- the trailing 0.</p>
- <p>Passed as <code class="code">items-written</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.400"></a><h3>ucs4-to-utf8</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return items-read items-written)
- (ucs4-to-utf8 str len items-read items-written))
- </pre></div>
- <p>Convert a string from a 32-bit fixed width representation as UCS-4.
- to UTF-8. The result will be terminated with a 0 byte.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.400.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a UCS-4 encoded string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>the maximum length (number of characters) of <em class="parameter"><code>str</code></em> to use.
- If <em class="parameter"><code>len</code></em> < 0, then the string is nul-terminated.</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>items_read</p></td>
- <td class="parameter_description">
- <p>location to store number of
- characters read, or <code class="constant">NULL</code>.</p>
- <p>Passed as <code class="code">items-read</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>items_written</p></td>
- <td class="parameter_description">
- <p>location to store number
- of bytes written or <code class="constant">NULL</code>. The value here stored does not include the
- trailing 0 byte.</p>
- <p>Passed as <code class="code">items-written</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.401"></a><h3>unichar-break-type</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-break-type c))
- </pre></div>
- <p>Determines the break type of <em class="parameter"><code>c</code></em>. <em class="parameter"><code>c</code></em> should be a Unicode character
- (to derive a character from UTF-8 encoded text, use
- <code class="function">g_utf8_get_char()</code>). The break type is used to find word and line
- breaks ("text boundaries"), Pango implements the Unicode boundary
- resolution algorithms and normally you would use a function such
- as <code class="function">pango_break()</code> instead of caring about break types yourself.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.401.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.402"></a><h3>unichar-combining-class</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-combining-class uc))
- </pre></div>
- <p>Determines the canonical combining class of a Unicode character.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.402.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>uc</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">uc</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.403"></a><h3>unichar-compose</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return ch) (unichar-compose a b))
- </pre></div>
- <p>Performs a single composition step of the
- Unicode canonical composition algorithm.
- </p>
- <p>This function includes algorithmic Hangul Jamo composition,
- but it is not exactly the inverse of <code class="function">g_unichar_decompose()</code>.
- No composition can have either of <em class="parameter"><code>a</code></em> or <em class="parameter"><code>b</code></em> equal to zero.
- To be precise, this function composes if and only if
- there exists a Primary Composite P which is canonically
- equivalent to the sequence <<em class="parameter"><code>a</code></em>,<em class="parameter"><code>b</code></em>>. See the Unicode
- Standard for the definition of Primary Composite.
- </p>
- <p>If <em class="parameter"><code>a</code></em> and <em class="parameter"><code>b</code></em> do not compose a new character, <em class="parameter"><code>ch</code></em> is set to zero.
- </p>
- <p>See
- [UAX#15](http://unicode.org/reports/tr15/)
- for details.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.403.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>a</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">a</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>b</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">b</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>ch</p></td>
- <td class="parameter_description">
- <p>return location for the composed character</p>
- <p>Passed as <code class="code">ch</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.404"></a><h3>unichar-decompose</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return a b) (unichar-decompose ch))
- </pre></div>
- <p>Performs a single decomposition step of the
- Unicode canonical decomposition algorithm.
- </p>
- <p>This function does not include compatibility
- decompositions. It does, however, include algorithmic
- Hangul Jamo decomposition, as well as 'singleton'
- decompositions which replace a character by a single
- other character. In the case of singletons *<em class="parameter"><code>b</code></em> will
- be set to zero.
- </p>
- <p>If <em class="parameter"><code>ch</code></em> is not decomposable, *<em class="parameter"><code>a</code></em> is set to <em class="parameter"><code>ch</code></em> and *<em class="parameter"><code>b</code></em>
- is set to zero.
- </p>
- <p>Note that the way Unicode decomposition pairs are
- defined, it is guaranteed that <em class="parameter"><code>b</code></em> would not decompose
- further, but <em class="parameter"><code>a</code></em> may itself decompose. To get the full
- canonical decomposition for <em class="parameter"><code>ch</code></em>, one would need to
- recursively call this function on <em class="parameter"><code>a</code></em>. Or use
- <code class="function">g_unichar_fully_decompose()</code>.
- </p>
- <p>See
- [UAX#15](http://unicode.org/reports/tr15/)
- for details.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.404.8"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>ch</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">ch</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>a</p></td>
- <td class="parameter_description">
- <p>return location for the first component of <em class="parameter"><code>ch</code></em></p>
- <p>Passed as <code class="code">a</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>b</p></td>
- <td class="parameter_description">
- <p>return location for the second component of <em class="parameter"><code>ch</code></em></p>
- <p>Passed as <code class="code">b</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.405"></a><h3>unichar-digit-value</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-digit-value c))
- </pre></div>
- <p>Determines the numeric value of a character as a decimal
- digit.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.405.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.406"></a><h3>unichar-fully-decompose</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return result)
- (unichar-fully-decompose ch compat result result-len))
- </pre></div>
- <p>Computes the canonical or compatibility decomposition of a
- Unicode character. For compatibility decomposition,
- pass <code class="constant">TRUE</code> for <em class="parameter"><code>compat</code></em>; for canonical decomposition
- pass <code class="constant">FALSE</code> for <em class="parameter"><code>compat</code></em>.
- </p>
- <p>The decomposed sequence is placed in <em class="parameter"><code>result</code></em>. Only up to
- <em class="parameter"><code>result_len</code></em> characters are written into <em class="parameter"><code>result</code></em>. The length
- of the full decomposition (irrespective of <em class="parameter"><code>result_len</code></em>) is
- returned by the function. For canonical decomposition,
- currently all decompositions are of length at most 4, but
- this may change in the future (very unlikely though).
- At any rate, Unicode does guarantee that a buffer of length
- 18 is always enough for both compatibility and canonical
- decompositions, so that is the size recommended. This is provided
- as <code class="constant">G_UNICHAR_MAX_DECOMPOSITION_LENGTH</code>.
- </p>
- <p>See
- [UAX#15](http://unicode.org/reports/tr15/)
- for details.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.406.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>ch</p></td>
- <td class="parameter_description">
- <p>a Unicode character.</p>
- <p>Passed as <code class="code">ch</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>compat</p></td>
- <td class="parameter_description">
- <p>whether perform canonical or compatibility decomposition</p>
- <p>Passed as <code class="code">compat</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>result</p></td>
- <td class="parameter_description">
- <p>location to store decomposed result, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">result</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>result_len</p></td>
- <td class="parameter_description">
- <p>length of <em class="parameter"><code>result</code></em></p>
- <p>Passed as <code class="code">result-len</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.407"></a><h3>unichar-get-mirror-char?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-get-mirror-char? ch mirrored-ch))
- </pre></div>
- <p>In Unicode, some characters are "mirrored". This means that their
- images are mirrored horizontally in text that is laid out from right
- to left. For instance, "(" would become its mirror image, ")", in
- right-to-left text.
- </p>
- <p>If <em class="parameter"><code>ch</code></em> has the Unicode mirrored property and there is another unicode
- character that typically has a glyph that is the mirror image of <em class="parameter"><code>ch</code></em>'s
- glyph and <em class="parameter"><code>mirrored_ch</code></em> is set, it puts that character in the address
- pointed to by <em class="parameter"><code>mirrored_ch</code></em>. Otherwise the original character is put.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.407.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>ch</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">ch</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>mirrored_ch</p></td>
- <td class="parameter_description">
- <p>location to store the mirrored character</p>
- <p>Passed as <code class="code">mirrored-ch</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.408"></a><h3>unichar-get-script</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-get-script ch))
- </pre></div>
- <p>Looks up the <span class="type">GUnicodeScript</span> for a particular character (as defined
- by Unicode Standard Annex \#24). No check is made for <em class="parameter"><code>ch</code></em> being a
- valid Unicode character; if you pass in invalid character, the
- result is undefined.
- </p>
- <p>This function is equivalent to <code class="function">pango_script_for_unichar()</code> and the
- two are interchangeable.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.408.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>ch</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">ch</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.409"></a><h3>unichar-isalnum?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-isalnum? c))
- </pre></div>
- <p>Determines whether a character is alphanumeric.
- Given some UTF-8 text, obtain a character value
- with <code class="function">g_utf8_get_char()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.409.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.410"></a><h3>unichar-isalpha?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-isalpha? c))
- </pre></div>
- <p>Determines whether a character is alphabetic (i.e. a letter).
- Given some UTF-8 text, obtain a character value with
- <code class="function">g_utf8_get_char()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.410.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.411"></a><h3>unichar-iscntrl?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-iscntrl? c))
- </pre></div>
- <p>Determines whether a character is a control character.
- Given some UTF-8 text, obtain a character value with
- <code class="function">g_utf8_get_char()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.411.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.412"></a><h3>unichar-isdefined?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-isdefined? c))
- </pre></div>
- <p>Determines if a given character is assigned in the Unicode
- standard.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.412.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.413"></a><h3>unichar-isdigit?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-isdigit? c))
- </pre></div>
- <p>Determines whether a character is numeric (i.e. a digit). This
- covers ASCII 0-9 and also digits in other languages/scripts. Given
- some UTF-8 text, obtain a character value with <code class="function">g_utf8_get_char()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.413.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.414"></a><h3>unichar-isgraph?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-isgraph? c))
- </pre></div>
- <p>Determines whether a character is printable and not a space
- (returns <code class="constant">FALSE</code> for control characters, format characters, and
- spaces). <code class="function">g_unichar_isprint()</code> is similar, but returns <code class="constant">TRUE</code> for
- spaces. Given some UTF-8 text, obtain a character value with
- <code class="function">g_utf8_get_char()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.414.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.415"></a><h3>unichar-islower?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-islower? c))
- </pre></div>
- <p>Determines whether a character is a lowercase letter.
- Given some UTF-8 text, obtain a character value with
- <code class="function">g_utf8_get_char()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.415.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.416"></a><h3>unichar-ismark?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-ismark? c))
- </pre></div>
- <p>Determines whether a character is a mark (non-spacing mark,
- combining mark, or enclosing mark in Unicode speak).
- Given some UTF-8 text, obtain a character value
- with <code class="function">g_utf8_get_char()</code>.
- </p>
- <p>Note: in most cases where isalpha characters are allowed,
- ismark characters should be allowed to as they are essential
- for writing most European languages as well as many non-Latin
- scripts.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.416.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.417"></a><h3>unichar-isprint?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-isprint? c))
- </pre></div>
- <p>Determines whether a character is printable.
- Unlike <code class="function">g_unichar_isgraph()</code>, returns <code class="constant">TRUE</code> for spaces.
- Given some UTF-8 text, obtain a character value with
- <code class="function">g_utf8_get_char()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.417.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.418"></a><h3>unichar-ispunct?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-ispunct? c))
- </pre></div>
- <p>Determines whether a character is punctuation or a symbol.
- Given some UTF-8 text, obtain a character value with
- <code class="function">g_utf8_get_char()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.418.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.419"></a><h3>unichar-isspace?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-isspace? c))
- </pre></div>
- <p>Determines whether a character is a space, tab, or line separator
- (newline, carriage return, etc.). Given some UTF-8 text, obtain a
- character value with <code class="function">g_utf8_get_char()</code>.
- </p>
- <p>(Note: don't use this to do word breaking; you have to use
- Pango or equivalent to get word breaking right, the algorithm
- is fairly complex.)</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.419.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.420"></a><h3>unichar-istitle?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-istitle? c))
- </pre></div>
- <p>Determines if a character is titlecase. Some characters in
- Unicode which are composites, such as the DZ digraph
- have three case variants instead of just two. The titlecase
- form is used at the beginning of a word where only the
- first letter is capitalized. The titlecase form of the DZ
- digraph is U+01F2 LATIN CAPITAL LETTTER D WITH SMALL LETTER Z.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.420.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.421"></a><h3>unichar-isupper?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-isupper? c))
- </pre></div>
- <p>Determines if a character is uppercase.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.421.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.422"></a><h3>unichar-iswide?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-iswide? c))
- </pre></div>
- <p>Determines if a character is typically rendered in a double-width
- cell.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.422.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.423"></a><h3>unichar-iswide-cjk?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-iswide-cjk? c))
- </pre></div>
- <p>Determines if a character is typically rendered in a double-width
- cell under legacy East Asian locales. If a character is wide according to
- <code class="function">g_unichar_iswide()</code>, then it is also reported wide with this function, but
- the converse is not necessarily true. See the
- [Unicode Standard Annex <span class="type">11</span>](http://www.unicode.org/reports/tr11/)
- for details.
- </p>
- <p>If a character passes the <code class="function">g_unichar_iswide()</code> test then it will also pass
- this test, but not the other way around. Note that some characters may
- pass both this test and <code class="function">g_unichar_iszerowidth()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.423.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.424"></a><h3>unichar-isxdigit?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-isxdigit? c))
- </pre></div>
- <p>Determines if a character is a hexadecimal digit.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.424.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character.</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.425"></a><h3>unichar-iszerowidth?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-iszerowidth? c))
- </pre></div>
- <p>Determines if a given character typically takes zero width when rendered.
- The return value is <code class="constant">TRUE</code> for all non-spacing and enclosing marks
- (e.g., combining accents), format characters, zero-width
- space, but not U+00AD SOFT HYPHEN.
- </p>
- <p>A typical use of this function is with one of <code class="function">g_unichar_iswide()</code> or
- <code class="function">g_unichar_iswide_cjk()</code> to determine the number of cells a string occupies
- when displayed on a grid display (terminals). However, note that not all
- terminals support zero-width rendering of zero-width marks.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.425.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.426"></a><h3>unichar-to-utf8!</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return outbuf) (unichar-to-utf8! c outbuf))
- </pre></div>
- <p>Converts a single character to UTF-8.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.426.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character code</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>outbuf</p></td>
- <td class="parameter_description">
- <p>output buffer, must have at
- least 6 bytes of space. If <code class="constant">NULL</code>, the length will be computed and
- returned and nothing will be written to <em class="parameter"><code>outbuf</code></em>.</p>
- <p>Passed as <code class="code">outbuf</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.427"></a><h3>unichar-tolower</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-tolower c))
- </pre></div>
- <p>Converts a character to lower case.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.427.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character.</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.428"></a><h3>unichar-totitle</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-totitle c))
- </pre></div>
- <p>Converts a character to the titlecase.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.428.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.429"></a><h3>unichar-toupper</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-toupper c))
- </pre></div>
- <p>Converts a character to uppercase.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.429.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.430"></a><h3>unichar-type</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-type c))
- </pre></div>
- <p>Classifies a Unicode character by type.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.430.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.431"></a><h3>unichar-validate?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-validate? ch))
- </pre></div>
- <p>Checks whether <em class="parameter"><code>ch</code></em> is a valid Unicode character. Some possible
- integer values of <em class="parameter"><code>ch</code></em> will not be valid. 0 is considered a valid
- character, though it's normally a string terminator.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.431.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>ch</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">ch</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.432"></a><h3>unichar-xdigit-value</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unichar-xdigit-value c))
- </pre></div>
- <p>Determines the numeric value of a character as a hexadecimal
- digit.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.432.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.433"></a><h3>unicode-canonical-ordering</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (unicode-canonical-ordering string len))
- </pre></div>
- <p>Computes the canonical ordering of a string in-place.
- This rearranges decomposed characters in the string
- according to their combining classes. See the Unicode
- manual for more information.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.433.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>a UCS-4 encoded string.</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>the maximum length of <em class="parameter"><code>string</code></em> to use.</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.434"></a><h3>unicode-script-from-iso15924</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unicode-script-from-iso15924 iso15924))
- </pre></div>
- <p>Looks up the Unicode script for <em class="parameter"><code>iso15924</code></em>. ISO 15924 assigns four-letter
- codes to scripts. For example, the code for Arabic is 'Arab'.
- This function accepts four letter codes encoded as a <em class="parameter"><code>guint32</code></em> in a
- big-endian fashion. That is, the code expected for Arabic is
- 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc).
- </p>
- <p>See
- [Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html)
- for details.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.434.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>iso15924</p></td>
- <td class="parameter_description">
- <p>a Unicode script</p>
- <p>Passed as <code class="code">iso15924</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.435"></a><h3>unicode-script-to-iso15924</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unicode-script-to-iso15924 script))
- </pre></div>
- <p>Looks up the ISO 15924 code for <em class="parameter"><code>script</code></em>. ISO 15924 assigns four-letter
- codes to scripts. For example, the code for Arabic is 'Arab'. The
- four letter codes are encoded as a <em class="parameter"><code>guint32</code></em> by this function in a
- big-endian fashion. That is, the code returned for Arabic is
- 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc).
- </p>
- <p>See
- [Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html)
- for details.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.435.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>script</p></td>
- <td class="parameter_description">
- <p>a Unicode script</p>
- <p>Passed as <code class="code">script</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.436"></a><h3>unix-error-quark</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unix-error-quark))
- </pre></div>
- <p>Undocumented</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.437"></a><h3>unix-fd-add-full</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (unix-fd-add-full priority fd condition function user-data notify))
- </pre></div>
- <p>Sets a function to be called when the IO condition, as specified by
- <em class="parameter"><code>condition</code></em> becomes true for <em class="parameter"><code>fd</code></em>.
- </p>
- <p>This is the same as <code class="function">g_unix_fd_add()</code>, except that it allows you to
- specify a non-default priority and a provide a <span class="type">GDestroyNotify</span> for
- <em class="parameter"><code>user_data</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.437.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>priority</p></td>
- <td class="parameter_description">
- <p>the priority of the source</p>
- <p>Passed as <code class="code">priority</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>fd</p></td>
- <td class="parameter_description">
- <p>a file descriptor</p>
- <p>Passed as <code class="code">fd</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>condition</p></td>
- <td class="parameter_description">
- <p>IO conditions to watch for on <em class="parameter"><code>fd</code></em></p>
- <p>Passed as <code class="code">condition</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>function</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GUnixFDSourceFunc</span></p>
- <p>Passed as <code class="code">function</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>user_data</p></td>
- <td class="parameter_description">
- <p>data to pass to <em class="parameter"><code>function</code></em></p>
- <p>Passed as <code class="code">user-data</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>notify</p></td>
- <td class="parameter_description">
- <p>function to call when the idle is removed, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">notify</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.438"></a><h3>unix-fd-source-new</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unix-fd-source-new fd condition))
- </pre></div>
- <p>Creates a <span class="type">GSource</span> to watch for a particular IO condition on a file
- descriptor.
- </p>
- <p>The source will never close the fd -- you must do it yourself.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.438.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>fd</p></td>
- <td class="parameter_description">
- <p>a file descriptor</p>
- <p>Passed as <code class="code">fd</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>condition</p></td>
- <td class="parameter_description">
- <p>IO conditions to watch for on <em class="parameter"><code>fd</code></em></p>
- <p>Passed as <code class="code">condition</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.439"></a><h3>unix-get-passwd-entry</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unix-get-passwd-entry user-name))
- </pre></div>
- <p>Get the <code class="code">passwd</code> file entry for the given <em class="parameter"><code>user_name</code></em> using <code class="code">getpwnam_r()</code>.
- This can fail if the given <em class="parameter"><code>user_name</code></em> doesn’t exist.
- </p>
- <p>The returned <code class="code">struct passwd</code> has been allocated using <code class="function">g_malloc()</code> and should
- be freed using <code class="function">g_free()</code>. The strings referenced by the returned struct are
- included in the same allocation, so are valid until the <code class="code">struct passwd</code> is
- freed.
- </p>
- <p>This function is safe to call from multiple threads concurrently.
- </p>
- <p>You will need to include <code class="code">pwd.h</code> to get the definition of <code class="code">struct passwd</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.439.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>user_name</p></td>
- <td class="parameter_description">
- <p>the username to get the passwd file entry for</p>
- <p>Passed as <code class="code">user-name</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.440"></a><h3>unix-open-pipe?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unix-open-pipe? fds flags))
- </pre></div>
- <p>Similar to the UNIX <code class="function">pipe()</code> call, but on modern systems like Linux
- uses the <code class="function">pipe2()</code> system call, which atomically creates a pipe with
- the configured flags. The only supported flag currently is
- <code class="constant">FD_CLOEXEC</code>. If for example you want to configure <code class="constant">O_NONBLOCK</code>, that
- must still be done separately with <code class="function">fcntl()</code>.
- </p>
- <p>This function does not take <code class="constant">O_CLOEXEC</code>, it takes <code class="constant">FD_CLOEXEC</code> as if
- for <code class="function">fcntl()</code>; these are different on Linux/glibc.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.440.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>fds</p></td>
- <td class="parameter_description">
- <p>Array of two integers</p>
- <p>Passed as <code class="code">fds</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>flags</p></td>
- <td class="parameter_description">
- <p>Bitfield of file descriptor flags, as for <code class="function">fcntl()</code></p>
- <p>Passed as <code class="code">flags</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.441"></a><h3>unix-set-fd-nonblocking?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unix-set-fd-nonblocking? fd nonblock))
- </pre></div>
- <p>Control the non-blocking state of the given file descriptor,
- according to <em class="parameter"><code>nonblock</code></em>. On most systems this uses <code class="constant">O_NONBLOCK</code>, but
- on some older ones may use <code class="constant">O_NDELAY</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.441.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>fd</p></td>
- <td class="parameter_description">
- <p>A file descriptor</p>
- <p>Passed as <code class="code">fd</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>nonblock</p></td>
- <td class="parameter_description">
- <p>If <code class="constant">TRUE</code>, set the descriptor to be non-blocking</p>
- <p>Passed as <code class="code">nonblock</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.442"></a><h3>unix-signal-add</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (unix-signal-add priority signum handler user-data notify))
- </pre></div>
- <p>A convenience function for <code class="function">g_unix_signal_source_new()</code>, which
- attaches to the default <span class="type">GMainContext</span>. You can remove the watch
- using <code class="function">g_source_remove()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.442.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>notify</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">notify</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>priority</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">priority</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>signum</p></td>
- <td class="parameter_description">
- <p>Signal number</p>
- <p>Passed as <code class="code">signum</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>handler</p></td>
- <td class="parameter_description">
- <p>Callback</p>
- <p>Passed as <code class="code">handler</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>user_data</p></td>
- <td class="parameter_description">
- <p>Data for <em class="parameter"><code>handler</code></em></p>
- <p>Passed as <code class="code">user-data</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.443"></a><h3>unix-signal-source-new</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unix-signal-source-new signum))
- </pre></div>
- <p>Create a <span class="type">GSource</span> that will be dispatched upon delivery of the UNIX
- signal <em class="parameter"><code>signum</code></em>. In GLib versions before 2.36, only <code class="code">SIGHUP</code>, <code class="code">SIGINT</code>,
- <code class="code">SIGTERM</code> can be monitored. In GLib 2.36, <code class="code">SIGUSR1</code> and <code class="code">SIGUSR2</code>
- were added. In GLib 2.54, <code class="code">SIGWINCH</code> was added.
- </p>
- <p>Note that unlike the UNIX default, all sources which have created a
- watch will be dispatched, regardless of which underlying thread
- invoked <code class="function">g_unix_signal_source_new()</code>.
- </p>
- <p>For example, an effective use of this function is to handle <code class="code">SIGTERM</code>
- cleanly; flushing any outstanding files, and then calling
- g_main_loop_quit (). It is not safe to do any of this a regular
- UNIX signal handler; your handler may be invoked while <code class="function">malloc()</code> or
- another library function is running, causing reentrancy if you
- attempt to use it from the handler. None of the GLib/GObject API
- is safe against this kind of reentrancy.
- </p>
- <p>The interaction of this source when combined with native UNIX
- functions like <code class="function">sigprocmask()</code> is not defined.
- </p>
- <p>The source will not initially be associated with any <span class="type">GMainContext</span>
- and must be added to one with <code class="function">g_source_attach()</code> before it will be
- executed.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.443.8"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>signum</p></td>
- <td class="parameter_description">
- <p>A signal number</p>
- <p>Passed as <code class="code">signum</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.444"></a><h3>unlink</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (unlink filename))
- </pre></div>
- <p>A wrapper for the POSIX <code class="function">unlink()</code> function. The <code class="function">unlink()</code> function
- deletes a name from the filesystem. If this was the last link to the
- file and no processes have it opened, the diskspace occupied by the
- file is freed.
- </p>
- <p>See your C library manual for more details about <code class="function">unlink()</code>. Note
- that on Windows, it is in general not possible to delete files that
- are open to some process, or mapped into memory.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.444.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>filename</p></td>
- <td class="parameter_description">
- <p>a pathname in the GLib file name encoding
- (UTF-8 on Windows)</p>
- <p>Passed as <code class="code">filename</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.445"></a><h3>unsetenv</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (unsetenv variable))
- </pre></div>
- <p>Removes an environment variable from the environment.
- </p>
- <p>Note that on some systems, when variables are overwritten, the
- memory used for the previous variables and its value isn't reclaimed.
- </p>
- <p>You should be mindful of the fact that environment variable handling
- in UNIX is not thread-safe, and your program may crash if one thread
- calls <code class="function">g_unsetenv()</code> while another thread is calling <code class="function">getenv()</code>. (And note
- that many functions, such as <code class="function">gettext()</code>, call <code class="function">getenv()</code> internally.) This
- function is only safe to use at the very start of your program, before
- creating any other threads (or creating objects that create worker
- threads of their own).
- </p>
- <p>If you need to set up the environment for a child process, you can
- use <code class="function">g_get_environ()</code> to get an environment array, modify that with
- <code class="function">g_environ_setenv()</code> and <code class="function">g_environ_unsetenv()</code>, and then pass that
- array directly to <code class="function">execvpe()</code>, <code class="function">g_spawn_async()</code>, or the like.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.445.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>variable</p></td>
- <td class="parameter_description">
- <p>the environment variable to remove, must
- not contain '='</p>
- <p>Passed as <code class="code">variable</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.446"></a><h3>uri-build</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (uri-build flags scheme userinfo host port path query fragment))
- </pre></div>
- <p>Creates a new <span class="type">GUri</span> from the given components according to <em class="parameter"><code>flags</code></em>.
- </p>
- <p>See also <code class="function">g_uri_build_with_user()</code>, which allows specifying the
- components of the "userinfo" separately.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.446.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>flags</p></td>
- <td class="parameter_description">
- <p>flags describing how to build the <span class="type">GUri</span></p>
- <p>Passed as <code class="code">flags</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>scheme</p></td>
- <td class="parameter_description">
- <p>the URI scheme</p>
- <p>Passed as <code class="code">scheme</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>userinfo</p></td>
- <td class="parameter_description">
- <p>the userinfo component, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">userinfo</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>host</p></td>
- <td class="parameter_description">
- <p>the host component, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">host</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>port</p></td>
- <td class="parameter_description">
- <p>the port, or <code class="code">-1</code></p>
- <p>Passed as <code class="code">port</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>path</p></td>
- <td class="parameter_description">
- <p>the path component</p>
- <p>Passed as <code class="code">path</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>query</p></td>
- <td class="parameter_description">
- <p>the query component, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">query</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>fragment</p></td>
- <td class="parameter_description">
- <p>the fragment, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">fragment</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.447"></a><h3>uri-build-with-user</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (uri-build-with-user
- flags
- scheme
- user
- password
- auth-params
- host
- port
- path
- query
- fragment))
- </pre></div>
- <p>Creates a new <span class="type">GUri</span> from the given components according to <em class="parameter"><code>flags</code></em>
- (<code class="constant">G_URI_FLAGS_HAS_PASSWORD</code> is added unconditionally). The <em class="parameter"><code>flags</code></em> must be
- coherent with the passed values, in particular use <code class="code">%</code>-encoded values with
- <code class="constant">G_URI_FLAGS_ENCODED</code>.
- </p>
- <p>In contrast to <code class="function">g_uri_build()</code>, this allows specifying the components
- of the ‘userinfo’ field separately. Note that <em class="parameter"><code>user</code></em> must be non-<code class="constant">NULL</code>
- if either <em class="parameter"><code>password</code></em> or <em class="parameter"><code>auth_params</code></em> is non-<code class="constant">NULL</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.447.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>flags</p></td>
- <td class="parameter_description">
- <p>flags describing how to build the <span class="type">GUri</span></p>
- <p>Passed as <code class="code">flags</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>scheme</p></td>
- <td class="parameter_description">
- <p>the URI scheme</p>
- <p>Passed as <code class="code">scheme</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>user</p></td>
- <td class="parameter_description">
- <p>the user component of the userinfo, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">user</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>password</p></td>
- <td class="parameter_description">
- <p>the password component of the userinfo, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">password</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>auth_params</p></td>
- <td class="parameter_description">
- <p>the auth params of the userinfo, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">auth-params</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>host</p></td>
- <td class="parameter_description">
- <p>the host component, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">host</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>port</p></td>
- <td class="parameter_description">
- <p>the port, or <code class="code">-1</code></p>
- <p>Passed as <code class="code">port</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>path</p></td>
- <td class="parameter_description">
- <p>the path component</p>
- <p>Passed as <code class="code">path</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>query</p></td>
- <td class="parameter_description">
- <p>the query component, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">query</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>fragment</p></td>
- <td class="parameter_description">
- <p>the fragment, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">fragment</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.448"></a><h3>uri-error-quark</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (uri-error-quark))
- </pre></div>
- <p>Undocumented</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.449"></a><h3>uri-escape-bytes</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (uri-escape-bytes unescaped reserved-chars-allowed))
- </pre></div>
- <p>Escapes arbitrary data for use in a URI.
- </p>
- <p>Normally all characters that are not ‘unreserved’ (i.e. ASCII
- alphanumerical characters plus dash, dot, underscore and tilde) are
- escaped. But if you specify characters in <em class="parameter"><code>reserved_chars_allowed</code></em>
- they are not escaped. This is useful for the ‘reserved’ characters
- in the URI specification, since those are allowed unescaped in some
- portions of a URI.
- </p>
- <p>Though technically incorrect, this will also allow escaping nul
- bytes as <code class="code">%</code><code class="code">00</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.449.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>unescaped</p></td>
- <td class="parameter_description">
- <p>the unescaped input data.</p>
- <p>Passed as <code class="code">unescaped</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>length</p></td>
- <td class="parameter_description">
- <p>the length of <em class="parameter"><code>unescaped</code></em></p>
- <p>Inferred from <code class="code">unescaped</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>reserved_chars_allowed</p></td>
- <td class="parameter_description">
- <p>a string of reserved
- characters that are allowed to be used, or <code class="constant">NULL</code>.</p>
- <p>Passed as <code class="code">reserved-chars-allowed</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.450"></a><h3>uri-escape-string</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (uri-escape-string unescaped reserved-chars-allowed allow-utf8))
- </pre></div>
- <p>Escapes a string for use in a URI.
- </p>
- <p>Normally all characters that are not "unreserved" (i.e. ASCII
- alphanumerical characters plus dash, dot, underscore and tilde) are
- escaped. But if you specify characters in <em class="parameter"><code>reserved_chars_allowed</code></em>
- they are not escaped. This is useful for the "reserved" characters
- in the URI specification, since those are allowed unescaped in some
- portions of a URI.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.450.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>unescaped</p></td>
- <td class="parameter_description">
- <p>the unescaped input string.</p>
- <p>Passed as <code class="code">unescaped</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>reserved_chars_allowed</p></td>
- <td class="parameter_description">
- <p>a string of reserved
- characters that are allowed to be used, or <code class="constant">NULL</code>.</p>
- <p>Passed as <code class="code">reserved-chars-allowed</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>allow_utf8</p></td>
- <td class="parameter_description">
- <p><code class="constant">TRUE</code> if the result can include UTF-8 characters.</p>
- <p>Passed as <code class="code">allow-utf8</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.451"></a><h3>uri-is-valid?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (uri-is-valid? uri-string flags))
- </pre></div>
- <p>Parses <em class="parameter"><code>uri_string</code></em> according to <em class="parameter"><code>flags</code></em>, to determine whether it is a valid
- [absolute URI][relative-absolute-uris], i.e. it does not need to be resolved
- relative to another URI using <code class="function">g_uri_parse_relative()</code>.
- </p>
- <p>If it’s not a valid URI, an error is returned explaining how it’s invalid.
- </p>
- <p>See <code class="function">g_uri_split()</code>, and the definition of <span class="type">GUriFlags</span>, for more
- information on the effect of <em class="parameter"><code>flags</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.451.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>uri_string</p></td>
- <td class="parameter_description">
- <p>a string containing an absolute URI</p>
- <p>Passed as <code class="code">uri-string</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>flags</p></td>
- <td class="parameter_description">
- <p>flags for parsing <em class="parameter"><code>uri_string</code></em></p>
- <p>Passed as <code class="code">flags</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.452"></a><h3>uri-join</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (uri-join flags scheme userinfo host port path query fragment))
- </pre></div>
- <p>Joins the given components together according to <em class="parameter"><code>flags</code></em> to create
- an absolute URI string. <em class="parameter"><code>path</code></em> may not be <code class="constant">NULL</code> (though it may be the empty
- string).
- </p>
- <p>When <em class="parameter"><code>host</code></em> is present, <em class="parameter"><code>path</code></em> must either be empty or begin with a slash (<code class="code">/</code>)
- character. When <em class="parameter"><code>host</code></em> is not present, <em class="parameter"><code>path</code></em> cannot begin with two slash
- characters (<code class="code">//</code>). See
- [RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3).
- </p>
- <p>See also <code class="function">g_uri_join_with_user()</code>, which allows specifying the
- components of the ‘userinfo’ separately.
- </p>
- <p><code class="constant">G_URI_FLAGS_HAS_PASSWORD</code> and <code class="constant">G_URI_FLAGS_HAS_AUTH_PARAMS</code> are ignored if set
- in <em class="parameter"><code>flags</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.452.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>flags</p></td>
- <td class="parameter_description">
- <p>flags describing how to build the URI string</p>
- <p>Passed as <code class="code">flags</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>scheme</p></td>
- <td class="parameter_description">
- <p>the URI scheme, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">scheme</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>userinfo</p></td>
- <td class="parameter_description">
- <p>the userinfo component, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">userinfo</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>host</p></td>
- <td class="parameter_description">
- <p>the host component, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">host</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>port</p></td>
- <td class="parameter_description">
- <p>the port, or <code class="code">-1</code></p>
- <p>Passed as <code class="code">port</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>path</p></td>
- <td class="parameter_description">
- <p>the path component</p>
- <p>Passed as <code class="code">path</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>query</p></td>
- <td class="parameter_description">
- <p>the query component, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">query</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>fragment</p></td>
- <td class="parameter_description">
- <p>the fragment, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">fragment</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.453"></a><h3>uri-join-with-user</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (uri-join-with-user
- flags
- scheme
- user
- password
- auth-params
- host
- port
- path
- query
- fragment))
- </pre></div>
- <p>Joins the given components together according to <em class="parameter"><code>flags</code></em> to create
- an absolute URI string. <em class="parameter"><code>path</code></em> may not be <code class="constant">NULL</code> (though it may be the empty
- string).
- </p>
- <p>In contrast to <code class="function">g_uri_join()</code>, this allows specifying the components
- of the ‘userinfo’ separately. It otherwise behaves the same.
- </p>
- <p><code class="constant">G_URI_FLAGS_HAS_PASSWORD</code> and <code class="constant">G_URI_FLAGS_HAS_AUTH_PARAMS</code> are ignored if set
- in <em class="parameter"><code>flags</code></em>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.453.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>flags</p></td>
- <td class="parameter_description">
- <p>flags describing how to build the URI string</p>
- <p>Passed as <code class="code">flags</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>scheme</p></td>
- <td class="parameter_description">
- <p>the URI scheme, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">scheme</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>user</p></td>
- <td class="parameter_description">
- <p>the user component of the userinfo, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">user</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>password</p></td>
- <td class="parameter_description">
- <p>the password component of the userinfo, or
- <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">password</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>auth_params</p></td>
- <td class="parameter_description">
- <p>the auth params of the userinfo, or
- <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">auth-params</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>host</p></td>
- <td class="parameter_description">
- <p>the host component, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">host</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>port</p></td>
- <td class="parameter_description">
- <p>the port, or <code class="code">-1</code></p>
- <p>Passed as <code class="code">port</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>path</p></td>
- <td class="parameter_description">
- <p>the path component</p>
- <p>Passed as <code class="code">path</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>query</p></td>
- <td class="parameter_description">
- <p>the query component, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">query</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>fragment</p></td>
- <td class="parameter_description">
- <p>the fragment, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">fragment</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.454"></a><h3>uri-list-extract-uris</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (uri-list-extract-uris uri-list))
- </pre></div>
- <p>Splits an URI list conforming to the text/uri-list
- mime type defined in RFC 2483 into individual URIs,
- discarding any comments. The URIs are not validated.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.454.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>uri_list</p></td>
- <td class="parameter_description">
- <p>an URI list</p>
- <p>Passed as <code class="code">uri-list</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.455"></a><h3>uri-parse</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (uri-parse uri-string flags))
- </pre></div>
- <p>Parses <em class="parameter"><code>uri_string</code></em> according to <em class="parameter"><code>flags</code></em>. If the result is not a
- valid [absolute URI][relative-absolute-uris], it will be discarded, and an
- error returned.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.455.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>uri_string</p></td>
- <td class="parameter_description">
- <p>a string representing an absolute URI</p>
- <p>Passed as <code class="code">uri-string</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>flags</p></td>
- <td class="parameter_description">
- <p>flags describing how to parse <em class="parameter"><code>uri_string</code></em></p>
- <p>Passed as <code class="code">flags</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.456"></a><h3>uri-parse-params</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (uri-parse-params params length separators flags))
- </pre></div>
- <p>Many URI schemes include one or more attribute/value pairs as part of the URI
- value. This method can be used to parse them into a hash table. When an
- attribute has multiple occurrences, the last value is the final returned
- value. If you need to handle repeated attributes differently, use
- <span class="type">GUriParamsIter</span>.
- </p>
- <p>The <em class="parameter"><code>params</code></em> string is assumed to still be <code class="code">%</code>-encoded, but the returned
- values will be fully decoded. (Thus it is possible that the returned values
- may contain <code class="code">=</code> or <em class="parameter"><code>separators</code></em>, if the value was encoded in the input.)
- Invalid <code class="code">%</code>-encoding is treated as with the <code class="constant">G_URI_FLAGS_PARSE_RELAXED</code>
- rules for <code class="function">g_uri_parse()</code>. (However, if <em class="parameter"><code>params</code></em> is the path or query string
- from a <span class="type">GUri</span> that was parsed without <code class="constant">G_URI_FLAGS_PARSE_RELAXED</code> and
- <code class="constant">G_URI_FLAGS_ENCODED</code>, then you already know that it does not contain any
- invalid encoding.)
- </p>
- <p><code class="constant">G_URI_PARAMS_WWW_FORM</code> is handled as documented for <code class="function">g_uri_params_iter_init()</code>.
- </p>
- <p>If <code class="constant">G_URI_PARAMS_CASE_INSENSITIVE</code> is passed to <em class="parameter"><code>flags</code></em>, attributes will be
- compared case-insensitively, so a params string <code class="code">attr=123&Attr=456</code> will only
- return a single attribute–value pair, <code class="code">Attr=456</code>. Case will be preserved in
- the returned attributes.
- </p>
- <p>If <em class="parameter"><code>params</code></em> cannot be parsed (for example, it contains two <em class="parameter"><code>separators</code></em>
- characters in a row), then <em class="parameter"><code>error</code></em> is set and <code class="constant">NULL</code> is returned.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.456.8"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>params</p></td>
- <td class="parameter_description">
- <p>a <code class="code">%</code>-encoded string containing <code class="code">attribute=value</code>
- parameters</p>
- <p>Passed as <code class="code">params</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>length</p></td>
- <td class="parameter_description">
- <p>the length of <em class="parameter"><code>params</code></em>, or <code class="code">-1</code> if it is nul-terminated</p>
- <p>Passed as <code class="code">length</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>separators</p></td>
- <td class="parameter_description">
- <p>the separator byte character set between parameters. (usually
- <code class="code">&</code>, but sometimes <code class="code">;</code> or both <code class="code">&;</code>). Note that this function works on
- bytes not characters, so it can't be used to delimit UTF-8 strings for
- anything but ASCII characters. You may pass an empty set, in which case
- no splitting will occur.</p>
- <p>Passed as <code class="code">separators</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>flags</p></td>
- <td class="parameter_description">
- <p>flags to modify the way the parameters are handled.</p>
- <p>Passed as <code class="code">flags</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.457"></a><h3>uri-parse-scheme</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (uri-parse-scheme uri))
- </pre></div>
- <p>Gets the scheme portion of a URI string.
- [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
- as:
- </p>
- <div class="informalexample"><pre class="programlisting">
- URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
- </pre></div>
- <p>Common schemes include <code class="code">file</code>, <code class="code">https</code>, <code class="code">svn+ssh</code>, etc.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.457.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>uri</p></td>
- <td class="parameter_description">
- <p>a valid URI.</p>
- <p>Passed as <code class="code">uri</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.458"></a><h3>uri-peek-scheme</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (uri-peek-scheme uri))
- </pre></div>
- <p>Gets the scheme portion of a URI string.
- [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
- as:
- </p>
- <div class="informalexample"><pre class="programlisting">
- URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
- </pre></div>
- <p>Common schemes include <code class="code">file</code>, <code class="code">https</code>, <code class="code">svn+ssh</code>, etc.
- </p>
- <p>Unlike <code class="function">g_uri_parse_scheme()</code>, the returned scheme is normalized to
- all-lowercase and does not need to be freed.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.458.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>uri</p></td>
- <td class="parameter_description">
- <p>a valid URI.</p>
- <p>Passed as <code class="code">uri</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.459"></a><h3>uri-resolve-relative</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (uri-resolve-relative base-uri-string uri-ref flags))
- </pre></div>
- <p>Parses <em class="parameter"><code>uri_ref</code></em> according to <em class="parameter"><code>flags</code></em> and, if it is a
- [relative URI][relative-absolute-uris], resolves it relative to
- <em class="parameter"><code>base_uri_string</code></em>. If the result is not a valid absolute URI, it will be
- discarded, and an error returned.
- </p>
- <p>(If <em class="parameter"><code>base_uri_string</code></em> is <code class="constant">NULL</code>, this just returns <em class="parameter"><code>uri_ref</code></em>, or
- <code class="constant">NULL</code> if <em class="parameter"><code>uri_ref</code></em> is invalid or not absolute.)</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.459.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>base_uri_string</p></td>
- <td class="parameter_description">
- <p>a string representing a base URI</p>
- <p>Passed as <code class="code">base-uri-string</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>uri_ref</p></td>
- <td class="parameter_description">
- <p>a string representing a relative or absolute URI</p>
- <p>Passed as <code class="code">uri-ref</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>flags</p></td>
- <td class="parameter_description">
- <p>flags describing how to parse <em class="parameter"><code>uri_ref</code></em></p>
- <p>Passed as <code class="code">flags</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.460"></a><h3>uri-split</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return scheme userinfo host port path query fragment)
- (uri-split uri-ref flags))
- </pre></div>
- <p>Parses <em class="parameter"><code>uri_ref</code></em> (which can be an
- [absolute or relative URI][relative-absolute-uris]) according to <em class="parameter"><code>flags</code></em>, and
- returns the pieces. Any component that doesn't appear in <em class="parameter"><code>uri_ref</code></em> will be
- returned as <code class="constant">NULL</code> (but note that all URIs always have a path component,
- though it may be the empty string).
- </p>
- <p>If <em class="parameter"><code>flags</code></em> contains <code class="constant">G_URI_FLAGS_ENCODED</code>, then <code class="code">%</code>-encoded characters in
- <em class="parameter"><code>uri_ref</code></em> will remain encoded in the output strings. (If not,
- then all such characters will be decoded.) Note that decoding will
- only work if the URI components are ASCII or UTF-8, so you will
- need to use <code class="constant">G_URI_FLAGS_ENCODED</code> if they are not.
- </p>
- <p>Note that the <code class="constant">G_URI_FLAGS_HAS_PASSWORD</code> and
- <code class="constant">G_URI_FLAGS_HAS_AUTH_PARAMS</code> <em class="parameter"><code>flags</code></em> are ignored by <code class="function">g_uri_split()</code>,
- since it always returns only the full userinfo; use
- <code class="function">g_uri_split_with_user()</code> if you want it split up.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.460.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>uri_ref</p></td>
- <td class="parameter_description">
- <p>a string containing a relative or absolute URI</p>
- <p>Passed as <code class="code">uri-ref</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>flags</p></td>
- <td class="parameter_description">
- <p>flags for parsing <em class="parameter"><code>uri_ref</code></em></p>
- <p>Passed as <code class="code">flags</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>scheme</p></td>
- <td class="parameter_description">
- <p>on return, contains
- the scheme (converted to lowercase), or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">scheme</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>userinfo</p></td>
- <td class="parameter_description">
- <p>on return, contains
- the userinfo, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">userinfo</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>host</p></td>
- <td class="parameter_description">
- <p>on return, contains the
- host, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">host</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>port</p></td>
- <td class="parameter_description">
- <p>on return, contains the
- port, or <code class="code">-1</code></p>
- <p>Passed as <code class="code">port</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>path</p></td>
- <td class="parameter_description">
- <p>on return, contains the
- path</p>
- <p>Passed as <code class="code">path</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>query</p></td>
- <td class="parameter_description">
- <p>on return, contains the
- query, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">query</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>fragment</p></td>
- <td class="parameter_description">
- <p>on return, contains
- the fragment, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">fragment</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.461"></a><h3>uri-split-network</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return scheme host port)
- (uri-split-network uri-string flags))
- </pre></div>
- <p>Parses <em class="parameter"><code>uri_string</code></em> (which must be an [absolute URI][relative-absolute-uris])
- according to <em class="parameter"><code>flags</code></em>, and returns the pieces relevant to connecting to a host.
- See the documentation for <code class="function">g_uri_split()</code> for more details; this is
- mostly a wrapper around that function with simpler arguments.
- However, it will return an error if <em class="parameter"><code>uri_string</code></em> is a relative URI,
- or does not contain a hostname component.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.461.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>uri_string</p></td>
- <td class="parameter_description">
- <p>a string containing an absolute URI</p>
- <p>Passed as <code class="code">uri-string</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>flags</p></td>
- <td class="parameter_description">
- <p>flags for parsing <em class="parameter"><code>uri_string</code></em></p>
- <p>Passed as <code class="code">flags</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>scheme</p></td>
- <td class="parameter_description">
- <p>on return, contains
- the scheme (converted to lowercase), or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">scheme</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>host</p></td>
- <td class="parameter_description">
- <p>on return, contains the
- host, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">host</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>port</p></td>
- <td class="parameter_description">
- <p>on return, contains the
- port, or <code class="code">-1</code></p>
- <p>Passed as <code class="code">port</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.462"></a><h3>uri-split-with-user</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return scheme user password auth-params host port path query fragment)
- (uri-split-with-user uri-ref flags))
- </pre></div>
- <p>Parses <em class="parameter"><code>uri_ref</code></em> (which can be an
- [absolute or relative URI][relative-absolute-uris]) according to <em class="parameter"><code>flags</code></em>, and
- returns the pieces. Any component that doesn't appear in <em class="parameter"><code>uri_ref</code></em> will be
- returned as <code class="constant">NULL</code> (but note that all URIs always have a path component,
- though it may be the empty string).
- </p>
- <p>See <code class="function">g_uri_split()</code>, and the definition of <span class="type">GUriFlags</span>, for more
- information on the effect of <em class="parameter"><code>flags</code></em>. Note that <em class="parameter"><code>password</code></em> will only
- be parsed out if <em class="parameter"><code>flags</code></em> contains <code class="constant">G_URI_FLAGS_HAS_PASSWORD</code>, and
- <em class="parameter"><code>auth_params</code></em> will only be parsed out if <em class="parameter"><code>flags</code></em> contains
- <code class="constant">G_URI_FLAGS_HAS_AUTH_PARAMS</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.462.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>uri_ref</p></td>
- <td class="parameter_description">
- <p>a string containing a relative or absolute URI</p>
- <p>Passed as <code class="code">uri-ref</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>flags</p></td>
- <td class="parameter_description">
- <p>flags for parsing <em class="parameter"><code>uri_ref</code></em></p>
- <p>Passed as <code class="code">flags</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>scheme</p></td>
- <td class="parameter_description">
- <p>on return, contains
- the scheme (converted to lowercase), or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">scheme</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>user</p></td>
- <td class="parameter_description">
- <p>on return, contains
- the user, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">user</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>password</p></td>
- <td class="parameter_description">
- <p>on return, contains
- the password, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">password</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>auth_params</p></td>
- <td class="parameter_description">
- <p>on return, contains
- the auth_params, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">auth-params</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>host</p></td>
- <td class="parameter_description">
- <p>on return, contains the
- host, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">host</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>port</p></td>
- <td class="parameter_description">
- <p>on return, contains the
- port, or <code class="code">-1</code></p>
- <p>Passed as <code class="code">port</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>path</p></td>
- <td class="parameter_description">
- <p>on return, contains the
- path</p>
- <p>Passed as <code class="code">path</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>query</p></td>
- <td class="parameter_description">
- <p>on return, contains the
- query, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">query</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>fragment</p></td>
- <td class="parameter_description">
- <p>on return, contains
- the fragment, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">fragment</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.463"></a><h3>uri-unescape-bytes</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (uri-unescape-bytes escaped-string length illegal-characters))
- </pre></div>
- <p>Unescapes a segment of an escaped string as binary data.
- </p>
- <p>Note that in contrast to <code class="function">g_uri_unescape_string()</code>, this does allow
- nul bytes to appear in the output.
- </p>
- <p>If any of the characters in <em class="parameter"><code>illegal_characters</code></em> appears as an escaped
- character in <em class="parameter"><code>escaped_string</code></em>, then that is an error and <code class="constant">NULL</code> will be
- returned. This is useful if you want to avoid for instance having a slash
- being expanded in an escaped path element, which might confuse pathname
- handling.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.463.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>escaped_string</p></td>
- <td class="parameter_description">
- <p>A URI-escaped string</p>
- <p>Passed as <code class="code">escaped-string</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>length</p></td>
- <td class="parameter_description">
- <p>the length (in bytes) of <em class="parameter"><code>escaped_string</code></em> to escape, or <code class="code">-1</code> if it
- is nul-terminated.</p>
- <p>Passed as <code class="code">length</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>illegal_characters</p></td>
- <td class="parameter_description">
- <p>a string of illegal characters
- not to be allowed, or <code class="constant">NULL</code>.</p>
- <p>Passed as <code class="code">illegal-characters</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.464"></a><h3>uri-unescape-segment</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (uri-unescape-segment escaped-string escaped-string-end illegal-characters))
- </pre></div>
- <p>Unescapes a segment of an escaped string.
- </p>
- <p>If any of the characters in <em class="parameter"><code>illegal_characters</code></em> or the NUL
- character appears as an escaped character in <em class="parameter"><code>escaped_string</code></em>, then
- that is an error and <code class="constant">NULL</code> will be returned. This is useful if you
- want to avoid for instance having a slash being expanded in an
- escaped path element, which might confuse pathname handling.
- </p>
- <p>Note: <code class="code">NUL</code> byte is not accepted in the output, in contrast to
- <code class="function">g_uri_unescape_bytes()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.464.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>escaped_string</p></td>
- <td class="parameter_description">
- <p>A string, may be <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">escaped-string</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>escaped_string_end</p></td>
- <td class="parameter_description">
- <p>Pointer to end of <em class="parameter"><code>escaped_string</code></em>,
- may be <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">escaped-string-end</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>illegal_characters</p></td>
- <td class="parameter_description">
- <p>An optional string of illegal
- characters not to be allowed, may be <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">illegal-characters</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.465"></a><h3>uri-unescape-string</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return)
- (uri-unescape-string escaped-string illegal-characters))
- </pre></div>
- <p>Unescapes a whole escaped string.
- </p>
- <p>If any of the characters in <em class="parameter"><code>illegal_characters</code></em> or the NUL
- character appears as an escaped character in <em class="parameter"><code>escaped_string</code></em>, then
- that is an error and <code class="constant">NULL</code> will be returned. This is useful if you
- want to avoid for instance having a slash being expanded in an
- escaped path element, which might confuse pathname handling.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.465.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>escaped_string</p></td>
- <td class="parameter_description">
- <p>an escaped string to be unescaped.</p>
- <p>Passed as <code class="code">escaped-string</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>illegal_characters</p></td>
- <td class="parameter_description">
- <p>a string of illegal characters
- not to be allowed, or <code class="constant">NULL</code>.</p>
- <p>Passed as <code class="code">illegal-characters</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.466"></a><h3>usleep</h3>
- <div class="informalexample"><pre class="programlisting">(define-values () (usleep microseconds))
- </pre></div>
- <p>Pauses the current thread for the given number of microseconds.
- </p>
- <p>There are 1 million microseconds per second (represented by the
- <span class="type">G_USEC_PER_SEC</span> macro). <code class="function">g_usleep()</code> may have limited precision,
- depending on hardware and operating system; don't rely on the exact
- length of the sleep.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.466.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>microseconds</p></td>
- <td class="parameter_description">
- <p>number of microseconds to pause</p>
- <p>Passed as <code class="code">microseconds</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.467"></a><h3>utf16-to-ucs4</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return items-read items-written)
- (utf16-to-ucs4 str len items-read items-written))
- </pre></div>
- <p>Convert a string from UTF-16 to UCS-4. The result will be
- nul-terminated.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.467.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a UTF-16 encoded string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>the maximum length (number of <span class="type">gunichar2</span>) of <em class="parameter"><code>str</code></em> to use.
- If <em class="parameter"><code>len</code></em> < 0, then the string is nul-terminated.</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>items_read</p></td>
- <td class="parameter_description">
- <p>location to store number of
- words read, or <code class="constant">NULL</code>. If <code class="constant">NULL</code>, then <code class="constant">G_CONVERT_ERROR_PARTIAL_INPUT</code> will
- be returned in case <em class="parameter"><code>str</code></em> contains a trailing partial character. If
- an error occurs then the index of the invalid input is stored here.</p>
- <p>Passed as <code class="code">items-read</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>items_written</p></td>
- <td class="parameter_description">
- <p>location to store number
- of characters written, or <code class="constant">NULL</code>. The value stored here does not include
- the trailing 0 character.</p>
- <p>Passed as <code class="code">items-written</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.468"></a><h3>utf16-to-utf8</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return items-read items-written)
- (utf16-to-utf8 str len items-read items-written))
- </pre></div>
- <p>Convert a string from UTF-16 to UTF-8. The result will be
- terminated with a 0 byte.
- </p>
- <p>Note that the input is expected to be already in native endianness,
- an initial byte-order-mark character is not handled specially.
- <code class="function">g_convert()</code> can be used to convert a byte buffer of UTF-16 data of
- ambiguous endianness.
- </p>
- <p>Further note that this function does not validate the result
- string; it may e.g. include embedded NUL characters. The only
- validation done by this function is to ensure that the input can
- be correctly interpreted as UTF-16, i.e. it doesn't contain
- unpaired surrogates or partial character sequences.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.468.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a UTF-16 encoded string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>the maximum length (number of <span class="type">gunichar2</span>) of <em class="parameter"><code>str</code></em> to use.
- If <em class="parameter"><code>len</code></em> < 0, then the string is nul-terminated.</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>items_read</p></td>
- <td class="parameter_description">
- <p>location to store number of
- words read, or <code class="constant">NULL</code>. If <code class="constant">NULL</code>, then <code class="constant">G_CONVERT_ERROR_PARTIAL_INPUT</code> will
- be returned in case <em class="parameter"><code>str</code></em> contains a trailing partial character. If
- an error occurs then the index of the invalid input is stored here.</p>
- <p>Passed as <code class="code">items-read</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>items_written</p></td>
- <td class="parameter_description">
- <p>location to store number
- of bytes written, or <code class="constant">NULL</code>. The value stored here does not include the
- trailing 0 byte.</p>
- <p>Passed as <code class="code">items-written</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.469"></a><h3>utf8-casefold</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-casefold str len))
- </pre></div>
- <p>Converts a string into a form that is independent of case. The
- result will not correspond to any particular case, but can be
- compared for equality or ordered with the results of calling
- <code class="function">g_utf8_casefold()</code> on other strings.
- </p>
- <p>Note that calling <code class="function">g_utf8_casefold()</code> followed by <code class="function">g_utf8_collate()</code> is
- only an approximation to the correct linguistic case insensitive
- ordering, though it is a fairly good one. Getting this exactly
- right would require a more sophisticated collation function that
- takes case sensitivity into account. GLib does not currently
- provide such a function.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.469.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a UTF-8 encoded string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>length of <em class="parameter"><code>str</code></em>, in bytes, or -1 if <em class="parameter"><code>str</code></em> is nul-terminated.</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.470"></a><h3>utf8-collate</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-collate str1 str2))
- </pre></div>
- <p>Compares two strings for ordering using the linguistically
- correct rules for the [current locale][setlocale].
- When sorting a large number of strings, it will be significantly
- faster to obtain collation keys with <code class="function">g_utf8_collate_key()</code> and
- compare the keys with <code class="function">strcmp()</code> when sorting instead of sorting
- the original strings.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.470.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str1</p></td>
- <td class="parameter_description">
- <p>a UTF-8 encoded string</p>
- <p>Passed as <code class="code">str1</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>str2</p></td>
- <td class="parameter_description">
- <p>a UTF-8 encoded string</p>
- <p>Passed as <code class="code">str2</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.471"></a><h3>utf8-collate-key</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-collate-key str len))
- </pre></div>
- <p>Converts a string into a collation key that can be compared
- with other collation keys produced by the same function using
- <code class="function">strcmp()</code>.
- </p>
- <p>The results of comparing the collation keys of two strings
- with <code class="function">strcmp()</code> will always be the same as comparing the two
- original keys with <code class="function">g_utf8_collate()</code>.
- </p>
- <p>Note that this function depends on the [current locale][setlocale].</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.471.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a UTF-8 encoded string.</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>length of <em class="parameter"><code>str</code></em>, in bytes, or -1 if <em class="parameter"><code>str</code></em> is nul-terminated.</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.472"></a><h3>utf8-collate-key-for-filename</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-collate-key-for-filename str len))
- </pre></div>
- <p>Converts a string into a collation key that can be compared
- with other collation keys produced by the same function using <code class="function">strcmp()</code>.
- </p>
- <p>In order to sort filenames correctly, this function treats the dot '.'
- as a special case. Most dictionary orderings seem to consider it
- insignificant, thus producing the ordering "event.c" "eventgenerator.c"
- "event.h" instead of "event.c" "event.h" "eventgenerator.c". Also, we
- would like to treat numbers intelligently so that "file1" "file10" "file5"
- is sorted as "file1" "file5" "file10".
- </p>
- <p>Note that this function depends on the [current locale][setlocale].</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.472.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a UTF-8 encoded string.</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>length of <em class="parameter"><code>str</code></em>, in bytes, or -1 if <em class="parameter"><code>str</code></em> is nul-terminated.</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.473"></a><h3>utf8-find-next-char</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-find-next-char p end))
- </pre></div>
- <p>Finds the start of the next UTF-8 character in the string after <em class="parameter"><code>p</code></em>.
- </p>
- <p><em class="parameter"><code>p</code></em> does not have to be at the beginning of a UTF-8 character. No check
- is made to see if the character found is actually valid other than
- it starts with an appropriate byte.
- </p>
- <p>If <em class="parameter"><code>end</code></em> is <code class="constant">NULL</code>, the return value will never be <code class="constant">NULL</code>: if the end of the
- string is reached, a pointer to the terminating nul byte is returned. If
- <em class="parameter"><code>end</code></em> is non-<code class="constant">NULL</code>, the return value will be <code class="constant">NULL</code> if the end of the string
- is reached.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.473.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>p</p></td>
- <td class="parameter_description">
- <p>a pointer to a position within a UTF-8 encoded string</p>
- <p>Passed as <code class="code">p</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>end</p></td>
- <td class="parameter_description">
- <p>a pointer to the byte following the end of the string,
- or <code class="constant">NULL</code> to indicate that the string is nul-terminated</p>
- <p>Passed as <code class="code">end</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.474"></a><h3>utf8-find-prev-char</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-find-prev-char str p))
- </pre></div>
- <p>Given a position <em class="parameter"><code>p</code></em> with a UTF-8 encoded string <em class="parameter"><code>str</code></em>, find the start
- of the previous UTF-8 character starting before <em class="parameter"><code>p</code></em>. Returns <code class="constant">NULL</code> if no
- UTF-8 characters are present in <em class="parameter"><code>str</code></em> before <em class="parameter"><code>p</code></em>.
- </p>
- <p><em class="parameter"><code>p</code></em> does not have to be at the beginning of a UTF-8 character. No check
- is made to see if the character found is actually valid other than
- it starts with an appropriate byte.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.474.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>pointer to the beginning of a UTF-8 encoded string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>p</p></td>
- <td class="parameter_description">
- <p>pointer to some position within <em class="parameter"><code>str</code></em></p>
- <p>Passed as <code class="code">p</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.475"></a><h3>utf8-get-char</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-get-char p))
- </pre></div>
- <p>Converts a sequence of bytes encoded as UTF-8 to a Unicode character.
- </p>
- <p>If <em class="parameter"><code>p</code></em> does not point to a valid UTF-8 encoded character, results
- are undefined. If you are not sure that the bytes are complete
- valid Unicode characters, you should use <code class="function">g_utf8_get_char_validated()</code>
- instead.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.475.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>p</p></td>
- <td class="parameter_description">
- <p>a pointer to Unicode character encoded as UTF-8</p>
- <p>Passed as <code class="code">p</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.476"></a><h3>utf8-get-char-validated</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-get-char-validated p max-len))
- </pre></div>
- <p>Convert a sequence of bytes encoded as UTF-8 to a Unicode character.
- This function checks for incomplete characters, for invalid characters
- such as characters that are out of the range of Unicode, and for
- overlong encodings of valid characters.
- </p>
- <p>Note that <code class="function">g_utf8_get_char_validated()</code> returns (gunichar)-2 if
- <em class="parameter"><code>max_len</code></em> is positive and any of the bytes in the first UTF-8 character
- sequence are nul.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.476.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>p</p></td>
- <td class="parameter_description">
- <p>a pointer to Unicode character encoded as UTF-8</p>
- <p>Passed as <code class="code">p</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>max_len</p></td>
- <td class="parameter_description">
- <p>the maximum number of bytes to read, or -1 if <em class="parameter"><code>p</code></em> is nul-terminated</p>
- <p>Passed as <code class="code">max-len</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.477"></a><h3>utf8-make-valid</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-make-valid str len))
- </pre></div>
- <p>If the provided string is valid UTF-8, return a copy of it. If not,
- return a copy in which bytes that could not be interpreted as valid Unicode
- are replaced with the Unicode replacement character (U+FFFD).
- </p>
- <p>For example, this is an appropriate function to use if you have received
- a string that was incorrectly declared to be UTF-8, and you need a valid
- UTF-8 version of it that can be logged or displayed to the user, with the
- assumption that it is close enough to ASCII or UTF-8 to be mostly
- readable as-is.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.477.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>string to coerce into UTF-8</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>the maximum length of <em class="parameter"><code>str</code></em> to use, in bytes. If <em class="parameter"><code>len</code></em> < 0,
- then the string is nul-terminated.</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.478"></a><h3>utf8-normalize</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-normalize str len mode))
- </pre></div>
- <p>Converts a string into canonical form, standardizing
- such issues as whether a character with an accent
- is represented as a base character and combining
- accent or as a single precomposed character. The
- string has to be valid UTF-8, otherwise <code class="constant">NULL</code> is
- returned. You should generally call <code class="function">g_utf8_normalize()</code>
- before comparing two Unicode strings.
- </p>
- <p>The normalization mode <code class="constant">G_NORMALIZE_DEFAULT</code> only
- standardizes differences that do not affect the
- text content, such as the above-mentioned accent
- representation. <code class="constant">G_NORMALIZE_ALL</code> also standardizes
- the "compatibility" characters in Unicode, such
- as SUPERSCRIPT THREE to the standard forms
- (in this case DIGIT THREE). Formatting information
- may be lost but for most text operations such
- characters should be considered the same.
- </p>
- <p><code class="constant">G_NORMALIZE_DEFAULT_COMPOSE</code> and <code class="constant">G_NORMALIZE_ALL_COMPOSE</code>
- are like <code class="constant">G_NORMALIZE_DEFAULT</code> and <code class="constant">G_NORMALIZE_ALL</code>,
- but returned a result with composed forms rather
- than a maximally decomposed form. This is often
- useful if you intend to convert the string to
- a legacy encoding or pass it to a system with
- less capable Unicode handling.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.478.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a UTF-8 encoded string.</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>length of <em class="parameter"><code>str</code></em>, in bytes, or -1 if <em class="parameter"><code>str</code></em> is nul-terminated.</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>mode</p></td>
- <td class="parameter_description">
- <p>the type of normalization to perform.</p>
- <p>Passed as <code class="code">mode</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.479"></a><h3>utf8-offset-to-pointer</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-offset-to-pointer str offset))
- </pre></div>
- <p>Converts from an integer character offset to a pointer to a position
- within the string.
- </p>
- <p>Since 2.10, this function allows to pass a negative <em class="parameter"><code>offset</code></em> to
- step backwards. It is usually worth stepping backwards from the end
- instead of forwards if <em class="parameter"><code>offset</code></em> is in the last fourth of the string,
- since moving forward is about 3 times faster than moving backward.
- </p>
- <p>Note that this function doesn't abort when reaching the end of <em class="parameter"><code>str</code></em>.
- Therefore you should be sure that <em class="parameter"><code>offset</code></em> is within string boundaries
- before calling that function. Call <code class="function">g_utf8_strlen()</code> when unsure.
- This limitation exists as this function is called frequently during
- text rendering and therefore has to be as fast as possible.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.479.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a UTF-8 encoded string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>offset</p></td>
- <td class="parameter_description">
- <p>a character offset within <em class="parameter"><code>str</code></em></p>
- <p>Passed as <code class="code">offset</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.480"></a><h3>utf8-pointer-to-offset</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-pointer-to-offset str pos))
- </pre></div>
- <p>Converts from a pointer to position within a string to an integer
- character offset.
- </p>
- <p>Since 2.10, this function allows <em class="parameter"><code>pos</code></em> to be before <em class="parameter"><code>str</code></em>, and returns
- a negative offset in this case.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.480.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a UTF-8 encoded string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>pos</p></td>
- <td class="parameter_description">
- <p>a pointer to a position within <em class="parameter"><code>str</code></em></p>
- <p>Passed as <code class="code">pos</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.481"></a><h3>utf8-prev-char</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-prev-char p))
- </pre></div>
- <p>Finds the previous UTF-8 character in the string before <em class="parameter"><code>p</code></em>.
- </p>
- <p><em class="parameter"><code>p</code></em> does not have to be at the beginning of a UTF-8 character. No check
- is made to see if the character found is actually valid other than
- it starts with an appropriate byte. If <em class="parameter"><code>p</code></em> might be the first
- character of the string, you must use <code class="function">g_utf8_find_prev_char()</code> instead.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.481.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>p</p></td>
- <td class="parameter_description">
- <p>a pointer to a position within a UTF-8 encoded string</p>
- <p>Passed as <code class="code">p</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.482"></a><h3>utf8-strchr</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-strchr p len c))
- </pre></div>
- <p>Finds the leftmost occurrence of the given Unicode character
- in a UTF-8 encoded string, while limiting the search to <em class="parameter"><code>len</code></em> bytes.
- If <em class="parameter"><code>len</code></em> is -1, allow unbounded search.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.482.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>p</p></td>
- <td class="parameter_description">
- <p>a nul-terminated UTF-8 encoded string</p>
- <p>Passed as <code class="code">p</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>the maximum length of <em class="parameter"><code>p</code></em></p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.483"></a><h3>utf8-strdown</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-strdown str len))
- </pre></div>
- <p>Converts all Unicode characters in the string that have a case
- to lowercase. The exact manner that this is done depends
- on the current locale, and may result in the number of
- characters in the string changing.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.483.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a UTF-8 encoded string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>length of <em class="parameter"><code>str</code></em>, in bytes, or -1 if <em class="parameter"><code>str</code></em> is nul-terminated.</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.484"></a><h3>utf8-strlen</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-strlen p max))
- </pre></div>
- <p>Computes the length of the string in characters, not including
- the terminating nul character. If the <em class="parameter"><code>max</code></em>'th byte falls in the
- middle of a character, the last (partial) character is not counted.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.484.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>p</p></td>
- <td class="parameter_description">
- <p>pointer to the start of a UTF-8 encoded string</p>
- <p>Passed as <code class="code">p</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>max</p></td>
- <td class="parameter_description">
- <p>the maximum number of bytes to examine. If <em class="parameter"><code>max</code></em>
- is less than 0, then the string is assumed to be
- nul-terminated. If <em class="parameter"><code>max</code></em> is 0, <em class="parameter"><code>p</code></em> will not be examined and
- may be <code class="constant">NULL</code>. If <em class="parameter"><code>max</code></em> is greater than 0, up to <em class="parameter"><code>max</code></em>
- bytes are examined</p>
- <p>Passed as <code class="code">max</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.485"></a><h3>utf8-strncpy</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-strncpy dest src n))
- </pre></div>
- <p>Like the standard C <code class="function">strncpy()</code> function, but copies a given number
- of characters instead of a given number of bytes. The <em class="parameter"><code>src</code></em> string
- must be valid UTF-8 encoded text. (Use <code class="function">g_utf8_validate()</code> on all
- text before trying to use UTF-8 utility functions with it.)
- </p>
- <p>Note you must ensure <em class="parameter"><code>dest</code></em> is at least 4 * <em class="parameter"><code>n</code></em> to fit the
- largest possible UTF-8 characters</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.485.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>dest</p></td>
- <td class="parameter_description">
- <p>buffer to fill with characters from <em class="parameter"><code>src</code></em></p>
- <p>Passed as <code class="code">dest</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>src</p></td>
- <td class="parameter_description">
- <p>UTF-8 encoded string</p>
- <p>Passed as <code class="code">src</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>n</p></td>
- <td class="parameter_description">
- <p>character count</p>
- <p>Passed as <code class="code">n</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.486"></a><h3>utf8-strrchr</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-strrchr p len c))
- </pre></div>
- <p>Find the rightmost occurrence of the given Unicode character
- in a UTF-8 encoded string, while limiting the search to <em class="parameter"><code>len</code></em> bytes.
- If <em class="parameter"><code>len</code></em> is -1, allow unbounded search.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.486.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>p</p></td>
- <td class="parameter_description">
- <p>a nul-terminated UTF-8 encoded string</p>
- <p>Passed as <code class="code">p</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>the maximum length of <em class="parameter"><code>p</code></em></p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>c</p></td>
- <td class="parameter_description">
- <p>a Unicode character</p>
- <p>Passed as <code class="code">c</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.487"></a><h3>utf8-strreverse</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-strreverse str len))
- </pre></div>
- <p>Reverses a UTF-8 string. <em class="parameter"><code>str</code></em> must be valid UTF-8 encoded text.
- (Use <code class="function">g_utf8_validate()</code> on all text before trying to use UTF-8
- utility functions with it.)
- </p>
- <p>This function is intended for programmatic uses of reversed strings.
- It pays no attention to decomposed characters, combining marks, byte
- order marks, directional indicators (LRM, LRO, etc) and similar
- characters which might need special handling when reversing a string
- for display purposes.
- </p>
- <p>Note that unlike <code class="function">g_strreverse()</code>, this function returns
- newly-allocated memory, which should be freed with <code class="function">g_free()</code> when
- no longer needed.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.487.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a UTF-8 encoded string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>the maximum length of <em class="parameter"><code>str</code></em> to use, in bytes. If <em class="parameter"><code>len</code></em> < 0,
- then the string is nul-terminated.</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.488"></a><h3>utf8-strup</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-strup str len))
- </pre></div>
- <p>Converts all Unicode characters in the string that have a case
- to uppercase. The exact manner that this is done depends
- on the current locale, and may result in the number of
- characters in the string increasing. (For instance, the
- German ess-zet will be changed to SS.)</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.488.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a UTF-8 encoded string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>length of <em class="parameter"><code>str</code></em>, in bytes, or -1 if <em class="parameter"><code>str</code></em> is nul-terminated.</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.489"></a><h3>utf8-substring</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (utf8-substring str start-pos end-pos))
- </pre></div>
- <p>Copies a substring out of a UTF-8 encoded string.
- The substring will contain <em class="parameter"><code>end_pos</code></em> - <em class="parameter"><code>start_pos</code></em> characters.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.489.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a UTF-8 encoded string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>start_pos</p></td>
- <td class="parameter_description">
- <p>a character offset within <em class="parameter"><code>str</code></em></p>
- <p>Passed as <code class="code">start-pos</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>end_pos</p></td>
- <td class="parameter_description">
- <p>another character offset within <em class="parameter"><code>str</code></em></p>
- <p>Passed as <code class="code">end-pos</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.490"></a><h3>utf8-to-ucs4</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return items-read items-written)
- (utf8-to-ucs4 str len items-read items-written))
- </pre></div>
- <p>Convert a string from UTF-8 to a 32-bit fixed width
- representation as UCS-4. A trailing 0 character will be added to the
- string after the converted text.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.490.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a UTF-8 encoded string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>the maximum length of <em class="parameter"><code>str</code></em> to use, in bytes. If <em class="parameter"><code>len</code></em> < 0,
- then the string is nul-terminated.</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>items_read</p></td>
- <td class="parameter_description">
- <p>location to store number of
- bytes read, or <code class="constant">NULL</code>.
- If <code class="constant">NULL</code>, then <code class="constant">G_CONVERT_ERROR_PARTIAL_INPUT</code> will be
- returned in case <em class="parameter"><code>str</code></em> contains a trailing partial
- character. If an error occurs then the index of the
- invalid input is stored here.</p>
- <p>Passed as <code class="code">items-read</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>items_written</p></td>
- <td class="parameter_description">
- <p>location to store number
- of characters written or <code class="constant">NULL</code>. The value here stored does not include
- the trailing 0 character.</p>
- <p>Passed as <code class="code">items-written</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.491"></a><h3>utf8-to-ucs4-fast</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return items-written)
- (utf8-to-ucs4-fast str len items-written))
- </pre></div>
- <p>Convert a string from UTF-8 to a 32-bit fixed width
- representation as UCS-4, assuming valid UTF-8 input.
- This function is roughly twice as fast as <code class="function">g_utf8_to_ucs4()</code>
- but does no error checking on the input. A trailing 0 character
- will be added to the string after the converted text.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.491.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a UTF-8 encoded string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>the maximum length of <em class="parameter"><code>str</code></em> to use, in bytes. If <em class="parameter"><code>len</code></em> < 0,
- then the string is nul-terminated.</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>items_written</p></td>
- <td class="parameter_description">
- <p>location to store the
- number of characters in the result, or <code class="constant">NULL</code>.</p>
- <p>Passed as <code class="code">items-written</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.492"></a><h3>utf8-to-utf16</h3>
- <div class="informalexample"><pre class="programlisting">(define-values
- (%return items-read items-written)
- (utf8-to-utf16 str len items-read items-written))
- </pre></div>
- <p>Convert a string from UTF-8 to UTF-16. A 0 character will be
- added to the result after the converted text.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.492.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a UTF-8 encoded string</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>len</p></td>
- <td class="parameter_description">
- <p>the maximum length (number of bytes) of <em class="parameter"><code>str</code></em> to use.
- If <em class="parameter"><code>len</code></em> < 0, then the string is nul-terminated.</p>
- <p>Passed as <code class="code">len</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>items_read</p></td>
- <td class="parameter_description">
- <p>location to store number of
- bytes read, or <code class="constant">NULL</code>. If <code class="constant">NULL</code>, then <code class="constant">G_CONVERT_ERROR_PARTIAL_INPUT</code> will
- be returned in case <em class="parameter"><code>str</code></em> contains a trailing partial character. If
- an error occurs then the index of the invalid input is stored here.</p>
- <p>Passed as <code class="code">items-read</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>items_written</p></td>
- <td class="parameter_description">
- <p>location to store number
- of <span class="type">gunichar2</span> written, or <code class="constant">NULL</code>. The value stored here does not include
- the trailing 0.</p>
- <p>Passed as <code class="code">items-written</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.493"></a><h3>utf8-validate</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return end) (utf8-validate str))
- </pre></div>
- <p>Validates UTF-8 encoded text. <em class="parameter"><code>str</code></em> is the text to validate;
- if <em class="parameter"><code>str</code></em> is nul-terminated, then <em class="parameter"><code>max_len</code></em> can be -1, otherwise
- <em class="parameter"><code>max_len</code></em> should be the number of bytes to validate.
- If <em class="parameter"><code>end</code></em> is non-<code class="constant">NULL</code>, then the end of the valid range
- will be stored there (i.e. the start of the first invalid
- character if some bytes were invalid, or the end of the text
- being validated otherwise).
- </p>
- <p>Note that <code class="function">g_utf8_validate()</code> returns <code class="constant">FALSE</code> if <em class="parameter"><code>max_len</code></em> is
- positive and any of the <em class="parameter"><code>max_len</code></em> bytes are nul.
- </p>
- <p>Returns <code class="constant">TRUE</code> if all of <em class="parameter"><code>str</code></em> was valid. Many GLib and GTK+
- routines require valid UTF-8 as input; so data read from a file
- or the network should be checked with <code class="function">g_utf8_validate()</code> before
- doing anything else with it.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.493.6"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a pointer to character data</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>max_len</p></td>
- <td class="parameter_description">
- <p>max bytes to validate, or -1 to go until NUL</p>
- <p>Inferred from <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>end</p></td>
- <td class="parameter_description">
- <p>return location for end of valid data</p>
- <p>Passed as <code class="code">end</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.494"></a><h3>utf8-validate-len</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return end) (utf8-validate-len str))
- </pre></div>
- <p>Validates UTF-8 encoded text.
- </p>
- <p>As with <code class="function">g_utf8_validate()</code>, but <em class="parameter"><code>max_len</code></em> must be set, and hence this function
- will always return <code class="constant">FALSE</code> if any of the bytes of <em class="parameter"><code>str</code></em> are nul.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.494.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a pointer to character data</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>max_len</p></td>
- <td class="parameter_description">
- <p>max bytes to validate</p>
- <p>Inferred from <code class="code">str</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>end</p></td>
- <td class="parameter_description">
- <p>return location for end of valid data</p>
- <p>Passed as <code class="code">end</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.495"></a><h3>uuid-string-is-valid?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (uuid-string-is-valid? str))
- </pre></div>
- <p>Parses the string <em class="parameter"><code>str</code></em> and verify if it is a UUID.
- </p>
- <p>The function accepts the following syntax:
- </p>
- <p>- simple forms (e.g. <code class="code">f81d4fae-7dec-11d0-a765-00a0c91e6bf6</code>)
- </p>
- <p>Note that hyphens are required within the UUID string itself,
- as per the aforementioned RFC.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.495.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>str</p></td>
- <td class="parameter_description">
- <p>a string representing a UUID</p>
- <p>Passed as <code class="code">str</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.496"></a><h3>uuid-string-random</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (uuid-string-random))
- </pre></div>
- <p>Generates a random UUID (RFC 4122 version 4) as a string. It has the same
- randomness guarantees as <span class="type">GRand</span>, so must not be used for cryptographic
- purposes such as key generation, nonces, salts or one-time pads.</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.497"></a><h3>variant-get-gtype</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-get-gtype))
- </pre></div>
- <p>Undocumented</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.498"></a><h3>variant-is-object-path?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-is-object-path? string))
- </pre></div>
- <p>Determines if a given string is a valid D-Bus object path. You
- should ensure that a string is a valid D-Bus object path before
- passing it to <code class="function">g_variant_new_object_path()</code>.
- </p>
- <p>A valid object path starts with <code class="code">/</code> followed by zero or more
- sequences of characters separated by <code class="code">/</code> characters. Each sequence
- must contain only the characters <code class="code">[A-Z][a-z][0-9]_</code>. No sequence
- (including the one following the final <code class="code">/</code> character) may be empty.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.498.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>a normal C nul-terminated string</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.499"></a><h3>variant-is-signature?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-is-signature? string))
- </pre></div>
- <p>Determines if a given string is a valid D-Bus type signature. You
- should ensure that a string is a valid D-Bus type signature before
- passing it to <code class="function">g_variant_new_signature()</code>.
- </p>
- <p>D-Bus type signatures consist of zero or more definite <span class="type">GVariantType</span>
- strings in sequence.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.499.5"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>a normal C nul-terminated string</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.500"></a><h3>variant-parse</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-parse type text limit endptr))
- </pre></div>
- <p>Parses a <span class="type">GVariant</span> from a text representation.
- </p>
- <p>A single <span class="type">GVariant</span> is parsed from the content of <em class="parameter"><code>text</code></em>.
- </p>
- <p>The format is described [here][gvariant-text].
- </p>
- <p>The memory at <em class="parameter"><code>limit</code></em> will never be accessed and the parser behaves as
- if the character at <em class="parameter"><code>limit</code></em> is the nul terminator. This has the
- effect of bounding <em class="parameter"><code>text</code></em>.
- </p>
- <p>If <em class="parameter"><code>endptr</code></em> is non-<code class="constant">NULL</code> then <em class="parameter"><code>text</code></em> is permitted to contain data
- following the value that this function parses and <em class="parameter"><code>endptr</code></em> will be
- updated to point to the first character past the end of the text
- parsed by this function. If <em class="parameter"><code>endptr</code></em> is <code class="constant">NULL</code> and there is extra data
- then an error is returned.
- </p>
- <p>If <em class="parameter"><code>type</code></em> is non-<code class="constant">NULL</code> then the value will be parsed to have that
- type. This may result in additional parse errors (in the case that
- the parsed value doesn't fit the type) but may also result in fewer
- errors (in the case that the type would have been ambiguous, such as
- with empty arrays).
- </p>
- <p>In the event that the parsing is successful, the resulting <span class="type">GVariant</span>
- is returned. It is never floating, and must be freed with
- <code class="function">g_variant_unref()</code>.
- </p>
- <p>In case of any error, <code class="constant">NULL</code> will be returned. If <em class="parameter"><code>error</code></em> is non-<code class="constant">NULL</code>
- then it will be set to reflect the error that occurred.
- </p>
- <p>Officially, the language understood by the parser is "any string
- produced by <code class="function">g_variant_print()</code>".
- </p>
- <p>There may be implementation specific restrictions on deeply nested values,
- which would result in a <code class="constant">G_VARIANT_PARSE_ERROR_RECURSION</code> error. <span class="type">GVariant</span> is
- guaranteed to handle nesting up to at least 64 levels.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.500.13"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>type</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GVariantType</span>, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">type</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>text</p></td>
- <td class="parameter_description">
- <p>a string containing a GVariant in text form</p>
- <p>Passed as <code class="code">text</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>limit</p></td>
- <td class="parameter_description">
- <p>a pointer to the end of <em class="parameter"><code>text</code></em>, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">limit</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>endptr</p></td>
- <td class="parameter_description">
- <p>a location to store the end pointer, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">endptr</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.501"></a><h3>variant-parse-error-print-context</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-parse-error-print-context error source-str))
- </pre></div>
- <p>Pretty-prints a message showing the context of a <span class="type">GVariant</span> parse
- error within the string for which parsing was attempted.
- </p>
- <p>The resulting string is suitable for output to the console or other
- monospace media where newlines are treated in the usual way.
- </p>
- <p>The message will typically look something like one of the following:
- </p>
- <div class="informalexample"><pre class="programlisting">
- unterminated string constant:
- (1, 2, 3, 'abc
- ^^^^
- </pre></div>
- <p>or
- </p>
- <div class="informalexample"><pre class="programlisting">
- unable to find a common type:
- [1, 2, 3, 'str']
- ^ ^^^^^
- </pre></div>
- <p>The format of the message may change in a future version.
- </p>
- <p><em class="parameter"><code>error</code></em> must have come from a failed attempt to <code class="function">g_variant_parse()</code> and
- <em class="parameter"><code>source_str</code></em> must be exactly the same string that caused the error.
- If <em class="parameter"><code>source_str</code></em> was not nul-terminated when you passed it to
- <code class="function">g_variant_parse()</code> then you must add nul termination before using this
- function.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.501.11"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>error</p></td>
- <td class="parameter_description">
- <p>a <span class="type">GError</span> from the <span class="type">GVariantParseError</span> domain</p>
- <p>Passed as <code class="code">error</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>source_str</p></td>
- <td class="parameter_description">
- <p>the string that was given to the parser</p>
- <p>Passed as <code class="code">source-str</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.502"></a><h3>variant-parse-error-quark</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-parse-error-quark))
- </pre></div>
- <p>Undocumented</p>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.503"></a><h3>variant-type-checked-</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-type-checked- arg0))
- </pre></div>
- <p>Undocumented</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.503.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>arg0</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">arg0</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.504"></a><h3>variant-type-string-get-depth-</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-type-string-get-depth- type-string))
- </pre></div>
- <p>Undocumented</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.504.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>type_string</p></td>
- <td class="parameter_description">
- <p></p>
- <p>Passed as <code class="code">type-string</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.505"></a><h3>variant-type-string-is-valid?</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return) (variant-type-string-is-valid? type-string))
- </pre></div>
- <p>Checks if <em class="parameter"><code>type_string</code></em> is a valid GVariant type string. This call is
- equivalent to calling <code class="function">g_variant_type_string_scan()</code> and confirming
- that the following character is a nul terminator.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.505.4"></a><h4>Parameters</h4>
- <div class="informaltable"><table><tr>
- <td class="parameter_name"><p>type_string</p></td>
- <td class="parameter_description">
- <p>a pointer to any string</p>
- <p>Passed as <code class="code">type-string</code></p>
- </td>
- </tr></table></div>
- </div>
- </div>
- <div class="refsect2">
- <a name="id-1.1.90.2.506"></a><h3>variant-type-string-scan</h3>
- <div class="informalexample"><pre class="programlisting">(define-values (%return endptr) (variant-type-string-scan string limit))
- </pre></div>
- <p>Scan for a single complete and valid GVariant type string in <em class="parameter"><code>string</code></em>.
- The memory pointed to by <em class="parameter"><code>limit</code></em> (or bytes beyond it) is never
- accessed.
- </p>
- <p>If a valid type string is found, <em class="parameter"><code>endptr</code></em> is updated to point to the
- first character past the end of the string that was found and <code class="constant">TRUE</code>
- is returned.
- </p>
- <p>If there is no valid type string starting at <em class="parameter"><code>string</code></em>, or if the type
- string does not end before <em class="parameter"><code>limit</code></em> then <code class="constant">FALSE</code> is returned.
- </p>
- <p>For the simple case of checking if a string is a valid type string,
- see <code class="function">g_variant_type_string_is_valid()</code>.</p>
- <div class="refsect3">
- <a name="id-1.1.90.2.506.7"></a><h4>Parameters</h4>
- <div class="informaltable"><table>
- <tr>
- <td class="parameter_name"><p>string</p></td>
- <td class="parameter_description">
- <p>a pointer to any string</p>
- <p>Passed as <code class="code">string</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>limit</p></td>
- <td class="parameter_description">
- <p>the end of <em class="parameter"><code>string</code></em>, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">limit</code></p>
- </td>
- </tr>
- <tr>
- <td class="parameter_name"><p>endptr</p></td>
- <td class="parameter_description">
- <p>location to store the end pointer, or <code class="constant">NULL</code></p>
- <p>Passed as <code class="code">endptr</code></p>
- </td>
- </tr>
- </table></div>
- </div>
- </div>
- </div>
- </div>
- <div class="footer">
- <hr>Generated by GTK-Doc V1.33.1</div>
- </body>
- </html>
|
