| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185418641874188418941904191419241934194419541964197419841994200420142024203420442054206420742084209421042114212421342144215421642174218421942204221422242234224422542264227422842294230423142324233423442354236423742384239424042414242424342444245424642474248424942504251425242534254425542564257425842594260426142624263426442654266426742684269427042714272427342744275427642774278427942804281428242834284428542864287428842894290429142924293429442954296429742984299430043014302430343044305430643074308430943104311431243134314431543164317431843194320432143224323432443254326432743284329433043314332433343344335433643374338433943404341434243434344434543464347434843494350435143524353435443554356435743584359436043614362436343644365436643674368436943704371437243734374437543764377437843794380438143824383438443854386438743884389439043914392439343944395439643974398439944004401440244034404440544064407440844094410441144124413441444154416441744184419442044214422442344244425442644274428442944304431443244334434443544364437443844394440444144424443444444454446444744484449445044514452445344544455445644574458445944604461446244634464446544664467446844694470447144724473447444754476447744784479448044814482448344844485448644874488448944904491449244934494449544964497449844994500450145024503450445054506450745084509451045114512451345144515451645174518451945204521452245234524452545264527452845294530453145324533453445354536453745384539454045414542454345444545454645474548454945504551455245534554455545564557455845594560456145624563456445654566456745684569457045714572457345744575457645774578457945804581458245834584458545864587458845894590459145924593459445954596459745984599460046014602460346044605460646074608460946104611461246134614461546164617461846194620462146224623462446254626462746284629463046314632463346344635463646374638463946404641464246434644464546464647464846494650465146524653465446554656465746584659466046614662466346644665466646674668466946704671467246734674467546764677467846794680468146824683468446854686468746884689469046914692469346944695469646974698469947004701470247034704470547064707470847094710471147124713471447154716471747184719472047214722472347244725472647274728472947304731473247334734473547364737473847394740474147424743474447454746474747484749475047514752475347544755475647574758475947604761476247634764476547664767476847694770477147724773477447754776477747784779478047814782478347844785478647874788478947904791479247934794479547964797479847994800480148024803480448054806480748084809481048114812481348144815481648174818481948204821482248234824482548264827482848294830483148324833483448354836483748384839484048414842484348444845484648474848484948504851485248534854485548564857485848594860486148624863486448654866486748684869487048714872487348744875487648774878487948804881488248834884488548864887488848894890489148924893489448954896489748984899490049014902490349044905490649074908490949104911491249134914491549164917491849194920492149224923492449254926492749284929493049314932493349344935493649374938493949404941494249434944494549464947494849494950495149524953495449554956495749584959496049614962496349644965496649674968496949704971497249734974497549764977497849794980498149824983498449854986498749884989499049914992499349944995499649974998499950005001500250035004500550065007500850095010501150125013501450155016501750185019502050215022502350245025502650275028502950305031503250335034503550365037503850395040504150425043504450455046504750485049505050515052505350545055505650575058505950605061506250635064506550665067506850695070507150725073507450755076507750785079508050815082508350845085508650875088508950905091509250935094509550965097509850995100510151025103510451055106510751085109511051115112511351145115511651175118511951205121512251235124512551265127512851295130513151325133513451355136513751385139514051415142514351445145514651475148514951505151515251535154515551565157515851595160516151625163516451655166516751685169517051715172517351745175517651775178517951805181518251835184518551865187518851895190519151925193519451955196519751985199520052015202520352045205520652075208520952105211521252135214521552165217521852195220522152225223522452255226522752285229523052315232523352345235523652375238523952405241524252435244524552465247524852495250525152525253525452555256525752585259526052615262526352645265526652675268526952705271527252735274527552765277527852795280528152825283528452855286528752885289529052915292529352945295529652975298529953005301530253035304530553065307530853095310531153125313531453155316531753185319532053215322532353245325532653275328532953305331533253335334533553365337533853395340534153425343534453455346534753485349535053515352535353545355535653575358535953605361536253635364536553665367536853695370537153725373537453755376537753785379538053815382538353845385538653875388538953905391539253935394539553965397539853995400540154025403540454055406540754085409541054115412541354145415541654175418541954205421542254235424542554265427542854295430543154325433543454355436543754385439544054415442544354445445544654475448544954505451545254535454545554565457545854595460546154625463546454655466546754685469547054715472547354745475547654775478547954805481548254835484548554865487548854895490549154925493549454955496549754985499550055015502550355045505550655075508550955105511551255135514551555165517551855195520552155225523552455255526552755285529553055315532553355345535553655375538553955405541554255435544554555465547554855495550555155525553555455555556555755585559556055615562556355645565556655675568556955705571557255735574557555765577557855795580558155825583558455855586558755885589559055915592559355945595559655975598559956005601560256035604560556065607560856095610561156125613561456155616561756185619562056215622562356245625562656275628562956305631563256335634563556365637563856395640564156425643564456455646564756485649565056515652565356545655565656575658565956605661566256635664566556665667566856695670567156725673567456755676567756785679568056815682568356845685568656875688568956905691569256935694569556965697569856995700570157025703570457055706570757085709571057115712571357145715571657175718571957205721572257235724572557265727572857295730573157325733573457355736573757385739574057415742574357445745574657475748574957505751575257535754575557565757575857595760576157625763576457655766576757685769577057715772577357745775577657775778577957805781578257835784578557865787578857895790579157925793579457955796579757985799580058015802580358045805580658075808580958105811581258135814581558165817581858195820582158225823582458255826582758285829583058315832583358345835583658375838583958405841584258435844584558465847584858495850585158525853585458555856585758585859586058615862586358645865586658675868586958705871587258735874587558765877587858795880588158825883588458855886588758885889589058915892589358945895589658975898589959005901590259035904590559065907590859095910591159125913591459155916591759185919592059215922592359245925592659275928592959305931593259335934593559365937593859395940594159425943594459455946594759485949595059515952595359545955595659575958595959605961596259635964596559665967596859695970597159725973597459755976597759785979598059815982598359845985598659875988598959905991599259935994599559965997599859996000600160026003600460056006600760086009601060116012601360146015601660176018601960206021602260236024602560266027602860296030603160326033603460356036603760386039604060416042604360446045604660476048604960506051605260536054605560566057605860596060606160626063606460656066606760686069607060716072607360746075607660776078607960806081608260836084608560866087608860896090609160926093609460956096609760986099610061016102610361046105610661076108610961106111611261136114611561166117611861196120612161226123612461256126612761286129613061316132613361346135613661376138613961406141614261436144614561466147614861496150615161526153615461556156615761586159616061616162616361646165616661676168616961706171617261736174617561766177617861796180618161826183618461856186618761886189619061916192619361946195619661976198619962006201620262036204620562066207620862096210621162126213621462156216621762186219622062216222622362246225622662276228622962306231623262336234623562366237623862396240624162426243624462456246624762486249625062516252625362546255625662576258625962606261626262636264626562666267626862696270627162726273627462756276627762786279628062816282628362846285628662876288628962906291629262936294629562966297629862996300630163026303630463056306630763086309631063116312631363146315631663176318631963206321632263236324632563266327632863296330633163326333633463356336633763386339634063416342634363446345634663476348634963506351635263536354635563566357635863596360636163626363636463656366636763686369637063716372637363746375637663776378637963806381638263836384638563866387638863896390639163926393639463956396639763986399640064016402640364046405640664076408640964106411641264136414641564166417641864196420642164226423642464256426642764286429643064316432643364346435643664376438643964406441644264436444644564466447644864496450645164526453645464556456645764586459646064616462646364646465646664676468646964706471647264736474647564766477647864796480648164826483648464856486648764886489649064916492649364946495649664976498649965006501650265036504650565066507650865096510651165126513651465156516651765186519652065216522652365246525652665276528652965306531653265336534653565366537653865396540654165426543654465456546654765486549655065516552655365546555655665576558655965606561656265636564656565666567656865696570657165726573657465756576657765786579658065816582658365846585658665876588658965906591659265936594659565966597659865996600660166026603660466056606660766086609661066116612661366146615661666176618661966206621662266236624662566266627662866296630663166326633663466356636663766386639664066416642664366446645664666476648664966506651665266536654665566566657665866596660666166626663666466656666666766686669667066716672667366746675667666776678667966806681668266836684668566866687668866896690669166926693669466956696669766986699670067016702670367046705670667076708670967106711671267136714671567166717671867196720672167226723672467256726672767286729673067316732673367346735673667376738673967406741674267436744674567466747674867496750675167526753675467556756675767586759676067616762676367646765676667676768676967706771677267736774677567766777677867796780678167826783678467856786678767886789679067916792679367946795679667976798679968006801680268036804680568066807680868096810681168126813681468156816681768186819682068216822682368246825682668276828682968306831683268336834683568366837683868396840684168426843684468456846684768486849685068516852685368546855685668576858685968606861686268636864686568666867686868696870687168726873687468756876687768786879688068816882688368846885688668876888688968906891689268936894689568966897689868996900690169026903690469056906690769086909691069116912691369146915691669176918691969206921692269236924692569266927692869296930693169326933693469356936693769386939694069416942694369446945694669476948694969506951695269536954695569566957695869596960696169626963696469656966696769686969697069716972697369746975697669776978697969806981698269836984698569866987698869896990699169926993699469956996699769986999700070017002700370047005700670077008700970107011701270137014701570167017701870197020702170227023702470257026702770287029703070317032703370347035703670377038703970407041704270437044704570467047704870497050705170527053705470557056705770587059706070617062706370647065706670677068706970707071707270737074707570767077707870797080708170827083708470857086708770887089709070917092709370947095709670977098709971007101710271037104710571067107710871097110711171127113711471157116711771187119712071217122712371247125712671277128712971307131713271337134713571367137713871397140714171427143714471457146714771487149715071517152715371547155715671577158715971607161716271637164716571667167716871697170717171727173717471757176717771787179718071817182718371847185718671877188718971907191719271937194719571967197719871997200720172027203720472057206720772087209721072117212721372147215721672177218721972207221722272237224722572267227722872297230723172327233723472357236723772387239724072417242724372447245724672477248724972507251725272537254725572567257725872597260726172627263726472657266726772687269727072717272727372747275727672777278727972807281728272837284728572867287728872897290729172927293729472957296729772987299730073017302730373047305730673077308730973107311731273137314731573167317731873197320732173227323732473257326732773287329733073317332733373347335733673377338733973407341734273437344734573467347734873497350735173527353735473557356735773587359736073617362736373647365736673677368736973707371737273737374737573767377737873797380738173827383738473857386738773887389739073917392739373947395739673977398739974007401740274037404740574067407740874097410741174127413741474157416741774187419742074217422742374247425742674277428742974307431743274337434743574367437743874397440744174427443744474457446744774487449745074517452745374547455745674577458745974607461746274637464746574667467746874697470747174727473747474757476747774787479748074817482748374847485748674877488748974907491749274937494749574967497749874997500750175027503750475057506750775087509751075117512751375147515751675177518751975207521752275237524752575267527752875297530753175327533753475357536753775387539754075417542754375447545754675477548754975507551755275537554755575567557755875597560756175627563756475657566756775687569757075717572757375747575757675777578757975807581758275837584758575867587758875897590759175927593759475957596759775987599760076017602760376047605760676077608760976107611761276137614761576167617761876197620762176227623762476257626762776287629763076317632763376347635763676377638763976407641764276437644764576467647764876497650765176527653765476557656765776587659766076617662766376647665766676677668766976707671767276737674767576767677767876797680768176827683768476857686768776887689769076917692769376947695769676977698769977007701770277037704770577067707770877097710771177127713771477157716771777187719772077217722772377247725772677277728772977307731773277337734773577367737773877397740774177427743774477457746774777487749775077517752775377547755775677577758775977607761776277637764776577667767776877697770777177727773777477757776777777787779778077817782778377847785778677877788778977907791779277937794779577967797779877997800780178027803780478057806780778087809781078117812781378147815781678177818781978207821782278237824782578267827782878297830783178327833783478357836783778387839784078417842784378447845784678477848784978507851785278537854785578567857785878597860786178627863786478657866786778687869787078717872787378747875787678777878787978807881788278837884788578867887788878897890789178927893789478957896789778987899790079017902790379047905790679077908790979107911791279137914791579167917791879197920792179227923792479257926792779287929793079317932793379347935793679377938793979407941794279437944794579467947794879497950795179527953795479557956795779587959796079617962796379647965796679677968796979707971797279737974797579767977797879797980798179827983798479857986798779887989799079917992799379947995799679977998799980008001800280038004800580068007800880098010801180128013801480158016801780188019802080218022802380248025802680278028802980308031803280338034803580368037803880398040804180428043804480458046804780488049805080518052805380548055805680578058805980608061806280638064806580668067806880698070807180728073807480758076807780788079808080818082808380848085808680878088808980908091809280938094809580968097809880998100810181028103810481058106810781088109811081118112811381148115811681178118811981208121812281238124812581268127812881298130813181328133813481358136813781388139814081418142814381448145814681478148814981508151815281538154815581568157815881598160816181628163816481658166816781688169817081718172817381748175817681778178817981808181818281838184818581868187818881898190819181928193819481958196819781988199820082018202820382048205820682078208820982108211821282138214821582168217821882198220822182228223822482258226822782288229823082318232823382348235823682378238823982408241824282438244824582468247824882498250825182528253825482558256825782588259826082618262826382648265826682678268826982708271827282738274827582768277827882798280828182828283828482858286828782888289829082918292829382948295829682978298829983008301830283038304830583068307830883098310831183128313831483158316831783188319832083218322832383248325832683278328832983308331833283338334833583368337833883398340834183428343834483458346834783488349835083518352835383548355835683578358835983608361836283638364836583668367836883698370837183728373837483758376837783788379838083818382838383848385838683878388838983908391839283938394839583968397839883998400840184028403840484058406840784088409841084118412841384148415841684178418841984208421842284238424842584268427842884298430843184328433843484358436843784388439844084418442844384448445844684478448844984508451845284538454845584568457845884598460846184628463846484658466846784688469847084718472847384748475847684778478847984808481848284838484848584868487848884898490849184928493849484958496849784988499850085018502850385048505850685078508850985108511851285138514851585168517851885198520852185228523852485258526852785288529853085318532853385348535853685378538853985408541854285438544854585468547854885498550855185528553855485558556855785588559856085618562856385648565856685678568856985708571857285738574857585768577857885798580858185828583858485858586858785888589859085918592859385948595859685978598859986008601860286038604860586068607860886098610861186128613861486158616861786188619862086218622862386248625862686278628862986308631863286338634863586368637863886398640864186428643864486458646864786488649865086518652865386548655865686578658865986608661866286638664866586668667866886698670867186728673867486758676867786788679868086818682868386848685868686878688868986908691869286938694869586968697869886998700870187028703870487058706870787088709871087118712871387148715871687178718871987208721872287238724872587268727872887298730873187328733873487358736873787388739874087418742874387448745874687478748874987508751875287538754875587568757875887598760876187628763876487658766876787688769877087718772877387748775877687778778877987808781878287838784878587868787878887898790879187928793879487958796879787988799880088018802880388048805880688078808880988108811881288138814881588168817881888198820882188228823882488258826882788288829883088318832883388348835883688378838883988408841884288438844884588468847884888498850885188528853885488558856885788588859886088618862886388648865886688678868886988708871887288738874887588768877887888798880888188828883888488858886888788888889889088918892889388948895889688978898889989008901890289038904890589068907890889098910891189128913891489158916891789188919892089218922892389248925892689278928892989308931893289338934893589368937893889398940894189428943894489458946894789488949895089518952895389548955895689578958895989608961896289638964896589668967896889698970897189728973897489758976897789788979898089818982898389848985898689878988898989908991899289938994899589968997899889999000900190029003900490059006900790089009901090119012901390149015901690179018901990209021902290239024902590269027902890299030903190329033903490359036903790389039904090419042904390449045904690479048904990509051905290539054905590569057905890599060906190629063906490659066906790689069907090719072907390749075907690779078907990809081908290839084908590869087908890899090909190929093909490959096909790989099910091019102910391049105910691079108910991109111911291139114911591169117911891199120912191229123912491259126912791289129913091319132913391349135913691379138913991409141914291439144914591469147914891499150915191529153915491559156915791589159916091619162916391649165916691679168916991709171917291739174917591769177917891799180918191829183918491859186918791889189919091919192919391949195919691979198919992009201920292039204920592069207920892099210921192129213921492159216921792189219922092219222922392249225922692279228922992309231923292339234923592369237923892399240924192429243924492459246924792489249925092519252925392549255925692579258925992609261926292639264926592669267926892699270927192729273927492759276927792789279928092819282928392849285928692879288928992909291929292939294929592969297929892999300930193029303930493059306930793089309931093119312931393149315931693179318931993209321932293239324932593269327932893299330933193329333933493359336933793389339934093419342934393449345934693479348934993509351935293539354935593569357935893599360936193629363936493659366936793689369937093719372937393749375937693779378937993809381938293839384938593869387938893899390939193929393939493959396939793989399940094019402940394049405940694079408940994109411941294139414941594169417941894199420942194229423942494259426942794289429943094319432943394349435943694379438943994409441944294439444944594469447944894499450945194529453945494559456945794589459946094619462946394649465946694679468946994709471947294739474947594769477947894799480948194829483948494859486948794889489949094919492949394949495949694979498949995009501950295039504950595069507950895099510951195129513951495159516951795189519952095219522952395249525952695279528952995309531953295339534953595369537953895399540954195429543954495459546954795489549955095519552955395549555955695579558955995609561956295639564956595669567956895699570957195729573957495759576957795789579958095819582958395849585958695879588958995909591959295939594959595969597959895999600960196029603960496059606960796089609961096119612961396149615961696179618961996209621962296239624962596269627962896299630963196329633963496359636963796389639964096419642964396449645964696479648964996509651965296539654965596569657965896599660966196629663966496659666966796689669967096719672967396749675967696779678967996809681968296839684968596869687968896899690969196929693969496959696969796989699970097019702970397049705970697079708970997109711971297139714971597169717971897199720972197229723972497259726972797289729973097319732973397349735973697379738973997409741974297439744974597469747974897499750975197529753975497559756975797589759976097619762976397649765976697679768976997709771977297739774977597769777977897799780978197829783978497859786978797889789979097919792979397949795979697979798979998009801980298039804980598069807980898099810981198129813981498159816981798189819982098219822982398249825982698279828982998309831983298339834983598369837983898399840984198429843984498459846984798489849985098519852985398549855985698579858985998609861986298639864986598669867986898699870987198729873987498759876987798789879988098819882988398849885988698879888988998909891989298939894989598969897989898999900990199029903990499059906990799089909991099119912991399149915991699179918991999209921992299239924992599269927992899299930993199329933993499359936993799389939994099419942994399449945994699479948994999509951995299539954995599569957995899599960996199629963996499659966996799689969997099719972997399749975997699779978997999809981998299839984998599869987998899899990999199929993999499959996999799989999100001000110002100031000410005100061000710008100091001010011100121001310014100151001610017100181001910020100211002210023100241002510026100271002810029100301003110032100331003410035100361003710038100391004010041100421004310044100451004610047100481004910050100511005210053100541005510056100571005810059100601006110062100631006410065100661006710068100691007010071100721007310074100751007610077100781007910080100811008210083100841008510086100871008810089100901009110092100931009410095100961009710098100991010010101101021010310104101051010610107101081010910110101111011210113101141011510116101171011810119101201012110122101231012410125101261012710128101291013010131101321013310134101351013610137101381013910140101411014210143101441014510146101471014810149101501015110152101531015410155101561015710158101591016010161101621016310164101651016610167101681016910170101711017210173101741017510176101771017810179101801018110182101831018410185101861018710188101891019010191101921019310194101951019610197101981019910200102011020210203102041020510206102071020810209102101021110212102131021410215102161021710218102191022010221102221022310224102251022610227102281022910230102311023210233102341023510236102371023810239102401024110242102431024410245102461024710248102491025010251102521025310254102551025610257102581025910260102611026210263102641026510266102671026810269102701027110272102731027410275102761027710278102791028010281102821028310284102851028610287102881028910290102911029210293102941029510296102971029810299103001030110302103031030410305103061030710308103091031010311103121031310314103151031610317103181031910320103211032210323103241032510326103271032810329103301033110332103331033410335103361033710338103391034010341103421034310344103451034610347103481034910350103511035210353103541035510356103571035810359103601036110362103631036410365103661036710368103691037010371103721037310374103751037610377103781037910380103811038210383103841038510386103871038810389103901039110392103931039410395103961039710398103991040010401104021040310404104051040610407104081040910410104111041210413104141041510416104171041810419104201042110422104231042410425104261042710428104291043010431104321043310434104351043610437104381043910440104411044210443104441044510446104471044810449104501045110452104531045410455104561045710458104591046010461104621046310464104651046610467104681046910470104711047210473104741047510476104771047810479104801048110482104831048410485104861048710488104891049010491104921049310494104951049610497104981049910500105011050210503105041050510506105071050810509105101051110512105131051410515105161051710518105191052010521105221052310524105251052610527105281052910530105311053210533105341053510536105371053810539105401054110542105431054410545105461054710548105491055010551105521055310554105551055610557105581055910560105611056210563105641056510566105671056810569105701057110572105731057410575105761057710578105791058010581105821058310584105851058610587105881058910590105911059210593105941059510596105971059810599106001060110602106031060410605106061060710608106091061010611106121061310614106151061610617106181061910620106211062210623106241062510626106271062810629106301063110632106331063410635106361063710638106391064010641106421064310644106451064610647106481064910650106511065210653106541065510656106571065810659106601066110662106631066410665106661066710668106691067010671106721067310674106751067610677106781067910680106811068210683106841068510686106871068810689106901069110692106931069410695106961069710698106991070010701107021070310704107051070610707107081070910710107111071210713107141071510716107171071810719107201072110722107231072410725107261072710728107291073010731107321073310734107351073610737107381073910740107411074210743107441074510746107471074810749107501075110752107531075410755107561075710758107591076010761107621076310764107651076610767107681076910770107711077210773107741077510776107771077810779107801078110782107831078410785107861078710788107891079010791107921079310794107951079610797107981079910800108011080210803108041080510806108071080810809108101081110812108131081410815108161081710818108191082010821108221082310824108251082610827108281082910830108311083210833108341083510836108371083810839108401084110842108431084410845108461084710848108491085010851108521085310854108551085610857108581085910860108611086210863108641086510866108671086810869108701087110872108731087410875108761087710878108791088010881108821088310884108851088610887108881088910890108911089210893108941089510896108971089810899109001090110902109031090410905109061090710908109091091010911109121091310914109151091610917109181091910920109211092210923109241092510926109271092810929109301093110932109331093410935109361093710938109391094010941109421094310944109451094610947109481094910950109511095210953109541095510956109571095810959109601096110962109631096410965109661096710968109691097010971109721097310974109751097610977109781097910980109811098210983109841098510986109871098810989109901099110992109931099410995109961099710998109991100011001110021100311004110051100611007110081100911010110111101211013110141101511016110171101811019110201102111022110231102411025110261102711028110291103011031110321103311034110351103611037110381103911040110411104211043110441104511046110471104811049110501105111052110531105411055110561105711058110591106011061110621106311064110651106611067110681106911070110711107211073110741107511076110771107811079110801108111082110831108411085110861108711088110891109011091110921109311094110951109611097110981109911100111011110211103111041110511106111071110811109111101111111112111131111411115111161111711118111191112011121111221112311124111251112611127111281112911130111311113211133111341113511136111371113811139111401114111142111431114411145111461114711148111491115011151111521115311154111551115611157111581115911160111611116211163111641116511166111671116811169111701117111172111731117411175111761117711178111791118011181111821118311184111851118611187111881118911190111911119211193111941119511196111971119811199112001120111202112031120411205112061120711208112091121011211112121121311214112151121611217112181121911220112211122211223112241122511226112271122811229112301123111232112331123411235112361123711238112391124011241112421124311244112451124611247112481124911250112511125211253112541125511256112571125811259112601126111262112631126411265112661126711268112691127011271112721127311274112751127611277112781127911280112811128211283112841128511286112871128811289112901129111292112931129411295112961129711298112991130011301113021130311304113051130611307113081130911310113111131211313113141131511316113171131811319113201132111322113231132411325113261132711328113291133011331113321133311334113351133611337113381133911340113411134211343113441134511346113471134811349113501135111352113531135411355113561135711358113591136011361113621136311364113651136611367113681136911370113711137211373113741137511376113771137811379113801138111382113831138411385113861138711388113891139011391113921139311394113951139611397113981139911400114011140211403114041140511406114071140811409114101141111412114131141411415114161141711418114191142011421114221142311424114251142611427114281142911430114311143211433114341143511436114371143811439114401144111442114431144411445114461144711448114491145011451114521145311454114551145611457114581145911460114611146211463114641146511466114671146811469114701147111472114731147411475114761147711478114791148011481114821148311484114851148611487114881148911490114911149211493114941149511496114971149811499115001150111502115031150411505115061150711508115091151011511115121151311514115151151611517115181151911520115211152211523115241152511526115271152811529115301153111532115331153411535115361153711538115391154011541115421154311544115451154611547115481154911550115511155211553115541155511556115571155811559115601156111562115631156411565115661156711568115691157011571115721157311574115751157611577115781157911580115811158211583115841158511586115871158811589115901159111592115931159411595115961159711598115991160011601116021160311604116051160611607116081160911610116111161211613116141161511616116171161811619116201162111622116231162411625116261162711628116291163011631116321163311634116351163611637116381163911640116411164211643116441164511646116471164811649116501165111652116531165411655116561165711658116591166011661116621166311664116651166611667116681166911670116711167211673116741167511676116771167811679116801168111682116831168411685116861168711688116891169011691116921169311694116951169611697116981169911700117011170211703117041170511706117071170811709117101171111712117131171411715117161171711718117191172011721117221172311724117251172611727117281172911730117311173211733117341173511736117371173811739117401174111742117431174411745117461174711748117491175011751117521175311754117551175611757117581175911760117611176211763117641176511766117671176811769117701177111772117731177411775117761177711778117791178011781117821178311784117851178611787117881178911790117911179211793117941179511796117971179811799118001180111802118031180411805118061180711808118091181011811118121181311814118151181611817118181181911820118211182211823118241182511826118271182811829118301183111832118331183411835118361183711838118391184011841118421184311844118451184611847118481184911850118511185211853118541185511856118571185811859118601186111862118631186411865118661186711868118691187011871118721187311874118751187611877118781187911880118811188211883118841188511886118871188811889118901189111892118931189411895118961189711898118991190011901119021190311904119051190611907119081190911910119111191211913119141191511916119171191811919119201192111922119231192411925119261192711928119291193011931119321193311934119351193611937119381193911940119411194211943119441194511946119471194811949119501195111952119531195411955119561195711958119591196011961119621196311964119651196611967119681196911970119711197211973119741197511976119771197811979119801198111982119831198411985119861198711988119891199011991119921199311994119951199611997119981199912000120011200212003120041200512006120071200812009120101201112012120131201412015120161201712018120191202012021120221202312024120251202612027120281202912030120311203212033120341203512036120371203812039120401204112042120431204412045120461204712048120491205012051120521205312054120551205612057120581205912060120611206212063120641206512066120671206812069120701207112072120731207412075120761207712078120791208012081120821208312084120851208612087120881208912090120911209212093120941209512096120971209812099121001210112102121031210412105121061210712108121091211012111121121211312114121151211612117121181211912120121211212212123121241212512126121271212812129121301213112132121331213412135121361213712138121391214012141121421214312144121451214612147121481214912150121511215212153121541215512156121571215812159121601216112162121631216412165121661216712168121691217012171121721217312174121751217612177121781217912180121811218212183121841218512186121871218812189121901219112192121931219412195121961219712198121991220012201122021220312204122051220612207122081220912210122111221212213122141221512216122171221812219122201222112222122231222412225122261222712228122291223012231122321223312234122351223612237122381223912240122411224212243122441224512246122471224812249122501225112252122531225412255122561225712258122591226012261122621226312264122651226612267122681226912270122711227212273122741227512276122771227812279122801228112282122831228412285122861228712288122891229012291122921229312294122951229612297122981229912300123011230212303123041230512306123071230812309123101231112312123131231412315123161231712318123191232012321123221232312324123251232612327123281232912330123311233212333123341233512336123371233812339123401234112342123431234412345123461234712348123491235012351123521235312354123551235612357123581235912360123611236212363123641236512366123671236812369123701237112372123731237412375123761237712378123791238012381123821238312384123851238612387123881238912390123911239212393123941239512396123971239812399124001240112402124031240412405124061240712408124091241012411124121241312414124151241612417124181241912420124211242212423124241242512426124271242812429124301243112432124331243412435124361243712438124391244012441124421244312444124451244612447124481244912450124511245212453124541245512456124571245812459124601246112462124631246412465124661246712468124691247012471124721247312474124751247612477124781247912480124811248212483124841248512486124871248812489124901249112492124931249412495124961249712498124991250012501125021250312504125051250612507125081250912510125111251212513125141251512516125171251812519125201252112522125231252412525125261252712528125291253012531125321253312534125351253612537125381253912540125411254212543125441254512546125471254812549125501255112552125531255412555125561255712558125591256012561125621256312564125651256612567125681256912570125711257212573125741257512576125771257812579125801258112582125831258412585125861258712588125891259012591125921259312594125951259612597125981259912600126011260212603126041260512606126071260812609126101261112612126131261412615126161261712618126191262012621126221262312624126251262612627126281262912630126311263212633126341263512636126371263812639126401264112642126431264412645126461264712648126491265012651126521265312654126551265612657126581265912660126611266212663126641266512666126671266812669126701267112672126731267412675126761267712678126791268012681126821268312684126851268612687126881268912690126911269212693126941269512696126971269812699127001270112702127031270412705127061270712708127091271012711127121271312714127151271612717127181271912720127211272212723127241272512726127271272812729127301273112732127331273412735127361273712738127391274012741127421274312744127451274612747127481274912750127511275212753127541275512756127571275812759127601276112762127631276412765127661276712768127691277012771127721277312774127751277612777127781277912780127811278212783127841278512786127871278812789127901279112792127931279412795127961279712798127991280012801128021280312804128051280612807128081280912810128111281212813128141281512816128171281812819128201282112822128231282412825128261282712828128291283012831128321283312834128351283612837128381283912840128411284212843128441284512846128471284812849128501285112852128531285412855128561285712858128591286012861128621286312864128651286612867128681286912870128711287212873128741287512876128771287812879128801288112882128831288412885128861288712888128891289012891128921289312894128951289612897128981289912900129011290212903129041290512906129071290812909129101291112912129131291412915129161291712918129191292012921129221292312924129251292612927129281292912930129311293212933129341293512936129371293812939129401294112942129431294412945129461294712948129491295012951129521295312954129551295612957129581295912960129611296212963129641296512966129671296812969129701297112972129731297412975129761297712978129791298012981129821298312984129851298612987129881298912990129911299212993129941299512996129971299812999130001300113002130031300413005130061300713008130091301013011130121301313014130151301613017130181301913020130211302213023130241302513026130271302813029130301303113032130331303413035130361303713038130391304013041130421304313044130451304613047130481304913050130511305213053130541305513056130571305813059130601306113062130631306413065130661306713068130691307013071130721307313074130751307613077130781307913080130811308213083130841308513086130871308813089130901309113092130931309413095130961309713098130991310013101131021310313104131051310613107131081310913110131111311213113131141311513116131171311813119131201312113122131231312413125131261312713128131291313013131131321313313134131351313613137131381313913140131411314213143131441314513146131471314813149131501315113152131531315413155131561315713158131591316013161131621316313164131651316613167131681316913170131711317213173131741317513176131771317813179131801318113182131831318413185131861318713188131891319013191131921319313194131951319613197131981319913200132011320213203132041320513206132071320813209132101321113212132131321413215132161321713218132191322013221132221322313224132251322613227132281322913230132311323213233132341323513236132371323813239132401324113242132431324413245132461324713248132491325013251132521325313254132551325613257132581325913260132611326213263132641326513266132671326813269132701327113272132731327413275132761327713278132791328013281132821328313284132851328613287132881328913290132911329213293132941329513296132971329813299133001330113302133031330413305133061330713308133091331013311133121331313314133151331613317133181331913320133211332213323133241332513326133271332813329133301333113332133331333413335133361333713338133391334013341133421334313344133451334613347133481334913350133511335213353133541335513356133571335813359133601336113362133631336413365133661336713368133691337013371133721337313374133751337613377133781337913380133811338213383133841338513386133871338813389133901339113392133931339413395133961339713398133991340013401134021340313404134051340613407134081340913410134111341213413134141341513416134171341813419134201342113422134231342413425134261342713428134291343013431134321343313434134351343613437134381343913440134411344213443134441344513446134471344813449134501345113452134531345413455134561345713458134591346013461134621346313464134651346613467134681346913470134711347213473134741347513476134771347813479134801348113482134831348413485134861348713488134891349013491134921349313494134951349613497134981349913500135011350213503135041350513506135071350813509135101351113512135131351413515135161351713518135191352013521135221352313524135251352613527135281352913530135311353213533135341353513536135371353813539135401354113542135431354413545135461354713548135491355013551135521355313554135551355613557135581355913560135611356213563135641356513566135671356813569135701357113572135731357413575135761357713578135791358013581135821358313584135851358613587135881358913590135911359213593135941359513596135971359813599136001360113602136031360413605136061360713608136091361013611136121361313614136151361613617136181361913620136211362213623136241362513626136271362813629136301363113632136331363413635136361363713638136391364013641 |
- <HTML><HEAD>
- <TITLE>BASH(1) Manual Page</TITLE>
- </HEAD>
- <BODY><TABLE WIDTH=100%>
- <TR>
- <TH ALIGN=LEFT width=33%>BASH(1)<TH ALIGN=CENTER width=33%>2016 August 26<TH ALIGN=RIGHT width=33%>BASH(1)
- </TR>
- </TABLE>
- <BR><A HREF="#index">Index</A>
- <HR>
- <A NAME="lbAB"> </A>
- <H3>NAME</H3>
- bash - GNU Bourne-Again SHell
- <A NAME="lbAC"> </A>
- <H3>SYNOPSIS</H3>
- <B>bash</B>
- [options]
- [command_string | file]
- <A NAME="lbAD"> </A>
- <H3>COPYRIGHT</H3>
- Bash is Copyright © 1989-2016 by the Free Software Foundation, Inc.
- <A NAME="lbAE"> </A>
- <H3>DESCRIPTION</H3>
- <B>Bash</B>
- is an <B>sh</B>-compatible command language interpreter that
- executes commands read from the standard input or from a file.
- <B>Bash</B>
- also incorporates useful features from the <I>Korn</I> and <I>C</I>
- shells (<B>ksh</B> and <B>csh</B>).
- <P>
- <B>Bash</B>
- is intended to be a conformant implementation of the
- Shell and Utilities portion of the IEEE POSIX specification
- (IEEE Standard 1003.1).
- <B>Bash</B>
- can be configured to be POSIX-conformant by default.
- <A NAME="lbAF"> </A>
- <H3>OPTIONS</H3>
- All of the single-character shell options documented in the
- description of the <B>set</B> builtin command can be used as options
- when the shell is invoked.
- In addition, <B>bash</B>
- interprets the following options when it is invoked:
- <P>
- <DL COMPACT>
- <DT><B>-c</B>
- <DD>
- If the
- <B>-c</B>
- option is present, then commands are read from the first non-option argument
- <I>command_string</I>.
- If there are arguments after the
- <I>command_string</I>,
- the first argument is assigned to
- <B>$0</B>
- and any remaining arguments are assigned to the positional parameters.
- The assignment to
- <B>$0</B>
- sets the name of the shell, which is used in warning and error messages.
- <DT><B>-i</B>
- <DD>
- If the
- <B>-i</B>
- option is present, the shell is
- <I>interactive</I>.
- <DT><B>-l</B>
- <DD>
- Make
- <B>bash</B>
- act as if it had been invoked as a login shell (see
- <FONT SIZE=-1><B>INVOCATION</B>
- </FONT>
- below).
- <DT><B>-r</B>
- <DD>
- If the
- <B>-r</B>
- option is present, the shell becomes
- <I>restricted</I>
- (see
- <FONT SIZE=-1><B>RESTRICTED SHELL</B>
- </FONT>
- below).
- <DT><B>-s</B>
- <DD>
- If the
- <B>-s</B>
- option is present, or if no arguments remain after option
- processing, then commands are read from the standard input.
- This option allows the positional parameters to be set
- when invoking an interactive shell.
- <DT><B>-D</B>
- <DD>
- A list of all double-quoted strings preceded by <B>$</B>
- is printed on the standard output.
- These are the strings that
- are subject to language translation when the current locale
- is not <B>C</B> or <B>POSIX</B>.
- This implies the <B>-n</B> option; no commands will be executed.
- <DT><B>[-+]O [</B><I>shopt_option</I>]
- <DD>
- <I>shopt_option</I> is one of the shell options accepted by the
- <B>shopt</B> builtin (see
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below).
- If <I>shopt_option</I> is present, <B>-O</B> sets the value of that option;
- <B>+O</B> unsets it.
- If <I>shopt_option</I> is not supplied, the names and values of the shell
- options accepted by <B>shopt</B> are printed on the standard output.
- If the invocation option is <B>+O</B>, the output is displayed in a format
- that may be reused as input.
- <DT><B>--</B>
- <DD>
- A
- <B>--</B>
- signals the end of options and disables further option processing.
- Any arguments after the
- <B>--</B>
- are treated as filenames and arguments. An argument of
- <B>-</B>
- is equivalent to <B>--</B>.
- </DL>
- <P>
- <B>Bash</B>
- also interprets a number of multi-character options.
- These options must appear on the command line before the
- single-character options to be recognized.
- <P>
- <DL COMPACT>
- <DT><B>--debugger</B>
- <DD>
- Arrange for the debugger profile to be executed before the shell
- starts.
- Turns on extended debugging mode (see the description of the
- <B>extdebug</B>
- option to the
- <B>shopt</B>
- builtin below).
- <DT><B>--dump-po-strings</B>
- <DD>
- Equivalent to <B>-D</B>, but the output is in the GNU <I>gettext</I>
- <B>po</B> (portable object) file format.
- <DT><B>--dump-strings</B>
- <DD>
- Equivalent to <B>-D</B>.
- <DT><B>--help</B>
- <DD>
- Display a usage message on standard output and exit successfully.
- <DT><B>--init-file</B> <I>file</I><DD>
- <DT><B>--rcfile</B> <I>file</I><DD>
- Execute commands from
- <I>file</I>
- instead of the standard personal initialization file
- <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A>
- if the shell is interactive (see
- <FONT SIZE=-1><B>INVOCATION</B>
- </FONT>
- below).
- <DT><B>--login</B>
- <DD>
- Equivalent to <B>-l</B>.
- <DT><B>--noediting</B>
- <DD>
- Do not use the GNU
- <B>readline</B>
- library to read command lines when the shell is interactive.
- <DT><B>--noprofile</B>
- <DD>
- Do not read either the system-wide startup file
- <A HREF="file:/etc/profile"><I>/etc/profile</I></A>
- or any of the personal initialization files
- <A HREF="file:~/.bash_profile"><I>~/.bash_profile</I></A>,
- <A HREF="file:~/.bash_login"><I>~/.bash_login</I></A>,
- or
- <A HREF="file:~/.profile"><I>~/.profile</I></A>.
- By default,
- <B>bash</B>
- reads these files when it is invoked as a login shell (see
- <FONT SIZE=-1><B>INVOCATION</B>
- </FONT>
- below).
- <DT><B>--norc</B>
- <DD>
- Do not read and execute the personal initialization file
- <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A>
- if the shell is interactive.
- This option is on by default if the shell is invoked as
- <B>sh</B>.
- <DT><B>--posix</B>
- <DD>
- Change the behavior of <B>bash</B> where the default operation differs
- from the POSIX standard to match the standard (<I>posix mode</I>).
- See
- <FONT SIZE=-1><B>SEE ALSO</B>
- </FONT>
- below for a reference to a document that details how posix mode affects
- bash's behavior.
- <DT><B>--restricted</B>
- <DD>
- The shell becomes restricted (see
- <FONT SIZE=-1><B>RESTRICTED SHELL</B>
- </FONT>
- below).
- <DT><B>--verbose</B>
- <DD>
- Equivalent to <B>-v</B>.
- <DT><B>--version</B>
- <DD>
- Show version information for this instance of
- <B>bash</B>
- on the standard output and exit successfully.
- </DL>
- <A NAME="lbAG"> </A>
- <H3>ARGUMENTS</H3>
- If arguments remain after option processing, and neither the
- <B>-c</B>
- nor the
- <B>-s</B>
- option has been supplied, the first argument is assumed to
- be the name of a file containing shell commands.
- If
- <B>bash</B>
- is invoked in this fashion,
- <B>$0</B>
- is set to the name of the file, and the positional parameters
- are set to the remaining arguments.
- <B>Bash</B>
- reads and executes commands from this file, then exits.
- <B>Bash</B>'s exit status is the exit status of the last command
- executed in the script.
- If no commands are executed, the exit status is 0.
- An attempt is first made to open the file in the current directory, and,
- if no file is found, then the shell searches the directories in
- <FONT SIZE=-1><B>PATH</B>
- </FONT>
- for the script.
- <A NAME="lbAH"> </A>
- <H3>INVOCATION</H3>
- A <I>login shell</I> is one whose first character of argument zero is a
- <B>-</B>,
- or one started with the
- <B>--login</B>
- option.
- <P>
- An <I>interactive</I> shell is one started without non-option arguments
- (unless <B>-s</B> is specified)
- and without the
- <B>-c</B>
- option
- whose standard input and error are
- both connected to terminals (as determined by
- <I>isatty</I>(3)),
- or one started with the
- <B>-i</B>
- option.
- <FONT SIZE=-1><B>PS1</B>
- </FONT>
- is set and
- <B>$-</B>
- includes
- <B>i</B>
- if
- <B>bash</B>
- is interactive,
- allowing a shell script or a startup file to test this state.
- <P>
- The following paragraphs describe how
- <B>bash</B>
- executes its startup files.
- If any of the files exist but cannot be read,
- <B>bash</B>
- reports an error.
- Tildes are expanded in filenames as described below under
- <B>Tilde Expansion</B>
- in the
- <FONT SIZE=-1><B>EXPANSION</B>
- </FONT>
- section.
- <P>
- When
- <B>bash</B>
- is invoked as an interactive login shell, or as a non-interactive shell
- with the <B>--login</B> option, it first reads and
- executes commands from the file <A HREF="file:/etc/profile"><I>/etc/profile</I></A>, if that
- file exists.
- After reading that file, it looks for <A HREF="file:~/.bash_profile"><I>~/.bash_profile</I></A>,
- <A HREF="file:~/.bash_login"><I>~/.bash_login</I></A>, and <A HREF="file:~/.profile"><I>~/.profile</I></A>, in that order, and reads
- and executes commands from the first one that exists and is readable.
- The
- <B>--noprofile</B>
- option may be used when the shell is started to inhibit this behavior.
- <P>
- When an interactive login shell exits,
- or a non-interactive login shell executes the <B>exit</B> builtin command,
- <B>bash</B>
- reads and executes commands from the file <A HREF="file:~/.bash_logout"><I>~/.bash_logout</I></A>, if it
- exists.
- <P>
- When an interactive shell that is not a login shell is started,
- <B>bash</B>
- reads and executes commands from <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A>, if that file exists.
- This may be inhibited by using the
- <B>--norc</B>
- option.
- The <B>--rcfile</B> <I>file</I> option will force
- <B>bash</B>
- to read and execute commands from <I>file</I> instead of <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A>.
- <P>
- When
- <B>bash</B>
- is started non-interactively, to run a shell script, for example, it
- looks for the variable
- <FONT SIZE=-1><B>BASH_ENV</B>
- </FONT>
- in the environment, expands its value if it appears there, and uses the
- expanded value as the name of a file to read and execute.
- <B>Bash</B>
- behaves as if the following command were executed:
- <P>
- <DL COMPACT><DT><DD>
- <TT>if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi</TT>
- </DL>
- <P>
- but the value of the
- <FONT SIZE=-1><B>PATH</B>
- </FONT>
- variable is not used to search for the filename.
- <P>
- If
- <B>bash</B>
- is invoked with the name
- <B>sh</B>,
- it tries to mimic the startup behavior of historical versions of
- <B>sh</B>
- as closely as possible,
- while conforming to the POSIX standard as well.
- When invoked as an interactive login shell, or a non-interactive
- shell with the <B>--login</B> option, it first attempts to
- read and execute commands from
- <A HREF="file:/etc/profile"><I>/etc/profile</I></A>
- and
- <A HREF="file:~/.profile"><I>~/.profile</I></A>,
- in that order.
- The
- <B>--noprofile</B>
- option may be used to inhibit this behavior.
- When invoked as an interactive shell with the name
- <B>sh</B>,
- <B>bash</B>
- looks for the variable
- <FONT SIZE=-1><B>ENV</B>,
- </FONT>
- expands its value if it is defined, and uses the
- expanded value as the name of a file to read and execute.
- Since a shell invoked as
- <B>sh</B>
- does not attempt to read and execute commands from any other startup
- files, the
- <B>--rcfile</B>
- option has no effect.
- A non-interactive shell invoked with the name
- <B>sh</B>
- does not attempt to read any other startup files.
- When invoked as
- <B>sh</B>,
- <B>bash</B>
- enters
- <I>posix</I>
- mode after the startup files are read.
- <P>
- When
- <B>bash</B>
- is started in
- <I>posix</I>
- mode, as with the
- <B>--posix</B>
- command line option, it follows the POSIX standard for startup files.
- In this mode, interactive shells expand the
- <FONT SIZE=-1><B>ENV</B>
- </FONT>
- variable and commands are read and executed from the file
- whose name is the expanded value.
- No other startup files are read.
- <P>
- <B>Bash</B>
- attempts to determine when it is being run with its standard input
- connected to a network connection, as when executed by the remote shell
- daemon, usually <I>rshd</I>, or the secure shell daemon <I>sshd</I>.
- If
- <B>bash</B>
- determines it is being run in this fashion, it reads and executes
- commands from <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A>, if that file exists and is readable.
- It will not do this if invoked as <B>sh</B>.
- The
- <B>--norc</B>
- option may be used to inhibit this behavior, and the
- <B>--rcfile</B>
- option may be used to force another file to be read, but neither
- <I>rshd</I> nor <I>sshd</I> generally invoke the shell with those options
- or allow them to be specified.
- <P>
- If the shell is started with the effective user (group) id not equal to the
- real user (group) id, and the <B>-p</B> option is not supplied, no startup
- files are read, shell functions are not inherited from the environment, the
- <FONT SIZE=-1><B>SHELLOPTS</B>,
- </FONT>
- <FONT SIZE=-1><B>BASHOPTS</B>,
- </FONT>
- <FONT SIZE=-1><B>CDPATH</B>,
- </FONT>
- and
- <FONT SIZE=-1><B>GLOBIGNORE</B>
- </FONT>
- variables, if they appear in the environment, are ignored,
- and the effective user id is set to the real user id.
- If the <B>-p</B> option is supplied at invocation, the startup behavior is
- the same, but the effective user id is not reset.
- <A NAME="lbAI"> </A>
- <H3>DEFINITIONS</H3>
- <P>
- The following definitions are used throughout the rest of this
- document.
- <DL COMPACT>
- <DT><B>blank</B>
- <DD>
- A space or tab.
- <DT><B>word</B>
- <DD>
- A sequence of characters considered as a single unit by the shell.
- Also known as a
- <B>token</B>.
- <DT><B>name</B>
- <DD>
- A
- <I>word</I>
- consisting only of alphanumeric characters and underscores, and
- beginning with an alphabetic character or an underscore. Also
- referred to as an
- <B>identifier</B>.
- <DT><B>metacharacter</B>
- <DD>
- A character that, when unquoted, separates words. One of the following:
- <BR>
- <DL COMPACT><DT><DD>
- <P>
- <B>| & ; ( ) < > space tab newline</B>
- </DL>
- </DL>
- <P>
- <DL COMPACT>
- <DT><B>control operator</B>
- <DD>
- A <I>token</I> that performs a control function. It is one of the following
- symbols:
- <DL COMPACT><DT><DD>
- <P>
- <B>|| & && ; ;; ;& ;;& ( ) | |& <newline></B>
- </DL>
- </DL>
- <A NAME="lbAJ"> </A>
- <H3>RESERVED WORDS</H3>
- <I>Reserved words</I> are words that have a special meaning to the shell.
- The following words are recognized as reserved when unquoted and either
- the first word of a simple command (see
- <FONT SIZE=-1><B>SHELL GRAMMAR</B>
- </FONT>
- below) or the third word of a
- <B>case</B>
- or
- <B>for</B>
- command:
- <DL COMPACT><DT><DD>
- <P>
- <B>
- </B>
- ! case coproc do done elif else esac fi for function if in select then until while { } time [[ ]]
- </DL>
- <A NAME="lbAK"> </A>
- <H3>SHELL GRAMMAR</H3>
- <A NAME="lbAL"> </A>
- <H4>Simple Commands</H4>
- <P>
- A <I>simple command</I> is a sequence of optional variable assignments
- followed by <B>blank</B>-separated words and redirections, and
- terminated by a <I>control operator</I>. The first word
- specifies the command to be executed, and is passed as argument zero.
- The remaining words are passed as arguments to the invoked command.
- <P>
- The return value of a <I>simple command</I> is its exit status, or
- 128+<I>n</I> if the command is terminated by signal
- <I>n</I>.
- <A NAME="lbAM"> </A>
- <H4>Pipelines</H4>
- <P>
- A <I>pipeline</I> is a sequence of one or more commands separated by
- one of the control operators
- <B>|</B>
- or <B>|&</B>.
- The format for a pipeline is:
- <DL COMPACT><DT><DD>
- <P>
- [<B>time</B> [<B>-p</B>]] [ ! ] <I>command</I> [ [<B>|</B>|<B>|&</B>] <I>command2</I> ... ]
- </DL>
- <P>
- The standard output of
- <I>command</I>
- is connected via a pipe to the standard input of
- <I>command2</I>.
- This connection is performed before any redirections specified by the
- command (see
- <FONT SIZE=-1><B>REDIRECTION</B>
- </FONT>
- below).
- If <B>|&</B> is used, <I>command</I>'s standard error, in addition to its
- standard output, is connected to
- <I>command2</I>'s standard input through the pipe;
- it is shorthand for <B>2>&1 |</B>.
- This implicit redirection of the standard error to the standard output is
- performed after any redirections specified by the command.
- <P>
- The return status of a pipeline is the exit status of the last
- command, unless the <B>pipefail</B> option is enabled.
- If <B>pipefail</B> is enabled, the pipeline's return status is the
- value of the last (rightmost) command to exit with a non-zero status,
- or zero if all commands exit successfully.
- If the reserved word
- <B>!</B>
- precedes a pipeline, the exit status of that pipeline is the logical
- negation of the exit status as described above.
- The shell waits for all commands in the pipeline to
- terminate before returning a value.
- <P>
- If the
- <B>time</B>
- reserved word precedes a pipeline, the elapsed as well as user and
- system time consumed by its execution are reported when the pipeline
- terminates.
- The <B>-p</B> option changes the output format to that specified by POSIX.
- When the shell is in <I>posix mode</I>, it does not recognize
- <B>time</B> as a reserved word if the next token begins with a `-'.
- The
- <FONT SIZE=-1><B>TIMEFORMAT</B>
- </FONT>
- variable may be set to a format string that specifies how the timing
- information should be displayed; see the description of
- <FONT SIZE=-1><B>TIMEFORMAT</B>
- </FONT>
- under
- <B>Shell Variables</B>
- below.
- <P>
- When the shell is in <I>posix mode</I>, <B>time</B>
- may be followed by a newline. In this case, the shell displays the
- total user and system time consumed by the shell and its children.
- The
- <FONT SIZE=-1><B>TIMEFORMAT</B>
- </FONT>
- variable may be used to specify the format of
- the time information.
- <P>
- Each command in a pipeline is executed as a separate process (i.e., in a
- subshell).
- <A NAME="lbAN"> </A>
- <H4>Lists</H4>
- <P>
- A <I>list</I> is a sequence of one or more pipelines separated by one
- of the operators
- <B>;</B>,
- <B>&</B>,
- <B>&&</B>,
- or
- <B>||</B>,
- and optionally terminated by one of
- <B>;</B>,
- <B>&</B>,
- or
- <B><newline></B>.
- <P>
- Of these list operators,
- <B>&&</B>
- and
- <B>||</B>
- have equal precedence, followed by
- <B>;</B>
- and
- <B>&</B>,
- which have equal precedence.
- <P>
- A sequence of one or more newlines may appear in a <I>list</I> instead
- of a semicolon to delimit commands.
- <P>
- If a command is terminated by the control operator
- <B>&</B>,
- the shell executes the command in the <I>background</I>
- in a subshell. The shell does not wait for the command to
- finish, and the return status is 0. Commands separated by a
- <B>;</B>
- are executed sequentially; the shell waits for each
- command to terminate in turn. The return status is the
- exit status of the last command executed.
- <P>
- AND and OR lists are sequences of one or more pipelines separated by the
- <B>&&</B> and <B>||</B> control operators, respectively.
- AND and OR lists are executed with left associativity.
- An AND list has the form
- <DL COMPACT><DT><DD>
- <P>
- <I>command1</I> <B>&&</B> <I>command2</I>
- </DL>
- <P>
- <I>command2</I>
- is executed if, and only if,
- <I>command1</I>
- returns an exit status of zero.
- <P>
- An OR list has the form
- <DL COMPACT><DT><DD>
- <P>
- <I>command1</I> <B>||</B> <I>command2</I>
- <P>
- </DL>
- <P>
- <I>command2</I>
- is executed if and only if
- <I>command1</I>
- returns a non-zero exit status.
- The return status of
- AND and OR lists is the exit status of the last command
- executed in the list.
- <A NAME="lbAO"> </A>
- <H4>Compound Commands</H4>
- <P>
- A <I>compound command</I> is one of the following.
- In most cases a <I>list</I> in a command's description may be separated from
- the rest of the command by one or more newlines, and may be followed by a
- newline in place of a semicolon.
- <DL COMPACT>
- <DT>(<I>list</I>)<DD>
- <I>list</I> is executed in a subshell environment (see
- <FONT SIZE=-1><B>COMMAND EXECUTION ENVIRONMENT</B></FONT>
- below).
- Variable assignments and builtin
- commands that affect the shell's environment do not remain in effect
- after the command completes. The return status is the exit status of
- <I>list</I>.
- <DT>{ <I>list</I>; }<DD>
- <I>list</I> is simply executed in the current shell environment.
- <I>list</I> must be terminated with a newline or semicolon.
- This is known as a <I>group command</I>.
- The return status is the exit status of
- <I>list</I>.
- Note that unlike the metacharacters <B>(</B> and <B>)</B>, <B>{</B> and
- <B>}</B> are <I>reserved words</I> and must occur where a reserved
- word is permitted to be recognized. Since they do not cause a word
- break, they must be separated from <I>list</I> by whitespace or another
- shell metacharacter.
- <DT>((<I>expression</I>))<DD>
- The <I>expression</I> is evaluated according to the rules described
- below under
- <FONT SIZE=-1><B>ARITHMETIC EVALUATION</B>.
- </FONT>
- If the value of the expression is non-zero, the return status is 0;
- otherwise the return status is 1. This is exactly equivalent to
- <B>let "</B><I>expression</I>".
- <DT><B>[[</B> <I>expression</I> <B>]]</B><DD>
- Return a status of 0 or 1 depending on the evaluation of
- the conditional expression <I>expression</I>.
- Expressions are composed of the primaries described below under
- <FONT SIZE=-1><B>CONDITIONAL EXPRESSIONS</B>.
- </FONT>
- Word splitting and pathname expansion are not performed on the words
- between the <B>[[</B> and <B>]]</B>; tilde expansion,
- parameter and variable expansion,
- arithmetic expansion, command substitution, process
- substitution, and quote removal are performed.
- Conditional operators such as <B>-f</B> must be unquoted to be recognized
- as primaries.
- <P>
- When used with <B>[[</B>, the <B><</B> and <B>></B> operators sort
- lexicographically using the current locale.
- <P>
- When the <B>==</B> and <B>!=</B> operators are used, the string to the
- right of the operator is considered a pattern and matched according
- to the rules described below under <B>Pattern Matching</B>,
- as if the <B>extglob</B> shell option were enabled.
- The <B>=</B> operator is equivalent to <B>==</B>.
- If the
- <B>nocasematch</B>
- shell option is enabled, the match is performed without regard to the case
- of alphabetic characters.
- The return value is 0 if the string matches (<B>==</B>) or does not match
- (<B>!=</B>) the pattern, and 1 otherwise.
- Any part of the pattern may be quoted to force the quoted portion
- to be matched as a string.
- <P>
- An additional binary operator, <B>=~</B>, is available, with the same
- precedence as <B>==</B> and <B>!=</B>.
- When it is used, the string to the right of the operator is considered
- an extended regular expression and matched accordingly (as in <I>regex</I>(3)).
- The return value is 0 if the string matches
- the pattern, and 1 otherwise.
- If the regular expression is syntactically incorrect, the conditional
- expression's return value is 2.
- If the
- <B>nocasematch</B>
- shell option is enabled, the match is performed without regard to the case
- of alphabetic characters.
- Any part of the pattern may be quoted to force the quoted portion
- to be matched as a string.
- Bracket expressions in regular expressions must be treated carefully,
- since normal quoting characters lose their meanings between brackets.
- If the pattern is stored in a shell variable, quoting the variable
- expansion forces the entire pattern to be matched as a string.
- Substrings matched by parenthesized subexpressions within the regular
- expression are saved in the array variable
- <FONT SIZE=-1><B>BASH_REMATCH</B>.
- </FONT>
- The element of
- <FONT SIZE=-1><B>BASH_REMATCH</B>
- </FONT>
- with index 0 is the portion of the string
- matching the entire regular expression.
- The element of
- <FONT SIZE=-1><B>BASH_REMATCH</B>
- </FONT>
- with index <I>n</I> is the portion of the
- string matching the <I>n</I>th parenthesized subexpression.
- <P>
- Expressions may be combined using the following operators, listed
- in decreasing order of precedence:
- <P>
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>( </B><I>expression</I> )
- <DD>
- Returns the value of <I>expression</I>.
- This may be used to override the normal precedence of operators.
- <DT><B>! </B><I>expression</I>
- <DD>
- True if
- <I>expression</I>
- is false.
- <DT><I>expression1</I> <B>&&</B> <I>expression2</I><DD>
- True if both
- <I>expression1</I>
- and
- <I>expression2</I>
- are true.
- <DT><I>expression1</I> <B>||</B> <I>expression2</I><DD>
- True if either
- <I>expression1</I>
- or
- <I>expression2</I>
- is true.
- </DL>
- <P>
- The <B>&&</B> and <B>||</B>
- operators do not evaluate <I>expression2</I> if the value of
- <I>expression1</I> is sufficient to determine the return value of
- the entire conditional expression.
- </DL>
- <DT><B>for</B> <I>name</I> [ [ <B>in</B> [ <I>word ...</I> ] ] ; ] <B>do</B> <I>list</I> ; <B>done</B><DD>
- The list of words following <B>in</B> is expanded, generating a list
- of items.
- The variable <I>name</I> is set to each element of this list
- in turn, and <I>list</I> is executed each time.
- If the <B>in</B> <I>word</I> is omitted, the <B>for</B> command executes
- <I>list</I> once for each positional parameter that is set (see
- <FONT SIZE=-1><B>PARAMETERS</B>
- </FONT>
- below).
- The return status is the exit status of the last command that executes.
- If the expansion of the items following <B>in</B> results in an empty
- list, no commands are executed, and the return status is 0.
- <DT><B>for</B> (( <I>expr1</I> ; <I>expr2</I> ; <I>expr3</I> )) ; <B>do</B> <I>list</I> ; <B>done</B><DD>
- First, the arithmetic expression <I>expr1</I> is evaluated according
- to the rules described below under
- <FONT SIZE=-1><B>ARITHMETIC EVALUATION</B>.
- </FONT>
- The arithmetic expression <I>expr2</I> is then evaluated repeatedly
- until it evaluates to zero.
- Each time <I>expr2</I> evaluates to a non-zero value, <I>list</I> is
- executed and the arithmetic expression <I>expr3</I> is evaluated.
- If any expression is omitted, it behaves as if it evaluates to 1.
- The return value is the exit status of the last command in <I>list</I>
- that is executed, or false if any of the expressions is invalid.
- <DT><B>select</B> <I>name</I> [ <B>in</B> <I>word</I> ] ; <B>do</B> <I>list</I> ; <B>done</B><DD>
- The list of words following <B>in</B> is expanded, generating a list
- of items. The set of expanded words is printed on the standard
- error, each preceded by a number. If the <B>in</B>
- <I>word</I> is omitted, the positional parameters are printed (see
- <FONT SIZE=-1><B>PARAMETERS</B>
- </FONT>
- below). The
- <FONT SIZE=-1><B>PS3</B>
- </FONT>
- prompt is then displayed and a line read from the standard input.
- If the line consists of a number corresponding to one of
- the displayed words, then the value of
- <I>name</I>
- is set to that word. If the line is empty, the words and prompt
- are displayed again. If EOF is read, the command completes. Any
- other value read causes
- <I>name</I>
- to be set to null. The line read is saved in the variable
- <FONT SIZE=-1><B>REPLY</B>.
- </FONT>
- The
- <I>list</I>
- is executed after each selection until a
- <B>break</B>
- command is executed.
- The exit status of
- <B>select</B>
- is the exit status of the last command executed in
- <I>list</I>,
- or zero if no commands were executed.
- <DT><B>case</B> <I>word</I> <B>in</B> [ [(] <I>pattern</I> [ <B>|</B> <I>pattern</I> ]
- <DD>
- A <B>case</B> command first expands <I>word</I>, and tries to match
- it against each <I>pattern</I> in turn, using the same matching rules
- as for pathname expansion (see
- <B>Pathname Expansion</B>
- below).
- The <I>word</I> is expanded using tilde
- expansion, parameter and variable expansion, arithmetic expansion,
- command substitution, process substitution and quote removal.
- Each <I>pattern</I> examined is expanded using tilde
- expansion, parameter and variable expansion, arithmetic expansion,
- command substitution, and process substitution.
- If the
- <B>nocasematch</B>
- shell option is enabled, the match is performed without regard to the case
- of alphabetic characters.
- When a match is found, the corresponding <I>list</I> is executed.
- If the <B>;;</B> operator is used, no subsequent matches are attempted after
- the first pattern match.
- Using <B>;&</B> in place of <B>;;</B> causes execution to continue with
- the <I>list</I> associated with the next set of patterns.
- Using <B>;;&</B> in place of <B>;;</B> causes the shell to test the next
- pattern list in the statement, if any, and execute any associated <I>list</I>
- on a successful match.
- The exit status is zero if no
- pattern matches. Otherwise, it is the exit status of the
- last command executed in <I>list</I>.
- <DT><B>if</B> <I>list</I>; <B>then</B> <I>list</I>; [ <B>elif</B> <I>list</I>; <B>then</B> <I>list</I>; ] ... [ <B>else</B> <I>list</I>; ] <B>fi</B><DD>
- The
- <B>if</B>
- <I>list</I>
- is executed. If its exit status is zero, the
- <B>then</B> <I>list</I> is executed. Otherwise, each <B>elif</B>
- <I>list</I> is executed in turn, and if its exit status is zero,
- the corresponding <B>then</B> <I>list</I> is executed and the
- command completes. Otherwise, the <B>else</B> <I>list</I> is
- executed, if present. The exit status is the exit status of the
- last command executed, or zero if no condition tested true.
- <DT><B>while</B> <I>list-1</I>; <B>do</B> <I>list-2</I>; <B>done</B><DD>
- <DT><B>until</B> <I>list-1</I>; <B>do</B> <I>list-2</I>; <B>done</B><DD>
- The <B>while</B> command continuously executes the list
- <I>list-2</I> as long as the last command in the list <I>list-1</I> returns
- an exit status of zero. The <B>until</B> command is identical
- to the <B>while</B> command, except that the test is negated:
- <I>list-2</I>
- is executed as long as the last command in
- <I>list-1</I>
- returns a non-zero exit status.
- The exit status of the <B>while</B> and <B>until</B> commands
- is the exit status
- of the last command executed in <I>list-2</I>, or zero if
- none was executed.
- </DL>
- <A NAME="lbAP"> </A>
- <H4>Coprocesses</H4>
- <P>
- A <I>coprocess</I> is a shell command preceded by the <B>coproc</B> reserved
- word.
- A coprocess is executed asynchronously in a subshell, as if the command
- had been terminated with the <B>&</B> control operator, with a two-way pipe
- established between the executing shell and the coprocess.
- <P>
- The format for a coprocess is:
- <DL COMPACT><DT><DD>
- <P>
- <B>coproc</B> [<I>NAME</I>] <I>command</I> [<I>redirections</I>]
- </DL>
- <P>
- This creates a coprocess named <I>NAME</I>.
- If <I>NAME</I> is not supplied, the default name is <B>COPROC</B>.
- <I>NAME</I> must not be supplied if <I>command</I> is a <I>simple
- command</I> (see above); otherwise, it is interpreted as the first word
- of the simple command.
- When the coprocess is executed, the shell creates an array variable (see
- <B>Arrays</B>
- below) named <I>NAME</I> in the context of the executing shell.
- The standard output of
- <I>command</I>
- is connected via a pipe to a file descriptor in the executing shell,
- and that file descriptor is assigned to <I>NAME</I>[0].
- The standard input of
- <I>command</I>
- is connected via a pipe to a file descriptor in the executing shell,
- and that file descriptor is assigned to <I>NAME</I>[1].
- This pipe is established before any redirections specified by the
- command (see
- <FONT SIZE=-1><B>REDIRECTION</B>
- </FONT>
- below).
- The file descriptors can be utilized as arguments to shell commands
- and redirections using standard word expansions.
- The file descriptors are not available in subshells.
- The process ID of the shell spawned to execute the coprocess is
- available as the value of the variable <I>NAME</I>_PID.
- The <B>wait</B>
- builtin command may be used to wait for the coprocess to terminate.
- <P>
- Since the coprocess is created as an asynchronous command,
- the <B>coproc</B> command always returns success.
- The return status of a coprocess is the exit status of <I>command</I>.
- <A NAME="lbAQ"> </A>
- <H4>Shell Function Definitions</H4>
- <P>
- A shell function is an object that is called like a simple command and
- executes a compound command with a new set of positional parameters.
- Shell functions are declared as follows:
- <DL COMPACT>
- <DT><I>name</I> () <I>compound-command</I> [<I>redirection</I>]<DD>
- <DT><B>function</B> <I>name</I> [()] <I>compound-command</I> [<I>redirection</I>]<DD>
- This defines a function named <I>name</I>.
- The reserved word <B>function</B> is optional.
- If the <B>function</B> reserved word is supplied, the parentheses are optional.
- The <I>body</I> of the function is the compound command
- <I>compound-command</I>
- (see <B>Compound Commands</B> above).
- That command is usually a <I>list</I> of commands between { and }, but
- may be any command listed under <B>Compound Commands</B> above,
- with one exception: If the <B>function</B> reserved word is used, but the
- parentheses are not supplied, the braces are required.
- <I>compound-command</I> is executed whenever <I>name</I> is specified as the
- name of a simple command.
- When in <I>posix mode</I>, <I>name</I> may not be the name of one of the
- POSIX <I>special builtins</I>.
- Any redirections (see
- <FONT SIZE=-1><B>REDIRECTION</B>
- </FONT>
- below) specified when a function is defined are performed
- when the function is executed.
- The exit status of a function definition is zero unless a syntax error
- occurs or a readonly function with the same name already exists.
- When executed, the exit status of a function is the exit status of the
- last command executed in the body. (See
- <FONT SIZE=-1><B>FUNCTIONS</B>
- </FONT>
- below.)
- </DL>
- <A NAME="lbAR"> </A>
- <H3>COMMENTS</H3>
- In a non-interactive shell, or an interactive shell in which the
- <B>interactive_comments</B>
- option to the
- <B>shopt</B>
- builtin is enabled (see
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below), a word beginning with
- <B>#</B>
- causes that word and all remaining characters on that line to
- be ignored. An interactive shell without the
- <B>interactive_comments</B>
- option enabled does not allow comments. The
- <B>interactive_comments</B>
- option is on by default in interactive shells.
- <A NAME="lbAS"> </A>
- <H3>QUOTING</H3>
- <I>Quoting</I> is used to remove the special meaning of certain
- characters or words to the shell. Quoting can be used to
- disable special treatment for special characters, to prevent
- reserved words from being recognized as such, and to prevent
- parameter expansion.
- <P>
- Each of the <I>metacharacters</I> listed above under
- <FONT SIZE=-1><B>DEFINITIONS</B>
- </FONT>
- has special meaning to the shell and must be quoted if it is to
- represent itself.
- <P>
- When the command history expansion facilities are being used
- (see
- <FONT SIZE=-1><B>HISTORY EXPANSION</B>
- </FONT>
- below), the
- <I>history expansion</I> character, usually <B>!</B>, must be quoted
- to prevent history expansion.
- <P>
- There are three quoting mechanisms: the
- <I>escape character</I>,
- single quotes, and double quotes.
- <P>
- A non-quoted backslash (<B>\</B>) is the
- <I>escape character</I>.
- It preserves the literal value of the next character that follows,
- with the exception of <newline>. If a <B>\</B><newline> pair
- appears, and the backslash is not itself quoted, the <B>\</B><newline>
- is treated as a line continuation (that is, it is removed from the
- input stream and effectively ignored).
- <P>
- Enclosing characters in single quotes preserves the literal value
- of each character within the quotes. A single quote may not occur
- between single quotes, even when preceded by a backslash.
- <P>
- Enclosing characters in double quotes preserves the literal value
- of all characters within the quotes, with the exception of
- <B>$</B>,
- <B>`</B>,
- <B>\</B>,
- and, when history expansion is enabled,
- <B>!</B>.
- When the shell is in <I>posix mode</I>, the <B>!</B> has no special meaning
- within double quotes, even when history expansion is enabled.
- The characters
- <B>$</B>
- and
- <B>`</B>
- retain their special meaning within double quotes. The backslash
- retains its special meaning only when followed by one of the following
- characters:
- <B>$</B>,
- <B>`</B>,
- <B>"</B>,
- <B>\</B>,
- or
- <B><newline></B>.
- A double quote may be quoted within double quotes by preceding it with
- a backslash.
- If enabled, history expansion will be performed unless an
- <B>!</B>
- appearing in double quotes is escaped using a backslash.
- The backslash preceding the
- <B>!</B>
- is not removed.
- <P>
- The special parameters
- <B>*</B>
- and
- <B>@</B>
- have special meaning when in double
- quotes (see
- <FONT SIZE=-1><B>PARAMETERS</B>
- </FONT>
- below).
- <P>
- Words of the form <B>$</B>aq<I>string</I>aq are treated specially. The
- word expands to <I>string</I>, with backslash-escaped characters replaced
- as specified by the ANSI C standard. Backslash escape sequences, if
- present, are decoded as follows:
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>\a</B>
- <DD>
- alert (bell)
- <DT><B>\b</B>
- <DD>
- backspace
- <DT><B>\e</B>
- <DD>
- <DT><B>\E</B>
- <DD>
- an escape character
- <DT><B>\f</B>
- <DD>
- form feed
- <DT><B>\n</B>
- <DD>
- new line
- <DT><B>\r</B>
- <DD>
- carriage return
- <DT><B>\t</B>
- <DD>
- horizontal tab
- <DT><B>\v</B>
- <DD>
- vertical tab
- <DT><B>\\</B>
- <DD>
- backslash
- <DT><B>\aq</B>
- <DD>
- single quote
- <DT><B>\dq</B>
- <DD>
- double quote
- <DT><B>\?</B>
- <DD>
- question mark
- <DT><B>\</B><I>nnn</I>
- <DD>
- the eight-bit character whose value is the octal value <I>nnn</I>
- (one to three digits)
- <DT><B>\x</B><I>HH</I>
- <DD>
- the eight-bit character whose value is the hexadecimal value <I>HH</I>
- (one or two hex digits)
- <DT><B>\u</B><I>HHHH</I>
- <DD>
- the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
- <I>HHHH</I> (one to four hex digits)
- <DT><B>\U</B><I>HHHHHHHH</I>
- <DD>
- the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
- <I>HHHHHHHH</I> (one to eight hex digits)
- <DT><B>\c</B><I>x</I>
- <DD>
- a control-<I>x</I> character
- </DL></DL>
- <P>
- The expanded result is single-quoted, as if the dollar sign had
- not been present.
- <P>
- A double-quoted string preceded by a dollar sign (<B>$</B>dq<I>string</I>dq)
- will cause the string to be translated according to the current locale.
- If the current locale is <B>C</B> or <B>POSIX</B>, the dollar sign
- is ignored.
- If the string is translated and replaced, the replacement is
- double-quoted.
- <A NAME="lbAT"> </A>
- <H3>PARAMETERS</H3>
- A
- <I>parameter</I>
- is an entity that stores values.
- It can be a
- <I>name</I>,
- a number, or one of the special characters listed below under
- <B>Special Parameters</B>.
- A
- <I>variable</I>
- is a parameter denoted by a
- <I>name</I>.
- A variable has a <I>value</I> and zero or more <I>attributes</I>.
- Attributes are assigned using the
- <B>declare</B>
- builtin command (see
- <B>declare</B>
- below in
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>).
- </FONT>
- <P>
- A parameter is set if it has been assigned a value. The null string is
- a valid value. Once a variable is set, it may be unset only by using
- the
- <B>unset</B>
- builtin command (see
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below).
- <P>
- A
- <I>variable</I>
- may be assigned to by a statement of the form
- <DL COMPACT><DT><DD>
- <P>
- <I>name</I>=[<I>value</I>]
- </DL>
- <P>
- If
- <I>value</I>
- is not given, the variable is assigned the null string. All
- <I>values</I>
- undergo tilde expansion, parameter and variable expansion,
- command substitution, arithmetic expansion, and quote
- removal (see
- <FONT SIZE=-1><B>EXPANSION</B>
- </FONT>
- below). If the variable has its
- <B>integer</B>
- attribute set, then
- <I>value</I>
- is evaluated as an arithmetic expression even if the $((...)) expansion is
- not used (see
- <B>Arithmetic Expansion</B>
- below).
- Word splitting is not performed, with the exception
- of <B>"$@"</B> as explained below under
- <B>Special Parameters</B>.
- Pathname expansion is not performed.
- Assignment statements may also appear as arguments to the
- <B>alias</B>,
- <B>declare</B>,
- <B>typeset</B>,
- <B>export</B>,
- <B>readonly</B>,
- and
- <B>local</B>
- builtin commands (<I>declaration</I> commands).
- When in <I>posix mode</I>, these builtins may appear in a command after
- one or more instances of the <B>command</B> builtin and retain these
- assignment statement properties.
- <P>
- In the context where an assignment statement is assigning a value
- to a shell variable or array index, the += operator can be used to
- append to or add to the variable's previous value.
- This includes arguments to builtin commands such as <B>declare</B> that
- accept assignment statements (<I>declaration</I> commands).
- When += is applied to a variable for which the <I>integer</I> attribute has been
- set, <I>value</I> is evaluated as an arithmetic expression and added to the
- variable's current value, which is also evaluated.
- When += is applied to an array variable using compound assignment (see
- <B>Arrays</B>
- below), the
- variable's value is not unset (as it is when using =), and new values are
- appended to the array beginning at one greater than the array's maximum index
- (for indexed arrays) or added as additional key-value pairs in an
- associative array.
- When applied to a string-valued variable, <I>value</I> is expanded and
- appended to the variable's value.
- <P>
- A variable can be assigned the <I>nameref</I> attribute using the
- <B>-n</B> option to the <B>declare</B> or <B>local</B> builtin commands
- (see the descriptions of <B>declare</B> and <B>local</B> below)
- to create a <I>nameref</I>, or a reference to another variable.
- This allows variables to be manipulated indirectly.
- Whenever the nameref variable is referenced, assigned to, unset, or has
- its attributes modified (other than using or changing the <I>nameref</I>
- attribute itself), the
- operation is actually performed on the variable specified by the nameref
- variable's value.
- A nameref is commonly used within shell functions to refer to a variable
- whose name is passed as an argument to the function.
- For instance, if a variable name is passed to a shell function as its first
- argument, running
- <P>
- <DL COMPACT><DT><DD>
- <TT>declare -n ref=$1</TT>
- </DL>
- <P>
- inside the function creates a nameref variable <B>ref</B> whose value is
- the variable name passed as the first argument.
- References and assignments to <B>ref</B>, and changes to its attributes,
- are treated as references, assignments, and attribute modifications
- to the variable whose name was passed as <B>$1</B>.
- If the control variable in a <B>for</B> loop has the nameref attribute,
- the list of words can be a list of shell variables, and a name reference
- will be established for each word in the list, in turn, when the loop is
- executed.
- Array variables cannot be given the <B>nameref</B> attribute.
- However, nameref variables can reference array variables and subscripted
- array variables.
- Namerefs can be unset using the <B>-n</B> option to the <B>unset</B> builtin.
- Otherwise, if <B>unset</B> is executed with the name of a nameref variable
- as an argument, the variable referenced by the nameref variable will be unset.
- <A NAME="lbAU"> </A>
- <H4>Positional Parameters</H4>
- <P>
- A
- <I>positional parameter</I>
- is a parameter denoted by one or more
- digits, other than the single digit 0. Positional parameters are
- assigned from the shell's arguments when it is invoked,
- and may be reassigned using the
- <B>set</B>
- builtin command. Positional parameters may not be assigned to
- with assignment statements. The positional parameters are
- temporarily replaced when a shell function is executed (see
- <FONT SIZE=-1><B>FUNCTIONS</B>
- </FONT>
- below).
- <P>
- When a positional parameter consisting of more than a single
- digit is expanded, it must be enclosed in braces (see
- <FONT SIZE=-1><B>EXPANSION</B>
- </FONT>
- below).
- <A NAME="lbAV"> </A>
- <H4>Special Parameters</H4>
- <P>
- The shell treats several parameters specially. These parameters may
- only be referenced; assignment to them is not allowed.
- <DL COMPACT>
- <DT><B>*</B>
- <DD>
- Expands to the positional parameters, starting from one.
- When the expansion is not within double quotes, each positional parameter
- expands to a separate word.
- In contexts where it is performed, those words
- are subject to further word splitting and pathname expansion.
- When the expansion occurs within double quotes, it expands to a single word
- with the value of each parameter separated by the first character of the
- <FONT SIZE=-1><B>IFS</B>
- </FONT>
- special variable. That is, "<B>$*</B>" is equivalent
- to "<B>$1</B><I>c</I><B>$2</B><I>c</I><B>...</B>", where
- <I>c</I>
- is the first character of the value of the
- <FONT SIZE=-1><B>IFS</B>
- </FONT>
- variable. If
- <FONT SIZE=-1><B>IFS</B>
- </FONT>
- is unset, the parameters are separated by spaces.
- If
- <FONT SIZE=-1><B>IFS</B>
- </FONT>
- is null, the parameters are joined without intervening separators.
- <DT><B>@</B>
- <DD>
- Expands to the positional parameters, starting from one. When the
- expansion occurs within double quotes, each parameter expands to a
- separate word. That is, "<B>$@</B>" is equivalent to
- "<B>$1</B>" "<B>$2</B>" ...
- If the double-quoted expansion occurs within a word, the expansion of
- the first parameter is joined with the beginning part of the original
- word, and the expansion of the last parameter is joined with the last
- part of the original word.
- When there are no positional parameters, "<B>$@</B>" and
- <B>$@</B>
- expand to nothing (i.e., they are removed).
- <DT><B>#</B>
- <DD>
- Expands to the number of positional parameters in decimal.
- <DT><B>?</B>
- <DD>
- Expands to the exit status of the most recently executed foreground
- pipeline.
- <DT><B>-</B>
- <DD>
- Expands to the current option flags as specified upon invocation,
- by the
- <B>set</B>
- builtin command, or those set by the shell itself
- (such as the
- <B>-i</B>
- option).
- <DT><B>$</B>
- <DD>
- Expands to the process ID of the shell. In a () subshell, it
- expands to the process ID of the current shell, not the
- subshell.
- <DT><B>!</B>
- <DD>
- Expands to the process ID of the job most recently placed into the
- background, whether executed as an asynchronous command or using
- the <B>bg</B> builtin (see
- <FONT SIZE=-1><B>JOB CONTROL</B>
- </FONT>
- below).
- <DT><B>0</B>
- <DD>
- Expands to the name of the shell or shell script. This is set at
- shell initialization. If
- <B>bash</B>
- is invoked with a file of commands,
- <B>$0</B>
- is set to the name of that file. If
- <B>bash</B>
- is started with the
- <B>-c</B>
- option, then
- <B>$0</B>
- is set to the first argument after the string to be
- executed, if one is present. Otherwise, it is set
- to the filename used to invoke
- <B>bash</B>,
- as given by argument zero.
- <DT><B>_</B>
- <DD>
- At shell startup, set to the absolute pathname used to invoke the
- shell or shell script being executed as passed in the environment
- or argument list.
- Subsequently, expands to the last argument to the previous command,
- after expansion.
- Also set to the full pathname used to invoke each command executed
- and placed in the environment exported to that command.
- When checking mail, this parameter holds the name of the mail file
- currently being checked.
- </DL>
- <A NAME="lbAW"> </A>
- <H4>Shell Variables</H4>
- <P>
- The following variables are set by the shell:
- <P>
- <DL COMPACT>
- <DT><B>BASH</B>
- <DD>
- Expands to the full filename used to invoke this instance of
- <B>bash</B>.
- <DT><B>BASHOPTS</B>
- <DD>
- A colon-separated list of enabled shell options. Each word in
- the list is a valid argument for the
- <B>-s</B>
- option to the
- <B>shopt</B>
- builtin command (see
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below). The options appearing in
- <FONT SIZE=-1><B>BASHOPTS</B>
- </FONT>
- are those reported as
- <I>on</I>
- by <B>shopt</B>.
- If this variable is in the environment when
- <B>bash</B>
- starts up, each shell option in the list will be enabled before
- reading any startup files.
- This variable is read-only.
- <DT><B>BASHPID</B>
- <DD>
- Expands to the process ID of the current <B>bash</B> process.
- This differs from <B>$$</B> under certain circumstances, such as subshells
- that do not require <B>bash</B> to be re-initialized.
- <DT><B>BASH_ALIASES</B>
- <DD>
- An associative array variable whose members correspond to the internal
- list of aliases as maintained by the <B>alias</B> builtin.
- Elements added to this array appear in the alias list; however,
- unsetting array elements currently does not cause aliases to be removed
- from the alias list.
- If
- <B>BASH_ALIASES</B>
- is unset, it loses its special properties, even if it is
- subsequently reset.
- <DT><B>BASH_ARGC</B>
- <DD>
- An array variable whose values are the number of parameters in each
- frame of the current <B>bash</B> execution call stack.
- The number of
- parameters to the current subroutine (shell function or script executed
- with <B>.</B> or <B>source</B>) is at the top of the stack.
- When a subroutine is executed, the number of parameters passed is pushed onto
- <FONT SIZE=-1><B>BASH_ARGC</B>.
- </FONT>
- The shell sets
- <FONT SIZE=-1><B>BASH_ARGC</B>
- </FONT>
- only when in extended debugging mode (see the description of the
- <B>extdebug</B>
- option to the
- <B>shopt</B>
- builtin below)
- <DT><B>BASH_ARGV</B>
- <DD>
- An array variable containing all of the parameters in the current <B>bash</B>
- execution call stack. The final parameter of the last subroutine call
- is at the top of the stack; the first parameter of the initial call is
- at the bottom. When a subroutine is executed, the parameters supplied
- are pushed onto
- <FONT SIZE=-1><B>BASH_ARGV</B>.
- </FONT>
- The shell sets
- <FONT SIZE=-1><B>BASH_ARGV</B>
- </FONT>
- only when in extended debugging mode
- (see the description of the
- <B>extdebug</B>
- option to the
- <B>shopt</B>
- builtin below)
- <DT><B>BASH_CMDS</B>
- <DD>
- An associative array variable whose members correspond to the internal
- hash table of commands as maintained by the <B>hash</B> builtin.
- Elements added to this array appear in the hash table; however,
- unsetting array elements currently does not cause command names to be removed
- from the hash table.
- If
- <B>BASH_CMDS</B>
- is unset, it loses its special properties, even if it is
- subsequently reset.
- <DT><B>BASH_COMMAND</B>
- <DD>
- The command currently being executed or about to be executed, unless the
- shell is executing a command as the result of a trap,
- in which case it is the command executing at the time of the trap.
- <DT><B>BASH_EXECUTION_STRING</B>
- <DD>
- The command argument to the <B>-c</B> invocation option.
- <DT><B>BASH_LINENO</B>
- <DD>
- An array variable whose members are the line numbers in source files
- where each corresponding member of
- <FONT SIZE=-1><B>FUNCNAME</B>
- </FONT>
- was invoked.
- <B>${BASH_LINENO[</B><I>$i</I><B>]}</B> is the line number in the source
- file (<B>${BASH_SOURCE[</B><I>$i+1</I><B>]}</B>) where
- <B>${FUNCNAME[</B><I>$i</I><B>]}</B> was called
- (or <B>${BASH_LINENO[</B><I>$i-1</I><B>]}</B> if referenced within another
- shell function).
- Use
- <FONT SIZE=-1><B>LINENO</B>
- </FONT>
- to obtain the current line number.
- <DT><B>BASH_LOADABLES_PATH</B>
- <DD>
- A colon-separated list of directories in which the shell looks for
- dynamically loadable builtins specified by the
- <B>enable</B>
- command.
- <DT><B>BASH_REMATCH</B>
- <DD>
- An array variable whose members are assigned by the <B>=~</B> binary
- operator to the <B>[[</B> conditional command.
- The element with index 0 is the portion of the string
- matching the entire regular expression.
- The element with index <I>n</I> is the portion of the
- string matching the <I>n</I>th parenthesized subexpression.
- This variable is read-only.
- <DT><B>BASH_SOURCE</B>
- <DD>
- An array variable whose members are the source filenames
- where the corresponding shell function names in the
- <FONT SIZE=-1><B>FUNCNAME</B>
- </FONT>
- array variable are defined.
- The shell function
- <B>${FUNCNAME[</B><I>$i</I><B>]}</B> is defined in the file
- <B>${BASH_SOURCE[</B><I>$i</I><B>]}</B> and called from
- <B>${BASH_SOURCE[</B><I>$i+1</I><B>]}</B>.
- <DT><B>BASH_SUBSHELL</B>
- <DD>
- Incremented by one within each subshell or subshell environment when
- the shell begins executing in that environment.
- The initial value is 0.
- <DT><B>BASH_VERSINFO</B>
- <DD>
- A readonly array variable whose members hold version information for
- this instance of
- <B>bash</B>.
- The values assigned to the array members are as follows:
- <P>
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>BASH_VERSINFO[</B>0]
- <DD>
- The major version number (the <I>release</I>).
- <DT><B>BASH_VERSINFO[</B>1]
- <DD>
- The minor version number (the <I>version</I>).
- <DT><B>BASH_VERSINFO[</B>2]
- <DD>
- The patch level.
- <DT><B>BASH_VERSINFO[</B>3]
- <DD>
- The build version.
- <DT><B>BASH_VERSINFO[</B>4]
- <DD>
- The release status (e.g., <I>beta1</I>).
- <DT><B>BASH_VERSINFO[</B>5]
- <DD>
- The value of
- <FONT SIZE=-1><B>MACHTYPE</B>.
- </FONT>
- </DL></DL>
- <DT><B>BASH_VERSION</B>
- <DD>
- Expands to a string describing the version of this instance of
- <B>bash</B>.
- <DT><B>COMP_CWORD</B>
- <DD>
- An index into <B>${COMP_WORDS}</B> of the word containing the current
- cursor position.
- This variable is available only in shell functions invoked by the
- programmable completion facilities (see <B>Programmable Completion</B>
- below).
- <DT><B>COMP_KEY</B>
- <DD>
- The key (or final key of a key sequence) used to invoke the current
- completion function.
- <DT><B>COMP_LINE</B>
- <DD>
- The current command line.
- This variable is available only in shell functions and external
- commands invoked by the
- programmable completion facilities (see <B>Programmable Completion</B>
- below).
- <DT><B>COMP_POINT</B>
- <DD>
- The index of the current cursor position relative to the beginning of
- the current command.
- If the current cursor position is at the end of the current command,
- the value of this variable is equal to <B>${#COMP_LINE}</B>.
- This variable is available only in shell functions and external
- commands invoked by the
- programmable completion facilities (see <B>Programmable Completion</B>
- below).
- <DT><B>COMP_TYPE</B>
- <DD>
- Set to an integer value corresponding to the type of completion attempted
- that caused a completion function to be called:
- <I>TAB</I>, for normal completion,
- <I>?</I>, for listing completions after successive tabs,
- <I>!</I>, for listing alternatives on partial word completion,
- <I>@</I>, to list completions if the word is not unmodified,
- or
- <I>%</I>, for menu completion.
- This variable is available only in shell functions and external
- commands invoked by the
- programmable completion facilities (see <B>Programmable Completion</B>
- below).
- <DT><B>COMP_WORDBREAKS</B>
- <DD>
- The set of characters that the <B>readline</B> library treats as word
- separators when performing word completion.
- If
- <FONT SIZE=-1><B>COMP_WORDBREAKS</B>
- </FONT>
- is unset, it loses its special properties, even if it is
- subsequently reset.
- <DT><B>COMP_WORDS</B>
- <DD>
- An array variable (see <B>Arrays</B> below) consisting of the individual
- words in the current command line.
- The line is split into words as <B>readline</B> would split it, using
- <FONT SIZE=-1><B>COMP_WORDBREAKS</B>
- </FONT>
- as described above.
- This variable is available only in shell functions invoked by the
- programmable completion facilities (see <B>Programmable Completion</B>
- below).
- <DT><B>COPROC</B>
- <DD>
- An array variable (see <B>Arrays</B> below) created to hold the file descriptors
- for output from and input to an unnamed coprocess (see <B>Coprocesses</B>
- above).
- <DT><B>DIRSTACK</B>
- <DD>
- An array variable (see
- <B>Arrays</B>
- below) containing the current contents of the directory stack.
- Directories appear in the stack in the order they are displayed by the
- <B>dirs</B>
- builtin.
- Assigning to members of this array variable may be used to modify
- directories already in the stack, but the
- <B>pushd</B>
- and
- <B>popd</B>
- builtins must be used to add and remove directories.
- Assignment to this variable will not change the current directory.
- If
- <FONT SIZE=-1><B>DIRSTACK</B>
- </FONT>
- is unset, it loses its special properties, even if it is
- subsequently reset.
- <DT><B>EUID</B>
- <DD>
- Expands to the effective user ID of the current user, initialized at
- shell startup. This variable is readonly.
- <DT><B>FUNCNAME</B>
- <DD>
- An array variable containing the names of all shell functions
- currently in the execution call stack.
- The element with index 0 is the name of any currently-executing
- shell function.
- The bottom-most element (the one with the highest index) is
- <TT>"main"</TT>.
- This variable exists only when a shell function is executing.
- Assignments to
- <FONT SIZE=-1><B>FUNCNAME</B>
- </FONT>
- have no effect.
- If
- <FONT SIZE=-1><B>FUNCNAME</B>
- </FONT>
- is unset, it loses its special properties, even if it is
- subsequently reset.
- <P>
- This variable can be used with <B>BASH_LINENO</B> and <B>BASH_SOURCE</B>.
- Each element of <B>FUNCNAME</B> has corresponding elements in
- <B>BASH_LINENO</B> and <B>BASH_SOURCE</B> to describe the call stack.
- For instance, <B>${FUNCNAME[</B><I>$i</I><B>]}</B> was called from the file
- <B>${BASH_SOURCE[</B><I>$i+1</I><B>]}</B> at line number
- <B>${BASH_LINENO[</B><I>$i</I><B>]}</B>.
- The <B>caller</B> builtin displays the current call stack using this
- information.
- <DT><B>GROUPS</B>
- <DD>
- An array variable containing the list of groups of which the current
- user is a member.
- Assignments to
- <FONT SIZE=-1><B>GROUPS</B>
- </FONT>
- have no effect.
- If
- <FONT SIZE=-1><B>GROUPS</B>
- </FONT>
- is unset, it loses its special properties, even if it is
- subsequently reset.
- <DT><B>HISTCMD</B>
- <DD>
- The history number, or index in the history list, of the current
- command.
- If
- <FONT SIZE=-1><B>HISTCMD</B>
- </FONT>
- is unset, it loses its special properties, even if it is
- subsequently reset.
- <DT><B>HOSTNAME</B>
- <DD>
- Automatically set to the name of the current host.
- <DT><B>HOSTTYPE</B>
- <DD>
- Automatically set to a string that uniquely
- describes the type of machine on which
- <B>bash</B>
- is executing.
- The default is system-dependent.
- <DT><B>LINENO</B>
- <DD>
- Each time this parameter is referenced, the shell substitutes
- a decimal number representing the current sequential line number
- (starting with 1) within a script or function. When not in a
- script or function, the value substituted is not guaranteed to
- be meaningful.
- If
- <FONT SIZE=-1><B>LINENO</B>
- </FONT>
- is unset, it loses its special properties, even if it is
- subsequently reset.
- <DT><B>MACHTYPE</B>
- <DD>
- Automatically set to a string that fully describes the system
- type on which
- <B>bash</B>
- is executing, in the standard GNU <I>cpu-company-system</I> format.
- The default is system-dependent.
- <DT><B>MAPFILE</B>
- <DD>
- An array variable (see <B>Arrays</B> below) created to hold the text
- read by the <B>mapfile</B> builtin when no variable name is supplied.
- <DT><B>OLDPWD</B>
- <DD>
- The previous working directory as set by the
- <B>cd</B>
- command.
- <DT><B>OPTARG</B>
- <DD>
- The value of the last option argument processed by the
- <B>getopts</B>
- builtin command (see
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below).
- <DT><B>OPTIND</B>
- <DD>
- The index of the next argument to be processed by the
- <B>getopts</B>
- builtin command (see
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below).
- <DT><B>OSTYPE</B>
- <DD>
- Automatically set to a string that
- describes the operating system on which
- <B>bash</B>
- is executing.
- The default is system-dependent.
- <DT><B>PIPESTATUS</B>
- <DD>
- An array variable (see
- <B>Arrays</B>
- below) containing a list of exit status values from the processes
- in the most-recently-executed foreground pipeline (which may
- contain only a single command).
- <DT><B>PPID</B>
- <DD>
- The process ID of the shell's parent. This variable is readonly.
- <DT><B>PWD</B>
- <DD>
- The current working directory as set by the
- <B>cd</B>
- command.
- <DT><B>RANDOM</B>
- <DD>
- Each time this parameter is referenced, a random integer between
- 0 and 32767 is
- generated. The sequence of random numbers may be initialized by assigning
- a value to
- <FONT SIZE=-1><B>RANDOM</B>.
- </FONT>
- If
- <FONT SIZE=-1><B>RANDOM</B>
- </FONT>
- is unset, it loses its special properties, even if it is
- subsequently reset.
- <DT><B>READLINE_LINE</B>
- <DD>
- The contents of the
- <B>readline</B>
- line buffer, for use with
- <TT>bind -x</TT>
- (see
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below).
- <DT><B>READLINE_POINT</B>
- <DD>
- The position of the insertion point in the
- <B>readline</B>
- line buffer, for use with
- <TT>bind -x</TT>
- (see
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below).
- <DT><B>REPLY</B>
- <DD>
- Set to the line of input read by the
- <B>read</B>
- builtin command when no arguments are supplied.
- <DT><B>SECONDS</B>
- <DD>
- Each time this parameter is
- referenced, the number of seconds since shell invocation is returned. If a
- value is assigned to
- <FONT SIZE=-1><B>SECONDS</B>,
- </FONT>
- the value returned upon subsequent
- references is
- the number of seconds since the assignment plus the value assigned.
- If
- <FONT SIZE=-1><B>SECONDS</B>
- </FONT>
- is unset, it loses its special properties, even if it is
- subsequently reset.
- <DT><B>SHELLOPTS</B>
- <DD>
- A colon-separated list of enabled shell options. Each word in
- the list is a valid argument for the
- <B>-o</B>
- option to the
- <B>set</B>
- builtin command (see
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below). The options appearing in
- <FONT SIZE=-1><B>SHELLOPTS</B>
- </FONT>
- are those reported as
- <I>on</I>
- by <B>set -o</B>.
- If this variable is in the environment when
- <B>bash</B>
- starts up, each shell option in the list will be enabled before
- reading any startup files.
- This variable is read-only.
- <DT><B>SHLVL</B>
- <DD>
- Incremented by one each time an instance of
- <B>bash</B>
- is started.
- <DT><B>UID</B>
- <DD>
- Expands to the user ID of the current user, initialized at shell startup.
- This variable is readonly.
- </DL>
- <P>
- The following variables are used by the shell. In some cases,
- <B>bash</B>
- assigns a default value to a variable; these cases are noted
- below.
- <P>
- <DL COMPACT>
- <DT><B>BASH_COMPAT</B>
- <DD>
- The value is used to set the shell's compatibility level.
- See the description of the <B>shopt</B> builtin below under
- <B>SHELL BUILTIN COMMANDS</B>
- for a description of the various compatibility
- levels and their effects.
- The value may be a decimal number (e.g., 4.2) or an integer (e.g., 42)
- corresponding to the desired compatibility level.
- If <B>BASH_COMPAT</B> is unset or set to the empty string, the compatibility
- level is set to the default for the current version.
- If <B>BASH_COMPAT</B> is set to a value that is not one of the valid
- compatibility levels, the shell prints an error message and sets the
- compatibility level to the default for the current version.
- The valid compatibility levels correspond to the compatibility options
- accepted by the <B>shopt</B> builtin described below (for example,
- <B>compat42</B> means that 4.2 and 42 are valid values).
- The current version is also a valid value.
- <DT><B>BASH_ENV</B>
- <DD>
- If this parameter is set when <B>bash</B> is executing a shell script,
- its value is interpreted as a filename containing commands to
- initialize the shell, as in
- <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A>.
- The value of
- <FONT SIZE=-1><B>BASH_ENV</B>
- </FONT>
- is subjected to parameter expansion, command substitution, and arithmetic
- expansion before being interpreted as a filename.
- <FONT SIZE=-1><B>PATH</B>
- </FONT>
- is not used to search for the resultant filename.
- <DT><B>BASH_XTRACEFD</B>
- <DD>
- If set to an integer corresponding to a valid file descriptor, <B>bash</B>
- will write the trace output generated when
- <TT>set -x</TT>
- is enabled to that file descriptor.
- The file descriptor is closed when
- <FONT SIZE=-1><B>BASH_XTRACEFD</B>
- </FONT>
- is unset or assigned a new value.
- Unsetting
- <FONT SIZE=-1><B>BASH_XTRACEFD</B>
- </FONT>
- or assigning it the empty string causes the
- trace output to be sent to the standard error.
- Note that setting
- <FONT SIZE=-1><B>BASH_XTRACEFD</B>
- </FONT>
- to 2 (the standard error file
- descriptor) and then unsetting it will result in the standard error
- being closed.
- <DT><B>CDPATH</B>
- <DD>
- The search path for the
- <B>cd</B>
- command.
- This is a colon-separated list of directories in which the shell looks
- for destination directories specified by the
- <B>cd</B>
- command.
- A sample value is
- <TT>".:~:/usr"</TT>.
- <DT><B>CHILD_MAX</B>
- <DD>
- Set the number of exited child status values for the shell to remember.
- Bash will not allow this value to be decreased below a POSIX-mandated
- minimum, and there is a maximum value (currently 8192) that this may
- not exceed.
- The minimum value is system-dependent.
- <DT><B>COLUMNS</B>
- <DD>
- Used by the <B>select</B> compound command to determine the terminal width
- when printing selection lists.
- Automatically set if the
- <B>checkwinsize</B>
- option is enabled or in an interactive shell upon receipt of a
- <FONT SIZE=-1><B>SIGWINCH</B>.
- </FONT>
- <DT><B>COMPREPLY</B>
- <DD>
- An array variable from which <B>bash</B> reads the possible completions
- generated by a shell function invoked by the programmable completion
- facility (see <B>Programmable Completion</B> below).
- Each array element contains one possible completion.
- <DT><B>EMACS</B>
- <DD>
- If <B>bash</B> finds this variable in the environment when the shell starts
- with value
- <TT>t</TT>,
- it assumes that the shell is running in an Emacs shell buffer and disables
- line editing.
- <DT><B>ENV</B>
- <DD>
- Similar to
- <FONT SIZE=-1><B>BASH_ENV</B>;
- </FONT>
- used when the shell is invoked in POSIX mode.
- <DT><B>EXECIGNORE</B>
- <DD>
- A colon-separated list of shell patterns (see <B>Pattern Matching</B>)
- defining the list of filenames to be ignored by command search using
- <B>PATH</B>.
- Files whose full pathnames match one of these patterns are not considered
- executable files for the purposes of completion and command execution
- via <B>PATH</B> lookup.
- This does not affect the behavior of the <B>[</B>, <B>test</B>, and <B>[[</B>
- commands.
- Full pathnames in the command hash table are not subject to <B>EXECIGNORE</B>.
- Use this variable to ignore shared library files that have the executable
- bit set, but are not executable files.
- The pattern matching honors the setting of the <B>extglob</B> shell
- option.
- <DT><B>FCEDIT</B>
- <DD>
- The default editor for the
- <B>fc</B>
- builtin command.
- <DT><B>FIGNORE</B>
- <DD>
- A colon-separated list of suffixes to ignore when performing
- filename completion (see
- <FONT SIZE=-1><B>READLINE</B>
- </FONT>
- below).
- A filename whose suffix matches one of the entries in
- <FONT SIZE=-1><B>FIGNORE</B>
- </FONT>
- is excluded from the list of matched filenames.
- A sample value is
- <TT>".o:~"</TT>.
- <DT><B>FUNCNEST</B>
- <DD>
- If set to a numeric value greater than 0, defines a maximum function
- nesting level. Function invocations that exceed this nesting level
- will cause the current command to abort.
- <DT><B>GLOBIGNORE</B>
- <DD>
- A colon-separated list of patterns defining the set of filenames to
- be ignored by pathname expansion.
- If a filename matched by a pathname expansion pattern also matches one
- of the patterns in
- <FONT SIZE=-1><B>GLOBIGNORE</B>,
- </FONT>
- it is removed from the list of matches.
- <DT><B>HISTCONTROL</B>
- <DD>
- A colon-separated list of values controlling how commands are saved on
- the history list.
- If the list of values includes
- <I>ignorespace</I>,
- lines which begin with a
- <B>space</B>
- character are not saved in the history list.
- A value of
- <I>ignoredups</I>
- causes lines matching the previous history entry to not be saved.
- A value of
- <I>ignoreboth</I>
- is shorthand for <I>ignorespace</I> and <I>ignoredups</I>.
- A value of
- <I>erasedups</I>
- causes all previous lines matching the current line to be removed from
- the history list before that line is saved.
- Any value not in the above list is ignored.
- If
- <FONT SIZE=-1><B>HISTCONTROL</B>
- </FONT>
- is unset, or does not include a valid value,
- all lines read by the shell parser are saved on the history list,
- subject to the value of
- <FONT SIZE=-1><B>HISTIGNORE</B>.
- </FONT>
- The second and subsequent lines of a multi-line compound command are
- not tested, and are added to the history regardless of the value of
- <FONT SIZE=-1><B>HISTCONTROL</B>.
- </FONT>
- <DT><B>HISTFILE</B>
- <DD>
- The name of the file in which command history is saved (see
- <FONT SIZE=-1><B>HISTORY</B>
- </FONT>
- below). The default value is <A HREF="file:~/.bash_history"><I>~/.bash_history</I></A>. If unset, the
- command history is not saved when a shell exits.
- <DT><B>HISTFILESIZE</B>
- <DD>
- The maximum number of lines contained in the history file. When this
- variable is assigned a value, the history file is truncated, if
- necessary,
- to contain no more than that number of lines by removing the oldest entries.
- The history file is also truncated to this size after
- writing it when a shell exits.
- If the value is 0, the history file is truncated to zero size.
- Non-numeric values and numeric values less than zero inhibit truncation.
- The shell sets the default value to the value of <B>HISTSIZE</B>
- after reading any startup files.
- <DT><B>HISTIGNORE</B>
- <DD>
- A colon-separated list of patterns used to decide which command lines
- should be saved on the history list. Each pattern is anchored at the
- beginning of the line and must match the complete line (no implicit
- `<B>*</B>' is appended). Each pattern is tested against the line
- after the checks specified by
- <FONT SIZE=-1><B>HISTCONTROL</B>
- </FONT>
- are applied.
- In addition to the normal shell pattern matching characters, `<B>&</B>'
- matches the previous history line. `<B>&</B>' may be escaped using a
- backslash; the backslash is removed before attempting a match.
- The second and subsequent lines of a multi-line compound command are
- not tested, and are added to the history regardless of the value of
- <FONT SIZE=-1><B>HISTIGNORE</B>.
- </FONT>
- The pattern matching honors the setting of the <B>extglob</B> shell
- option.
- <DT><B>HISTSIZE</B>
- <DD>
- The number of commands to remember in the command history (see
- <FONT SIZE=-1><B>HISTORY</B>
- </FONT>
- below).
- If the value is 0, commands are not saved in the history list.
- Numeric values less than zero result in every command being saved
- on the history list (there is no limit).
- The shell sets the default value to 500 after reading any startup files.
- <DT><B>HISTTIMEFORMAT</B>
- <DD>
- If this variable is set and not null, its value is used as a format string
- for <I>strftime</I>(3) to print the time stamp associated with each history
- entry displayed by the <B>history</B> builtin.
- If this variable is set, time stamps are written to the history file so
- they may be preserved across shell sessions.
- This uses the history comment character to distinguish timestamps from
- other history lines.
- <DT><B>HOME</B>
- <DD>
- The home directory of the current user; the default argument for the
- <B>cd</B> builtin command.
- The value of this variable is also used when performing tilde expansion.
- <DT><B>HOSTFILE</B>
- <DD>
- Contains the name of a file in the same format as
- <I>/etc/hosts</I>
- that should be read when the shell needs to complete a
- hostname.
- The list of possible hostname completions may be changed while the
- shell is running;
- the next time hostname completion is attempted after the
- value is changed,
- <B>bash</B>
- adds the contents of the new file to the existing list.
- If
- <FONT SIZE=-1><B>HOSTFILE</B>
- </FONT>
- is set, but has no value, or does not name a readable file,
- <B>bash</B> attempts to read
- <I>/etc/hosts</I>
- to obtain the list of possible hostname completions.
- When
- <FONT SIZE=-1><B>HOSTFILE</B>
- </FONT>
- is unset, the hostname list is cleared.
- <DT><B>IFS</B>
- <DD>
- The
- <I>Internal Field Separator</I>
- that is used
- for word splitting after expansion and to
- split lines into words with the
- <B>read</B>
- builtin command. The default value is
- ``<space><tab><newline>''.
- <DT><B>IGNOREEOF</B>
- <DD>
- Controls the
- action of an interactive shell on receipt of an
- <FONT SIZE=-1><B>EOF</B>
- </FONT>
- character as the sole input. If set, the value is the number of
- consecutive
- <FONT SIZE=-1><B>EOF</B>
- </FONT>
- characters which must be
- typed as the first characters on an input line before
- <B>bash</B>
- exits. If the variable exists but does not have a numeric value, or
- has no value, the default value is 10. If it does not exist,
- <FONT SIZE=-1><B>EOF</B>
- </FONT>
- signifies the end of input to the shell.
- <DT><B>INPUTRC</B>
- <DD>
- The filename for the
- <B>readline</B>
- startup file, overriding the default of
- <A HREF="file:~/.inputrc"><I>~/.inputrc</I></A>
- (see
- <FONT SIZE=-1><B>READLINE</B>
- </FONT>
- below).
- <DT><B>LANG</B>
- <DD>
- Used to determine the locale category for any category not specifically
- selected with a variable starting with <B>LC_</B>.
- <DT><B>LC_ALL</B>
- <DD>
- This variable overrides the value of
- <FONT SIZE=-1><B>LANG</B>
- </FONT>
- and any other
- <B>LC_</B> variable specifying a locale category.
- <DT><B>LC_COLLATE</B>
- <DD>
- This variable determines the collation order used when sorting the
- results of pathname expansion, and determines the behavior of range
- expressions, equivalence classes, and collating sequences within
- pathname expansion and pattern matching.
- <DT><B>LC_CTYPE</B>
- <DD>
- This variable determines the interpretation of characters and the
- behavior of character classes within pathname expansion and pattern
- matching.
- <DT><B>LC_MESSAGES</B>
- <DD>
- This variable determines the locale used to translate double-quoted
- strings preceded by a <B>$</B>.
- <DT><B>LC_NUMERIC</B>
- <DD>
- This variable determines the locale category used for number formatting.
- <DT><B>LC_TIME</B>
- <DD>
- This variable determines the locale category used for data and time
- formatting.
- <DT><B>LINES</B>
- <DD>
- Used by the <B>select</B> compound command to determine the column length
- for printing selection lists.
- Automatically set if the
- <B>checkwinsize</B>
- option is enabled or in an interactive shell upon receipt of a
- <FONT SIZE=-1><B>SIGWINCH</B>.
- </FONT>
- <DT><B>MAIL</B>
- <DD>
- If this parameter is set to a file or directory name and the
- <FONT SIZE=-1><B>MAILPATH</B>
- </FONT>
- variable is not set,
- <B>bash</B>
- informs the user of the arrival of mail in the specified file or
- Maildir-format directory.
- <DT><B>MAILCHECK</B>
- <DD>
- Specifies how
- often (in seconds)
- <B>bash</B>
- checks for mail. The default is 60 seconds. When it is time to check
- for mail, the shell does so before displaying the primary prompt.
- If this variable is unset, or set to a value that is not a number
- greater than or equal to zero, the shell disables mail checking.
- <DT><B>MAILPATH</B>
- <DD>
- A colon-separated list of filenames to be checked for mail.
- The message to be printed when mail arrives in a particular file
- may be specified by separating the filename from the message with a `?'.
- When used in the text of the message, <B>$_</B> expands to the name of
- the current mailfile.
- Example:
- <DL COMPACT><DT><DD>
- <P>
- <B>MAILPATH</B>=aq/var/mail/bfox?"You have mail":~/shell-mail?"$_ has mail!"aq
- <P>
- <B>Bash</B>
- can be configured to supply
- a default value for this variable (there is no value by default),
- but the location of the user
- mail files that it uses is system dependent (e.g., /var/mail/<B>$USER</B>).
- </DL>
- <DT><B>OPTERR</B>
- <DD>
- If set to the value 1,
- <B>bash</B>
- displays error messages generated by the
- <B>getopts</B>
- builtin command (see
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below).
- <FONT SIZE=-1><B>OPTERR</B>
- </FONT>
- is initialized to 1 each time the shell is invoked or a shell
- script is executed.
- <DT><B>PATH</B>
- <DD>
- The search path for commands. It
- is a colon-separated list of directories in which
- the shell looks for commands (see
- <FONT SIZE=-1><B>COMMAND EXECUTION</B>
- </FONT>
- below).
- A zero-length (null) directory name in the value of
- <FONT SIZE=-1><B>PATH</B>
- </FONT>
- indicates the current directory.
- A null directory name may appear as two adjacent colons, or as an initial
- or trailing colon.
- The default path is system-dependent,
- and is set by the administrator who installs
- <B>bash</B>.
- A common value is
- <TT>/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin:/bin:/sbin</TT>.
- <DT><B>POSIXLY_CORRECT</B>
- <DD>
- If this variable is in the environment when <B>bash</B> starts, the shell
- enters <I>posix mode</I> before reading the startup files, as if the
- <B>--posix</B>
- invocation option had been supplied. If it is set while the shell is
- running, <B>bash</B> enables <I>posix mode</I>, as if the command
- <TT>set -o posix</TT>
- had been executed.
- <DT><B>PROMPT_COMMAND</B>
- <DD>
- If set, the value is executed as a command prior to issuing each primary
- prompt.
- <DT><B>PROMPT_DIRTRIM</B>
- <DD>
- If set to a number greater than zero, the value is used as the number of
- trailing directory components to retain when expanding the <B>\w</B> and
- <B>\W</B> prompt string escapes (see
- <FONT SIZE=-1><B>PROMPTING</B>
- </FONT>
- below). Characters removed are replaced with an ellipsis.
- <DT><B>PS0</B>
- <DD>
- The value of this parameter is expanded (see
- <FONT SIZE=-1><B>PROMPTING</B>
- </FONT>
- below) and displayed by interactive shells after reading a command
- and before the command is executed.
- <DT><B>PS1</B>
- <DD>
- The value of this parameter is expanded (see
- <FONT SIZE=-1><B>PROMPTING</B>
- </FONT>
- below) and used as the primary prompt string. The default value is
- ``<B>\s-\v\$ </B>''.
- <DT><B>PS2</B>
- <DD>
- The value of this parameter is expanded as with
- <FONT SIZE=-1><B>PS1</B>
- </FONT>
- and used as the secondary prompt string. The default is
- ``<B>> </B>''.
- <DT><B>PS3</B>
- <DD>
- The value of this parameter is used as the prompt for the
- <B>select</B>
- command (see
- <FONT SIZE=-1><B>SHELL GRAMMAR</B>
- </FONT>
- above).
- <DT><B>PS4</B>
- <DD>
- The value of this parameter is expanded as with
- <FONT SIZE=-1><B>PS1</B>
- </FONT>
- and the value is printed before each command
- <B>bash</B>
- displays during an execution trace. The first character of
- <FONT SIZE=-1><B>PS4</B>
- </FONT>
- is replicated multiple times, as necessary, to indicate multiple
- levels of indirection. The default is ``<B>+ </B>''.
- <DT><B>SHELL</B>
- <DD>
- The full pathname to the shell is kept in this environment variable.
- If it is not set when the shell starts,
- <B>bash</B>
- assigns to it the full pathname of the current user's login shell.
- <DT><B>TIMEFORMAT</B>
- <DD>
- The value of this parameter is used as a format string specifying
- how the timing information for pipelines prefixed with the
- <B>time</B>
- reserved word should be displayed.
- The <B>%</B> character introduces an escape sequence that is
- expanded to a time value or other information.
- The escape sequences and their meanings are as follows; the
- braces denote optional portions.
- <P>
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>%%</B>
- <DD>
- A literal <B>%</B>.
- <DT><B>%[</B><I>p</I>][l]R
- <DD>
- The elapsed time in seconds.
- <DT><B>%[</B><I>p</I>][l]U
- <DD>
- The number of CPU seconds spent in user mode.
- <DT><B>%[</B><I>p</I>][l]S
- <DD>
- The number of CPU seconds spent in system mode.
- <DT><B>%P</B>
- <DD>
- The CPU percentage, computed as (%U + %S) / %R.
- </DL></DL>
- <DT><DD>
- The optional <I>p</I> is a digit specifying the <I>precision</I>,
- the number of fractional digits after a decimal point.
- A value of 0 causes no decimal point or fraction to be output.
- At most three places after the decimal point may be specified;
- values of <I>p</I> greater than 3 are changed to 3.
- If <I>p</I> is not specified, the value 3 is used.
- <DT><DD>
- The optional <B>l</B> specifies a longer format, including
- minutes, of the form <I>MM</I>m<I>SS</I>.<I>FF</I>s.
- The value of <I>p</I> determines whether or not the fraction is
- included.
- <DT><DD>
- If this variable is not set, <B>bash</B> acts as if it had the
- value <B>$aq\nreal\t%3lR\nuser\t%3lU\nsys\t%3lSaq</B>.
- If the value is null, no timing information is displayed.
- A trailing newline is added when the format string is displayed.
- <DT><B>TMOUT</B>
- <DD>
- If set to a value greater than zero,
- <FONT SIZE=-1><B>TMOUT</B>
- </FONT>
- is treated as the
- default timeout for the <B>read</B> builtin.
- The <B>select</B> command terminates if input does not arrive
- after
- <FONT SIZE=-1><B>TMOUT</B>
- </FONT>
- seconds when input is coming from a terminal.
- In an interactive shell, the value is interpreted as the
- number of seconds to wait for a line of input after issuing the
- primary prompt.
- <B>Bash</B>
- terminates after waiting for that number of seconds if a complete
- line of input does not arrive.
- <DT><B>TMPDIR</B>
- <DD>
- If set, <B>bash</B> uses its value as the name of a directory in which
- <B>bash</B> creates temporary files for the shell's use.
- <DT><B>auto_resume</B>
- <DD>
- This variable controls how the shell interacts with the user and
- job control. If this variable is set, single word simple
- commands without redirections are treated as candidates for resumption
- of an existing stopped job. There is no ambiguity allowed; if there is
- more than one job beginning with the string typed, the job most recently
- accessed is selected. The
- <I>name</I>
- of a stopped job, in this context, is the command line used to
- start it.
- If set to the value
- <I>exact</I>,
- the string supplied must match the name of a stopped job exactly;
- if set to
- <I>substring</I>,
- the string supplied needs to match a substring of the name of a
- stopped job. The
- <I>substring</I>
- value provides functionality analogous to the
- <B>%?</B>
- job identifier (see
- <FONT SIZE=-1><B>JOB CONTROL</B>
- </FONT>
- below). If set to any other value, the supplied string must
- be a prefix of a stopped job's name; this provides functionality
- analogous to the <B>%</B><I>string</I> job identifier.
- <DT><B>histchars</B>
- <DD>
- The two or three characters which control history expansion
- and tokenization (see
- <FONT SIZE=-1><B>HISTORY EXPANSION</B>
- </FONT>
- below). The first character is the <I>history expansion</I> character,
- the character which signals the start of a history
- expansion, normally `<B>!</B>'.
- The second character is the <I>quick substitution</I>
- character, which is used as shorthand for re-running the previous
- command entered, substituting one string for another in the command.
- The default is `<B>^</B>'.
- The optional third character is the character
- which indicates that the remainder of the line is a comment when found
- as the first character of a word, normally `<B>#</B>'. The history
- comment character causes history substitution to be skipped for the
- remaining words on the line. It does not necessarily cause the shell
- parser to treat the rest of the line as a comment.
- </DL>
- <A NAME="lbAX"> </A>
- <H4>Arrays</H4>
- <B>Bash</B>
- provides one-dimensional indexed and associative array variables.
- Any variable may be used as an indexed array; the
- <B>declare</B>
- builtin will explicitly declare an array.
- There is no maximum
- limit on the size of an array, nor any requirement that members
- be indexed or assigned contiguously.
- Indexed arrays are referenced using integers (including arithmetic
- expressions) and are zero-based; associative arrays are referenced
- using arbitrary strings.
- Unless otherwise noted, indexed array indices must be non-negative integers.
- <P>
- An indexed array is created automatically if any variable is assigned to
- using the syntax <I>name</I>[<I>subscript</I>]=<I>value</I>. The
- <I>subscript</I>
- is treated as an arithmetic expression that must evaluate to a number.
- To explicitly declare an indexed array, use
- <B>declare -a </B><I>name</I>
- (see
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below).
- <B>declare -a </B><I>name</I>[<I>subscript</I>]
- is also accepted; the <I>subscript</I> is ignored.
- <P>
- Associative arrays are created using
- <B>declare -A </B><I>name</I>.
- <P>
- Attributes may be
- specified for an array variable using the
- <B>declare</B>
- and
- <B>readonly</B>
- builtins. Each attribute applies to all members of an array.
- <P>
- Arrays are assigned to using compound assignments of the form
- <I>name</I>=<B>(</B>value<I>1</I> ... value<I>n</I><B>)</B>, where each
- <I>value</I> is of the form [<I>subscript</I>]=<I>string</I>.
- Indexed array assignments do not require anything but <I>string</I>.
- When assigning to indexed arrays, if the optional brackets and subscript
- are supplied, that index is assigned to;
- otherwise the index of the element assigned is the last index assigned
- to by the statement plus one. Indexing starts at zero.
- <P>
- When assigning to an associative array, the subscript is required.
- <P>
- This syntax is also accepted by the
- <B>declare</B>
- builtin. Individual array elements may be assigned to using the
- <I>name</I>[<I>subscript</I>]=<I>value</I> syntax introduced above.
- When assigning to an indexed array, if
- <I>name</I>
- is subscripted by a negative number, that number is
- interpreted as relative to one greater than the maximum index of
- <I>name</I>, so negative indices count back from the end of the
- array, and an index of -1 references the last element.
- <P>
- Any element of an array may be referenced using
- ${<I>name</I>[<I>subscript</I>]}. The braces are required to avoid
- conflicts with pathname expansion. If
- <I>subscript</I> is <B>@</B> or <B>*</B>, the word expands to
- all members of <I>name</I>. These subscripts differ only when the
- word appears within double quotes. If the word is double-quoted,
- ${<I>name</I>[*]} expands to a single
- word with the value of each array member separated by the first
- character of the
- <FONT SIZE=-1><B>IFS</B>
- </FONT>
- special variable, and ${<I>name</I>[@]} expands each element of
- <I>name</I> to a separate word. When there are no array members,
- ${<I>name</I>[@]} expands to nothing.
- If the double-quoted expansion occurs within a word, the expansion of
- the first parameter is joined with the beginning part of the original
- word, and the expansion of the last parameter is joined with the last
- part of the original word.
- This is analogous to the expansion
- of the special parameters <B>*</B> and <B>@</B> (see
- <B>Special Parameters</B>
- above). ${#<I>name</I>[<I>subscript</I>]} expands to the length of
- ${<I>name</I>[<I>subscript</I>]}. If <I>subscript</I> is <B>*</B> or
- <B>@</B>, the expansion is the number of elements in the array.
- If the
- <I>subscript</I>
- used to reference an element of an indexed array
- evaluates to a number less than zero, it is
- interpreted as relative to one greater than the maximum index of the array,
- so negative indices count back from the end of the
- array, and an index of -1 references the last element.
- <P>
- Referencing an array variable without a subscript is equivalent to
- referencing the array with a subscript of 0.
- Any reference to a variable using a valid subscript is legal, and
- <B>bash</B>
- will create an array if necessary.
- <P>
- An array variable is considered set if a subscript has been assigned a
- value. The null string is a valid value.
- <P>
- It is possible to obtain the keys (indices) of an array as well as the values.
- ${<B>!</B><I>name</I>[<I>@</I>]} and ${<B>!</B><I>name</I>[<I>*</I>]}
- expand to the indices assigned in array variable <I>name</I>.
- The treatment when in double quotes is similar to the expansion of the
- special parameters <I>@</I> and <I>*</I> within double quotes.
- <P>
- The
- <B>unset</B>
- builtin is used to destroy arrays. <B>unset</B> <I>name</I>[<I>subscript</I>]
- destroys the array element at index <I>subscript</I>.
- Negative subscripts to indexed arrays are interpreted as described above.
- Care must be taken to avoid unwanted side effects caused by pathname
- expansion.
- <B>unset</B> <I>name</I>, where <I>name</I> is an array, or
- <B>unset</B> <I>name</I>[<I>subscript</I>], where
- <I>subscript</I> is <B>*</B> or <B>@</B>, removes the entire array.
- <P>
- The
- <B>declare</B>,
- <B>local</B>,
- and
- <B>readonly</B>
- builtins each accept a
- <B>-a</B>
- option to specify an indexed array and a
- <B>-A</B>
- option to specify an associative array.
- If both options are supplied,
- <B>-A</B>
- takes precedence.
- The
- <B>read</B>
- builtin accepts a
- <B>-a</B>
- option to assign a list of words read from the standard input
- to an array. The
- <B>set</B>
- and
- <B>declare</B>
- builtins display array values in a way that allows them to be
- reused as assignments.
- <A NAME="lbAY"> </A>
- <H3>EXPANSION</H3>
- Expansion is performed on the command line after it has been split into
- words. There are seven kinds of expansion performed:
- <I>brace expansion</I>,
- <I>tilde expansion</I>,
- <I>parameter and variable expansion</I>,
- <I>command substitution</I>,
- <I>arithmetic expansion</I>,
- <I>word splitting</I>,
- and
- <I>pathname expansion</I>.
- <P>
- The order of expansions is:
- brace expansion;
- tilde expansion, parameter and variable expansion, arithmetic expansion,
- and command substitution (done in a left-to-right fashion);
- word splitting;
- and pathname expansion.
- <P>
- On systems that can support it, there is an additional expansion
- available: <I>process substitution</I>.
- This is performed at the
- same time as tilde, parameter, variable, and arithmetic expansion and
- command substitution.
- <P>
- After these expansions are performed, quote characters present in the
- original word are removed unless they have been quoted themselves
- (<I>quote removal</I>).
- <P>
- Only brace expansion, word splitting, and pathname expansion
- can change the number of words of the expansion; other expansions
- expand a single word to a single word.
- The only exceptions to this are the expansions of
- "<B>$@</B>" and "<B>${</B><I>name</I><B>[@]}</B>"
- as explained above (see
- <FONT SIZE=-1><B>PARAMETERS</B>).
- </FONT>
- <A NAME="lbAZ"> </A>
- <H4>Brace Expansion</H4>
- <P>
- <I>Brace expansion</I>
- is a mechanism by which arbitrary strings
- may be generated. This mechanism is similar to
- <I>pathname expansion</I>, but the filenames generated
- need not exist. Patterns to be brace expanded take
- the form of an optional
- <I>preamble</I>,
- followed by either a series of comma-separated strings or
- a sequence expression between a pair of braces, followed by
- an optional
- <I>postscript</I>.
- The preamble is prefixed to each string contained
- within the braces, and the postscript is then appended
- to each resulting string, expanding left to right.
- <P>
- Brace expansions may be nested. The results of each expanded
- string are not sorted; left to right order is preserved.
- For example, a<B>{</B>d,c,b<B>}</B>e expands into `ade ace abe'.
- <P>
- A sequence expression takes the form
- <B>{</B><I>x</I><B>..</B><I>y</I><B>[..</B><I>incr</I><B>]}</B>,
- where <I>x</I> and <I>y</I> are either integers or single characters,
- and <I>incr</I>, an optional increment, is an integer.
- When integers are supplied, the expression expands to each number between
- <I>x</I> and <I>y</I>, inclusive.
- Supplied integers may be prefixed with <I>0</I> to force each term to have the
- same width.
- When either <I>x</I> or y begins with a zero, the shell
- attempts to force all generated terms to contain the same number of digits,
- zero-padding where necessary.
- When characters are supplied, the expression expands to each character
- lexicographically between <I>x</I> and <I>y</I>, inclusive,
- using the default C locale.
- Note that both <I>x</I> and <I>y</I> must be of the same type.
- When the increment is supplied, it is used as the difference between
- each term. The default increment is 1 or -1 as appropriate.
- <P>
- Brace expansion is performed before any other expansions,
- and any characters special to other expansions are preserved
- in the result. It is strictly textual.
- <B>Bash</B>
- does not apply any syntactic interpretation to the context of the
- expansion or the text between the braces.
- <P>
- A correctly-formed brace expansion must contain unquoted opening
- and closing braces, and at least one unquoted comma or a valid
- sequence expression.
- Any incorrectly formed brace expansion is left unchanged.
- A <B>{</B> or <B>,</B> may be quoted with a backslash to prevent its
- being considered part of a brace expression.
- To avoid conflicts with parameter expansion, the string <B>${</B>
- is not considered eligible for brace expansion.
- <P>
- This construct is typically used as shorthand when the common
- prefix of the strings to be generated is longer than in the
- above example:
- <DL COMPACT><DT><DD>
- <P>
- mkdir /usr/local/src/bash/{old,new,dist,bugs}
- </DL>
- or
- <DL COMPACT><DT><DD>
- chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}}
- </DL>
- <P>
- Brace expansion introduces a slight incompatibility with
- historical versions of
- <B>sh</B>.
- <B>sh</B>
- does not treat opening or closing braces specially when they
- appear as part of a word, and preserves them in the output.
- <B>Bash</B>
- removes braces from words as a consequence of brace
- expansion. For example, a word entered to
- <B>sh</B>
- as <I>file{1,2}</I>
- appears identically in the output. The same word is
- output as
- <I>file1 file2</I>
- after expansion by
- <B>bash</B>.
- If strict compatibility with
- <B>sh</B>
- is desired, start
- <B>bash</B>
- with the
- <B>+B</B>
- option or disable brace expansion with the
- <B>+B</B>
- option to the
- <B>set</B>
- command (see
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below).
- <A NAME="lbBA"> </A>
- <H4>Tilde Expansion</H4>
- <P>
- If a word begins with an unquoted tilde character (`<B>~</B>'), all of
- the characters preceding the first unquoted slash (or all characters,
- if there is no unquoted slash) are considered a <I>tilde-prefix</I>.
- If none of the characters in the tilde-prefix are quoted, the
- characters in the tilde-prefix following the tilde are treated as a
- possible <I>login name</I>.
- If this login name is the null string, the tilde is replaced with the
- value of the shell parameter
- <FONT SIZE=-1><B>HOME</B>.
- </FONT>
- If
- <FONT SIZE=-1><B>HOME</B>
- </FONT>
- is unset, the home directory of the user executing the shell is
- substituted instead.
- Otherwise, the tilde-prefix is replaced with the home directory
- associated with the specified login name.
- <P>
- If the tilde-prefix is a `~+', the value of the shell variable
- <FONT SIZE=-1><B>PWD</B>
- </FONT>
- replaces the tilde-prefix.
- If the tilde-prefix is a `~-', the value of the shell variable
- <FONT SIZE=-1><B>OLDPWD</B>,
- </FONT>
- if it is set, is substituted.
- If the characters following the tilde in the tilde-prefix consist
- of a number <I>N</I>, optionally prefixed
- by a `+' or a `-', the tilde-prefix is replaced with the corresponding
- element from the directory stack, as it would be displayed by the
- <B>dirs</B>
- builtin invoked with the tilde-prefix as an argument.
- If the characters following the tilde in the tilde-prefix consist of a
- number without a leading `+' or `-', `+' is assumed.
- <P>
- If the login name is invalid, or the tilde expansion fails, the word
- is unchanged.
- <P>
- Each variable assignment is checked for unquoted tilde-prefixes immediately
- following a
- <B>:</B>
- or the first
- <B>=</B>.
- In these cases, tilde expansion is also performed.
- Consequently, one may use filenames with tildes in assignments to
- <FONT SIZE=-1><B>PATH</B>,
- </FONT>
- <FONT SIZE=-1><B>MAILPATH</B>,
- </FONT>
- and
- <FONT SIZE=-1><B>CDPATH</B>,
- </FONT>
- and the shell assigns the expanded value.
- <A NAME="lbBB"> </A>
- <H4>Parameter Expansion</H4>
- <P>
- The `<B>$</B>' character introduces parameter expansion,
- command substitution, or arithmetic expansion. The parameter name
- or symbol to be expanded may be enclosed in braces, which
- are optional but serve to protect the variable to be expanded from
- characters immediately following it which could be
- interpreted as part of the name.
- <P>
- When braces are used, the matching ending brace is the first `<B>}</B>'
- not escaped by a backslash or within a quoted string, and not within an
- embedded arithmetic expansion, command substitution, or parameter
- expansion.
- <P>
- <DL COMPACT>
- <DT>${<I>parameter</I>}<DD>
- The value of <I>parameter</I> is substituted. The braces are required
- when
- <I>parameter</I>
- is a positional parameter with more than one digit,
- or when
- <I>parameter</I>
- is followed by a character which is not to be
- interpreted as part of its name.
- The <I>parameter</I> is a shell parameter as described above
- <B>PARAMETERS</B>) or an array reference (<B>Arrays</B>).
- </DL>
- <P>
- If the first character of <I>parameter</I> is an exclamation point (<B>!</B>),
- and <I>parameter</I> is not a <I>nameref</I>,
- it introduces a level of variable indirection.
- <B>Bash</B> uses the value of the variable formed from the rest of
- <I>parameter</I> as the name of the variable; this variable is then
- expanded and that value is used in the rest of the substitution, rather
- than the value of <I>parameter</I> itself.
- This is known as <I>indirect expansion</I>.
- If <I>parameter</I> is a nameref, this expands to the name of the
- variable referenced by <I>parameter</I> instead of performing the
- complete indirect expansion.
- The exceptions to this are the expansions of ${<B>!</B><I>prefix</I><B>*</B>} and
- ${<B>!</B><I>name</I>[<I>@</I>]} described below.
- The exclamation point must immediately follow the left brace in order to
- introduce indirection.
- <P>
- In each of the cases below, <I>word</I> is subject to tilde expansion,
- parameter expansion, command substitution, and arithmetic expansion.
- <P>
- When not performing substring expansion, using the forms documented below
- (e.g., <B>:-</B>),
- <B>bash</B> tests for a parameter that is unset or null. Omitting the colon
- results in a test only for a parameter that is unset.
- <P>
- <DL COMPACT>
- <DT>${<I>parameter</I><B>:-</B><I>word</I>}<DD>
- <B>Use Default Values</B>. If
- <I>parameter</I>
- is unset or null, the expansion of
- <I>word</I>
- is substituted. Otherwise, the value of
- <I>parameter</I>
- is substituted.
- <DT>${<I>parameter</I><B>:=</B><I>word</I>}<DD>
- <B>Assign Default Values</B>.
- If
- <I>parameter</I>
- is unset or null, the expansion of
- <I>word</I>
- is assigned to
- <I>parameter</I>.
- The value of
- <I>parameter</I>
- is then substituted. Positional parameters and special parameters may
- not be assigned to in this way.
- <DT>${<I>parameter</I><B>:?</B><I>word</I>}<DD>
- <B>Display Error if Null or Unset</B>.
- If
- <I>parameter</I>
- is null or unset, the expansion of <I>word</I> (or a message to that effect
- if
- <I>word</I>
- is not present) is written to the standard error and the shell, if it
- is not interactive, exits. Otherwise, the value of <I>parameter</I> is
- substituted.
- <DT>${<I>parameter</I><B>:+</B><I>word</I>}<DD>
- <B>Use Alternate Value</B>.
- If
- <I>parameter</I>
- is null or unset, nothing is substituted, otherwise the expansion of
- <I>word</I>
- is substituted.
- <DT>${<I>parameter</I><B>:</B><I>offset</I>}<DD>
- <DT>${<I>parameter</I><B>:</B><I>offset</I><B>:</B><I>length</I>}<DD>
- <B>Substring Expansion</B>.
- Expands to up to <I>length</I> characters of the value of <I>parameter</I>
- starting at the character specified by <I>offset</I>.
- If <I>parameter</I> is <B>@</B>, an indexed array subscripted by
- <B>@</B> or <B>*</B>, or an associative array name, the results differ as
- described below.
- If <I>length</I> is omitted, expands to the substring of the value of
- <I>parameter</I> starting at the character specified by <I>offset</I>
- and extending to the end of the value.
- <I>length</I> and <I>offset</I> are arithmetic expressions (see
- <FONT SIZE=-1><B>ARITHMETIC EVALUATION</B>
- </FONT>
- below).
- <P>
- If <I>offset</I> evaluates to a number less than zero, the value
- is used as an offset in characters
- from the end of the value of <I>parameter</I>.
- If <I>length</I> evaluates to a number less than zero,
- it is interpreted as an offset in characters
- from the end of the value of <I>parameter</I> rather than
- a number of characters, and the expansion is the characters between
- <I>offset</I> and that result.
- Note that a negative offset must be separated from the colon by at least
- one space to avoid being confused with the <B>:-</B> expansion.
- <P>
- If <I>parameter</I> is <B>@</B>, the result is <I>length</I> positional
- parameters beginning at <I>offset</I>.
- A negative <I>offset</I> is taken relative to one greater than the greatest
- positional parameter, so an offset of -1 evaluates to the last positional
- parameter.
- It is an expansion error if <I>length</I> evaluates to a number less than
- zero.
- <P>
- If <I>parameter</I> is an indexed array name subscripted by @ or *,
- the result is the <I>length</I>
- members of the array beginning with ${<I>parameter</I>[<I>offset</I>]}.
- A negative <I>offset</I> is taken relative to one greater than the maximum
- index of the specified array.
- It is an expansion error if <I>length</I> evaluates to a number less than
- zero.
- <P>
- Substring expansion applied to an associative array produces undefined
- results.
- <P>
- Substring indexing is zero-based unless the positional parameters
- are used, in which case the indexing starts at 1 by default.
- If <I>offset</I> is 0, and the positional parameters are used, <B>$0</B> is
- prefixed to the list.
- <DT>${<B>!</B><I>prefix</I><B>*</B>}<DD>
- <DT>${<B>!</B><I>prefix</I><B>@</B>}<DD>
- <B>Names matching prefix</B>.
- Expands to the names of variables whose names begin with <I>prefix</I>,
- separated by the first character of the
- <FONT SIZE=-1><B>IFS</B>
- </FONT>
- special variable.
- When <I>@</I> is used and the expansion appears within double quotes, each
- variable name expands to a separate word.
- <DT>${<B>!</B><I>name</I>[<I>@</I>]}<DD>
- <DT>${<B>!</B><I>name</I>[<I>*</I>]}<DD>
- <B>List of array keys</B>.
- If <I>name</I> is an array variable, expands to the list of array indices
- (keys) assigned in <I>name</I>.
- If <I>name</I> is not an array, expands to 0 if <I>name</I> is set and null
- otherwise.
- When <I>@</I> is used and the expansion appears within double quotes, each
- key expands to a separate word.
- <DT>${<B>#</B><I>parameter</I>}<DD>
- <B>Parameter length</B>.
- The length in characters of the value of <I>parameter</I> is substituted.
- If
- <I>parameter</I>
- is
- <B>*</B>
- or
- <B>@</B>,
- the value substituted is the number of positional parameters.
- If
- <I>parameter</I>
- is an array name subscripted by
- <B>*</B>
- or
- <B>@</B>,
- the value substituted is the number of elements in the array.
- If
- <I>parameter</I>
- is an indexed array name subscripted by a negative number, that number is
- interpreted as relative to one greater than the maximum index of
- <I>parameter</I>, so negative indices count back from the end of the
- array, and an index of -1 references the last element.
- <DT>${<I>parameter</I><B>#</B><I>word</I>}<DD>
- <DT>${<I>parameter</I><B>##</B><I>word</I>}<DD>
- <B>Remove matching prefix pattern</B>.
- The
- <I>word</I>
- is expanded to produce a pattern just as in pathname
- expansion. If the pattern matches the beginning of
- the value of
- <I>parameter</I>,
- then the result of the expansion is the expanded value of
- <I>parameter</I>
- with the shortest matching pattern (the ``<B>#</B>'' case) or the
- longest matching pattern (the ``<B>##</B>'' case) deleted.
- If
- <I>parameter</I>
- is
- <B>@</B>
- or
- <B>*</B>,
- the pattern removal operation is applied to each positional
- parameter in turn, and the expansion is the resultant list.
- If
- <I>parameter</I>
- is an array variable subscripted with
- <B>@</B>
- or
- <B>*</B>,
- the pattern removal operation is applied to each member of the
- array in turn, and the expansion is the resultant list.
- <DT>${<I>parameter</I><B>%</B><I>word</I>}<DD>
- <DT>${<I>parameter</I><B>%%</B><I>word</I>}<DD>
- <B>Remove matching suffix pattern</B>.
- The <I>word</I> is expanded to produce a pattern just as in
- pathname expansion.
- If the pattern matches a trailing portion of the expanded value of
- <I>parameter</I>,
- then the result of the expansion is the expanded value of
- <I>parameter</I>
- with the shortest matching pattern (the ``<B>%</B>'' case) or the
- longest matching pattern (the ``<B>%%</B>'' case) deleted.
- If
- <I>parameter</I>
- is
- <B>@</B>
- or
- <B>*</B>,
- the pattern removal operation is applied to each positional
- parameter in turn, and the expansion is the resultant list.
- If
- <I>parameter</I>
- is an array variable subscripted with
- <B>@</B>
- or
- <B>*</B>,
- the pattern removal operation is applied to each member of the
- array in turn, and the expansion is the resultant list.
- <DT>${<I>parameter</I><B>/</B><I>pattern</I><B>/</B><I>string</I>}<DD>
- <B>Pattern substitution</B>.
- The <I>pattern</I> is expanded to produce a pattern just as in
- pathname expansion.
- <I>Parameter</I> is expanded and the longest match of <I>pattern</I>
- against its value is replaced with <I>string</I>.
- If <I>pattern</I> begins with <B>/</B>, all matches of <I>pattern</I> are
- replaced with <I>string</I>. Normally only the first match is replaced.
- If <I>pattern</I> begins with <B>#</B>, it must match at the beginning
- of the expanded value of <I>parameter</I>.
- If <I>pattern</I> begins with <B>%</B>, it must match at the end
- of the expanded value of <I>parameter</I>.
- If <I>string</I> is null, matches of <I>pattern</I> are deleted
- and the <B>/</B> following <I>pattern</I> may be omitted.
- If the
- <B>nocasematch</B>
- shell option is enabled, the match is performed without regard to the case
- of alphabetic characters.
- If
- <I>parameter</I>
- is
- <B>@</B>
- or
- <B>*</B>,
- the substitution operation is applied to each positional
- parameter in turn, and the expansion is the resultant list.
- If
- <I>parameter</I>
- is an array variable subscripted with
- <B>@</B>
- or
- <B>*</B>,
- the substitution operation is applied to each member of the
- array in turn, and the expansion is the resultant list.
- <DT>${<I>parameter</I><B>^</B><I>pattern</I>}<DD>
- <DT>${<I>parameter</I><B>^^</B><I>pattern</I>}<DD>
- <DT>${<I>parameter</I><B>,</B><I>pattern</I>}<DD>
- <DT>${<I>parameter</I><B>,,</B><I>pattern</I>}<DD>
- <B>Case modification</B>.
- This expansion modifies the case of alphabetic characters in <I>parameter</I>.
- The <I>pattern</I> is expanded to produce a pattern just as in
- pathname expansion.
- Each character in the expanded value of <I>parameter</I> is tested against
- <I>pattern</I>, and, if it matches the pattern, its case is converted.
- The pattern should not attempt to match more than one character.
- The <B>^</B> operator converts lowercase letters matching <I>pattern</I>
- to uppercase; the <B>,</B> operator converts matching uppercase letters
- to lowercase.
- The <B>^^</B> and <B>,,</B> expansions convert each matched character in the
- expanded value; the <B>^</B> and <B>,</B> expansions match and convert only
- the first character in the expanded value.
- If <I>pattern</I> is omitted, it is treated like a <B>?</B>, which matches
- every character.
- If
- <I>parameter</I>
- is
- <B>@</B>
- or
- <B>*</B>,
- the case modification operation is applied to each positional
- parameter in turn, and the expansion is the resultant list.
- If
- <I>parameter</I>
- is an array variable subscripted with
- <B>@</B>
- or
- <B>*</B>,
- the case modification operation is applied to each member of the
- array in turn, and the expansion is the resultant list.
- <DT>${<I>parameter</I><B>@</B><I>operator</I>}<DD>
- <B>Parameter transformation</B>.
- The expansion is either a transformation of the value of <I>parameter</I>
- or information about <I>parameter</I> itself, depending on the value of
- <I>operator</I>. Each <I>operator</I> is a single letter:
- <P>
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>Q</B>
- <DD>
- The expansion is a string that is the value of <I>parameter</I> quoted in a
- format that can be reused as input.
- <DT><B>E</B>
- <DD>
- The expansion is a string that is the value of <I>parameter</I> with backslash
- escape sequences expanded as with the <B>$'...'</B> quoting mechansim.
- <DT><B>P</B>
- <DD>
- The expansion is a string that is the result of expanding the value of
- <I>parameter</I> as if it were a prompt string (see <B>PROMPTING</B> below).
- <DT><B>A</B>
- <DD>
- The expansion is a string in the form of
- an assignment statement or <B>declare</B> command that, if
- evaluated, will recreate <I>parameter</I> with its attributes and value.
- <DT><B>a</B>
- <DD>
- The expansion is a string consisting of flag values representing
- <I>parameter</I>'s attributes.
- </DL>
- <P>
- If
- <I>parameter</I>
- is
- <B>@</B>
- or
- <B>*</B>,
- the operation is applied to each positional
- parameter in turn, and the expansion is the resultant list.
- If
- <I>parameter</I>
- is an array variable subscripted with
- <B>@</B>
- or
- <B>*</B>,
- the case modification operation is applied to each member of the
- array in turn, and the expansion is the resultant list.
- <P>
- The result of the expansion is subject to word splitting and pathname
- expansion as described below.
- </DL>
- </DL>
- <A NAME="lbBC"> </A>
- <H4>Command Substitution</H4>
- <P>
- <I>Command substitution</I> allows the output of a command to replace
- the command name. There are two forms:
- <DL COMPACT><DT><DD>
- <P>
- <B>$(</B><I>command</I><B>)</B>
- </DL>
- or
- <DL COMPACT><DT><DD>
- <B>`</B><I>command</I><B>`</B>
- </DL>
- <P>
- <B>Bash</B>
- performs the expansion by executing <I>command</I> in a subshell environment
- and replacing the command substitution with the standard output of the
- command, with any trailing newlines deleted.
- Embedded newlines are not deleted, but they may be removed during
- word splitting.
- The command substitution <B>$(cat </B><I>file</I>) can be replaced by
- the equivalent but faster <B>$(< </B><I>file</I>).
- <P>
- When the old-style backquote form of substitution is used,
- backslash retains its literal meaning except when followed by
- <B>$</B>,
- <B>`</B>,
- or
- <B>\</B>.
- The first backquote not preceded by a backslash terminates the
- command substitution.
- When using the $(<I>command</I>) form, all characters between the
- parentheses make up the command; none are treated specially.
- <P>
- Command substitutions may be nested. To nest when using the backquoted form,
- escape the inner backquotes with backslashes.
- <P>
- If the substitution appears within double quotes, word splitting and
- pathname expansion are not performed on the results.
- <A NAME="lbBD"> </A>
- <H4>Arithmetic Expansion</H4>
- <P>
- Arithmetic expansion allows the evaluation of an arithmetic expression
- and the substitution of the result. The format for arithmetic expansion is:
- <DL COMPACT><DT><DD>
- <P>
- <B>$((</B><I>expression</I><B>))</B>
- </DL>
- <P>
- The
- <I>expression</I>
- is treated as if it were within double quotes, but a double quote
- inside the parentheses is not treated specially.
- All tokens in the expression undergo parameter and variable expansion,
- command substitution, and quote removal.
- The result is treated as the arithmetic expression to be evaluated.
- Arithmetic expansions may be nested.
- <P>
- The evaluation is performed according to the rules listed below under
- <FONT SIZE=-1><B>ARITHMETIC EVALUATION</B>.
- </FONT>
- If
- <I>expression</I>
- is invalid,
- <B>bash</B>
- prints a message indicating failure and no substitution occurs.
- <A NAME="lbBE"> </A>
- <H4>Process Substitution</H4>
- <P>
- <I>Process substitution</I> allows a process's input or output to be
- referred to using a filename.
- It takes the form of
- <B><(</B><I>list</I><B>)</B>
- or
- <B>>(</B><I>list</I><B>)</B>.
- The process <I>list</I> is run asynchronously, and its input or output
- appears as a filename.
- This filename is
- passed as an argument to the current command as the result of the
- expansion.
- If the <B>>(</B><I>list</I><B>)</B> form is used, writing to
- the file will provide input for <I>list</I>. If the
- <B><(</B><I>list</I><B>)</B> form is used, the file passed as an
- argument should be read to obtain the output of <I>list</I>.
- Process substitution is supported on systems that support named
- pipes (<I>FIFOs</I>) or the <B>/dev/fd</B> method of naming open files.
- <P>
- When available, process substitution is performed
- simultaneously with parameter and variable expansion,
- command substitution,
- and arithmetic expansion.
- <A NAME="lbBF"> </A>
- <H4>Word Splitting</H4>
- <P>
- The shell scans the results of
- parameter expansion,
- command substitution,
- and
- arithmetic expansion
- that did not occur within double quotes for
- <I>word splitting</I>.
- <P>
- The shell treats each character of
- <FONT SIZE=-1><B>IFS</B>
- </FONT>
- as a delimiter, and splits the results of the other
- expansions into words using these characters as field terminators.
- If
- <FONT SIZE=-1><B>IFS</B>
- </FONT>
- is unset, or its
- value is exactly
- <B><space><tab><newline></B>,
- the default, then
- sequences of
- <B><space></B>,
- <B><tab></B>,
- and
- <B><newline></B>
- at the beginning and end of the results of the previous
- expansions are ignored, and
- any sequence of
- <FONT SIZE=-1><B>IFS</B>
- </FONT>
- characters not at the beginning or end serves to delimit words.
- If
- <FONT SIZE=-1><B>IFS</B>
- </FONT>
- has a value other than the default, then sequences of
- the whitespace characters
- <B>space</B>,
- <B>tab</B>,
- and
- <B>newline</B>
- are ignored at the beginning and end of the
- word, as long as the whitespace character is in the
- value of
- <FONT SIZE=-1><B>IFS</B>
- </FONT>
- (an
- <FONT SIZE=-1><B>IFS</B>
- </FONT>
- whitespace character).
- Any character in
- <FONT SIZE=-1><B>IFS</B>
- </FONT>
- that is not
- <FONT SIZE=-1><B>IFS</B>
- </FONT>
- whitespace, along with any adjacent
- <FONT SIZE=-1><B>IFS</B>
- </FONT>
- whitespace characters, delimits a field.
- A sequence of
- <FONT SIZE=-1><B>IFS</B>
- </FONT>
- whitespace characters is also treated as a delimiter.
- If the value of
- <FONT SIZE=-1><B>IFS</B>
- </FONT>
- is null, no word splitting occurs.
- <P>
- Explicit null arguments (<B>""</B> or <B>aqaq</B>) are retained
- and passed to commands as empty strings.
- Unquoted implicit null arguments, resulting from the expansion of
- parameters that have no values, are removed.
- If a parameter with no value is expanded within double quotes, a
- null argument results and is retained
- and passed to a command as an empty string.
- When a quoted null argument appears as part of a word whose expansion is
- non-null, the null argument is removed.
- That is, the word
- <TT>-daqaq</TT> becomes <TT>-d</TT> after word splitting and
- null argument removal.
- <P>
- Note that if no expansion occurs, no splitting
- is performed.
- <A NAME="lbBG"> </A>
- <H4>Pathname Expansion</H4>
- <P>
- After word splitting,
- unless the
- <B>-f</B>
- option has been set,
- <B>bash</B>
- scans each word for the characters
- <B>*</B>,
- <B>?</B>,
- and
- <B>[</B>.
- If one of these characters appears, then the word is
- regarded as a
- <I>pattern</I>,
- and replaced with an alphabetically sorted list of
- filenames matching the pattern
- (see
- <FONT SIZE=-1><B>Pattern Matching</B>
- </FONT>
- below).
- If no matching filenames are found,
- and the shell option
- <B>nullglob</B>
- is not enabled, the word is left unchanged.
- If the
- <B>nullglob</B>
- option is set, and no matches are found,
- the word is removed.
- If the
- <B>failglob</B>
- shell option is set, and no matches are found, an error message
- is printed and the command is not executed.
- If the shell option
- <B>nocaseglob</B>
- is enabled, the match is performed without regard to the case
- of alphabetic characters.
- When a pattern is used for pathname expansion,
- the character
- <B>``.''</B>
- at the start of a name or immediately following a slash
- must be matched explicitly, unless the shell option
- <B>dotglob</B>
- is set.
- When matching a pathname, the slash character must always be
- matched explicitly.
- In other cases, the
- <B>``.''</B>
- character is not treated specially.
- See the description of
- <B>shopt</B>
- below under
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- for a description of the
- <B>nocaseglob</B>,
- <B>nullglob</B>,
- <B>failglob</B>,
- and
- <B>dotglob</B>
- shell options.
- <P>
- The
- <FONT SIZE=-1><B>GLOBIGNORE</B>
- </FONT>
- shell variable may be used to restrict the set of filenames matching a
- <I>pattern</I>.
- If
- <FONT SIZE=-1><B>GLOBIGNORE</B>
- </FONT>
- is set, each matching filename that also matches one of the patterns in
- <FONT SIZE=-1><B>GLOBIGNORE</B>
- </FONT>
- is removed from the list of matches.
- If the <B>nocaseglob</B> option is set, the matching against the patterns in
- <FONT SIZE=-1><B>GLOBIGNORE</B>
- </FONT>
- is performed without regard to case.
- The filenames
- <B>``.''</B>
- and
- <B>``..''</B>
- are always ignored when
- <FONT SIZE=-1><B>GLOBIGNORE</B>
- </FONT>
- is set and not null. However, setting
- <FONT SIZE=-1><B>GLOBIGNORE</B>
- </FONT>
- to a non-null value has the effect of enabling the
- <B>dotglob</B>
- shell option, so all other filenames beginning with a
- <B>``.''</B>
- will match.
- To get the old behavior of ignoring filenames beginning with a
- <B>``.''</B>,
- make
- <B>``.*''</B>
- one of the patterns in
- <FONT SIZE=-1><B>GLOBIGNORE</B>.
- </FONT>
- The
- <B>dotglob</B>
- option is disabled when
- <FONT SIZE=-1><B>GLOBIGNORE</B>
- </FONT>
- is unset.
- The pattern matching honors the setting of the <B>extglob</B> shell
- option.
- <P>
- <B>Pattern Matching</B>
- <P>
- Any character that appears in a pattern, other than the special pattern
- characters described below, matches itself. The NUL character may not
- occur in a pattern. A backslash escapes the following character; the
- escaping backslash is discarded when matching.
- The special pattern characters must be quoted if
- they are to be matched literally.
- <P>
- The special pattern characters have the following meanings:
- <P>
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>*</B>
- <DD>
- Matches any string, including the null string.
- When the <B>globstar</B> shell option is enabled, and <B>*</B> is used in
- a pathname expansion context, two adjacent <B>*</B>s used as a single
- pattern will match all files and zero or more directories and
- subdirectories.
- If followed by a <B>/</B>, two adjacent <B>*</B>s will match only directories
- and subdirectories.
- <DT><B>?</B>
- <DD>
- Matches any single character.
- <DT><B>[...]</B>
- <DD>
- Matches any one of the enclosed characters. A pair of characters
- separated by a hyphen denotes a
- <I>range expression</I>;
- any character that falls between those two characters, inclusive,
- using the current locale's collating sequence and character set,
- is matched. If the first character following the
- <B>[</B>
- is a
- <B>!</B>
- or a
- <B>^</B>
- then any character not enclosed is matched.
- The sorting order of characters in range expressions is determined by
- the current locale and the values of the
- <FONT SIZE=-1><B>LC_COLLATE</B>
- </FONT>
- or
- <FONT SIZE=-1><B>LC_ALL</B>
- </FONT>
- shell variables, if set.
- To obtain the traditional interpretation of range expressions, where
- <B>[a-d]</B>
- is equivalent to
- <B>[abcd]</B>,
- set value of the
- <B>LC_ALL</B>
- shell variable to
- <B>C</B>,
- or enable the
- <B>globasciiranges</B>
- shell option.
- A
- <B>-</B>
- may be matched by including it as the first or last character
- in the set.
- A
- <B>]</B>
- may be matched by including it as the first character
- in the set.
- <BR>
- <P>
- Within
- <B>[</B>
- and
- <B>]</B>,
- <I>character classes</I> can be specified using the syntax
- <B>[:</B><I>class</I><B>:]</B>, where <I>class</I> is one of the
- following classes defined in the POSIX standard:
- </DL>
- <P>
- <DL COMPACT><DT><DD>
- <B>
- </B>
- alnum alpha ascii blank cntrl digit graph lower print punct space upper word xdigit
- <BR>
- A character class matches any character belonging to that class.
- The <B>word</B> character class matches letters, digits, and the character _.
- <BR>
- <P>
- Within
- <B>[</B>
- and
- <B>]</B>,
- an <I>equivalence class</I> can be specified using the syntax
- <B>[=</B><I>c</I><B>=]</B>, which matches all characters with the
- same collation weight (as defined by the current locale) as
- the character <I>c</I>.
- <BR>
- <P>
- Within
- <B>[</B>
- and
- <B>]</B>,
- the syntax <B>[.</B><I>symbol</I><B>.]</B> matches the collating symbol
- <I>symbol</I>.
- </DL>
- </DL>
- <P>
- If the <B>extglob</B> shell option is enabled using the <B>shopt</B>
- builtin, several extended pattern matching operators are recognized.
- In the following description, a <I>pattern-list</I> is a list of one
- or more patterns separated by a <B>|</B>.
- Composite patterns may be formed using one or more of the following
- sub-patterns:
- <P>
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>?(</B><I>pattern-list</I><B>)</B><DD>
- Matches zero or one occurrence of the given patterns
- <DT><B>*(</B><I>pattern-list</I><B>)</B><DD>
- Matches zero or more occurrences of the given patterns
- <DT><B>+(</B><I>pattern-list</I><B>)</B><DD>
- Matches one or more occurrences of the given patterns
- <DT><B>@(</B><I>pattern-list</I><B>)</B><DD>
- Matches one of the given patterns
- <DT><B>!(</B><I>pattern-list</I><B>)</B><DD>
- Matches anything except one of the given patterns
- </DL></DL>
- <A NAME="lbBH"> </A>
- <H4>Quote Removal</H4>
- <P>
- After the preceding expansions, all unquoted occurrences of the
- characters
- <B>\</B>,
- <B>aq</B>,
- and <B>"</B> that did not result from one of the above
- expansions are removed.
- <A NAME="lbBI"> </A>
- <H3>REDIRECTION</H3>
- Before a command is executed, its input and output
- may be
- <I>redirected</I>
- using a special notation interpreted by the shell.
- Redirection allows commands' file handles to be
- duplicated, opened, closed,
- made to refer to different files,
- and can change the files the command reads from and writes to.
- Redirection may also be used to modify file handles in the
- current shell execution environment.
- The following redirection
- operators may precede or appear anywhere within a
- <I>simple command</I>
- or may follow a
- <I>command</I>.
- Redirections are processed in the order they appear, from
- left to right.
- <P>
- Each redirection that may be preceded by a file descriptor number
- may instead be preceded by a word of the form {<I>varname</I>}.
- In this case, for each redirection operator except
- >&- and <&-, the shell will allocate a file descriptor greater
- than or equal to 10 and assign it to <I>varname</I>.
- If >&- or <&- is preceded
- by {<I>varname</I>}, the value of <I>varname</I> defines the file
- descriptor to close.
- <P>
- In the following descriptions, if the file descriptor number is
- omitted, and the first character of the redirection operator is
- <B><</B>,
- the redirection refers to the standard input (file descriptor
- 0). If the first character of the redirection operator is
- <B>></B>,
- the redirection refers to the standard output (file descriptor
- 1).
- <P>
- The word following the redirection operator in the following
- descriptions, unless otherwise noted, is subjected to
- brace expansion, tilde expansion, parameter and variable expansion,
- command substitution, arithmetic expansion, quote removal,
- pathname expansion, and word splitting.
- If it expands to more than one word,
- <B>bash</B>
- reports an error.
- <P>
- Note that the order of redirections is significant. For example,
- the command
- <DL COMPACT><DT><DD>
- <P>
- ls <B>></B> dirlist 2<B>>&</B>1
- </DL>
- <P>
- directs both standard output and standard error to the file
- <I>dirlist</I>,
- while the command
- <DL COMPACT><DT><DD>
- <P>
- ls 2<B>>&</B>1 <B>></B> dirlist
- </DL>
- <P>
- directs only the standard output to file
- <I>dirlist</I>,
- because the standard error was duplicated from the standard output
- before the standard output was redirected to
- <I>dirlist</I>.
- <P>
- <B>Bash</B> handles several filenames specially when they are used in
- redirections, as described in the following table.
- If the operating system on which <B>bash</B> is running provides these
- special files, bash will use them; otherwise it will emulate them
- internally with the behavior described below.
- <DL COMPACT><DT><DD>
- <P>
- <DL COMPACT>
- <DT><B>/dev/fd/</B><I>fd</I>
- <DD>
- If <I>fd</I> is a valid integer, file descriptor <I>fd</I> is duplicated.
- <DT><B>/dev/stdin</B>
- <DD>
- File descriptor 0 is duplicated.
- <DT><B>/dev/stdout</B>
- <DD>
- File descriptor 1 is duplicated.
- <DT><B>/dev/stderr</B>
- <DD>
- File descriptor 2 is duplicated.
- <DT><B>/dev/tcp/</B><I>host</I>/<I>port</I>
- <DD>
- If <I>host</I> is a valid hostname or Internet address, and <I>port</I>
- is an integer port number or service name, <B>bash</B> attempts to open
- the corresponding TCP socket.
- <DT><B>/dev/udp/</B><I>host</I>/<I>port</I>
- <DD>
- If <I>host</I> is a valid hostname or Internet address, and <I>port</I>
- is an integer port number or service name, <B>bash</B> attempts to open
- the corresponding UDP socket.
- </DL></DL>
- <P>
- A failure to open or create a file causes the redirection to fail.
- <P>
- Redirections using file descriptors greater than 9 should be used with
- care, as they may conflict with file descriptors the shell uses
- internally.
- <A NAME="lbBJ"> </A>
- <H4>Redirecting Input</H4>
- <P>
- Redirection of input causes the file whose name results from
- the expansion of
- <I>word</I>
- to be opened for reading on file descriptor
- <I>n</I>,
- or the standard input (file descriptor 0) if
- <I>n</I>
- is not specified.
- <P>
- The general format for redirecting input is:
- <DL COMPACT><DT><DD>
- <P>
- [<I>n</I>]<B><</B><I>word</I>
- </DL>
- <A NAME="lbBK"> </A>
- <H4>Redirecting Output</H4>
- <P>
- Redirection of output causes the file whose name results from
- the expansion of
- <I>word</I>
- to be opened for writing on file descriptor
- <I>n</I>,
- or the standard output (file descriptor 1) if
- <I>n</I>
- is not specified. If the file does not exist it is created;
- if it does exist it is truncated to zero size.
- <P>
- The general format for redirecting output is:
- <DL COMPACT><DT><DD>
- <P>
- [<I>n</I>]<B>></B><I>word</I>
- </DL>
- <P>
- If the redirection operator is
- <B>></B>,
- and the
- <B>noclobber</B>
- option to the
- <B>set</B>
- builtin has been enabled, the redirection will fail if the file
- whose name results from the expansion of <I>word</I> exists and is
- a regular file.
- If the redirection operator is
- <B>>|</B>,
- or the redirection operator is
- <B>></B>
- and the
- <B>noclobber</B>
- option to the
- <B>set</B>
- builtin command is not enabled, the redirection is attempted even
- if the file named by <I>word</I> exists.
- <A NAME="lbBL"> </A>
- <H4>Appending Redirected Output</H4>
- <P>
- Redirection of output in this fashion
- causes the file whose name results from
- the expansion of
- <I>word</I>
- to be opened for appending on file descriptor
- <I>n</I>,
- or the standard output (file descriptor 1) if
- <I>n</I>
- is not specified. If the file does not exist it is created.
- <P>
- The general format for appending output is:
- <DL COMPACT><DT><DD>
- <P>
- [<I>n</I>]<B>>></B><I>word</I>
- </DL>
- <P>
- <A NAME="lbBM"> </A>
- <H4>Redirecting Standard Output and Standard Error</H4>
- <P>
- This construct allows both the
- standard output (file descriptor 1) and
- the standard error output (file descriptor 2)
- to be redirected to the file whose name is the
- expansion of
- <I>word</I>.
- <P>
- There are two formats for redirecting standard output and
- standard error:
- <DL COMPACT><DT><DD>
- <P>
- <B>&></B><I>word</I>
- </DL>
- and
- <DL COMPACT><DT><DD>
- <B>>&</B><I>word</I>
- </DL>
- <P>
- Of the two forms, the first is preferred.
- This is semantically equivalent to
- <DL COMPACT><DT><DD>
- <P>
- <B>></B><I>word</I> 2<B>>&</B>1
- </DL>
- <P>
- When using the second form, <I>word</I> may not expand to a number or
- <B>-</B>. If it does, other redirection operators apply
- (see <B>Duplicating File Descriptors</B> below) for compatibility
- reasons.
- <A NAME="lbBN"> </A>
- <H4>Appending Standard Output and Standard Error</H4>
- <P>
- This construct allows both the
- standard output (file descriptor 1) and
- the standard error output (file descriptor 2)
- to be appended to the file whose name is the
- expansion of
- <I>word</I>.
- <P>
- The format for appending standard output and standard error is:
- <DL COMPACT><DT><DD>
- <P>
- <B>&>></B><I>word</I>
- </DL>
- <P>
- This is semantically equivalent to
- <DL COMPACT><DT><DD>
- <P>
- <B>>></B><I>word</I> 2<B>>&</B>1
- </DL>
- <P>
- (see <B>Duplicating File Descriptors</B> below).
- <A NAME="lbBO"> </A>
- <H4>Here Documents</H4>
- <P>
- This type of redirection instructs the shell to read input from the
- current source until a line containing only
- <I>delimiter</I>
- (with no trailing blanks)
- is seen. All of
- the lines read up to that point are then used as the standard
- input (or file descriptor <I>n</I> if <I>n</I> is specified) for a command.
- <P>
- The format of here-documents is:
- <DL COMPACT><DT><DD>
- <P>
- <PRE>
- [<I>n</I>]<B><<</B>[<B>-</B>]<I>word</I>
- <I>here-document</I>
- <I>delimiter</I>
- </PRE>
- </DL>
- <P>
- No parameter and variable expansion, command substitution,
- arithmetic expansion, or pathname expansion is performed on
- <I>word</I>.
- If any part of
- <I>word</I>
- is quoted, the
- <I>delimiter</I>
- is the result of quote removal on
- <I>word</I>,
- and the lines in the here-document are not expanded.
- If <I>word</I> is unquoted,
- all lines of the here-document are subjected to
- parameter expansion, command substitution, and arithmetic expansion,
- the character sequence
- <B>\<newline></B>
- is ignored, and
- <B>\</B>
- must be used to quote the characters
- <B>\</B>,
- <B>$</B>,
- and
- <B>`</B>.
- <P>
- If the redirection operator is
- <B><<-</B>,
- then all leading tab characters are stripped from input lines and the
- line containing
- <I>delimiter</I>.
- This allows
- here-documents within shell scripts to be indented in a
- natural fashion.
- <A NAME="lbBP"> </A>
- <H4>Here Strings</H4>
- A variant of here documents, the format is:
- <DL COMPACT><DT><DD>
- <P>
- <PRE>
- [<I>n</I>]<B><<<</B><I>word</I>
- </PRE>
- </DL>
- <P>
- The <I>word</I> undergoes
- brace expansion, tilde expansion, parameter and variable expansion,
- command substitution, arithmetic expansion, and quote removal.
- Pathname expansion and word splitting are not performed.
- The result is supplied as a single string, with a newline appended,
- to the command on its
- standard input (or file descriptor <I>n</I> if <I>n</I> is specified).
- <A NAME="lbBQ"> </A>
- <H4>Duplicating File Descriptors</H4>
- <P>
- The redirection operator
- <DL COMPACT><DT><DD>
- <P>
- [<I>n</I>]<B><&</B><I>word</I>
- </DL>
- <P>
- is used to duplicate input file descriptors.
- If
- <I>word</I>
- expands to one or more digits, the file descriptor denoted by
- <I>n</I>
- is made to be a copy of that file descriptor.
- If the digits in
- <I>word</I>
- do not specify a file descriptor open for input, a redirection error occurs.
- If
- <I>word</I>
- evaluates to
- <B>-</B>,
- file descriptor
- <I>n</I>
- is closed. If
- <I>n</I>
- is not specified, the standard input (file descriptor 0) is used.
- <P>
- The operator
- <DL COMPACT><DT><DD>
- <P>
- [<I>n</I>]<B>>&</B><I>word</I>
- </DL>
- <P>
- is used similarly to duplicate output file descriptors. If
- <I>n</I>
- is not specified, the standard output (file descriptor 1) is used.
- If the digits in
- <I>word</I>
- do not specify a file descriptor open for output, a redirection error occurs.
- If
- <I>word</I>
- evaluates to
- <B>-</B>,
- file descriptor
- <I>n</I>
- is closed.
- As a special case, if <I>n</I> is omitted, and <I>word</I> does not
- expand to one or more digits or <B>-</B>, the standard output and standard
- error are redirected as described previously.
- <A NAME="lbBR"> </A>
- <H4>Moving File Descriptors</H4>
- <P>
- The redirection operator
- <DL COMPACT><DT><DD>
- <P>
- [<I>n</I>]<B><&</B><I>digit</I><B>-</B>
- </DL>
- <P>
- moves the file descriptor <I>digit</I> to file descriptor
- <I>n</I>,
- or the standard input (file descriptor 0) if <I>n</I> is not specified.
- <I>digit</I> is closed after being duplicated to <I>n</I>.
- <P>
- Similarly, the redirection operator
- <DL COMPACT><DT><DD>
- <P>
- [<I>n</I>]<B>>&</B><I>digit</I><B>-</B>
- </DL>
- <P>
- moves the file descriptor <I>digit</I> to file descriptor
- <I>n</I>,
- or the standard output (file descriptor 1) if <I>n</I> is not specified.
- <A NAME="lbBS"> </A>
- <H4>Opening File Descriptors for Reading and Writing</H4>
- <P>
- The redirection operator
- <DL COMPACT><DT><DD>
- <P>
- [<I>n</I>]<B><></B><I>word</I>
- </DL>
- <P>
- causes the file whose name is the expansion of
- <I>word</I>
- to be opened for both reading and writing on file descriptor
- <I>n</I>,
- or on file descriptor 0 if
- <I>n</I>
- is not specified. If the file does not exist, it is created.
- <A NAME="lbBT"> </A>
- <H3>ALIASES</H3>
- <I>Aliases</I> allow a string to be substituted for a word when it is used
- as the first word of a simple command.
- The shell maintains a list of aliases that may be set and unset with the
- <B>alias</B>
- and
- <B>unalias</B>
- builtin commands (see
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below).
- The first word of each simple command, if unquoted,
- is checked to see if it has an
- alias. If so, that word is replaced by the text of the alias.
- The characters <B>/</B>, <B>$</B>, <B>`</B>, and <B>=</B> and
- any of the shell <I>metacharacters</I> or quoting characters
- listed above may not appear in an alias name.
- The replacement text may contain any valid shell input,
- including shell metacharacters.
- The first word of the replacement text is tested
- for aliases, but a word that is identical to an alias being expanded
- is not expanded a second time.
- This means that one may alias
- <B>ls</B>
- to
- <B>ls -F</B>,
- for instance, and
- <B>bash</B>
- does not try to recursively expand the replacement text.
- If the last character of the alias value is a
- <I>blank</I>,
- then the next command
- word following the alias is also checked for alias expansion.
- <P>
- Aliases are created and listed with the
- <B>alias</B>
- command, and removed with the
- <B>unalias</B>
- command.
- <P>
- There is no mechanism for using arguments in the replacement text.
- If arguments are needed, a shell function should be used (see
- <FONT SIZE=-1><B>FUNCTIONS</B>
- </FONT>
- below).
- <P>
- Aliases are not expanded when the shell is not interactive, unless
- the
- <B>expand_aliases</B>
- shell option is set using
- <B>shopt</B>
- (see the description of
- <B>shopt</B>
- under
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B></FONT>
- below).
- <P>
- The rules concerning the definition and use of aliases are
- somewhat confusing.
- <B>Bash</B>
- always reads at least one complete line
- of input before executing any
- of the commands on that line. Aliases are expanded when a
- command is read, not when it is executed. Therefore, an
- alias definition appearing on the same line as another
- command does not take effect until the next line of input is read.
- The commands following the alias definition
- on that line are not affected by the new alias.
- This behavior is also an issue when functions are executed.
- Aliases are expanded when a function definition is read,
- not when the function is executed, because a function definition
- is itself a command. As a consequence, aliases
- defined in a function are not available until after that
- function is executed. To be safe, always put
- alias definitions on a separate line, and do not use
- <B>alias</B>
- in compound commands.
- <P>
- For almost every purpose, aliases are superseded by
- shell functions.
- <A NAME="lbBU"> </A>
- <H3>FUNCTIONS</H3>
- A shell function, defined as described above under
- <FONT SIZE=-1><B>SHELL GRAMMAR</B>,
- </FONT>
- stores a series of commands for later execution.
- When the name of a shell function is used as a simple command name,
- the list of commands associated with that function name is executed.
- Functions are executed in the context of the
- current shell; no new process is created to interpret
- them (contrast this with the execution of a shell script).
- When a function is executed, the arguments to the
- function become the positional parameters
- during its execution.
- The special parameter
- <B>#</B>
- is updated to reflect the change. Special parameter <B>0</B>
- is unchanged.
- The first element of the
- <FONT SIZE=-1><B>FUNCNAME</B>
- </FONT>
- variable is set to the name of the function while the function
- is executing.
- <P>
- All other aspects of the shell execution
- environment are identical between a function and its caller
- with these exceptions: the
- <FONT SIZE=-1><B>DEBUG</B>
- </FONT>
- and
- <B>RETURN</B>
- traps (see the description of the
- <B>trap</B>
- builtin under
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below) are not inherited unless the function has been given the
- <B>trace</B> attribute (see the description of the
- <FONT SIZE=-1><B>declare</B>
- </FONT>
- builtin below) or the
- <B>-o functrace</B> shell option has been enabled with
- the <B>set</B> builtin
- (in which case all functions inherit the <B>DEBUG</B> and <B>RETURN</B> traps),
- and the
- <FONT SIZE=-1><B>ERR</B>
- </FONT>
- trap is not inherited unless the <B>-o errtrace</B> shell option has
- been enabled.
- <P>
- Variables local to the function may be declared with the
- <B>local</B>
- builtin command. Ordinarily, variables and their values
- are shared between the function and its caller.
- <P>
- The <B>FUNCNEST</B> variable, if set to a numeric value greater
- than 0, defines a maximum function nesting level. Function
- invocations that exceed the limit cause the entire command to
- abort.
- <P>
- If the builtin command
- <B>return</B>
- is executed in a function, the function completes and
- execution resumes with the next command after the function
- call.
- Any command associated with the <B>RETURN</B> trap is executed
- before execution resumes.
- When a function completes, the values of the
- positional parameters and the special parameter
- <B>#</B>
- are restored to the values they had prior to the function's
- execution.
- <P>
- Function names and definitions may be listed with the
- <B>-f</B>
- option to the
- <B>declare</B>
- or
- <B>typeset</B>
- builtin commands. The
- <B>-F</B>
- option to
- <B>declare</B>
- or
- <B>typeset</B>
- will list the function names only
- (and optionally the source file and line number, if the <B>extdebug</B>
- shell option is enabled).
- Functions may be exported so that subshells
- automatically have them defined with the
- <B>-f</B>
- option to the
- <B>export</B>
- builtin.
- A function definition may be deleted using the <B>-f</B> option to
- the
- <B>unset</B>
- builtin.
- Note that shell functions and variables with the same name may result
- in multiple identically-named entries in the environment passed to the
- shell's children.
- Care should be taken in cases where this may cause a problem.
- <P>
- Functions may be recursive.
- The <B>FUNCNEST</B> variable may be used to limit the depth of the
- function call stack and restrict the number of function invocations.
- By default, no limit is imposed on the number of recursive calls.
- <A NAME="lbBV"> </A>
- <H3>ARITHMETIC EVALUATION</H3>
- The shell allows arithmetic expressions to be evaluated, under
- certain circumstances (see the <B>let</B> and <B>declare</B> builtin
- commands, the <B>((</B> compound command, and <B>Arithmetic Expansion</B>).
- Evaluation is done in fixed-width integers with no check for overflow,
- though division by 0 is trapped and flagged as an error.
- The operators and their precedence, associativity, and values
- are the same as in the C language.
- The following list of operators is grouped into levels of
- equal-precedence operators.
- The levels are listed in order of decreasing precedence.
- <P>
- <DL COMPACT>
- <DT><B></B><I>id</I>++ <I>id</I>--
- <DD>
- variable post-increment and post-decrement
- <DT><B>++</B><I>id</I> --<I>id</I>
- <DD>
- variable pre-increment and pre-decrement
- <DT><B>- +</B>
- <DD>
- unary minus and plus
- <DT><B>! ~</B>
- <DD>
- logical and bitwise negation
- <DT><B>**</B>
- <DD>
- exponentiation
- <DT><B>* / %</B>
- <DD>
- multiplication, division, remainder
- <DT><B>+ -</B>
- <DD>
- addition, subtraction
- <DT><B><< >></B>
- <DD>
- left and right bitwise shifts
- <DT><B><= >= < ></B>
- <DD>
- comparison
- <DT><B>== !=</B>
- <DD>
- equality and inequality
- <DT><B>&</B>
- <DD>
- bitwise AND
- <DT><B>^</B>
- <DD>
- bitwise exclusive OR
- <DT><B>|</B>
- <DD>
- bitwise OR
- <DT><B>&&</B>
- <DD>
- logical AND
- <DT><B>||</B>
- <DD>
- logical OR
- <DT><B></B><I>expr</I>?<I>expr</I>:<I>expr</I>
- <DD>
- conditional operator
- <DT><B>= *= /= %= += -= <<= >>= &= ^= |=</B>
- <DD>
- assignment
- <DT><B></B><I>expr1</I> , <I>expr2</I>
- <DD>
- comma
- </DL>
- <P>
- Shell variables are allowed as operands; parameter expansion is
- performed before the expression is evaluated.
- Within an expression, shell variables may also be referenced by name
- without using the parameter expansion syntax.
- A shell variable that is null or unset evaluates to 0 when referenced
- by name without using the parameter expansion syntax.
- The value of a variable is evaluated as an arithmetic expression
- when it is referenced, or when a variable which has been given the
- <I>integer</I> attribute using <B>declare -i</B> is assigned a value.
- A null value evaluates to 0.
- A shell variable need not have its <I>integer</I> attribute
- turned on to be used in an expression.
- <P>
- Constants with a leading 0 are interpreted as octal numbers.
- A leading 0x or 0X denotes hexadecimal.
- Otherwise, numbers take the form [<I>base#</I>]n, where the optional <I>base</I>
- is a decimal number between 2 and 64 representing the arithmetic
- base, and <I>n</I> is a number in that base.
- If <I>base#</I> is omitted, then base 10 is used.
- When specifying <I>n</I>,
- the digits greater than 9 are represented by the lowercase letters,
- the uppercase letters, @, and _, in that order.
- If <I>base</I> is less than or equal to 36, lowercase and uppercase
- letters may be used interchangeably to represent numbers between 10
- and 35.
- <P>
- Operators are evaluated in order of precedence. Sub-expressions in
- parentheses are evaluated first and may override the precedence
- rules above.
- <A NAME="lbBW"> </A>
- <H3>CONDITIONAL EXPRESSIONS</H3>
- Conditional expressions are used by the <B>[[</B> compound command and
- the <B>test</B> and <B>[</B> builtin commands to test file attributes
- and perform string and arithmetic comparisons.
- Expressions are formed from the following unary or binary primaries.
- <B>Bash</B> handles several filenames specially when they are used in
- expressions.
- If the operating system on which <B>bash</B> is running provides these
- special files, bash will use them; otherwise it will emulate them
- internally with this behavior:
- If any <I>file</I> argument to one of the primaries is of the form
- <I>/dev/fd/n</I>, then file descriptor <I>n</I> is checked.
- If the <I>file</I> argument to one of the primaries is one of
- <I>/dev/stdin</I>, <I>/dev/stdout</I>, or <I>/dev/stderr</I>, file
- descriptor 0, 1, or 2, respectively, is checked.
- <P>
- Unless otherwise specified, primaries that operate on files follow symbolic
- links and operate on the target of the link, rather than the link itself.
- <P>
- When used with <B>[[</B>, the <B><</B> and <B>></B> operators sort
- lexicographically using the current locale.
- The <B>test</B> command sorts using ASCII ordering.
- <P>
- <DL COMPACT>
- <DT><B>-a </B><I>file</I>
- <DD>
- True if <I>file</I> exists.
- <DT><B>-b </B><I>file</I>
- <DD>
- True if <I>file</I> exists and is a block special file.
- <DT><B>-c </B><I>file</I>
- <DD>
- True if <I>file</I> exists and is a character special file.
- <DT><B>-d </B><I>file</I>
- <DD>
- True if <I>file</I> exists and is a directory.
- <DT><B>-e </B><I>file</I>
- <DD>
- True if <I>file</I> exists.
- <DT><B>-f </B><I>file</I>
- <DD>
- True if <I>file</I> exists and is a regular file.
- <DT><B>-g </B><I>file</I>
- <DD>
- True if <I>file</I> exists and is set-group-id.
- <DT><B>-h </B><I>file</I>
- <DD>
- True if <I>file</I> exists and is a symbolic link.
- <DT><B>-k </B><I>file</I>
- <DD>
- True if <I>file</I> exists and its ``sticky'' bit is set.
- <DT><B>-p </B><I>file</I>
- <DD>
- True if <I>file</I> exists and is a named pipe (FIFO).
- <DT><B>-r </B><I>file</I>
- <DD>
- True if <I>file</I> exists and is readable.
- <DT><B>-s </B><I>file</I>
- <DD>
- True if <I>file</I> exists and has a size greater than zero.
- <DT><B>-t </B><I>fd</I>
- <DD>
- True if file descriptor
- <I>fd</I>
- is open and refers to a terminal.
- <DT><B>-u </B><I>file</I>
- <DD>
- True if <I>file</I> exists and its set-user-id bit is set.
- <DT><B>-w </B><I>file</I>
- <DD>
- True if <I>file</I> exists and is writable.
- <DT><B>-x </B><I>file</I>
- <DD>
- True if <I>file</I> exists and is executable.
- <DT><B>-G </B><I>file</I>
- <DD>
- True if <I>file</I> exists and is owned by the effective group id.
- <DT><B>-L </B><I>file</I>
- <DD>
- True if <I>file</I> exists and is a symbolic link.
- <DT><B>-N </B><I>file</I>
- <DD>
- True if <I>file</I> exists and has been modified since it was last read.
- <DT><B>-O </B><I>file</I>
- <DD>
- True if <I>file</I> exists and is owned by the effective user id.
- <DT><B>-S </B><I>file</I>
- <DD>
- True if <I>file</I> exists and is a socket.
- <DT><I>file1</I> <B>-ef</B> <I>file2</I><DD>
- True if <I>file1</I> and <I>file2</I> refer to the same device and
- inode numbers.
- <DT><I>file1</I> -<B>nt</B> <I>file2</I><DD>
- True if <I>file1</I> is newer (according to modification date) than <I>file2</I>,
- or if <I>file1</I> exists and file2 does not.
- <DT><I>file1</I> -<B>ot</B> <I>file2</I><DD>
- True if <I>file1</I> is older than <I>file2</I>, or if <I>file2</I> exists
- and <I>file1</I> does not.
- <DT><B>-o </B><I>optname</I>
- <DD>
- True if the shell option
- <I>optname</I>
- is enabled.
- See the list of options under the description of the
- <B>-o</B>
- option to the
- <B>set</B>
- builtin below.
- <DT><B>-v </B><I>varname</I>
- <DD>
- True if the shell variable
- <I>varname</I>
- is set (has been assigned a value).
- <DT><B>-R </B><I>varname</I>
- <DD>
- True if the shell variable
- <I>varname</I>
- is set and is a name reference.
- <DT><B>-z </B><I>string</I>
- <DD>
- True if the length of <I>string</I> is zero.
- <DT><I>string</I><DD>
- <DT><B>-n </B><I>string</I>
- <DD>
- True if the length of
- <I>string</I>
- is non-zero.
- <DT><I>string1</I> <B>==</B> <I>string2</I><DD>
- <DT><I>string1</I> <B>=</B> <I>string2</I><DD>
- True if the strings are equal. <B>=</B> should be used
- with the <B>test</B> command for POSIX conformance.
- When used with the <B>[[</B> command, this performs pattern matching as
- described above (<B>Compound Commands</B>).
- <DT><I>string1</I> <B>!=</B> <I>string2</I><DD>
- True if the strings are not equal.
- <DT><I>string1</I> <B><</B> <I>string2</I><DD>
- True if <I>string1</I> sorts before <I>string2</I> lexicographically.
- <DT><I>string1</I> <B>></B> <I>string2</I><DD>
- True if <I>string1</I> sorts after <I>string2</I> lexicographically.
- <DT><I>arg1</I> <B>OP</B> <I>arg2</I>
- <DD>
- <FONT SIZE=-1><B>OP</B>
- </FONT>
- is one of
- <B>-eq</B>,
- <B>-ne</B>,
- <B>-lt</B>,
- <B>-le</B>,
- <B>-gt</B>,
- or
- <B>-ge</B>.
- These arithmetic binary operators return true if <I>arg1</I>
- is equal to, not equal to, less than, less than or equal to,
- greater than, or greater than or equal to <I>arg2</I>, respectively.
- <I>Arg1</I>
- and
- <I>arg2</I>
- may be positive or negative integers.
- </DL>
- <A NAME="lbBX"> </A>
- <H3>SIMPLE COMMAND EXPANSION</H3>
- When a simple command is executed, the shell performs the following
- expansions, assignments, and redirections, from left to right.
- <DL COMPACT>
- <DT>1.<DD>
- The words that the parser has marked as variable assignments (those
- preceding the command name) and redirections are saved for later
- processing.
- <DT>2.<DD>
- The words that are not variable assignments or redirections are
- expanded. If any words remain after expansion, the first word
- is taken to be the name of the command and the remaining words are
- the arguments.
- <DT>3.<DD>
- Redirections are performed as described above under
- <FONT SIZE=-1><B>REDIRECTION</B>.
- </FONT>
- <DT>4.<DD>
- The text after the <B>=</B> in each variable assignment undergoes tilde
- expansion, parameter expansion, command substitution, arithmetic expansion,
- and quote removal before being assigned to the variable.
- </DL>
- <P>
- If no command name results, the variable assignments affect the current
- shell environment. Otherwise, the variables are added to the environment
- of the executed command and do not affect the current shell environment.
- If any of the assignments attempts to assign a value to a readonly variable,
- an error occurs, and the command exits with a non-zero status.
- <P>
- If no command name results, redirections are performed, but do not
- affect the current shell environment. A redirection error causes the
- command to exit with a non-zero status.
- <P>
- If there is a command name left after expansion, execution proceeds as
- described below. Otherwise, the command exits. If one of the expansions
- contained a command substitution, the exit status of the command is
- the exit status of the last command substitution performed. If there
- were no command substitutions, the command exits with a status of zero.
- <A NAME="lbBY"> </A>
- <H3>COMMAND EXECUTION</H3>
- After a command has been split into words, if it results in a
- simple command and an optional list of arguments, the following
- actions are taken.
- <P>
- If the command name contains no slashes, the shell attempts to
- locate it. If there exists a shell function by that name, that
- function is invoked as described above in
- <FONT SIZE=-1><B>FUNCTIONS</B>.
- </FONT>
- If the name does not match a function, the shell searches for
- it in the list of shell builtins. If a match is found, that
- builtin is invoked.
- <P>
- If the name is neither a shell function nor a builtin,
- and contains no slashes,
- <B>bash</B>
- searches each element of the
- <FONT SIZE=-1><B>PATH</B>
- </FONT>
- for a directory containing an executable file by that name.
- <B>Bash</B>
- uses a hash table to remember the full pathnames of executable
- files (see
- <B>hash</B>
- under
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below).
- A full search of the directories in
- <FONT SIZE=-1><B>PATH</B>
- </FONT>
- is performed only if the command is not found in the hash table.
- If the search is unsuccessful, the shell searches for a defined shell
- function named <B>command_not_found_handle</B>.
- If that function exists, it is invoked with the original command and
- the original command's arguments as its arguments, and the function's
- exit status becomes the exit status of the shell.
- If that function is not defined, the shell prints an error
- message and returns an exit status of 127.
- <P>
- If the search is successful, or if the command name contains
- one or more slashes, the shell executes the named program in a
- separate execution environment.
- Argument 0 is set to the name given, and the remaining arguments
- to the command are set to the arguments given, if any.
- <P>
- If this execution fails because the file is not in executable
- format, and the file is not a directory, it is assumed to be
- a <I>shell script</I>, a file
- containing shell commands. A subshell is spawned to execute
- it. This subshell reinitializes itself, so
- that the effect is as if a new shell had been invoked
- to handle the script, with the exception that the locations of
- commands remembered by the parent (see
- <B>hash</B>
- below under
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>)</FONT>
- are retained by the child.
- <P>
- If the program is a file beginning with
- <B>#!</B>,
- the remainder of the first line specifies an interpreter
- for the program. The shell executes the
- specified interpreter on operating systems that do not
- handle this executable format themselves. The arguments to the
- interpreter consist of a single optional argument following the
- interpreter name on the first line of the program, followed
- by the name of the program, followed by the command
- arguments, if any.
- <A NAME="lbBZ"> </A>
- <H3>COMMAND EXECUTION ENVIRONMENT</H3>
- The shell has an <I>execution environment</I>, which consists of the
- following:
- <DL COMPACT>
- <DT>*<DD>
- open files inherited by the shell at invocation, as modified by
- redirections supplied to the <B>exec</B> builtin
- <DT>*<DD>
- the current working directory as set by <B>cd</B>, <B>pushd</B>, or
- <B>popd</B>, or inherited by the shell at invocation
- <DT>*<DD>
- the file creation mode mask as set by <B>umask</B> or inherited from
- the shell's parent
- <DT>*<DD>
- current traps set by <B>trap</B>
- <DT>*<DD>
- shell parameters that are set by variable assignment or with <B>set</B>
- or inherited from the shell's parent in the environment
- <DT>*<DD>
- shell functions defined during execution or inherited from the shell's
- parent in the environment
- <DT>*<DD>
- options enabled at invocation (either by default or with command-line
- arguments) or by <B>set</B>
- <DT>*<DD>
- options enabled by <B>shopt</B>
- <DT>*<DD>
- shell aliases defined with <B>alias</B>
- <DT>*<DD>
- various process IDs, including those of background jobs, the value
- of <B>$$</B>, and the value of
- <FONT SIZE=-1><B>PPID</B>
- </FONT>
- </DL>
- <P>
- When a simple command other than a builtin or shell function
- is to be executed, it
- is invoked in a separate execution environment that consists of
- the following. Unless otherwise noted, the values are inherited
- from the shell.
- <DL COMPACT>
- <DT>*<DD>
- the shell's open files, plus any modifications and additions specified
- by redirections to the command
- <DT>*<DD>
- the current working directory
- <DT>*<DD>
- the file creation mode mask
- <DT>*<DD>
- shell variables and functions marked for export, along with variables
- exported for the command, passed in the environment
- <DT>*<DD>
- traps caught by the shell are reset to the values inherited from the
- shell's parent, and traps ignored by the shell are ignored
- </DL>
- <P>
- A command invoked in this separate environment cannot affect the
- shell's execution environment.
- <P>
- Command substitution, commands grouped with parentheses,
- and asynchronous commands are invoked in a
- subshell environment that is a duplicate of the shell environment,
- except that traps caught by the shell are reset to the values
- that the shell inherited from its parent at invocation. Builtin
- commands that are invoked as part of a pipeline are also executed in a
- subshell environment. Changes made to the subshell environment
- cannot affect the shell's execution environment.
- <P>
- Subshells spawned to execute command substitutions inherit the value of
- the <B>-e</B> option from the parent shell. When not in <I>posix</I> mode,
- <B>bash</B> clears the <B>-e</B> option in such subshells.
- <P>
- If a command is followed by a <B>&</B> and job control is not active, the
- default standard input for the command is the empty file <I>/dev/null</I>.
- Otherwise, the invoked command inherits the file descriptors of the calling
- shell as modified by redirections.
- <A NAME="lbCA"> </A>
- <H3>ENVIRONMENT</H3>
- When a program is invoked it is given an array of strings
- called the
- <I>environment</I>.
- This is a list of
- <I>name</I>-<I>value</I> pairs, of the form
- <I>name</I>=value.
- <P>
- The shell provides several ways to manipulate the environment.
- On invocation, the shell scans its own environment and
- creates a parameter for each name found, automatically marking
- it for
- <I>export</I>
- to child processes. Executed commands inherit the environment.
- The
- <B>export</B>
- and
- <B>declare -x</B>
- commands allow parameters and functions to be added to and
- deleted from the environment. If the value of a parameter
- in the environment is modified, the new value becomes part
- of the environment, replacing the old. The environment
- inherited by any executed command consists of the shell's
- initial environment, whose values may be modified in the shell,
- less any pairs removed by the
- <B>unset</B>
- command, plus any additions via the
- <B>export</B>
- and
- <B>declare -x</B>
- commands.
- <P>
- The environment for any
- <I>simple command</I>
- or function may be augmented temporarily by prefixing it with
- parameter assignments, as described above in
- <FONT SIZE=-1><B>PARAMETERS</B>.
- </FONT>
- These assignment statements affect only the environment seen
- by that command.
- <P>
- If the
- <B>-k</B>
- option is set (see the
- <B>set</B>
- builtin command below), then
- <I>all</I>
- parameter assignments are placed in the environment for a command,
- not just those that precede the command name.
- <P>
- When
- <B>bash</B>
- invokes an external command, the variable
- <B>_</B>
- is set to the full filename of the command and passed to that
- command in its environment.
- <A NAME="lbCB"> </A>
- <H3>EXIT STATUS</H3>
- <P>
- The exit status of an executed command is the value returned by the
- <I>waitpid</I> system call or equivalent function. Exit statuses
- fall between 0 and 255, though, as explained below, the shell may
- use values above 125 specially. Exit statuses from shell builtins and
- compound commands are also limited to this range. Under certain
- circumstances, the shell will use special values to indicate specific
- failure modes.
- <P>
- For the shell's purposes, a command which exits with a
- zero exit status has succeeded. An exit status of zero
- indicates success. A non-zero exit status indicates failure.
- When a command terminates on a fatal signal <I>N</I>, <B>bash</B> uses
- the value of 128+<I>N</I> as the exit status.
- <P>
- If a command is not found, the child process created to
- execute it returns a status of 127. If a command is found
- but is not executable, the return status is 126.
- <P>
- If a command fails because of an error during expansion or redirection,
- the exit status is greater than zero.
- <P>
- Shell builtin commands return a status of 0 (<I>true</I>) if
- successful, and non-zero (<I>false</I>) if an error occurs
- while they execute.
- All builtins return an exit status of 2 to indicate incorrect usage,
- generally invalid options or missing arguments.
- <P>
- <B>Bash</B> itself returns the exit status of the last command
- executed, unless a syntax error occurs, in which case it exits
- with a non-zero value. See also the <B>exit</B> builtin
- command below.
- <A NAME="lbCC"> </A>
- <H3>SIGNALS</H3>
- When <B>bash</B> is interactive, in the absence of any traps, it ignores
- <FONT SIZE=-1><B>SIGTERM</B>
- </FONT>
- (so that <B>kill 0</B> does not kill an interactive shell),
- and
- <FONT SIZE=-1><B>SIGINT</B>
- </FONT>
- is caught and handled (so that the <B>wait</B> builtin is interruptible).
- In all cases, <B>bash</B> ignores
- <FONT SIZE=-1><B>SIGQUIT</B>.
- </FONT>
- If job control is in effect,
- <B>bash</B>
- ignores
- <FONT SIZE=-1><B>SIGTTIN</B>,
- </FONT>
- <FONT SIZE=-1><B>SIGTTOU</B>,
- </FONT>
- and
- <FONT SIZE=-1><B>SIGTSTP</B>.
- </FONT>
- <P>
- Non-builtin commands run by <B>bash</B> have signal handlers
- set to the values inherited by the shell from its parent.
- When job control is not in effect, asynchronous commands
- ignore
- <FONT SIZE=-1><B>SIGINT</B>
- </FONT>
- and
- <FONT SIZE=-1><B>SIGQUIT</B>
- </FONT>
- in addition to these inherited handlers.
- Commands run as a result of command substitution ignore the
- keyboard-generated job control signals
- <FONT SIZE=-1><B>SIGTTIN</B>,
- </FONT>
- <FONT SIZE=-1><B>SIGTTOU</B>,
- </FONT>
- and
- <FONT SIZE=-1><B>SIGTSTP</B>.
- </FONT>
- <P>
- The shell exits by default upon receipt of a
- <FONT SIZE=-1><B>SIGHUP</B>.
- </FONT>
- Before exiting, an interactive shell resends the
- <FONT SIZE=-1><B>SIGHUP</B>
- </FONT>
- to all jobs, running or stopped.
- Stopped jobs are sent
- <FONT SIZE=-1><B>SIGCONT</B>
- </FONT>
- to ensure that they receive the
- <FONT SIZE=-1><B>SIGHUP</B>.
- </FONT>
- To prevent the shell from
- sending the signal to a particular job, it should be removed from the
- jobs table with the
- <B>disown</B>
- builtin (see
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below) or marked
- to not receive
- <FONT SIZE=-1><B>SIGHUP</B>
- </FONT>
- using
- <B>disown -h</B>.
- <P>
- If the
- <B>huponexit</B>
- shell option has been set with
- <B>shopt</B>,
- <B>bash</B>
- sends a
- <FONT SIZE=-1><B>SIGHUP</B>
- </FONT>
- to all jobs when an interactive login shell exits.
- <P>
- If <B>bash</B> is waiting for a command to complete and receives a signal
- for which a trap has been set, the trap will not be executed until
- the command completes.
- When <B>bash</B> is waiting for an asynchronous command via the <B>wait</B>
- builtin, the reception of a signal for which a trap has been set will
- cause the <B>wait</B> builtin to return immediately with an exit status
- greater than 128, immediately after which the trap is executed.
- <A NAME="lbCD"> </A>
- <H3>JOB CONTROL</H3>
- <I>Job control</I>
- refers to the ability to selectively stop (<I>suspend</I>)
- the execution of processes and continue (<I>resume</I>)
- their execution at a later point. A user typically employs
- this facility via an interactive interface supplied jointly
- by the operating system kernel's terminal driver and
- <B>bash</B>.
- <P>
- The shell associates a
- <I>job</I>
- with each pipeline. It keeps a table of currently executing
- jobs, which may be listed with the
- <B>jobs</B>
- command. When
- <B>bash</B>
- starts a job asynchronously (in the
- <I>background</I>),
- it prints a line that looks like:
- <DL COMPACT><DT><DD>
- <P>
- [1] 25647
- </DL>
- <P>
- indicating that this job is job number 1 and that the process ID
- of the last process in the pipeline associated with this job is 25647.
- All of the processes in a single pipeline are members of the same job.
- <B>Bash</B>
- uses the
- <I>job</I>
- abstraction as the basis for job control.
- <P>
- To facilitate the implementation of the user interface to job
- control, the operating system maintains the notion of a <I>current terminal
- process group ID</I>. Members of this process group (processes whose
- process group ID is equal to the current terminal process group ID)
- receive keyboard-generated signals such as
- <FONT SIZE=-1><B>SIGINT</B>.
- </FONT>
- These processes are said to be in the
- <I>foreground</I>.
- <I>Background</I>
- processes are those whose process group ID differs from the terminal's;
- such processes are immune to keyboard-generated signals.
- Only foreground processes are allowed to read from or, if the
- user so specifies with <TT>stty tostop</TT>, write to the
- terminal.
- Background processes which attempt to read from (write to when
- <TT>stty tostop</TT> is in effect) the
- terminal are sent a
- <FONT SIZE=-1><B>SIGTTIN (SIGTTOU)</B>
- </FONT>
- signal by the kernel's terminal driver,
- which, unless caught, suspends the process.
- <P>
- If the operating system on which
- <B>bash</B>
- is running supports
- job control,
- <B>bash</B>
- contains facilities to use it.
- Typing the
- <I>suspend</I>
- character (typically
- <B>^Z</B>,
- Control-Z) while a process is running
- causes that process to be stopped and returns control to
- <B>bash</B>.
- Typing the
- <I>delayed suspend</I>
- character (typically
- <B>^Y</B>,
- Control-Y) causes the process to be stopped when it
- attempts to read input from the terminal, and control to
- be returned to
- <B>bash</B>.
- The user may then manipulate the state of this job, using the
- <B>bg</B>
- command to continue it in the background, the
- <B>fg</B>
- command to continue it in the foreground, or
- the
- <B>kill</B>
- command to kill it. A <B>^Z</B> takes effect immediately,
- and has the additional side effect of causing pending output
- and typeahead to be discarded.
- <P>
- There are a number of ways to refer to a job in the shell.
- The character
- <B>%</B>
- introduces a job specification (<I>jobspec</I>). Job number
- <I>n</I>
- may be referred to as
- <B>%n</B>.
- A job may also be referred to using a prefix of the name used to
- start it, or using a substring that appears in its command line.
- For example,
- <B>%ce</B>
- refers to a stopped
- <B>ce</B>
- job. If a prefix matches more than one job,
- <B>bash</B>
- reports an error. Using
- <B>%?ce</B>,
- on the other hand, refers to any job containing the string
- <B>ce</B>
- in its command line. If the substring matches more than one job,
- <B>bash</B>
- reports an error. The symbols
- <B>%%</B>
- and
- <B>%+</B>
- refer to the shell's notion of the
- <I>current job</I>,
- which is the last job stopped while it was in
- the foreground or started in the background.
- The
- <I>previous job</I>
- may be referenced using
- <B>%-</B>.
- If there is only a single job, <B>%+</B> and <B>%-</B> can both be used
- to refer to that job.
- In output pertaining to jobs (e.g., the output of the
- <B>jobs</B>
- command), the current job is always flagged with a
- <B>+</B>,
- and the previous job with a
- <B>-</B>.
- A single % (with no accompanying job specification) also refers to the
- current job.
- <P>
- Simply naming a job can be used to bring it into the
- foreground:
- <B>%1</B>
- is a synonym for
- <B>``fg %1''</B>,
- bringing job 1 from the background into the foreground.
- Similarly,
- <B>``%1 &''</B>
- resumes job 1 in the background, equivalent to
- <B>``bg %1''</B>.
- <P>
- The shell learns immediately whenever a job changes state.
- Normally,
- <B>bash</B>
- waits until it is about to print a prompt before reporting
- changes in a job's status so as to not interrupt
- any other output. If the
- <B>-b</B>
- option to the
- <B>set</B>
- builtin command
- is enabled,
- <B>bash</B>
- reports such changes immediately.
- Any trap on
- <FONT SIZE=-1><B>SIGCHLD</B>
- </FONT>
- is executed for each child that exits.
- <P>
- If an attempt to exit
- <B>bash</B>
- is made while jobs are stopped (or, if the <B>checkjobs</B> shell option has
- been enabled using the <B>shopt</B> builtin, running), the shell prints a
- warning message, and, if the <B>checkjobs</B> option is enabled, lists the
- jobs and their statuses.
- The
- <B>jobs</B>
- command may then be used to inspect their status.
- If a second attempt to exit is made without an intervening command,
- the shell does not print another warning, and any stopped
- jobs are terminated.
- <A NAME="lbCE"> </A>
- <H3>PROMPTING</H3>
- When executing interactively,
- <B>bash</B>
- displays the primary prompt
- <FONT SIZE=-1><B>PS1</B>
- </FONT>
- when it is ready to read a command, and the secondary prompt
- <FONT SIZE=-1><B>PS2</B>
- </FONT>
- when it needs more input to complete a command.
- <B>Bash</B>
- displays
- <B>PS0</B>
- after it reads a command but before executing it.
- <B>Bash</B>
- allows these prompt strings to be customized by inserting a number of
- backslash-escaped special characters that are decoded as follows:
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>\a</B>
- <DD>
- an ASCII bell character (07)
- <DT><B>\d</B>
- <DD>
- the date in "Weekday Month Date" format (e.g., "Tue May 26")
- <DT><B>\D{</B><I>format</I>}
- <DD>
- the <I>format</I> is passed to <I>strftime</I>(3) and the result is inserted
- into the prompt string; an empty <I>format</I> results in a locale-specific
- time representation. The braces are required
- <DT><B>\e</B>
- <DD>
- an ASCII escape character (033)
- <DT><B>\h</B>
- <DD>
- the hostname up to the first `.'
- <DT><B>\H</B>
- <DD>
- the hostname
- <DT><B>\j</B>
- <DD>
- the number of jobs currently managed by the shell
- <DT><B>\l</B>
- <DD>
- the basename of the shell's terminal device name
- <DT><B>\n</B>
- <DD>
- newline
- <DT><B>\r</B>
- <DD>
- carriage return
- <DT><B>\s</B>
- <DD>
- the name of the shell, the basename of
- <B>$0</B>
- (the portion following the final slash)
- <DT><B>\t</B>
- <DD>
- the current time in 24-hour HH:MM:SS format
- <DT><B>\T</B>
- <DD>
- the current time in 12-hour HH:MM:SS format
- <DT><B>\@</B>
- <DD>
- the current time in 12-hour am/pm format
- <DT><B>\A</B>
- <DD>
- the current time in 24-hour HH:MM format
- <DT><B>\u</B>
- <DD>
- the username of the current user
- <DT><B>\v</B>
- <DD>
- the version of <B>bash</B> (e.g., 2.00)
- <DT><B>\V</B>
- <DD>
- the release of <B>bash</B>, version + patch level (e.g., 2.00.0)
- <DT><B>\w</B>
- <DD>
- the current working directory, with
- <FONT SIZE=-1><B>$HOME</B>
- </FONT>
- abbreviated with a tilde
- (uses the value of the
- <FONT SIZE=-1><B>PROMPT_DIRTRIM</B>
- </FONT>
- variable)
- <DT><B>\W</B>
- <DD>
- the basename of the current working directory, with
- <FONT SIZE=-1><B>$HOME</B>
- </FONT>
- abbreviated with a tilde
- <DT><B>\!</B>
- <DD>
- the history number of this command
- <DT><B>\#</B>
- <DD>
- the command number of this command
- <DT><B>\$</B>
- <DD>
- if the effective UID is 0, a
- <B>#</B>,
- otherwise a
- <B>$</B>
- <DT><B>\</B><I>nnn</I>
- <DD>
- the character corresponding to the octal number <I>nnn</I>
- <DT><B>\\</B>
- <DD>
- a backslash
- <DT><B>\[</B>
- <DD>
- begin a sequence of non-printing characters, which could be used to
- embed a terminal control sequence into the prompt
- <DT><B>\]</B>
- <DD>
- end a sequence of non-printing characters
- </DL></DL>
- <P>
- The command number and the history number are usually different:
- the history number of a command is its position in the history
- list, which may include commands restored from the history file
- (see
- <FONT SIZE=-1><B>HISTORY</B>
- </FONT>
- below), while the command number is the position in the sequence
- of commands executed during the current shell session.
- After the string is decoded, it is expanded via
- parameter expansion, command substitution, arithmetic
- expansion, and quote removal, subject to the value of the
- <B>promptvars</B>
- shell option (see the description of the
- <B>shopt</B>
- command under
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below).
- <A NAME="lbCF"> </A>
- <H3>READLINE</H3>
- This is the library that handles reading input when using an interactive
- shell, unless the
- <B>--noediting</B>
- option is given at shell invocation.
- Line editing is also used when using the <B>-e</B> option to the
- <B>read</B> builtin.
- By default, the line editing commands are similar to those of Emacs.
- A vi-style line editing interface is also available.
- Line editing can be enabled at any time using the
- <B>-o emacs</B>
- or
- <B>-o vi</B>
- options to the
- <B>set</B>
- builtin (see
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below).
- To turn off line editing after the shell is running, use the
- <B>+o emacs</B>
- or
- <B>+o vi</B>
- options to the
- <B>set</B>
- builtin.
- <A NAME="lbCG"> </A>
- <H4>Readline Notation</H4>
- <P>
- In this section, the Emacs-style notation is used to denote
- keystrokes. Control keys are denoted by C-<I>key</I>, e.g., C-n
- means Control-N. Similarly,
- <I>meta</I>
- keys are denoted by M-<I>key</I>, so M-x means Meta-X. (On keyboards
- without a
- <I>meta</I>
- key, M-<I>x</I> means ESC <I>x</I>, i.e., press the Escape key
- then the
- <I>x</I>
- key. This makes ESC the <I>meta prefix</I>.
- The combination M-C-<I>x</I> means ESC-Control-<I>x</I>,
- or press the Escape key
- then hold the Control key while pressing the
- <I>x</I>
- key.)
- <P>
- Readline commands may be given numeric
- <I>arguments</I>,
- which normally act as a repeat count.
- Sometimes, however, it is the sign of the argument that is significant.
- Passing a negative argument to a command that acts in the forward
- direction (e.g., <B>kill-line</B>) causes that command to act in a
- backward direction.
- Commands whose behavior with arguments deviates from this are noted
- below.
- <P>
- When a command is described as <I>killing</I> text, the text
- deleted is saved for possible future retrieval
- (<I>yanking</I>). The killed text is saved in a
- <I>kill ring</I>. Consecutive kills cause the text to be
- accumulated into one unit, which can be yanked all at once.
- Commands which do not kill text separate the chunks of text
- on the kill ring.
- <A NAME="lbCH"> </A>
- <H4>Readline Initialization</H4>
- <P>
- Readline is customized by putting commands in an initialization
- file (the <I>inputrc</I> file).
- The name of this file is taken from the value of the
- <FONT SIZE=-1><B>INPUTRC</B>
- </FONT>
- variable. If that variable is unset, the default is
- <A HREF="file:~/.inputrc"><I>~/.inputrc</I></A>.
- When a program which uses the readline library starts up, the
- initialization file is read, and the key bindings and variables
- are set.
- There are only a few basic constructs allowed in the
- readline initialization file.
- Blank lines are ignored.
- Lines beginning with a <B>#</B> are comments.
- Lines beginning with a <B>$</B> indicate conditional constructs.
- Other lines denote key bindings and variable settings.
- <P>
- The default key-bindings may be changed with an
- <I>inputrc</I>
- file.
- Other programs that use this library may add their own commands
- and bindings.
- <P>
- For example, placing
- <DL COMPACT><DT><DD>
- <P>
- M-Control-u: universal-argument
- </DL>
- or
- <DL COMPACT><DT><DD>
- C-Meta-u: universal-argument
- </DL>
- into the
- <I>inputrc</I>
- would make M-C-u execute the readline command
- <I>universal-argument</I>.
- <P>
- The following symbolic character names are recognized:
- <I>RUBOUT</I>,
- <I>DEL</I>,
- <I>ESC</I>,
- <I>LFD</I>,
- <I>NEWLINE</I>,
- <I>RET</I>,
- <I>RETURN</I>,
- <I>SPC</I>,
- <I>SPACE</I>,
- and
- <I>TAB</I>.
- <P>
- In addition to command names, readline allows keys to be bound
- to a string that is inserted when the key is pressed (a <I>macro</I>).
- <A NAME="lbCI"> </A>
- <H4>Readline Key Bindings</H4>
- <P>
- The syntax for controlling key bindings in the
- <I>inputrc</I>
- file is simple. All that is required is the name of the
- command or the text of a macro and a key sequence to which
- it should be bound. The name may be specified in one of two ways:
- as a symbolic key name, possibly with <I>Meta-</I> or <I>Control-</I>
- prefixes, or as a key sequence.
- <P>
- When using the form <B>keyname</B>:<I>function-name</I> or <I>macro</I>,
- <I>keyname</I>
- is the name of a key spelled out in English. For example:
- <P>
- <DL COMPACT><DT><DD>
- Control-u: universal-argument
- <BR>
- Meta-Rubout: backward-kill-word
- <BR>
- Control-o: "> output"
- </DL>
- <P>
- In the above example,
- <I>C-u</I>
- is bound to the function
- <B>universal-argument</B>,
- <I>M-DEL</I>
- is bound to the function
- <B>backward-kill-word</B>,
- and
- <I>C-o</I>
- is bound to run the macro
- expressed on the right hand side (that is, to insert the text
- <TT>> output</TT>
- into the line).
- <P>
- In the second form, <B>"keyseq"</B>:<I>function-name</I> or <I>macro</I>,
- <B>keyseq</B>
- differs from
- <B>keyname</B>
- above in that strings denoting
- an entire key sequence may be specified by placing the sequence
- within double quotes. Some GNU Emacs style key escapes can be
- used, as in the following example, but the symbolic character names
- are not recognized.
- <P>
- <DL COMPACT><DT><DD>
- "\C-u": universal-argument
- <BR>
- "\C-x\C-r": re-read-init-file
- <BR>
- "\e[11~": "Function Key 1"
- </DL>
- <P>
- In this example,
- <I>C-u</I>
- is again bound to the function
- <B>universal-argument</B>.
- <I>C-x C-r</I>
- is bound to the function
- <B>re-read-init-file</B>,
- and
- <I>ESC [ 1 1 ~</I>
- is bound to insert the text
- <TT>Function Key 1</TT>.
- <P>
- The full set of GNU Emacs style escape sequences is
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>\C-</B>
- <DD>
- control prefix
- <DT><B>\M-</B>
- <DD>
- meta prefix
- <DT><B>\e</B>
- <DD>
- an escape character
- <DT><B>\\</B>
- <DD>
- backslash
- <DT><B>\</B>
- <DD>
- literal "
- <DT><B>\aq</B>
- <DD>
- literal aq
- </DL></DL>
- <P>
- In addition to the GNU Emacs style escape sequences, a second
- set of backslash escapes is available:
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>\a</B>
- <DD>
- alert (bell)
- <DT><B>\b</B>
- <DD>
- backspace
- <DT><B>\d</B>
- <DD>
- delete
- <DT><B>\f</B>
- <DD>
- form feed
- <DT><B>\n</B>
- <DD>
- newline
- <DT><B>\r</B>
- <DD>
- carriage return
- <DT><B>\t</B>
- <DD>
- horizontal tab
- <DT><B>\v</B>
- <DD>
- vertical tab
- <DT><B>\</B><I>nnn</I>
- <DD>
- the eight-bit character whose value is the octal value <I>nnn</I>
- (one to three digits)
- <DT><B>\x</B><I>HH</I>
- <DD>
- the eight-bit character whose value is the hexadecimal value <I>HH</I>
- (one or two hex digits)
- </DL></DL>
- <P>
- When entering the text of a macro, single or double quotes must
- be used to indicate a macro definition.
- Unquoted text is assumed to be a function name.
- In the macro body, the backslash escapes described above are expanded.
- Backslash will quote any other character in the macro text,
- including " and aq.
- <P>
- <B>Bash</B>
- allows the current readline key bindings to be displayed or modified
- with the
- <B>bind</B>
- builtin command. The editing mode may be switched during interactive
- use by using the
- <B>-o</B>
- option to the
- <B>set</B>
- builtin command (see
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below).
- <A NAME="lbCJ"> </A>
- <H4>Readline Variables</H4>
- <P>
- Readline has variables that can be used to further customize its
- behavior. A variable may be set in the
- <I>inputrc</I>
- file with a statement of the form
- <DL COMPACT><DT><DD>
- <P>
- <B>set</B> <I>variable-name</I> <I>value</I>
- </DL>
- <P>
- Except where noted, readline variables can take the values
- <B>On</B>
- or
- <B>Off</B>
- (without regard to case).
- Unrecognized variable names are ignored.
- When a variable value is read, empty or null values, "on" (case-insensitive),
- and "1" are equivalent to <B>On</B>. All other values are equivalent to
- <B>Off</B>.
- The variables and their default values are:
- <P>
- <DL COMPACT>
- <DT><B>bell-style (audible)</B>
- <DD>
- Controls what happens when readline wants to ring the terminal bell.
- If set to <B>none</B>, readline never rings the bell. If set to
- <B>visible</B>, readline uses a visible bell if one is available.
- If set to <B>audible</B>, readline attempts to ring the terminal's bell.
- <DT><B>bind-tty-special-chars (On)</B>
- <DD>
- If set to <B>On</B>, readline attempts to bind the control characters
- treated specially by the kernel's terminal driver to their readline
- equivalents.
- <DT><B>blink-matching-paren (Off)</B>
- <DD>
- If set to <B>On</B>, readline attempts to briefly move the cursor to an
- opening parenthesis when a closing parenthesis is inserted.
- <DT><B>colored-completion-prefix (Off)</B>
- <DD>
- If set to <B>On</B>, when listing completions, readline displays the
- common prefix of the set of possible completions using a different color.
- The color definitions are taken from the value of the <B>LS_COLORS</B>
- environment variable.
- <DT><B>colored-stats (Off)</B>
- <DD>
- If set to <B>On</B>, readline displays possible completions using different
- colors to indicate their file type.
- The color definitions are taken from the value of the <B>LS_COLORS</B>
- environment variable.
- <DT><B>comment-begin (``#'')</B>
- <DD>
- The string that is inserted when the readline
- <B>insert-comment</B>
- command is executed.
- This command is bound to
- <B>M-#</B>
- in emacs mode and to
- <B>#</B>
- in vi command mode.
- <DT><B>completion-display-width (-1)</B>
- <DD>
- The number of screen columns used to display possible matches
- when performing completion.
- The value is ignored if it is less than 0 or greater than the terminal
- screen width.
- A value of 0 will cause matches to be displayed one per line.
- The default value is -1.
- <DT><B>completion-ignore-case (Off)</B>
- <DD>
- If set to <B>On</B>, readline performs filename matching and completion
- in a case-insensitive fashion.
- <DT><B>completion-map-case (Off)</B>
- <DD>
- If set to <B>On</B>, and <B>completion-ignore-case</B> is enabled, readline
- treats hyphens (<I>-</I>) and underscores (<I>_</I>) as equivalent when
- performing case-insensitive filename matching and completion.
- <DT><B>completion-prefix-display-length (0)</B>
- <DD>
- The length in characters of the common prefix of a list of possible
- completions that is displayed without modification. When set to a
- value greater than zero, common prefixes longer than this value are
- replaced with an ellipsis when displaying possible completions.
- <DT><B>completion-query-items (100)</B>
- <DD>
- This determines when the user is queried about viewing
- the number of possible completions
- generated by the <B>possible-completions</B> command.
- It may be set to any integer value greater than or equal to
- zero. If the number of possible completions is greater than
- or equal to the value of this variable, the user is asked whether
- or not he wishes to view them; otherwise they are simply listed
- on the terminal.
- <DT><B>convert-meta (On)</B>
- <DD>
- If set to <B>On</B>, readline will convert characters with the
- eighth bit set to an ASCII key sequence
- by stripping the eighth bit and prefixing an
- escape character (in effect, using escape as the <I>meta prefix</I>).
- The default is <I>On</I>, but readline will set it to <I>Off</I> if the
- locale contains eight-bit characters.
- <DT><B>disable-completion (Off)</B>
- <DD>
- If set to <B>On</B>, readline will inhibit word completion. Completion
- characters will be inserted into the line as if they had been
- mapped to <B>self-insert</B>.
- <DT><B>echo-control-characters (On)</B>
- <DD>
- When set to <B>On</B>, on operating systems that indicate they support it,
- readline echoes a character corresponding to a signal generated from the
- keyboard.
- <DT><B>editing-mode (emacs)</B>
- <DD>
- Controls whether readline begins with a set of key bindings similar
- to <I>Emacs</I> or <I>vi</I>.
- <B>editing-mode</B>
- can be set to either
- <B>emacs</B>
- or
- <B>vi</B>.
- <DT><B>enable-bracketed-paste (Off)</B>
- <DD>
- When set to <B>On</B>, readline will configure the terminal in a way
- that will enable it to insert each paste into the editing buffer as a
- single string of characters, instead of treating each character as if
- it had been read from the keyboard. This can prevent pasted characters
- from being interpreted as editing commands.
- <DT><B>enable-keypad (Off)</B>
- <DD>
- When set to <B>On</B>, readline will try to enable the application
- keypad when it is called. Some systems need this to enable the
- arrow keys.
- <DT><B>enable-meta-key (On)</B>
- <DD>
- When set to <B>On</B>, readline will try to enable any meta modifier
- key the terminal claims to support when it is called. On many terminals,
- the meta key is used to send eight-bit characters.
- <DT><B>expand-tilde (Off)</B>
- <DD>
- If set to <B>On</B>, tilde expansion is performed when readline
- attempts word completion.
- <DT><B>history-preserve-point (Off)</B>
- <DD>
- If set to <B>On</B>, the history code attempts to place point at the
- same location on each history line retrieved with <B>previous-history</B>
- or <B>next-history</B>.
- <DT><B>history-size (unset)</B>
- <DD>
- Set the maximum number of history entries saved in the history list.
- If set to zero, any existing history entries are deleted and no new entries
- are saved.
- If set to a value less than zero, the number of history entries is not
- limited.
- By default, the number of history entries is set to the value of the
- <B>HISTSIZE</B> shell variable.
- If an attempt is made to set <I>history-size</I> to a non-numeric value,
- the maximum number of history entries will be set to 500.
- <DT><B>horizontal-scroll-mode (Off)</B>
- <DD>
- When set to <B>On</B>, makes readline use a single line for display,
- scrolling the input horizontally on a single screen line when it
- becomes longer than the screen width rather than wrapping to a new line.
- <DT><B>input-meta (Off)</B>
- <DD>
- If set to <B>On</B>, readline will enable eight-bit input (that is,
- it will not strip the eighth bit from the characters it reads),
- regardless of what the terminal claims it can support. The name
- <B>meta-flag</B>
- is a synonym for this variable.
- The default is <I>Off</I>, but readline will set it to <I>On</I> if the
- locale contains eight-bit characters.
- <DT><B>isearch-terminators (``C-[C-J'')</B>
- <DD>
- The string of characters that should terminate an incremental
- search without subsequently executing the character as a command.
- If this variable has not been given a value, the characters
- <I>ESC</I> and <I>C-J</I> will terminate an incremental search.
- <DT><B>keymap (emacs)</B>
- <DD>
- Set the current readline keymap. The set of valid keymap names is
- <I>emacs, emacs-standard, emacs-meta, emacs-ctlx, vi,
- vi-command</I>, and
- <I>vi-insert</I>.
- <I>vi</I> is equivalent to <I>vi-command</I>; <I>emacs</I> is
- equivalent to <I>emacs-standard</I>. The default value is
- <I>emacs</I>;
- the value of
- <B>editing-mode</B>
- also affects the default keymap.
- <DT><B>emacs-mode-string (@)</B>
- <DD>
- This string is displayed immediately before the last line of the primary
- prompt when emacs editing mode is active. The value is expanded like a
- key binding, so the standard set of meta- and control prefixes and
- backslash escape sequences is available.
- Use the \1 and \2 escapes to begin and end sequences of
- non-printing characters, which can be used to embed a terminal control
- sequence into the mode string.
- <DT><B>keyseq-timeout (500)</B>
- <DD>
- Specifies the duration <I>readline</I> will wait for a character when reading an
- ambiguous key sequence (one that can form a complete key sequence using
- the input read so far, or can take additional input to complete a longer
- key sequence).
- If no input is received within the timeout, <I>readline</I> will use the shorter
- but complete key sequence.
- The value is specified in milliseconds, so a value of 1000 means that
- <I>readline</I> will wait one second for additional input.
- If this variable is set to a value less than or equal to zero, or to a
- non-numeric value, <I>readline</I> will wait until another key is pressed to
- decide which key sequence to complete.
- <DT><B>mark-directories (On)</B>
- <DD>
- If set to <B>On</B>, completed directory names have a slash
- appended.
- <DT><B>mark-modified-lines (Off)</B>
- <DD>
- If set to <B>On</B>, history lines that have been modified are displayed
- with a preceding asterisk (<B>*</B>).
- <DT><B>mark-symlinked-directories (Off)</B>
- <DD>
- If set to <B>On</B>, completed names which are symbolic links to directories
- have a slash appended (subject to the value of
- <B>mark-directories</B>).
- <DT><B>match-hidden-files (On)</B>
- <DD>
- This variable, when set to <B>On</B>, causes readline to match files whose
- names begin with a `.' (hidden files) when performing filename
- completion.
- If set to <B>Off</B>, the leading `.' must be
- supplied by the user in the filename to be completed.
- <DT><B>menu-complete-display-prefix (Off)</B>
- <DD>
- If set to <B>On</B>, menu completion displays the common prefix of the
- list of possible completions (which may be empty) before cycling through
- the list.
- <DT><B>output-meta (Off)</B>
- <DD>
- If set to <B>On</B>, readline will display characters with the
- eighth bit set directly rather than as a meta-prefixed escape
- sequence.
- The default is <I>Off</I>, but readline will set it to <I>On</I> if the
- locale contains eight-bit characters.
- <DT><B>page-completions (On)</B>
- <DD>
- If set to <B>On</B>, readline uses an internal <I>more</I>-like pager
- to display a screenful of possible completions at a time.
- <DT><B>print-completions-horizontally (Off)</B>
- <DD>
- If set to <B>On</B>, readline will display completions with matches
- sorted horizontally in alphabetical order, rather than down the screen.
- <DT><B>revert-all-at-newline (Off)</B>
- <DD>
- If set to <B>On</B>, readline will undo all changes to history lines
- before returning when <B>accept-line</B> is executed. By default,
- history lines may be modified and retain individual undo lists across
- calls to <B>readline</B>.
- <DT><B>show-all-if-ambiguous (Off)</B>
- <DD>
- This alters the default behavior of the completion functions. If
- set to
- <B>On</B>,
- words which have more than one possible completion cause the
- matches to be listed immediately instead of ringing the bell.
- <DT><B>show-all-if-unmodified (Off)</B>
- <DD>
- This alters the default behavior of the completion functions in
- a fashion similar to <B>show-all-if-ambiguous</B>.
- If set to
- <B>On</B>,
- words which have more than one possible completion without any
- possible partial completion (the possible completions don't share
- a common prefix) cause the matches to be listed immediately instead
- of ringing the bell.
- <DT><B>show-mode-in-prompt (Off)</B>
- <DD>
- If set to <B>On</B>, add a character to the beginning of the prompt
- indicating the editing mode: emacs (@), vi command (:) or vi
- insertion (+).
- <DT><B>skip-completed-text (Off)</B>
- <DD>
- If set to <B>On</B>, this alters the default completion behavior when
- inserting a single match into the line. It's only active when
- performing completion in the middle of a word. If enabled, readline
- does not insert characters from the completion that match characters
- after point in the word being completed, so portions of the word
- following the cursor are not duplicated.
- <DT><B>vi-cmd-mode-string ((cmd))</B>
- <DD>
- This string is displayed immediately before the last line of the primary
- prompt when vi editing mode is active and in command mode.
- The value is expanded like a
- key binding, so the standard set of meta- and control prefixes and
- backslash escape sequences is available.
- Use the \1 and \2 escapes to begin and end sequences of
- non-printing characters, which can be used to embed a terminal control
- sequence into the mode string.
- <DT><B>vi-ins-mode-string ((ins))</B>
- <DD>
- This string is displayed immediately before the last line of the primary
- prompt when vi editing mode is active and in insertion mode.
- The value is expanded like a
- key binding, so the standard set of meta- and control prefixes and
- backslash escape sequences is available.
- Use the \1 and \2 escapes to begin and end sequences of
- non-printing characters, which can be used to embed a terminal control
- sequence into the mode string.
- <DT><B>visible-stats (Off)</B>
- <DD>
- If set to <B>On</B>, a character denoting a file's type as reported
- by <I>stat</I>(2) is appended to the filename when listing possible
- completions.
- </DL>
- <A NAME="lbCK"> </A>
- <H4>Readline Conditional Constructs</H4>
- <P>
- Readline implements a facility similar in spirit to the conditional
- compilation features of the C preprocessor which allows key
- bindings and variable settings to be performed as the result
- of tests. There are four parser directives used.
- <DL COMPACT>
- <DT><B>$if</B><DD>
- The
- <B>$if</B>
- construct allows bindings to be made based on the
- editing mode, the terminal being used, or the application using
- readline. The text of the test extends to the end of the line;
- no characters are required to isolate it.
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>mode</B><DD>
- The <B>mode=</B> form of the <B>$if</B> directive is used to test
- whether readline is in emacs or vi mode.
- This may be used in conjunction
- with the <B>set keymap</B> command, for instance, to set bindings in
- the <I>emacs-standard</I> and <I>emacs-ctlx</I> keymaps only if
- readline is starting out in emacs mode.
- <DT><B>term</B><DD>
- The <B>term=</B> form may be used to include terminal-specific
- key bindings, perhaps to bind the key sequences output by the
- terminal's function keys. The word on the right side of the
- <B>=</B>
- is tested against both the full name of the terminal and the portion
- of the terminal name before the first <B>-</B>. This allows
- <I>sun</I>
- to match both
- <I>sun</I>
- and
- <I>sun-cmd</I>,
- for instance.
- <DT><B>application</B><DD>
- The <B>application</B> construct is used to include
- application-specific settings. Each program using the readline
- library sets the <I>application name</I>, and an initialization
- file can test for a particular value.
- This could be used to bind key sequences to functions useful for
- a specific program. For instance, the following command adds a
- key sequence that quotes the current or previous word in <B>bash</B>:
- <P>
- <DL COMPACT><DT><DD>
- <PRE>
- <B>$if</B> Bash
- # Quote the current or previous word
- "\C-xq": "\eb\"\ef\""
- <B>$endif</B>
- </PRE>
- </DL>
- </DL></DL>
- <DT><B>$endif</B><DD>
- This command, as seen in the previous example, terminates an
- <B>$if</B> command.
- <DT><B>$else</B><DD>
- Commands in this branch of the <B>$if</B> directive are executed if
- the test fails.
- <DT><B>$include</B><DD>
- This directive takes a single filename as an argument and reads commands
- and bindings from that file. For example, the following directive
- would read <A HREF="file:/etc/inputrc"><I>/etc/inputrc</I></A>:
- <P>
- <DL COMPACT><DT><DD>
- <PRE>
- <B>$include</B> <A HREF="file:/etc/inputrc"><I>/etc/inputrc</I></A>
- </PRE>
- </DL>
- </DL>
- <A NAME="lbCL"> </A>
- <H4>Searching</H4>
- <P>
- Readline provides commands for searching through the command history
- (see
- <FONT SIZE=-1><B>HISTORY</B>
- </FONT>
- below) for lines containing a specified string.
- There are two search modes:
- <I>incremental</I>
- and
- <I>non-incremental</I>.
- <P>
- Incremental searches begin before the user has finished typing the
- search string.
- As each character of the search string is typed, readline displays
- the next entry from the history matching the string typed so far.
- An incremental search requires only as many characters as needed to
- find the desired history entry.
- The characters present in the value of the <B>isearch-terminators</B>
- variable are used to terminate an incremental search.
- If that variable has not been assigned a value the Escape and
- Control-J characters will terminate an incremental search.
- Control-G will abort an incremental search and restore the original
- line.
- When the search is terminated, the history entry containing the
- search string becomes the current line.
- <P>
- To find other matching entries in the history list, type Control-S or
- Control-R as appropriate.
- This will search backward or forward in the history for the next
- entry matching the search string typed so far.
- Any other key sequence bound to a readline command will terminate
- the search and execute that command.
- For instance, a <I>newline</I> will terminate the search and accept
- the line, thereby executing the command from the history list.
- <P>
- Readline remembers the last incremental search string. If two
- Control-Rs are typed without any intervening characters defining a
- new search string, any remembered search string is used.
- <P>
- Non-incremental searches read the entire search string before starting
- to search for matching history lines. The search string may be
- typed by the user or be part of the contents of the current line.
- <A NAME="lbCM"> </A>
- <H4>Readline Command Names</H4>
- <P>
- The following is a list of the names of the commands and the default
- key sequences to which they are bound.
- Command names without an accompanying key sequence are unbound by default.
- In the following descriptions, <I>point</I> refers to the current cursor
- position, and <I>mark</I> refers to a cursor position saved by the
- <B>set-mark</B> command.
- The text between the point and mark is referred to as the <I>region</I>.
- <A NAME="lbCN"> </A>
- <H4>Commands for Moving</H4>
- <P>
- <DL COMPACT>
- <DT><B>beginning-of-line (C-a)</B>
- <DD>
- Move to the start of the current line.
- <DT><B>end-of-line (C-e)</B>
- <DD>
- Move to the end of the line.
- <DT><B>forward-char (C-f)</B>
- <DD>
- Move forward a character.
- <DT><B>backward-char (C-b)</B>
- <DD>
- Move back a character.
- <DT><B>forward-word (M-f)</B>
- <DD>
- Move forward to the end of the next word. Words are composed of
- alphanumeric characters (letters and digits).
- <DT><B>backward-word (M-b)</B>
- <DD>
- Move back to the start of the current or previous word.
- Words are composed of alphanumeric characters (letters and digits).
- <DT><B>shell-forward-word</B>
- <DD>
- Move forward to the end of the next word.
- Words are delimited by non-quoted shell metacharacters.
- <DT><B>shell-backward-word</B>
- <DD>
- Move back to the start of the current or previous word.
- Words are delimited by non-quoted shell metacharacters.
- <DT><B>clear-screen (C-l)</B>
- <DD>
- Clear the screen leaving the current line at the top of the screen.
- With an argument, refresh the current line without clearing the
- screen.
- <DT><B>redraw-current-line</B>
- <DD>
- Refresh the current line.
- </DL>
- <A NAME="lbCO"> </A>
- <H4>Commands for Manipulating the History</H4>
- <P>
- <DL COMPACT>
- <DT><B>accept-line (Newline, Return)</B>
- <DD>
- Accept the line regardless of where the cursor is. If this line is
- non-empty, add it to the history list according to the state of the
- <FONT SIZE=-1><B>HISTCONTROL</B>
- </FONT>
- variable. If the line is a modified history
- line, then restore the history line to its original state.
- <DT><B>previous-history (C-p)</B>
- <DD>
- Fetch the previous command from the history list, moving back in
- the list.
- <DT><B>next-history (C-n)</B>
- <DD>
- Fetch the next command from the history list, moving forward in the
- list.
- <DT><B>beginning-of-history (M-<)</B>
- <DD>
- Move to the first line in the history.
- <DT><B>end-of-history (M->)</B>
- <DD>
- Move to the end of the input history, i.e., the line currently being
- entered.
- <DT><B>reverse-search-history (C-r)</B>
- <DD>
- Search backward starting at the current line and moving `up' through
- the history as necessary. This is an incremental search.
- <DT><B>forward-search-history (C-s)</B>
- <DD>
- Search forward starting at the current line and moving `down' through
- the history as necessary. This is an incremental search.
- <DT><B>non-incremental-reverse-search-history (M-p)</B>
- <DD>
- Search backward through the history starting at the current line
- using a non-incremental search for a string supplied by the user.
- <DT><B>non-incremental-forward-search-history (M-n)</B>
- <DD>
- Search forward through the history using a non-incremental search for
- a string supplied by the user.
- <DT><B>history-search-forward</B>
- <DD>
- Search forward through the history for the string of characters
- between the start of the current line and the point.
- This is a non-incremental search.
- <DT><B>history-search-backward</B>
- <DD>
- Search backward through the history for the string of characters
- between the start of the current line and the point.
- This is a non-incremental search.
- <DT><B>yank-nth-arg (M-C-y)</B>
- <DD>
- Insert the first argument to the previous command (usually
- the second word on the previous line) at point.
- With an argument
- <I>n</I>,
- insert the <I>n</I>th word from the previous command (the words
- in the previous command begin with word 0). A negative argument
- inserts the <I>n</I>th word from the end of the previous command.
- Once the argument <I>n</I> is computed, the argument is extracted
- as if the "!<I>n</I>" history expansion had been specified.
- <DT><B>yank-last-arg (M-., M-_)</B>
- <DD>
- Insert the last argument to the previous command (the last word of
- the previous history entry).
- With a numeric argument, behave exactly like <B>yank-nth-arg</B>.
- Successive calls to <B>yank-last-arg</B> move back through the history
- list, inserting the last word (or the word specified by the argument to
- the first call) of each line in turn.
- Any numeric argument supplied to these successive calls determines
- the direction to move through the history. A negative argument switches
- the direction through the history (back or forward).
- The history expansion facilities are used to extract the last word,
- as if the "!$" history expansion had been specified.
- <DT><B>shell-expand-line (M-C-e)</B>
- <DD>
- Expand the line as the shell does. This
- performs alias and history expansion as well as all of the shell
- word expansions. See
- <FONT SIZE=-1><B>HISTORY EXPANSION</B>
- </FONT>
- below for a description of history expansion.
- <DT><B>history-expand-line (M-^)</B>
- <DD>
- Perform history expansion on the current line.
- See
- <FONT SIZE=-1><B>HISTORY EXPANSION</B>
- </FONT>
- below for a description of history expansion.
- <DT><B>magic-space</B>
- <DD>
- Perform history expansion on the current line and insert a space.
- See
- <FONT SIZE=-1><B>HISTORY EXPANSION</B>
- </FONT>
- below for a description of history expansion.
- <DT><B>alias-expand-line</B>
- <DD>
- Perform alias expansion on the current line.
- See
- <FONT SIZE=-1><B>ALIASES</B>
- </FONT>
- above for a description of alias expansion.
- <DT><B>history-and-alias-expand-line</B>
- <DD>
- Perform history and alias expansion on the current line.
- <DT><B>insert-last-argument (M-., M-_)</B>
- <DD>
- A synonym for <B>yank-last-arg</B>.
- <DT><B>operate-and-get-next (C-o)</B>
- <DD>
- Accept the current line for execution and fetch the next line
- relative to the current line from the history for editing. Any
- argument is ignored.
- <DT><B>edit-and-execute-command (C-xC-e)</B>
- <DD>
- Invoke an editor on the current command line, and execute the result as shell
- commands.
- <B>Bash</B> attempts to invoke
- <FONT SIZE=-1><B>$VISUAL</B>,
- </FONT>
- <FONT SIZE=-1><B>$EDITOR</B>,
- </FONT>
- and <I>emacs</I> as the editor, in that order.
- </DL>
- <A NAME="lbCP"> </A>
- <H4>Commands for Changing Text</H4>
- <P>
- <DL COMPACT>
- <DT><B></B><I>end-of-file</I> (usually C-d)
- <DD>
- The character indicating end-of-file as set, for example, by
- <TT>stty</TT>.
- If this character is read when there are no characters
- on the line, and point is at the beginning of the line, Readline
- interprets it as the end of input and returns
- <FONT SIZE=-1><B>EOF</B>.
- </FONT>
- <DT><B>delete-char (C-d)</B>
- <DD>
- Delete the character at point.
- If this function is bound to the
- same character as the tty <B>EOF</B> character, as <B>C-d</B>
- commonly is, see above for the effects.
- <DT><B>backward-delete-char (Rubout)</B>
- <DD>
- Delete the character behind the cursor. When given a numeric argument,
- save the deleted text on the kill ring.
- <DT><B>forward-backward-delete-char</B>
- <DD>
- Delete the character under the cursor, unless the cursor is at the
- end of the line, in which case the character behind the cursor is
- deleted.
- <DT><B>quoted-insert (C-q, C-v)</B>
- <DD>
- Add the next character typed to the line verbatim. This is
- how to insert characters like <B>C-q</B>, for example.
- <DT><B>tab-insert (C-v TAB)</B>
- <DD>
- Insert a tab character.
- <DT><B>self-insert (a, b, A, 1, !, ...)</B>
- <DD>
- Insert the character typed.
- <DT><B>transpose-chars (C-t)</B>
- <DD>
- Drag the character before point forward over the character at point,
- moving point forward as well.
- If point is at the end of the line, then this transposes
- the two characters before point.
- Negative arguments have no effect.
- <DT><B>transpose-words (M-t)</B>
- <DD>
- Drag the word before point past the word after point,
- moving point over that word as well.
- If point is at the end of the line, this transposes
- the last two words on the line.
- <DT><B>upcase-word (M-u)</B>
- <DD>
- Uppercase the current (or following) word. With a negative argument,
- uppercase the previous word, but do not move point.
- <DT><B>downcase-word (M-l)</B>
- <DD>
- Lowercase the current (or following) word. With a negative argument,
- lowercase the previous word, but do not move point.
- <DT><B>capitalize-word (M-c)</B>
- <DD>
- Capitalize the current (or following) word. With a negative argument,
- capitalize the previous word, but do not move point.
- <DT><B>overwrite-mode</B>
- <DD>
- Toggle overwrite mode. With an explicit positive numeric argument,
- switches to overwrite mode. With an explicit non-positive numeric
- argument, switches to insert mode. This command affects only
- <B>emacs</B> mode; <B>vi</B> mode does overwrite differently.
- Each call to <I>readline()</I> starts in insert mode.
- In overwrite mode, characters bound to <B>self-insert</B> replace
- the text at point rather than pushing the text to the right.
- Characters bound to <B>backward-delete-char</B> replace the character
- before point with a space. By default, this command is unbound.
- </DL>
- <A NAME="lbCQ"> </A>
- <H4>Killing and Yanking</H4>
- <P>
- <DL COMPACT>
- <DT><B>kill-line (C-k)</B>
- <DD>
- Kill the text from point to the end of the line.
- <DT><B>backward-kill-line (C-x Rubout)</B>
- <DD>
- Kill backward to the beginning of the line.
- <DT><B>unix-line-discard (C-u)</B>
- <DD>
- Kill backward from point to the beginning of the line.
- The killed text is saved on the kill-ring.
- <DT><B>kill-whole-line</B>
- <DD>
- Kill all characters on the current line, no matter where point is.
- <DT><B>kill-word (M-d)</B>
- <DD>
- Kill from point to the end of the current word, or if between
- words, to the end of the next word.
- Word boundaries are the same as those used by <B>forward-word</B>.
- <DT><B>backward-kill-word (M-Rubout)</B>
- <DD>
- Kill the word behind point.
- Word boundaries are the same as those used by <B>backward-word</B>.
- <DT><B>shell-kill-word</B>
- <DD>
- Kill from point to the end of the current word, or if between
- words, to the end of the next word.
- Word boundaries are the same as those used by <B>shell-forward-word</B>.
- <DT><B>shell-backward-kill-word</B>
- <DD>
- Kill the word behind point.
- Word boundaries are the same as those used by <B>shell-backward-word</B>.
- <DT><B>unix-word-rubout (C-w)</B>
- <DD>
- Kill the word behind point, using white space as a word boundary.
- The killed text is saved on the kill-ring.
- <DT><B>unix-filename-rubout</B>
- <DD>
- Kill the word behind point, using white space and the slash character
- as the word boundaries.
- The killed text is saved on the kill-ring.
- <DT><B>delete-horizontal-space (M-\)</B>
- <DD>
- Delete all spaces and tabs around point.
- <DT><B>kill-region</B>
- <DD>
- Kill the text in the current region.
- <DT><B>copy-region-as-kill</B>
- <DD>
- Copy the text in the region to the kill buffer.
- <DT><B>copy-backward-word</B>
- <DD>
- Copy the word before point to the kill buffer.
- The word boundaries are the same as <B>backward-word</B>.
- <DT><B>copy-forward-word</B>
- <DD>
- Copy the word following point to the kill buffer.
- The word boundaries are the same as <B>forward-word</B>.
- <DT><B>yank (C-y)</B>
- <DD>
- Yank the top of the kill ring into the buffer at point.
- <DT><B>yank-pop (M-y)</B>
- <DD>
- Rotate the kill ring, and yank the new top. Only works following
- <B>yank</B>
- or
- <B>yank-pop</B>.
- </DL>
- <A NAME="lbCR"> </A>
- <H4>Numeric Arguments</H4>
- <P>
- <DL COMPACT>
- <DT><B>digit-argument (M-0, M-1, ..., M--)</B>
- <DD>
- Add this digit to the argument already accumulating, or start a new
- argument. M-- starts a negative argument.
- <DT><B>universal-argument</B>
- <DD>
- This is another way to specify an argument.
- If this command is followed by one or more digits, optionally with a
- leading minus sign, those digits define the argument.
- If the command is followed by digits, executing
- <B>universal-argument</B>
- again ends the numeric argument, but is otherwise ignored.
- As a special case, if this command is immediately followed by a
- character that is neither a digit nor minus sign, the argument count
- for the next command is multiplied by four.
- The argument count is initially one, so executing this function the
- first time makes the argument count four, a second time makes the
- argument count sixteen, and so on.
- </DL>
- <A NAME="lbCS"> </A>
- <H4>Completing</H4>
- <P>
- <DL COMPACT>
- <DT><B>complete (TAB)</B>
- <DD>
- Attempt to perform completion on the text before point.
- <B>Bash</B>
- attempts completion treating the text as a variable (if the
- text begins with <B>$</B>), username (if the text begins with
- <B>~</B>), hostname (if the text begins with <B>@</B>), or
- command (including aliases and functions) in turn. If none
- of these produces a match, filename completion is attempted.
- <DT><B>possible-completions (M-?)</B>
- <DD>
- List the possible completions of the text before point.
- <DT><B>insert-completions (M-*)</B>
- <DD>
- Insert all completions of the text before point
- that would have been generated by
- <B>possible-completions</B>.
- <DT><B>menu-complete</B>
- <DD>
- Similar to <B>complete</B>, but replaces the word to be completed
- with a single match from the list of possible completions.
- Repeated execution of <B>menu-complete</B> steps through the list
- of possible completions, inserting each match in turn.
- At the end of the list of completions, the bell is rung
- (subject to the setting of <B>bell-style</B>)
- and the original text is restored.
- An argument of <I>n</I> moves <I>n</I> positions forward in the list
- of matches; a negative argument may be used to move backward
- through the list.
- This command is intended to be bound to <B>TAB</B>, but is unbound
- by default.
- <DT><B>menu-complete-backward</B>
- <DD>
- Identical to <B>menu-complete</B>, but moves backward through the list
- of possible completions, as if <B>menu-complete</B> had been given a
- negative argument. This command is unbound by default.
- <DT><B>delete-char-or-list</B>
- <DD>
- Deletes the character under the cursor if not at the beginning or
- end of the line (like <B>delete-char</B>).
- If at the end of the line, behaves identically to
- <B>possible-completions</B>.
- This command is unbound by default.
- <DT><B>complete-filename (M-/)</B>
- <DD>
- Attempt filename completion on the text before point.
- <DT><B>possible-filename-completions (C-x /)</B>
- <DD>
- List the possible completions of the text before point,
- treating it as a filename.
- <DT><B>complete-username (M-~)</B>
- <DD>
- Attempt completion on the text before point, treating
- it as a username.
- <DT><B>possible-username-completions (C-x ~)</B>
- <DD>
- List the possible completions of the text before point,
- treating it as a username.
- <DT><B>complete-variable (M-$)</B>
- <DD>
- Attempt completion on the text before point, treating
- it as a shell variable.
- <DT><B>possible-variable-completions (C-x $)</B>
- <DD>
- List the possible completions of the text before point,
- treating it as a shell variable.
- <DT><B>complete-hostname (M-@)</B>
- <DD>
- Attempt completion on the text before point, treating
- it as a hostname.
- <DT><B>possible-hostname-completions (C-x @)</B>
- <DD>
- List the possible completions of the text before point,
- treating it as a hostname.
- <DT><B>complete-command (M-!)</B>
- <DD>
- Attempt completion on the text before point, treating
- it as a command name. Command completion attempts to
- match the text against aliases, reserved words, shell
- functions, shell builtins, and finally executable filenames,
- in that order.
- <DT><B>possible-command-completions (C-x !)</B>
- <DD>
- List the possible completions of the text before point,
- treating it as a command name.
- <DT><B>dynamic-complete-history (M-TAB)</B>
- <DD>
- Attempt completion on the text before point, comparing
- the text against lines from the history list for possible
- completion matches.
- <DT><B>dabbrev-expand</B>
- <DD>
- Attempt menu completion on the text before point, comparing
- the text against lines from the history list for possible
- completion matches.
- <DT><B>complete-into-braces (M-{)</B>
- <DD>
- Perform filename completion and insert the list of possible completions
- enclosed within braces so the list is available to the shell (see
- <B>Brace Expansion</B>
- above).
- </DL>
- <A NAME="lbCT"> </A>
- <H4>Keyboard Macros</H4>
- <P>
- <DL COMPACT>
- <DT><B>start-kbd-macro (C-x ()</B>
- <DD>
- Begin saving the characters typed into the current keyboard macro.
- <DT><B>end-kbd-macro (C-x ))</B>
- <DD>
- Stop saving the characters typed into the current keyboard macro
- and store the definition.
- <DT><B>call-last-kbd-macro (C-x e)</B>
- <DD>
- Re-execute the last keyboard macro defined, by making the characters
- in the macro appear as if typed at the keyboard.
- <DT><B>print-last-kbd-macro ()</B>
- <DD>
- Print the last keyboard macro defined in a format suitable for the
- <I>inputrc</I> file.
- </DL>
- <A NAME="lbCU"> </A>
- <H4>Miscellaneous</H4>
- <P>
- <DL COMPACT>
- <DT><B>re-read-init-file (C-x C-r)</B>
- <DD>
- Read in the contents of the <I>inputrc</I> file, and incorporate
- any bindings or variable assignments found there.
- <DT><B>abort (C-g)</B>
- <DD>
- Abort the current editing command and
- ring the terminal's bell (subject to the setting of
- <B>bell-style</B>).
- <DT><B>do-uppercase-version (M-a, M-b, M-</B><I>x</I>, ...)
- <DD>
- If the metafied character <I>x</I> is lowercase, run the command
- that is bound to the corresponding uppercase character.
- <DT><B>prefix-meta (ESC)</B>
- <DD>
- Metafy the next character typed.
- <FONT SIZE=-1><B>ESC</B>
- </FONT>
- <B>f</B>
- is equivalent to
- <B>Meta-f</B>.
- <DT><B>undo (C-_, C-x C-u)</B>
- <DD>
- Incremental undo, separately remembered for each line.
- <DT><B>revert-line (M-r)</B>
- <DD>
- Undo all changes made to this line. This is like executing the
- <B>undo</B>
- command enough times to return the line to its initial state.
- <DT><B>tilde-expand (M-&)</B>
- <DD>
- Perform tilde expansion on the current word.
- <DT><B>set-mark (C-@, M-<space>)</B>
- <DD>
- Set the mark to the point. If a
- numeric argument is supplied, the mark is set to that position.
- <DT><B>exchange-point-and-mark (C-x C-x)</B>
- <DD>
- Swap the point with the mark. The current cursor position is set to
- the saved position, and the old cursor position is saved as the mark.
- <DT><B>character-search (C-])</B>
- <DD>
- A character is read and point is moved to the next occurrence of that
- character. A negative count searches for previous occurrences.
- <DT><B>character-search-backward (M-C-])</B>
- <DD>
- A character is read and point is moved to the previous occurrence of that
- character. A negative count searches for subsequent occurrences.
- <DT><B>skip-csi-sequence</B>
- <DD>
- Read enough characters to consume a multi-key sequence such as those
- defined for keys like Home and End. Such sequences begin with a
- Control Sequence Indicator (CSI), usually ESC-[. If this sequence is
- bound to "\[", keys producing such sequences will have no effect
- unless explicitly bound to a readline command, instead of inserting
- stray characters into the editing buffer. This is unbound by default,
- but usually bound to ESC-[.
- <DT><B>insert-comment (M-#)</B>
- <DD>
- Without a numeric argument, the value of the readline
- <B>comment-begin</B>
- variable is inserted at the beginning of the current line.
- If a numeric argument is supplied, this command acts as a toggle: if
- the characters at the beginning of the line do not match the value
- of <B>comment-begin</B>, the value is inserted, otherwise
- the characters in <B>comment-begin</B> are deleted from the beginning of
- the line.
- In either case, the line is accepted as if a newline had been typed.
- The default value of
- <B>comment-begin</B> causes this command to make the current line
- a shell comment.
- If a numeric argument causes the comment character to be removed, the line
- will be executed by the shell.
- <DT><B>glob-complete-word (M-g)</B>
- <DD>
- The word before point is treated as a pattern for pathname expansion,
- with an asterisk implicitly appended. This pattern is used to
- generate a list of matching filenames for possible completions.
- <DT><B>glob-expand-word (C-x *)</B>
- <DD>
- The word before point is treated as a pattern for pathname expansion,
- and the list of matching filenames is inserted, replacing the word.
- If a numeric argument is supplied, an asterisk is appended before
- pathname expansion.
- <DT><B>glob-list-expansions (C-x g)</B>
- <DD>
- The list of expansions that would have been generated by
- <B>glob-expand-word</B>
- is displayed, and the line is redrawn.
- If a numeric argument is supplied, an asterisk is appended before
- pathname expansion.
- <DT><B>dump-functions</B>
- <DD>
- Print all of the functions and their key bindings to the
- readline output stream. If a numeric argument is supplied,
- the output is formatted in such a way that it can be made part
- of an <I>inputrc</I> file.
- <DT><B>dump-variables</B>
- <DD>
- Print all of the settable readline variables and their values to the
- readline output stream. If a numeric argument is supplied,
- the output is formatted in such a way that it can be made part
- of an <I>inputrc</I> file.
- <DT><B>dump-macros</B>
- <DD>
- Print all of the readline key sequences bound to macros and the
- strings they output. If a numeric argument is supplied,
- the output is formatted in such a way that it can be made part
- of an <I>inputrc</I> file.
- <DT><B>display-shell-version (C-x C-v)</B>
- <DD>
- Display version information about the current instance of
- <B>bash</B>.
- </DL>
- <A NAME="lbCV"> </A>
- <H4>Programmable Completion</H4>
- <P>
- When word completion is attempted for an argument to a command for
- which a completion specification (a <I>compspec</I>) has been defined
- using the <B>complete</B> builtin (see
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below), the programmable completion facilities are invoked.
- <P>
- First, the command name is identified.
- If the command word is the empty string (completion attempted at the
- beginning of an empty line), any compspec defined with
- the <B>-E</B> option to <B>complete</B> is used.
- If a compspec has been defined for that command, the
- compspec is used to generate the list of possible completions for the word.
- If the command word is a full pathname, a compspec for the full
- pathname is searched for first.
- If no compspec is found for the full pathname, an attempt is made to
- find a compspec for the portion following the final slash.
- If those searches do not result in a compspec, any compspec defined with
- the <B>-D</B> option to <B>complete</B> is used as the default.
- <P>
- Once a compspec has been found, it is used to generate the list of
- matching words.
- If a compspec is not found, the default <B>bash</B> completion as
- described above under <B>Completing</B> is performed.
- <P>
- First, the actions specified by the compspec are used.
- Only matches which are prefixed by the word being completed are
- returned.
- When the
- <B>-f</B>
- or
- <B>-d</B>
- option is used for filename or directory name completion, the shell
- variable
- <FONT SIZE=-1><B>FIGNORE</B>
- </FONT>
- is used to filter the matches.
- <P>
- Any completions specified by a pathname expansion pattern to the
- <B>-G</B> option are generated next.
- The words generated by the pattern need not match the word
- being completed.
- The
- <FONT SIZE=-1><B>GLOBIGNORE</B>
- </FONT>
- shell variable is not used to filter the matches, but the
- <FONT SIZE=-1><B>FIGNORE</B>
- </FONT>
- variable is used.
- <P>
- Next, the string specified as the argument to the <B>-W</B> option
- is considered.
- The string is first split using the characters in the
- <FONT SIZE=-1><B>IFS</B>
- </FONT>
- special variable as delimiters.
- Shell quoting is honored.
- Each word is then expanded using
- brace expansion, tilde expansion, parameter and variable expansion,
- command substitution, and arithmetic expansion,
- as described above under
- <FONT SIZE=-1><B>EXPANSION</B>.
- </FONT>
- The results are split using the rules described above under
- <B>Word Splitting</B>.
- The results of the expansion are prefix-matched against the word being
- completed, and the matching words become the possible completions.
- <P>
- After these matches have been generated, any shell function or command
- specified with the <B>-F</B> and <B>-C</B> options is invoked.
- When the command or function is invoked, the
- <FONT SIZE=-1><B>COMP_LINE</B>,
- </FONT>
- <FONT SIZE=-1><B>COMP_POINT</B>,
- </FONT>
- <FONT SIZE=-1><B>COMP_KEY</B>,
- </FONT>
- and
- <FONT SIZE=-1><B>COMP_TYPE</B>
- </FONT>
- variables are assigned values as described above under
- <B>Shell Variables</B>.
- If a shell function is being invoked, the
- <FONT SIZE=-1><B>COMP_WORDS</B>
- </FONT>
- and
- <FONT SIZE=-1><B>COMP_CWORD</B>
- </FONT>
- variables are also set.
- When the function or command is invoked,
- the first argument (<B>$1</B>) is the name of the command whose arguments are
- being completed,
- the second argument (<B>$2</B>) is the word being completed,
- and the third argument (<B>$3</B>) is the word preceding the word being
- completed on the current command line.
- No filtering of the generated completions against the word being completed
- is performed; the function or command has complete freedom in generating
- the matches.
- <P>
- Any function specified with <B>-F</B> is invoked first.
- The function may use any of the shell facilities, including the
- <B>compgen</B> builtin described below, to generate the matches.
- It must put the possible completions in the
- <FONT SIZE=-1><B>COMPREPLY</B>
- </FONT>
- array variable, one per array element.
- <P>
- Next, any command specified with the <B>-C</B> option is invoked
- in an environment equivalent to command substitution.
- It should print a list of completions, one per line, to the
- standard output.
- Backslash may be used to escape a newline, if necessary.
- <P>
- After all of the possible completions are generated, any filter
- specified with the <B>-X</B> option is applied to the list.
- The filter is a pattern as used for pathname expansion; a <B>&</B>
- in the pattern is replaced with the text of the word being completed.
- A literal <B>&</B> may be escaped with a backslash; the backslash
- is removed before attempting a match.
- Any completion that matches the pattern will be removed from the list.
- A leading <B>!</B> negates the pattern; in this case any completion
- not matching the pattern will be removed.
- If the
- <B>nocasematch</B>
- shell option is enabled, the match is performed without regard to the case
- of alphabetic characters.
- <P>
- Finally, any prefix and suffix specified with the <B>-P</B> and <B>-S</B>
- options are added to each member of the completion list, and the result is
- returned to the readline completion code as the list of possible
- completions.
- <P>
- If the previously-applied actions do not generate any matches, and the
- <B>-o dirnames</B> option was supplied to <B>complete</B> when the
- compspec was defined, directory name completion is attempted.
- <P>
- If the <B>-o plusdirs</B> option was supplied to <B>complete</B> when the
- compspec was defined, directory name completion is attempted and any
- matches are added to the results of the other actions.
- <P>
- By default, if a compspec is found, whatever it generates is returned
- to the completion code as the full set of possible completions.
- The default <B>bash</B> completions are not attempted, and the readline
- default of filename completion is disabled.
- If the <B>-o bashdefault</B> option was supplied to <B>complete</B> when
- the compspec was defined, the <B>bash</B> default completions are attempted
- if the compspec generates no matches.
- If the <B>-o default</B> option was supplied to <B>complete</B> when the
- compspec was defined, readline's default completion will be performed
- if the compspec (and, if attempted, the default <B>bash</B> completions)
- generate no matches.
- <P>
- When a compspec indicates that directory name completion is desired,
- the programmable completion functions force readline to append a slash
- to completed names which are symbolic links to directories, subject to
- the value of the <B>mark-directories</B> readline variable, regardless
- of the setting of the <B>mark-symlinked-directories</B> readline variable.
- <P>
- There is some support for dynamically modifying completions. This is
- most useful when used in combination with a default completion specified
- with <B>complete -D</B>.
- It's possible for shell functions executed as completion
- handlers to indicate that completion should be retried by returning an
- exit status of 124. If a shell function returns 124, and changes
- the compspec associated with the command on which completion is being
- attempted (supplied as the first argument when the function is executed),
- programmable completion restarts from the beginning, with an
- attempt to find a new compspec for that command. This allows a set of
- completions to be built dynamically as completion is attempted, rather than
- being loaded all at once.
- <P>
- For instance, assuming that there is a library of compspecs, each kept in a
- file corresponding to the name of the command, the following default
- completion function would load completions dynamically:
- <P>
- <TT>_completion_loader()
- <BR>
- {
- <BR>
- <TT> </TT>. "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124<BR>
- <BR>
- }
- <BR>
- complete -D -F _completion_loader -o bashdefault -o default
- <BR>
- </TT>
- <A NAME="lbCW"> </A>
- <H3>HISTORY</H3>
- When the
- <B>-o history</B>
- option to the
- <B>set</B>
- builtin is enabled, the shell provides access to the
- <I>command history</I>,
- the list of commands previously typed.
- The value of the
- <FONT SIZE=-1><B>HISTSIZE</B>
- </FONT>
- variable is used as the
- number of commands to save in a history list.
- The text of the last
- <FONT SIZE=-1><B>HISTSIZE</B>
- </FONT>
- commands (default 500) is saved. The shell
- stores each command in the history list prior to parameter and
- variable expansion (see
- <FONT SIZE=-1><B>EXPANSION</B>
- </FONT>
- above) but after history expansion is performed, subject to the
- values of the shell variables
- <FONT SIZE=-1><B>HISTIGNORE</B>
- </FONT>
- and
- <FONT SIZE=-1><B>HISTCONTROL</B>.
- </FONT>
- <P>
- On startup, the history is initialized from the file named by
- the variable
- <FONT SIZE=-1><B>HISTFILE</B>
- </FONT>
- (default <A HREF="file:~/.bash_history"><I>~/.bash_history</I></A>).
- The file named by the value of
- <FONT SIZE=-1><B>HISTFILE</B>
- </FONT>
- is truncated, if necessary, to contain no more than
- the number of lines specified by the value of
- <FONT SIZE=-1><B>HISTFILESIZE</B>.
- </FONT>
- If <B>HISTFILESIZE</B> is unset, or set to null, a non-numeric value,
- or a numeric value less than zero, the history file is not truncated.
- When the history file is read,
- lines beginning with the history comment character followed immediately
- by a digit are interpreted as timestamps for the preceding history line.
- These timestamps are optionally displayed depending on the value of the
- <FONT SIZE=-1><B>HISTTIMEFORMAT</B>
- </FONT>
- variable.
- When a shell with history enabled exits, the last
- <FONT SIZE=-1><B>$HISTSIZE</B>
- </FONT>
- lines are copied from the history list to
- <FONT SIZE=-1><B>$HISTFILE</B>.
- </FONT>
- If the
- <B>histappend</B>
- shell option is enabled
- (see the description of
- <B>shopt</B>
- under
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below), the lines are appended to the history file,
- otherwise the history file is overwritten.
- If
- <FONT SIZE=-1><B>HISTFILE</B>
- </FONT>
- is unset, or if the history file is unwritable, the history is
- not saved.
- If the
- <FONT SIZE=-1><B>HISTTIMEFORMAT</B>
- </FONT>
- variable is set, time stamps are written to the history file, marked
- with the history comment character, so
- they may be preserved across shell sessions.
- This uses the history comment character to distinguish timestamps from
- other history lines.
- After saving the history, the history file is truncated
- to contain no more than
- <FONT SIZE=-1><B>HISTFILESIZE</B>
- </FONT>
- lines. If
- <FONT SIZE=-1><B>HISTFILESIZE</B>
- </FONT>
- is unset, or set to null, a non-numeric value,
- or a numeric value less than zero, the history file is not truncated.
- <P>
- The builtin command
- <B>fc</B>
- (see
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below) may be used to list or edit and re-execute a portion of
- the history list.
- The
- <B>history</B>
- builtin may be used to display or modify the history list and
- manipulate the history file.
- When using command-line editing, search commands
- are available in each editing mode that provide access to the
- history list.
- <P>
- The shell allows control over which commands are saved on the history
- list. The
- <FONT SIZE=-1><B>HISTCONTROL</B>
- </FONT>
- and
- <FONT SIZE=-1><B>HISTIGNORE</B>
- </FONT>
- variables may be set to cause the shell to save only a subset of the
- commands entered.
- The
- <B>cmdhist</B>
- shell option, if enabled, causes the shell to attempt to save each
- line of a multi-line command in the same history entry, adding
- semicolons where necessary to preserve syntactic correctness.
- The
- <B>lithist</B>
- shell option causes the shell to save the command with embedded newlines
- instead of semicolons. See the description of the
- <B>shopt</B>
- builtin below under
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- for information on setting and unsetting shell options.
- <A NAME="lbCX"> </A>
- <H3>HISTORY EXPANSION</H3>
- <P>
- The shell supports a history expansion feature that
- is similar to the history expansion in
- <B>csh.</B>
- This section describes what syntax features are available. This
- feature is enabled by default for interactive shells, and can be
- disabled using the
- <B>+H</B>
- option to the
- <B>set</B>
- builtin command (see
- <FONT SIZE=-1><B>SHELL BUILTIN COMMANDS</B>
- </FONT>
- below). Non-interactive shells do not perform history expansion
- by default.
- <P>
- History expansions introduce words from the history list into
- the input stream, making it easy to repeat commands, insert the
- arguments to a previous command into the current input line, or
- fix errors in previous commands quickly.
- <P>
- History expansion is performed immediately after a complete line
- is read, before the shell breaks it into words.
- It takes place in two parts.
- The first is to determine which line from the history list
- to use during substitution.
- The second is to select portions of that line for inclusion into
- the current one.
- The line selected from the history is the <I>event</I>,
- and the portions of that line that are acted upon are <I>words</I>.
- Various <I>modifiers</I> are available to manipulate the selected words.
- The line is broken into words in the same fashion as when reading input,
- so that several <I>metacharacter</I>-separated words surrounded by
- quotes are considered one word.
- History expansions are introduced by the appearance of the
- history expansion character, which is <B>!</B> by default.
- Only backslash (<B>\</B>) and single quotes can quote
- the history expansion character, but the history expansion character is
- also treated as quoted if it immediately precedes the closing double quote
- in a double-quoted string.
- <P>
- Several characters inhibit history expansion if found immediately
- following the history expansion character, even if it is unquoted:
- space, tab, newline, carriage return, and <B>=</B>.
- If the <B>extglob</B> shell option is enabled, <B>(</B> will also
- inhibit expansion.
- <P>
- Several shell options settable with the
- <B>shopt</B>
- builtin may be used to tailor the behavior of history expansion.
- If the
- <B>histverify</B>
- shell option is enabled (see the description of the
- <B>shopt</B>
- builtin below), and
- <B>readline</B>
- is being used, history substitutions are not immediately passed to
- the shell parser.
- Instead, the expanded line is reloaded into the
- <B>readline</B>
- editing buffer for further modification.
- If
- <B>readline</B>
- is being used, and the
- <B>histreedit</B>
- shell option is enabled, a failed history substitution will be reloaded
- into the
- <B>readline</B>
- editing buffer for correction.
- The
- <B>-p</B>
- option to the
- <B>history</B>
- builtin command may be used to see what a history expansion will
- do before using it.
- The
- <B>-s</B>
- option to the
- <B>history</B>
- builtin may be used to add commands to the end of the history list
- without actually executing them, so that they are available for
- subsequent recall.
- <P>
- The shell allows control of the various characters used by the
- history expansion mechanism (see the description of
- <B>histchars</B>
- above under
- <B>Shell Variables</B>).
- The shell uses
- the history comment character to mark history timestamps when
- writing the history file.
- <A NAME="lbCY"> </A>
- <H4>Event Designators</H4>
- <P>
- An event designator is a reference to a command line entry in the
- history list.
- Unless the reference is absolute, events are relative to the current
- position in the history list.
- <P>
- <DL COMPACT>
- <DT><B>!</B>
- <DD>
- Start a history substitution, except when followed by a
- <B>blank</B>,
- newline, carriage return, =
- or ( (when the <B>extglob</B> shell option is enabled using
- the <B>shopt</B> builtin).
- <DT><B>!</B><I>n</I>
- <DD>
- Refer to command line
- <I>n</I>.
- <DT><B>!-</B><I>n</I>
- <DD>
- Refer to the current command minus
- <I>n</I>.
- <DT><B>!!</B>
- <DD>
- Refer to the previous command. This is a synonym for `!-1'.
- <DT><B>!</B><I>string</I>
- <DD>
- Refer to the most recent command preceding the current position in the
- history list starting with
- <I>string</I>.
- <DT><B>!?</B><I>string</I><B>[?]</B>
- <DD>
- Refer to the most recent command preceding the current position in the
- history list containing
- <I>string</I>.
- The trailing <B>?</B> may be omitted if
- <I>string</I>
- is followed immediately by a newline.
- <DT><B></B><FONT SIZE=+2><B>^</B></FONT><B></B><I>string1</I><FONT SIZE=+2>^</FONT><I>string2</I><FONT SIZE=+2>^</FONT>
- <DD>
- Quick substitution. Repeat the previous command, replacing
- <I>string1</I>
- with
- <I>string2</I>.
- Equivalent to
- ``!!:s/<I>string1</I>/<I>string2</I>/''
- (see <B>Modifiers</B> below).
- <DT><B>!#</B>
- <DD>
- The entire command line typed so far.
- </DL>
- <A NAME="lbCZ"> </A>
- <H4>Word Designators</H4>
- <P>
- Word designators are used to select desired words from the event.
- A
- <B>:</B>
- separates the event specification from the word designator.
- It may be omitted if the word designator begins with a
- <B>^</B>,
- <B>$</B>,
- <B>*</B>,
- <B>-</B>,
- or
- <B>%</B>.
- Words are numbered from the beginning of the line,
- with the first word being denoted by 0 (zero).
- Words are inserted into the current line separated by single spaces.
- <P>
- <DL COMPACT>
- <DT><B>0 (zero)</B>
- <DD>
- The zeroth word. For the shell, this is the command
- word.
- <DT><I>n</I>
- <DD>
- The <I>n</I>th word.
- <DT><B>^</B>
- <DD>
- The first argument. That is, word 1.
- <DT><B>$</B>
- <DD>
- The last word. This is usually the last argument, but will expand to the
- zeroth word if there is only one word in the line.
- <DT><B>%</B>
- <DD>
- The word matched by the most recent `?<I>string</I>?' search.
- <DT><I>x</I><B>-</B>y
- <DD>
- A range of words; `-<I>y</I>' abbreviates `0-<I>y</I>'.
- <DT><B>*</B>
- <DD>
- All of the words but the zeroth. This is a synonym
- for `<I>1-$</I>'. It is not an error to use
- <B>*</B>
- if there is just one
- word in the event; the empty string is returned in that case.
- <DT><B>x*</B>
- <DD>
- Abbreviates <I>x-$</I>.
- <DT><B>x-</B>
- <DD>
- Abbreviates <I>x-$</I> like <B>x*</B>, but omits the last word.
- </DL>
- <P>
- If a word designator is supplied without an event specification, the
- previous command is used as the event.
- <A NAME="lbDA"> </A>
- <H4>Modifiers</H4>
- <P>
- After the optional word designator, there may appear a sequence of
- one or more of the following modifiers, each preceded by a `:'.
- <P>
- <P>
- <DL COMPACT>
- <DT><B>h</B>
- <DD>
- Remove a trailing filename component, leaving only the head.
- <DT><B>t</B>
- <DD>
- Remove all leading filename components, leaving the tail.
- <DT><B>r</B>
- <DD>
- Remove a trailing suffix of the form <I>.xxx</I>, leaving the
- basename.
- <DT><B>e</B>
- <DD>
- Remove all but the trailing suffix.
- <DT><B>p</B>
- <DD>
- Print the new command but do not execute it.
- <DT><B>q</B>
- <DD>
- Quote the substituted words, escaping further substitutions.
- <DT><B>x</B>
- <DD>
- Quote the substituted words as with
- <B>q</B>,
- but break into words at
- <B>blanks</B>
- and newlines.
- <DT><B>s/</B><I>old</I>/<I>new</I>/
- <DD>
- Substitute
- <I>new</I>
- for the first occurrence of
- <I>old</I>
- in the event line. Any delimiter can be used in place of /. The
- final delimiter is optional if it is the last character of the
- event line. The delimiter may be quoted in
- <I>old</I>
- and
- <I>new</I>
- with a single backslash. If & appears in
- <I>new</I>,
- it is replaced by
- <I>old</I>.
- A single backslash will quote the &. If
- <I>old</I>
- is null, it is set to the last
- <I>old</I>
- substituted, or, if no previous history substitutions took place,
- the last
- <I>string</I>
- in a
- <B>!?</B><I>string</I><B>[?]</B>
- search.
- <DT><B>&</B>
- <DD>
- Repeat the previous substitution.
- <DT><B>g</B>
- <DD>
- Cause changes to be applied over the entire event line. This is
- used in conjunction with `<B>:s</B>' (e.g., `<B>:gs/</B><I>old</I>/<I>new</I>/')
- or `<B>:&</B>'. If used with
- `<B>:s</B>', any delimiter can be used
- in place of /, and the final delimiter is optional
- if it is the last character of the event line.
- An <B>a</B> may be used as a synonym for <B>g</B>.
- <DT><B>G</B>
- <DD>
- Apply the following `<B>s</B>' modifier once to each word in the event line.
- </DL>
- <A NAME="lbDB"> </A>
- <H3>SHELL BUILTIN COMMANDS</H3>
- <P>
- Unless otherwise noted, each builtin command documented in this
- section as accepting options preceded by
- <B>-</B>
- accepts
- <B>--</B>
- to signify the end of the options.
- The <B>:</B>, <B>true</B>, <B>false</B>, and <B>test</B> builtins
- do not accept options and do not treat <B>--</B> specially.
- The <B>exit</B>, <B>logout</B>, <B>return</B>,
- <B>break</B>, <B>continue</B>, <B>let</B>,
- and <B>shift</B> builtins accept and process arguments beginning with
- <B>-</B> without requiring <B>--</B>.
- Other builtins that accept arguments but are not specified as accepting
- options interpret arguments beginning with <B>-</B> as invalid options and
- require <B>--</B> to prevent this interpretation.
- <P>
- <DL COMPACT>
- <DT><B>:</B> [<I>arguments</I>]<DD>
- No effect; the command does nothing beyond expanding
- <I>arguments</I>
- and performing any specified
- redirections.
- The return status is zero.
- <DT><B> . </B> <I>filename</I> [<I>arguments</I>]<DD>
- <DT><B>source</B> <I>filename</I> [<I>arguments</I>]<DD>
- Read and execute commands from
- <I>filename</I>
- in the current
- shell environment and return the exit status of the last command
- executed from
- <I>filename</I>.
- If
- <I>filename</I>
- does not contain a slash, filenames in
- <FONT SIZE=-1><B>PATH</B>
- </FONT>
- are used to find the directory containing
- <I>filename</I>.
- The file searched for in
- <FONT SIZE=-1><B>PATH</B>
- </FONT>
- need not be executable.
- When <B>bash</B> is not in <I>posix mode</I>, the current directory is
- searched if no file is found in
- <FONT SIZE=-1><B>PATH</B>.
- </FONT>
- If the
- <B>sourcepath</B>
- option to the
- <B>shopt</B>
- builtin command is turned off, the
- <FONT SIZE=-1><B>PATH</B>
- </FONT>
- is not searched.
- If any <I>arguments</I> are supplied, they become the positional
- parameters when <I>filename</I> is executed. Otherwise the positional
- parameters are unchanged.
- If the <B>-T</B> option is enabled, <B>source</B> inherits any trap on
- <B>DEBUG</B>; if it is not, any <B>DEBUG</B> trap string is saved and
- restored around the call to <B>source</B>, and <B>source</B> unsets the
- <B>DEBUG</B> trap while it executes.
- If <B>-T</B> is not set, and the sourced file changes
- the <B>DEBUG</B> trap, the new value is retained when <B>source</B> completes.
- The return status is the status of the last command exited within
- the script (0 if no commands are executed), and false if
- <I>filename</I>
- is not found or cannot be read.
- <DT><B>alias</B> [<B>-p</B>] [<I>name</I>[=<I>value</I>] ...]<DD>
- <B>Alias</B> with no arguments or with the
- <B>-p</B>
- option prints the list of aliases in the form
- <B>alias</B> <I>name</I>=<I>value</I> on standard output.
- When arguments are supplied, an alias is defined for
- each <I>name</I> whose <I>value</I> is given.
- A trailing space in <I>value</I> causes the next word to be
- checked for alias substitution when the alias is expanded.
- For each <I>name</I> in the argument list for which no <I>value</I>
- is supplied, the name and value of the alias is printed.
- <B>Alias</B> returns true unless a <I>name</I> is given for which
- no alias has been defined.
- <DT><B>bg</B> [<I>jobspec</I> ...]<DD>
- Resume each suspended job <I>jobspec</I> in the background, as if it
- had been started with
- <B>&</B>.
- If
- <I>jobspec</I>
- is not present, the shell's notion of the <I>current job</I> is used.
- <B>bg</B>
- <I>jobspec</I>
- returns 0 unless run when job control is disabled or, when run with
- job control enabled, any specified <I>jobspec</I> was not found
- or was started without job control.
- <DT><B>bind</B> [<B>-m</B> <I>keymap</I>] [<B>-lpsvPSVX</B>]<DD>
- <DT><B>bind</B> [<B>-m</B> <I>keymap</I>] [<B>-q</B> <I>function</I>] [<B>-u</B> <I>function</I>] [<B>-r</B> <I>keyseq</I>]<DD>
- <DT><B>bind</B> [<B>-m</B> <I>keymap</I>] <B>-f</B> <I>filename</I><DD>
- <DT><B>bind</B> [<B>-m</B> <I>keymap</I>] <B>-x</B> <I>keyseq</I>:<I>shell-command</I><DD>
- <DT><B>bind</B> [<B>-m</B> <I>keymap</I>] <I>keyseq</I>:<I>function-name</I><DD>
- <DT><B>bind</B> [<B>-m</B> <I>keymap</I>] <I>keyseq</I>:<I>readline-command</I><DD>
- Display current
- <B>readline</B>
- key and function bindings, bind a key sequence to a
- <B>readline</B>
- function or macro, or set a
- <B>readline</B>
- variable.
- Each non-option argument is a command as it would appear in
- <I>.inputrc</I>,
- but each binding or command must be passed as a separate argument;
- e.g., '"\C-x\C-r": re-read-init-file'.
- Options, if supplied, have the following meanings:
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>-m </B><I>keymap</I>
- <DD>
- Use
- <I>keymap</I>
- as the keymap to be affected by the subsequent bindings.
- Acceptable
- <I>keymap</I>
- names are
- <I>emacs, emacs-standard, emacs-meta, emacs-ctlx, vi,
- vi-move, vi-command</I>, and
- <I>vi-insert</I>.
- <I>vi</I> is equivalent to <I>vi-command</I> (<I>vi-move</I> is also
- a synonym); <I>emacs</I> is
- equivalent to <I>emacs-standard</I>.
- <DT><B>-l</B>
- <DD>
- List the names of all <B>readline</B> functions.
- <DT><B>-p</B>
- <DD>
- Display <B>readline</B> function names and bindings in such a way
- that they can be re-read.
- <DT><B>-P</B>
- <DD>
- List current <B>readline</B> function names and bindings.
- <DT><B>-s</B>
- <DD>
- Display <B>readline</B> key sequences bound to macros and the strings
- they output in such a way that they can be re-read.
- <DT><B>-S</B>
- <DD>
- Display <B>readline</B> key sequences bound to macros and the strings
- they output.
- <DT><B>-v</B>
- <DD>
- Display <B>readline</B> variable names and values in such a way that they
- can be re-read.
- <DT><B>-V</B>
- <DD>
- List current <B>readline</B> variable names and values.
- <DT><B>-f </B><I>filename</I>
- <DD>
- Read key bindings from <I>filename</I>.
- <DT><B>-q </B><I>function</I>
- <DD>
- Query about which keys invoke the named <I>function</I>.
- <DT><B>-u </B><I>function</I>
- <DD>
- Unbind all keys bound to the named <I>function</I>.
- <DT><B>-r </B><I>keyseq</I>
- <DD>
- Remove any current binding for <I>keyseq</I>.
- <DT><B>-x </B><I>keyseq</I>:<I>shell-command</I>
- <DD>
- Cause <I>shell-command</I> to be executed whenever <I>keyseq</I> is
- entered.
- When <I>shell-command</I> is executed, the shell sets the
- <FONT SIZE=-1><B>READLINE_LINE</B>
- </FONT>
- variable to the contents of the <B>readline</B> line buffer and the
- <FONT SIZE=-1><B>READLINE_POINT</B>
- </FONT>
- variable to the current location of the insertion point.
- If the executed command changes the value of
- <FONT SIZE=-1><B>READLINE_LINE</B>
- </FONT>
- or
- <FONT SIZE=-1><B>READLINE_POINT</B>,
- </FONT>
- those new values will be reflected in the editing state.
- <DT><B>-X</B>
- <DD>
- List all key sequences bound to shell commands and the associated commands
- in a format that can be reused as input.
- </DL>
- <P>
- The return value is 0 unless an unrecognized option is given or an
- error occurred.
- </DL>
- <DT><B>break</B> [<I>n</I>]<DD>
- Exit from within a
- <B>for</B>,
- <B>while</B>,
- <B>until</B>,
- or
- <B>select</B>
- loop. If <I>n</I> is specified, break <I>n</I> levels.
- <I>n</I>
- must be >= 1. If
- <I>n</I>
- is greater than the number of enclosing loops, all enclosing loops
- are exited.
- The return value is 0 unless <I>n</I> is not greater than or equal to 1.
- <DT><B>builtin</B> <I>shell-builtin</I> [<I>arguments</I>]<DD>
- Execute the specified shell builtin, passing it
- <I>arguments</I>,
- and return its exit status.
- This is useful when defining a
- function whose name is the same as a shell builtin,
- retaining the functionality of the builtin within the function.
- The <B>cd</B> builtin is commonly redefined this way.
- The return status is false if
- <I>shell-builtin</I>
- is not a shell builtin command.
- <DT><B>caller</B> [<I>expr</I>]<DD>
- Returns the context of any active subroutine call (a shell function or
- a script executed with the <B>.</B> or <B>source</B> builtins).
- Without <I>expr</I>, <B>caller</B> displays the line number and source
- filename of the current subroutine call.
- If a non-negative integer is supplied as <I>expr</I>, <B>caller</B>
- displays the line number, subroutine name, and source file corresponding
- to that position in the current execution call stack. This extra
- information may be used, for example, to print a stack trace. The
- current frame is frame 0.
- The return value is 0 unless the shell is not executing a subroutine
- call or <I>expr</I> does not correspond to a valid position in the
- call stack.
- <DT><B>cd</B> [<B>-L</B>|[<B>-P</B> [<B>-e</B>]] [-@]] [<I>dir</I>]<DD>
- Change the current directory to <I>dir</I>.
- if <I>dir</I> is not supplied, the value of the
- <FONT SIZE=-1><B>HOME</B>
- </FONT>
- shell variable is the default.
- Any additional arguments following <I>dir</I> are ignored.
- The variable
- <FONT SIZE=-1><B>CDPATH</B>
- </FONT>
- defines the search path for the directory containing
- <I>dir</I>:
- each directory name in
- <FONT SIZE=-1><B>CDPATH</B>
- </FONT>
- is searched for <I>dir</I>.
- Alternative directory names in
- <FONT SIZE=-1><B>CDPATH</B>
- </FONT>
- are separated by a colon (:). A null directory name in
- <FONT SIZE=-1><B>CDPATH</B>
- </FONT>
- is the same as the current directory, i.e., ``<B>.</B>''. If
- <I>dir</I>
- begins with a slash (/),
- then
- <FONT SIZE=-1><B>CDPATH</B>
- </FONT>
- is not used. The
- <B>-P</B>
- option causes <B>cd</B> to use the physical directory structure
- by resolving symbolic links while traversing <I>dir</I> and
- before processing instances of <I>..</I> in <I>dir</I> (see also the
- <B>-P</B>
- option to the
- <B>set</B>
- builtin command); the
- <B>-L</B>
- option forces symbolic links to be followed by resolving the link
- after processing instances of <I>..</I> in <I>dir</I>.
- If <I>..</I> appears in <I>dir</I>, it is processed by removing the
- immediately previous pathname component from <I>dir</I>, back to a slash
- or the beginning of <I>dir</I>.
- If the
- <B>-e</B>
- option is supplied with
- <B>-P</B>,
- and the current working directory cannot be successfully determined
- after a successful directory change, <B>cd</B> will return an unsuccessful
- status.
- On systems that support it, the <B>-@</B> option presents the extended
- attributes associated with a file as a directory.
- An argument of
- <B>-</B>
- is converted to
- <FONT SIZE=-1><B>$OLDPWD</B>
- </FONT>
- before the directory change is attempted.
- If a non-empty directory name from
- <FONT SIZE=-1><B>CDPATH</B>
- </FONT>
- is used, or if
- <B>-</B> is the first argument, and the directory change is
- successful, the absolute pathname of the new working directory is
- written to the standard output.
- The return value is true if the directory was successfully changed;
- false otherwise.
- <DT><B>command</B> [<B>-pVv</B>] <I>command</I> [<I>arg</I> ...]<DD>
- Run
- <I>command</I>
- with
- <I>args</I>
- suppressing the normal shell function lookup.
- Only builtin commands or commands found in the
- <FONT SIZE=-1><B>PATH</B>
- </FONT>
- are executed. If the
- <B>-p</B>
- option is given, the search for
- <I>command</I>
- is performed using a default value for
- <FONT SIZE=-1><B>PATH</B>
- </FONT>
- that is guaranteed to find all of the standard utilities.
- If either the
- <B>-V</B>
- or
- <B>-v</B>
- option is supplied, a description of
- <I>command</I>
- is printed. The
- <B>-v</B>
- option causes a single word indicating the command or filename
- used to invoke
- <I>command</I>
- to be displayed; the
- <B>-V</B>
- option produces a more verbose description.
- If the
- <B>-V</B>
- or
- <B>-v</B>
- option is supplied, the exit status is 0 if
- <I>command</I>
- was found, and 1 if not. If neither option is supplied and
- an error occurred or
- <I>command</I>
- cannot be found, the exit status is 127. Otherwise, the exit status of the
- <B>command</B>
- builtin is the exit status of
- <I>command</I>.
- <DT><B>compgen</B> [<I>option</I>] [<I>word</I>]<DD>
- Generate possible completion matches for <I>word</I> according to
- the <I>option</I>s, which may be any option accepted by the
- <B>complete</B>
- builtin with the exception of <B>-p</B> and <B>-r</B>, and write
- the matches to the standard output.
- When using the <B>-F</B> or <B>-C</B> options, the various shell variables
- set by the programmable completion facilities, while available, will not
- have useful values.
- <P>
- The matches will be generated in the same way as if the programmable
- completion code had generated them directly from a completion specification
- with the same flags.
- If <I>word</I> is specified, only those completions matching <I>word</I>
- will be displayed.
- <P>
- The return value is true unless an invalid option is supplied, or no
- matches were generated.
- <DT><B>complete</B> [<B>-abcdefgjksuv</B>] [<B>-o</B> <I>comp-option</I>] [<B>-DE</B>] [<B>-A</B> <I>action</I>] [<B>-G</B> <I>globpat</I>] [<B>-W</B> <I>wordlist</I>] [<B>-F</B> <I>function</I>] [<B>-C</B> <I>command</I>]<DD>
- <BR>
- [<B>-X</B> <I>filterpat</I>] [<B>-P</B> <I>prefix</I>] [<B>-S</B> <I>suffix</I>] <I>name</I> [<I>name ...</I>]
- <DT><B>complete</B> <B>-pr</B> [<B>-DE</B>] [<I>name</I> ...]<DD>
- Specify how arguments to each <I>name</I> should be completed.
- If the <B>-p</B> option is supplied, or if no options are supplied,
- existing completion specifications are printed in a way that allows
- them to be reused as input.
- The <B>-r</B> option removes a completion specification for
- each <I>name</I>, or, if no <I>name</I>s are supplied, all
- completion specifications.
- The <B>-D</B> option indicates that the remaining options and actions should
- apply to the ``default'' command completion; that is, completion attempted
- on a command for which no completion has previously been defined.
- The <B>-E</B> option indicates that the remaining options and actions should
- apply to ``empty'' command completion; that is, completion attempted on a
- blank line.
- <P>
- The process of applying these completion specifications when word completion
- is attempted is described above under <B>Programmable Completion</B>.
- <P>
- Other options, if specified, have the following meanings.
- The arguments to the <B>-G</B>, <B>-W</B>, and <B>-X</B> options
- (and, if necessary, the <B>-P</B> and <B>-S</B> options)
- should be quoted to protect them from expansion before the
- <B>complete</B>
- builtin is invoked.
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>-o</B> <I>comp-option</I><DD>
- The <I>comp-option</I> controls several aspects of the compspec's behavior
- beyond the simple generation of completions.
- <I>comp-option</I> may be one of:
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>bashdefault</B>
- <DD>
- Perform the rest of the default <B>bash</B> completions if the compspec
- generates no matches.
- <DT><B>default</B>
- <DD>
- Use readline's default filename completion if the compspec generates
- no matches.
- <DT><B>dirnames</B>
- <DD>
- Perform directory name completion if the compspec generates no matches.
- <DT><B>filenames</B>
- <DD>
- Tell readline that the compspec generates filenames, so it can perform any
- filename-specific processing (like adding a slash to directory names,
- quoting special characters, or suppressing trailing spaces).
- Intended to be used with shell functions.
- <DT><B>noquote</B>
- <DD>
- Tell readline not to quote the completed words if they are filenames
- (quoting filenames is the default).
- <DT><B>nosort</B>
- <DD>
- Tell readline not to sort the list of possible completions alphabetically.
- <DT><B>nospace</B>
- <DD>
- Tell readline not to append a space (the default) to words completed at
- the end of the line.
- <DT><B>plusdirs</B>
- <DD>
- After any matches defined by the compspec are generated,
- directory name completion is attempted and any
- matches are added to the results of the other actions.
- </DL></DL>
- <DT><B>-A</B> <I>action</I><DD>
- The <I>action</I> may be one of the following to generate a list of possible
- completions:
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>alias</B>
- <DD>
- Alias names. May also be specified as <B>-a</B>.
- <DT><B>arrayvar</B>
- <DD>
- Array variable names.
- <DT><B>binding</B>
- <DD>
- <B>Readline</B> key binding names.
- <DT><B>builtin</B>
- <DD>
- Names of shell builtin commands. May also be specified as <B>-b</B>.
- <DT><B>command</B>
- <DD>
- Command names. May also be specified as <B>-c</B>.
- <DT><B>directory</B>
- <DD>
- Directory names. May also be specified as <B>-d</B>.
- <DT><B>disabled</B>
- <DD>
- Names of disabled shell builtins.
- <DT><B>enabled</B>
- <DD>
- Names of enabled shell builtins.
- <DT><B>export</B>
- <DD>
- Names of exported shell variables. May also be specified as <B>-e</B>.
- <DT><B>file</B>
- <DD>
- File names. May also be specified as <B>-f</B>.
- <DT><B>function</B>
- <DD>
- Names of shell functions.
- <DT><B>group</B>
- <DD>
- Group names. May also be specified as <B>-g</B>.
- <DT><B>helptopic</B>
- <DD>
- Help topics as accepted by the <B>help</B> builtin.
- <DT><B>hostname</B>
- <DD>
- Hostnames, as taken from the file specified by the
- <FONT SIZE=-1><B>HOSTFILE</B>
- </FONT>
- shell variable.
- <DT><B>job</B>
- <DD>
- Job names, if job control is active. May also be specified as <B>-j</B>.
- <DT><B>keyword</B>
- <DD>
- Shell reserved words. May also be specified as <B>-k</B>.
- <DT><B>running</B>
- <DD>
- Names of running jobs, if job control is active.
- <DT><B>service</B>
- <DD>
- Service names. May also be specified as <B>-s</B>.
- <DT><B>setopt</B>
- <DD>
- Valid arguments for the <B>-o</B> option to the <B>set</B> builtin.
- <DT><B>shopt</B>
- <DD>
- Shell option names as accepted by the <B>shopt</B> builtin.
- <DT><B>signal</B>
- <DD>
- Signal names.
- <DT><B>stopped</B>
- <DD>
- Names of stopped jobs, if job control is active.
- <DT><B>user</B>
- <DD>
- User names. May also be specified as <B>-u</B>.
- <DT><B>variable</B>
- <DD>
- Names of all shell variables. May also be specified as <B>-v</B>.
- </DL></DL>
- <DT><B>-C</B> <I>command</I><DD>
- <I>command</I> is executed in a subshell environment, and its output is
- used as the possible completions.
- <DT><B>-F</B> <I>function</I><DD>
- The shell function <I>function</I> is executed in the current shell
- environment.
- When the function is executed,
- the first argument (<B>$1</B>) is the name of the command whose arguments are
- being completed,
- the second argument (<B>$2</B>) is the word being completed,
- and the third argument (<B>$3</B>) is the word preceding the word being
- completed on the current command line.
- When it finishes, the possible completions are retrieved from the value
- of the
- <FONT SIZE=-1><B>COMPREPLY</B>
- </FONT>
- array variable.
- <DT><B>-G</B> <I>globpat</I><DD>
- The pathname expansion pattern <I>globpat</I> is expanded to generate
- the possible completions.
- <DT><B>-P</B> <I>prefix</I><DD>
- <I>prefix</I> is added at the beginning of each possible completion
- after all other options have been applied.
- <DT><B>-S</B> <I>suffix</I><DD>
- <I>suffix</I> is appended to each possible completion
- after all other options have been applied.
- <DT><B>-W</B> <I>wordlist</I><DD>
- The <I>wordlist</I> is split using the characters in the
- <FONT SIZE=-1><B>IFS</B>
- </FONT>
- special variable as delimiters, and each resultant word is expanded.
- The possible completions are the members of the resultant list which
- match the word being completed.
- <DT><B>-X</B> <I>filterpat</I><DD>
- <I>filterpat</I> is a pattern as used for pathname expansion.
- It is applied to the list of possible completions generated by the
- preceding options and arguments, and each completion matching
- <I>filterpat</I> is removed from the list.
- A leading <B>!</B> in <I>filterpat</I> negates the pattern; in this
- case, any completion not matching <I>filterpat</I> is removed.
- </DL>
- <P>
- The return value is true unless an invalid option is supplied, an option
- other than <B>-p</B> or <B>-r</B> is supplied without a <I>name</I>
- argument, an attempt is made to remove a completion specification for
- a <I>name</I> for which no specification exists, or
- an error occurs adding a completion specification.
- </DL>
- <DT><B>compopt</B> [<B>-o</B> <I>option</I>] [<B>-DE</B>] [<B>+o</B> <I>option</I>] [<I>name</I>]<DD>
- Modify completion options for each <I>name</I> according to the
- <I>option</I>s, or for the
- currently-executing completion if no <I>name</I>s are supplied.
- If no <I>option</I>s are given, display the completion options for each
- <I>name</I> or the current completion.
- The possible values of <I>option</I> are those valid for the <B>complete</B>
- builtin described above.
- The <B>-D</B> option indicates that the remaining options should
- apply to the ``default'' command completion; that is, completion attempted
- on a command for which no completion has previously been defined.
- The <B>-E</B> option indicates that the remaining options should
- apply to ``empty'' command completion; that is, completion attempted on a
- blank line.
- <P>
- The return value is true unless an invalid option is supplied, an attempt
- is made to modify the options for a <I>name</I> for which no completion
- specification exists, or an output error occurs.
- <DT><B>continue</B> [<I>n</I>]<DD>
- Resume the next iteration of the enclosing
- <B>for</B>,
- <B>while</B>,
- <B>until</B>,
- or
- <B>select</B>
- loop.
- If
- <I>n</I>
- is specified, resume at the <I>n</I>th enclosing loop.
- <I>n</I>
- must be >= 1. If
- <I>n</I>
- is greater than the number of enclosing loops, the last enclosing loop
- (the ``top-level'' loop) is resumed.
- The return value is 0 unless <I>n</I> is not greater than or equal to 1.
- <DT><B>declare</B> [<B>-aAfFgilnrtux</B>] [<B>-p</B>] [<I>name</I>[=<I>value</I>] ...]<DD>
- <DT><B>typeset</B> [<B>-aAfFgilnrtux</B>] [<B>-p</B>] [<I>name</I>[=<I>value</I>] ...]<DD>
- Declare variables and/or give them attributes.
- If no <I>name</I>s are given then display the values of variables.
- The
- <B>-p</B>
- option will display the attributes and values of each
- <I>name</I>.
- When
- <B>-p</B>
- is used with <I>name</I> arguments, additional options,
- other than <B>-f</B> and <B>-F</B>, are ignored.
- When
- <B>-p</B>
- is supplied without <I>name</I> arguments, it will display the attributes
- and values of all variables having the attributes specified by the
- additional options.
- If no other options are supplied with <B>-p</B>, <B>declare</B> will display
- the attributes and values of all shell variables. The <B>-f</B> option
- will restrict the display to shell functions.
- The
- <B>-F</B>
- option inhibits the display of function definitions; only the
- function name and attributes are printed.
- If the <B>extdebug</B> shell option is enabled using <B>shopt</B>,
- the source file name and line number where each <I>name</I>
- is defined are displayed as well. The
- <B>-F</B>
- option implies
- <B>-f</B>.
- The
- <B>-g</B>
- option forces variables to be created or modified at the global scope,
- even when <B>declare</B> is executed in a shell function.
- It is ignored in all other cases.
- The following options can
- be used to restrict output to variables with the specified attribute or
- to give variables attributes:
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>-a</B>
- <DD>
- Each <I>name</I> is an indexed array variable (see
- <B>Arrays</B>
- above).
- <DT><B>-A</B>
- <DD>
- Each <I>name</I> is an associative array variable (see
- <B>Arrays</B>
- above).
- <DT><B>-f</B>
- <DD>
- Use function names only.
- <DT><B>-i</B>
- <DD>
- The variable is treated as an integer; arithmetic evaluation (see
- <FONT SIZE=-1><B>ARITHMETIC EVALUATION</B>
- </FONT>
- above) is performed when the variable is assigned a value.
- <DT><B>-l</B>
- <DD>
- When the variable is assigned a value, all upper-case characters are
- converted to lower-case.
- The upper-case attribute is disabled.
- <DT><B>-n</B>
- <DD>
- Give each <I>name</I> the <I>nameref</I> attribute, making
- it a name reference to another variable.
- That other variable is defined by the value of <I>name</I>.
- All references, assignments, and attribute modifications
- to <I>name</I>, except those using or changing the
- <B>-n</B> attribute itself, are performed on the variable referenced by
- <I>name</I>'s value.
- The nameref attribute cannot be applied to array variables.
- <DT><B>-r</B>
- <DD>
- Make <I>name</I>s readonly. These names cannot then be assigned values
- by subsequent assignment statements or unset.
- <DT><B>-t</B>
- <DD>
- Give each <I>name</I> the <I>trace</I> attribute.
- Traced functions inherit the <B>DEBUG</B> and <B>RETURN</B> traps from
- the calling shell.
- The trace attribute has no special meaning for variables.
- <DT><B>-u</B>
- <DD>
- When the variable is assigned a value, all lower-case characters are
- converted to upper-case.
- The lower-case attribute is disabled.
- <DT><B>-x</B>
- <DD>
- Mark <I>name</I>s for export to subsequent commands via the environment.
- </DL>
- <P>
- Using `+' instead of `-'
- turns off the attribute instead,
- with the exceptions that <B>+a</B>
- may not be used to destroy an array variable and <B>+r</B> will not
- remove the readonly attribute.
- When used in a function,
- <B>declare</B>
- and
- <B>typeset</B>
- make each
- <I>name</I> local, as with the
- <B>local</B>
- command,
- unless the <B>-g</B> option is supplied.
- If a variable name is followed by =<I>value</I>, the value of
- the variable is set to <I>value</I>.
- When using <B>-a</B> or <B>-A</B> and the compound assignment syntax to
- create array variables, additional attributes do not take effect until
- subsequent assignments.
- The return value is 0 unless an invalid option is encountered,
- an attempt is made to define a function using
- <TT>-f foo=bar</TT>,
- an attempt is made to assign a value to a readonly variable,
- an attempt is made to assign a value to an array variable without
- using the compound assignment syntax (see
- <B>Arrays</B>
- above), one of the <I>names</I> is not a valid shell variable name,
- an attempt is made to turn off readonly status for a readonly variable,
- an attempt is made to turn off array status for an array variable,
- or an attempt is made to display a non-existent function with <B>-f</B>.
- </DL>
- <DT><B>dirs [-clpv</B>] [+<I>n</I>] [-<I>n</I>]
- <DD>
- Without options, displays the list of currently remembered directories.
- The default display is on a single line with directory names separated
- by spaces.
- Directories are added to the list with the
- <B>pushd</B>
- command; the
- <B>popd</B>
- command removes entries from the list.
- The current directory is always the first directory in the stack.
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>-c</B>
- <DD>
- Clears the directory stack by deleting all of the entries.
- <DT><B>-l</B>
- <DD>
- Produces a listing using full pathnames;
- the default listing format uses a tilde to denote the home directory.
- <DT><B>-p</B>
- <DD>
- Print the directory stack with one entry per line.
- <DT><B>-v</B>
- <DD>
- Print the directory stack with one entry per line,
- prefixing each entry with its index in the stack.
- <DT><B>+</B><I>n</I><DD>
- Displays the <I>n</I>th entry counting from the left of the list
- shown by
- <B>dirs</B>
- when invoked without options, starting with zero.
- <DT><B>-</B><I>n</I><DD>
- Displays the <I>n</I>th entry counting from the right of the list
- shown by
- <B>dirs</B>
- when invoked without options, starting with zero.
- </DL>
- <P>
- The return value is 0 unless an
- invalid option is supplied or <I>n</I> indexes beyond the end
- of the directory stack.
- </DL>
- <DT><B>disown</B> [<B>-ar</B>] [<B>-h</B>] [<I>jobspec</I> ... | <I>pid</I> ... ]<DD>
- Without options, remove each
- <I>jobspec</I>
- from the table of active jobs.
- If
- <I>jobspec</I>
- is not present, and neither the <B>-a</B> nor the <B>-r</B> option
- is supplied, the <I>current job</I> is used.
- If the <B>-h</B> option is given, each
- <I>jobspec</I>
- is not removed from the table, but is marked so that
- <FONT SIZE=-1><B>SIGHUP</B>
- </FONT>
- is not sent to the job if the shell receives a
- <FONT SIZE=-1><B>SIGHUP</B>.
- </FONT>
- If no
- <I>jobspec</I>
- is supplied, the
- <B>-a</B>
- option means to remove or mark all jobs; the
- <B>-r</B>
- option without a
- <I>jobspec</I>
- argument restricts operation to running jobs.
- The return value is 0 unless a
- <I>jobspec</I>
- does not specify a valid job.
- <DT><B>echo</B> [<B>-neE</B>] [<I>arg</I> ...]<DD>
- Output the <I>arg</I>s, separated by spaces, followed by a newline.
- The return status is 0 unless a write error occurs.
- If <B>-n</B> is specified, the trailing newline is
- suppressed. If the <B>-e</B> option is given, interpretation of
- the following backslash-escaped characters is enabled. The
- <B>-E</B>
- option disables the interpretation of these escape characters,
- even on systems where they are interpreted by default.
- The <B>xpg_echo</B> shell option may be used to
- dynamically determine whether or not <B>echo</B> expands these
- escape characters by default.
- <B>echo</B>
- does not interpret <B>--</B> to mean the end of options.
- <B>echo</B>
- interprets the following escape sequences:
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>\a</B>
- <DD>
- alert (bell)
- <DT><B>\b</B>
- <DD>
- backspace
- <DT><B>\c</B>
- <DD>
- suppress further output
- <DT><B>\e</B>
- <DD>
- <DT><B>\E</B>
- <DD>
- an escape character
- <DT><B>\f</B>
- <DD>
- form feed
- <DT><B>\n</B>
- <DD>
- new line
- <DT><B>\r</B>
- <DD>
- carriage return
- <DT><B>\t</B>
- <DD>
- horizontal tab
- <DT><B>\v</B>
- <DD>
- vertical tab
- <DT><B>\\</B>
- <DD>
- backslash
- <DT><B>\0</B><I>nnn</I>
- <DD>
- the eight-bit character whose value is the octal value <I>nnn</I>
- (zero to three octal digits)
- <DT><B>\x</B><I>HH</I>
- <DD>
- the eight-bit character whose value is the hexadecimal value <I>HH</I>
- (one or two hex digits)
- <DT><B>\u</B><I>HHHH</I>
- <DD>
- the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
- <I>HHHH</I> (one to four hex digits)
- <DT><B>\U</B><I>HHHHHHHH</I>
- <DD>
- the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
- <I>HHHHHHHH</I> (one to eight hex digits)
- </DL></DL>
- <DT><B>enable</B> [<B>-a</B>] [<B>-dnps</B>] [<B>-f</B> <I>filename</I>] [<I>name</I> ...]<DD>
- Enable and disable builtin shell commands.
- Disabling a builtin allows a disk command which has the same name
- as a shell builtin to be executed without specifying a full pathname,
- even though the shell normally searches for builtins before disk commands.
- If <B>-n</B> is used, each <I>name</I>
- is disabled; otherwise,
- <I>names</I> are enabled. For example, to use the
- <B>test</B>
- binary found via the
- <FONT SIZE=-1><B>PATH</B>
- </FONT>
- instead of the shell builtin version, run
- <TT>enable -n test</TT>.
- The
- <B>-f</B>
- option means to load the new builtin command
- <I>name</I>
- from shared object
- <I>filename</I>,
- on systems that support dynamic loading. The
- <B>-d</B>
- option will delete a builtin previously loaded with
- <B>-f</B>.
- If no <I>name</I> arguments are given, or if the
- <B>-p</B>
- option is supplied, a list of shell builtins is printed.
- With no other option arguments, the list consists of all enabled
- shell builtins.
- If <B>-n</B> is supplied, only disabled builtins are printed.
- If <B>-a</B> is supplied, the list printed includes all builtins, with an
- indication of whether or not each is enabled.
- If <B>-s</B> is supplied, the output is restricted to the POSIX
- <I>special</I> builtins.
- The return value is 0 unless a
- <I>name</I>
- is not a shell builtin or there is an error loading a new builtin
- from a shared object.
- <DT><B>eval</B> [<I>arg</I> ...]<DD>
- The <I>arg</I>s are read and concatenated together into a single
- command. This command is then read and executed by the shell, and
- its exit status is returned as the value of
- <B>eval</B>.
- If there are no
- <I>args</I>,
- or only null arguments,
- <B>eval</B>
- returns 0.
- <DT><B>exec</B> [<B>-cl</B>] [<B>-a</B> <I>name</I>] [<I>command</I> [<I>arguments</I>]]<DD>
- If
- <I>command</I>
- is specified, it replaces the shell.
- No new process is created. The
- <I>arguments</I>
- become the arguments to <I>command</I>.
- If the
- <B>-l</B>
- option is supplied,
- the shell places a dash at the beginning of the zeroth argument passed to
- <I>command</I>.
- This is what
- <I>login</I>(1)
- does. The
- <B>-c</B>
- option causes
- <I>command</I>
- to be executed with an empty environment. If
- <B>-a</B>
- is supplied, the shell passes
- <I>name</I>
- as the zeroth argument to the executed command.
- If
- <I>command</I>
- cannot be executed for some reason, a non-interactive shell exits,
- unless the
- <B>execfail</B>
- shell option
- is enabled. In that case, it returns failure.
- An interactive shell returns failure if the file cannot be executed.
- If
- <I>command</I>
- is not specified, any redirections take effect in the current shell,
- and the return status is 0. If there is a redirection error, the
- return status is 1.
- <DT><B>exit</B> [<I>n</I>]<DD>
- Cause the shell to exit
- with a status of <I>n</I>. If
- <I>n</I>
- is omitted, the exit status
- is that of the last command executed.
- A trap on
- <FONT SIZE=-1><B>EXIT</B>
- </FONT>
- is executed before the shell terminates.
- <DT><B>export</B> [<B>-fn</B>] [<I>name</I>[=<I>word</I>]] ...<DD>
- <DT><B>export -p</B>
- <DD>
- The supplied
- <I>names</I>
- are marked for automatic export to the environment of
- subsequently executed commands. If the
- <B>-f</B>
- option is given, the
- <I>names</I>
- refer to functions.
- If no
- <I>names</I>
- are given, or if the
- <B>-p</B>
- option is supplied, a list
- of names of all exported variables is printed.
- The
- <B>-n</B>
- option causes the export property to be removed from each
- <I>name</I>.
- If a variable name is followed by =<I>word</I>, the value of
- the variable is set to <I>word</I>.
- <B>export</B>
- returns an exit status of 0 unless an invalid option is
- encountered,
- one of the <I>names</I> is not a valid shell variable name, or
- <B>-f</B>
- is supplied with a
- <I>name</I>
- that is not a function.
- <DT><B>fc</B> [<B>-e</B> <I>ename</I>] [<B>-lnr</B>] [<I>first</I>] [<I>last</I>]<DD>
- <DT><B>fc</B> <B>-s</B> [<I>pat</I>=<I>rep</I>] [<I>cmd</I>]<DD>
- The first form selects a range of commands from
- <I>first</I>
- to
- <I>last</I>
- from the history list and displays or edits and re-executes them.
- <I>First</I>
- and
- <I>last</I>
- may be specified as a string (to locate the last command beginning
- with that string) or as a number (an index into the history list,
- where a negative number is used as an offset from the current
- command number). If
- <I>last</I>
- is not specified it is set to
- the current command for listing (so that
- <TT>fc -l -10</TT>
- prints the last 10 commands) and to
- <I>first</I>
- otherwise.
- If
- <I>first</I>
- is not specified it is set to the previous
- command for editing and -16 for listing.
- <P>
- The
- <B>-n</B>
- option suppresses
- the command numbers when listing. The
- <B>-r</B>
- option reverses the order of
- the commands. If the
- <B>-l</B>
- option is given,
- the commands are listed on
- standard output. Otherwise, the editor given by
- <I>ename</I>
- is invoked
- on a file containing those commands. If
- <I>ename</I>
- is not given, the
- value of the
- <FONT SIZE=-1><B>FCEDIT</B>
- </FONT>
- variable is used, and
- the value of
- <FONT SIZE=-1><B>EDITOR</B>
- </FONT>
- if
- <FONT SIZE=-1><B>FCEDIT</B>
- </FONT>
- is not set. If neither variable is set,
- <I>vi</I>
- is used. When editing is complete, the edited commands are
- echoed and executed.
- <P>
- In the second form, <I>command</I> is re-executed after each instance
- of <I>pat</I> is replaced by <I>rep</I>.
- <I>Command</I> is intepreted the same as <I>first</I> above.
- A useful alias to use with this is
- <TT>r='fc -s'</TT>,
- so that typing
- <TT>r cc</TT>
- runs the last command beginning with
- <TT>cc</TT>
- and typing
- <TT>r</TT>
- re-executes the last command.
- <P>
- If the first form is used, the return value is 0 unless an invalid
- option is encountered or
- <I>first</I>
- or
- <I>last</I>
- specify history lines out of range.
- If the
- <B>-e</B>
- option is supplied, the return value is the value of the last
- command executed or failure if an error occurs with the temporary
- file of commands. If the second form is used, the return status
- is that of the command re-executed, unless
- <I>cmd</I>
- does not specify a valid history line, in which case
- <B>fc</B>
- returns failure.
- <DT><B>fg</B> [<I>jobspec</I>]<DD>
- Resume
- <I>jobspec</I>
- in the foreground, and make it the current job.
- If
- <I>jobspec</I>
- is not present, the shell's notion of the <I>current job</I> is used.
- The return value is that of the command placed into the foreground,
- or failure if run when job control is disabled or, when run with
- job control enabled, if
- <I>jobspec</I>
- does not specify a valid job or
- <I>jobspec</I>
- specifies a job that was started without job control.
- <DT><B>getopts</B> <I>optstring</I> <I>name</I> [<I>args</I>]<DD>
- <B>getopts</B>
- is used by shell procedures to parse positional parameters.
- <I>optstring</I>
- contains the option characters to be recognized; if a character
- is followed by a colon, the option is expected to have an
- argument, which should be separated from it by white space.
- The colon and question mark characters may not be used as
- option characters.
- Each time it is invoked,
- <B>getopts</B>
- places the next option in the shell variable
- <I>name</I>,
- initializing
- <I>name</I>
- if it does not exist,
- and the index of the next argument to be processed into the
- variable
- <FONT SIZE=-1><B>OPTIND</B>.
- </FONT>
- <FONT SIZE=-1><B>OPTIND</B>
- </FONT>
- is initialized to 1 each time the shell or a shell script
- is invoked. When an option requires an argument,
- <B>getopts</B>
- places that argument into the variable
- <FONT SIZE=-1><B>OPTARG</B>.
- </FONT>
- The shell does not reset
- <FONT SIZE=-1><B>OPTIND</B>
- </FONT>
- automatically; it must be manually reset between multiple
- calls to
- <B>getopts</B>
- within the same shell invocation if a new set of parameters
- is to be used.
- <P>
- When the end of options is encountered, <B>getopts</B> exits with a
- return value greater than zero.
- <FONT SIZE=-1><B>OPTIND</B>
- </FONT>
- is set to the index of the first non-option argument,
- and <I>name</I> is set to ?.
- <P>
- <B>getopts</B>
- normally parses the positional parameters, but if more arguments are
- given in
- <I>args</I>,
- <B>getopts</B>
- parses those instead.
- <P>
- <B>getopts</B>
- can report errors in two ways. If the first character of
- <I>optstring</I>
- is a colon,
- <I>silent</I>
- error reporting is used. In normal operation, diagnostic messages
- are printed when invalid options or missing option arguments are
- encountered.
- If the variable
- <FONT SIZE=-1><B>OPTERR</B>
- </FONT>
- is set to 0, no error messages will be displayed, even if the first
- character of
- <I>optstring</I>
- is not a colon.
- <P>
- If an invalid option is seen,
- <B>getopts</B>
- places ? into
- <I>name</I>
- and, if not silent,
- prints an error message and unsets
- <FONT SIZE=-1><B>OPTARG</B>.
- </FONT>
- If
- <B>getopts</B>
- is silent,
- the option character found is placed in
- <FONT SIZE=-1><B>OPTARG</B>
- </FONT>
- and no diagnostic message is printed.
- <P>
- If a required argument is not found, and
- <B>getopts</B>
- is not silent,
- a question mark (<B>?</B>) is placed in
- <I>name</I>,
- <FONT SIZE=-1><B>OPTARG</B>
- </FONT>
- is unset, and a diagnostic message is printed.
- If
- <B>getopts</B>
- is silent, then a colon (<B>:</B>) is placed in
- <I>name</I>
- and
- <FONT SIZE=-1><B>OPTARG</B>
- </FONT>
- is set to the option character found.
- <P>
- <B>getopts</B>
- returns true if an option, specified or unspecified, is found.
- It returns false if the end of options is encountered or an
- error occurs.
- <DT><B>hash</B> [<B>-lr</B>] [<B>-p</B> <I>filename</I>] [<B>-dt</B>] [<I>name</I>]<DD>
- Each time <B>hash</B> is invoked,
- the full pathname of the command
- <I>name</I>
- is determined by searching
- the directories in
- <B>$PATH</B>
- and remembered. Any previously-remembered pathname is discarded.
- If the
- <B>-p</B>
- option is supplied, no path search is performed, and
- <I>filename</I>
- is used as the full filename of the command.
- The
- <B>-r</B>
- option causes the shell to forget all
- remembered locations.
- The
- <B>-d</B>
- option causes the shell to forget the remembered location of each <I>name</I>.
- If the
- <B>-t</B>
- option is supplied, the full pathname to which each <I>name</I> corresponds
- is printed. If multiple <I>name</I> arguments are supplied with <B>-t</B>,
- the <I>name</I> is printed before the hashed full pathname.
- The
- <B>-l</B>
- option causes output to be displayed in a format that may be reused as input.
- If no arguments are given, or if only <B>-l</B> is supplied,
- information about remembered commands is printed.
- The return status is true unless a
- <I>name</I>
- is not found or an invalid option is supplied.
- <DT><B>help</B> [<B>-dms</B>] [<I>pattern</I>]<DD>
- Display helpful information about builtin commands. If
- <I>pattern</I>
- is specified,
- <B>help</B>
- gives detailed help on all commands matching
- <I>pattern</I>;
- otherwise help for all the builtins and shell control structures
- is printed.
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>-d</B>
- <DD>
- Display a short description of each <I>pattern</I>
- <DT><B>-m</B>
- <DD>
- Display the description of each <I>pattern</I> in a manpage-like format
- <DT><B>-s</B>
- <DD>
- Display only a short usage synopsis for each <I>pattern</I>
- </DL>
- <P>
- The return status is 0 unless no command matches
- <I>pattern</I>.
- </DL>
- <DT><B>history [</B><I>n</I>]<DD>
- <DT><B>history</B> <B>-c</B><DD>
- <DT><B>history -d</B> <I>offset</I><DD>
- <DT><B>history</B> <B>-anrw</B> [<I>filename</I>]<DD>
- <DT><B>history</B> <B>-p</B> <I>arg</I> [<I>arg ...</I>]<DD>
- <DT><B>history</B> <B>-s</B> <I>arg</I> [<I>arg ...</I>]<DD>
- With no options, display the command
- history list with line numbers. Lines listed
- with a
- <B>*</B>
- have been modified. An argument of
- <I>n</I>
- lists only the last
- <I>n</I>
- lines.
- If the shell variable
- <FONT SIZE=-1><B>HISTTIMEFORMAT</B>
- </FONT>
- is set and not null,
- it is used as a format string for <I>strftime</I>(3) to display
- the time stamp associated with each displayed history entry.
- No intervening blank is printed between the formatted time stamp
- and the history line.
- If <I>filename</I> is supplied, it is used as the
- name of the history file; if not, the value of
- <FONT SIZE=-1><B>HISTFILE</B>
- </FONT>
- is used. Options, if supplied, have the following meanings:
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>-c</B>
- <DD>
- Clear the history list by deleting all the entries.
- <DT><B>-d</B> <I>offset</I><DD>
- Delete the history entry at position <I>offset</I>.
- <DT><B>-a</B>
- <DD>
- Append the ``new'' history lines to the history file.
- These are history lines entered since the beginning of the current
- <B>bash</B> session, but not already appended to the history file.
- <DT><B>-n</B>
- <DD>
- Read the history lines not already read from the history
- file into the current history list. These are lines
- appended to the history file since the beginning of the
- current <B>bash</B> session.
- <DT><B>-r</B>
- <DD>
- Read the contents of the history file
- and append them to the current history list.
- <DT><B>-w</B>
- <DD>
- Write the current history list to the history file, overwriting the
- history file's contents.
- <DT><B>-p</B>
- <DD>
- Perform history substitution on the following <I>args</I> and display
- the result on the standard output.
- Does not store the results in the history list.
- Each <I>arg</I> must be quoted to disable normal history expansion.
- <DT><B>-s</B>
- <DD>
- Store the
- <I>args</I>
- in the history list as a single entry. The last command in the
- history list is removed before the
- <I>args</I>
- are added.
- </DL>
- <P>
- If the
- <FONT SIZE=-1><B>HISTTIMEFORMAT</B>
- </FONT>
- variable is set, the time stamp information
- associated with each history entry is written to the history file,
- marked with the history comment character.
- When the history file is read, lines beginning with the history
- comment character followed immediately by a digit are interpreted
- as timestamps for the following history entry.
- The return value is 0 unless an invalid option is encountered, an
- error occurs while reading or writing the history file, an invalid
- <I>offset</I> is supplied as an argument to <B>-d</B>, or the
- history expansion supplied as an argument to <B>-p</B> fails.
- </DL>
- <DT><B>jobs</B> [<B>-lnprs</B>] [ <I>jobspec</I> ... ]<DD>
- <DT><B>jobs</B> <B>-x</B> <I>command</I> [ <I>args</I> ... ]<DD>
- The first form lists the active jobs. The options have the following
- meanings:
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>-l</B>
- <DD>
- List process IDs
- in addition to the normal information.
- <DT><B>-n</B>
- <DD>
- Display information only about jobs that have changed status since
- the user was last notified of their status.
- <DT><B>-p</B>
- <DD>
- List only the process ID of the job's process group
- leader.
- <DT><B>-r</B>
- <DD>
- Display only running jobs.
- <DT><B>-s</B>
- <DD>
- Display only stopped jobs.
- </DL>
- <P>
- If
- <I>jobspec</I>
- is given, output is restricted to information about that job.
- The return status is 0 unless an invalid option is encountered
- or an invalid
- <I>jobspec</I>
- is supplied.
- <P>
- If the
- <B>-x</B>
- option is supplied,
- <B>jobs</B>
- replaces any
- <I>jobspec</I>
- found in
- <I>command</I>
- or
- <I>args</I>
- with the corresponding process group ID, and executes
- <I>command</I>
- passing it
- <I>args</I>,
- returning its exit status.
- </DL>
- <DT><B>kill</B> [<B>-s</B> <I>sigspec</I> | <B>-n</B> <I>signum</I> | <B>-</B><I>sigspec</I>] [<I>pid</I> | <I>jobspec</I>] ...<DD>
- <DT><B>kill</B> <B>-l</B>|<B>-L</B> [<I>sigspec</I> | <I>exit_status</I>]<DD>
- Send the signal named by
- <I>sigspec</I>
- or
- <I>signum</I>
- to the processes named by
- <I>pid</I>
- or
- <I>jobspec</I>.
- <I>sigspec</I>
- is either a case-insensitive signal name such as
- <FONT SIZE=-1><B>SIGKILL</B>
- </FONT>
- (with or without the
- <FONT SIZE=-1><B>SIG</B>
- </FONT>
- prefix) or a signal number;
- <I>signum</I>
- is a signal number.
- If
- <I>sigspec</I>
- is not present, then
- <FONT SIZE=-1><B>SIGTERM</B>
- </FONT>
- is assumed.
- An argument of
- <B>-l</B>
- lists the signal names.
- If any arguments are supplied when
- <B>-l</B>
- is given, the names of the signals corresponding to the arguments are
- listed, and the return status is 0.
- The <I>exit_status</I> argument to
- <B>-l</B>
- is a number specifying either a signal number or the exit status of
- a process terminated by a signal.
- The
- <B>-L</B>
- option is equivalent to <B>-l</B>.
- <B>kill</B>
- returns true if at least one signal was successfully sent, or false
- if an error occurs or an invalid option is encountered.
- <DT><B>let</B> <I>arg</I> [<I>arg</I> ...]<DD>
- Each
- <I>arg</I>
- is an arithmetic expression to be evaluated (see
- <FONT SIZE=-1><B>ARITHMETIC EVALUATION</B>
- </FONT>
- above).
- If the last
- <I>arg</I>
- evaluates to 0,
- <B>let</B>
- returns 1; 0 is returned otherwise.
- <DT><B>local</B> [<I>option</I>] [<I>name</I>[=<I>value</I>] ... | - ]<DD>
- For each argument, a local variable named
- <I>name</I>
- is created, and assigned
- <I>value</I>.
- The <I>option</I> can be any of the options accepted by <B>declare</B>.
- When
- <B>local</B>
- is used within a function, it causes the variable
- <I>name</I>
- to have a visible scope restricted to that function and its children.
- If <I>name</I> is -, the set of shell options is made local to the function
- in which <B>local</B> is invoked: shell options changed using the
- <B>set</B> builtin inside the function are restored to their original values
- when the function returns.
- With no operands,
- <B>local</B>
- writes a list of local variables to the standard output. It is
- an error to use
- <B>local</B>
- when not within a function. The return status is 0 unless
- <B>local</B>
- is used outside a function, an invalid
- <I>name</I>
- is supplied, or
- <I>name</I> is a readonly variable.
- <DT><B>logout</B>
- <DD>
- Exit a login shell.
- <DT><B>mapfile</B> [<B>-d</B> <I>delim</I>] [<B>-n</B> <I>count</I>] [<B>-O</B> <I>origin</I>] [<B>-s</B> <I>count</I>] [<B>-t</B>] [<B>-u</B> <I>fd</I>] [<B>-C</B> <I>callback</I>] [<B>-c</B> <I>quantum</I>] [<I>array</I>]<DD>
- <DT><B>readarray</B> [<B>-d</B> <I>delim</I>] [<B>-n</B> <I>count</I>] [<B>-O</B> <I>origin</I>] [<B>-s</B> <I>count</I>] [<B>-t</B>] [<B>-u</B> <I>fd</I>] [<B>-C</B> <I>callback</I>] [<B>-c</B> <I>quantum</I>] [<I>array</I>]<DD>
- Read lines from the standard input into the indexed array variable
- <I>array</I>,
- or from file descriptor
- <I>fd</I>
- if the
- <B>-u</B>
- option is supplied.
- The variable
- <FONT SIZE=-1><B>MAPFILE</B>
- </FONT>
- is the default <I>array</I>.
- Options, if supplied, have the following meanings:
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>-d</B>
- <DD>
- The first character of <I>delim</I> is used to terminate each input line,
- rather than newline.
- <DT><B>-n</B>
- <DD>
- Copy at most
- <I>count</I>
- lines. If <I>count</I> is 0, all lines are copied.
- <DT><B>-O</B>
- <DD>
- Begin assigning to
- <I>array</I>
- at index
- <I>origin</I>.
- The default index is 0.
- <DT><B>-s</B>
- <DD>
- Discard the first <I>count</I> lines read.
- <DT><B>-t</B>
- <DD>
- Remove a trailing <I>delim</I> (default newline) from each line read.
- <DT><B>-u</B>
- <DD>
- Read lines from file descriptor <I>fd</I> instead of the standard input.
- <DT><B>-C</B>
- <DD>
- Evaluate
- <I>callback</I>
- each time <I>quantum</I> lines are read. The <B>-c</B> option specifies
- <I>quantum</I>.
- <DT><B>-c</B>
- <DD>
- Specify the number of lines read between each call to
- <I>callback</I>.
- </DL>
- <P>
- If
- <B>-C</B>
- is specified without
- <B>-c</B>,
- the default quantum is 5000.
- When <I>callback</I> is evaluated, it is supplied the index of the next
- array element to be assigned and the line to be assigned to that element
- as additional arguments.
- <I>callback</I> is evaluated after the line is read but before the
- array element is assigned.
- <P>
- If not supplied with an explicit origin, <B>mapfile</B> will clear <I>array</I>
- before assigning to it.
- <P>
- <B>mapfile</B> returns successfully unless an invalid option or option
- argument is supplied, <I>array</I> is invalid or unassignable, or if
- <I>array</I> is not an indexed array.
- </DL>
- <DT><B>popd</B> [-<B>n</B>] [+<I>n</I>] [-<I>n</I>]<DD>
- Removes entries from the directory stack. With no arguments,
- removes the top directory from the stack, and performs a
- <B>cd</B>
- to the new top directory.
- Arguments, if supplied, have the following meanings:
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>-n</B>
- <DD>
- Suppresses the normal change of directory when removing directories
- from the stack, so that only the stack is manipulated.
- <DT><B>+</B><I>n</I><DD>
- Removes the <I>n</I>th entry counting from the left of the list
- shown by
- <B>dirs</B>,
- starting with zero. For example:
- <TT>popd +0</TT>
- removes the first directory,
- <TT>popd +1</TT>
- the second.
- <DT><B>-</B><I>n</I><DD>
- Removes the <I>n</I>th entry counting from the right of the list
- shown by
- <B>dirs</B>,
- starting with zero. For example:
- <TT>popd -0</TT>
- removes the last directory,
- <TT>popd -1</TT>
- the next to last.
- </DL>
- <P>
- If the
- <B>popd</B>
- command is successful, a
- <B>dirs</B>
- is performed as well, and the return status is 0.
- <B>popd</B>
- returns false if an invalid option is encountered, the directory stack
- is empty, a non-existent directory stack entry is specified, or the
- directory change fails.
- </DL>
- <DT><B>printf</B> [<B>-v</B> <I>var</I>] <I>format</I> [<I>arguments</I>]<DD>
- Write the formatted <I>arguments</I> to the standard output under the
- control of the <I>format</I>.
- The <B>-v</B> option causes the output to be assigned to the variable
- <I>var</I> rather than being printed to the standard output.
- <P>
- The <I>format</I> is a character string which contains three types of objects:
- plain characters, which are simply copied to standard output, character
- escape sequences, which are converted and copied to the standard output, and
- format specifications, each of which causes printing of the next successive
- <I>argument</I>.
- In addition to the standard <I>printf</I>(1) format specifications,
- <B>printf</B> interprets the following extensions:
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>%b</B>
- <DD>
- causes
- <B>printf</B> to expand backslash escape sequences in the corresponding
- <I>argument</I>
- in the same way as <B>echo -e</B>.
- <DT><B>%q</B>
- <DD>
- causes <B>printf</B> to output the corresponding
- <I>argument</I> in a format that can be reused as shell input.
- <DT><B>%(</B><I>datefmt</I>)T
- <DD>
- causes <B>printf</B> to output the date-time string resulting from using
- <I>datefmt</I> as a format string for <I>strftime</I>(3).
- The corresponding <I>argument</I> is an integer representing the number of
- seconds since the epoch.
- Two special argument values may be used: -1 represents the current
- time, and -2 represents the time the shell was invoked.
- If no argument is specified, conversion behaves as if -1 had been given.
- This is an exception to the usual <B>printf</B> behavior.
- </DL>
- <P>
- Arguments to non-string format specifiers are treated as C constants,
- except that a leading plus or minus sign is allowed, and if the leading
- character is a single or double quote, the value is the ASCII value of
- the following character.
- <P>
- The <I>format</I> is reused as necessary to consume all of the <I>arguments</I>.
- If the <I>format</I> requires more <I>arguments</I> than are supplied, the
- extra format specifications behave as if a zero value or null string, as
- appropriate, had been supplied.
- The return value is zero on success, non-zero on failure.
- </DL>
- <DT><B>pushd</B> [<B>-n</B>] [+<I>n</I>] [-<I>n</I>]<DD>
- <DT><B>pushd</B> [<B>-n</B>] [<I>dir</I>]<DD>
- Adds a directory to the top of the directory stack, or rotates
- the stack, making the new top of the stack the current working
- directory. With no arguments, <B>pushd</B> exchanges the top two directories
- and returns 0, unless the directory stack is empty.
- Arguments, if supplied, have the following meanings:
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>-n</B>
- <DD>
- Suppresses the normal change of directory when rotating or
- adding directories to the stack, so that only the stack is manipulated.
- <DT><B>+</B><I>n</I><DD>
- Rotates the stack so that the <I>n</I>th directory
- (counting from the left of the list shown by
- <B>dirs</B>,
- starting with zero)
- is at the top.
- <DT><B>-</B><I>n</I><DD>
- Rotates the stack so that the <I>n</I>th directory
- (counting from the right of the list shown by
- <B>dirs</B>,
- starting with zero) is at the top.
- <DT><I>dir</I>
- <DD>
- Adds
- <I>dir</I>
- to the directory stack at the top, making it the
- new current working directory as if it had been supplied as the argument
- to the <B>cd</B> builtin.
- </DL>
- <P>
- If the
- <B>pushd</B>
- command is successful, a
- <B>dirs</B>
- is performed as well.
- If the first form is used,
- <B>pushd</B>
- returns 0 unless the cd to
- <I>dir</I>
- fails. With the second form,
- <B>pushd</B>
- returns 0 unless the directory stack is empty,
- a non-existent directory stack element is specified,
- or the directory change to the specified new current directory
- fails.
- </DL>
- <DT><B>pwd</B> [<B>-LP</B>]<DD>
- Print the absolute pathname of the current working directory.
- The pathname printed contains no symbolic links if the
- <B>-P</B>
- option is supplied or the
- <B>-o physical</B>
- option to the
- <B>set</B>
- builtin command is enabled.
- If the
- <B>-L</B>
- option is used, the pathname printed may contain symbolic links.
- The return status is 0 unless an error occurs while
- reading the name of the current directory or an
- invalid option is supplied.
- <DT><B>read</B> [<B>-ers</B>] [<B>-a</B> <I>aname</I>] [<B>-d</B> <I>delim</I>] [<B>-i</B> <I>text</I>] [<B>-n</B> <I>nchars</I>] [<B>-N</B> <I>nchars</I>] [<B>-p</B> <I>prompt</I>] [<B>-t</B> <I>timeout</I>] [<B>-u</B> <I>fd</I>] [<I>name</I> ...]<DD>
- One line is read from the standard input, or from the file descriptor
- <I>fd</I> supplied as an argument to the <B>-u</B> option,
- split into words as described above under <B>Word Splitting</B>,
- and the first word
- is assigned to the first
- <I>name</I>,
- the second word to the second
- <I>name</I>,
- and so on.
- If there are more words than names, the remaining words and their
- intervening delimiters are assigned to the last
- <I>name</I>.
- If there are fewer words read from the input stream than names,
- the remaining names are assigned empty values.
- The characters in
- <FONT SIZE=-1><B>IFS</B>
- </FONT>
- are used to split the line into words using the same rules the shell
- uses for expansion (described above under <B>Word Splitting</B>).
- The backslash character (<B>\</B>) may be used to remove any special
- meaning for the next character read and for line continuation.
- Options, if supplied, have the following meanings:
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>-a </B><I>aname</I>
- <DD>
- The words are assigned to sequential indices
- of the array variable
- <I>aname</I>,
- starting at 0.
- <I>aname</I>
- is unset before any new values are assigned.
- Other <I>name</I> arguments are ignored.
- <DT><B>-d </B><I>delim</I>
- <DD>
- The first character of <I>delim</I> is used to terminate the input line,
- rather than newline.
- <DT><B>-e</B>
- <DD>
- If the standard input
- is coming from a terminal,
- <B>readline</B>
- (see
- <FONT SIZE=-1><B>READLINE</B>
- </FONT>
- above) is used to obtain the line.
- Readline uses the current (or default, if line editing was not previously
- active) editing settings.
- <DT><B>-i </B><I>text</I>
- <DD>
- If
- <B>readline</B>
- is being used to read the line, <I>text</I> is placed into the editing
- buffer before editing begins.
- <DT><B>-n </B><I>nchars</I>
- <DD>
- <B>read</B> returns after reading <I>nchars</I> characters rather than
- waiting for a complete line of input, but honors a delimiter if fewer
- than <I>nchars</I> characters are read before the delimiter.
- <DT><B>-N </B><I>nchars</I>
- <DD>
- <B>read</B> returns after reading exactly <I>nchars</I> characters rather
- than waiting for a complete line of input, unless EOF is encountered or
- <B>read</B> times out.
- Delimiter characters encountered in the input are
- not treated specially and do not cause <B>read</B> to return until
- <I>nchars</I> characters are read.
- The result is not split on the characters in <B>IFS</B>; the intent is
- that the variable is assigned exactly the characters read
- (with the exception of backslash; see the <B>-r</B> option below).
- <DT><B>-p </B><I>prompt</I>
- <DD>
- Display <I>prompt</I> on standard error, without a
- trailing newline, before attempting to read any input. The prompt
- is displayed only if input is coming from a terminal.
- <DT><B>-r</B>
- <DD>
- Backslash does not act as an escape character.
- The backslash is considered to be part of the line.
- In particular, a backslash-newline pair may not be used as a line
- continuation.
- <DT><B>-s</B>
- <DD>
- Silent mode. If input is coming from a terminal, characters are
- not echoed.
- <DT><B>-t </B><I>timeout</I>
- <DD>
- Cause <B>read</B> to time out and return failure if a complete line of
- input (or a specified number of characters)
- is not read within <I>timeout</I> seconds.
- <I>timeout</I> may be a decimal number with a fractional portion following
- the decimal point.
- This option is only effective if <B>read</B> is reading input from a
- terminal, pipe, or other special file; it has no effect when reading
- from regular files.
- If <B>read</B> times out, <B>read</B> saves any partial input read into
- the specified variable <I>name</I>.
- If <I>timeout</I> is 0, <B>read</B> returns immediately, without trying to
- read any data. The exit status is 0 if input is available on
- the specified file descriptor, non-zero otherwise.
- The exit status is greater than 128 if the timeout is exceeded.
- <DT><B>-u </B><I>fd</I>
- <DD>
- Read input from file descriptor <I>fd</I>.
- </DL>
- <P>
- If no
- <I>names</I>
- are supplied, the line read is assigned to the variable
- <FONT SIZE=-1><B>REPLY</B>.
- </FONT>
- The exit status is zero, unless end-of-file is encountered, <B>read</B>
- times out (in which case the status is greater than 128),
- a variable assignment error (such as assigning to a readonly variable) occurs,
- or an invalid file descriptor is supplied as the argument to <B>-u</B>.
- </DL>
- <DT><B>readonly</B> [<B>-aAf</B>] [<B>-p</B>] [<I>name</I>[=<I>word</I>] ...]<DD>
- The given
- <I>names</I> are marked readonly; the values of these
- <I>names</I>
- may not be changed by subsequent assignment.
- If the
- <B>-f</B>
- option is supplied, the functions corresponding to the
- <I>names</I> are so
- marked.
- The
- <B>-a</B>
- option restricts the variables to indexed arrays; the
- <B>-A</B>
- option restricts the variables to associative arrays.
- If both options are supplied,
- <B>-A</B>
- takes precedence.
- If no
- <I>name</I>
- arguments are given, or if the
- <B>-p</B>
- option is supplied, a list of all readonly names is printed.
- The other options may be used to restrict the output to a subset of
- the set of readonly names.
- The
- <B>-p</B>
- option causes output to be displayed in a format that
- may be reused as input.
- If a variable name is followed by =<I>word</I>, the value of
- the variable is set to <I>word</I>.
- The return status is 0 unless an invalid option is encountered,
- one of the
- <I>names</I>
- is not a valid shell variable name, or
- <B>-f</B>
- is supplied with a
- <I>name</I>
- that is not a function.
- <DT><B>return</B> [<I>n</I>]<DD>
- Causes a function to stop executing and return the value specified by
- <I>n</I>
- to its caller.
- If
- <I>n</I>
- is omitted, the return status is that of the last command
- executed in the function body.
- If <B>return</B> is executed by a trap handler, the last command used to
- determine the status is the last command executed before the trap handler.
- if <B>return</B> is executed during a <B>DEBUG</B> trap, the last command
- used to determine the status is the last command executed by the trap
- handler before <B>return</B> was invoked.
- If
- <B>return</B>
- is used outside a function,
- but during execution of a script by the
- <B>.</B>
- (<B>source</B>) command, it causes the shell to stop executing
- that script and return either
- <I>n</I>
- or the exit status of the last command executed within the
- script as the exit status of the script.
- If <I>n</I> is supplied, the return value is its least significant
- 8 bits.
- The return status is non-zero if
- <B>return</B>
- is supplied a non-numeric argument, or
- is used outside a
- function and not during execution of a script by <B>.</B> or <B>source</B>.
- Any command associated with the <B>RETURN</B> trap is executed
- before execution resumes after the function or script.
- <DT><B>set</B> [<B>--abefhkmnptuvxBCEHPT</B>] [<B>-o</B> <I>option-name</I>] [<I>arg</I> ...]<DD>
- <DT><B>set</B> [<B>+abefhkmnptuvxBCEHPT</B>] [<B>+o</B> <I>option-name</I>] [<I>arg</I> ...]<DD>
- Without options, the name and value of each shell variable are displayed
- in a format that can be reused as input
- for setting or resetting the currently-set variables.
- Read-only variables cannot be reset.
- In <I>posix</I> mode, only shell variables are listed.
- The output is sorted according to the current locale.
- When options are specified, they set or unset shell attributes.
- Any arguments remaining after option processing are treated
- as values for the positional parameters and are assigned, in order, to
- <B>$1</B>,
- <B>$2</B>,
- <B>...</B>
- <B>$</B><I>n</I>.
- Options, if specified, have the following meanings:
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>-a</B>
- <DD>
- Each variable or function that is created or modified is given the
- export attribute and marked for export to the environment of
- subsequent commands.
- <DT><B>-b</B>
- <DD>
- Report the status of terminated background jobs
- immediately, rather than before the next primary prompt. This is
- effective only when job control is enabled.
- <DT><B>-e</B>
- <DD>
- Exit immediately if a
- <I>pipeline</I> (which may consist of a single <I>simple command</I>),
- a <I>list</I>,
- or a <I>compound command</I>
- (see
- <FONT SIZE=-1><B>SHELL GRAMMAR</B>
- </FONT>
- above), exits with a non-zero status.
- The shell does not exit if the
- command that fails is part of the command list immediately following a
- <B>while</B>
- or
- <B>until</B>
- keyword,
- part of the test following the
- <B>if</B>
- or
- <B>elif</B>
- reserved words, part of any command executed in a
- <B>&&</B>
- or
- <B>||</B>
- list except the command following the final <B>&&</B> or <B>||</B>,
- any command in a pipeline but the last,
- or if the command's return value is
- being inverted with
- <B>!</B>.
- If a compound command other than a subshell
- returns a non-zero status because a command failed
- while <B>-e</B> was being ignored, the shell does not exit.
- A trap on <B>ERR</B>, if set, is executed before the shell exits.
- This option applies to the shell environment and each subshell environment
- separately (see
- <FONT SIZE=-1><B>COMMAND EXECUTION ENVIRONMENT</B>
- </FONT>
- above), and may cause
- subshells to exit before executing all the commands in the subshell.
- <P>
- If a compound command or shell function executes in a context
- where <B>-e</B> is being ignored,
- none of the commands executed within the compound command or function body
- will be affected by the <B>-e</B> setting, even if <B>-e</B> is set
- and a command returns a failure status.
- If a compound command or shell function sets <B>-e</B> while executing in
- a context where <B>-e</B> is ignored, that setting will not have any
- effect until the compound command or the command containing the function
- call completes.
- <DT><B>-f</B>
- <DD>
- Disable pathname expansion.
- <DT><B>-h</B>
- <DD>
- Remember the location of commands as they are looked up for execution.
- This is enabled by default.
- <DT><B>-k</B>
- <DD>
- All arguments in the form of assignment statements
- are placed in the environment for a command, not just
- those that precede the command name.
- <DT><B>-m</B>
- <DD>
- Monitor mode. Job control is enabled. This option is on
- by default for interactive shells on systems that support
- it (see
- <FONT SIZE=-1><B>JOB CONTROL</B>
- </FONT>
- above).
- All processes run in a separate process group.
- When a background job completes, the shell prints a line
- containing its exit status.
- <DT><B>-n</B>
- <DD>
- Read commands but do not execute them.
- This may be used to check a shell script for syntax errors.
- This is ignored by interactive shells.
- <DT><B>-o </B><I>option-name</I>
- <DD>
- The <I>option-name</I> can be one of the following:
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>allexport</B>
- <DD>
- Same as
- <B>-a</B>.
- <DT><B>braceexpand</B>
- <DD>
- Same as
- <B>-B</B>.
- <DT><B>emacs</B>
- <DD>
- Use an emacs-style command line editing interface. This is enabled
- by default when the shell is interactive, unless the shell is started
- with the
- <B>--noediting</B>
- option.
- This also affects the editing interface used for <B>read -e</B>.
- <DT><B>errexit</B>
- <DD>
- Same as
- <B>-e</B>.
- <DT><B>errtrace</B>
- <DD>
- Same as
- <B>-E</B>.
- <DT><B>functrace</B>
- <DD>
- Same as
- <B>-T</B>.
- <DT><B>hashall</B>
- <DD>
- Same as
- <B>-h</B>.
- <DT><B>histexpand</B>
- <DD>
- Same as
- <B>-H</B>.
- <DT><B>history</B>
- <DD>
- Enable command history, as described above under
- <FONT SIZE=-1><B>HISTORY</B>.
- </FONT>
- This option is on by default in interactive shells.
- <DT><B>ignoreeof</B>
- <DD>
- The effect is as if the shell command
- <TT>IGNOREEOF=10</TT>
- had been executed
- (see
- <B>Shell Variables</B>
- above).
- <DT><B>keyword</B>
- <DD>
- Same as
- <B>-k</B>.
- <DT><B>monitor</B>
- <DD>
- Same as
- <B>-m</B>.
- <DT><B>noclobber</B>
- <DD>
- Same as
- <B>-C</B>.
- <DT><B>noexec</B>
- <DD>
- Same as
- <B>-n</B>.
- <DT><B>noglob</B>
- <DD>
- Same as
- <B>-f</B>.
- <DT><B>nolog</B>
- <DD>
- Currently ignored.
- <DT><B>notify</B>
- <DD>
- Same as
- <B>-b</B>.
- <DT><B>nounset</B>
- <DD>
- Same as
- <B>-u</B>.
- <DT><B>onecmd</B>
- <DD>
- Same as
- <B>-t</B>.
- <DT><B>physical</B>
- <DD>
- Same as
- <B>-P</B>.
- <DT><B>pipefail</B>
- <DD>
- If set, the return value of a pipeline is the value of the last
- (rightmost) command to exit with a non-zero status, or zero if all
- commands in the pipeline exit successfully.
- This option is disabled by default.
- <DT><B>posix</B>
- <DD>
- Change the behavior of
- <B>bash</B>
- where the default operation differs
- from the POSIX standard to match the standard (<I>posix mode</I>).
- See
- <FONT SIZE=-1><B>SEE ALSO</B>
- </FONT>
- below for a reference to a document that details how posix mode affects
- bash's behavior.
- <DT><B>privileged</B>
- <DD>
- Same as
- <B>-p</B>.
- <DT><B>verbose</B>
- <DD>
- Same as
- <B>-v</B>.
- <DT><B>vi</B>
- <DD>
- Use a vi-style command line editing interface.
- This also affects the editing interface used for <B>read -e</B>.
- <DT><B>xtrace</B>
- <DD>
- Same as
- <B>-x</B>.
- <P>
- </DL>
- <P>
- If
- <B>-o</B>
- is supplied with no <I>option-name</I>, the values of the current options are
- printed.
- If
- <B>+o</B>
- is supplied with no <I>option-name</I>, a series of
- <B>set</B>
- commands to recreate the current option settings is displayed on
- the standard output.
- </DL>
- <DT><B>-p</B>
- <DD>
- Turn on
- <I>privileged</I>
- mode. In this mode, the
- <FONT SIZE=-1><B>$ENV</B>
- </FONT>
- and
- <FONT SIZE=-1><B>$BASH_ENV</B>
- </FONT>
- files are not processed, shell functions are not inherited from the
- environment, and the
- <FONT SIZE=-1><B>SHELLOPTS</B>,
- </FONT>
- <FONT SIZE=-1><B>BASHOPTS</B>,
- </FONT>
- <FONT SIZE=-1><B>CDPATH</B>,
- </FONT>
- and
- <FONT SIZE=-1><B>GLOBIGNORE</B>
- </FONT>
- variables, if they appear in the environment, are ignored.
- If the shell is started with the effective user (group) id not equal to the
- real user (group) id, and the <B>-p</B> option is not supplied, these actions
- are taken and the effective user id is set to the real user id.
- If the <B>-p</B> option is supplied at startup, the effective user id is
- not reset.
- Turning this option off causes the effective user
- and group ids to be set to the real user and group ids.
- <DT><B>-t</B>
- <DD>
- Exit after reading and executing one command.
- <DT><B>-u</B>
- <DD>
- Treat unset variables and parameters other than the special
- parameters "@" and "*" as an error when performing
- parameter expansion. If expansion is attempted on an
- unset variable or parameter, the shell prints an error message, and,
- if not interactive, exits with a non-zero status.
- <DT><B>-v</B>
- <DD>
- Print shell input lines as they are read.
- <DT><B>-x</B>
- <DD>
- After expanding each <I>simple command</I>,
- <B>for</B> command, <B>case</B> command, <B>select</B> command, or
- arithmetic <B>for</B> command, display the expanded value of
- <FONT SIZE=-1><B>PS4</B>,
- </FONT>
- followed by the command and its expanded arguments
- or associated word list.
- <DT><B>-B</B>
- <DD>
- The shell performs brace expansion (see
- <B>Brace Expansion</B>
- above). This is on by default.
- <DT><B>-C</B>
- <DD>
- If set,
- <B>bash</B>
- does not overwrite an existing file with the
- <B>></B>,
- <B>>&</B>,
- and
- <B><></B>
- redirection operators. This may be overridden when
- creating output files by using the redirection operator
- <B>>|</B>
- instead of
- <B>></B>.
- <DT><B>-E</B>
- <DD>
- If set, any trap on <B>ERR</B> is inherited by shell functions, command
- substitutions, and commands executed in a subshell environment.
- The <B>ERR</B> trap is normally not inherited in such cases.
- <DT><B>-H</B>
- <DD>
- Enable
- <B>!</B>
- style history substitution. This option is on by
- default when the shell is interactive.
- <DT><B>-P</B>
- <DD>
- If set, the shell does not resolve symbolic links when executing
- commands such as
- <B>cd</B>
- that change the current working directory. It uses the
- physical directory structure instead. By default,
- <B>bash</B>
- follows the logical chain of directories when performing commands
- which change the current directory.
- <DT><B>-T</B>
- <DD>
- If set, any traps on <B>DEBUG</B> and <B>RETURN</B> are inherited by shell
- functions, command substitutions, and commands executed in a
- subshell environment.
- The <B>DEBUG</B> and <B>RETURN</B> traps are normally not inherited
- in such cases.
- <DT><B>--</B>
- <DD>
- If no arguments follow this option, then the positional parameters are
- unset. Otherwise, the positional parameters are set to the
- <I>arg</I>s, even if some of them begin with a
- <B>-</B>.
- <DT><B>-</B>
- <DD>
- Signal the end of options, cause all remaining <I>arg</I>s to be
- assigned to the positional parameters. The
- <B>-x</B>
- and
- <B>-v</B>
- options are turned off.
- If there are no <I>arg</I>s,
- the positional parameters remain unchanged.
- </DL>
- <P>
- The options are off by default unless otherwise noted.
- Using + rather than - causes these options to be turned off.
- The options can also be specified as arguments to an invocation of
- the shell.
- The current set of options may be found in
- <B>$-</B>.
- The return status is always true unless an invalid option is encountered.
- </DL>
- <DT><B>shift</B> [<I>n</I>]<DD>
- The positional parameters from <I>n</I>+1 ... are renamed to
- <B>$1</B>
- <B>....</B>
- Parameters represented by the numbers <B>$#</B>
- down to <B>$#</B>-<I>n</I>+1 are unset.
- <I>n</I>
- must be a non-negative number less than or equal to <B>$#</B>.
- If
- <I>n</I>
- is 0, no parameters are changed.
- If
- <I>n</I>
- is not given, it is assumed to be 1.
- If
- <I>n</I>
- is greater than <B>$#</B>, the positional parameters are not changed.
- The return status is greater than zero if
- <I>n</I>
- is greater than
- <B>$#</B>
- or less than zero; otherwise 0.
- <DT><B>shopt</B> [<B>-pqsu</B>] [<B>-o</B>] [<I>optname</I> ...]<DD>
- Toggle the values of settings controlling optional shell behavior.
- The settings can be either those listed below, or, if the
- <B>-o</B>
- option is used, those available with the
- <B>-o</B>
- option to the <B>set</B> builtin command.
- With no options, or with the
- <B>-p</B>
- option, a list of all settable options is displayed, with
- an indication of whether or not each is set.
- The <B>-p</B> option causes output to be displayed in a form that
- may be reused as input.
- Other options have the following meanings:
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>-s</B>
- <DD>
- Enable (set) each <I>optname</I>.
- <DT><B>-u</B>
- <DD>
- Disable (unset) each <I>optname</I>.
- <DT><B>-q</B>
- <DD>
- Suppresses normal output (quiet mode); the return status indicates
- whether the <I>optname</I> is set or unset.
- If multiple <I>optname</I> arguments are given with
- <B>-q</B>,
- the return status is zero if all <I>optnames</I> are enabled; non-zero
- otherwise.
- <DT><B>-o</B>
- <DD>
- Restricts the values of <I>optname</I> to be those defined for the
- <B>-o</B>
- option to the
- <B>set</B>
- builtin.
- </DL>
- <P>
- If either
- <B>-s</B>
- or
- <B>-u</B>
- is used with no <I>optname</I> arguments,
- <B>shopt</B>
- shows only those options which are set or unset, respectively.
- Unless otherwise noted, the <B>shopt</B> options are disabled (unset)
- by default.
- <P>
- The return status when listing options is zero if all <I>optnames</I>
- are enabled, non-zero otherwise. When setting or unsetting options,
- the return status is zero unless an <I>optname</I> is not a valid shell
- option.
- <P>
- The list of <B>shopt</B> options is:
- <P>
- <DL COMPACT>
- <DT><B>autocd</B>
- <DD>
- If set, a command name that is the name of a directory is executed as if
- it were the argument to the <B>cd</B> command.
- This option is only used by interactive shells.
- <DT><B>cdable_vars</B>
- <DD>
- If set, an argument to the
- <B>cd</B>
- builtin command that
- is not a directory is assumed to be the name of a variable whose
- value is the directory to change to.
- <DT><B>cdspell</B>
- <DD>
- If set, minor errors in the spelling of a directory component in a
- <B>cd</B>
- command will be corrected.
- The errors checked for are transposed characters,
- a missing character, and one character too many.
- If a correction is found, the corrected filename is printed,
- and the command proceeds.
- This option is only used by interactive shells.
- <DT><B>checkhash</B>
- <DD>
- If set, <B>bash</B> checks that a command found in the hash
- table exists before trying to execute it. If a hashed command no
- longer exists, a normal path search is performed.
- <DT><B>checkjobs</B>
- <DD>
- If set, <B>bash</B> lists the status of any stopped and running jobs before
- exiting an interactive shell. If any jobs are running, this causes
- the exit to be deferred until a second exit is attempted without an
- intervening command (see
- <FONT SIZE=-1><B>JOB CONTROL</B>
- </FONT>
- above). The shell always
- postpones exiting if any jobs are stopped.
- <DT><B>checkwinsize</B>
- <DD>
- If set, <B>bash</B> checks the window size after each command
- and, if necessary, updates the values of
- <FONT SIZE=-1><B>LINES</B>
- </FONT>
- and
- <FONT SIZE=-1><B>COLUMNS</B>.
- </FONT>
- <DT><B>cmdhist</B>
- <DD>
- If set,
- <B>bash</B>
- attempts to save all lines of a multiple-line
- command in the same history entry. This allows
- easy re-editing of multi-line commands.
- <DT><B>compat31</B>
- <DD>
- If set,
- <B>bash</B>
- changes its behavior to that of version 3.1 with respect to quoted
- arguments to the <B>[[</B> conditional command's <B>=~</B> operator
- and locale-specific string comparison when using the <B>[[</B>
- conditional command's <B><</B> and <B>></B> operators.
- Bash versions prior to bash-4.1 use ASCII collation and
- <I>strcmp</I>(3);
- bash-4.1 and later use the current locale's collation sequence and
- <I>strcoll</I>(3).
- <DT><B>compat32</B>
- <DD>
- If set,
- <B>bash</B>
- changes its behavior to that of version 3.2 with respect to
- locale-specific string comparison when using the <B>[[</B>
- conditional command's <B><</B> and <B>></B> operators (see previous item)
- and the effect of interrupting a command list.
- Bash versions 3.2 and earlier continue with the next command in the list
- after one terminates due to an interrupt.
- <DT><B>compat40</B>
- <DD>
- If set,
- <B>bash</B>
- changes its behavior to that of version 4.0 with respect to locale-specific
- string comparison when using the <B>[[</B>
- conditional command's <B><</B> and <B>></B> operators (see description of
- <B>compat31</B>)
- and the effect of interrupting a command list.
- Bash versions 4.0 and later interrupt the list as if the shell received the
- interrupt; previous versions continue with the next command in the list.
- <DT><B>compat41</B>
- <DD>
- If set,
- <B>bash</B>,
- when in <I>posix</I> mode, treats a single quote in a double-quoted
- parameter expansion as a special character. The single quotes must match
- (an even number) and the characters between the single quotes are considered
- quoted. This is the behavior of posix mode through version 4.1.
- The default bash behavior remains as in previous versions.
- <DT><B>compat42</B>
- <DD>
- If set,
- <B>bash</B>
- does not process the replacement string in the pattern substitution word
- expansion using quote removal.
- <DT><B>compat43</B>
- <DD>
- If set,
- <B>bash</B>
- does not print a warning message if an attempt is made to use a quoted compound
- array assignment as an argument to <B>declare</B>,
- makes word expansion errors
- non-fatal errors that cause the current command to fail (the default behavior is
- to make them fatal errors that cause the shell to exit),
- and does not reset the
- loop state when a shell function is executed (this allows <B>break</B> or
- <B>continue</B> in a shell function to affect loops in the caller's context).
- <DT><B>complete_fullquote</B>
- <DD>
- If set,
- <B>bash</B>
- quotes all shell metacharacters in filenames and directory names when
- performing completion.
- If not set,
- <B>bash</B>
- removes metacharacters such as the dollar sign from the set of
- characters that will be quoted in completed filenames
- when these metacharacters appear in shell variable references in words to be
- completed.
- This means that dollar signs in variable names that expand to directories
- will not be quoted;
- however, any dollar signs appearing in filenames will not be quoted, either.
- This is active only when bash is using backslashes to quote completed
- filenames.
- This variable is set by default, which is the default bash behavior in
- versions through 4.2.
- <DT><B>direxpand</B>
- <DD>
- If set,
- <B>bash</B>
- replaces directory names with the results of word expansion when performing
- filename completion. This changes the contents of the readline editing
- buffer.
- If not set,
- <B>bash</B>
- attempts to preserve what the user typed.
- <DT><B>dirspell</B>
- <DD>
- If set,
- <B>bash</B>
- attempts spelling correction on directory names during word completion
- if the directory name initially supplied does not exist.
- <DT><B>dotglob</B>
- <DD>
- If set,
- <B>bash</B>
- includes filenames beginning with a `.' in the results of pathname
- expansion.
- <DT><B>execfail</B>
- <DD>
- If set, a non-interactive shell will not exit if
- it cannot execute the file specified as an argument to the
- <B>exec</B>
- builtin command. An interactive shell does not exit if
- <B>exec</B>
- fails.
- <DT><B>expand_aliases</B>
- <DD>
- If set, aliases are expanded as described above under
- <FONT SIZE=-1><B>ALIASES</B>.
- </FONT>
- This option is enabled by default for interactive shells.
- <DT><B>extdebug</B>
- <DD>
- If set at shell invocation, arrange to execute the debugger profile
- before the shell starts, identical to the <B>--debugger</B> option.
- If set after invocation, behavior intended for use by debuggers is enabled:
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>1.</B>
- <DD>
- The <B>-F</B> option to the <B>declare</B> builtin displays the source
- file name and line number corresponding to each function name supplied
- as an argument.
- <DT><B>2.</B>
- <DD>
- If the command run by the <B>DEBUG</B> trap returns a non-zero value, the
- next command is skipped and not executed.
- <DT><B>3.</B>
- <DD>
- If the command run by the <B>DEBUG</B> trap returns a value of 2, and the
- shell is executing in a subroutine (a shell function or a shell script
- executed by the <B>.</B> or <B>source</B> builtins), the shell simulates
- a call to <B>return</B>.
- <DT><B>4.</B>
- <DD>
- <FONT SIZE=-1><B>BASH_ARGC</B>
- </FONT>
- and
- <FONT SIZE=-1><B>BASH_ARGV</B>
- </FONT>
- are updated as described in their descriptions above.
- <DT><B>5.</B>
- <DD>
- Function tracing is enabled: command substitution, shell functions, and
- subshells invoked with <B>(</B> <I>command</I> <B>)</B> inherit the
- <B>DEBUG</B> and <B>RETURN</B> traps.
- <DT><B>6.</B>
- <DD>
- Error tracing is enabled: command substitution, shell functions, and
- subshells invoked with <B>(</B> <I>command</I> <B>)</B> inherit the
- <B>ERR</B> trap.
- </DL></DL>
- <DT><B>extglob</B>
- <DD>
- If set, the extended pattern matching features described above under
- <B>Pathname Expansion</B> are enabled.
- <DT><B>extquote</B>
- <DD>
- If set, <B>$</B>aq<I>string</I>aq and <B>$</B>"<I>string</I>" quoting is
- performed within <B>${</B><I>parameter</I><B>}</B> expansions
- enclosed in double quotes. This option is enabled by default.
- <DT><B>failglob</B>
- <DD>
- If set, patterns which fail to match filenames during pathname expansion
- result in an expansion error.
- <DT><B>force_fignore</B>
- <DD>
- If set, the suffixes specified by the
- <FONT SIZE=-1><B>FIGNORE</B>
- </FONT>
- shell variable
- cause words to be ignored when performing word completion even if
- the ignored words are the only possible completions.
- See
- <FONT SIZE=-1><B>SHELL VARIABLES</B></FONT>
- above for a description of
- <FONT SIZE=-1><B>FIGNORE</B>.
- </FONT>
- This option is enabled by default.
- <DT><B>globasciiranges</B>
- <DD>
- If set, range expressions used in pattern matching bracket expressions (see
- <FONT SIZE=-1><B>Pattern Matching</B>
- </FONT>
- above) behave as if in the traditional C locale when performing
- comparisons. That is, the current locale's collating sequence
- is not taken into account, so
- <B>b</B>
- will not collate between
- <B>A</B>
- and
- <B>B</B>,
- and upper-case and lower-case ASCII characters will collate together.
- <DT><B>globstar</B>
- <DD>
- If set, the pattern <B>**</B> used in a pathname expansion context will
- match all files and zero or more directories and subdirectories.
- If the pattern is followed by a <B>/</B>, only directories and
- subdirectories match.
- <DT><B>gnu_errfmt</B>
- <DD>
- If set, shell error messages are written in the standard GNU error
- message format.
- <DT><B>histappend</B>
- <DD>
- If set, the history list is appended to the file named by the value
- of the
- <FONT SIZE=-1><B>HISTFILE</B>
- </FONT>
- variable when the shell exits, rather than overwriting the file.
- <DT><B>histreedit</B>
- <DD>
- If set, and
- <B>readline</B>
- is being used, a user is given the opportunity to re-edit a
- failed history substitution.
- <DT><B>histverify</B>
- <DD>
- If set, and
- <B>readline</B>
- is being used, the results of history substitution are not immediately
- passed to the shell parser. Instead, the resulting line is loaded into
- the <B>readline</B> editing buffer, allowing further modification.
- <DT><B>hostcomplete</B>
- <DD>
- If set, and
- <B>readline</B>
- is being used, <B>bash</B> will attempt to perform hostname completion when a
- word containing a <B>@</B> is being completed (see
- <B>Completing</B>
- under
- <FONT SIZE=-1><B>READLINE</B>
- </FONT>
- above).
- This is enabled by default.
- <DT><B>huponexit</B>
- <DD>
- If set, <B>bash</B> will send
- <FONT SIZE=-1><B>SIGHUP</B>
- </FONT>
- to all jobs when an interactive login shell exits.
- <DT><B>inherit_errexit</B>
- <DD>
- If set, command substitution inherits the value of the <B>errexit</B> option,
- instead of unsetting it in the subshell environment.
- This option is enabled when <I>posix mode</I> is enabled.
- <DT><B>interactive_comments</B>
- <DD>
- If set, allow a word beginning with
- <B>#</B>
- to cause that word and all remaining characters on that
- line to be ignored in an interactive shell (see
- <FONT SIZE=-1><B>COMMENTS</B>
- </FONT>
- above). This option is enabled by default.
- <DT><B>lastpipe</B>
- <DD>
- If set, and job control is not active, the shell runs the last command of
- a pipeline not executed in the background in the current shell environment.
- <DT><B>lithist</B>
- <DD>
- If set, and the
- <B>cmdhist</B>
- option is enabled, multi-line commands are saved to the history with
- embedded newlines rather than using semicolon separators where possible.
- <DT><B>login_shell</B>
- <DD>
- The shell sets this option if it is started as a login shell (see
- <FONT SIZE=-1><B>INVOCATION</B>
- </FONT>
- above).
- The value may not be changed.
- <DT><B>mailwarn</B>
- <DD>
- If set, and a file that <B>bash</B> is checking for mail has been
- accessed since the last time it was checked, the message ``The mail in
- <I>mailfile</I> has been read'' is displayed.
- <DT><B>no_empty_cmd_completion</B>
- <DD>
- If set, and
- <B>readline</B>
- is being used,
- <B>bash</B>
- will not attempt to search the
- <FONT SIZE=-1><B>PATH</B>
- </FONT>
- for possible completions when
- completion is attempted on an empty line.
- <DT><B>nocaseglob</B>
- <DD>
- If set,
- <B>bash</B>
- matches filenames in a case-insensitive fashion when performing pathname
- expansion (see
- <B>Pathname Expansion</B>
- above).
- <DT><B>nocasematch</B>
- <DD>
- If set,
- <B>bash</B>
- matches patterns in a case-insensitive fashion when performing matching
- while executing <B>case</B> or <B>[[</B> conditional commands,
- when performing pattern substitution word expansions,
- or when filtering possible completions as part of programmable completion.
- <DT><B>nullglob</B>
- <DD>
- If set,
- <B>bash</B>
- allows patterns which match no
- files (see
- <B>Pathname Expansion</B>
- above)
- to expand to a null string, rather than themselves.
- <DT><B>progcomp</B>
- <DD>
- If set, the programmable completion facilities (see
- <B>Programmable Completion</B> above) are enabled.
- This option is enabled by default.
- <DT><B>promptvars</B>
- <DD>
- If set, prompt strings undergo
- parameter expansion, command substitution, arithmetic
- expansion, and quote removal after being expanded as described in
- <FONT SIZE=-1><B>PROMPTING</B>
- </FONT>
- above. This option is enabled by default.
- <DT><B>restricted_shell</B>
- <DD>
- The shell sets this option if it is started in restricted mode (see
- <FONT SIZE=-1><B>RESTRICTED SHELL</B>
- </FONT>
- below).
- The value may not be changed.
- This is not reset when the startup files are executed, allowing
- the startup files to discover whether or not a shell is restricted.
- <DT><B>shift_verbose</B>
- <DD>
- If set, the
- <B>shift</B>
- builtin prints an error message when the shift count exceeds the
- number of positional parameters.
- <DT><B>sourcepath</B>
- <DD>
- If set, the
- <B>source</B> (<B>.</B>) builtin uses the value of
- <FONT SIZE=-1><B>PATH</B>
- </FONT>
- to find the directory containing the file supplied as an argument.
- This option is enabled by default.
- <DT><B>xpg_echo</B>
- <DD>
- If set, the <B>echo</B> builtin expands backslash-escape sequences
- by default.
- </DL></DL>
- <DT><B>suspend</B> [<B>-f</B>]<DD>
- Suspend the execution of this shell until it receives a
- <FONT SIZE=-1><B>SIGCONT</B>
- </FONT>
- signal. A login shell cannot be suspended; the
- <B>-f</B>
- option can be used to override this and force the suspension.
- The return status is 0 unless the shell is a login shell and
- <B>-f</B>
- is not supplied, or if job control is not enabled.
- <DT><B>test</B> <I>expr</I><DD>
- <DT><B>[</B> <I>expr</I> <B>]</B><DD>
- Return a status of 0 (true) or 1 (false) depending on
- the evaluation of the conditional expression
- <I>expr</I>.
- Each operator and operand must be a separate argument.
- Expressions are composed of the primaries described above under
- <FONT SIZE=-1><B>CONDITIONAL EXPRESSIONS</B>.
- </FONT>
- <B>test</B> does not accept any options, nor does it accept and ignore
- an argument of <B>--</B> as signifying the end of options.
- <P>
- Expressions may be combined using the following operators, listed
- in decreasing order of precedence.
- The evaluation depends on the number of arguments; see below.
- Operator precedence is used when there are five or more arguments.
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>! </B><I>expr</I>
- <DD>
- True if
- <I>expr</I>
- is false.
- <DT><B>( </B><I>expr</I> )
- <DD>
- Returns the value of <I>expr</I>.
- This may be used to override the normal precedence of operators.
- <DT><I>expr1</I> -<B>a</B> <I>expr2</I><DD>
- True if both
- <I>expr1</I>
- and
- <I>expr2</I>
- are true.
- <DT><I>expr1</I> -<B>o</B> <I>expr2</I><DD>
- True if either
- <I>expr1</I>
- or
- <I>expr2</I>
- is true.
- </DL>
- <P>
- <B>test</B> and <B>[</B> evaluate conditional
- expressions using a set of rules based on the number of arguments.
- <P>
- <DL COMPACT>
- <DT>0 arguments<DD>
- The expression is false.
- <DT>1 argument<DD>
- The expression is true if and only if the argument is not null.
- <DT>2 arguments<DD>
- If the first argument is <B>!</B>, the expression is true if and
- only if the second argument is null.
- If the first argument is one of the unary conditional operators listed above
- under
- <FONT SIZE=-1><B>CONDITIONAL EXPRESSIONS</B>,
- </FONT>
- the expression is true if the unary test is true.
- If the first argument is not a valid unary conditional operator, the expression
- is false.
- <DT>3 arguments<DD>
- The following conditions are applied in the order listed.
- If the second argument is one of the binary conditional operators listed above
- under
- <FONT SIZE=-1><B>CONDITIONAL EXPRESSIONS</B>,
- </FONT>
- the result of the expression is the result of the binary test using
- the first and third arguments as operands.
- The <B>-a</B> and <B>-o</B> operators are considered binary operators
- when there are three arguments.
- If the first argument is <B>!</B>, the value is the negation of
- the two-argument test using the second and third arguments.
- If the first argument is exactly <B>(</B> and the third argument is
- exactly <B>)</B>, the result is the one-argument test of the second
- argument.
- Otherwise, the expression is false.
- <DT>4 arguments<DD>
- If the first argument is <B>!</B>, the result is the negation of
- the three-argument expression composed of the remaining arguments.
- Otherwise, the expression is parsed and evaluated according to
- precedence using the rules listed above.
- <DT>5 or more arguments<DD>
- The expression is parsed and evaluated according to precedence
- using the rules listed above.
- <P>
- </DL>
- <P>
- When used with <B>test</B> or <B>[</B>, the <B><</B> and <B>></B> operators
- sort lexicographically using ASCII ordering.
- </DL>
- <DT><B>times</B>
- <DD>
- Print the accumulated user and system times for the shell and
- for processes run from the shell. The return status is 0.
- <DT><B>trap</B> [<B>-lp</B>] [[<I>arg</I>] <I>sigspec</I> ...]<DD>
- The command
- <I>arg</I>
- is to be read and executed when the shell receives
- signal(s)
- <I>sigspec</I>.
- If
- <I>arg</I>
- is absent (and there is a single <I>sigspec</I>) or
- <B>-</B>,
- each specified signal is
- reset to its original disposition (the value it had
- upon entrance to the shell).
- If
- <I>arg</I>
- is the null string the signal specified by each
- <I>sigspec</I>
- is ignored by the shell and by the commands it invokes.
- If
- <I>arg</I>
- is not present and
- <B>-p</B>
- has been supplied, then the trap commands associated with each
- <I>sigspec</I>
- are displayed.
- If no arguments are supplied or if only
- <B>-p</B>
- is given,
- <B>trap</B>
- prints the list of commands associated with each signal.
- The
- <B>-l</B>
- option causes the shell to print a list of signal names and
- their corresponding numbers.
- Each
- <I>sigspec</I>
- is either
- a signal name defined in <<I>signal.h</I>>, or a signal number.
- Signal names are case insensitive and the
- <FONT SIZE=-1><B>SIG</B>
- </FONT>
- prefix is optional.
- <P>
- If a
- <I>sigspec</I>
- is
- <FONT SIZE=-1><B>EXIT</B>
- </FONT>
- (0) the command
- <I>arg</I>
- is executed on exit from the shell.
- If a
- <I>sigspec</I>
- is
- <FONT SIZE=-1><B>DEBUG</B>,
- </FONT>
- the command
- <I>arg</I>
- is executed before every <I>simple command</I>, <I>for</I> command,
- <I>case</I> command, <I>select</I> command, every arithmetic <I>for</I>
- command, and before the first command executes in a shell function (see
- <FONT SIZE=-1><B>SHELL GRAMMAR</B>
- </FONT>
- above).
- Refer to the description of the <B>extdebug</B> option to the
- <B>shopt</B> builtin for details of its effect on the <B>DEBUG</B> trap.
- If a
- <I>sigspec</I>
- is
- <FONT SIZE=-1><B>RETURN</B>,
- </FONT>
- the command
- <I>arg</I>
- is executed each time a shell function or a script executed with
- the <B>.</B> or <B>source</B> builtins finishes executing.
- <P>
- If a
- <I>sigspec</I>
- is
- <FONT SIZE=-1><B>ERR</B>,
- </FONT>
- the command
- <I>arg</I>
- is executed whenever
- a pipeline (which may consist of a single simple
- command), a list, or a compound command returns a
- non-zero exit status,
- subject to the following conditions.
- The
- <FONT SIZE=-1><B>ERR</B>
- </FONT>
- trap is not executed if the failed
- command is part of the command list immediately following a
- <B>while</B>
- or
- <B>until</B>
- keyword,
- part of the test in an
- <I>if</I>
- statement, part of a command executed in a
- <B>&&</B>
- or
- <B>||</B>
- list except the command following the final <B>&&</B> or <B>||</B>,
- any command in a pipeline but the last,
- or if the command's return value is
- being inverted using
- <B>!</B>.
- These are the same conditions obeyed by the <B>errexit</B> (<B>-e</B>) option.
- <P>
- Signals ignored upon entry to the shell cannot be trapped or reset.
- Trapped signals that are not being ignored are reset to their original
- values in a subshell or subshell environment when one is created.
- The return status is false if any
- <I>sigspec</I>
- is invalid; otherwise
- <B>trap</B>
- returns true.
- <DT><B>type</B> [<B>-aftpP</B>] <I>name</I> [<I>name</I> ...]<DD>
- With no options,
- indicate how each
- <I>name</I>
- would be interpreted if used as a command name.
- If the
- <B>-t</B>
- option is used,
- <B>type</B>
- prints a string which is one of
- <I>alias</I>,
- <I>keyword</I>,
- <I>function</I>,
- <I>builtin</I>,
- or
- <I>file</I>
- if
- <I>name</I>
- is an alias, shell reserved word, function, builtin, or disk file,
- respectively.
- If the
- <I>name</I>
- is not found, then nothing is printed, and an exit status of false
- is returned.
- If the
- <B>-p</B>
- option is used,
- <B>type</B>
- either returns the name of the disk file
- that would be executed if
- <I>name</I>
- were specified as a command name,
- or nothing if
- <TT>type -t name</TT>
- would not return
- <I>file</I>.
- The
- <B>-P</B>
- option forces a
- <FONT SIZE=-1><B>PATH</B>
- </FONT>
- search for each <I>name</I>, even if
- <TT>type -t name</TT>
- would not return
- <I>file</I>.
- If a command is hashed,
- <B>-p</B>
- and
- <B>-P</B>
- print the hashed value, which is not necessarily the file that appears
- first in
- <FONT SIZE=-1><B>PATH</B>.
- </FONT>
- If the
- <B>-a</B>
- option is used,
- <B>type</B>
- prints all of the places that contain
- an executable named
- <I>name</I>.
- This includes aliases and functions,
- if and only if the
- <B>-p</B>
- option is not also used.
- The table of hashed commands is not consulted
- when using
- <B>-a</B>.
- The
- <B>-f</B>
- option suppresses shell function lookup, as with the <B>command</B> builtin.
- <B>type</B>
- returns true if all of the arguments are found, false if
- any are not found.
- <DT><B>ulimit</B> [<B>-HSabcdefiklmnpqrstuvxPT</B> [<I>limit</I>]]<DD>
- Provides control over the resources available to the shell and to
- processes started by it, on systems that allow such control.
- The <B>-H</B> and <B>-S</B> options specify that the hard or soft limit is
- set for the given resource.
- A hard limit cannot be increased by a non-root user once it is set;
- a soft limit may be increased up to the value of the hard limit.
- If neither <B>-H</B> nor <B>-S</B> is specified, both the soft and hard
- limits are set.
- The value of
- <I>limit</I>
- can be a number in the unit specified for the resource
- or one of the special values
- <B>hard</B>,
- <B>soft</B>,
- or
- <B>unlimited</B>,
- which stand for the current hard limit, the current soft limit, and
- no limit, respectively.
- If
- <I>limit</I>
- is omitted, the current value of the soft limit of the resource is
- printed, unless the <B>-H</B> option is given. When more than one
- resource is specified, the limit name and unit are printed before the value.
- Other options are interpreted as follows:
- <DL COMPACT><DT><DD>
- <DL COMPACT>
- <DT><B>-a</B>
- <DD>
- All current limits are reported
- <DT><B>-b</B>
- <DD>
- The maximum socket buffer size
- <DT><B>-c</B>
- <DD>
- The maximum size of core files created
- <DT><B>-d</B>
- <DD>
- The maximum size of a process's data segment
- <DT><B>-e</B>
- <DD>
- The maximum scheduling priority ("nice")
- <DT><B>-f</B>
- <DD>
- The maximum size of files written by the shell and its children
- <DT><B>-i</B>
- <DD>
- The maximum number of pending signals
- <DT><B>-k</B>
- <DD>
- The maximum number of kqueues that may be allocated
- <DT><B>-l</B>
- <DD>
- The maximum size that may be locked into memory
- <DT><B>-m</B>
- <DD>
- The maximum resident set size (many systems do not honor this limit)
- <DT><B>-n</B>
- <DD>
- The maximum number of open file descriptors (most systems do not
- allow this value to be set)
- <DT><B>-p</B>
- <DD>
- The pipe size in 512-byte blocks (this may not be set)
- <DT><B>-q</B>
- <DD>
- The maximum number of bytes in POSIX message queues
- <DT><B>-r</B>
- <DD>
- The maximum real-time scheduling priority
- <DT><B>-s</B>
- <DD>
- The maximum stack size
- <DT><B>-t</B>
- <DD>
- The maximum amount of cpu time in seconds
- <DT><B>-u</B>
- <DD>
- The maximum number of processes available to a single user
- <DT><B>-v</B>
- <DD>
- The maximum amount of virtual memory available to the shell and, on
- some systems, to its children
- <DT><B>-x</B>
- <DD>
- The maximum number of file locks
- <DT><B>-P</B>
- <DD>
- The maximum number of pseudoterminals
- <DT><B>-T</B>
- <DD>
- The maximum number of threads
- </DL>
- <P>
- If
- <I>limit</I>
- is given, and the
- <B>-a</B>
- option is not used,
- <I>limit</I> is the new value of the specified resource.
- If no option is given, then
- <B>-f</B>
- is assumed. Values are in 1024-byte increments, except for
- <B>-t</B>,
- which is in seconds;
- <B>-p</B>,
- which is in units of 512-byte blocks;
- <B>-P</B>,
- <B>-T</B>,
- <B>-b</B>,
- <B>-k</B>,
- <B>-n</B>,
- and
- <B>-u</B>,
- which are unscaled values;
- and, when in Posix mode,
- <B>-c</B>
- and
- <B>-f</B>,
- which are in 512-byte increments.
- The return status is 0 unless an invalid option or argument is supplied,
- or an error occurs while setting a new limit.
- </DL>
- <DT><B>umask</B> [<B>-p</B>] [<B>-S</B>] [<I>mode</I>]<DD>
- The user file-creation mask is set to
- <I>mode</I>.
- If
- <I>mode</I>
- begins with a digit, it
- is interpreted as an octal number; otherwise
- it is interpreted as a symbolic mode mask similar
- to that accepted by
- <I>chmod</I>(1).
- If
- <I>mode</I>
- is omitted, the current value of the mask is printed.
- The
- <B>-S</B>
- option causes the mask to be printed in symbolic form; the
- default output is an octal number.
- If the
- <B>-p</B>
- option is supplied, and
- <I>mode</I>
- is omitted, the output is in a form that may be reused as input.
- The return status is 0 if the mode was successfully changed or if
- no <I>mode</I> argument was supplied, and false otherwise.
- <DT><B>unalias</B> [-<B>a</B>] [<I>name</I> ...]<DD>
- Remove each <I>name</I> from the list of defined aliases. If
- <B>-a</B>
- is supplied, all alias definitions are removed. The return
- value is true unless a supplied
- <I>name</I>
- is not a defined alias.
- <DT><B>unset</B> [-<B>fv</B>] [-<B>n</B>] [<I>name</I> ...]<DD>
- For each
- <I>name</I>,
- remove the corresponding variable or function.
- If the
- <B>-v</B>
- option is given, each
- <I>name</I>
- refers to a shell variable, and that variable is removed.
- Read-only variables may not be unset.
- If
- <B>-f</B>
- is specified, each
- <I>name</I>
- refers to a shell function, and the function definition
- is removed.
- If the
- <B>-n</B>
- option is supplied, and <I>name</I> is a variable with the <I>nameref</I>
- attribute, <I>name</I> will be unset rather than the variable it
- references.
- <B>-n</B> has no effect if the <B>-f</B> option is supplied.
- If no options are supplied, each <I>name</I> refers to a variable; if
- there is no variable by that name, any function with that name is
- unset.
- Each unset variable or function is removed from the environment
- passed to subsequent commands.
- If any of
- <FONT SIZE=-1><B>COMP_WORDBREAKS</B>,
- </FONT>
- <FONT SIZE=-1><B>RANDOM</B>,
- </FONT>
- <FONT SIZE=-1><B>SECONDS</B>,
- </FONT>
- <FONT SIZE=-1><B>LINENO</B>,
- </FONT>
- <FONT SIZE=-1><B>HISTCMD</B>,
- </FONT>
- <FONT SIZE=-1><B>FUNCNAME</B>,
- </FONT>
- <FONT SIZE=-1><B>GROUPS</B>,
- </FONT>
- or
- <FONT SIZE=-1><B>DIRSTACK</B>
- </FONT>
- are unset, they lose their special properties, even if they are
- subsequently reset. The exit status is true unless a
- <I>name</I>
- is readonly.
- <DT><B>wait</B> [<B>-n</B>] [<I>n ...</I>]<DD>
- Wait for each specified child process and return its termination status.
- Each
- <I>n</I>
- may be a process
- ID or a job specification; if a job spec is given, all processes
- in that job's pipeline are waited for. If
- <I>n</I>
- is not given, all currently active child processes
- are waited for, and the return status is zero.
- If the <B>-n</B> option is supplied, <B>wait</B> waits for any job to
- terminate and returns its exit status.
- If
- <I>n</I>
- specifies a non-existent process or job, the return status is
- 127. Otherwise, the return status is the exit status of the last
- process or job waited for.
- </DL>
- <A NAME="lbDC"> </A>
- <H3>RESTRICTED SHELL</H3>
- <P>
- If
- <B>bash</B>
- is started with the name
- <B>rbash</B>,
- or the
- <B>-r</B>
- option is supplied at invocation,
- the shell becomes restricted.
- A restricted shell is used to
- set up an environment more controlled than the standard shell.
- It behaves identically to
- <B>bash</B>
- with the exception that the following are disallowed or not performed:
- <DL COMPACT>
- <DT>*<DD>
- changing directories with <B>cd</B>
- <DT>*<DD>
- setting or unsetting the values of
- <FONT SIZE=-1><B>SHELL</B>,
- </FONT>
- <FONT SIZE=-1><B>PATH</B>,
- </FONT>
- <FONT SIZE=-1><B>ENV</B>,
- </FONT>
- or
- <FONT SIZE=-1><B>BASH_ENV</B>
- </FONT>
- <DT>*<DD>
- specifying command names containing
- <B>/</B>
- <DT>*<DD>
- specifying a filename containing a
- <B>/</B>
- as an argument to the
- <B>.</B>
- builtin command
- <DT>*<DD>
- specifying a filename containing a slash as an argument to the
- <B>-p</B>
- option to the
- <B>hash</B>
- builtin command
- <DT>*<DD>
- importing function definitions from the shell environment at startup
- <DT>*<DD>
- parsing the value of
- <FONT SIZE=-1><B>SHELLOPTS</B>
- </FONT>
- from the shell environment at startup
- <DT>*<DD>
- redirecting output using the >, >|, <>, >&, &>, and >> redirection operators
- <DT>*<DD>
- using the
- <B>exec</B>
- builtin command to replace the shell with another command
- <DT>*<DD>
- adding or deleting builtin commands with the
- <B>-f</B>
- and
- <B>-d</B>
- options to the
- <B>enable</B>
- builtin command
- <DT>*<DD>
- using the <B>enable</B> builtin command to enable disabled shell builtins
- <DT>*<DD>
- specifying the
- <B>-p</B>
- option to the
- <B>command</B>
- builtin command
- <DT>*<DD>
- turning off restricted mode with
- <B>set +r</B> or <B>set +o restricted</B>.
- </DL>
- <P>
- These restrictions are enforced after any startup files are read.
- <P>
- When a command that is found to be a shell script is executed
- (see
- <FONT SIZE=-1><B>COMMAND EXECUTION</B>
- </FONT>
- above),
- <B>rbash</B>
- turns off any restrictions in the shell spawned to execute the
- script.
- <A NAME="lbDD"> </A>
- <H3>SEE ALSO</H3>
- <DL COMPACT>
- <DT><I>Bash Reference Manual</I>, Brian Fox and Chet Ramey<DD>
- <DT><I>The Gnu Readline Library</I>, Brian Fox and Chet Ramey<DD>
- <DT><I>The Gnu History Library</I>, Brian Fox and Chet Ramey<DD>
- <DT><I>Portable Operating System Interface (POSIX) Part 2: Shell and Utilities</I>, IEEE --<DD>
- <A HREF="http://pubs.opengroup.org/onlinepubs/9699919799/">http://pubs.opengroup.org/onlinepubs/9699919799/</A>
- <DT><A HREF="http://tiswww.case.edu/~chet/bash/POSIX">http://tiswww.case.edu/~chet/bash/POSIX</A> -- a description of posix mode<DD>
- <DT><I>sh</I>(1), <I>ksh</I>(1), <I>csh</I>(1)<DD>
- <DT><I>emacs</I>(1), <I>vi</I>(1)<DD>
- <DT><I>readline</I>(3)<DD>
- </DL>
- <A NAME="lbDE"> </A>
- <H3>FILES</H3>
- <DL COMPACT>
- <DT>
- <A HREF="file:/bin/bash"><I>/bin/bash</I></A>
- <DD>
- The <B>bash</B> executable
- <DT>
- <A HREF="file:/etc/profile"><I>/etc/profile</I></A>
- <DD>
- The systemwide initialization file, executed for login shells
- <DT>
- <A HREF="file:~/.bash_profile"><I>~/.bash_profile</I></A>
- <DD>
- The personal initialization file, executed for login shells
- <DT>
- <A HREF="file:~/.bashrc"><I>~/.bashrc</I></A>
- <DD>
- The individual per-interactive-shell startup file
- <DT>
- <A HREF="file:~/.bash_logout"><I>~/.bash_logout</I></A>
- <DD>
- The individual login shell cleanup file, executed when a login shell exits
- <DT>
- <A HREF="file:~/.inputrc"><I>~/.inputrc</I></A>
- <DD>
- Individual <I>readline</I> initialization file
- </DL>
- <A NAME="lbDF"> </A>
- <H3>AUTHORS</H3>
- Brian Fox, Free Software Foundation
- <BR>
- <A HREF="mailto:bfox@gnu.org">bfox@gnu.org</A>
- <P>
- Chet Ramey, Case Western Reserve University
- <BR>
- <A HREF="mailto:chet.ramey@case.edu">chet.ramey@case.edu</A>
- <A NAME="lbDG"> </A>
- <H3>BUG REPORTS</H3>
- If you find a bug in
- <B>bash,</B>
- you should report it. But first, you should
- make sure that it really is a bug, and that it appears in the latest
- version of
- <B>bash</B>.
- The latest version is always available from
- <I><A HREF="ftp://ftp.gnu.org/pub/gnu/bash/">ftp://ftp.gnu.org/pub/gnu/bash/</A></I>.
- <P>
- Once you have determined that a bug actually exists, use the
- <I>bashbug</I>
- command to submit a bug report.
- If you have a fix, you are encouraged to mail that as well!
- Suggestions and `philosophical' bug reports may be mailed
- to <I><A HREF="mailto:bug-bash@gnu.org">bug-bash@gnu.org</A></I> or posted to the Usenet
- newsgroup
- <A HREF="news:gnu.bash.bug">gnu.bash.bug</A>.
- <P>
- ALL bug reports should include:
- <P>
- <DL COMPACT>
- <DT>The version number of <B>bash</B><DD>
- <DT>The hardware and operating system<DD>
- <DT>The compiler used to compile<DD>
- <DT>A description of the bug behaviour<DD>
- <DT>A short script or `recipe' which exercises the bug<DD>
- </DL>
- <P>
- <I>bashbug</I>
- inserts the first three items automatically into the template
- it provides for filing a bug report.
- <P>
- Comments and bug reports concerning
- this manual page should be directed to
- <I><A HREF="mailto:chet.ramey@case.edu">chet.ramey@case.edu</A></I>.
- <A NAME="lbDH"> </A>
- <H3>BUGS</H3>
- <P>
- It's too big and too slow.
- <P>
- There are some subtle differences between
- <B>bash</B>
- and traditional versions of
- <B>sh</B>,
- mostly because of the
- <FONT SIZE=-1><B>POSIX</B>
- </FONT>
- specification.
- <P>
- Aliases are confusing in some uses.
- <P>
- Shell builtin commands and functions are not stoppable/restartable.
- <P>
- Compound commands and command sequences of the form `a ; b ; c'
- are not handled gracefully when process suspension is attempted.
- When a process is stopped, the shell immediately executes the next
- command in the sequence.
- It suffices to place the sequence of commands between
- parentheses to force it into a subshell, which may be stopped as
- a unit.
- <P>
- Array variables may not (yet) be exported.
- <P>
- There may be only one active coprocess at a time.
- <HR>
- <TABLE WIDTH=100%>
- <TR>
- <TH ALIGN=LEFT width=33%>GNU Bash 4.4<TH ALIGN=CENTER width=33%>2016 August 26<TH ALIGN=RIGHT width=33%>BASH(1)
- </TR>
- </TABLE>
- <HR>
- <A NAME="index"> </A><H2>Index</H2>
- <DL>
- <DT><A HREF="#lbAB">NAME</A><DD>
- <DT><A HREF="#lbAC">SYNOPSIS</A><DD>
- <DT><A HREF="#lbAD">COPYRIGHT</A><DD>
- <DT><A HREF="#lbAE">DESCRIPTION</A><DD>
- <DT><A HREF="#lbAF">OPTIONS</A><DD>
- <DT><A HREF="#lbAG">ARGUMENTS</A><DD>
- <DT><A HREF="#lbAH">INVOCATION</A><DD>
- <DT><A HREF="#lbAI">DEFINITIONS</A><DD>
- <DT><A HREF="#lbAJ">RESERVED WORDS</A><DD>
- <DT><A HREF="#lbAK">SHELL GRAMMAR</A><DD>
- <DL>
- <DT><A HREF="#lbAL">Simple Commands</A><DD>
- <DT><A HREF="#lbAM">Pipelines</A><DD>
- <DT><A HREF="#lbAN">Lists</A><DD>
- <DT><A HREF="#lbAO">Compound Commands</A><DD>
- <DT><A HREF="#lbAP">Coprocesses</A><DD>
- <DT><A HREF="#lbAQ">Shell Function Definitions</A><DD>
- </DL>
- <DT><A HREF="#lbAR">COMMENTS</A><DD>
- <DT><A HREF="#lbAS">QUOTING</A><DD>
- <DT><A HREF="#lbAT">PARAMETERS</A><DD>
- <DL>
- <DT><A HREF="#lbAU">Positional Parameters</A><DD>
- <DT><A HREF="#lbAV">Special Parameters</A><DD>
- <DT><A HREF="#lbAW">Shell Variables</A><DD>
- <DT><A HREF="#lbAX">Arrays</A><DD>
- </DL>
- <DT><A HREF="#lbAY">EXPANSION</A><DD>
- <DL>
- <DT><A HREF="#lbAZ">Brace Expansion</A><DD>
- <DT><A HREF="#lbBA">Tilde Expansion</A><DD>
- <DT><A HREF="#lbBB">Parameter Expansion</A><DD>
- <DT><A HREF="#lbBC">Command Substitution</A><DD>
- <DT><A HREF="#lbBD">Arithmetic Expansion</A><DD>
- <DT><A HREF="#lbBE">Process Substitution</A><DD>
- <DT><A HREF="#lbBF">Word Splitting</A><DD>
- <DT><A HREF="#lbBG">Pathname Expansion</A><DD>
- <DT><A HREF="#lbBH">Quote Removal</A><DD>
- </DL>
- <DT><A HREF="#lbBI">REDIRECTION</A><DD>
- <DL>
- <DT><A HREF="#lbBJ">Redirecting Input</A><DD>
- <DT><A HREF="#lbBK">Redirecting Output</A><DD>
- <DT><A HREF="#lbBL">Appending Redirected Output</A><DD>
- <DT><A HREF="#lbBM">Redirecting Standard Output and Standard Error</A><DD>
- <DT><A HREF="#lbBN">Appending Standard Output and Standard Error</A><DD>
- <DT><A HREF="#lbBO">Here Documents</A><DD>
- <DT><A HREF="#lbBP">Here Strings</A><DD>
- <DT><A HREF="#lbBQ">Duplicating File Descriptors</A><DD>
- <DT><A HREF="#lbBR">Moving File Descriptors</A><DD>
- <DT><A HREF="#lbBS">Opening File Descriptors for Reading and Writing</A><DD>
- </DL>
- <DT><A HREF="#lbBT">ALIASES</A><DD>
- <DT><A HREF="#lbBU">FUNCTIONS</A><DD>
- <DT><A HREF="#lbBV">ARITHMETIC EVALUATION</A><DD>
- <DT><A HREF="#lbBW">CONDITIONAL EXPRESSIONS</A><DD>
- <DT><A HREF="#lbBX">SIMPLE COMMAND EXPANSION</A><DD>
- <DT><A HREF="#lbBY">COMMAND EXECUTION</A><DD>
- <DT><A HREF="#lbBZ">COMMAND EXECUTION ENVIRONMENT</A><DD>
- <DT><A HREF="#lbCA">ENVIRONMENT</A><DD>
- <DT><A HREF="#lbCB">EXIT STATUS</A><DD>
- <DT><A HREF="#lbCC">SIGNALS</A><DD>
- <DT><A HREF="#lbCD">JOB CONTROL</A><DD>
- <DT><A HREF="#lbCE">PROMPTING</A><DD>
- <DT><A HREF="#lbCF">READLINE</A><DD>
- <DL>
- <DT><A HREF="#lbCG">Readline Notation</A><DD>
- <DT><A HREF="#lbCH">Readline Initialization</A><DD>
- <DT><A HREF="#lbCI">Readline Key Bindings</A><DD>
- <DT><A HREF="#lbCJ">Readline Variables</A><DD>
- <DT><A HREF="#lbCK">Readline Conditional Constructs</A><DD>
- <DT><A HREF="#lbCL">Searching</A><DD>
- <DT><A HREF="#lbCM">Readline Command Names</A><DD>
- <DT><A HREF="#lbCN">Commands for Moving</A><DD>
- <DT><A HREF="#lbCO">Commands for Manipulating the History</A><DD>
- <DT><A HREF="#lbCP">Commands for Changing Text</A><DD>
- <DT><A HREF="#lbCQ">Killing and Yanking</A><DD>
- <DT><A HREF="#lbCR">Numeric Arguments</A><DD>
- <DT><A HREF="#lbCS">Completing</A><DD>
- <DT><A HREF="#lbCT">Keyboard Macros</A><DD>
- <DT><A HREF="#lbCU">Miscellaneous</A><DD>
- <DT><A HREF="#lbCV">Programmable Completion</A><DD>
- </DL>
- <DT><A HREF="#lbCW">HISTORY</A><DD>
- <DT><A HREF="#lbCX">HISTORY EXPANSION</A><DD>
- <DL>
- <DT><A HREF="#lbCY">Event Designators</A><DD>
- <DT><A HREF="#lbCZ">Word Designators</A><DD>
- <DT><A HREF="#lbDA">Modifiers</A><DD>
- </DL>
- <DT><A HREF="#lbDB">SHELL BUILTIN COMMANDS</A><DD>
- <DT><A HREF="#lbDC">RESTRICTED SHELL</A><DD>
- <DT><A HREF="#lbDD">SEE ALSO</A><DD>
- <DT><A HREF="#lbDE">FILES</A><DD>
- <DT><A HREF="#lbDF">AUTHORS</A><DD>
- <DT><A HREF="#lbDG">BUG REPORTS</A><DD>
- <DT><A HREF="#lbDH">BUGS</A><DD>
- </DL>
- <HR>
- This document was created by man2html from bash.1.<BR>
- Time: 31 August 2016 10:24:30 EDT
- </BODY>
- </HTML>
|
