1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031303230333034303530363037303830393040304130423043304430453046304730483049305030513052305330543055305630573058305930603061306230633064306530663067306830693070307130723073307430753076307730783079308030813082308330843085308630873088308930903091309230933094309530963097309830993100310131023103310431053106310731083109311031113112311331143115311631173118311931203121312231233124312531263127312831293130313131323133313431353136313731383139314031413142314331443145314631473148314931503151315231533154315531563157315831593160316131623163316431653166316731683169317031713172317331743175317631773178317931803181318231833184318531863187318831893190319131923193319431953196319731983199320032013202320332043205320632073208320932103211321232133214321532163217321832193220322132223223322432253226322732283229323032313232323332343235323632373238323932403241324232433244324532463247324832493250325132523253325432553256325732583259326032613262326332643265326632673268326932703271327232733274327532763277327832793280328132823283328432853286328732883289329032913292329332943295329632973298329933003301330233033304330533063307330833093310331133123313331433153316331733183319332033213322332333243325332633273328332933303331333233333334333533363337333833393340334133423343334433453346334733483349335033513352335333543355335633573358335933603361336233633364336533663367336833693370337133723373337433753376337733783379338033813382338333843385338633873388338933903391339233933394339533963397339833993400340134023403340434053406340734083409341034113412341334143415341634173418341934203421342234233424342534263427342834293430343134323433343434353436343734383439344034413442344334443445344634473448344934503451345234533454345534563457345834593460346134623463346434653466346734683469347034713472347334743475347634773478347934803481348234833484348534863487348834893490349134923493349434953496349734983499350035013502350335043505350635073508350935103511351235133514351535163517351835193520352135223523352435253526352735283529353035313532353335343535353635373538353935403541354235433544354535463547354835493550355135523553355435553556355735583559356035613562356335643565356635673568356935703571357235733574357535763577357835793580358135823583358435853586358735883589359035913592359335943595359635973598359936003601360236033604360536063607360836093610361136123613361436153616361736183619362036213622362336243625362636273628362936303631363236333634363536363637363836393640364136423643364436453646364736483649365036513652365336543655365636573658365936603661366236633664366536663667366836693670367136723673367436753676367736783679368036813682368336843685368636873688368936903691369236933694369536963697369836993700370137023703370437053706370737083709371037113712371337143715371637173718371937203721372237233724372537263727372837293730373137323733373437353736373737383739374037413742374337443745374637473748374937503751375237533754375537563757375837593760376137623763376437653766376737683769377037713772377337743775377637773778377937803781378237833784378537863787378837893790379137923793379437953796379737983799380038013802380338043805380638073808380938103811381238133814381538163817381838193820382138223823382438253826382738283829383038313832383338343835383638373838383938403841384238433844384538463847384838493850385138523853385438553856385738583859386038613862386338643865386638673868386938703871387238733874387538763877387838793880388138823883388438853886388738883889389038913892389338943895389638973898389939003901390239033904390539063907390839093910391139123913391439153916391739183919392039213922392339243925392639273928392939303931393239333934393539363937393839393940394139423943394439453946394739483949395039513952395339543955395639573958395939603961396239633964396539663967396839693970397139723973397439753976397739783979398039813982398339843985398639873988398939903991399239933994399539963997399839994000400140024003400440054006400740084009401040114012401340144015401640174018401940204021402240234024402540264027402840294030403140324033403440354036403740384039404040414042404340444045404640474048404940504051405240534054405540564057405840594060406140624063406440654066406740684069407040714072407340744075407640774078407940804081408240834084408540864087408840894090409140924093409440954096409740984099410041014102410341044105410641074108410941104111411241134114411541164117411841194120412141224123412441254126412741284129413041314132413341344135413641374138413941404141414241434144414541464147414841494150415141524153415441554156415741584159416041614162416341644165416641674168416941704171417241734174417541764177417841794180418141824183418441854186418741884189419041914192419341944195419641974198419942004201420242034204420542064207420842094210421142124213421442154216421742184219422042214222422342244225422642274228422942304231423242334234423542364237423842394240424142424243424442454246424742484249425042514252425342544255425642574258425942604261426242634264426542664267426842694270427142724273427442754276427742784279428042814282428342844285428642874288428942904291429242934294429542964297429842994300430143024303430443054306430743084309431043114312431343144315431643174318431943204321432243234324432543264327432843294330433143324333433443354336433743384339434043414342434343444345434643474348434943504351435243534354435543564357435843594360436143624363436443654366436743684369437043714372437343744375437643774378437943804381438243834384438543864387438843894390439143924393439443954396439743984399440044014402440344044405440644074408440944104411441244134414441544164417441844194420442144224423442444254426442744284429443044314432443344344435443644374438443944404441444244434444444544464447444844494450445144524453445444554456445744584459446044614462446344644465446644674468446944704471447244734474447544764477447844794480448144824483448444854486448744884489449044914492449344944495449644974498449945004501450245034504450545064507450845094510451145124513451445154516451745184519452045214522452345244525452645274528452945304531453245334534453545364537453845394540454145424543454445454546454745484549455045514552455345544555455645574558455945604561456245634564456545664567456845694570457145724573457445754576457745784579458045814582458345844585458645874588458945904591459245934594459545964597459845994600460146024603460446054606460746084609461046114612461346144615461646174618461946204621462246234624462546264627462846294630463146324633463446354636463746384639464046414642464346444645464646474648464946504651465246534654465546564657465846594660466146624663466446654666466746684669467046714672467346744675467646774678467946804681468246834684468546864687468846894690469146924693469446954696469746984699470047014702470347044705470647074708470947104711471247134714471547164717471847194720472147224723472447254726472747284729473047314732473347344735473647374738473947404741474247434744474547464747474847494750475147524753475447554756475747584759476047614762476347644765476647674768476947704771477247734774477547764777477847794780478147824783478447854786478747884789479047914792479347944795479647974798479948004801480248034804480548064807480848094810481148124813481448154816481748184819482048214822482348244825482648274828482948304831483248334834483548364837483848394840484148424843484448454846484748484849485048514852485348544855485648574858485948604861486248634864486548664867486848694870487148724873487448754876487748784879488048814882488348844885488648874888488948904891489248934894489548964897489848994900490149024903490449054906490749084909491049114912491349144915491649174918491949204921492249234924492549264927492849294930493149324933493449354936493749384939494049414942494349444945494649474948494949504951495249534954495549564957495849594960496149624963496449654966496749684969497049714972497349744975497649774978497949804981498249834984498549864987498849894990499149924993499449954996499749984999500050015002500350045005500650075008500950105011501250135014501550165017501850195020502150225023502450255026502750285029503050315032503350345035503650375038503950405041504250435044504550465047504850495050505150525053505450555056505750585059506050615062506350645065506650675068506950705071507250735074507550765077507850795080508150825083508450855086508750885089509050915092509350945095509650975098509951005101510251035104510551065107510851095110511151125113511451155116511751185119512051215122512351245125512651275128512951305131513251335134513551365137513851395140514151425143514451455146514751485149515051515152515351545155515651575158515951605161516251635164516551665167516851695170517151725173517451755176517751785179518051815182518351845185518651875188518951905191519251935194519551965197519851995200520152025203520452055206520752085209521052115212521352145215521652175218521952205221522252235224522552265227522852295230523152325233523452355236523752385239524052415242524352445245524652475248524952505251525252535254525552565257525852595260526152625263526452655266526752685269527052715272527352745275527652775278527952805281528252835284528552865287528852895290529152925293529452955296529752985299530053015302530353045305530653075308530953105311531253135314531553165317531853195320532153225323532453255326532753285329533053315332533353345335533653375338533953405341534253435344534553465347534853495350535153525353535453555356535753585359536053615362536353645365536653675368536953705371537253735374537553765377537853795380538153825383538453855386538753885389539053915392539353945395539653975398539954005401540254035404540554065407540854095410541154125413541454155416541754185419542054215422542354245425542654275428542954305431543254335434543554365437543854395440544154425443544454455446544754485449545054515452545354545455545654575458545954605461546254635464546554665467546854695470547154725473547454755476547754785479548054815482548354845485548654875488548954905491549254935494549554965497549854995500550155025503550455055506550755085509551055115512551355145515551655175518551955205521552255235524552555265527552855295530553155325533553455355536553755385539554055415542554355445545554655475548554955505551555255535554555555565557555855595560556155625563556455655566556755685569557055715572557355745575557655775578557955805581558255835584558555865587558855895590559155925593559455955596559755985599560056015602560356045605560656075608560956105611561256135614561556165617561856195620562156225623562456255626562756285629563056315632563356345635563656375638563956405641564256435644564556465647564856495650565156525653565456555656565756585659566056615662566356645665566656675668566956705671567256735674567556765677567856795680568156825683568456855686568756885689569056915692569356945695569656975698569957005701570257035704570557065707570857095710571157125713571457155716571757185719572057215722572357245725572657275728572957305731573257335734573557365737573857395740574157425743574457455746574757485749575057515752575357545755575657575758575957605761576257635764576557665767576857695770577157725773577457755776577757785779578057815782578357845785578657875788578957905791579257935794579557965797579857995800580158025803580458055806580758085809581058115812581358145815581658175818581958205821582258235824582558265827582858295830583158325833583458355836583758385839584058415842584358445845584658475848584958505851585258535854585558565857585858595860586158625863586458655866586758685869587058715872587358745875587658775878587958805881588258835884588558865887588858895890589158925893589458955896589758985899590059015902590359045905590659075908590959105911591259135914591559165917591859195920592159225923592459255926592759285929593059315932593359345935593659375938593959405941594259435944594559465947594859495950595159525953595459555956595759585959596059615962596359645965596659675968596959705971597259735974597559765977597859795980598159825983598459855986598759885989599059915992599359945995599659975998599960006001600260036004600560066007600860096010601160126013601460156016601760186019602060216022602360246025602660276028602960306031603260336034603560366037603860396040604160426043604460456046604760486049605060516052605360546055605660576058605960606061606260636064606560666067606860696070607160726073607460756076607760786079608060816082608360846085608660876088608960906091609260936094609560966097609860996100610161026103610461056106610761086109611061116112611361146115611661176118611961206121612261236124612561266127612861296130613161326133613461356136613761386139614061416142614361446145614661476148614961506151615261536154615561566157615861596160616161626163616461656166616761686169617061716172617361746175617661776178617961806181618261836184618561866187618861896190619161926193619461956196619761986199620062016202620362046205620662076208620962106211621262136214621562166217621862196220622162226223622462256226622762286229623062316232623362346235623662376238623962406241624262436244624562466247624862496250625162526253625462556256625762586259626062616262626362646265626662676268626962706271627262736274627562766277627862796280628162826283628462856286628762886289629062916292629362946295629662976298629963006301630263036304630563066307630863096310631163126313631463156316631763186319632063216322632363246325632663276328632963306331633263336334633563366337633863396340634163426343634463456346634763486349635063516352635363546355635663576358635963606361636263636364636563666367636863696370637163726373637463756376637763786379638063816382638363846385638663876388638963906391639263936394639563966397639863996400640164026403640464056406640764086409641064116412641364146415641664176418641964206421642264236424642564266427642864296430643164326433643464356436643764386439644064416442644364446445644664476448644964506451645264536454645564566457645864596460646164626463646464656466646764686469647064716472647364746475647664776478647964806481648264836484648564866487648864896490649164926493649464956496649764986499650065016502650365046505650665076508650965106511651265136514651565166517651865196520652165226523652465256526652765286529653065316532653365346535653665376538653965406541654265436544654565466547654865496550655165526553655465556556655765586559656065616562656365646565656665676568656965706571657265736574657565766577657865796580658165826583658465856586658765886589659065916592659365946595659665976598659966006601660266036604660566066607660866096610661166126613661466156616661766186619662066216622662366246625662666276628662966306631663266336634663566366637663866396640664166426643664466456646664766486649665066516652665366546655665666576658665966606661666266636664666566666667666866696670667166726673667466756676667766786679668066816682668366846685668666876688668966906691669266936694669566966697669866996700670167026703670467056706670767086709671067116712671367146715671667176718671967206721672267236724672567266727672867296730673167326733673467356736673767386739674067416742674367446745674667476748674967506751675267536754675567566757675867596760676167626763676467656766676767686769677067716772677367746775677667776778677967806781678267836784678567866787678867896790679167926793679467956796679767986799680068016802680368046805680668076808680968106811681268136814681568166817681868196820682168226823682468256826682768286829683068316832683368346835683668376838683968406841684268436844684568466847684868496850685168526853685468556856685768586859686068616862686368646865686668676868686968706871687268736874687568766877687868796880688168826883688468856886688768886889689068916892689368946895689668976898689969006901690269036904690569066907690869096910691169126913691469156916691769186919692069216922692369246925692669276928692969306931693269336934693569366937693869396940694169426943694469456946694769486949695069516952695369546955695669576958695969606961696269636964696569666967696869696970697169726973697469756976697769786979698069816982698369846985698669876988698969906991699269936994699569966997699869997000700170027003700470057006700770087009701070117012701370147015701670177018701970207021702270237024702570267027702870297030703170327033703470357036703770387039704070417042704370447045704670477048704970507051705270537054705570567057705870597060706170627063706470657066706770687069707070717072707370747075707670777078707970807081708270837084708570867087708870897090709170927093709470957096709770987099710071017102710371047105710671077108710971107111711271137114711571167117711871197120712171227123712471257126712771287129713071317132713371347135713671377138713971407141714271437144714571467147714871497150715171527153715471557156715771587159716071617162716371647165716671677168716971707171717271737174717571767177717871797180718171827183718471857186718771887189719071917192719371947195719671977198719972007201720272037204720572067207720872097210721172127213721472157216721772187219722072217222722372247225722672277228722972307231723272337234723572367237723872397240724172427243724472457246724772487249725072517252725372547255725672577258725972607261726272637264726572667267726872697270727172727273727472757276727772787279728072817282728372847285728672877288728972907291729272937294729572967297729872997300730173027303730473057306730773087309731073117312731373147315731673177318731973207321732273237324732573267327732873297330733173327333733473357336733773387339734073417342734373447345734673477348734973507351735273537354735573567357735873597360736173627363736473657366736773687369737073717372737373747375737673777378737973807381738273837384738573867387738873897390739173927393739473957396739773987399740074017402740374047405740674077408740974107411741274137414741574167417741874197420742174227423742474257426742774287429743074317432743374347435743674377438743974407441744274437444744574467447744874497450745174527453745474557456745774587459746074617462746374647465746674677468746974707471747274737474747574767477747874797480748174827483748474857486748774887489749074917492749374947495749674977498749975007501750275037504750575067507750875097510751175127513751475157516751775187519752075217522752375247525752675277528752975307531753275337534753575367537753875397540754175427543754475457546754775487549755075517552755375547555755675577558755975607561756275637564756575667567756875697570757175727573757475757576757775787579758075817582758375847585758675877588758975907591759275937594759575967597759875997600760176027603760476057606760776087609761076117612761376147615761676177618761976207621762276237624762576267627762876297630763176327633763476357636763776387639764076417642764376447645764676477648764976507651765276537654765576567657765876597660766176627663766476657666766776687669767076717672767376747675767676777678767976807681768276837684768576867687768876897690769176927693769476957696769776987699770077017702770377047705770677077708770977107711771277137714771577167717771877197720772177227723772477257726772777287729773077317732773377347735773677377738773977407741774277437744774577467747774877497750775177527753775477557756775777587759776077617762776377647765776677677768776977707771777277737774777577767777777877797780778177827783778477857786778777887789779077917792779377947795779677977798779978007801780278037804780578067807780878097810781178127813781478157816781778187819782078217822782378247825782678277828782978307831783278337834783578367837783878397840784178427843784478457846784778487849785078517852785378547855785678577858785978607861786278637864786578667867786878697870787178727873787478757876787778787879788078817882788378847885788678877888788978907891789278937894789578967897789878997900790179027903790479057906790779087909791079117912791379147915791679177918791979207921792279237924792579267927792879297930793179327933793479357936793779387939794079417942794379447945794679477948794979507951795279537954795579567957795879597960796179627963796479657966796779687969797079717972797379747975797679777978797979807981798279837984798579867987798879897990799179927993799479957996799779987999800080018002800380048005800680078008800980108011801280138014801580168017801880198020802180228023802480258026802780288029803080318032803380348035803680378038803980408041804280438044804580468047804880498050805180528053805480558056805780588059806080618062806380648065806680678068806980708071807280738074807580768077807880798080808180828083808480858086808780888089809080918092809380948095809680978098809981008101810281038104810581068107810881098110811181128113811481158116811781188119812081218122812381248125812681278128812981308131813281338134813581368137813881398140814181428143814481458146814781488149815081518152815381548155815681578158815981608161816281638164816581668167816881698170817181728173817481758176817781788179818081818182818381848185818681878188818981908191819281938194819581968197819881998200820182028203820482058206820782088209821082118212821382148215821682178218821982208221822282238224822582268227822882298230823182328233823482358236823782388239824082418242824382448245824682478248824982508251825282538254825582568257825882598260826182628263826482658266826782688269827082718272827382748275827682778278827982808281828282838284828582868287828882898290829182928293829482958296829782988299830083018302830383048305830683078308830983108311831283138314831583168317831883198320832183228323832483258326832783288329833083318332833383348335833683378338833983408341834283438344834583468347834883498350835183528353835483558356835783588359836083618362836383648365836683678368836983708371837283738374837583768377837883798380838183828383838483858386838783888389839083918392839383948395839683978398839984008401840284038404840584068407840884098410841184128413841484158416841784188419842084218422842384248425842684278428842984308431843284338434843584368437843884398440844184428443844484458446844784488449845084518452845384548455845684578458845984608461846284638464846584668467846884698470847184728473847484758476847784788479848084818482848384848485848684878488848984908491849284938494849584968497849884998500850185028503850485058506850785088509851085118512851385148515851685178518851985208521852285238524852585268527852885298530853185328533853485358536853785388539854085418542854385448545854685478548854985508551855285538554855585568557855885598560856185628563856485658566856785688569857085718572857385748575857685778578857985808581858285838584858585868587858885898590859185928593859485958596859785988599860086018602860386048605860686078608860986108611861286138614861586168617861886198620862186228623862486258626862786288629863086318632863386348635863686378638863986408641864286438644864586468647864886498650865186528653865486558656865786588659866086618662866386648665866686678668866986708671867286738674867586768677867886798680868186828683868486858686868786888689869086918692869386948695869686978698869987008701870287038704870587068707870887098710871187128713871487158716871787188719872087218722872387248725872687278728872987308731873287338734873587368737873887398740874187428743874487458746874787488749875087518752875387548755875687578758875987608761876287638764876587668767876887698770877187728773877487758776877787788779878087818782878387848785878687878788878987908791879287938794879587968797879887998800880188028803880488058806880788088809881088118812881388148815881688178818881988208821882288238824882588268827882888298830883188328833883488358836883788388839884088418842884388448845884688478848884988508851885288538854885588568857885888598860886188628863886488658866886788688869887088718872887388748875887688778878887988808881888288838884888588868887888888898890889188928893889488958896889788988899890089018902890389048905890689078908890989108911891289138914891589168917891889198920892189228923892489258926892789288929893089318932893389348935893689378938893989408941894289438944894589468947894889498950895189528953895489558956895789588959896089618962896389648965896689678968896989708971897289738974897589768977897889798980898189828983898489858986898789888989899089918992899389948995899689978998899990009001900290039004900590069007900890099010901190129013901490159016901790189019902090219022902390249025902690279028902990309031903290339034903590369037903890399040904190429043904490459046904790489049905090519052905390549055905690579058905990609061906290639064906590669067906890699070907190729073907490759076907790789079908090819082908390849085908690879088908990909091909290939094909590969097909890999100910191029103910491059106910791089109911091119112911391149115911691179118911991209121912291239124912591269127912891299130913191329133913491359136913791389139914091419142914391449145914691479148914991509151915291539154915591569157915891599160916191629163916491659166916791689169917091719172917391749175917691779178917991809181918291839184918591869187918891899190919191929193919491959196919791989199920092019202920392049205920692079208920992109211921292139214921592169217921892199220922192229223922492259226922792289229923092319232923392349235923692379238923992409241924292439244924592469247924892499250925192529253925492559256925792589259926092619262926392649265926692679268926992709271927292739274927592769277927892799280928192829283928492859286928792889289929092919292929392949295929692979298929993009301930293039304930593069307930893099310931193129313931493159316931793189319932093219322932393249325932693279328932993309331933293339334933593369337933893399340934193429343934493459346934793489349935093519352935393549355935693579358935993609361936293639364936593669367936893699370937193729373937493759376937793789379938093819382938393849385938693879388938993909391939293939394939593969397939893999400940194029403940494059406940794089409941094119412941394149415941694179418941994209421942294239424942594269427942894299430943194329433943494359436943794389439944094419442944394449445944694479448944994509451945294539454945594569457945894599460946194629463946494659466946794689469947094719472947394749475947694779478947994809481948294839484948594869487948894899490949194929493949494959496949794989499950095019502950395049505950695079508950995109511951295139514951595169517951895199520952195229523952495259526952795289529953095319532953395349535953695379538953995409541954295439544954595469547954895499550955195529553955495559556955795589559956095619562956395649565956695679568956995709571957295739574957595769577 |
- \input texinfo.tex @c -*- texinfo -*-
- @c %**start of header
- @setfilename bashref.info
- @settitle Bash Reference Manual
- @include version.texi
- @c %**end of header
- @copying
- This text is a brief description of the features that are present in
- the Bash shell (version @value{VERSION}, @value{UPDATED}).
- This is Edition @value{EDITION}, last updated @value{UPDATED},
- of @cite{The GNU Bash Reference Manual},
- for @code{Bash}, Version @value{VERSION}.
- Copyright @copyright{} 1988--2020 Free Software Foundation, Inc.
- @quotation
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.3 or
- any later version published by the Free Software Foundation; with no
- Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
- A copy of the license is included in the section entitled
- ``GNU Free Documentation License''.
- @end quotation
- @end copying
- @defcodeindex bt
- @defcodeindex rw
- @set BashFeatures
- @dircategory Basics
- @direntry
- * Bash: (bash). The GNU Bourne-Again SHell.
- @end direntry
- @finalout
- @titlepage
- @title Bash Reference Manual
- @subtitle Reference Documentation for Bash
- @subtitle Edition @value{EDITION}, for @code{Bash} Version @value{VERSION}.
- @subtitle @value{UPDATED-MONTH}
- @author Chet Ramey, Case Western Reserve University
- @author Brian Fox, Free Software Foundation
- @page
- @vskip 0pt plus 1filll
- @insertcopying
- @end titlepage
- @contents
- @ifnottex
- @node Top, Introduction, (dir), (dir)
- @top Bash Features
- This text is a brief description of the features that are present in
- the Bash shell (version @value{VERSION}, @value{UPDATED}).
- The Bash home page is @url{http://www.gnu.org/software/bash/}.
- This is Edition @value{EDITION}, last updated @value{UPDATED},
- of @cite{The GNU Bash Reference Manual},
- for @code{Bash}, Version @value{VERSION}.
- Bash contains features that appear in other popular shells, and some
- features that only appear in Bash. Some of the shells that Bash has
- borrowed concepts from are the Bourne Shell (@file{sh}), the Korn Shell
- (@file{ksh}), and the C-shell (@file{csh} and its successor,
- @file{tcsh}). The following menu breaks the features up into
- categories, noting which features were inspired by other shells and
- which are specific to Bash.
- This manual is meant as a brief introduction to features found in
- Bash. The Bash manual page should be used as the definitive
- reference on shell behavior.
- @menu
- * Introduction:: An introduction to the shell.
- * Definitions:: Some definitions used in the rest of this
- manual.
- * Basic Shell Features:: The shell "building blocks".
- * Shell Builtin Commands:: Commands that are a part of the shell.
- * Shell Variables:: Variables used or set by Bash.
- * Bash Features:: Features found only in Bash.
- * Job Control:: What job control is and how Bash allows you
- to use it.
- * Command Line Editing:: Chapter describing the command line
- editing features.
- * Using History Interactively:: Command History Expansion
- * Installing Bash:: How to build and install Bash on your system.
- * Reporting Bugs:: How to report bugs in Bash.
- * Major Differences From The Bourne Shell:: A terse list of the differences
- between Bash and historical
- versions of /bin/sh.
- * GNU Free Documentation License:: Copying and sharing this documentation.
- * Indexes:: Various indexes for this manual.
- @end menu
- @end ifnottex
- @node Introduction
- @chapter Introduction
- @menu
- * What is Bash?:: A short description of Bash.
- * What is a shell?:: A brief introduction to shells.
- @end menu
- @node What is Bash?
- @section What is Bash?
- Bash is the shell, or command language interpreter,
- for the @sc{gnu} operating system.
- The name is an acronym for the @samp{Bourne-Again SHell},
- a pun on Stephen Bourne, the author of the direct ancestor of
- the current Unix shell @code{sh},
- which appeared in the Seventh Edition Bell Labs Research version
- of Unix.
- Bash is largely compatible with @code{sh} and incorporates useful
- features from the Korn shell @code{ksh} and the C shell @code{csh}.
- It is intended to be a conformant implementation of the @sc{ieee}
- @sc{posix} Shell and Tools portion of the @sc{ieee} @sc{posix}
- specification (@sc{ieee} Standard 1003.1).
- It offers functional improvements over @code{sh} for both interactive and
- programming use.
- While the @sc{gnu} operating system provides other shells, including
- a version of @code{csh}, Bash is the default shell.
- Like other @sc{gnu} software, Bash is quite portable. It currently runs
- on nearly every version of Unix and a few other operating systems @minus{}
- independently-supported ports exist for @sc{ms-dos}, @sc{os/2},
- and Windows platforms.
- @node What is a shell?
- @section What is a shell?
- At its base, a shell is simply a macro processor that executes
- commands. The term macro processor means functionality where text
- and symbols are expanded to create larger expressions.
- A Unix shell is both a command interpreter and a programming
- language. As a command interpreter, the shell provides the user
- interface to the rich set of @sc{gnu} utilities. The programming
- language features allow these utilities to be combined.
- Files containing commands can be created, and become
- commands themselves. These new commands have the same status as
- system commands in directories such as @file{/bin}, allowing users
- or groups to establish custom environments to automate their common
- tasks.
- Shells may be used interactively or non-interactively. In
- interactive mode, they accept input typed from the keyboard.
- When executing non-interactively, shells execute commands read
- from a file.
- A shell allows execution of @sc{gnu} commands, both synchronously and
- asynchronously.
- The shell waits for synchronous commands to complete before accepting
- more input; asynchronous commands continue to execute in parallel
- with the shell while it reads and executes additional commands.
- The @dfn{redirection} constructs permit
- fine-grained control of the input and output of those commands.
- Moreover, the shell allows control over the contents of commands'
- environments.
- Shells also provide a small set of built-in
- commands (@dfn{builtins}) implementing functionality impossible
- or inconvenient to obtain via separate utilities.
- For example, @code{cd}, @code{break}, @code{continue}, and
- @code{exec} cannot be implemented outside of the shell because
- they directly manipulate the shell itself.
- The @code{history}, @code{getopts}, @code{kill}, or @code{pwd}
- builtins, among others, could be implemented in separate utilities,
- but they are more convenient to use as builtin commands.
- All of the shell builtins are described in
- subsequent sections.
- While executing commands is essential, most of the power (and
- complexity) of shells is due to their embedded programming
- languages. Like any high-level language, the shell provides
- variables, flow control constructs, quoting, and functions.
- Shells offer features geared specifically for
- interactive use rather than to augment the programming language.
- These interactive features include job control, command line
- editing, command history and aliases. Each of these features is
- described in this manual.
- @node Definitions
- @chapter Definitions
- These definitions are used throughout the remainder of this manual.
- @table @code
- @item POSIX
- @cindex POSIX
- A family of open system standards based on Unix. Bash
- is primarily concerned with the Shell and Utilities portion of the
- @sc{posix} 1003.1 standard.
- @item blank
- A space or tab character.
- @item builtin
- @cindex builtin
- A command that is implemented internally by the shell itself, rather
- than by an executable program somewhere in the file system.
- @item control operator
- @cindex control operator
- A @code{token} that performs a control function. It is a @code{newline}
- or one of the following:
- @samp{||}, @samp{&&}, @samp{&}, @samp{;}, @samp{;;}, @samp{;&}, @samp{;;&},
- @samp{|}, @samp{|&}, @samp{(}, or @samp{)}.
- @item exit status
- @cindex exit status
- The value returned by a command to its caller. The value is restricted
- to eight bits, so the maximum value is 255.
- @item field
- @cindex field
- A unit of text that is the result of one of the shell expansions. After
- expansion, when executing a command, the resulting fields are used as
- the command name and arguments.
- @item filename
- @cindex filename
- A string of characters used to identify a file.
- @item job
- @cindex job
- A set of processes comprising a pipeline, and any processes descended
- from it, that are all in the same process group.
- @item job control
- @cindex job control
- A mechanism by which users can selectively stop (suspend) and restart
- (resume) execution of processes.
- @item metacharacter
- @cindex metacharacter
- A character that, when unquoted, separates words. A metacharacter is
- a @code{space}, @code{tab}, @code{newline}, or one of the following characters:
- @samp{|}, @samp{&}, @samp{;}, @samp{(}, @samp{)}, @samp{<}, or
- @samp{>}.
- @item name
- @cindex name
- @cindex identifier
- A @code{word} consisting solely of letters, numbers, and underscores,
- and beginning with a letter or underscore. @code{Name}s are used as
- shell variable and function names.
- Also referred to as an @code{identifier}.
- @item operator
- @cindex operator, shell
- A @code{control operator} or a @code{redirection operator}.
- @xref{Redirections}, for a list of redirection operators.
- Operators contain at least one unquoted @code{metacharacter}.
- @item process group
- @cindex process group
- A collection of related processes each having the same process
- group @sc{id}.
- @item process group ID
- @cindex process group ID
- A unique identifier that represents a @code{process group}
- during its lifetime.
- @item reserved word
- @cindex reserved word
- A @code{word} that has a special meaning to the shell. Most reserved
- words introduce shell flow control constructs, such as @code{for} and
- @code{while}.
- @item return status
- @cindex return status
- A synonym for @code{exit status}.
- @item signal
- @cindex signal
- A mechanism by which a process may be notified by the kernel
- of an event occurring in the system.
- @item special builtin
- @cindex special builtin
- A shell builtin command that has been classified as special by the
- @sc{posix} standard.
- @item token
- @cindex token
- A sequence of characters considered a single unit by the shell.
- It is either a @code{word} or an @code{operator}.
- @item word
- @cindex word
- A sequence of characters treated as a unit by the shell.
- Words may not include unquoted @code{metacharacters}.
- @end table
- @node Basic Shell Features
- @chapter Basic Shell Features
- @cindex Bourne shell
- Bash is an acronym for @samp{Bourne-Again SHell}.
- The Bourne shell is
- the traditional Unix shell originally written by Stephen Bourne.
- All of the Bourne shell builtin commands are available in Bash,
- The rules for evaluation and quoting are taken from the @sc{posix}
- specification for the `standard' Unix shell.
- This chapter briefly summarizes the shell's `building blocks':
- commands, control structures, shell functions, shell @i{parameters},
- shell expansions,
- @i{redirections}, which are a way to direct input and output from
- and to named files, and how the shell executes commands.
- @menu
- * Shell Syntax:: What your input means to the shell.
- * Shell Commands:: The types of commands you can use.
- * Shell Functions:: Grouping commands by name.
- * Shell Parameters:: How the shell stores values.
- * Shell Expansions:: How Bash expands parameters and the various
- expansions available.
- * Redirections:: A way to control where input and output go.
- * Executing Commands:: What happens when you run a command.
- * Shell Scripts:: Executing files of shell commands.
- @end menu
- @node Shell Syntax
- @section Shell Syntax
- @menu
- * Shell Operation:: The basic operation of the shell.
- * Quoting:: How to remove the special meaning from characters.
- * Comments:: How to specify comments.
- @end menu
- When the shell reads input, it proceeds through a
- sequence of operations. If the input indicates the beginning of a
- comment, the shell ignores the comment symbol (@samp{#}), and the rest
- of that line.
-
- Otherwise, roughly speaking, the shell reads its input and
- divides the input into words and operators, employing the quoting rules
- to select which meanings to assign various words and characters.
- The shell then parses these tokens into commands and other constructs,
- removes the special meaning of certain words or characters, expands
- others, redirects input and output as needed, executes the specified
- command, waits for the command's exit status, and makes that exit status
- available for further inspection or processing.
- @node Shell Operation
- @subsection Shell Operation
- The following is a brief description of the shell's operation when it
- reads and executes a command. Basically, the shell does the
- following:
- @enumerate
- @item
- Reads its input from a file (@pxref{Shell Scripts}), from a string
- supplied as an argument to the @option{-c} invocation option
- (@pxref{Invoking Bash}), or from the user's terminal.
- @item
- Breaks the input into words and operators, obeying the quoting rules
- described in @ref{Quoting}. These tokens are separated by
- @code{metacharacters}. Alias expansion is performed by this step
- (@pxref{Aliases}).
- @item
- Parses the tokens into simple and compound commands
- (@pxref{Shell Commands}).
- @item
- Performs the various shell expansions (@pxref{Shell Expansions}), breaking
- the expanded tokens into lists of filenames (@pxref{Filename Expansion})
- and commands and arguments.
- @item
- Performs any necessary redirections (@pxref{Redirections}) and removes
- the redirection operators and their operands from the argument list.
- @item
- Executes the command (@pxref{Executing Commands}).
- @item
- Optionally waits for the command to complete and collects its exit
- status (@pxref{Exit Status}).
- @end enumerate
- @node Quoting
- @subsection Quoting
- @cindex quoting
- @menu
- * Escape Character:: How to remove the special meaning from a single
- character.
- * Single Quotes:: How to inhibit all interpretation of a sequence
- of characters.
- * Double Quotes:: How to suppress most of the interpretation of a
- sequence of characters.
- * ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings.
- * Locale Translation:: How to translate strings into different languages.
- @end menu
- Quoting 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.
- Each of the shell metacharacters (@pxref{Definitions})
- has special meaning to the shell and must be quoted if it is to
- represent itself.
- When the command history expansion facilities are being used
- (@pxref{History Interaction}), the
- @var{history expansion} character, usually @samp{!}, must be quoted
- to prevent history expansion. @xref{Bash History Facilities}, for
- more details concerning history expansion.
- There are three quoting mechanisms: the
- @var{escape character}, single quotes, and double quotes.
- @node Escape Character
- @subsubsection Escape Character
- A non-quoted backslash @samp{\} is the Bash escape character.
- It preserves the literal value of the next character that follows,
- with the exception of @code{newline}. If a @code{\newline} pair
- appears, and the backslash itself is not quoted, the @code{\newline}
- is treated as a line continuation (that is, it is removed from
- the input stream and effectively ignored).
- @node Single Quotes
- @subsubsection Single Quotes
- Enclosing characters in single quotes (@samp{'}) 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.
- @node Double Quotes
- @subsubsection Double Quotes
- Enclosing characters in double quotes (@samp{"}) preserves the literal value
- of all characters within the quotes, with the exception of
- @samp{$}, @samp{`}, @samp{\},
- and, when history expansion is enabled, @samp{!}.
- When the shell is in
- @sc{posix} mode (@pxref{Bash POSIX Mode}),
- the @samp{!} has no special meaning
- within double quotes, even when history expansion is enabled.
- The characters @samp{$} and @samp{`}
- retain their special meaning within double quotes (@pxref{Shell Expansions}).
- The backslash retains its special meaning only when followed by one of
- the following characters:
- @samp{$}, @samp{`}, @samp{"}, @samp{\}, or @code{newline}.
- Within double quotes, backslashes that are followed by one of these
- characters are removed. Backslashes preceding characters without a
- special meaning are left unmodified.
- A double quote may be quoted within double quotes by preceding it with
- a backslash.
- If enabled, history expansion will be performed unless an @samp{!}
- appearing in double quotes is escaped using a backslash.
- The backslash preceding the @samp{!} is not removed.
- The special parameters @samp{*} and @samp{@@} have special meaning
- when in double quotes (@pxref{Shell Parameter Expansion}).
- @node ANSI-C Quoting
- @subsubsection ANSI-C Quoting
- @cindex quoting, ANSI
- Words of the form @code{$'@var{string}'} are treated specially. The
- word expands to @var{string}, with backslash-escaped characters replaced
- as specified by the ANSI C standard. Backslash escape sequences, if
- present, are decoded as follows:
- @table @code
- @item \a
- alert (bell)
- @item \b
- backspace
- @item \e
- @itemx \E
- an escape character (not ANSI C)
- @item \f
- form feed
- @item \n
- newline
- @item \r
- carriage return
- @item \t
- horizontal tab
- @item \v
- vertical tab
- @item \\
- backslash
- @item \'
- single quote
- @item \"
- double quote
- @item \?
- question mark
- @item \@var{nnn}
- the eight-bit character whose value is the octal value @var{nnn}
- (one to three octal digits)
- @item \x@var{HH}
- the eight-bit character whose value is the hexadecimal value @var{HH}
- (one or two hex digits)
- @item \u@var{HHHH}
- the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
- @var{HHHH} (one to four hex digits)
- @item \U@var{HHHHHHHH}
- the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
- @var{HHHHHHHH} (one to eight hex digits)
- @item \c@var{x}
- a control-@var{x} character
- @end table
- @noindent
- The expanded result is single-quoted, as if the dollar sign had not
- been present.
- @node Locale Translation
- @subsubsection Locale-Specific Translation
- @cindex localization
- @cindex internationalization
- @cindex native languages
- @cindex translation, native languages
- A double-quoted string preceded by a dollar sign (@samp{$})
- will cause the string to be translated according to the current locale.
- The @var{gettext} infrastructure performs the message catalog lookup and
- translation, using the @code{LC_MESSAGES} and @code{TEXTDOMAIN} shell
- variables, as explained below. See the gettext documentation for additional
- details.
- If the current locale is @code{C} or @code{POSIX},
- or if there are no translations available,
- the dollar sign is ignored.
- If the string is translated and replaced, the replacement is
- double-quoted.
- @vindex LC_MESSAGES
- @vindex TEXTDOMAIN
- @vindex TEXTDOMAINDIR
- Some systems use the message catalog selected by the @env{LC_MESSAGES}
- shell variable. Others create the name of the message catalog from the
- value of the @env{TEXTDOMAIN} shell variable, possibly adding a
- suffix of @samp{.mo}. If you use the @env{TEXTDOMAIN} variable, you
- may need to set the @env{TEXTDOMAINDIR} variable to the location of
- the message catalog files. Still others use both variables in this
- fashion:
- @env{TEXTDOMAINDIR}/@env{LC_MESSAGES}/LC_MESSAGES/@env{TEXTDOMAIN}.mo.
- @node Comments
- @subsection Comments
- @cindex comments, shell
- In a non-interactive shell, or an interactive shell in which the
- @code{interactive_comments} option to the @code{shopt}
- builtin is enabled (@pxref{The Shopt Builtin}),
- a word beginning with @samp{#}
- causes that word and all remaining characters on that line to
- be ignored. An interactive shell without the @code{interactive_comments}
- option enabled does not allow comments. The @code{interactive_comments}
- option is on by default in interactive shells.
- @xref{Interactive Shells}, for a description of what makes
- a shell interactive.
- @node Shell Commands
- @section Shell Commands
- @cindex commands, shell
- A simple shell command such as @code{echo a b c} consists of the command
- itself followed by arguments, separated by spaces.
- More complex shell commands are composed of simple commands arranged together
- in a variety of ways: in a pipeline in which the output of one command
- becomes the input of a second, in a loop or conditional construct, or in
- some other grouping.
- @menu
- * Reserved Words:: Words that have special meaning to the shell.
- * Simple Commands:: The most common type of command.
- * Pipelines:: Connecting the input and output of several
- commands.
- * Lists:: How to execute commands sequentially.
- * Compound Commands:: Shell commands for control flow.
- * Coprocesses:: Two-way communication between commands.
- * GNU Parallel:: Running commands in parallel.
- @end menu
- @node Reserved Words
- @subsection Reserved Words
- @cindex reserved words
- Reserved words are words that have special meaning to the shell.
- They are used to begin and end the shell's compound commands.
- The following words are recognized as reserved when unquoted and
- the first word of a command (see below for exceptions):
- @multitable @columnfractions .1 .1 .1 .1 .12 .1
- @item @code{if} @tab @code{then} @tab @code{elif}
- @tab @code{else} @tab @code{fi} @tab @code{time}
- @item @code{for} @tab @code{in} @tab @code{until}
- @tab @code{while} @tab @code{do} @tab @code{done}
- @item @code{case} @tab @code{esac} @tab @code{coproc}
- @tab @code{select} @tab @code{function}
- @item @code{@{} @tab @code{@}} @tab @code{[[} @tab @code{]]} @tab @code{!}
- @end multitable
- @noindent
- @code{in} is recognized as a reserved word if it is the third word of a
- @code{case} or @code{select} command.
- @code{in} and @code{do} are recognized as reserved
- words if they are the third word in a @code{for} command.
- @node Simple Commands
- @subsection Simple Commands
- @cindex commands, simple
- A simple command is the kind of command encountered most often.
- It's just a sequence of words separated by @code{blank}s, terminated
- by one of the shell's control operators (@pxref{Definitions}). The
- first word generally specifies a command to be executed, with the
- rest of the words being that command's arguments.
- The return status (@pxref{Exit Status}) of a simple command is
- its exit status as provided
- by the @sc{posix} 1003.1 @code{waitpid} function, or 128+@var{n} if
- the command was terminated by signal @var{n}.
- @node Pipelines
- @subsection Pipelines
- @cindex pipeline
- @cindex commands, pipelines
- A @code{pipeline} is a sequence of one or more commands separated by
- one of the control operators @samp{|} or @samp{|&}.
- @rwindex time
- @rwindex !
- @cindex command timing
- The format for a pipeline is
- @example
- [time [-p]] [!] @var{command1} [ | or |& @var{command2} ] @dots{}
- @end example
- @noindent
- The output of each command in the pipeline is connected via a pipe
- to the input of the next command.
- That is, each command reads the previous command's output. This
- connection is performed before any redirections specified by the
- command.
- If @samp{|&} is used, @var{command1}'s standard error, in addition to
- its standard output, is connected to
- @var{command2}'s standard input through the pipe;
- it is shorthand for @code{2>&1 |}.
- This implicit redirection of the standard error to the standard output is
- performed after any redirections specified by the command.
- The reserved word @code{time} causes timing statistics
- to be printed for the pipeline once it finishes.
- The statistics currently consist of elapsed (wall-clock) time and
- user and system time consumed by the command's execution.
- The @option{-p} option changes the output format to that specified
- by @sc{posix}.
- When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}),
- it does not recognize @code{time} as a reserved word if the next
- token begins with a @samp{-}.
- The @env{TIMEFORMAT} variable may be set to a format string that
- specifies how the timing information should be displayed.
- @xref{Bash Variables}, for a description of the available formats.
- The use of @code{time} as a reserved word permits the timing of
- shell builtins, shell functions, and pipelines. An external
- @code{time} command cannot time these easily.
- When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}), @code{time}
- 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 @env{TIMEFORMAT} variable may be used to specify the format of
- the time information.
- If the pipeline is not executed asynchronously (@pxref{Lists}), the
- shell waits for all commands in the pipeline to complete.
- Each command in a pipeline is executed in its own subshell, which is a
- separate process (@pxref{Command Execution Environment}).
- If the @code{lastpipe} option is enabled using the @code{shopt} builtin
- (@pxref{The Shopt Builtin}),
- the last element of a pipeline may be run by the shell process.
- The exit
- status of a pipeline is the exit status of the last command in the
- pipeline, unless the @code{pipefail} option is enabled
- (@pxref{The Set Builtin}).
- If @code{pipefail} 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 @samp{!} precedes the pipeline, the
- exit status 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.
- @node Lists
- @subsection Lists of Commands
- @cindex commands, lists
- A @code{list} is a sequence of one or more pipelines separated by one
- of the operators @samp{;}, @samp{&}, @samp{&&}, or @samp{||},
- and optionally terminated by one of @samp{;}, @samp{&}, or a
- @code{newline}.
- Of these list operators, @samp{&&} and @samp{||}
- have equal precedence, followed by @samp{;} and @samp{&},
- which have equal precedence.
- A sequence of one or more newlines may appear in a @code{list}
- to delimit commands, equivalent to a semicolon.
- If a command is terminated by the control operator @samp{&},
- the shell executes the command asynchronously in a subshell.
- This is known as executing the command in the @var{background},
- and these are referred to as @var{asynchronous} commands.
- The shell does not wait for the command to finish, and the return
- status is 0 (true).
- When job control is not active (@pxref{Job Control}),
- the standard input for asynchronous commands, in the absence of any
- explicit redirections, is redirected from @code{/dev/null}.
- Commands separated by a @samp{;} 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.
- @sc{and} and @sc{or} lists are sequences of one or more pipelines
- separated by the control operators @samp{&&} and @samp{||},
- respectively. @sc{and} and @sc{or} lists are executed with left
- associativity.
- An @sc{and} list has the form
- @example
- @var{command1} && @var{command2}
- @end example
- @noindent
- @var{command2} is executed if, and only if, @var{command1}
- returns an exit status of zero (success).
- An @sc{or} list has the form
- @example
- @var{command1} || @var{command2}
- @end example
- @noindent
- @var{command2} is executed if, and only if, @var{command1}
- returns a non-zero exit status.
- The return status of
- @sc{and} and @sc{or} lists is the exit status of the last command
- executed in the list.
- @node Compound Commands
- @subsection Compound Commands
- @cindex commands, compound
- @menu
- * Looping Constructs:: Shell commands for iterative action.
- * Conditional Constructs:: Shell commands for conditional execution.
- * Command Grouping:: Ways to group commands.
- @end menu
- Compound commands are the shell programming language constructs.
- Each construct begins with a reserved word or control operator and is
- terminated by a corresponding reserved word or operator.
- Any redirections (@pxref{Redirections}) associated with a compound command
- apply to all commands within that compound command unless explicitly overridden.
- In most cases a list of commands in a compound 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.
- Bash provides looping constructs, conditional commands, and mechanisms
- to group commands and execute them as a unit.
- @node Looping Constructs
- @subsubsection Looping Constructs
- @cindex commands, looping
- Bash supports the following looping constructs.
- Note that wherever a @samp{;} appears in the description of a
- command's syntax, it may be replaced with one or more newlines.
- @table @code
- @item until
- @rwindex until
- @rwindex do
- @rwindex done
- The syntax of the @code{until} command is:
- @example
- until @var{test-commands}; do @var{consequent-commands}; done
- @end example
- Execute @var{consequent-commands} as long as
- @var{test-commands} has an exit status which is not zero.
- The return status is the exit status of the last command executed
- in @var{consequent-commands}, or zero if none was executed.
- @item while
- @rwindex while
- The syntax of the @code{while} command is:
- @example
- while @var{test-commands}; do @var{consequent-commands}; done
- @end example
- Execute @var{consequent-commands} as long as
- @var{test-commands} has an exit status of zero.
- The return status is the exit status of the last command executed
- in @var{consequent-commands}, or zero if none was executed.
- @item for
- @rwindex for
- The syntax of the @code{for} command is:
- @example
- for @var{name} [ [in [@var{words} @dots{}] ] ; ] do @var{commands}; done
- @end example
- Expand @var{words} (@pxref{Shell Expansions}), and execute @var{commands}
- once for each member
- in the resultant list, with @var{name} bound to the current member.
- If @samp{in @var{words}} is not present, the @code{for} command
- executes the @var{commands} once for each positional parameter that is
- set, as if @samp{in "$@@"} had been specified
- (@pxref{Special Parameters}).
- The return status is the exit status of the last command that executes.
- If there are no items in the expansion of @var{words}, no commands are
- executed, and the return status is zero.
- An alternate form of the @code{for} command is also supported:
- @example
- for (( @var{expr1} ; @var{expr2} ; @var{expr3} )) ; do @var{commands} ; done
- @end example
- First, the arithmetic expression @var{expr1} is evaluated according
- to the rules described below (@pxref{Shell Arithmetic}).
- The arithmetic expression @var{expr2} is then evaluated repeatedly
- until it evaluates to zero.
- Each time @var{expr2} evaluates to a non-zero value, @var{commands} are
- executed and the arithmetic expression @var{expr3} 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 @var{commands}
- that is executed, or false if any of the expressions is invalid.
- @end table
- The @code{break} and @code{continue} builtins (@pxref{Bourne Shell Builtins})
- may be used to control loop execution.
- @node Conditional Constructs
- @subsubsection Conditional Constructs
- @cindex commands, conditional
- @table @code
- @item if
- @rwindex if
- @rwindex then
- @rwindex else
- @rwindex elif
- @rwindex fi
- The syntax of the @code{if} command is:
- @example
- if @var{test-commands}; then
- @var{consequent-commands};
- [elif @var{more-test-commands}; then
- @var{more-consequents};]
- [else @var{alternate-consequents};]
- fi
- @end example
- The @var{test-commands} list is executed, and if its return status is zero,
- the @var{consequent-commands} list is executed.
- If @var{test-commands} returns a non-zero status, each @code{elif} list
- is executed in turn, and if its exit status is zero,
- the corresponding @var{more-consequents} is executed and the
- command completes.
- If @samp{else @var{alternate-consequents}} is present, and
- the final command in the final @code{if} or @code{elif} clause
- has a non-zero exit status, then @var{alternate-consequents} is executed.
- The return status is the exit status of the last command executed, or
- zero if no condition tested true.
- @item case
- @rwindex case
- @rwindex in
- @rwindex esac
- The syntax of the @code{case} command is:
- @example
- case @var{word} in
- [ [(] @var{pattern} [| @var{pattern}]@dots{}) @var{command-list} ;;]@dots{}
- esac
- @end example
- @code{case} will selectively execute the @var{command-list} corresponding to
- the first @var{pattern} that matches @var{word}.
- The match is performed according
- to the rules described below in @ref{Pattern Matching}.
- If the @code{nocasematch} shell option
- (see the description of @code{shopt} in @ref{The Shopt Builtin})
- is enabled, the match is performed without regard to the case
- of alphabetic characters.
- The @samp{|} is used to separate multiple patterns, and the @samp{)}
- operator terminates a pattern list.
- A list of patterns and an associated command-list is known
- as a @var{clause}.
- Each clause must be terminated with @samp{;;}, @samp{;&}, or @samp{;;&}.
- The @var{word} undergoes tilde expansion, parameter expansion, command
- substitution, arithmetic expansion, and quote removal
- (@pxref{Shell Parameter Expansion})
- before matching is
- attempted. Each @var{pattern} undergoes tilde expansion, parameter
- expansion, command substitution, and arithmetic expansion.
- There may be an arbitrary number of @code{case} clauses, each terminated
- by a @samp{;;}, @samp{;&}, or @samp{;;&}.
- The first pattern that matches determines the
- command-list that is executed.
- It's a common idiom to use @samp{*} as the final pattern to define the
- default case, since that pattern will always match.
- Here is an example using @code{case} in a script that could be used to
- describe one interesting feature of an animal:
- @example
- echo -n "Enter the name of an animal: "
- read ANIMAL
- echo -n "The $ANIMAL has "
- case $ANIMAL in
- horse | dog | cat) echo -n "four";;
- man | kangaroo ) echo -n "two";;
- *) echo -n "an unknown number of";;
- esac
- echo " legs."
- @end example
- @noindent
- If the @samp{;;} operator is used, no subsequent matches are attempted after
- the first pattern match.
- Using @samp{;&} in place of @samp{;;} causes execution to continue with
- the @var{command-list} associated with the next clause, if any.
- Using @samp{;;&} in place of @samp{;;} causes the shell to test the patterns
- in the next clause, if any, and execute any associated @var{command-list}
- on a successful match,
- continuing the case statement execution as if the pattern list had not matched.
- The return status is zero if no @var{pattern} is matched. Otherwise, the
- return status is the exit status of the @var{command-list} executed.
- @item select
- @rwindex select
- The @code{select} construct allows the easy generation of menus.
- It has almost the same syntax as the @code{for} command:
- @example
- select @var{name} [in @var{words} @dots{}]; do @var{commands}; done
- @end example
- The list of words following @code{in} is expanded, generating a list
- of items. The set of expanded words is printed on the standard
- error output stream, each preceded by a number. If the
- @samp{in @var{words}} is omitted, the positional parameters are printed,
- as if @samp{in "$@@"} had been specified.
- The @env{PS3} prompt is then displayed and a line is read from the
- standard input.
- If the line consists of a number corresponding to one of the displayed
- words, then the value of @var{name} is set to that word.
- If the line is empty, the words and prompt are displayed again.
- If @code{EOF} is read, the @code{select} command completes.
- Any other value read causes @var{name} to be set to null.
- The line read is saved in the variable @env{REPLY}.
- The @var{commands} are executed after each selection until a
- @code{break} command is executed, at which
- point the @code{select} command completes.
- Here is an example that allows the user to pick a filename from the
- current directory, and displays the name and index of the file
- selected.
- @example
- select fname in *;
- do
- echo you picked $fname \($REPLY\)
- break;
- done
- @end example
- @item ((@dots{}))
- @example
- (( @var{expression} ))
- @end example
- The arithmetic @var{expression} is evaluated according to the rules
- described below (@pxref{Shell Arithmetic}).
- 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
- @example
- let "@var{expression}"
- @end example
- @noindent
- @xref{Bash Builtins}, for a full description of the @code{let} builtin.
- @item [[@dots{}]]
- @rwindex [[
- @rwindex ]]
- @example
- [[ @var{expression} ]]
- @end example
- Return a status of 0 or 1 depending on the evaluation of
- the conditional expression @var{expression}.
- Expressions are composed of the primaries described below in
- @ref{Bash Conditional Expressions}.
- Word splitting and filename expansion are not performed on the words
- between the @code{[[} and @code{]]}; tilde expansion, parameter and
- variable expansion, arithmetic expansion, command substitution, process
- substitution, and quote removal are performed.
- Conditional operators such as @samp{-f} must be unquoted to be recognized
- as primaries.
- When used with @code{[[}, the @samp{<} and @samp{>} operators sort
- lexicographically using the current locale.
- When the @samp{==} and @samp{!=} operators are used, the string to the
- right of the operator is considered a pattern and matched according
- to the rules described below in @ref{Pattern Matching},
- as if the @code{extglob} shell option were enabled.
- The @samp{=} operator is identical to @samp{==}.
- If the @code{nocasematch} shell option
- (see the description of @code{shopt} in @ref{The Shopt Builtin})
- is enabled, the match is performed without regard to the case
- of alphabetic characters.
- The return value is 0 if the string matches (@samp{==}) or does not
- match (@samp{!=}) the pattern, and 1 otherwise.
- Any part of the pattern may be quoted to force the quoted portion
- to be matched as a string.
- An additional binary operator, @samp{=~}, is available, with the same
- precedence as @samp{==} and @samp{!=}.
- When it is used, the string to the right of the operator is considered
- a @sc{posix} extended regular expression and matched accordingly
- (using the @sc{posix} @code{regcomp} and @code{regexec} interfaces
- usually described in @i{regex}(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 @code{nocasematch} shell option
- (see the description of @code{shopt} in @ref{The Shopt Builtin})
- 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.
- The pattern will match if it matches any part of the string.
- Anchor the pattern using the @samp{^} and @samp{$} regular expression
- operators to force it to match the entire string.
- The array variable @code{BASH_REMATCH} records which parts of the string
- matched the pattern.
- The element of @code{BASH_REMATCH} with index 0 contains the portion of
- the string matching the entire regular expression.
- Substrings matched by parenthesized subexpressions within the regular
- expression are saved in the remaining @code{BASH_REMATCH} indices.
- The element of @code{BASH_REMATCH} with index @var{n} is the portion of the
- string matching the @var{n}th parenthesized subexpression.
- For example, the following will match a line
- (stored in the shell variable @var{line})
- if there is a sequence of characters anywhere in the value consisting of
- any number, including zero, of
- characters in the @code{space} character class,
- zero or one instances of @samp{a}, then a @samp{b}:
- @example
- [[ $line =~ [[:space:]]*(a)?b ]]
- @end example
- @noindent
- That means values like @samp{aab} and @samp{ aaaaaab} will match, as
- will a line containing a @samp{b} anywhere in its value.
- Storing the regular expression in a shell variable is often a useful
- way to avoid problems with quoting characters that are special to the
- shell.
- It is sometimes difficult to specify a regular expression literally
- without using quotes, or to keep track of the quoting used by regular
- expressions while paying attention to the shell's quote removal.
- Using a shell variable to store the pattern decreases these problems.
- For example, the following is equivalent to the above:
- @example
- pattern='[[:space:]]*(a)?b'
- [[ $line =~ $pattern ]]
- @end example
- @noindent
- If you want to match a character that's special to the regular expression
- grammar, it has to be quoted to remove its special meaning.
- This means that in the pattern @samp{xxx.txt}, the @samp{.} matches any
- character in the string (its usual regular expression meaning), but in the
- pattern @samp{"xxx.txt"} it can only match a literal @samp{.}.
- Shell programmers should take special care with backslashes, since backslashes
- are used both by the shell and regular expressions to remove the special
- meaning from the following character.
- The following two sets of commands are @emph{not} equivalent:
- @example
- pattern='\.'
- [[ . =~ $pattern ]]
- [[ . =~ \. ]]
- [[ . =~ "$pattern" ]]
- [[ . =~ '\.' ]]
- @end example
- @noindent
- The first two matches will succeed, but the second two will not, because
- in the second two the backslash will be part of the pattern to be matched.
- In the first two examples, the backslash removes the special meaning from
- @samp{.}, so the literal @samp{.} matches.
- If the string in the first examples were anything other than @samp{.}, say
- @samp{a}, the pattern would not match, because the quoted @samp{.} in the
- pattern loses its special meaning of matching any single character.
- Expressions may be combined using the following operators, listed
- in decreasing order of precedence:
- @table @code
- @item ( @var{expression} )
- Returns the value of @var{expression}.
- This may be used to override the normal precedence of operators.
- @item ! @var{expression}
- True if @var{expression} is false.
- @item @var{expression1} && @var{expression2}
- True if both @var{expression1} and @var{expression2} are true.
- @item @var{expression1} || @var{expression2}
- True if either @var{expression1} or @var{expression2} is true.
- @end table
- @noindent
- The @code{&&} and @code{||} operators do not evaluate @var{expression2} if the
- value of @var{expression1} is sufficient to determine the return
- value of the entire conditional expression.
- @end table
- @node Command Grouping
- @subsubsection Grouping Commands
- @cindex commands, grouping
- Bash provides two ways to group a list of commands to be executed
- as a unit. When commands are grouped, redirections may be applied
- to the entire command list. For example, the output of all the
- commands in the list may be redirected to a single stream.
- @table @code
- @item ()
- @example
- ( @var{list} )
- @end example
- Placing a list of commands between parentheses causes a subshell
- environment to be created (@pxref{Command Execution Environment}), and each
- of the commands in @var{list} to be executed in that subshell. Since the
- @var{list} is executed in a subshell, variable assignments do not remain in
- effect after the subshell completes.
- @item @{@}
- @rwindex @{
- @rwindex @}
- @example
- @{ @var{list}; @}
- @end example
- Placing a list of commands between curly braces causes the list to
- be executed in the current shell context. No subshell is created.
- The semicolon (or newline) following @var{list} is required.
- @end table
- In addition to the creation of a subshell, there is a subtle difference
- between these two constructs due to historical reasons. The braces
- are @code{reserved words}, so they must be separated from the @var{list}
- by @code{blank}s or other shell metacharacters.
- The parentheses are @code{operators}, and are
- recognized as separate tokens by the shell even if they are not separated
- from the @var{list} by whitespace.
- The exit status of both of these constructs is the exit status of
- @var{list}.
- @node Coprocesses
- @subsection Coprocesses
- @cindex coprocess
- A @code{coprocess} is a shell command preceded by the @code{coproc}
- reserved word.
- A coprocess is executed asynchronously in a subshell, as if the command
- had been terminated with the @samp{&} control operator, with a two-way pipe
- established between the executing shell and the coprocess.
- The format for a coprocess is:
- @example
- coproc [@var{NAME}] @var{command} [@var{redirections}]
- @end example
- @noindent
- This creates a coprocess named @var{NAME}.
- If @var{NAME} is not supplied, the default name is @var{COPROC}.
- @var{NAME} must not be supplied if @var{command} is a simple
- command (@pxref{Simple Commands}); otherwise, it is interpreted as
- the first word of the simple command.
- When the coprocess is executed, the shell creates an array variable
- (@pxref{Arrays})
- named @env{NAME} in the context of the executing shell.
- The standard output of @var{command}
- is connected via a pipe to a file descriptor in the executing shell,
- and that file descriptor is assigned to @env{NAME}[0].
- The standard input of @var{command}
- is connected via a pipe to a file descriptor in the executing shell,
- and that file descriptor is assigned to @env{NAME}[1].
- This pipe is established before any redirections specified by the
- command (@pxref{Redirections}).
- The file descriptors can be utilized as arguments to shell commands
- and redirections using standard word expansions.
- Other than those created to execute command and process substitutions,
- 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 @env{NAME}_PID.
- The @code{wait}
- builtin command may be used to wait for the coprocess to terminate.
- Since the coprocess is created as an asynchronous command,
- the @code{coproc} command always returns success.
- The return status of a coprocess is the exit status of @var{command}.
- @node GNU Parallel
- @subsection GNU Parallel
- There are ways to run commands in parallel that are not built into Bash.
- GNU Parallel is a tool to do just that.
- GNU Parallel, as its name suggests, can be used to build and run commands
- in parallel. You may run the same command with different arguments, whether
- they are filenames, usernames, hostnames, or lines read from files. GNU
- Parallel provides shorthand references to many of the most common operations
- (input lines, various portions of the input line, different ways to specify
- the input source, and so on). Parallel can replace @code{xargs} or feed
- commands from its input sources to several different instances of Bash.
- For a complete description, refer to the GNU Parallel documentation. A few
- examples should provide a brief introduction to its use.
- For example, it is easy to replace @code{xargs} to gzip all html files in the
- current directory and its subdirectories:
- @example
- find . -type f -name '*.html' -print | parallel gzip
- @end example
- @noindent
- If you need to protect special characters such as newlines in file names,
- use find's @option{-print0} option and parallel's @option{-0} option.
- You can use Parallel to move files from the current directory when the
- number of files is too large to process with one @code{mv} invocation:
- @example
- printf '%s\n' * | parallel mv @{@} destdir
- @end example
- As you can see, the @{@} is replaced with each line read from standard input.
- While using @code{ls} will work in most instances, it is not sufficient to
- deal with all filenames. @code{printf} is a shell builtin, and therefore is
- not subject to the kernel's limit on the number of arguments to a program,
- so you can use @samp{*} (but see below about the @code{dotglob} shell option).
- If you need to accommodate special characters in filenames, you can use
- @example
- printf '%s\0' * | parallel -0 mv @{@} destdir
- @end example
- @noindent
- as alluded to above.
- This will run as many @code{mv} commands as there are files in the current
- directory.
- You can emulate a parallel @code{xargs} by adding the @option{-X} option:
- @example
- printf '%s\0' * | parallel -0 -X mv @{@} destdir
- @end example
- (You may have to modify the pattern if you have the @code{dotglob} option
- enabled.)
- GNU Parallel can replace certain common idioms that operate on lines read
- from a file (in this case, filenames listed one per line):
- @example
- while IFS= read -r x; do
- do-something1 "$x" "config-$x"
- do-something2 < "$x"
- done < file | process-output
- @end example
- @noindent
- with a more compact syntax reminiscent of lambdas:
- @example
- cat list | parallel "do-something1 @{@} config-@{@} ; do-something2 < @{@}" |
- process-output
- @end example
- Parallel provides a built-in mechanism to remove filename extensions, which
- lends itself to batch file transformations or renaming:
- @example
- ls *.gz | parallel -j+0 "zcat @{@} | bzip2 >@{.@}.bz2 && rm @{@}"
- @end example
- @noindent
- This will recompress all files in the current directory with names ending
- in .gz using bzip2, running one job per CPU (-j+0) in parallel.
- (We use @code{ls} for brevity here; using @code{find} as above is more
- robust in the face of filenames containing unexpected characters.)
- Parallel can take arguments from the command line; the above can also be
- written as
- @example
- parallel "zcat @{@} | bzip2 >@{.@}.bz2 && rm @{@}" ::: *.gz
- @end example
- If a command generates output, you may want to preserve the input order in
- the output. For instance, the following command
- @example
- @{
- echo foss.org.my ;
- echo debian.org ;
- echo freenetproject.org ;
- @} | parallel traceroute
- @end example
- @noindent
- will display as output the traceroute invocation that finishes first.
- Adding the @option{-k} option
- @example
- @{
- echo foss.org.my ;
- echo debian.org ;
- echo freenetproject.org ;
- @} | parallel -k traceroute
- @end example
- @noindent
- will ensure that the output of @code{traceroute foss.org.my} is displayed first.
- Finally, Parallel can be used to run a sequence of shell commands in parallel,
- similar to @samp{cat file | bash}.
- It is not uncommon to take a list of filenames, create a series of shell
- commands to operate on them, and feed that list of commands to a shell.
- Parallel can speed this up. Assuming that @file{file} contains a list of
- shell commands, one per line,
- @example
- parallel -j 10 < file
- @end example
- @noindent
- will evaluate the commands using the shell (since no explicit command is
- supplied as an argument), in blocks of ten shell jobs at a time.
- @node Shell Functions
- @section Shell Functions
- @cindex shell function
- @cindex functions, shell
- Shell functions are a way to group commands for later execution
- using a single name for the group. They are executed just like
- a "regular" command.
- 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.
- Shell functions are executed in the current
- shell context; no new process is created to interpret them.
- Functions are declared using this syntax:
- @rwindex function
- @example
- @var{fname} () @var{compound-command} [ @var{redirections} ]
- @end example
- or
- @example
- function @var{fname} [()] @var{compound-command} [ @var{redirections} ]
- @end example
- This defines a shell function named @var{fname}. The reserved
- word @code{function} is optional.
- If the @code{function} reserved
- word is supplied, the parentheses are optional.
- The @var{body} of the function is the compound command
- @var{compound-command} (@pxref{Compound Commands}).
- That command is usually a @var{list} enclosed between @{ and @}, but
- may be any compound command listed above,
- with one exception: If the @code{function} reserved word is used, but the
- parentheses are not supplied, the braces are required.
- @var{compound-command} is executed whenever @var{fname} is specified as the
- name of a command.
- When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}),
- @var{fname} must be a valid shell @var{name} and
- may not be the same as one of the special builtins
- (@pxref{Special Builtins}).
- In default mode, a function name can be any unquoted shell word that does
- not contain @samp{$}.
- Any redirections (@pxref{Redirections}) associated with the shell function
- are performed when the function is executed.
- A function definition may be deleted using the @option{-f} option to the
- @code{unset} builtin (@pxref{Bourne Shell Builtins}).
- 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.
- Note that for historical reasons, in the most common usage the curly braces
- that surround the body of the function must be separated from the body by
- @code{blank}s or newlines.
- This is because the braces are reserved words and are only recognized
- as such when they are separated from the command list
- by whitespace or another shell metacharacter.
- Also, when using the braces, the @var{list} must be terminated by a semicolon,
- a @samp{&}, or a newline.
- When a function is executed, the arguments to the
- function become the positional parameters
- during its execution (@pxref{Positional Parameters}).
- The special parameter @samp{#} that expands to the number of
- positional parameters is updated to reflect the change.
- Special parameter @code{0} is unchanged.
- The first element of the @env{FUNCNAME} variable is set to the
- name of the function while the function is executing.
- All other aspects of the shell execution
- environment are identical between a function and its caller
- with these exceptions:
- the @env{DEBUG} and @env{RETURN} traps
- are not inherited unless the function has been given the
- @code{trace} attribute using the @code{declare} builtin or
- the @code{-o functrace} option has been enabled with
- the @code{set} builtin,
- (in which case all functions inherit the @env{DEBUG} and @env{RETURN} traps),
- and the @env{ERR} trap is not inherited unless the @code{-o errtrace}
- shell option has been enabled.
- @xref{Bourne Shell Builtins}, for the description of the
- @code{trap} builtin.
- The @env{FUNCNEST} 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.
- If the builtin command @code{return}
- is executed in a function, the function completes and
- execution resumes with the next command after the function
- call.
- Any command associated with the @code{RETURN} trap is executed
- before execution resumes.
- When a function completes, the values of the
- positional parameters and the special parameter @samp{#}
- are restored to the values they had prior to the function's
- execution. If a numeric argument is given to @code{return},
- that is the function's return status; otherwise the function's
- return status is the exit status of the last command executed
- before the @code{return}.
- Variables local to the function may be declared with the
- @code{local} builtin. These variables are visible only to
- the function and the commands it invokes. This is particularly
- important when a shell function calls other functions.
- Local variables "shadow" variables with the same name declared at
- previous scopes. For instance, a local variable declared in a function
- hides a global variable of the same name: references and assignments
- refer to the local variable, leaving the global variable unmodified.
- When the function returns, the global variable is once again visible.
- The shell uses @var{dynamic scoping} to control a variable's visibility
- within functions.
- With dynamic scoping, visible variables and their values
- are a result of the sequence of function calls that caused execution
- to reach the current function.
- The value of a variable that a function sees depends
- on its value within its caller, if any, whether that caller is
- the "global" scope or another shell function.
- This is also the value that a local variable
- declaration "shadows", and the value that is restored when the function
- returns.
- For example, if a variable @var{var} is declared as local in function
- @var{func1}, and @var{func1} calls another function @var{func2},
- references to @var{var} made from within @var{func2} will resolve to the
- local variable @var{var} from @var{func1}, shadowing any global variable
- named @var{var}.
- The following script demonstrates this behavior.
- When executed, the script displays
- @example
- In func2, var = func1 local
- @end example
- @example
- func1()
- @{
- local var='func1 local'
- func2
- @}
- func2()
- @{
- echo "In func2, var = $var"
- @}
- var=global
- func1
- @end example
- The @code{unset} builtin also acts using the same dynamic scope: if a
- variable is local to the current scope, @code{unset} will unset it;
- otherwise the unset will refer to the variable found in any calling scope
- as described above.
- If a variable at the current local scope is unset, it will remain so
- until it is reset in that scope or until the function returns.
- Once the function returns, any instance of the variable at a previous
- scope will become visible.
- If the unset acts on a variable at a previous scope, any instance of a
- variable with that name that had been shadowed will become visible.
- Function names and definitions may be listed with the
- @option{-f} option to the @code{declare} (@code{typeset})
- builtin command (@pxref{Bash Builtins}).
- The @option{-F} option to @code{declare} or @code{typeset}
- will list the function names only
- (and optionally the source file and line number, if the @code{extdebug}
- shell option is enabled).
- Functions may be exported so that subshells
- automatically have them defined with the
- @option{-f} option to the @code{export} builtin
- (@pxref{Bourne Shell Builtins}).
- Functions may be recursive.
- The @code{FUNCNEST} 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 placed on the number of recursive calls.
- @node Shell Parameters
- @section Shell Parameters
- @cindex parameters
- @cindex variable, shell
- @cindex shell variable
- @menu
- * Positional Parameters:: The shell's command-line arguments.
- * Special Parameters:: Parameters denoted by special characters.
- @end menu
- A @var{parameter} is an entity that stores values.
- It can be a @code{name}, a number, or one of the special characters
- listed below.
- A @var{variable} is a parameter denoted by a @code{name}.
- A variable has a @var{value} and zero or more @var{attributes}.
- Attributes are assigned using the @code{declare} builtin command
- (see the description of the @code{declare} builtin in @ref{Bash Builtins}).
- 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 @code{unset} builtin command.
- A variable may be assigned to by a statement of the form
- @example
- @var{name}=[@var{value}]
- @end example
- @noindent
- If @var{value}
- is not given, the variable is assigned the null string. All
- @var{value}s undergo tilde expansion, parameter and variable expansion,
- command substitution, arithmetic expansion, and quote
- removal (detailed below). If the variable has its @code{integer}
- attribute set, then @var{value}
- is evaluated as an arithmetic expression even if the @code{$((@dots{}))}
- expansion is not used (@pxref{Arithmetic Expansion}).
- Word splitting is not performed, with the exception
- of @code{"$@@"} as explained below.
- Filename expansion is not performed.
- Assignment statements may also appear as arguments to the
- @code{alias},
- @code{declare}, @code{typeset}, @code{export}, @code{readonly},
- and @code{local} builtin commands (@var{declaration} commands).
- When in @sc{posix} mode (@pxref{Bash POSIX Mode}), these builtins may appear
- in a command after one or more instances of the @code{command} builtin
- and retain these assignment statement properties.
- In the context where an assignment statement is assigning a value
- to a shell variable or array index (@pxref{Arrays}), the @samp{+=}
- operator can be used to
- append to or add to the variable's previous value.
- This includes arguments to builtin commands such as @code{declare} that
- accept assignment statements (@var{declaration} commands).
- When @samp{+=} is applied to a variable for which the @var{integer} attribute
- has been set, @var{value} is evaluated as an arithmetic expression and
- added to the variable's current value, which is also evaluated.
- When @samp{+=} is applied to an array variable using compound assignment
- (@pxref{Arrays}), the
- variable's value is not unset (as it is when using @samp{=}), 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, @var{value} is expanded and
- appended to the variable's value.
- A variable can be assigned the @var{nameref} attribute using the
- @option{-n} option to the @code{declare} or @code{local} builtin commands
- (@pxref{Bash Builtins})
- to create a @var{nameref}, 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 nameref
- 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
- @example
- declare -n ref=$1
- @end example
- @noindent
- inside the function creates a nameref variable @var{ref} whose value is
- the variable name passed as the first argument.
- References and assignments to @var{ref}, and changes to its attributes,
- are treated as references, assignments, and attribute modifications
- to the variable whose name was passed as @code{$1}.
- If the control variable in a @code{for} 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 nameref attribute.
- However, nameref variables can reference array variables and subscripted
- array variables.
- Namerefs can be unset using the @option{-n} option to the @code{unset} builtin
- (@pxref{Bourne Shell Builtins}).
- Otherwise, if @code{unset} is executed with the name of a nameref variable
- as an argument, the variable referenced by the nameref variable will be unset.
- @node Positional Parameters
- @subsection Positional Parameters
- @cindex parameters, positional
- A @var{positional parameter} is a parameter denoted by one or more
- digits, other than the single digit @code{0}. Positional parameters are
- assigned from the shell's arguments when it is invoked,
- and may be reassigned using the @code{set} builtin command.
- Positional parameter @code{N} may be referenced as @code{$@{N@}}, or
- as @code{$N} when @code{N} consists of a single digit.
- Positional parameters may not be assigned to with assignment statements.
- The @code{set} and @code{shift} builtins are used to set and
- unset them (@pxref{Shell Builtin Commands}).
- The positional parameters are
- temporarily replaced when a shell function is executed
- (@pxref{Shell Functions}).
- When a positional parameter consisting of more than a single
- digit is expanded, it must be enclosed in braces.
- @node Special Parameters
- @subsection Special Parameters
- @cindex parameters, special
- The shell treats several parameters specially. These parameters may
- only be referenced; assignment to them is not allowed.
- @vtable @code
- @item *
- @vindex $*
- ($*) 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 filename 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
- @env{IFS} special variable. That is, @code{"$*"} is equivalent
- to @code{"$1@var{c}$2@var{c}@dots{}"}, where @var{c}
- is the first character of the value of the @code{IFS}
- variable.
- If @env{IFS} is unset, the parameters are separated by spaces.
- If @env{IFS} is null, the parameters are joined without intervening
- separators.
- @item @@
- @vindex $@@
- ($@@) Expands to the positional parameters, starting from one.
- In contexts where word splitting is performed, this expands each
- positional parameter to a separate word; if not within double
- quotes, these words are subject to word splitting.
- In contexts where word splitting is not performed,
- this expands to a single word
- with each positional parameter separated by a space.
- When the
- expansion occurs within double quotes, and word splitting is performed,
- each parameter expands to a
- separate word. That is, @code{"$@@"} is equivalent to
- @code{"$1" "$2" @dots{}}.
- 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, @code{"$@@"} and
- @code{$@@}
- expand to nothing (i.e., they are removed).
- @item #
- @vindex $#
- ($#) Expands to the number of positional parameters in decimal.
- @item ?
- @vindex $?
- ($?) Expands to the exit status of the most recently executed foreground
- pipeline.
- @item -
- @vindex $-
- ($-, a hyphen.) Expands to the current option flags as specified upon
- invocation, by the @code{set}
- builtin command, or those set by the shell itself
- (such as the @option{-i} option).
- @item $
- @vindex $$
- ($$) Expands to the process @sc{id} of the shell. In a @code{()} subshell, it
- expands to the process @sc{id} of the invoking shell, not the subshell.
- @item !
- @vindex $!
- ($!) Expands to the process @sc{id} of the job most recently placed into the
- background, whether executed as an asynchronous command or using
- the @code{bg} builtin (@pxref{Job Control Builtins}).
- @item 0
- @vindex $0
- ($0) Expands to the name of the shell or shell script. This is set at
- shell initialization. If Bash is invoked with a file of commands
- (@pxref{Shell Scripts}), @code{$0} is set to the name of that file.
- If Bash is started with the @option{-c} option (@pxref{Invoking Bash}),
- then @code{$0} 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 Bash, as given by argument zero.
- @end vtable
- @node Shell Expansions
- @section Shell Expansions
- @cindex expansion
- Expansion is performed on the command line after it has been split into
- @code{token}s. There are seven kinds of expansion performed:
- @itemize @bullet
- @item brace expansion
- @item tilde expansion
- @item parameter and variable expansion
- @item command substitution
- @item arithmetic expansion
- @item word splitting
- @item filename expansion
- @end itemize
- @menu
- * Brace Expansion:: Expansion of expressions within braces.
- * Tilde Expansion:: Expansion of the ~ character.
- * Shell Parameter Expansion:: How Bash expands variables to their values.
- * Command Substitution:: Using the output of a command as an argument.
- * Arithmetic Expansion:: How to use arithmetic in shell expansions.
- * Process Substitution:: A way to write and read to and from a
- command.
- * Word Splitting:: How the results of expansion are split into separate
- arguments.
- * Filename Expansion:: A shorthand for specifying filenames matching patterns.
- * Quote Removal:: How and when quote characters are removed from
- words.
- @end menu
- 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 filename expansion.
- On systems that can support it, there is an additional expansion
- available: @var{process substitution}.
- This is performed at the
- same time as tilde, parameter, variable, and arithmetic expansion and
- command substitution.
- After these expansions are performed, quote characters present in the
- original word are removed unless they have been quoted themselves
- (@var{quote removal}).
- Only brace expansion, word splitting, and filename expansion
- can increase 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
- @code{"$@@"} and @code{$*} (@pxref{Special Parameters}), and
- @code{"$@{@var{name}[@@]@}"} and @code{$@{@var{name}[*]@}}
- (@pxref{Arrays}).
- After all expansions, @code{quote removal} (@pxref{Quote Removal})
- is performed.
- @node Brace Expansion
- @subsection Brace Expansion
- @cindex brace expansion
- @cindex expansion, brace
- Brace expansion is a mechanism by which arbitrary strings may be generated.
- This mechanism is similar to
- @var{filename expansion} (@pxref{Filename Expansion}),
- but the filenames generated need not exist.
- Patterns to be brace expanded take the form of an optional @var{preamble},
- followed by either a series of comma-separated strings or a sequence expression
- between a pair of braces,
- followed by an optional @var{postscript}.
- 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.
- Brace expansions may be nested.
- The results of each expanded string are not sorted; left to right order
- is preserved.
- For example,
- @example
- bash$ echo a@{d,c,b@}e
- ade ace abe
- @end example
- A sequence expression takes the form @code{@{@var{x}..@var{y}[..@var{incr}]@}},
- where @var{x} and @var{y} are either integers or single characters,
- and @var{incr}, an optional increment, is an integer.
- When integers are supplied, the expression expands to each number between
- @var{x} and @var{y}, inclusive.
- Supplied integers may be prefixed with @samp{0} to force each term to have the
- same width.
- When either @var{x} or @var{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 @var{x} and @var{y}, inclusive,
- using the default C locale.
- Note that both @var{x} and @var{y} 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.
- Brace expansion is performed before any other expansions,
- and any characters special to other expansions are preserved
- in the result. It is strictly textual. Bash
- does not apply any syntactic interpretation to the context of the
- expansion or the text between the braces.
- 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 @{ or @samp{,} may be quoted with a backslash to prevent its
- being considered part of a brace expression.
- To avoid conflicts with parameter expansion, the string @samp{$@{}
- is not considered eligible for brace expansion,
- and inhibits brace expansion until the closing @samp{@}}.
- This construct is typically used as shorthand when the common
- prefix of the strings to be generated is longer than in the
- above example:
- @example
- mkdir /usr/local/src/bash/@{old,new,dist,bugs@}
- @end example
- or
- @example
- chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@}
- @end example
- @node Tilde Expansion
- @subsection Tilde Expansion
- @cindex tilde expansion
- @cindex expansion, tilde
- If a word begins with an unquoted tilde character (@samp{~}), all of the
- characters up to the first unquoted slash (or all characters,
- if there is no unquoted slash) are considered a @var{tilde-prefix}.
- 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 @var{login name}.
- If this login name is the null string, the tilde is replaced with the
- value of the @env{HOME} shell variable.
- If @env{HOME} 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.
- If the tilde-prefix is @samp{~+}, the value of
- the shell variable @env{PWD} replaces the tilde-prefix.
- If the tilde-prefix is @samp{~-}, the value of the shell variable
- @env{OLDPWD}, if it is set, is substituted.
- If the characters following the tilde in the tilde-prefix consist of a
- number @var{N}, optionally prefixed by a @samp{+} or a @samp{-},
- the tilde-prefix is replaced with the
- corresponding element from the directory stack, as it would be displayed
- by the @code{dirs} builtin invoked with the characters following tilde
- in the tilde-prefix as an argument (@pxref{The Directory Stack}).
- If the tilde-prefix, sans the tilde, consists of a number without a
- leading @samp{+} or @samp{-}, @samp{+} is assumed.
- If the login name is invalid, or the tilde expansion fails, the word is
- left unchanged.
- Each variable assignment is checked for unquoted tilde-prefixes immediately
- following a @samp{:} or the first @samp{=}.
- In these cases, tilde expansion is also performed.
- Consequently, one may use filenames with tildes in assignments to
- @env{PATH}, @env{MAILPATH}, and @env{CDPATH},
- and the shell assigns the expanded value.
- The following table shows how Bash treats unquoted tilde-prefixes:
- @table @code
- @item ~
- The value of @code{$HOME}
- @item ~/foo
- @file{$HOME/foo}
- @item ~fred/foo
- The subdirectory @code{foo} of the home directory of the user
- @code{fred}
- @item ~+/foo
- @file{$PWD/foo}
- @item ~-/foo
- @file{$@{OLDPWD-'~-'@}/foo}
- @item ~@var{N}
- The string that would be displayed by @samp{dirs +@var{N}}
- @item ~+@var{N}
- The string that would be displayed by @samp{dirs +@var{N}}
- @item ~-@var{N}
- The string that would be displayed by @samp{dirs -@var{N}}
- @end table
- Bash also performs tilde expansion on words satisfying the conditions of
- variable assignments (@pxref{Shell Parameters})
- when they appear as arguments to simple commands.
- Bash does not do this, except for the @var{declaration} commands listed
- above, when in @sc{posix} mode.
- @node Shell Parameter Expansion
- @subsection Shell Parameter Expansion
- @cindex parameter expansion
- @cindex expansion, parameter
- The @samp{$} 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.
- When braces are used, the matching ending brace is the first @samp{@}}
- not escaped by a backslash or within a quoted string, and not within an
- embedded arithmetic expansion, command substitution, or parameter
- expansion.
- The basic form of parameter expansion is $@{@var{parameter}@}.
- The value of @var{parameter} is substituted.
- The @var{parameter} is a shell parameter as described above
- (@pxref{Shell Parameters}) or an array reference (@pxref{Arrays}).
- The braces are required when @var{parameter}
- is a positional parameter with more than one digit,
- or when @var{parameter} is followed by a character that is not to be
- interpreted as part of its name.
- If the first character of @var{parameter} is an exclamation point (!),
- and @var{parameter} is not a @var{nameref},
- it introduces a level of indirection.
- Bash uses the value formed by expanding the rest of
- @var{parameter} as the new @var{parameter}; this is then
- expanded and that value is used in the rest of the expansion, rather
- than the expansion of the original @var{parameter}.
- This is known as @code{indirect expansion}.
- The value is subject to tilde expansion,
- parameter expansion, command substitution, and arithmetic expansion.
- If @var{parameter} is a nameref, this expands to the name of the
- variable referenced by @var{parameter} instead of performing the
- complete indirect expansion.
- The exceptions to this are the expansions of $@{!@var{prefix}*@}
- and $@{!@var{name}[@@]@}
- described below.
- The exclamation point must immediately follow the left brace in order to
- introduce indirection.
- In each of the cases below, @var{word} is subject to tilde expansion,
- parameter expansion, command substitution, and arithmetic expansion.
- When not performing substring expansion, using the form described
- below (e.g., @samp{:-}), Bash tests for a parameter that is unset or null.
- Omitting the colon results in a test only for a parameter that is unset.
- Put another way, if the colon is included,
- the operator tests for both @var{parameter}'s existence and that its value
- is not null; if the colon is omitted, the operator tests only for existence.
- @table @code
- @item $@{@var{parameter}:@minus{}@var{word}@}
- If @var{parameter} is unset or null, the expansion of
- @var{word} is substituted. Otherwise, the value of
- @var{parameter} is substituted.
- @item $@{@var{parameter}:=@var{word}@}
- If @var{parameter}
- is unset or null, the expansion of @var{word}
- is assigned to @var{parameter}.
- The value of @var{parameter} is then substituted.
- Positional parameters and special parameters may not be assigned to
- in this way.
- @item $@{@var{parameter}:?@var{word}@}
- If @var{parameter}
- is null or unset, the expansion of @var{word} (or a message
- to that effect if @var{word}
- is not present) is written to the standard error and the shell, if it
- is not interactive, exits. Otherwise, the value of @var{parameter} is
- substituted.
- @item $@{@var{parameter}:+@var{word}@}
- If @var{parameter}
- is null or unset, nothing is substituted, otherwise the expansion of
- @var{word} is substituted.
- @item $@{@var{parameter}:@var{offset}@}
- @itemx $@{@var{parameter}:@var{offset}:@var{length}@}
- This is referred to as Substring Expansion.
- It expands to up to @var{length} characters of the value of @var{parameter}
- starting at the character specified by @var{offset}.
- If @var{parameter} is @samp{@@}, an indexed array subscripted by
- @samp{@@} or @samp{*}, or an associative array name, the results differ as
- described below.
- If @var{length} is omitted, it expands to the substring of the value of
- @var{parameter} starting at the character specified by @var{offset}
- and extending to the end of the value.
- @var{length} and @var{offset} are arithmetic expressions
- (@pxref{Shell Arithmetic}).
- If @var{offset} evaluates to a number less than zero, the value
- is used as an offset in characters
- from the end of the value of @var{parameter}.
- If @var{length} evaluates to a number less than zero,
- it is interpreted as an offset in characters
- from the end of the value of @var{parameter} rather than
- a number of characters, and the expansion is the characters between
- @var{offset} 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 @samp{:-} expansion.
- Here are some examples illustrating substring expansion on parameters and
- subscripted arrays:
- @verbatim
- $ string=01234567890abcdefgh
- $ echo ${string:7}
- 7890abcdefgh
- $ echo ${string:7:0}
- $ echo ${string:7:2}
- 78
- $ echo ${string:7:-2}
- 7890abcdef
- $ echo ${string: -7}
- bcdefgh
- $ echo ${string: -7:0}
- $ echo ${string: -7:2}
- bc
- $ echo ${string: -7:-2}
- bcdef
- $ set -- 01234567890abcdefgh
- $ echo ${1:7}
- 7890abcdefgh
- $ echo ${1:7:0}
- $ echo ${1:7:2}
- 78
- $ echo ${1:7:-2}
- 7890abcdef
- $ echo ${1: -7}
- bcdefgh
- $ echo ${1: -7:0}
- $ echo ${1: -7:2}
- bc
- $ echo ${1: -7:-2}
- bcdef
- $ array[0]=01234567890abcdefgh
- $ echo ${array[0]:7}
- 7890abcdefgh
- $ echo ${array[0]:7:0}
- $ echo ${array[0]:7:2}
- 78
- $ echo ${array[0]:7:-2}
- 7890abcdef
- $ echo ${array[0]: -7}
- bcdefgh
- $ echo ${array[0]: -7:0}
- $ echo ${array[0]: -7:2}
- bc
- $ echo ${array[0]: -7:-2}
- bcdef
- @end verbatim
- If @var{parameter} is @samp{@@}, the result is @var{length} positional
- parameters beginning at @var{offset}.
- A negative @var{offset} 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 @var{length} evaluates to a number less than zero.
- The following examples illustrate substring expansion using positional
- parameters:
- @verbatim
- $ set -- 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
- $ echo ${@:7}
- 7 8 9 0 a b c d e f g h
- $ echo ${@:7:0}
- $ echo ${@:7:2}
- 7 8
- $ echo ${@:7:-2}
- bash: -2: substring expression < 0
- $ echo ${@: -7:2}
- b c
- $ echo ${@:0}
- ./bash 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
- $ echo ${@:0:2}
- ./bash 1
- $ echo ${@: -7:0}
- @end verbatim
- If @var{parameter} is an indexed array name subscripted
- by @samp{@@} or @samp{*}, the result is the @var{length}
- members of the array beginning with @code{$@{@var{parameter}[@var{offset}]@}}.
- A negative @var{offset} is taken relative to one greater than the maximum
- index of the specified array.
- It is an expansion error if @var{length} evaluates to a number less than zero.
- These examples show how you can use substring expansion with indexed
- arrays:
- @verbatim
- $ array=(0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h)
- $ echo ${array[@]:7}
- 7 8 9 0 a b c d e f g h
- $ echo ${array[@]:7:2}
- 7 8
- $ echo ${array[@]: -7:2}
- b c
- $ echo ${array[@]: -7:-2}
- bash: -2: substring expression < 0
- $ echo ${array[@]:0}
- 0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h
- $ echo ${array[@]:0:2}
- 0 1
- $ echo ${array[@]: -7:0}
- @end verbatim
- Substring expansion applied to an associative array produces undefined
- results.
- Substring indexing is zero-based unless the positional parameters
- are used, in which case the indexing starts at 1 by default.
- If @var{offset} is 0, and the positional parameters are used, @code{$0} is
- prefixed to the list.
- @item $@{!@var{prefix}*@}
- @itemx $@{!@var{prefix}@@@}
- Expands to the names of variables whose names begin with @var{prefix},
- separated by the first character of the @env{IFS} special variable.
- When @samp{@@} is used and the expansion appears within double quotes, each
- variable name expands to a separate word.
- @item $@{!@var{name}[@@]@}
- @itemx $@{!@var{name}[*]@}
- If @var{name} is an array variable, expands to the list of array indices
- (keys) assigned in @var{name}.
- If @var{name} is not an array, expands to 0 if @var{name} is set and null
- otherwise.
- When @samp{@@} is used and the expansion appears within double quotes, each
- key expands to a separate word.
- @item $@{#@var{parameter}@}
- The length in characters of the expanded value of @var{parameter} is
- substituted.
- If @var{parameter} is @samp{*} or @samp{@@}, the value substituted
- is the number of positional parameters.
- If @var{parameter} is an array name subscripted by @samp{*} or @samp{@@},
- the value substituted is the number of elements in the array.
- If @var{parameter}
- is an indexed array name subscripted by a negative number, that number is
- interpreted as relative to one greater than the maximum index of
- @var{parameter}, so negative indices count back from the end of the
- array, and an index of -1 references the last element.
- @item $@{@var{parameter}#@var{word}@}
- @itemx $@{@var{parameter}##@var{word}@}
- The @var{word}
- is expanded to produce a pattern and matched according to the rules
- described below (@pxref{Pattern Matching}). If the pattern matches
- the beginning of the expanded value of @var{parameter},
- then the result of the expansion is the expanded value of @var{parameter}
- with the shortest matching pattern (the @samp{#} case) or the
- longest matching pattern (the @samp{##} case) deleted.
- If @var{parameter} is @samp{@@} or @samp{*},
- the pattern removal operation is applied to each positional
- parameter in turn, and the expansion is the resultant list.
- If @var{parameter} is an array variable subscripted with
- @samp{@@} or @samp{*},
- the pattern removal operation is applied to each member of the
- array in turn, and the expansion is the resultant list.
- @item $@{@var{parameter}%@var{word}@}
- @itemx $@{@var{parameter}%%@var{word}@}
- The @var{word}
- is expanded to produce a pattern and matched according to the rules
- described below (@pxref{Pattern Matching}).
- If the pattern matches a trailing portion of the expanded value of
- @var{parameter}, then the result of the expansion is the value of
- @var{parameter} with the shortest matching pattern (the @samp{%} case)
- or the longest matching pattern (the @samp{%%} case) deleted.
- If @var{parameter} is @samp{@@} or @samp{*},
- the pattern removal operation is applied to each positional
- parameter in turn, and the expansion is the resultant list.
- If @var{parameter}
- is an array variable subscripted with @samp{@@} or @samp{*},
- the pattern removal operation is applied to each member of the
- array in turn, and the expansion is the resultant list.
- @item $@{@var{parameter}/@var{pattern}/@var{string}@}
- The @var{pattern} is expanded to produce a pattern just as in
- filename expansion.
- @var{Parameter} is expanded and the longest match of @var{pattern}
- against its value is replaced with @var{string}.
- The match is performed according to the rules described below
- (@pxref{Pattern Matching}).
- If @var{pattern} begins with @samp{/}, all matches of @var{pattern} are
- replaced with @var{string}. Normally only the first match is replaced.
- If @var{pattern} begins with @samp{#}, it must match at the beginning
- of the expanded value of @var{parameter}.
- If @var{pattern} begins with @samp{%}, it must match at the end
- of the expanded value of @var{parameter}.
- If @var{string} is null, matches of @var{pattern} are deleted
- and the @code{/} following @var{pattern} may be omitted.
- If the @code{nocasematch} shell option
- (see the description of @code{shopt} in @ref{The Shopt Builtin})
- is enabled, the match is performed without regard to the case
- of alphabetic characters.
- If @var{parameter} is @samp{@@} or @samp{*},
- the substitution operation is applied to each positional
- parameter in turn, and the expansion is the resultant list.
- If @var{parameter}
- is an array variable subscripted with @samp{@@} or @samp{*},
- the substitution operation is applied to each member of the
- array in turn, and the expansion is the resultant list.
- @item $@{@var{parameter}^@var{pattern}@}
- @itemx $@{@var{parameter}^^@var{pattern}@}
- @itemx $@{@var{parameter},@var{pattern}@}
- @itemx $@{@var{parameter},,@var{pattern}@}
- This expansion modifies the case of alphabetic characters in @var{parameter}.
- The @var{pattern} is expanded to produce a pattern just as in
- filename expansion.
- Each character in the expanded value of @var{parameter} is tested against
- @var{pattern}, and, if it matches the pattern, its case is converted.
- The pattern should not attempt to match more than one character.
- The @samp{^} operator converts lowercase letters matching @var{pattern}
- to uppercase; the @samp{,} operator converts matching uppercase letters
- to lowercase.
- The @samp{^^} and @samp{,,} expansions convert each matched character in the
- expanded value; the @samp{^} and @samp{,} expansions match and convert only
- the first character in the expanded value.
- If @var{pattern} is omitted, it is treated like a @samp{?}, which matches
- every character.
- If @var{parameter} is @samp{@@} or @samp{*},
- the case modification operation is applied to each positional
- parameter in turn, and the expansion is the resultant list.
- If @var{parameter}
- is an array variable subscripted with @samp{@@} or @samp{*},
- the case modification operation is applied to each member of the
- array in turn, and the expansion is the resultant list.
- @item $@{@var{parameter}@@@var{operator}@}
- The expansion is either a transformation of the value of @var{parameter}
- or information about @var{parameter} itself, depending on the value of
- @var{operator}. Each @var{operator} is a single letter:
- @table @code
- @item U
- The expansion is a string that is the value of @var{parameter} with lowercase
- alphabetic characters converted to uppercase.
- @item u
- The expansion is a string that is the value of @var{parameter} with the first
- character converted to uppercase, if it is alphabetic.
- @item L
- The expansion is a string that is the value of @var{parameter} with uppercase
- alphabetic characters converted to lowercase.
- @item Q
- The expansion is a string that is the value of @var{parameter} quoted in a
- format that can be reused as input.
- @item E
- The expansion is a string that is the value of @var{parameter} with backslash
- escape sequences expanded as with the @code{$'@dots{}'} quoting mechanism.
- @item P
- The expansion is a string that is the result of expanding the value of
- @var{parameter} as if it were a prompt string (@pxref{Controlling the Prompt}).
- @item A
- The expansion is a string in the form of
- an assignment statement or @code{declare} command that, if
- evaluated, will recreate @var{parameter} with its attributes and value.
- @item K
- Produces a possibly-quoted version of the value of @var{parameter},
- except that it prints the values of
- indexed and associative arrays as a sequence of quoted key-value pairs
- (@pxref{Arrays}).
- @item a
- The expansion is a string consisting of flag values representing
- @var{parameter}'s attributes.
- @end table
- If @var{parameter} is @samp{@@} or @samp{*},
- the operation is applied to each positional
- parameter in turn, and the expansion is the resultant list.
- If @var{parameter}
- is an array variable subscripted with @samp{@@} or @samp{*},
- the operation is applied to each member of the
- array in turn, and the expansion is the resultant list.
- The result of the expansion is subject to word splitting and filename
- expansion as described below.
- @end table
- @node Command Substitution
- @subsection Command Substitution
- @cindex command substitution
- Command substitution allows the output of a command to replace
- the command itself.
- Command substitution occurs when a command is enclosed as follows:
- @example
- $(@var{command})
- @end example
- @noindent
- or
- @example
- `@var{command}`
- @end example
- @noindent
- Bash performs the expansion by executing @var{command} 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 @code{$(cat @var{file})} can be
- replaced by the equivalent but faster @code{$(< @var{file})}.
- When the old-style backquote form of substitution is used,
- backslash retains its literal meaning except when followed by
- @samp{$}, @samp{`}, or @samp{\}.
- The first backquote not preceded by a backslash terminates the
- command substitution.
- When using the @code{$(@var{command})} form, all characters between
- the parentheses make up the command; none are treated specially.
- Command substitutions may be nested. To nest when using the backquoted
- form, escape the inner backquotes with backslashes.
- If the substitution appears within double quotes, word splitting and
- filename expansion are not performed on the results.
- @node Arithmetic Expansion
- @subsection Arithmetic Expansion
- @cindex expansion, arithmetic
- @cindex arithmetic expansion
- Arithmetic expansion allows the evaluation of an arithmetic expression
- and the substitution of the result. The format for arithmetic expansion is:
- @example
- $(( @var{expression} ))
- @end example
- The expression 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.
- The evaluation is performed according to the rules listed below
- (@pxref{Shell Arithmetic}).
- If the expression is invalid, Bash prints a message indicating
- failure to the standard error and no substitution occurs.
- @node Process Substitution
- @subsection Process Substitution
- @cindex process substitution
- Process substitution allows a process's input or output to be
- referred to using a filename.
- It takes the form of
- @example
- <(@var{list})
- @end example
- @noindent
- or
- @example
- >(@var{list})
- @end example
- @noindent
- The process @var{list} 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 @code{>(@var{list})} form is used, writing to
- the file will provide input for @var{list}. If the
- @code{<(@var{list})} form is used, the file passed as an
- argument should be read to obtain the output of @var{list}.
- Note that no space may appear between the @code{<} or @code{>}
- and the left parenthesis, otherwise the construct would be interpreted
- as a redirection.
- Process substitution is supported on systems that support named
- pipes (@sc{fifo}s) or the @file{/dev/fd} method of naming open files.
- When available, process substitution is performed simultaneously with
- parameter and variable expansion, command substitution, and arithmetic
- expansion.
- @node Word Splitting
- @subsection Word Splitting
- @cindex word splitting
- The shell scans the results of parameter expansion, command substitution,
- and arithmetic expansion that did not occur within double quotes for
- word splitting.
- The shell treats each character of @env{$IFS} as a delimiter, and splits
- the results of the other expansions into words using these characters
- as field terminators.
- If @env{IFS} is unset, or its value is exactly @code{<space><tab><newline>},
- the default, then sequences of
- @code{ <space>}, @code{<tab>}, and @code{<newline>}
- at the beginning and end of the results of the previous
- expansions are ignored, and any sequence of @env{IFS}
- characters not at the beginning or end serves to delimit words.
- If @env{IFS} has a value other than the default, then sequences of
- the whitespace characters @code{space}, @code{tab}, and @code{newline}
- are ignored at the beginning and end of the
- word, as long as the whitespace character is in the
- value of @env{IFS} (an @env{IFS} whitespace character).
- Any character in @env{IFS} that is not @env{IFS}
- whitespace, along with any adjacent @env{IFS}
- whitespace characters, delimits a field. A sequence of @env{IFS}
- whitespace characters is also treated as a delimiter.
- If the value of @env{IFS} is null, no word splitting occurs.
- Explicit null arguments (@code{""} or @code{''}) 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
- @code{-d''} becomes @code{-d} after word splitting and
- null argument removal.
- Note that if no expansion occurs, no splitting
- is performed.
- @node Filename Expansion
- @subsection Filename Expansion
- @menu
- * Pattern Matching:: How the shell matches patterns.
- @end menu
- @cindex expansion, filename
- @cindex expansion, pathname
- @cindex filename expansion
- @cindex pathname expansion
- After word splitting, unless the @option{-f} option has been set
- (@pxref{The Set Builtin}), Bash scans each word for the characters
- @samp{*}, @samp{?}, and @samp{[}.
- If one of these characters appears, and is not quoted, then the word is
- regarded as a @var{pattern},
- and replaced with an alphabetically sorted list of
- filenames matching the pattern (@pxref{Pattern Matching}).
- If no matching filenames are found,
- and the shell option @code{nullglob} is disabled, the word is left
- unchanged.
- If the @code{nullglob} option is set, and no matches are found, the word
- is removed.
- If the @code{failglob} shell option is set, and no matches are found,
- an error message is printed and the command is not executed.
- If the shell option @code{nocaseglob} is enabled, the match is performed
- without regard to the case of alphabetic characters.
- When a pattern is used for filename expansion, the character @samp{.}
- at the start of a filename or immediately following a slash
- must be matched explicitly, unless the shell option @code{dotglob} is set.
- The filenames @samp{.} and @samp{..} must always be matched explicitly,
- even if @code{dotglob} is set.
- In other cases, the @samp{.} character is not treated specially.
- When matching a filename, the slash character must always be
- matched explicitly by a slash in the pattern, but in other matching
- contexts it can be matched by a special pattern character as described
- below (@pxref{Pattern Matching}).
- See the description of @code{shopt} in @ref{The Shopt Builtin},
- for a description of the @code{nocaseglob}, @code{nullglob},
- @code{failglob}, and @code{dotglob} options.
- The @env{GLOBIGNORE}
- shell variable may be used to restrict the set of file names matching a
- pattern. If @env{GLOBIGNORE}
- is set, each matching file name that also matches one of the patterns in
- @env{GLOBIGNORE} is removed from the list of matches.
- If the @code{nocaseglob} option is set, the matching against the patterns in
- @env{GLOBIGNORE} is performed without regard to case.
- The filenames
- @file{.} and @file{..}
- are always ignored when @env{GLOBIGNORE}
- is set and not null.
- However, setting @env{GLOBIGNORE} to a non-null value has the effect of
- enabling the @code{dotglob}
- shell option, so all other filenames beginning with a
- @samp{.} will match.
- To get the old behavior of ignoring filenames beginning with a
- @samp{.}, make @samp{.*} one of the patterns in @env{GLOBIGNORE}.
- The @code{dotglob} option is disabled when @env{GLOBIGNORE}
- is unset.
- @node Pattern Matching
- @subsubsection Pattern Matching
- @cindex pattern matching
- @cindex matching, pattern
- Any character that appears in a pattern, other than the special pattern
- characters described below, matches itself.
- The @sc{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.
- The special pattern characters have the following meanings:
- @table @code
- @item *
- Matches any string, including the null string.
- When the @code{globstar} shell option is enabled, and @samp{*} is used in
- a filename expansion context, two adjacent @samp{*}s used as a single
- pattern will match all files and zero or more directories and
- subdirectories.
- If followed by a @samp{/}, two adjacent @samp{*}s will match only
- directories and subdirectories.
- @item ?
- Matches any single character.
- @item [@dots{}]
- Matches any one of the enclosed characters. A pair of characters
- separated by a hyphen denotes a @var{range expression};
- 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
- @samp{[} is a @samp{!} or a @samp{^}
- then any character not enclosed is matched. A @samp{@minus{}}
- may be matched by including it as the first or last character
- in the set. A @samp{]} may be matched by including it as the first
- character in the set.
- The sorting order of characters in range expressions is determined by
- the current locale and the values of the
- @env{LC_COLLATE} and @env{LC_ALL} shell variables, if set.
- For example, in the default C locale, @samp{[a-dx-z]} is equivalent to
- @samp{[abcdxyz]}. Many locales sort characters in dictionary order, and in
- these locales @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]};
- it might be equivalent to @samp{[aBbCcDdxXyYz]}, for example. To obtain
- the traditional interpretation of ranges in bracket expressions, you can
- force the use of the C locale by setting the @env{LC_COLLATE} or
- @env{LC_ALL} environment variable to the value @samp{C}, or enable the
- @code{globasciiranges} shell option.
- Within @samp{[} and @samp{]}, @var{character classes} can be specified
- using the syntax
- @code{[:}@var{class}@code{:]}, where @var{class} is one of the
- following classes defined in the @sc{posix} standard:
- @example
- alnum alpha ascii blank cntrl digit graph lower
- print punct space upper word xdigit
- @end example
- @noindent
- A character class matches any character belonging to that class.
- The @code{word} character class matches letters, digits, and the character
- @samp{_}.
- Within @samp{[} and @samp{]}, an @var{equivalence class} can be
- specified using the syntax @code{[=}@var{c}@code{=]}, which
- matches all characters with the same collation weight (as defined
- by the current locale) as the character @var{c}.
- Within @samp{[} and @samp{]}, the syntax @code{[.}@var{symbol}@code{.]}
- matches the collating symbol @var{symbol}.
- @end table
- If the @code{extglob} shell option is enabled using the @code{shopt}
- builtin, several extended pattern matching operators are recognized.
- In the following description, a @var{pattern-list} is a list of one
- or more patterns separated by a @samp{|}.
- Composite patterns may be formed using one or more of the following
- sub-patterns:
- @table @code
- @item ?(@var{pattern-list})
- Matches zero or one occurrence of the given patterns.
- @item *(@var{pattern-list})
- Matches zero or more occurrences of the given patterns.
- @item +(@var{pattern-list})
- Matches one or more occurrences of the given patterns.
- @item @@(@var{pattern-list})
- Matches one of the given patterns.
- @item !(@var{pattern-list})
- Matches anything except one of the given patterns.
- @end table
- Complicated extended pattern matching against long strings is slow,
- especially when the patterns contain alternations and the strings
- contain multiple matches.
- Using separate matches against shorter strings, or using arrays of
- strings instead of a single long string, may be faster.
- @node Quote Removal
- @subsection Quote Removal
- After the preceding expansions, all unquoted occurrences of the
- characters @samp{\}, @samp{'}, and @samp{"} that did not
- result from one of the above expansions are removed.
- @node Redirections
- @section Redirections
- @cindex redirection
- Before a command is executed, its input and output
- may be @var{redirected}
- 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
- simple command or may follow a command.
- Redirections are processed in the order they appear, from
- left to right.
- Each redirection that may be preceded by a file descriptor number
- may instead be preceded by a word of the form @{@var{varname}@}.
- In this case, for each redirection operator except
- >&- and <&-, the shell will allocate a file descriptor greater
- than 10 and assign it to @{@var{varname}@}. If >&- or <&- is preceded
- by @{@var{varname}@}, the value of @var{varname} defines the file
- descriptor to close.
- If @{@var{varname}@} is supplied, the redirection persists beyond
- the scope of the command, allowing the shell programmer to manage
- the file descriptor's lifetime manually.
- In the following descriptions, if the file descriptor number is
- omitted, and the first character of the redirection operator is
- @samp{<}, the redirection refers to the standard input (file
- descriptor 0). If the first character of the redirection operator
- is @samp{>}, the redirection refers to the standard output (file
- descriptor 1).
- The word following the redirection operator in the following
- descriptions, unless otherwise noted, is subjected to brace expansion,
- tilde expansion, parameter expansion, command substitution, arithmetic
- expansion, quote removal, filename expansion, and word splitting.
- If it expands to more than one word, Bash reports an error.
- Note that the order of redirections is significant. For example,
- the command
- @example
- ls > @var{dirlist} 2>&1
- @end example
- @noindent
- directs both standard output (file descriptor 1) and standard error
- (file descriptor 2) to the file @var{dirlist}, while the command
- @example
- ls 2>&1 > @var{dirlist}
- @end example
- @noindent
- directs only the standard output to file @var{dirlist},
- because the standard error was made a copy of the standard output
- before the standard output was redirected to @var{dirlist}.
- Bash handles several filenames specially when they are used in
- redirections, as described in the following table.
- If the operating system on which Bash is running provides these
- special files, bash will use them; otherwise it will emulate them
- internally with the behavior described below.
- @table @code
- @item /dev/fd/@var{fd}
- If @var{fd} is a valid integer, file descriptor @var{fd} is duplicated.
- @item /dev/stdin
- File descriptor 0 is duplicated.
- @item /dev/stdout
- File descriptor 1 is duplicated.
- @item /dev/stderr
- File descriptor 2 is duplicated.
- @item /dev/tcp/@var{host}/@var{port}
- If @var{host} is a valid hostname or Internet address, and @var{port}
- is an integer port number or service name, Bash attempts to open
- the corresponding TCP socket.
- @item /dev/udp/@var{host}/@var{port}
- If @var{host} is a valid hostname or Internet address, and @var{port}
- is an integer port number or service name, Bash attempts to open
- the corresponding UDP socket.
- @end table
- A failure to open or create a file causes the redirection to fail.
- Redirections using file descriptors greater than 9 should be used with
- care, as they may conflict with file descriptors the shell uses
- internally.
- @subsection Redirecting Input
- Redirection of input causes the file whose name results from
- the expansion of @var{word}
- to be opened for reading on file descriptor @code{n},
- or the standard input (file descriptor 0) if @code{n}
- is not specified.
- The general format for redirecting input is:
- @example
- [@var{n}]<@var{word}
- @end example
- @subsection Redirecting Output
- Redirection of output causes the file whose name results from
- the expansion of @var{word}
- to be opened for writing on file descriptor @var{n},
- or the standard output (file descriptor 1) if @var{n}
- is not specified. If the file does not exist it is created;
- if it does exist it is truncated to zero size.
- The general format for redirecting output is:
- @example
- [@var{n}]>[|]@var{word}
- @end example
- If the redirection operator is @samp{>}, and the @code{noclobber}
- option to the @code{set} builtin has been enabled, the redirection
- will fail if the file whose name results from the expansion of
- @var{word} exists and is a regular file.
- If the redirection operator is @samp{>|}, or the redirection operator is
- @samp{>} and the @code{noclobber} option is not enabled, the redirection
- is attempted even if the file named by @var{word} exists.
- @subsection Appending Redirected Output
- Redirection of output in this fashion
- causes the file whose name results from
- the expansion of @var{word}
- to be opened for appending on file descriptor @var{n},
- or the standard output (file descriptor 1) if @var{n}
- is not specified. If the file does not exist it is created.
- The general format for appending output is:
- @example
- [@var{n}]>>@var{word}
- @end example
- @subsection Redirecting Standard Output and Standard Error
- 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 @var{word}.
- There are two formats for redirecting standard output and
- standard error:
- @example
- &>@var{word}
- @end example
- @noindent
- and
- @example
- >&@var{word}
- @end example
- @noindent
- Of the two forms, the first is preferred.
- This is semantically equivalent to
- @example
- >@var{word} 2>&1
- @end example
- When using the second form, @var{word} may not expand to a number or
- @samp{-}. If it does, other redirection operators apply
- (see Duplicating File Descriptors below) for compatibility reasons.
- @subsection Appending Standard Output and Standard Error
- 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 @var{word}.
- The format for appending standard output and standard error is:
- @example
- &>>@var{word}
- @end example
- @noindent
- This is semantically equivalent to
- @example
- >>@var{word} 2>&1
- @end example
- (see Duplicating File Descriptors below).
- @subsection Here Documents
- This type of redirection instructs the shell to read input from the
- current source until a line containing only @var{word}
- (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 @var{n} if @var{n} is specified) for a command.
- The format of here-documents is:
- @example
- [@var{n}]<<[@minus{}]@var{word}
- @var{here-document}
- @var{delimiter}
- @end example
- No parameter and variable expansion, command substitution,
- arithmetic expansion, or filename expansion is performed on
- @var{word}. If any part of @var{word} is quoted, the
- @var{delimiter} is the result of quote removal on @var{word},
- and the lines in the here-document are not expanded.
- If @var{word} is unquoted,
- all lines of the here-document are subjected to
- parameter expansion, command substitution, and arithmetic expansion,
- the character sequence @code{\newline} is ignored, and @samp{\}
- must be used to quote the characters
- @samp{\}, @samp{$}, and @samp{`}.
- If the redirection operator is @samp{<<-},
- then all leading tab characters are stripped from input lines and the
- line containing @var{delimiter}.
- This allows here-documents within shell scripts to be indented in a
- natural fashion.
- @subsection Here Strings
- A variant of here documents, the format is:
- @example
- [@var{n}]<<< @var{word}
- @end example
- The @var{word} undergoes
- tilde expansion, parameter and variable expansion,
- command substitution, arithmetic expansion, and quote removal.
- Filename 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 @var{n} if @var{n} is specified).
- @subsection Duplicating File Descriptors
- The redirection operator
- @example
- [@var{n}]<&@var{word}
- @end example
- @noindent
- is used to duplicate input file descriptors.
- If @var{word}
- expands to one or more digits, the file descriptor denoted by @var{n}
- is made to be a copy of that file descriptor.
- If the digits in @var{word} do not specify a file descriptor open for
- input, a redirection error occurs.
- If @var{word}
- evaluates to @samp{-}, file descriptor @var{n} is closed.
- If @var{n} is not specified, the standard input (file descriptor 0) is used.
- The operator
- @example
- [@var{n}]>&@var{word}
- @end example
- @noindent
- is used similarly to duplicate output file descriptors. If
- @var{n} is not specified, the standard output (file descriptor 1) is used.
- If the digits in @var{word} do not specify a file descriptor open for
- output, a redirection error occurs.
- If @var{word}
- evaluates to @samp{-}, file descriptor @var{n} is closed.
- As a special case, if @var{n} is omitted, and @var{word} does not
- expand to one or more digits or @samp{-}, the standard output and standard
- error are redirected as described previously.
- @subsection Moving File Descriptors
- The redirection operator
- @example
- [@var{n}]<&@var{digit}-
- @end example
- @noindent
- moves the file descriptor @var{digit} to file descriptor @var{n},
- or the standard input (file descriptor 0) if @var{n} is not specified.
- @var{digit} is closed after being duplicated to @var{n}.
- Similarly, the redirection operator
- @example
- [@var{n}]>&@var{digit}-
- @end example
- @noindent
- moves the file descriptor @var{digit} to file descriptor @var{n},
- or the standard output (file descriptor 1) if @var{n} is not specified.
- @subsection Opening File Descriptors for Reading and Writing
- The redirection operator
- @example
- [@var{n}]<>@var{word}
- @end example
- @noindent
- causes the file whose name is the expansion of @var{word}
- to be opened for both reading and writing on file descriptor
- @var{n}, or on file descriptor 0 if @var{n}
- is not specified. If the file does not exist, it is created.
- @node Executing Commands
- @section Executing Commands
- @menu
- * Simple Command Expansion:: How Bash expands simple commands before
- executing them.
- * Command Search and Execution:: How Bash finds commands and runs them.
- * Command Execution Environment:: The environment in which Bash
- executes commands that are not
- shell builtins.
- * Environment:: The environment given to a command.
- * Exit Status:: The status returned by commands and how Bash
- interprets it.
- * Signals:: What happens when Bash or a command it runs
- receives a signal.
- @end menu
- @node Simple Command Expansion
- @subsection Simple Command Expansion
- @cindex command expansion
- When a simple command is executed, the shell performs the following
- expansions, assignments, and redirections, from left to right, in
- the following order.
- @enumerate
- @item
- The words that the parser has marked as variable assignments (those
- preceding the command name) and redirections are saved for later
- processing.
- @item
- The words that are not variable assignments or redirections are
- expanded (@pxref{Shell Expansions}).
- 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.
- @item
- Redirections are performed as described above (@pxref{Redirections}).
- @item
- The text after the @samp{=} in each variable assignment undergoes tilde
- expansion, parameter expansion, command substitution, arithmetic expansion,
- and quote removal before being assigned to the variable.
- @end enumerate
- 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.
- 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.
- 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.
- @node Command Search and Execution
- @subsection Command Search and Execution
- @cindex command execution
- @cindex command search
- 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.
- @enumerate
- @item
- 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 in @ref{Shell Functions}.
- @item
- 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.
- @item
- If the name is neither a shell function nor a builtin,
- and contains no slashes, Bash searches each element of
- @env{$PATH} for a directory containing an executable file
- by that name. Bash uses a hash table to remember the full
- pathnames of executable files to avoid multiple @env{PATH} searches
- (see the description of @code{hash} in @ref{Bourne Shell Builtins}).
- A full search of the directories in @env{$PATH}
- 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 @code{command_not_found_handle}.
- If that function exists, it is invoked in a separate execution environment
- with the original command and
- the original command's arguments as its arguments, and the function's
- exit status becomes the exit status of that subshell.
- If that function is not defined, the shell prints an error
- message and returns an exit status of 127.
- @item
- 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 supplied, if any.
- @item
- 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
- @var{shell script} and the shell executes it as described in
- @ref{Shell Scripts}.
- @item
- If the command was not begun asynchronously, the shell waits for
- the command to complete and collects its exit status.
- @end enumerate
- @node Command Execution Environment
- @subsection Command Execution Environment
- @cindex execution environment
- The shell has an @var{execution environment}, which consists of the
- following:
- @itemize @bullet
- @item
- open files inherited by the shell at invocation, as modified by
- redirections supplied to the @code{exec} builtin
- @item
- the current working directory as set by @code{cd}, @code{pushd}, or
- @code{popd}, or inherited by the shell at invocation
- @item
- the file creation mode mask as set by @code{umask} or inherited from
- the shell's parent
- @item
- current traps set by @code{trap}
- @item
- shell parameters that are set by variable assignment or with @code{set}
- or inherited from the shell's parent in the environment
- @item
- shell functions defined during execution or inherited from the shell's
- parent in the environment
- @item
- options enabled at invocation (either by default or with command-line
- arguments) or by @code{set}
- @item
- options enabled by @code{shopt} (@pxref{The Shopt Builtin})
- @item
- shell aliases defined with @code{alias} (@pxref{Aliases})
- @item
- various process @sc{id}s, including those of background jobs
- (@pxref{Lists}), the value of @code{$$}, and the value of
- @env{$PPID}
- @end itemize
- 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.
- @itemize @bullet
- @item
- the shell's open files, plus any modifications and additions specified
- by redirections to the command
- @item
- the current working directory
- @item
- the file creation mode mask
- @item
- shell variables and functions marked for export, along with variables
- exported for the command, passed in the environment (@pxref{Environment})
- @item
- traps caught by the shell are reset to the values inherited from the
- shell's parent, and traps ignored by the shell are ignored
- @end itemize
- A command invoked in this separate environment cannot affect the
- shell's execution environment.
- 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.
- Subshells spawned to execute command substitutions inherit the value of
- the @option{-e} option from the parent shell. When not in @sc{posix} mode,
- Bash clears the @option{-e} option in such subshells.
- If a command is followed by a @samp{&} and job control is not active, the
- default standard input for the command is the empty file @file{/dev/null}.
- Otherwise, the invoked command inherits the file descriptors of the calling
- shell as modified by redirections.
- @node Environment
- @subsection Environment
- @cindex environment
- When a program is invoked it is given an array of strings
- called the @var{environment}.
- This is a list of name-value pairs, of the form @code{name=value}.
- Bash 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 @var{export}
- to child processes. Executed commands inherit the environment.
- The @code{export} and @samp{declare -x}
- 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 @code{unset} and @samp{export -n}
- commands, plus any additions via the @code{export} and
- @samp{declare -x} commands.
- The environment for any simple command
- or function may be augmented temporarily by prefixing it with
- parameter assignments, as described in @ref{Shell Parameters}.
- These assignment statements affect only the environment seen
- by that command.
- If the @option{-k} option is set (@pxref{The Set Builtin}), then all
- parameter assignments are placed in the environment for a command,
- not just those that precede the command name.
- When Bash invokes an external command, the variable @samp{$_}
- is set to the full pathname of the command and passed to that
- command in its environment.
- @node Exit Status
- @subsection Exit Status
- @cindex exit status
- The exit status of an executed command is the value returned by the
- @var{waitpid} 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.
- For the shell's purposes, a command which exits with a
- zero exit status has succeeded.
- A non-zero exit status indicates failure.
- This seemingly counter-intuitive scheme is used so there
- is one well-defined way to indicate success and a variety of
- ways to indicate various failure modes.
- When a command terminates on a fatal signal whose number is @var{N},
- Bash uses the value 128+@var{N} as the exit status.
- 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.
- If a command fails because of an error during expansion or redirection,
- the exit status is greater than zero.
- The exit status is used by the Bash conditional commands
- (@pxref{Conditional Constructs}) and some of the list
- constructs (@pxref{Lists}).
- All of the Bash builtins return an exit status of zero if they succeed
- and a non-zero status on failure, so they may be used by the
- conditional and list constructs.
- All builtins return an exit status of 2 to indicate incorrect usage,
- generally invalid options or missing arguments.
- @node Signals
- @subsection Signals
- @cindex signal handling
- When Bash is interactive, in the absence of any traps, it ignores
- @code{SIGTERM} (so that @samp{kill 0} does not kill an interactive shell),
- and @code{SIGINT}
- is caught and handled (so that the @code{wait} builtin is interruptible).
- When Bash receives a @code{SIGINT}, it breaks out of any executing loops.
- In all cases, Bash ignores @code{SIGQUIT}.
- If job control is in effect (@pxref{Job Control}), Bash
- ignores @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
- Non-builtin commands started by Bash have signal handlers set to the
- values inherited by the shell from its parent.
- When job control is not in effect, asynchronous commands
- ignore @code{SIGINT} and @code{SIGQUIT} in addition to these inherited
- handlers.
- Commands run as a result of
- command substitution ignore the keyboard-generated job control signals
- @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
- The shell exits by default upon receipt of a @code{SIGHUP}.
- Before exiting, an interactive shell resends the @code{SIGHUP} to
- all jobs, running or stopped.
- Stopped jobs are sent @code{SIGCONT} to ensure that they receive
- the @code{SIGHUP}.
- To prevent the shell from sending the @code{SIGHUP} signal to a
- particular job, it should be removed
- from the jobs table with the @code{disown}
- builtin (@pxref{Job Control Builtins}) or marked
- to not receive @code{SIGHUP} using @code{disown -h}.
- If the @code{huponexit} shell option has been set with @code{shopt}
- (@pxref{The Shopt Builtin}), Bash sends a @code{SIGHUP} to all jobs when
- an interactive login shell exits.
- If Bash 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 Bash is waiting for an asynchronous
- command via the @code{wait} builtin, the reception of a signal for
- which a trap has been set will cause the @code{wait} builtin to return
- immediately with an exit status greater than 128, immediately after
- which the trap is executed.
- @node Shell Scripts
- @section Shell Scripts
- @cindex shell script
- A shell script is a text file containing shell commands. When such
- a file is used as the first non-option argument when invoking Bash,
- and neither the @option{-c} nor @option{-s} option is supplied
- (@pxref{Invoking Bash}),
- Bash reads and executes commands from the file, then exits. This
- mode of operation creates a non-interactive shell. The shell first
- searches for the file in the current directory, and looks in the
- directories in @env{$PATH} if not found there.
- When Bash runs
- a shell script, it sets the special parameter @code{0} to the name
- of the file, rather than the name of the shell, and the positional
- parameters are set to the remaining arguments, if any are given.
- If no additional arguments are supplied, the positional parameters
- are unset.
- A shell script may be made executable by using the @code{chmod} command
- to turn on the execute bit. When Bash finds such a file while
- searching the @env{$PATH} for a command, it spawns a subshell to
- execute it. In other words, executing
- @example
- filename @var{arguments}
- @end example
- @noindent
- is equivalent to executing
- @example
- bash filename @var{arguments}
- @end example
- @noindent
- if @code{filename} is an executable shell script.
- This subshell reinitializes itself, so that the effect is as if a
- new shell had been invoked to interpret the script, with the
- exception that the locations of commands remembered by the parent
- (see the description of @code{hash} in @ref{Bourne Shell Builtins})
- are retained by the child.
- Most versions of Unix make this a part of the operating system's command
- execution mechanism. If the first line of a script begins with
- the two characters @samp{#!}, the remainder of the line specifies
- an interpreter for the program and, depending on the operating system, one
- or more optional arguments for that interpreter.
- Thus, you can specify Bash, @code{awk}, Perl, or some other
- interpreter and write the rest of the script file in that language.
- The arguments to the interpreter
- consist of one or more optional arguments following the interpreter
- name on the first line of the script file, followed by the name of
- the script file, followed by the rest of the arguments supplied to the
- script.
- The details of how the interpreter line is split into an interpreter name
- and a set of arguments vary across systems.
- Bash will perform this action on operating systems that do not handle it
- themselves.
- Note that some older versions of Unix limit the interpreter
- name and a single argument to a maximum of 32 characters, so it's not
- portable to assume that using more than one argument will work.
- Bash scripts often begin with @code{#! /bin/bash} (assuming that
- Bash has been installed in @file{/bin}), since this ensures that
- Bash will be used to interpret the script, even if it is executed
- under another shell. It's a common idiom to use @code{env} to find
- @code{bash} even if it's been installed in another directory:
- @code{#!/usr/bin/env bash} will find the first occurrence of @code{bash}
- in @env{$PATH}.
- @node Shell Builtin Commands
- @chapter Shell Builtin Commands
- @menu
- * Bourne Shell Builtins:: Builtin commands inherited from the Bourne
- Shell.
- * Bash Builtins:: Table of builtins specific to Bash.
- * Modifying Shell Behavior:: Builtins to modify shell attributes and
- optional behavior.
- * Special Builtins:: Builtin commands classified specially by
- POSIX.
- @end menu
- Builtin commands are contained within the shell itself.
- When the name of a builtin command is used as the first word of
- a simple command (@pxref{Simple Commands}), the shell executes
- the command directly, without invoking another program.
- Builtin commands are necessary to implement functionality impossible
- or inconvenient to obtain with separate utilities.
- This section briefly describes the builtins which Bash inherits from
- the Bourne Shell, as well as the builtin commands which are unique
- to or have been extended in Bash.
- Several builtin commands are described in other chapters: builtin
- commands which provide the Bash interface to the job control
- facilities (@pxref{Job Control Builtins}), the directory stack
- (@pxref{Directory Stack Builtins}), the command history
- (@pxref{Bash History Builtins}), and the programmable completion
- facilities (@pxref{Programmable Completion Builtins}).
- Many of the builtins have been extended by @sc{posix} or Bash.
- Unless otherwise noted, each builtin command documented as accepting
- options preceded by @samp{-} accepts @samp{--}
- to signify the end of the options.
- The @code{:}, @code{true}, @code{false}, and @code{test}/@code{[}
- builtins do not accept options and do not treat @samp{--} specially.
- The @code{exit}, @code{logout}, @code{return},
- @code{break}, @code{continue}, @code{let},
- and @code{shift} builtins accept and process arguments beginning
- with @samp{-} without requiring @samp{--}.
- Other builtins that accept arguments but are not specified as accepting
- options interpret arguments beginning with @samp{-} as invalid options and
- require @samp{--} to prevent this interpretation.
- @node Bourne Shell Builtins
- @section Bourne Shell Builtins
- The following shell builtin commands are inherited from the Bourne Shell.
- These commands are implemented as specified by the @sc{posix} standard.
- @table @code
- @item : @r{(a colon)}
- @btindex :
- @example
- : [@var{arguments}]
- @end example
- Do nothing beyond expanding @var{arguments} and performing redirections.
- The return status is zero.
- @item . @r{(a period)}
- @btindex .
- @example
- . @var{filename} [@var{arguments}]
- @end example
- Read and execute commands from the @var{filename} argument in the
- current shell context. If @var{filename} does not contain a slash,
- the @env{PATH} variable is used to find @var{filename}.
- When Bash is not in @sc{posix} mode, the current directory is searched
- if @var{filename} is not found in @env{$PATH}.
- If any @var{arguments} are supplied, they become the positional
- parameters when @var{filename} is executed. Otherwise the positional
- parameters are unchanged.
- If the @option{-T} option is enabled, @code{source} inherits any trap on
- @code{DEBUG}; if it is not, any @code{DEBUG} trap string is saved and
- restored around the call to @code{source}, and @code{source} unsets the
- @code{DEBUG} trap while it executes.
- If @option{-T} is not set, and the sourced file changes
- the @code{DEBUG} trap, the new value is retained when @code{source} completes.
- The return status is the exit status of the last command executed, or
- zero if no commands are executed. If @var{filename} is not found, or
- cannot be read, the return status is non-zero.
- This builtin is equivalent to @code{source}.
- @item break
- @btindex break
- @example
- break [@var{n}]
- @end example
- Exit from a @code{for}, @code{while}, @code{until}, or @code{select} loop.
- If @var{n} is supplied, the @var{n}th enclosing loop is exited.
- @var{n} must be greater than or equal to 1.
- The return status is zero unless @var{n} is not greater than or equal to 1.
- @item cd
- @btindex cd
- @example
- cd [-L|[-P [-e]] [-@@] [@var{directory}]
- @end example
- Change the current working directory to @var{directory}.
- If @var{directory} is not supplied, the value of the @env{HOME}
- shell variable is used.
- Any additional arguments following @var{directory} are ignored.
- If the shell variable
- @env{CDPATH} exists, it is used as a search path:
- each directory name in @env{CDPATH} is searched for
- @var{directory}, with alternative directory names in @env{CDPATH}
- separated by a colon (@samp{:}).
- If @var{directory} begins with a slash, @env{CDPATH} is not used.
- The @option{-P} option means to not follow symbolic links: symbolic links
- are resolved while @code{cd} is traversing @var{directory} and before
- processing an instance of @samp{..} in @var{directory}.
- By default, or when the @option{-L} option is supplied, symbolic links
- in @var{directory} are resolved after @code{cd} processes an instance
- of @samp{..} in @var{directory}.
- If @samp{..} appears in @var{directory}, it is processed by removing the
- immediately preceding pathname component, back to a slash or the beginning
- of @var{directory}.
- If the @option{-e} option is supplied with @option{-P}
- and the current working directory cannot be successfully determined
- after a successful directory change, @code{cd} will return an unsuccessful
- status.
- On systems that support it, the @option{-@@} option presents the extended
- attributes associated with a file as a directory.
- If @var{directory} is @samp{-}, it is converted to @env{$OLDPWD}
- before the directory change is attempted.
- If a non-empty directory name from @env{CDPATH} is used, or if
- @samp{-} 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 status is zero if the directory is successfully changed,
- non-zero otherwise.
- @item continue
- @btindex continue
- @example
- continue [@var{n}]
- @end example
- Resume the next iteration of an enclosing @code{for}, @code{while},
- @code{until}, or @code{select} loop.
- If @var{n} is supplied, the execution of the @var{n}th enclosing loop
- is resumed.
- @var{n} must be greater than or equal to 1.
- The return status is zero unless @var{n} is not greater than or equal to 1.
- @item eval
- @btindex eval
- @example
- eval [@var{arguments}]
- @end example
- The arguments are concatenated together into a single command, which is
- then read and executed, and its exit status returned as the exit status
- of @code{eval}.
- If there are no arguments or only empty arguments, the return status is
- zero.
- @item exec
- @btindex exec
- @example
- exec [-cl] [-a @var{name}] [@var{command} [@var{arguments}]]
- @end example
- If @var{command}
- is supplied, it replaces the shell without creating a new process.
- If the @option{-l} option is supplied, the shell places a dash at the
- beginning of the zeroth argument passed to @var{command}.
- This is what the @code{login} program does.
- The @option{-c} option causes @var{command} to be executed with an empty
- environment.
- If @option{-a} is supplied, the shell passes @var{name} as the zeroth
- argument to @var{command}.
- If @var{command}
- cannot be executed for some reason, a non-interactive shell exits,
- unless the @code{execfail} shell option
- is enabled. In that case, it returns failure.
- An interactive shell returns failure if the file cannot be executed.
- A subshell exits unconditionally if @code{exec} fails.
- If no @var{command} is specified, redirections may be used to affect
- the current shell environment. If there are no redirection errors, the
- return status is zero; otherwise the return status is non-zero.
- @item exit
- @btindex exit
- @example
- exit [@var{n}]
- @end example
- Exit the shell, returning a status of @var{n} to the shell's parent.
- If @var{n} is omitted, the exit status is that of the last command executed.
- Any trap on @code{EXIT} is executed before the shell terminates.
- @item export
- @btindex export
- @example
- export [-fn] [-p] [@var{name}[=@var{value}]]
- @end example
- Mark each @var{name} to be passed to child processes
- in the environment. If the @option{-f} option is supplied, the @var{name}s
- refer to shell functions; otherwise the names refer to shell variables.
- The @option{-n} option means to no longer mark each @var{name} for export.
- If no @var{names} are supplied, or if the @option{-p} option is given, a
- list of names of all exported variables is displayed.
- The @option{-p} option displays output in a form that may be reused as input.
- If a variable name is followed by =@var{value}, the value of
- the variable is set to @var{value}.
- The return status is zero unless an invalid option is supplied, one of
- the names is not a valid shell variable name, or @option{-f} is supplied
- with a name that is not a shell function.
- @item getopts
- @btindex getopts
- @example
- getopts @var{optstring} @var{name} [@var{arg} @dots{}]
- @end example
- @code{getopts} is used by shell scripts to parse positional parameters.
- @var{optstring} 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 whitespace.
- The colon (@samp{:}) and question mark (@samp{?}) may not be
- used as option characters.
- Each time it is invoked, @code{getopts}
- places the next option in the shell variable @var{name}, initializing
- @var{name} if it does not exist,
- and the index of the next argument to be processed into the
- variable @env{OPTIND}.
- @env{OPTIND} is initialized to 1 each time the shell or a shell script
- is invoked.
- When an option requires an argument,
- @code{getopts} places that argument into the variable @env{OPTARG}.
- The shell does not reset @env{OPTIND} automatically; it must be manually
- reset between multiple calls to @code{getopts} within the same shell
- invocation if a new set of parameters is to be used.
- When the end of options is encountered, @code{getopts} exits with a
- return value greater than zero.
- @env{OPTIND} is set to the index of the first non-option argument,
- and @var{name} is set to @samp{?}.
- @code{getopts}
- normally parses the positional parameters, but if more arguments are
- supplied as @var{arg} values, @code{getopts} parses those instead.
- @code{getopts} can report errors in two ways. If the first character of
- @var{optstring} is a colon, @var{silent}
- error reporting is used. In normal operation, diagnostic messages
- are printed when invalid options or missing option arguments are
- encountered.
- If the variable @env{OPTERR}
- is set to 0, no error messages will be displayed, even if the first
- character of @code{optstring} is not a colon.
- If an invalid option is seen,
- @code{getopts} places @samp{?} into @var{name} and, if not silent,
- prints an error message and unsets @env{OPTARG}.
- If @code{getopts} is silent, the option character found is placed in
- @env{OPTARG} and no diagnostic message is printed.
- If a required argument is not found, and @code{getopts}
- is not silent, a question mark (@samp{?}) is placed in @var{name},
- @code{OPTARG} is unset, and a diagnostic message is printed.
- If @code{getopts} is silent, then a colon (@samp{:}) is placed in
- @var{name} and @env{OPTARG} is set to the option character found.
- @item hash
- @btindex hash
- @example
- hash [-r] [-p @var{filename}] [-dt] [@var{name}]
- @end example
- Each time @code{hash} is invoked, it remembers the full pathnames of the
- commands specified as @var{name} arguments,
- so they need not be searched for on subsequent invocations.
- The commands are found by searching through the directories listed in
- @env{$PATH}.
- Any previously-remembered pathname is discarded.
- The @option{-p} option inhibits the path search, and @var{filename} is
- used as the location of @var{name}.
- The @option{-r} option causes the shell to forget all remembered locations.
- The @option{-d} option causes the shell to forget the remembered location
- of each @var{name}.
- If the @option{-t} option is supplied, the full pathname to which each
- @var{name} corresponds is printed. If multiple @var{name} arguments are
- supplied with @option{-t}, the @var{name} is printed before the hashed
- full pathname.
- The @option{-l} option causes output to be displayed in a format
- that may be reused as input.
- If no arguments are given, or if only @option{-l} is supplied,
- information about remembered commands is printed.
- The return status is zero unless a @var{name} is not found or an invalid
- option is supplied.
- @item pwd
- @btindex pwd
- @example
- pwd [-LP]
- @end example
- Print the absolute pathname of the current working directory.
- If the @option{-P} option is supplied, the pathname printed will not
- contain symbolic links.
- If the @option{-L} option is supplied, the pathname printed may contain
- symbolic links.
- The return status is zero unless an error is encountered while
- determining the name of the current directory or an invalid option
- is supplied.
- @item readonly
- @btindex readonly
- @example
- readonly [-aAf] [-p] [@var{name}[=@var{value}]] @dots{}
- @end example
- Mark each @var{name} as readonly.
- The values of these names may not be changed by subsequent assignment.
- If the @option{-f} option is supplied, each @var{name} refers to a shell
- function.
- The @option{-a} option means each @var{name} refers to an indexed
- array variable; the @option{-A} option means each @var{name} refers
- to an associative array variable.
- If both options are supplied, @option{-A} takes precedence.
- If no @var{name} arguments are given, or if the @option{-p}
- 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 @option{-p} option causes output to be displayed in a format that
- may be reused as input.
- If a variable name is followed by =@var{value}, the value of
- the variable is set to @var{value}.
- The return status is zero unless an invalid option is supplied, one of
- the @var{name} arguments is not a valid shell variable or function name,
- or the @option{-f} option is supplied with a name that is not a shell function.
- @item return
- @btindex return
- @example
- return [@var{n}]
- @end example
- Cause a shell function to stop executing and return the value @var{n}
- to its caller.
- If @var{n} is not supplied, the return value is the exit status of the
- last command executed in the function.
- If @code{return} is executed by a trap handler, the last command used to
- determine the status is the last command executed before the trap handler.
- If @code{return} is executed during a @code{DEBUG} trap, the last command
- used to determine the status is the last command executed by the trap
- handler before @code{return} was invoked.
- @code{return} may also be used to terminate execution of a script
- being executed with the @code{.} (@code{source}) builtin,
- returning either @var{n} or
- the exit status of the last command executed within the script as the exit
- status of the script.
- If @var{n} is supplied, the return value is its least significant
- 8 bits.
- Any command associated with the @code{RETURN} trap is executed
- before execution resumes after the function or script.
- The return status is non-zero if @code{return} is supplied a non-numeric
- argument or is used outside a function
- and not during the execution of a script by @code{.} or @code{source}.
- @item shift
- @btindex shift
- @example
- shift [@var{n}]
- @end example
- Shift the positional parameters to the left by @var{n}.
- The positional parameters from @var{n}+1 @dots{} @code{$#} are
- renamed to @code{$1} @dots{} @code{$#}-@var{n}.
- Parameters represented by the numbers @code{$#} down to @code{$#}-@var{n}+1
- are unset.
- @var{n} must be a non-negative number less than or equal to @code{$#}.
- If @var{n} is zero or greater than @code{$#}, the positional parameters
- are not changed.
- If @var{n} is not supplied, it is assumed to be 1.
- The return status is zero unless @var{n} is greater than @code{$#} or
- less than zero, non-zero otherwise.
- @item test
- @itemx [
- @btindex test
- @btindex [
- @example
- test @var{expr}
- @end example
- Evaluate a conditional expression @var{expr} and return a status of 0
- (true) or 1 (false).
- Each operator and operand must be a separate argument.
- Expressions are composed of the primaries described below in
- @ref{Bash Conditional Expressions}.
- @code{test} does not accept any options, nor does it accept and ignore
- an argument of @option{--} as signifying the end of options.
- When the @code{[} form is used, the last argument to the command must
- be a @code{]}.
- 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.
- @table @code
- @item ! @var{expr}
- True if @var{expr} is false.
- @item ( @var{expr} )
- Returns the value of @var{expr}.
- This may be used to override the normal precedence of operators.
- @item @var{expr1} -a @var{expr2}
- True if both @var{expr1} and @var{expr2} are true.
- @item @var{expr1} -o @var{expr2}
- True if either @var{expr1} or @var{expr2} is true.
- @end table
- The @code{test} and @code{[} builtins evaluate conditional
- expressions using a set of rules based on the number of arguments.
- @table @asis
- @item 0 arguments
- The expression is false.
- @item 1 argument
- The expression is true if, and only if, the argument is not null.
- @item 2 arguments
- If the first argument is @samp{!}, the expression is true if and
- only if the second argument is null.
- If the first argument is one of the unary conditional operators
- (@pxref{Bash Conditional Expressions}), the expression
- is true if the unary test is true.
- If the first argument is not a valid unary operator, the expression is
- false.
- @item 3 arguments
- The following conditions are applied in the order listed.
- @enumerate
- @item
- If the second argument is one of the binary conditional
- operators (@pxref{Bash Conditional Expressions}), the
- result of the expression is the result of the binary test using the
- first and third arguments as operands.
- The @samp{-a} and @samp{-o} operators are considered binary operators
- when there are three arguments.
- @item
- If the first argument is @samp{!}, the value is the negation of
- the two-argument test using the second and third arguments.
- @item
- If the first argument is exactly @samp{(} and the third argument is
- exactly @samp{)}, the result is the one-argument test of the second
- argument.
- @item
- Otherwise, the expression is false.
- @end enumerate
- @item 4 arguments
- If the first argument is @samp{!}, 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.
- @item 5 or more arguments
- The expression is parsed and evaluated according to precedence
- using the rules listed above.
- @end table
- When used with @code{test} or @samp{[}, the @samp{<} and @samp{>}
- operators sort lexicographically using ASCII ordering.
- @item times
- @btindex times
- @example
- times
- @end example
- Print out the user and system times used by the shell and its children.
- The return status is zero.
- @item trap
- @btindex trap
- @example
- trap [-lp] [@var{arg}] [@var{sigspec} @dots{}]
- @end example
- The commands in @var{arg} are to be read and executed when the
- shell receives signal @var{sigspec}. If @var{arg} is absent (and
- there is a single @var{sigspec}) or
- equal to @samp{-}, each specified signal's disposition is reset
- to the value it had when the shell was started.
- If @var{arg} is the null string, then the signal specified by
- each @var{sigspec} is ignored by the shell and commands it invokes.
- If @var{arg} is not present and @option{-p} has been supplied,
- the shell displays the trap commands associated with each @var{sigspec}.
- If no arguments are supplied, or
- only @option{-p} is given, @code{trap} prints the list of commands
- associated with each signal number in a form that may be reused as
- shell input.
- The @option{-l} option causes the shell to print a list of signal names
- and their corresponding numbers.
- Each @var{sigspec} is either a signal name or a signal number.
- Signal names are case insensitive and the @code{SIG} prefix is optional.
- If a @var{sigspec}
- is @code{0} or @code{EXIT}, @var{arg} is executed when the shell exits.
- If a @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed
- before every simple command, @code{for} command, @code{case} command,
- @code{select} command, every arithmetic @code{for} command, and before
- the first command executes in a shell function.
- Refer to the description of the @code{extdebug} option to the
- @code{shopt} builtin (@pxref{The Shopt Builtin}) for details of its
- effect on the @code{DEBUG} trap.
- If a @var{sigspec} is @code{RETURN}, the command @var{arg} is executed
- each time a shell function or a script executed with the @code{.} or
- @code{source} builtins finishes executing.
- If a @var{sigspec} is @code{ERR}, the command @var{arg}
- 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 @code{ERR} trap is not executed if the failed command is part of the
- command list immediately following an @code{until} or @code{while} keyword,
- part of the test following the @code{if} or @code{elif} reserved words,
- part of a command executed in a @code{&&} or @code{||} list
- except the command following the final @code{&&} or @code{||},
- any command in a pipeline but the last,
- or if the command's return
- status is being inverted using @code{!}.
- These are the same conditions obeyed by the @code{errexit} (@option{-e})
- option.
- 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 zero unless a @var{sigspec} does not specify a
- valid signal.
- @item umask
- @btindex umask
- @example
- umask [-p] [-S] [@var{mode}]
- @end example
- Set the shell process's file creation mask to @var{mode}. If
- @var{mode} begins with a digit, it is interpreted as an octal number;
- if not, it is interpreted as a symbolic mode mask similar
- to that accepted by the @code{chmod} command. If @var{mode} is
- omitted, the current value of the mask is printed. If the @option{-S}
- option is supplied without a @var{mode} argument, the mask is printed
- in a symbolic format.
- If the @option{-p} option is supplied, and @var{mode}
- is omitted, the output is in a form that may be reused as input.
- The return status is zero if the mode is successfully changed or if
- no @var{mode} argument is supplied, and non-zero otherwise.
- Note that when the mode is interpreted as an octal number, each number
- of the umask is subtracted from @code{7}. Thus, a umask of @code{022}
- results in permissions of @code{755}.
- @item unset
- @btindex unset
- @example
- unset [-fnv] [@var{name}]
- @end example
- Remove each variable or function @var{name}.
- If the @option{-v} option is given, each
- @var{name} refers to a shell variable and that variable is removed.
- If the @option{-f} option is given, the @var{name}s refer to shell
- functions, and the function definition is removed.
- If the @option{-n} option is supplied, and @var{name} is a variable with
- the @var{nameref} attribute, @var{name} will be unset rather than the
- variable it references.
- @option{-n} has no effect if the @option{-f} option is supplied.
- If no options are supplied, each @var{name} refers to a variable; if
- there is no variable by that name, a function with that name, if any, is
- unset.
- Readonly variables and functions may not be unset.
- Some shell variables lose their special behavior if they are unset; such
- behavior is noted in the description of the individual variables.
- The return status is zero unless a @var{name} is readonly.
- @end table
- @node Bash Builtins
- @section Bash Builtin Commands
- This section describes builtin commands which are unique to
- or have been extended in Bash.
- Some of these commands are specified in the @sc{posix} standard.
- @table @code
- @item alias
- @btindex alias
- @example
- alias [-p] [@var{name}[=@var{value}] @dots{}]
- @end example
- Without arguments or with the @option{-p} option, @code{alias} prints
- the list of aliases on the standard output in a form that allows
- them to be reused as input.
- If arguments are supplied, an alias is defined for each @var{name}
- whose @var{value} is given. If no @var{value} is given, the name
- and value of the alias is printed.
- Aliases are described in @ref{Aliases}.
- @item bind
- @btindex bind
- @example
- bind [-m @var{keymap}] [-lpsvPSVX]
- bind [-m @var{keymap}] [-q @var{function}] [-u @var{function}] [-r @var{keyseq}]
- bind [-m @var{keymap}] -f @var{filename}
- bind [-m @var{keymap}] -x @var{keyseq:shell-command}
- bind [-m @var{keymap}] @var{keyseq:function-name}
- bind [-m @var{keymap}] @var{keyseq:readline-command}
- @end example
- Display current Readline (@pxref{Command Line Editing})
- key and function bindings,
- bind a key sequence to a Readline function or macro,
- or set a Readline variable.
- Each non-option argument is a command as it would appear in a
- Readline initialization file (@pxref{Readline Init File}),
- but each binding or command must be passed as a separate argument; e.g.,
- @samp{"\C-x\C-r":re-read-init-file}.
- Options, if supplied, have the following meanings:
- @table @code
- @item -m @var{keymap}
- Use @var{keymap} as the keymap to be affected by
- the subsequent bindings. Acceptable @var{keymap}
- names are
- @code{emacs},
- @code{emacs-standard},
- @code{emacs-meta},
- @code{emacs-ctlx},
- @code{vi},
- @code{vi-move},
- @code{vi-command}, and
- @code{vi-insert}.
- @code{vi} is equivalent to @code{vi-command} (@code{vi-move} is also a
- synonym); @code{emacs} is equivalent to @code{emacs-standard}.
- @item -l
- List the names of all Readline functions.
- @item -p
- Display Readline function names and bindings in such a way that they
- can be used as input or in a Readline initialization file.
- @item -P
- List current Readline function names and bindings.
- @item -v
- Display Readline variable names and values in such a way that they
- can be used as input or in a Readline initialization file.
- @item -V
- List current Readline variable names and values.
- @item -s
- Display Readline key sequences bound to macros and the strings they output
- in such a way that they can be used as input or in a Readline
- initialization file.
- @item -S
- Display Readline key sequences bound to macros and the strings they output.
- @item -f @var{filename}
- Read key bindings from @var{filename}.
- @item -q @var{function}
- Query about which keys invoke the named @var{function}.
- @item -u @var{function}
- Unbind all keys bound to the named @var{function}.
- @item -r @var{keyseq}
- Remove any current binding for @var{keyseq}.
- @item -x @var{keyseq:shell-command}
- Cause @var{shell-command} to be executed whenever @var{keyseq} is
- entered.
- When @var{shell-command} is executed, the shell sets the
- @code{READLINE_LINE} variable to the contents of the Readline line
- buffer and the @code{READLINE_POINT} and @code{READLINE_MARK} variables
- to the current location of the insertion point and the saved insertion
- point (the @var{mark}), respectively.
- If the executed command changes the value of any of @code{READLINE_LINE},
- @code{READLINE_POINT}, or @code{READLINE_MARK}, those new values will be
- reflected in the editing state.
- @item -X
- List all key sequences bound to shell commands and the associated commands
- in a format that can be reused as input.
- @end table
- @noindent
- The return status is zero unless an invalid option is supplied or an
- error occurs.
- @item builtin
- @btindex builtin
- @example
- builtin [@var{shell-builtin} [@var{args}]]
- @end example
- Run a shell builtin, passing it @var{args}, and return its exit status.
- This is useful when defining a shell function with the same
- name as a shell builtin, retaining the functionality of the builtin within
- the function.
- The return status is non-zero if @var{shell-builtin} is not a shell
- builtin command.
- @item caller
- @btindex caller
- @example
- caller [@var{expr}]
- @end example
- Returns the context of any active subroutine call (a shell function or
- a script executed with the @code{.} or @code{source} builtins).
- Without @var{expr}, @code{caller} displays the line number and source
- filename of the current subroutine call.
- If a non-negative integer is supplied as @var{expr}, @code{caller}
- 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 @var{expr} does not correspond to a valid position in the
- call stack.
- @item command
- @btindex command
- @example
- command [-pVv] @var{command} [@var{arguments} @dots{}]
- @end example
- Runs @var{command} with @var{arguments} ignoring any shell function
- named @var{command}.
- Only shell builtin commands or commands found by searching the
- @env{PATH} are executed.
- If there is a shell function named @code{ls}, running @samp{command ls}
- within the function will execute the external command @code{ls}
- instead of calling the function recursively.
- The @option{-p} option means to use a default value for @env{PATH}
- that is guaranteed to find all of the standard utilities.
- The return status in this case is 127 if @var{command} cannot be
- found or an error occurred, and the exit status of @var{command}
- otherwise.
- If either the @option{-V} or @option{-v} option is supplied, a
- description of @var{command} is printed. The @option{-v} option
- causes a single word indicating the command or file name used to
- invoke @var{command} to be displayed; the @option{-V} option produces
- a more verbose description. In this case, the return status is
- zero if @var{command} is found, and non-zero if not.
- @item declare
- @btindex declare
- @example
- declare [-aAfFgiIlnrtux] [-p] [@var{name}[=@var{value}] @dots{}]
- @end example
- Declare variables and give them attributes. If no @var{name}s
- are given, then display the values of variables instead.
- The @option{-p} option will display the attributes and values of each
- @var{name}.
- When @option{-p} is used with @var{name} arguments, additional options,
- other than @option{-f} and @option{-F}, are ignored.
- When @option{-p} is supplied without @var{name} arguments, @code{declare}
- will display the attributes and values of all variables having the
- attributes specified by the additional options.
- If no other options are supplied with @option{-p}, @code{declare} will
- display the attributes and values of all shell variables. The @option{-f}
- option will restrict the display to shell functions.
- The @option{-F} option inhibits the display of function definitions;
- only the function name and attributes are printed.
- If the @code{extdebug} shell option is enabled using @code{shopt}
- (@pxref{The Shopt Builtin}), the source file name and line number where
- each @var{name} is defined are displayed as well.
- @option{-F} implies @option{-f}.
- The @option{-g} option forces variables to be created or modified at
- the global scope, even when @code{declare} is executed in a shell function.
- It is ignored in all other cases.
- The @option{-I} option causes local variables to inherit the attributes
- (except the @var{nameref} attribute)
- and value of any existing variable with the same
- @var{name} at a surrounding scope.
- If there is no existing variable, the local variable is initially unset.
- The following options can be used to restrict output to variables with
- the specified attributes or to give variables attributes:
- @table @code
- @item -a
- Each @var{name} is an indexed array variable (@pxref{Arrays}).
- @item -A
- Each @var{name} is an associative array variable (@pxref{Arrays}).
- @item -f
- Use function names only.
- @item -i
- The variable is to be treated as
- an integer; arithmetic evaluation (@pxref{Shell Arithmetic}) is
- performed when the variable is assigned a value.
- @item -l
- When the variable is assigned a value, all upper-case characters are
- converted to lower-case.
- The upper-case attribute is disabled.
- @item -n
- Give each @var{name} the @var{nameref} attribute, making
- it a name reference to another variable.
- That other variable is defined by the value of @var{name}.
- All references, assignments, and attribute modifications
- to @var{name}, except for those using or changing the
- @option{-n} attribute itself, are performed on the variable referenced by
- @var{name}'s value.
- The nameref attribute cannot be applied to array variables.
- @item -r
- Make @var{name}s readonly. These names cannot then be assigned values
- by subsequent assignment statements or unset.
- @item -t
- Give each @var{name} the @code{trace} attribute.
- Traced functions inherit the @code{DEBUG} and @code{RETURN} traps from
- the calling shell.
- The trace attribute has no special meaning for variables.
- @item -u
- When the variable is assigned a value, all lower-case characters are
- converted to upper-case.
- The lower-case attribute is disabled.
- @item -x
- Mark each @var{name} for export to subsequent commands via
- the environment.
- @end table
- Using @samp{+} instead of @samp{-} turns off the attribute instead,
- with the exceptions that @samp{+a} and @samp{+A}
- may not be used to destroy array variables and @samp{+r} will not
- remove the readonly attribute.
- When used in a function, @code{declare} makes each @var{name} local,
- as with the @code{local} command, unless the @option{-g} option is used.
- If a variable name is followed by =@var{value}, the value of the variable
- is set to @var{value}.
- When using @option{-a} or @option{-A} and the compound assignment syntax to
- create array variables, additional attributes do not take effect until
- subsequent assignments.
- The return status is zero unless an invalid option is encountered,
- an attempt is made to define a function using @samp{-f foo=bar},
- 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 (@pxref{Arrays}),
- one of the @var{names} 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 @option{-f}.
- @item echo
- @btindex echo
- @example
- echo [-neE] [@var{arg} @dots{}]
- @end example
- Output the @var{arg}s, separated by spaces, terminated with a
- newline.
- The return status is 0 unless a write error occurs.
- If @option{-n} is specified, the trailing newline is suppressed.
- If the @option{-e} option is given, interpretation of the following
- backslash-escaped characters is enabled.
- The @option{-E} option disables the interpretation of these escape characters,
- even on systems where they are interpreted by default.
- The @code{xpg_echo} shell option may be used to
- dynamically determine whether or not @code{echo} expands these
- escape characters by default.
- @code{echo} does not interpret @option{--} to mean the end of options.
- @code{echo} interprets the following escape sequences:
- @table @code
- @item \a
- alert (bell)
- @item \b
- backspace
- @item \c
- suppress further output
- @item \e
- @itemx \E
- escape
- @item \f
- form feed
- @item \n
- new line
- @item \r
- carriage return
- @item \t
- horizontal tab
- @item \v
- vertical tab
- @item \\
- backslash
- @item \0@var{nnn}
- the eight-bit character whose value is the octal value @var{nnn}
- (zero to three octal digits)
- @item \x@var{HH}
- the eight-bit character whose value is the hexadecimal value @var{HH}
- (one or two hex digits)
- @item \u@var{HHHH}
- the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
- @var{HHHH} (one to four hex digits)
- @item \U@var{HHHHHHHH}
- the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value
- @var{HHHHHHHH} (one to eight hex digits)
- @end table
- @item enable
- @btindex enable
- @example
- enable [-a] [-dnps] [-f @var{filename}] [@var{name} @dots{}]
- @end example
- 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 @option{-n} is used, the @var{name}s become disabled. Otherwise
- @var{name}s are enabled. For example, to use the @code{test} binary
- found via @env{$PATH} instead of the shell builtin version, type
- @samp{enable -n test}.
- If the @option{-p} option is supplied, or no @var{name} arguments appear,
- a list of shell builtins is printed. With no other arguments, the list
- consists of all enabled shell builtins.
- The @option{-a} option means to list
- each builtin with an indication of whether or not it is enabled.
- The @option{-f} option means to load the new builtin command @var{name}
- from shared object @var{filename}, on systems that support dynamic loading.
- The @option{-d} option will delete a builtin loaded with @option{-f}.
- If there are no options, a list of the shell builtins is displayed.
- The @option{-s} option restricts @code{enable} to the @sc{posix} special
- builtins. If @option{-s} is used with @option{-f}, the new builtin becomes
- a special builtin (@pxref{Special Builtins}).
- The return status is zero unless a @var{name} is not a shell builtin
- or there is an error loading a new builtin from a shared object.
- @item help
- @btindex help
- @example
- help [-dms] [@var{pattern}]
- @end example
- Display helpful information about builtin commands.
- If @var{pattern} is specified, @code{help} gives detailed help
- on all commands matching @var{pattern}, otherwise a list of
- the builtins is printed.
- Options, if supplied, have the following meanings:
- @table @code
- @item -d
- Display a short description of each @var{pattern}
- @item -m
- Display the description of each @var{pattern} in a manpage-like format
- @item -s
- Display only a short usage synopsis for each @var{pattern}
- @end table
- The return status is zero unless no command matches @var{pattern}.
- @item let
- @btindex let
- @example
- let @var{expression} [@var{expression} @dots{}]
- @end example
- The @code{let} builtin allows arithmetic to be performed on shell
- variables. Each @var{expression} is evaluated according to the
- rules given below in @ref{Shell Arithmetic}. If the
- last @var{expression} evaluates to 0, @code{let} returns 1;
- otherwise 0 is returned.
- @item local
- @btindex local
- @example
- local [@var{option}] @var{name}[=@var{value}] @dots{}
- @end example
- For each argument, a local variable named @var{name} is created,
- and assigned @var{value}.
- The @var{option} can be any of the options accepted by @code{declare}.
- @code{local} can only be used within a function; it makes the variable
- @var{name} have a visible scope restricted to that function and its
- children.
- If @var{name} is @samp{-}, the set of shell options is made local to the
- function in which @code{local} is invoked: shell options changed using
- the @code{set} builtin inside the function are restored to their original
- values when the function returns.
- The restore is effected as if a series of @code{set} commands were executed
- to restore the values that were in place before the function.
- The return status is zero unless @code{local} is used outside
- a function, an invalid @var{name} is supplied, or @var{name} is a
- readonly variable.
- @item logout
- @btindex logout
- @example
- logout [@var{n}]
- @end example
- Exit a login shell, returning a status of @var{n} to the shell's
- parent.
- @item mapfile
- @btindex mapfile
- @example
- mapfile [-d @var{delim}] [-n @var{count}] [-O @var{origin}] [-s @var{count}]
- [-t] [-u @var{fd}] [-C @var{callback}] [-c @var{quantum}] [@var{array}]
- @end example
- Read lines from the standard input into the indexed array variable @var{array},
- or from file descriptor @var{fd}
- if the @option{-u} option is supplied.
- The variable @code{MAPFILE} is the default @var{array}.
- Options, if supplied, have the following meanings:
- @table @code
- @item -d
- The first character of @var{delim} is used to terminate each input line,
- rather than newline.
- If @var{delim} is the empty string, @code{mapfile} will terminate a line
- when it reads a NUL character.
- @item -n
- Copy at most @var{count} lines. If @var{count} is 0, all lines are copied.
- @item -O
- Begin assigning to @var{array} at index @var{origin}.
- The default index is 0.
- @item -s
- Discard the first @var{count} lines read.
- @item -t
- Remove a trailing @var{delim} (default newline) from each line read.
- @item -u
- Read lines from file descriptor @var{fd} instead of the standard input.
- @item -C
- Evaluate @var{callback} each time @var{quantum} lines are read.
- The @option{-c} option specifies @var{quantum}.
- @item -c
- Specify the number of lines read between each call to @var{callback}.
- @end table
- If @option{-C} is specified without @option{-c},
- the default quantum is 5000.
- When @var{callback} 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.
- @var{callback} is evaluated after the line is read but before the
- array element is assigned.
- If not supplied with an explicit origin, @code{mapfile} will clear @var{array}
- before assigning to it.
- @code{mapfile} returns successfully unless an invalid option or option
- argument is supplied, @var{array} is invalid or unassignable, or @var{array}
- is not an indexed array.
- @item printf
- @btindex printf
- @example
- printf [-v @var{var}] @var{format} [@var{arguments}]
- @end example
- Write the formatted @var{arguments} to the standard output under the
- control of the @var{format}.
- The @option{-v} option causes the output to be assigned to the variable
- @var{var} rather than being printed to the standard output.
- The @var{format} 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
- @var{argument}.
- In addition to the standard @code{printf(1)} formats, @code{printf}
- interprets the following extensions:
- @table @code
- @item %b
- Causes @code{printf} to expand backslash escape sequences in the
- corresponding @var{argument} in the same way as @code{echo -e}
- (@pxref{Bash Builtins}).
- @item %q
- Causes @code{printf} to output the
- corresponding @var{argument} in a format that can be reused as shell input.
- @item %(@var{datefmt})T
- Causes @code{printf} to output the date-time string resulting from using
- @var{datefmt} as a format string for @code{strftime}(3).
- The corresponding @var{argument} 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 @code{printf} behavior.
- @end table
- @noindent
- The %b, %q, and %T directives all use the field width and precision
- arguments from the format specification and write that many bytes from
- (or use that wide a field for) the expanded argument, which usually
- contains more characters than the original.
- Arguments to non-string format specifiers are treated as C language 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.
- The @var{format} is reused as necessary to consume all of the @var{arguments}.
- If the @var{format} requires more @var{arguments} 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.
- @item read
- @btindex read
- @example
- read [-ers] [-a @var{aname}] [-d @var{delim}] [-i @var{text}] [-n @var{nchars}]
- [-N @var{nchars}] [-p @var{prompt}] [-t @var{timeout}] [-u @var{fd}] [@var{name} @dots{}]
- @end example
- One line is read from the standard input, or from the file descriptor
- @var{fd} supplied as an argument to the @option{-u} option,
- split into words as described above in @ref{Word Splitting},
- and the first word
- is assigned to the first @var{name}, the second word to the second @var{name},
- and so on.
- If there are more words than names,
- the remaining words and their intervening delimiters are assigned
- to the last @var{name}.
- If there are fewer words read from the input stream than names,
- the remaining names are assigned empty values.
- The characters in the value of the @env{IFS} variable
- are used to split the line into words using the same rules the shell
- uses for expansion (described above in @ref{Word Splitting}).
- The backslash character @samp{\} may be used to remove any special
- meaning for the next character read and for line continuation.
- Options, if supplied, have the following meanings:
- @table @code
- @item -a @var{aname}
- The words are assigned to sequential indices of the array variable
- @var{aname}, starting at 0.
- All elements are removed from @var{aname} before the assignment.
- Other @var{name} arguments are ignored.
- @item -d @var{delim}
- The first character of @var{delim} is used to terminate the input line,
- rather than newline.
- If @var{delim} is the empty string, @code{read} will terminate a line
- when it reads a NUL character.
- @item -e
- Readline (@pxref{Command Line Editing}) is used to obtain the line.
- Readline uses the current (or default, if line editing was not previously
- active) editing settings, but uses Readline's default filename completion.
- @item -i @var{text}
- If Readline is being used to read the line, @var{text} is placed into
- the editing buffer before editing begins.
- @item -n @var{nchars}
- @code{read} returns after reading @var{nchars} characters rather than
- waiting for a complete line of input, but honors a delimiter if fewer
- than @var{nchars} characters are read before the delimiter.
- @item -N @var{nchars}
- @code{read} returns after reading exactly @var{nchars} characters rather
- than waiting for a complete line of input, unless EOF is encountered or
- @code{read} times out.
- Delimiter characters encountered in the input are
- not treated specially and do not cause @code{read} to return until
- @var{nchars} characters are read.
- The result is not split on the characters in @code{IFS}; the intent is
- that the variable is assigned exactly the characters read
- (with the exception of backslash; see the @option{-r} option below).
- @item -p @var{prompt}
- Display @var{prompt}, without a trailing newline, before attempting
- to read any input.
- The prompt is displayed only if input is coming from a terminal.
- @item -r
- If this option is given, 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 then be used as a line
- continuation.
- @item -s
- Silent mode. If input is coming from a terminal, characters are
- not echoed.
- @item -t @var{timeout}
- Cause @code{read} to time out and return failure if a complete line of
- input (or a specified number of characters)
- is not read within @var{timeout} seconds.
- @var{timeout} may be a decimal number with a fractional portion following
- the decimal point.
- This option is only effective if @code{read} is reading input from a
- terminal, pipe, or other special file; it has no effect when reading
- from regular files.
- If @code{read} times out, @code{read} saves any partial input read into
- the specified variable @var{name}.
- If @var{timeout} is 0, @code{read} 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.
- @item -u @var{fd}
- Read input from file descriptor @var{fd}.
- @end table
- If no @var{name}s are supplied, the line read,
- without the ending delimiter but otherwise unmodified,
- is assigned to the
- variable @env{REPLY}.
- The exit status is zero, unless end-of-file is encountered, @code{read}
- 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 @option{-u}.
- @item readarray
- @btindex readarray
- @example
- readarray [-d @var{delim}] [-n @var{count}] [-O @var{origin}] [-s @var{count}]
- [-t] [-u @var{fd}] [-C @var{callback}] [-c @var{quantum}] [@var{array}]
- @end example
- Read lines from the standard input into the indexed array variable @var{array},
- or from file descriptor @var{fd}
- if the @option{-u} option is supplied.
- A synonym for @code{mapfile}.
- @item source
- @btindex source
- @example
- source @var{filename}
- @end example
- A synonym for @code{.} (@pxref{Bourne Shell Builtins}).
- @item type
- @btindex type
- @example
- type [-afptP] [@var{name} @dots{}]
- @end example
- For each @var{name}, indicate how it would be interpreted if used as a
- command name.
- If the @option{-t} option is used, @code{type} prints a single word
- which is one of @samp{alias}, @samp{function}, @samp{builtin},
- @samp{file} or @samp{keyword},
- if @var{name} is an alias, shell function, shell builtin,
- disk file, or shell reserved word, respectively.
- If the @var{name} is not found, then nothing is printed, and
- @code{type} returns a failure status.
- If the @option{-p} option is used, @code{type} either returns the name
- of the disk file that would be executed, or nothing if @option{-t}
- would not return @samp{file}.
- The @option{-P} option forces a path search for each @var{name}, even if
- @option{-t} would not return @samp{file}.
- If a command is hashed, @option{-p} and @option{-P} print the hashed value,
- which is not necessarily the file that appears first in @code{$PATH}.
- If the @option{-a} option is used, @code{type} returns all of the places
- that contain an executable named @var{file}.
- This includes aliases and functions, if and only if the @option{-p} option
- is not also used.
- If the @option{-f} option is used, @code{type} does not attempt to find
- shell functions, as with the @code{command} builtin.
- The return status is zero if all of the @var{names} are found, non-zero
- if any are not found.
- @item typeset
- @btindex typeset
- @example
- typeset [-afFgrxilnrtux] [-p] [@var{name}[=@var{value}] @dots{}]
- @end example
- The @code{typeset} command is supplied for compatibility with the Korn
- shell.
- It is a synonym for the @code{declare} builtin command.
- @item ulimit
- @btindex ulimit
- @example
- ulimit [-HS] -a
- ulimit [-HS] [-bcdefiklmnpqrstuvxPRT] [@var{limit}]
- @end example
- @code{ulimit} provides control over the resources available to processes
- started by the shell, on systems that allow such control. If an
- option is given, it is interpreted as follows:
- @table @code
- @item -S
- Change and report the soft limit associated with a resource.
- @item -H
- Change and report the hard limit associated with a resource.
- @item -a
- All current limits are reported; no limits are set.
- @item -b
- The maximum socket buffer size.
- @item -c
- The maximum size of core files created.
- @item -d
- The maximum size of a process's data segment.
- @item -e
- The maximum scheduling priority ("nice").
- @item -f
- The maximum size of files written by the shell and its children.
- @item -i
- The maximum number of pending signals.
- @item -k
- The maximum number of kqueues that may be allocated.
- @item -l
- The maximum size that may be locked into memory.
- @item -m
- The maximum resident set size (many systems do not honor this limit).
- @item -n
- The maximum number of open file descriptors (most systems do not
- allow this value to be set).
- @item -p
- The pipe buffer size.
- @item -q
- The maximum number of bytes in @sc{posix} message queues.
- @item -r
- The maximum real-time scheduling priority.
- @item -s
- The maximum stack size.
- @item -t
- The maximum amount of cpu time in seconds.
- @item -u
- The maximum number of processes available to a single user.
- @item -v
- The maximum amount of virtual memory available to the shell, and, on
- some systems, to its children.
- @item -x
- The maximum number of file locks.
- @item -P
- The maximum number of pseudoterminals.
- @item -R
- The maximum time a real-time process can run before blocking, in microseconds.
- @item -T
- The maximum number of threads.
- @end table
- If @var{limit} is given, and the @option{-a} option is not used,
- @var{limit} is the new value of the specified resource.
- The special @var{limit} values @code{hard}, @code{soft}, and
- @code{unlimited} stand for the current hard limit, the current soft limit,
- and no limit, respectively.
- 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.
- Otherwise, the current value of the soft limit for the specified resource
- is printed, unless the @option{-H} option is supplied.
- When more than one
- resource is specified, the limit name and unit, if appropriate,
- are printed before the value.
- When setting new limits, if neither @option{-H} nor @option{-S} is supplied,
- both the hard and soft limits are set.
- If no option is given, then @option{-f} is assumed. Values are in 1024-byte
- increments, except for
- @option{-t}, which is in seconds;
- @option{-R}, which is in microseconds;
- @option{-p}, which is in units of 512-byte blocks;
- @option{-P},
- @option{-T},
- @option{-b},
- @option{-k},
- @option{-n} and @option{-u}, which are unscaled values;
- and, when in @sc{posix} Mode (@pxref{Bash POSIX Mode}),
- @option{-c} and @option{-f}, which are in 512-byte increments.
- The return status is zero unless an invalid option or argument is supplied,
- or an error occurs while setting a new limit.
- @item unalias
- @btindex unalias
- @example
- unalias [-a] [@var{name} @dots{} ]
- @end example
- Remove each @var{name} from the list of aliases. If @option{-a} is
- supplied, all aliases are removed.
- Aliases are described in @ref{Aliases}.
- @end table
- @node Modifying Shell Behavior
- @section Modifying Shell Behavior
-
- @menu
- * The Set Builtin:: Change the values of shell attributes and
- positional parameters.
- * The Shopt Builtin:: Modify shell optional behavior.
- @end menu
- @node The Set Builtin
- @subsection The Set Builtin
- This builtin is so complicated that it deserves its own section. @code{set}
- allows you to change the values of shell options and set the positional
- parameters, or to display the names and values of shell variables.
- @table @code
- @item set
- @btindex set
- @example
- set [--abefhkmnptuvxBCEHPT] [-o @var{option-name}] [@var{argument} @dots{}]
- set [+abefhkmnptuvxBCEHPT] [+o @var{option-name}] [@var{argument} @dots{}]
- @end example
- If no options or arguments are supplied, @code{set} displays the names
- and values of all shell variables and functions, sorted according to the
- current locale, in a format that may be reused as input
- for setting or resetting the currently-set variables.
- Read-only variables cannot be reset.
- In @sc{posix} mode, only shell variables are listed.
- When options are supplied, they set or unset shell attributes.
- Options, if specified, have the following meanings:
- @table @code
- @item -a
- Each variable or function that is created or modified is given the
- export attribute and marked for export to the environment of
- subsequent commands.
- @item -b
- Cause the status of terminated background jobs to be reported
- immediately, rather than before printing the next primary prompt.
- @item -e
- Exit immediately if
- a pipeline (@pxref{Pipelines}), which may consist of a single simple command
- (@pxref{Simple Commands}),
- a list (@pxref{Lists}),
- or a compound command (@pxref{Compound Commands})
- returns a non-zero status.
- The shell does not exit if the command that fails is part of the
- command list immediately following a @code{while} or @code{until} keyword,
- part of the test in an @code{if} statement,
- part of any command executed in a @code{&&} or @code{||} list except
- the command following the final @code{&&} or @code{||},
- any command in a pipeline but the last,
- or if the command's return status is being inverted with @code{!}.
- If a compound command other than a subshell
- returns a non-zero status because a command failed
- while @option{-e} was being ignored, the shell does not exit.
- A trap on @code{ERR}, if set, is executed before the shell exits.
- This option applies to the shell environment and each subshell environment
- separately (@pxref{Command Execution Environment}), and may cause
- subshells to exit before executing all the commands in the subshell.
- If a compound command or shell function executes in a context where
- @option{-e} is being ignored,
- none of the commands executed within the compound command or function body
- will be affected by the @option{-e} setting, even if @option{-e} is set
- and a command returns a failure status.
- If a compound command or shell function sets @option{-e} while executing in
- a context where @option{-e} is ignored, that setting will not have any
- effect until the compound command or the command containing the function
- call completes.
- @item -f
- Disable filename expansion (globbing).
- @item -h
- Locate and remember (hash) commands as they are looked up for execution.
- This option is enabled by default.
- @item -k
- All arguments in the form of assignment statements are placed
- in the environment for a command, not just those that precede
- the command name.
- @item -m
- Job control is enabled (@pxref{Job Control}).
- All processes run in a separate process group.
- When a background job completes, the shell prints a line
- containing its exit status.
- @item -n
- Read commands but do not execute them.
- This may be used to check a script for syntax errors.
- This option is ignored by interactive shells.
- @item -o @var{option-name}
- Set the option corresponding to @var{option-name}:
- @table @code
- @item allexport
- Same as @code{-a}.
- @item braceexpand
- Same as @code{-B}.
- @item emacs
- Use an @code{emacs}-style line editing interface (@pxref{Command Line Editing}).
- This also affects the editing interface used for @code{read -e}.
- @item errexit
- Same as @code{-e}.
- @item errtrace
- Same as @code{-E}.
- @item functrace
- Same as @code{-T}.
- @item hashall
- Same as @code{-h}.
- @item histexpand
- Same as @code{-H}.
- @item history
- Enable command history, as described in @ref{Bash History Facilities}.
- This option is on by default in interactive shells.
- @item ignoreeof
- An interactive shell will not exit upon reading EOF.
- @item keyword
- Same as @code{-k}.
- @item monitor
- Same as @code{-m}.
- @item noclobber
- Same as @code{-C}.
- @item noexec
- Same as @code{-n}.
- @item noglob
- Same as @code{-f}.
- @item nolog
- Currently ignored.
- @item notify
- Same as @code{-b}.
- @item nounset
- Same as @code{-u}.
- @item onecmd
- Same as @code{-t}.
- @item physical
- Same as @code{-P}.
- @item pipefail
- 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.
- @item posix
- Change the behavior of Bash where the default operation differs
- from the @sc{posix} standard to match the standard
- (@pxref{Bash POSIX Mode}).
- This is intended to make Bash behave as a strict superset of that
- standard.
- @item privileged
- Same as @code{-p}.
- @item verbose
- Same as @code{-v}.
- @item vi
- Use a @code{vi}-style line editing interface.
- This also affects the editing interface used for @code{read -e}.
- @item xtrace
- Same as @code{-x}.
- @end table
- @item -p
- Turn on privileged mode.
- In this mode, the @env{$BASH_ENV} and @env{$ENV} files are not
- processed, shell functions are not inherited from the environment,
- and the @env{SHELLOPTS}, @env{BASHOPTS}, @env{CDPATH} and @env{GLOBIGNORE}
- 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 @option{-p} option is not supplied, these actions
- are taken and the effective user id is set to the real user id.
- If the @option{-p} 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.
- @item -t
- Exit after reading and executing one command.
- @item -u
- Treat unset variables and parameters other than the special parameters
- @samp{@@} or @samp{*} as an error when performing parameter expansion.
- An error message will be written to the standard error, and a non-interactive
- shell will exit.
- @item -v
- Print shell input lines as they are read.
- @item -x
- Print a trace of simple commands, @code{for} commands, @code{case}
- commands, @code{select} commands, and arithmetic @code{for} commands
- and their arguments or associated word lists after they are
- expanded and before they are executed. The value of the @env{PS4}
- variable is expanded and the resultant value is printed before
- the command and its expanded arguments.
- @item -B
- The shell will perform brace expansion (@pxref{Brace Expansion}).
- This option is on by default.
- @item -C
- Prevent output redirection using @samp{>}, @samp{>&}, and @samp{<>}
- from overwriting existing files.
- @item -E
- If set, any trap on @code{ERR} is inherited by shell functions, command
- substitutions, and commands executed in a subshell environment.
- The @code{ERR} trap is normally not inherited in such cases.
- @item -H
- Enable @samp{!} style history substitution (@pxref{History Interaction}).
- This option is on by default for interactive shells.
- @item -P
- If set, do not resolve symbolic links when performing commands such as
- @code{cd} which change the current directory. The physical directory
- is used instead. By default, Bash follows
- the logical chain of directories when performing commands
- which change the current directory.
- For example, if @file{/usr/sys} is a symbolic link to @file{/usr/local/sys}
- then:
- @example
- $ cd /usr/sys; echo $PWD
- /usr/sys
- $ cd ..; pwd
- /usr
- @end example
- @noindent
- If @code{set -P} is on, then:
- @example
- $ cd /usr/sys; echo $PWD
- /usr/local/sys
- $ cd ..; pwd
- /usr/local
- @end example
- @item -T
- If set, any trap on @code{DEBUG} and @code{RETURN} are inherited by
- shell functions, command substitutions, and commands executed
- in a subshell environment.
- The @code{DEBUG} and @code{RETURN} traps are normally not inherited
- in such cases.
- @item --
- If no arguments follow this option, then the positional parameters are
- unset. Otherwise, the positional parameters are set to the
- @var{arguments}, even if some of them begin with a @samp{-}.
- @item -
- Signal the end of options, cause all remaining @var{arguments}
- to be assigned to the positional parameters. The @option{-x}
- and @option{-v} options are turned off.
- If there are no arguments, the positional parameters remain unchanged.
- @end table
- Using @samp{+} rather than @samp{-} causes these options to be
- turned off. The options can also be used upon invocation of the
- shell. The current set of options may be found in @code{$-}.
- The remaining N @var{arguments} are positional parameters and are
- assigned, in order, to @code{$1}, @code{$2}, @dots{} @code{$N}.
- The special parameter @code{#} is set to N.
- The return status is always zero unless an invalid option is supplied.
- @end table
- @node The Shopt Builtin
- @subsection The Shopt Builtin
- This builtin allows you to change additional shell optional behavior.
- @table @code
- @item shopt
- @btindex shopt
- @example
- shopt [-pqsu] [-o] [@var{optname} @dots{}]
- @end example
- Toggle the values of settings controlling optional shell behavior.
- The settings can be either those listed below, or, if the
- @option{-o} option is used, those available with the @option{-o}
- option to the @code{set} builtin command (@pxref{The Set Builtin}).
- With no options, or with the @option{-p} option, a list of all settable
- options is displayed, with an indication of whether or not each is set;
- if @var{optnames} are supplied, the output is restricted to those options.
- The @option{-p} option causes output to be displayed in a form that
- may be reused as input.
- Other options have the following meanings:
- @table @code
- @item -s
- Enable (set) each @var{optname}.
- @item -u
- Disable (unset) each @var{optname}.
- @item -q
- Suppresses normal output; the return status
- indicates whether the @var{optname} is set or unset.
- If multiple @var{optname} arguments are given with @option{-q},
- the return status is zero if all @var{optnames} are enabled;
- non-zero otherwise.
- @item -o
- Restricts the values of
- @var{optname} to be those defined for the @option{-o} option to the
- @code{set} builtin (@pxref{The Set Builtin}).
- @end table
- If either @option{-s} or @option{-u}
- is used with no @var{optname} arguments, @code{shopt} shows only
- those options which are set or unset, respectively.
- Unless otherwise noted, the @code{shopt} options are disabled (off)
- by default.
- The return status when listing options is zero if all @var{optnames}
- are enabled, non-zero otherwise. When setting or unsetting options,
- the return status is zero unless an @var{optname} is not a valid shell
- option.
- The list of @code{shopt} options is:
- @table @code
- @item assoc_expand_once
- If set, the shell suppresses multiple evaluation of associative array
- subscripts during arithmetic expression evaluation, while executing
- builtins that can perform variable assignments,
- and while executing builtins that perform array dereferencing.
- @item autocd
- If set, a command name that is the name of a directory is executed as if
- it were the argument to the @code{cd} command.
- This option is only used by interactive shells.
- @item cdable_vars
- If this is set, an argument to the @code{cd} builtin command that
- is not a directory is assumed to be the name of a variable whose
- value is the directory to change to.
- @item cdspell
- If set, minor errors in the spelling of a directory component in a
- @code{cd} command will be corrected.
- The errors checked for are transposed characters,
- a missing character, and a character too many.
- If a correction is found, the corrected path is printed,
- and the command proceeds.
- This option is only used by interactive shells.
- @item checkhash
- If this is set, Bash 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.
- @item checkjobs
- If set, Bash 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 (@pxref{Job Control}).
- The shell always postpones exiting if any jobs are stopped.
- @item checkwinsize
- If set, Bash checks the window size after each external (non-builtin)
- command and, if necessary, updates the values of
- @env{LINES} and @env{COLUMNS}.
- This option is enabled by default.
- @item cmdhist
- If set, Bash
- attempts to save all lines of a multiple-line
- command in the same history entry. This allows
- easy re-editing of multi-line commands.
- This option is enabled by default, but only has an effect if command
- history is enabled (@pxref{Bash History Facilities}).
- @item compat31
- @itemx compat32
- @itemx compat40
- @itemx compat41
- @itemx compat42
- @itemx compat43
- @itemx compat44
- These control aspects of the shell's compatibility mode
- (@pxref{Shell Compatibility Mode}).
- @item complete_fullquote
- If set, Bash
- quotes all shell metacharacters in filenames and directory names when
- performing completion.
- If not set, Bash
- 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.
- @item direxpand
- If set, Bash
- 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, Bash attempts to preserve what the user typed.
- @item dirspell
- If set, Bash
- attempts spelling correction on directory names during word completion
- if the directory name initially supplied does not exist.
- @item dotglob
- If set, Bash includes filenames beginning with a `.' in
- the results of filename expansion.
- The filenames @samp{.} and @samp{..} must always be matched explicitly,
- even if @code{dotglob} is set.
- @item execfail
- If this is set, a non-interactive shell will not exit if
- it cannot execute the file specified as an argument to the @code{exec}
- builtin command. An interactive shell does not exit if @code{exec}
- fails.
- @item expand_aliases
- If set, aliases are expanded as described below under Aliases,
- @ref{Aliases}.
- This option is enabled by default for interactive shells.
- @item extdebug
- If set at shell invocation,
- or in a shell startup file,
- arrange to execute the debugger profile
- before the shell starts, identical to the @option{--debugger} option.
- If set after invocation, behavior intended for use by debuggers is enabled:
- @enumerate
- @item
- The @option{-F} option to the @code{declare} builtin (@pxref{Bash Builtins})
- displays the source file name and line number corresponding to each function
- name supplied as an argument.
- @item
- If the command run by the @code{DEBUG} trap returns a non-zero value, the
- next command is skipped and not executed.
- @item
- If the command run by the @code{DEBUG} trap returns a value of 2, and the
- shell is executing in a subroutine (a shell function or a shell script
- executed by the @code{.} or @code{source} builtins), the shell simulates
- a call to @code{return}.
- @item
- @code{BASH_ARGC} and @code{BASH_ARGV} are updated as described in their
- descriptions (@pxref{Bash Variables}).
- @item
- Function tracing is enabled: command substitution, shell functions, and
- subshells invoked with @code{( @var{command} )} inherit the
- @code{DEBUG} and @code{RETURN} traps.
- @item
- Error tracing is enabled: command substitution, shell functions, and
- subshells invoked with @code{( @var{command} )} inherit the
- @code{ERR} trap.
- @end enumerate
- @item extglob
- If set, the extended pattern matching features described above
- (@pxref{Pattern Matching}) are enabled.
- @item extquote
- If set, @code{$'@var{string}'} and @code{$"@var{string}"} quoting is
- performed within @code{$@{@var{parameter}@}} expansions
- enclosed in double quotes. This option is enabled by default.
- @item failglob
- If set, patterns which fail to match filenames during filename expansion
- result in an expansion error.
- @item force_fignore
- If set, the suffixes specified by the @env{FIGNORE} shell variable
- cause words to be ignored when performing word completion even if
- the ignored words are the only possible completions.
- @xref{Bash Variables}, for a description of @env{FIGNORE}.
- This option is enabled by default.
- @item globasciiranges
- If set, range expressions used in pattern matching bracket expressions
- (@pxref{Pattern Matching})
- 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
- @samp{b} will not collate between @samp{A} and @samp{B},
- and upper-case and lower-case ASCII characters will collate together.
- @item globstar
- If set, the pattern @samp{**} used in a filename expansion context will
- match all files and zero or more directories and subdirectories.
- If the pattern is followed by a @samp{/}, only directories and
- subdirectories match.
- @item gnu_errfmt
- If set, shell error messages are written in the standard @sc{gnu} error
- message format.
- @item histappend
- If set, the history list is appended to the file named by the value
- of the @env{HISTFILE}
- variable when the shell exits, rather than overwriting the file.
- @item histreedit
- If set, and Readline
- is being used, a user is given the opportunity to re-edit a
- failed history substitution.
- @item histverify
- If set, and Readline
- is being used, the results of history substitution are not immediately
- passed to the shell parser. Instead, the resulting line is loaded into
- the Readline editing buffer, allowing further modification.
- @item hostcomplete
- If set, and Readline is being used, Bash will attempt to perform
- hostname completion when a word containing a @samp{@@} is being
- completed (@pxref{Commands For Completion}). This option is enabled
- by default.
- @item huponexit
- If set, Bash will send @code{SIGHUP} to all jobs when an interactive
- login shell exits (@pxref{Signals}).
- @item inherit_errexit
- If set, command substitution inherits the value of the @code{errexit} option,
- instead of unsetting it in the subshell environment.
- This option is enabled when @sc{posix} mode is enabled.
- @item interactive_comments
- Allow a word beginning with @samp{#}
- to cause that word and all remaining characters on that
- line to be ignored in an interactive shell.
- This option is enabled by default.
- @item lastpipe
- 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.
- @item lithist
- If enabled, and the @code{cmdhist}
- option is enabled, multi-line commands are saved to the history with
- embedded newlines rather than using semicolon separators where possible.
- @item localvar_inherit
- If set, local variables inherit the value and attributes of a variable of
- the same name that exists at a previous scope before any new value is
- assigned. The @var{nameref} attribute is not inherited.
- @item localvar_unset
- If set, calling @code{unset} on local variables in previous function scopes
- marks them so subsequent lookups find them unset until that function
- returns. This is identical to the behavior of unsetting local variables
- at the current function scope.
- @item login_shell
- The shell sets this option if it is started as a login shell
- (@pxref{Invoking Bash}).
- The value may not be changed.
- @item mailwarn
- If set, and a file that Bash is checking for mail has been
- accessed since the last time it was checked, the message
- @code{"The mail in @var{mailfile} has been read"} is displayed.
- @item no_empty_cmd_completion
- If set, and Readline is being used, Bash will not attempt to search
- the @env{PATH} for possible completions when completion is attempted
- on an empty line.
- @item nocaseglob
- If set, Bash matches filenames in a case-insensitive fashion when
- performing filename expansion.
- @item nocasematch
- If set, Bash matches patterns in a case-insensitive fashion when
- performing matching while executing @code{case} or @code{[[}
- conditional commands,
- when performing pattern substitution word expansions,
- or when filtering possible completions as part of programmable completion.
- @item nullglob
- If set, Bash allows filename patterns which match no
- files to expand to a null string, rather than themselves.
- @item progcomp
- If set, the programmable completion facilities
- (@pxref{Programmable Completion}) are enabled.
- This option is enabled by default.
- @item progcomp_alias
- If set, and programmable completion is enabled, Bash treats a command
- name that doesn't have any completions as a possible alias and attempts
- alias expansion. If it has an alias, Bash attempts programmable
- completion using the command word resulting from the expanded alias.
- @item promptvars
- If set, prompt strings undergo
- parameter expansion, command substitution, arithmetic
- expansion, and quote removal after being expanded
- as described below (@pxref{Controlling the Prompt}).
- This option is enabled by default.
- @item restricted_shell
- The shell sets this option if it is started in restricted mode
- (@pxref{The Restricted Shell}).
- 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.
- @item shift_verbose
- If this is set, the @code{shift}
- builtin prints an error message when the shift count exceeds the
- number of positional parameters.
- @item sourcepath
- If set, the @code{source} builtin uses the value of @env{PATH}
- to find the directory containing the file supplied as an argument.
- This option is enabled by default.
- @item xpg_echo
- If set, the @code{echo} builtin expands backslash-escape sequences
- by default.
- @end table
- @end table
- @node Special Builtins
- @section Special Builtins
- @cindex special builtin
- For historical reasons, the @sc{posix} standard has classified
- several builtin commands as @emph{special}.
- When Bash is executing in @sc{posix} mode, the special builtins
- differ from other builtin commands in three respects:
- @enumerate
- @item
- Special builtins are found before shell functions during command lookup.
- @item
- If a special builtin returns an error status, a non-interactive shell exits.
- @item
- Assignment statements preceding the command stay in effect in the shell
- environment after the command completes.
- @end enumerate
- When Bash is not executing in @sc{posix} mode, these builtins behave no
- differently than the rest of the Bash builtin commands.
- The Bash @sc{posix} mode is described in @ref{Bash POSIX Mode}.
- These are the @sc{posix} special builtins:
- @example
- @w{break : . continue eval exec exit export readonly return set}
- @w{shift trap unset}
- @end example
- @node Shell Variables
- @chapter Shell Variables
- @menu
- * Bourne Shell Variables:: Variables which Bash uses in the same way
- as the Bourne Shell.
- * Bash Variables:: List of variables that exist in Bash.
- @end menu
- This chapter describes the shell variables that Bash uses.
- Bash automatically assigns default values to a number of variables.
- @node Bourne Shell Variables
- @section Bourne Shell Variables
- Bash uses certain shell variables in the same way as the Bourne shell.
- In some cases, Bash assigns a default value to the variable.
- @vtable @code
- @item CDPATH
- A colon-separated list of directories used as a search path for
- the @code{cd} builtin command.
- @item HOME
- The current user's home directory; the default for the @code{cd} builtin
- command.
- The value of this variable is also used by tilde expansion
- (@pxref{Tilde Expansion}).
- @item IFS
- A list of characters that separate fields; used when the shell splits
- words as part of expansion.
- @item MAIL
- If this parameter is set to a filename or directory name
- and the @env{MAILPATH} variable
- is not set, Bash informs the user of the arrival of mail in
- the specified file or Maildir-format directory.
- @item MAILPATH
- A colon-separated list of filenames which the shell periodically checks
- for new mail.
- Each list entry can specify the message that is printed when new mail
- arrives in the mail file by separating the filename from the message with
- a @samp{?}.
- When used in the text of the message, @code{$_} expands to the name of
- the current mail file.
- @item OPTARG
- The value of the last option argument processed by the @code{getopts} builtin.
- @item OPTIND
- The index of the last option argument processed by the @code{getopts} builtin.
- @item PATH
- A colon-separated list of directories in which the shell looks for
- commands.
- A zero-length (null) directory name in the value of @code{PATH} indicates the
- current directory.
- A null directory name may appear as two adjacent colons, or as an initial
- or trailing colon.
- @item PS1
- The primary prompt string. The default value is @samp{\s-\v\$ }.
- @xref{Controlling the Prompt}, for the complete list of escape
- sequences that are expanded before @env{PS1} is displayed.
- @item PS2
- The secondary prompt string. The default value is @samp{> }.
- @env{PS2} is expanded in the same way as @env{PS1} before being
- displayed.
- @end vtable
- @node Bash Variables
- @section Bash Variables
- These variables are set or used by Bash, but other shells
- do not normally treat them specially.
- A few variables used by Bash are described in different chapters:
- variables for controlling the job control facilities
- (@pxref{Job Control Variables}).
- @vtable @code
- @item _
- @vindex $_
- ($_, an underscore.)
- At shell startup, set to the 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 simple
- command executed in the foreground, 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.
- @item BASH
- The full pathname used to execute the current instance of Bash.
- @item BASHOPTS
- A colon-separated list of enabled shell options. Each word in
- the list is a valid argument for the @option{-s} option to the
- @code{shopt} builtin command (@pxref{The Shopt Builtin}).
- The options appearing in @env{BASHOPTS} are those reported
- as @samp{on} by @samp{shopt}.
- If this variable is in the environment when Bash
- starts up, each shell option in the list will be enabled before
- reading any startup files. This variable is readonly.
- @item BASHPID
- Expands to the process ID of the current Bash process.
- This differs from @code{$$} under certain circumstances, such as subshells
- that do not require Bash to be re-initialized.
- Assignments to @env{BASHPID} have no effect.
- If @env{BASHPID}
- is unset, it loses its special properties, even if it is
- subsequently reset.
- @item BASH_ALIASES
- An associative array variable whose members correspond to the internal
- list of aliases as maintained by the @code{alias} builtin.
- (@pxref{Bourne Shell Builtins}).
- 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 @env{BASH_ALIASES}
- is unset, it loses its special properties, even if it is
- subsequently reset.
- @item BASH_ARGC
- An array variable whose values are the number of parameters in each
- frame of the current bash execution call stack. The number of
- parameters to the current subroutine (shell function or script executed
- with @code{.} or @code{source}) is at the top of the stack. When a
- subroutine is executed, the number of parameters passed is pushed onto
- @code{BASH_ARGC}.
- The shell sets @code{BASH_ARGC} only when in extended debugging mode
- (see @ref{The Shopt Builtin}
- for a description of the @code{extdebug} option to the @code{shopt}
- builtin).
- Setting @code{extdebug} after the shell has started to execute a script,
- or referencing this variable when @code{extdebug} is not set,
- may result in inconsistent values.
- @item BASH_ARGV
- An array variable containing all of the parameters in the current bash
- 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 @code{BASH_ARGV}.
- The shell sets @code{BASH_ARGV} only when in extended debugging mode
- (see @ref{The Shopt Builtin}
- for a description of the @code{extdebug} option to the @code{shopt}
- builtin).
- Setting @code{extdebug} after the shell has started to execute a script,
- or referencing this variable when @code{extdebug} is not set,
- may result in inconsistent values.
- @item BASH_ARGV0
- When referenced, this variable expands to the name of the shell or shell
- script (identical to @code{$0}; @xref{Special Parameters},
- for the description of special parameter 0).
- Assignment to @code{BASH_ARGV0}
- causes the value assigned to also be assigned to @code{$0}.
- If @env{BASH_ARGV0}
- is unset, it loses its special properties, even if it is
- subsequently reset.
- @item BASH_CMDS
- An associative array variable whose members correspond to the internal
- hash table of commands as maintained by the @code{hash} builtin
- (@pxref{Bourne Shell Builtins}).
- 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 @env{BASH_CMDS}
- is unset, it loses its special properties, even if it is
- subsequently reset.
- @item BASH_COMMAND
- 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.
- If @env{BASH_COMMAND}
- is unset, it loses its special properties, even if it is
- subsequently reset.
- @item BASH_COMPAT
- The value is used to set the shell's compatibility level.
- @xref{Shell Compatibility Mode}, 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 @env{BASH_COMPAT} is unset or set to the empty string, the compatibility
- level is set to the default for the current version.
- If @env{BASH_COMPAT} 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 values correspond to the compatibility levels
- described below (@pxref{Shell Compatibility Mode}).
- For example, 4.2 and 42 are valid values that correspond
- to the @code{compat42} @code{shopt} option
- and set the compatibility level to 42.
- The current version is also a valid value.
- @item BASH_ENV
- If this variable is set when Bash is invoked to execute a shell
- script, its value is expanded and used as the name of a startup file
- to read before executing the script. @xref{Bash Startup Files}.
- @item BASH_EXECUTION_STRING
- The command argument to the @option{-c} invocation option.
- @item BASH_LINENO
- An array variable whose members are the line numbers in source files
- where each corresponding member of @var{FUNCNAME} was invoked.
- @code{$@{BASH_LINENO[$i]@}} is the line number in the source file
- (@code{$@{BASH_SOURCE[$i+1]@}}) where
- @code{$@{FUNCNAME[$i]@}} was called (or @code{$@{BASH_LINENO[$i-1]@}} if
- referenced within another shell function).
- Use @code{LINENO} to obtain the current line number.
- @item BASH_LOADABLES_PATH
- A colon-separated list of directories in which the shell looks for
- dynamically loadable builtins specified by the
- @code{enable} command.
- @item BASH_REMATCH
- An array variable whose members are assigned by the @samp{=~} binary
- operator to the @code{[[} conditional command
- (@pxref{Conditional Constructs}).
- The element with index 0 is the portion of the string
- matching the entire regular expression.
- The element with index @var{n} is the portion of the
- string matching the @var{n}th parenthesized subexpression.
- @item BASH_SOURCE
- An array variable whose members are the source filenames where the
- corresponding shell function names in the @code{FUNCNAME} array
- variable are defined.
- The shell function @code{$@{FUNCNAME[$i]@}} is defined in the file
- @code{$@{BASH_SOURCE[$i]@}} and called from @code{$@{BASH_SOURCE[$i+1]@}}
- @item BASH_SUBSHELL
- Incremented by one within each subshell or subshell environment when
- the shell begins executing in that environment.
- The initial value is 0.
- If @env{BASH_SUBSHELL}
- is unset, it loses its special properties, even if it is
- subsequently reset.
- @item BASH_VERSINFO
- A readonly array variable (@pxref{Arrays})
- whose members hold version information for this instance of Bash.
- The values assigned to the array members are as follows:
- @table @code
- @item BASH_VERSINFO[0]
- The major version number (the @var{release}).
- @item BASH_VERSINFO[1]
- The minor version number (the @var{version}).
- @item BASH_VERSINFO[2]
- The patch level.
- @item BASH_VERSINFO[3]
- The build version.
- @item BASH_VERSINFO[4]
- The release status (e.g., @var{beta1}).
- @item BASH_VERSINFO[5]
- The value of @env{MACHTYPE}.
- @end table
- @item BASH_VERSION
- The version number of the current instance of Bash.
- @item BASH_XTRACEFD
- If set to an integer corresponding to a valid file descriptor, Bash
- will write the trace output generated when @samp{set -x}
- is enabled to that file descriptor.
- This allows tracing output to be separated from diagnostic and error
- messages.
- The file descriptor is closed when @code{BASH_XTRACEFD} is unset or assigned
- a new value.
- Unsetting @code{BASH_XTRACEFD} or assigning it the empty string causes the
- trace output to be sent to the standard error.
- Note that setting @code{BASH_XTRACEFD} to 2 (the standard error file
- descriptor) and then unsetting it will result in the standard error
- being closed.
- @item CHILD_MAX
- Set the number of exited child status values for the shell to remember.
- Bash will not allow this value to be decreased below a @sc{posix}-mandated
- minimum, and there is a maximum value (currently 8192) that this may
- not exceed.
- The minimum value is system-dependent.
- @item COLUMNS
- Used by the @code{select} command to determine the terminal width
- when printing selection lists.
- Automatically set if the @code{checkwinsize} option is enabled
- (@pxref{The Shopt Builtin}), or in an interactive shell upon receipt of a
- @code{SIGWINCH}.
- @item COMP_CWORD
- An index into @env{$@{COMP_WORDS@}} of the word containing the current
- cursor position.
- This variable is available only in shell functions invoked by the
- programmable completion facilities (@pxref{Programmable Completion}).
- @item COMP_LINE
- The current command line.
- This variable is available only in shell functions and external
- commands invoked by the
- programmable completion facilities (@pxref{Programmable Completion}).
- @item COMP_POINT
- 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 @code{$@{#COMP_LINE@}}.
- This variable is available only in shell functions and external
- commands invoked by the
- programmable completion facilities (@pxref{Programmable Completion}).
- @item COMP_TYPE
- Set to an integer value corresponding to the type of completion attempted
- that caused a completion function to be called:
- @var{TAB}, for normal completion,
- @samp{?}, for listing completions after successive tabs,
- @samp{!}, for listing alternatives on partial word completion,
- @samp{@@}, to list completions if the word is not unmodified,
- or
- @samp{%}, for menu completion.
- This variable is available only in shell functions and external
- commands invoked by the
- programmable completion facilities (@pxref{Programmable Completion}).
- @item COMP_KEY
- The key (or final key of a key sequence) used to invoke the current
- completion function.
- @item COMP_WORDBREAKS
- The set of characters that the Readline library treats as word
- separators when performing word completion.
- If @env{COMP_WORDBREAKS}
- is unset, it loses its special properties,
- even if it is subsequently reset.
- @item COMP_WORDS
- An array variable consisting of the individual
- words in the current command line.
- The line is split into words as Readline would split it, using
- @code{COMP_WORDBREAKS} as described above.
- This variable is available only in shell functions invoked by the
- programmable completion facilities (@pxref{Programmable Completion}).
- @item COMPREPLY
- An array variable from which Bash reads the possible completions
- generated by a shell function invoked by the programmable completion
- facility (@pxref{Programmable Completion}).
- Each array element contains one possible completion.
- @item COPROC
- An array variable created to hold the file descriptors
- for output from and input to an unnamed coprocess (@pxref{Coprocesses}).
- @item DIRSTACK
- An array variable containing the current contents of the directory stack.
- Directories appear in the stack in the order they are displayed by the
- @code{dirs} builtin.
- Assigning to members of this array variable may be used to modify
- directories already in the stack, but the @code{pushd} and @code{popd}
- builtins must be used to add and remove directories.
- Assignment to this variable will not change the current directory.
- If @env{DIRSTACK}
- is unset, it loses its special properties, even if
- it is subsequently reset.
- @item EMACS
- If Bash finds this variable in the environment when the shell
- starts with value @samp{t}, it assumes that the shell is running in an
- Emacs shell buffer and disables line editing.
- @item ENV
- Expanded and executed similarlty to @code{BASH_ENV}
- (@pxref{Bash Startup Files})
- when an interactive shell is invoked in
- @sc{posix} Mode (@pxref{Bash POSIX Mode}).
- @item EPOCHREALTIME
- Each time this parameter is referenced, it expands to the number of seconds
- since the Unix Epoch as a floating point value with micro-second granularity
- (see the documentation for the C library function @var{time} for the
- definition of Epoch).
- Assignments to @env{EPOCHREALTIME} are ignored.
- If @env{EPOCHREALTIME}
- is unset, it loses its special properties, even if
- it is subsequently reset.
- @item EPOCHSECONDS
- Each time this parameter is referenced, it expands to the number of seconds
- since the Unix Epoch (see the documentation for the C library function
- @var{time} for the definition of Epoch).
- Assignments to @env{EPOCHSECONDS} are ignored.
- If @env{EPOCHSECONDS}
- is unset, it loses its special properties, even if
- it is subsequently reset.
- @item EUID
- The numeric effective user id of the current user. This variable
- is readonly.
- @item EXECIGNORE
- A colon-separated list of shell patterns (@pxref{Pattern Matching})
- defining the list of filenames to be ignored by command search using
- @code{PATH}.
- Files whose full pathnames match one of these patterns are not considered
- executable files for the purposes of completion and command execution
- via @code{PATH} lookup.
- This does not affect the behavior of the @code{[}, @code{test}, and @code{[[}
- commands.
- Full pathnames in the command hash table are not subject to @code{EXECIGNORE}.
- 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 @code{extglob} shell
- option.
- @item FCEDIT
- The editor used as a default by the @option{-e} option to the @code{fc}
- builtin command.
- @item FIGNORE
- A colon-separated list of suffixes to ignore when performing
- filename completion.
- A filename whose suffix matches one of the entries in
- @env{FIGNORE}
- is excluded from the list of matched filenames. A sample
- value is @samp{.o:~}
- @item FUNCNAME
- 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 @code{"main"}.
- This variable exists only when a shell function is executing.
- Assignments to @env{FUNCNAME} have no effect.
- If @env{FUNCNAME}
- is unset, it loses its special properties, even if
- it is subsequently reset.
- This variable can be used with @code{BASH_LINENO} and @code{BASH_SOURCE}.
- Each element of @code{FUNCNAME} has corresponding elements in
- @code{BASH_LINENO} and @code{BASH_SOURCE} to describe the call stack.
- For instance, @code{$@{FUNCNAME[$i]@}} was called from the file
- @code{$@{BASH_SOURCE[$i+1]@}} at line number @code{$@{BASH_LINENO[$i]@}}.
- The @code{caller} builtin displays the current call stack using this
- information.
- @item FUNCNEST
- 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.
- @item GLOBIGNORE
- A colon-separated list of patterns defining the set of file names to
- be ignored by filename expansion.
- If a file name matched by a filename expansion pattern also matches one
- of the patterns in @env{GLOBIGNORE}, it is removed from the list
- of matches.
- The pattern matching honors the setting of the @code{extglob} shell
- option.
- @item GROUPS
- An array variable containing the list of groups of which the current
- user is a member.
- Assignments to @env{GROUPS} have no effect.
- If @env{GROUPS}
- is unset, it loses its special properties, even if it is
- subsequently reset.
- @item histchars
- Up to three characters which control history expansion, quick
- substitution, and tokenization (@pxref{History Interaction}).
- The first character is the
- @var{history expansion} character, that is, the character which signifies the
- start of a history expansion, normally @samp{!}. The second character is the
- character which signifies `quick substitution' when seen as the first
- character on a line, normally @samp{^}. 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, usually @samp{#}. 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.
- @item HISTCMD
- The history number, or index in the history list, of the current
- command.
- Assignments to @env{HISTCMD} are ignored.
- If @env{HISTCMD}
- is unset, it loses its special properties,
- even if it is subsequently reset.
- @item HISTCONTROL
- A colon-separated list of values controlling how commands are saved on
- the history list.
- If the list of values includes @samp{ignorespace}, lines which begin
- with a space character are not saved in the history list.
- A value of @samp{ignoredups} causes lines which match the previous
- history entry to not be saved.
- A value of @samp{ignoreboth} is shorthand for
- @samp{ignorespace} and @samp{ignoredups}.
- A value of @samp{erasedups} 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 @env{HISTCONTROL} 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 @env{HISTIGNORE}.
- 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
- @env{HISTCONTROL}.
- @item HISTFILE
- The name of the file to which the command history is saved. The
- default value is @file{~/.bash_history}.
- @item HISTFILESIZE
- 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 @env{HISTSIZE}
- after reading any startup files.
- @item HISTIGNORE
- 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 @samp{*} is appended). Each pattern is tested
- against the line after the checks specified by @env{HISTCONTROL}
- are applied. In addition to the normal shell pattern matching
- characters, @samp{&} matches the previous history line. @samp{&}
- 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
- @env{HISTIGNORE}.
- The pattern matching honors the setting of the @code{extglob} shell
- option.
- @env{HISTIGNORE} subsumes the function of @env{HISTCONTROL}. A
- pattern of @samp{&} is identical to @code{ignoredups}, and a
- pattern of @samp{[ ]*} is identical to @code{ignorespace}.
- Combining these two patterns, separating them with a colon,
- provides the functionality of @code{ignoreboth}.
- @item HISTSIZE
- The maximum number of commands to remember on the history list.
- 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.
- @item HISTTIMEFORMAT
- If this variable is set and not null, its value is used as a format string
- for @var{strftime} to print the time stamp associated with each history
- entry displayed by the @code{history} 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.
- @item HOSTFILE
- Contains the name of a file in the same format as @file{/etc/hosts} 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, Bash adds the contents of the new file to the
- existing list.
- If @env{HOSTFILE} is set, but has no value, or does not name a readable file,
- Bash attempts to read
- @file{/etc/hosts} to obtain the list of possible hostname completions.
- When @env{HOSTFILE} is unset, the hostname list is cleared.
- @item HOSTNAME
- The name of the current host.
- @item HOSTTYPE
- A string describing the machine Bash is running on.
- @item IGNOREEOF
- Controls the action of the shell on receipt of an @code{EOF} character
- as the sole input. If set, the value denotes the number
- of consecutive @code{EOF} characters that can be read as the
- first character on an input line
- before the shell will exit. If the variable exists but does not
- have a numeric value, or has no value, then the default is 10.
- If the variable does not exist, then @code{EOF} signifies the end of
- input to the shell. This is only in effect for interactive shells.
- @item INPUTRC
- The name of the Readline initialization file, overriding the default
- of @file{~/.inputrc}.
- @item INSIDE_EMACS
- If Bash finds this variable in the environment when the shell
- starts, it assumes that the shell is running in an Emacs shell buffer
- and may disable line editing depending on the value of @env{TERM}.
- @item LANG
- Used to determine the locale category for any category not specifically
- selected with a variable starting with @code{LC_}.
- @item LC_ALL
- This variable overrides the value of @env{LANG} and any other
- @code{LC_} variable specifying a locale category.
- @item LC_COLLATE
- This variable determines the collation order used when sorting the
- results of filename expansion, and
- determines the behavior of range expressions, equivalence classes,
- and collating sequences within filename expansion and pattern matching
- (@pxref{Filename Expansion}).
- @item LC_CTYPE
- This variable determines the interpretation of characters and the
- behavior of character classes within filename expansion and pattern
- matching (@pxref{Filename Expansion}).
- @item LC_MESSAGES
- This variable determines the locale used to translate double-quoted
- strings preceded by a @samp{$} (@pxref{Locale Translation}).
- @item LC_NUMERIC
- This variable determines the locale category used for number formatting.
- @item LC_TIME
- This variable determines the locale category used for data and time
- formatting.
- @item LINENO
- The line number in the script or shell function currently executing.
- If @env{LINENO}
- is unset, it loses its special properties, even if it is
- subsequently reset.
- @item LINES
- Used by the @code{select} command to determine the column length
- for printing selection lists.
- Automatically set if the @code{checkwinsize} option is enabled
- (@pxref{The Shopt Builtin}), or in an interactive shell upon receipt of a
- @code{SIGWINCH}.
- @item MACHTYPE
- A string that fully describes the system type on which Bash
- is executing, in the standard @sc{gnu} @var{cpu-company-system} format.
- @item MAILCHECK
- How often (in seconds) that the shell should check for mail in the
- files specified in the @env{MAILPATH} or @env{MAIL} variables.
- 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.
- @item MAPFILE
- An array variable created to hold the text read by the
- @code{mapfile} builtin when no variable name is supplied.
- @item OLDPWD
- The previous working directory as set by the @code{cd} builtin.
- @item OPTERR
- If set to the value 1, Bash displays error messages
- generated by the @code{getopts} builtin command.
- @item OSTYPE
- A string describing the operating system Bash is running on.
- @item PIPESTATUS
- An array variable (@pxref{Arrays})
- containing a list of exit status values from the processes
- in the most-recently-executed foreground pipeline (which may
- contain only a single command).
- @item POSIXLY_CORRECT
- If this variable is in the environment when Bash starts, the shell
- enters @sc{posix} mode (@pxref{Bash POSIX Mode}) before reading the
- startup files, as if the @option{--posix} invocation option had been supplied.
- If it is set while the shell is running, Bash enables @sc{posix} mode,
- as if the command
- @example
- @code{set -o posix}
- @end example
- @noindent
- had been executed.
- When the shell enters @sc{posix} mode, it sets this variable if it was
- not already set.
- @item PPID
- The process @sc{id} of the shell's parent process. This variable
- is readonly.
- @item PROMPT_COMMAND
- If this variable is set, and is an array,
- the value of each set element is interpreted as a command to execute
- before printing the primary prompt (@env{$PS1}).
- If this is set but not an array variable,
- its value is used as a command to execute instead.
- @item PROMPT_DIRTRIM
- If set to a number greater than zero, the value is used as the number of
- trailing directory components to retain when expanding the @code{\w} and
- @code{\W} prompt string escapes (@pxref{Controlling the Prompt}).
- Characters removed are replaced with an ellipsis.
- @item PS0
- The value of this parameter is expanded like @env{PS1}
- and displayed by interactive shells after reading a command
- and before the command is executed.
- @item PS3
- The value of this variable is used as the prompt for the
- @code{select} command. If this variable is not set, the
- @code{select} command prompts with @samp{#? }
- @item PS4
- The value of this parameter is expanded like @var{PS1}
- and the expanded value is the prompt printed before the command line
- is echoed when the @option{-x} option is set (@pxref{The Set Builtin}).
- The first character of the expanded value is replicated multiple times,
- as necessary, to indicate multiple levels of indirection.
- The default is @samp{+ }.
- @item PWD
- The current working directory as set by the @code{cd} builtin.
- @item RANDOM
- Each time this parameter is referenced, it expands to a random integer
- between 0 and 32767. Assigning a value to this
- variable seeds the random number generator.
- If @env{RANDOM}
- is unset, it loses its special properties, even if it is
- subsequently reset.
- @item READLINE_LINE
- The contents of the Readline line buffer, for use
- with @samp{bind -x} (@pxref{Bash Builtins}).
- @item READLINE_MARK
- The position of the @var{mark} (saved insertion point) in the
- Readline line buffer, for use
- with @samp{bind -x} (@pxref{Bash Builtins}).
- The characters between the insertion point and the mark are often
- called the @var{region}.
- @item READLINE_POINT
- The position of the insertion point in the Readline line buffer, for use
- with @samp{bind -x} (@pxref{Bash Builtins}).
- @item REPLY
- The default variable for the @code{read} builtin.
- @item SECONDS
- This variable expands to the number of seconds since the
- shell was started. Assignment to this variable resets
- the count to the value assigned, and the expanded value
- becomes the value assigned plus the number of seconds
- since the assignment.
- The number of seconds at shell invocation and the current time is always
- determined by querying the system clock.
- If @env{SECONDS}
- is unset, it loses its special properties,
- even if it is subsequently reset.
- @item SHELL
- This environment variable expands to the full pathname to the shell.
- If it is not set when the shell starts,
- Bash assigns to it the full pathname of the current user's login shell.
- @item SHELLOPTS
- A colon-separated list of enabled shell options. Each word in
- the list is a valid argument for the @option{-o} option to the
- @code{set} builtin command (@pxref{The Set Builtin}).
- The options appearing in @env{SHELLOPTS} are those reported
- as @samp{on} by @samp{set -o}.
- If this variable is in the environment when Bash
- starts up, each shell option in the list will be enabled before
- reading any startup files. This variable is readonly.
- @item SHLVL
- Incremented by one each time a new instance of Bash is started. This is
- intended to be a count of how deeply your Bash shells are nested.
- @item SRANDOM
- This variable expands to a 32-bit pseudo-random number each time it is
- referenced. The random number generator is not linear on systems that
- support @file{/dev/urandom} or @code{arc4random}, so each returned number
- has no relationship to the numbers preceding it.
- The random number generator cannot be seeded, so assignments to this
- variable have no effect.
- If @env{SRANDOM}
- is unset, it loses its special properties,
- even if it is subsequently reset.
- @item TIMEFORMAT
- The value of this parameter is used as a format string specifying
- how the timing information for pipelines prefixed with the @code{time}
- reserved word should be displayed.
- The @samp{%} 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.
- @table @code
- @item %%
- A literal @samp{%}.
- @item %[@var{p}][l]R
- The elapsed time in seconds.
- @item %[@var{p}][l]U
- The number of CPU seconds spent in user mode.
- @item %[@var{p}][l]S
- The number of CPU seconds spent in system mode.
- @item %P
- The CPU percentage, computed as (%U + %S) / %R.
- @end table
- The optional @var{p} is a digit specifying the precision, 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 @var{p} greater than 3 are changed to 3.
- If @var{p} is not specified, the value 3 is used.
- The optional @code{l} specifies a longer format, including minutes, of
- the form @var{MM}m@var{SS}.@var{FF}s.
- The value of @var{p} determines whether or not the fraction is included.
- If this variable is not set, Bash acts as if it had the value
- @example
- @code{$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'}
- @end example
- If the value is null, no timing information is displayed.
- A trailing newline is added when the format string is displayed.
- @item TMOUT
- If set to a value greater than zero, @code{TMOUT} is treated as the
- default timeout for the @code{read} builtin (@pxref{Bash Builtins}).
- The @code{select} command (@pxref{Conditional Constructs}) terminates
- if input does not arrive after @code{TMOUT} 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.
- Bash
- terminates after waiting for that number of seconds if a complete
- line of input does not arrive.
- @item TMPDIR
- If set, Bash uses its value as the name of a directory in which
- Bash creates temporary files for the shell's use.
- @item UID
- The numeric real user id of the current user. This variable is readonly.
- @end vtable
- @node Bash Features
- @chapter Bash Features
- This chapter describes features unique to Bash.
- @menu
- * Invoking Bash:: Command line options that you can give
- to Bash.
- * Bash Startup Files:: When and how Bash executes scripts.
- * Interactive Shells:: What an interactive shell is.
- * Bash Conditional Expressions:: Primitives used in composing expressions for
- the @code{test} builtin.
- * Shell Arithmetic:: Arithmetic on shell variables.
- * Aliases:: Substituting one command for another.
- * Arrays:: Array Variables.
- * The Directory Stack:: History of visited directories.
- * Controlling the Prompt:: Customizing the various prompt strings.
- * The Restricted Shell:: A more controlled mode of shell execution.
- * Bash POSIX Mode:: Making Bash behave more closely to what
- the POSIX standard specifies.
- * Shell Compatibility Mode:: How Bash supports behavior that was present
- in earlier versions and has changed.
- @end menu
- @node Invoking Bash
- @section Invoking Bash
- @example
- bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o @var{option}]
- [-O @var{shopt_option}] [@var{argument} @dots{}]
- bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o @var{option}]
- [-O @var{shopt_option}] -c @var{string} [@var{argument} @dots{}]
- bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o @var{option}]
- [-O @var{shopt_option}] [@var{argument} @dots{}]
- @end example
- All of the single-character options used with the @code{set} builtin
- (@pxref{The Set Builtin}) can be used as options when the shell is invoked.
- In addition, there are several multi-character
- options that you can use. These options must appear on the command
- line before the single-character options to be recognized.
- @table @code
- @item --debugger
- Arrange for the debugger profile to be executed before the shell
- starts. Turns on extended debugging mode (see @ref{The Shopt Builtin}
- for a description of the @code{extdebug} option to the @code{shopt}
- builtin).
- @item --dump-po-strings
- A list of all double-quoted strings preceded by @samp{$}
- is printed on the standard output
- in the @sc{gnu} @code{gettext} PO (portable object) file format.
- Equivalent to @option{-D} except for the output format.
- @item --dump-strings
- Equivalent to @option{-D}.
- @item --help
- Display a usage message on standard output and exit successfully.
- @item --init-file @var{filename}
- @itemx --rcfile @var{filename}
- Execute commands from @var{filename} (instead of @file{~/.bashrc})
- in an interactive shell.
- @item --login
- Equivalent to @option{-l}.
- @item --noediting
- Do not use the @sc{gnu} Readline library (@pxref{Command Line Editing})
- to read command lines when the shell is interactive.
- @item --noprofile
- Don't load the system-wide startup file @file{/etc/profile}
- or any of the personal initialization files
- @file{~/.bash_profile}, @file{~/.bash_login}, or @file{~/.profile}
- when Bash is invoked as a login shell.
- @item --norc
- Don't read the @file{~/.bashrc} initialization file in an
- interactive shell. This is on by default if the shell is
- invoked as @code{sh}.
- @item --posix
- Change the behavior of Bash where the default operation differs
- from the @sc{posix} standard to match the standard. This
- is intended to make Bash behave as a strict superset of that
- standard. @xref{Bash POSIX Mode}, for a description of the Bash
- @sc{posix} mode.
- @item --restricted
- Make the shell a restricted shell (@pxref{The Restricted Shell}).
- @item --verbose
- Equivalent to @option{-v}. Print shell input lines as they're read.
- @item --version
- Show version information for this instance of
- Bash on the standard output and exit successfully.
- @end table
- There are several single-character options that may be supplied at
- invocation which are not available with the @code{set} builtin.
- @table @code
- @item -c
- Read and execute commands from the first non-option argument
- @var{command_string}, then exit.
- If there are arguments after the @var{command_string},
- the first argument is assigned to @code{$0}
- and any remaining arguments are assigned to the positional parameters.
- The assignment to @code{$0} sets the name of the shell, which is used
- in warning and error messages.
- @item -i
- Force the shell to run interactively. Interactive shells are
- described in @ref{Interactive Shells}.
- @item -l
- Make this shell act as if it had been directly invoked by login.
- When the shell is interactive, this is equivalent to starting a
- login shell with @samp{exec -l bash}.
- When the shell is not interactive, the login shell startup files will
- be executed.
- @samp{exec bash -l} or @samp{exec bash --login}
- will replace the current shell with a Bash login shell.
- @xref{Bash Startup Files}, for a description of the special behavior
- of a login shell.
- @item -r
- Make the shell a restricted shell (@pxref{The Restricted Shell}).
- @item -s
- If this 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 or when reading input
- through a pipe.
- @item -D
- A list of all double-quoted strings preceded by @samp{$}
- is printed on the standard output.
- These are the strings that
- are subject to language translation when the current locale
- is not @code{C} or @code{POSIX} (@pxref{Locale Translation}).
- This implies the @option{-n} option; no commands will be executed.
- @item [-+]O [@var{shopt_option}]
- @var{shopt_option} is one of the shell options accepted by the
- @code{shopt} builtin (@pxref{The Shopt Builtin}).
- If @var{shopt_option} is present, @option{-O} sets the value of that option;
- @option{+O} unsets it.
- If @var{shopt_option} is not supplied, the names and values of the shell
- options accepted by @code{shopt} are printed on the standard output.
- If the invocation option is @option{+O}, the output is displayed in a format
- that may be reused as input.
- @item --
- A @code{--} signals the end of options and disables further option
- processing.
- Any arguments after the @code{--} are treated as filenames and arguments.
- @end table
- @cindex login shell
- A @emph{login} shell is one whose first character of argument zero is
- @samp{-}, or one invoked with the @option{--login} option.
- @cindex interactive shell
- An @emph{interactive} shell is one started without non-option arguments,
- unless @option{-s} is specified,
- without specifying the @option{-c} option, and whose input and output are both
- connected to terminals (as determined by @code{isatty(3)}), or one
- started with the @option{-i} option. @xref{Interactive Shells}, for more
- information.
- If arguments remain after option processing, and neither the
- @option{-c} nor the @option{-s}
- option has been supplied, the first argument is assumed to
- be the name of a file containing shell commands (@pxref{Shell Scripts}).
- When Bash is invoked in this fashion, @code{$0}
- is set to the name of the file, and the positional parameters
- are set to the remaining arguments.
- Bash reads and executes commands from this file, then exits.
- Bash'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.
- @node Bash Startup Files
- @section Bash Startup Files
- @cindex startup files
- This section describes how Bash executes its startup files.
- If any of the files exist but cannot be read, Bash reports an error.
- Tildes are expanded in filenames as described above under
- Tilde Expansion (@pxref{Tilde Expansion}).
- Interactive shells are described in @ref{Interactive Shells}.
- @subsubheading Invoked as an interactive login shell, or with @option{--login}
- When Bash is invoked as an interactive login shell, or as a
- non-interactive shell with the @option{--login} option, it first reads and
- executes commands from the file @file{/etc/profile}, if that file exists.
- After reading that file, it looks for @file{~/.bash_profile},
- @file{~/.bash_login}, and @file{~/.profile}, in that order, and reads
- and executes commands from the first one that exists and is readable.
- The @option{--noprofile} option may be used when the shell is started to
- inhibit this behavior.
- When an interactive login shell exits,
- or a non-interactive login shell executes the @code{exit} builtin command,
- Bash reads and executes commands from
- the file @file{~/.bash_logout}, if it exists.
- @subsubheading Invoked as an interactive non-login shell
- When an interactive shell that is not a login shell is started, Bash
- reads and executes commands from @file{~/.bashrc}, if that file exists.
- This may be inhibited by using the @option{--norc} option.
- The @option{--rcfile @var{file}} option will force Bash to read and
- execute commands from @var{file} instead of @file{~/.bashrc}.
- So, typically, your @file{~/.bash_profile} contains the line
- @example
- @code{if [ -f ~/.bashrc ]; then . ~/.bashrc; fi}
- @end example
- @noindent
- after (or before) any login-specific initializations.
- @subsubheading Invoked non-interactively
- When Bash is started non-interactively, to run a shell script,
- for example, it looks for the variable @env{BASH_ENV} 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. Bash behaves as if the
- following command were executed:
- @example
- @code{if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi}
- @end example
- @noindent
- but the value of the @env{PATH} variable is not used to search for the
- filename.
- As noted above, if a non-interactive shell is invoked with the
- @option{--login} option, Bash attempts to read and execute commands from the
- login shell startup files.
- @subsubheading Invoked with name @code{sh}
- If Bash is invoked with the name @code{sh}, it tries to mimic the
- startup behavior of historical versions of @code{sh} as closely as
- possible, while conforming to the @sc{posix} standard as well.
- When invoked as an interactive login shell, or as a non-interactive
- shell with the @option{--login} option, it first attempts to read
- and execute commands from @file{/etc/profile} and @file{~/.profile}, in
- that order.
- The @option{--noprofile} option may be used to inhibit this behavior.
- When invoked as an interactive shell with the name @code{sh}, Bash
- looks for the variable @env{ENV}, 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 @code{sh} does not attempt to read and execute
- commands from any other startup files, the @option{--rcfile} option has
- no effect.
- A non-interactive shell invoked with the name @code{sh} does not attempt
- to read any other startup files.
- When invoked as @code{sh}, Bash enters @sc{posix} mode after
- the startup files are read.
- @subsubheading Invoked in @sc{posix} mode
- When Bash is started in @sc{posix} mode, as with the
- @option{--posix} command line option, it follows the @sc{posix} standard
- for startup files.
- In this mode, interactive shells expand the @env{ENV} variable
- and commands are read and executed from the file whose name is the
- expanded value.
- No other startup files are read.
- @subsubheading Invoked by remote shell daemon
- Bash 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 @code{rshd}, or the secure shell daemon @code{sshd}.
- If Bash determines it is being run in
- this fashion, it reads and executes commands from @file{~/.bashrc}, if that
- file exists and is readable.
- It will not do this if invoked as @code{sh}.
- The @option{--norc} option may be used to inhibit this behavior, and the
- @option{--rcfile} option may be used to force another file to be read, but
- neither @code{rshd} nor @code{sshd} generally invoke the shell with those
- options or allow them to be specified.
- @subsubheading Invoked with unequal effective and real @sc{uid/gid}s
- If Bash is started with the effective user (group) id not equal to the
- real user (group) id, and the @option{-p} option is not supplied, no startup
- files are read, shell functions are not inherited from the environment,
- the @env{SHELLOPTS}, @env{BASHOPTS}, @env{CDPATH}, and @env{GLOBIGNORE}
- variables, if they appear in the environment, are ignored, and the effective
- user id is set to the real user id.
- If the @option{-p} option is supplied at invocation, the startup behavior is
- the same, but the effective user id is not reset.
- @node Interactive Shells
- @section Interactive Shells
- @cindex interactive shell
- @cindex shell, interactive
- @menu
- * What is an Interactive Shell?:: What determines whether a shell is Interactive.
- * Is this Shell Interactive?:: How to tell if a shell is interactive.
- * Interactive Shell Behavior:: What changes in a interactive shell?
- @end menu
- @node What is an Interactive Shell?
- @subsection What is an Interactive Shell?
- An interactive shell
- is one started without non-option arguments, unless @option{-s} is
- specified, without specifying the @option{-c} option, and
- whose input and error output are both
- connected to terminals (as determined by @code{isatty(3)}),
- or one started with the @option{-i} option.
- An interactive shell generally reads from and writes to a user's
- terminal.
- The @option{-s} invocation option may be used to set the positional parameters
- when an interactive shell is started.
- @node Is this Shell Interactive?
- @subsection Is this Shell Interactive?
- To determine within a startup script whether or not Bash is
- running interactively,
- test the value of the @samp{-} special parameter.
- It contains @code{i} when the shell is interactive. For example:
- @example
- case "$-" in
- *i*) echo This shell is interactive ;;
- *) echo This shell is not interactive ;;
- esac
- @end example
- Alternatively, startup scripts may examine the variable
- @env{PS1}; it is unset in non-interactive shells, and set in
- interactive shells. Thus:
- @example
- if [ -z "$PS1" ]; then
- echo This shell is not interactive
- else
- echo This shell is interactive
- fi
- @end example
- @node Interactive Shell Behavior
- @subsection Interactive Shell Behavior
- When the shell is running interactively, it changes its behavior in
- several ways.
- @enumerate
- @item
- Startup files are read and executed as described in @ref{Bash Startup Files}.
- @item
- Job Control (@pxref{Job Control}) is enabled by default. When job
- control is in effect, Bash ignores the keyboard-generated job control
- signals @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}.
- @item
- Bash expands and displays @env{PS1} before reading the first line
- of a command, and expands and displays @env{PS2} before reading the
- second and subsequent lines of a multi-line command.
- Bash expands and displays @env{PS0} after it reads a command but before
- executing it.
- See @ref{Controlling the Prompt}, for a complete list of prompt
- string escape sequences.
- @item
- Bash executes the values of the set elements of the @env{PROMPT_COMMANDS}
- array variable as commands before printing the primary prompt, @env{$PS1}
- (@pxref{Bash Variables}).
- @item
- Readline (@pxref{Command Line Editing}) is used to read commands from
- the user's terminal.
- @item
- Bash inspects the value of the @code{ignoreeof} option to @code{set -o}
- instead of exiting immediately when it receives an @code{EOF} on its
- standard input when reading a command (@pxref{The Set Builtin}).
- @item
- Command history (@pxref{Bash History Facilities})
- and history expansion (@pxref{History Interaction})
- are enabled by default.
- Bash will save the command history to the file named by @env{$HISTFILE}
- when a shell with history enabled exits.
- @item
- Alias expansion (@pxref{Aliases}) is performed by default.
- @item
- In the absence of any traps, Bash ignores @code{SIGTERM}
- (@pxref{Signals}).
- @item
- In the absence of any traps, @code{SIGINT} is caught and handled
- (@pxref{Signals}).
- @code{SIGINT} will interrupt some shell builtins.
- @item
- An interactive login shell sends a @code{SIGHUP} to all jobs on exit
- if the @code{huponexit} shell option has been enabled (@pxref{Signals}).
- @item
- The @option{-n} invocation option is ignored, and @samp{set -n} has
- no effect (@pxref{The Set Builtin}).
- @item
- Bash will check for mail periodically, depending on the values of the
- @env{MAIL}, @env{MAILPATH}, and @env{MAILCHECK} shell variables
- (@pxref{Bash Variables}).
- @item
- Expansion errors due to references to unbound shell variables after
- @samp{set -u} has been enabled will not cause the shell to exit
- (@pxref{The Set Builtin}).
- @item
- The shell will not exit on expansion errors caused by @var{var} being unset
- or null in @code{$@{@var{var}:?@var{word}@}} expansions
- (@pxref{Shell Parameter Expansion}).
- @item
- Redirection errors encountered by shell builtins will not cause the
- shell to exit.
- @item
- When running in @sc{posix} mode, a special builtin returning an error
- status will not cause the shell to exit (@pxref{Bash POSIX Mode}).
- @item
- A failed @code{exec} will not cause the shell to exit
- (@pxref{Bourne Shell Builtins}).
- @item
- Parser syntax errors will not cause the shell to exit.
- @item
- Simple spelling correction for directory arguments to the @code{cd}
- builtin is enabled by default (see the description of the @code{cdspell}
- option to the @code{shopt} builtin in @ref{The Shopt Builtin}).
- @item
- The shell will check the value of the @env{TMOUT} variable and exit
- if a command is not read within the specified number of seconds after
- printing @env{$PS1} (@pxref{Bash Variables}).
- @end enumerate
- @node Bash Conditional Expressions
- @section Bash Conditional Expressions
- @cindex expressions, conditional
- Conditional expressions are used by the @code{[[} compound command
- and the @code{test} and @code{[} builtin commands. The @code{test}
- and @code{[} commands determine their behavior based on the number
- of arguments; see the descriptions of those commands for any other
- command-specific actions.
- Expressions may be unary or binary,
- and are formed from the following primaries.
- Unary expressions are often used to examine the status of a file.
- There are string operators and numeric comparison operators as well.
- Bash handles several filenames specially when they are used in
- expressions.
- If the operating system on which Bash is running provides these
- special files, Bash will use them; otherwise it will emulate them
- internally with this behavior:
- If the @var{file} argument to one of the primaries is of the form
- @file{/dev/fd/@var{N}}, then file descriptor @var{N} is checked.
- If the @var{file} argument to one of the primaries is one of
- @file{/dev/stdin}, @file{/dev/stdout}, or @file{/dev/stderr}, file
- descriptor 0, 1, or 2, respectively, is checked.
- When used with @code{[[}, the @samp{<} and @samp{>} operators sort
- lexicographically using the current locale.
- The @code{test} command uses ASCII ordering.
- Unless otherwise specified, primaries that operate on files follow symbolic
- links and operate on the target of the link, rather than the link itself.
- @table @code
- @item -a @var{file}
- True if @var{file} exists.
- @item -b @var{file}
- True if @var{file} exists and is a block special file.
- @item -c @var{file}
- True if @var{file} exists and is a character special file.
- @item -d @var{file}
- True if @var{file} exists and is a directory.
- @item -e @var{file}
- True if @var{file} exists.
- @item -f @var{file}
- True if @var{file} exists and is a regular file.
- @item -g @var{file}
- True if @var{file} exists and its set-group-id bit is set.
- @item -h @var{file}
- True if @var{file} exists and is a symbolic link.
- @item -k @var{file}
- True if @var{file} exists and its "sticky" bit is set.
- @item -p @var{file}
- True if @var{file} exists and is a named pipe (FIFO).
- @item -r @var{file}
- True if @var{file} exists and is readable.
- @item -s @var{file}
- True if @var{file} exists and has a size greater than zero.
- @item -t @var{fd}
- True if file descriptor @var{fd} is open and refers to a terminal.
- @item -u @var{file}
- True if @var{file} exists and its set-user-id bit is set.
- @item -w @var{file}
- True if @var{file} exists and is writable.
- @item -x @var{file}
- True if @var{file} exists and is executable.
- @item -G @var{file}
- True if @var{file} exists and is owned by the effective group id.
- @item -L @var{file}
- True if @var{file} exists and is a symbolic link.
- @item -N @var{file}
- True if @var{file} exists and has been modified since it was last read.
- @item -O @var{file}
- True if @var{file} exists and is owned by the effective user id.
- @item -S @var{file}
- True if @var{file} exists and is a socket.
- @item @var{file1} -ef @var{file2}
- True if @var{file1} and @var{file2} refer to the same device and
- inode numbers.
- @item @var{file1} -nt @var{file2}
- True if @var{file1} is newer (according to modification date)
- than @var{file2}, or if @var{file1} exists and @var{file2} does not.
- @item @var{file1} -ot @var{file2}
- True if @var{file1} is older than @var{file2},
- or if @var{file2} exists and @var{file1} does not.
- @item -o @var{optname}
- True if the shell option @var{optname} is enabled.
- The list of options appears in the description of the @option{-o}
- option to the @code{set} builtin (@pxref{The Set Builtin}).
- @item -v @var{varname}
- True if the shell variable @var{varname} is set (has been assigned a value).
- @item -R @var{varname}
- True if the shell variable @var{varname} is set and is a name reference.
- @item -z @var{string}
- True if the length of @var{string} is zero.
- @item -n @var{string}
- @itemx @var{string}
- True if the length of @var{string} is non-zero.
- @item @var{string1} == @var{string2}
- @itemx @var{string1} = @var{string2}
- True if the strings are equal.
- When used with the @code{[[} command, this performs pattern matching as
- described above (@pxref{Conditional Constructs}).
- @samp{=} should be used with the @code{test} command for @sc{posix} conformance.
- @item @var{string1} != @var{string2}
- True if the strings are not equal.
- @item @var{string1} < @var{string2}
- True if @var{string1} sorts before @var{string2} lexicographically.
- @item @var{string1} > @var{string2}
- True if @var{string1} sorts after @var{string2} lexicographically.
- @item @var{arg1} OP @var{arg2}
- @code{OP} is one of
- @samp{-eq}, @samp{-ne}, @samp{-lt}, @samp{-le}, @samp{-gt}, or @samp{-ge}.
- These arithmetic binary operators return true if @var{arg1}
- is equal to, not equal to, less than, less than or equal to,
- greater than, or greater than or equal to @var{arg2},
- respectively. @var{Arg1} and @var{arg2}
- may be positive or negative integers.
- When used with the @code{[[} command, @var{Arg1} and @var{Arg2}
- are evaluated as arithmetic expressions (@pxref{Shell Arithmetic}).
- @end table
- @node Shell Arithmetic
- @section Shell Arithmetic
- @cindex arithmetic, shell
- @cindex shell arithmetic
- @cindex expressions, arithmetic
- @cindex evaluation, arithmetic
- @cindex arithmetic evaluation
- The shell allows arithmetic expressions to be evaluated, as one of
- the shell expansions or by using the @code{((} compound command, the
- @code{let} builtin, or the @option{-i} option to the @code{declare} builtin.
- 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.
- @table @code
- @item @var{id}++ @var{id}--
- variable post-increment and post-decrement
- @item ++@var{id} --@var{id}
- variable pre-increment and pre-decrement
- @item - +
- unary minus and plus
- @item ! ~
- logical and bitwise negation
- @item **
- exponentiation
- @item * / %
- multiplication, division, remainder
- @item + -
- addition, subtraction
- @item << >>
- left and right bitwise shifts
- @item <= >= < >
- comparison
- @item == !=
- equality and inequality
- @item &
- bitwise AND
- @item ^
- bitwise exclusive OR
- @item |
- bitwise OR
- @item &&
- logical AND
- @item ||
- logical OR
- @item expr ? expr : expr
- conditional operator
- @item = *= /= %= += -= <<= >>= &= ^= |=
- assignment
- @item expr1 , expr2
- comma
- @end table
- 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
- @var{integer} attribute using @samp{declare -i} is assigned a value.
- A null value evaluates to 0.
- A shell variable need not have its @var{integer} attribute turned on
- to be used in an expression.
- Integer constants follow the C language definition, without suffixes or
- character constants.
- Constants with a leading 0 are interpreted as octal numbers.
- A leading @samp{0x} or @samp{0X} denotes hexadecimal. Otherwise,
- numbers take the form [@var{base}@code{#}]@var{n}, where the optional @var{base}
- is a decimal number between 2 and 64 representing the arithmetic
- base, and @var{n} is a number in that base.
- If @var{base}@code{#} is omitted, then base 10 is used.
- When specifying @var{n},
- if a non-digit is required,
- the digits greater than 9 are represented by the lowercase letters,
- the uppercase letters, @samp{@@}, and @samp{_}, in that order.
- If @var{base} is less than or equal to 36, lowercase and uppercase
- letters may be used interchangeably to represent numbers between 10
- and 35.
- Operators are evaluated in order of precedence. Sub-expressions in
- parentheses are evaluated first and may override the precedence
- rules above.
- @node Aliases
- @section Aliases
- @cindex alias expansion
- @var{Aliases} 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 @code{alias} and @code{unalias} builtin commands.
- 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 @samp{/}, @samp{$}, @samp{`}, @samp{=} and any of the
- shell metacharacters 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 @code{ls} to @code{"ls -F"},
- for instance, and Bash does not try to recursively expand the
- replacement text.
- If the last character of the alias value is a
- @var{blank}, then the next command word following the
- alias is also checked for alias expansion.
- Aliases are created and listed with the @code{alias}
- command, and removed with the @code{unalias} command.
- There is no mechanism for using arguments in the replacement text,
- as in @code{csh}.
- If arguments are needed, a shell function should be used
- (@pxref{Shell Functions}).
- Aliases are not expanded when the shell is not interactive,
- unless the @code{expand_aliases} shell option is set using
- @code{shopt} (@pxref{The Shopt Builtin}).
- The rules concerning the definition and use of aliases are
- somewhat confusing. Bash
- always reads at least one complete line of input,
- and all lines that make up a compound command,
- before executing any of the commands on that line or the compound command.
- 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 @code{alias}
- in compound commands.
- For almost every purpose, shell functions are preferred over aliases.
- @node Arrays
- @section Arrays
- @cindex arrays
- Bash provides one-dimensional indexed and associative array variables.
- Any variable may be used as an indexed array;
- the @code{declare} 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 (@pxref{Shell Arithmetic})) and are zero-based;
- associative arrays use arbitrary strings.
- Unless otherwise noted, indexed array indices must be non-negative integers.
- An indexed array is created automatically if any variable is assigned to
- using the syntax
- @example
- @var{name}[@var{subscript}]=@var{value}
- @end example
- @noindent
- The @var{subscript}
- is treated as an arithmetic expression that must evaluate to a number.
- To explicitly declare an array, use
- @example
- declare -a @var{name}
- @end example
- @noindent
- The syntax
- @example
- declare -a @var{name}[@var{subscript}]
- @end example
- @noindent
- is also accepted; the @var{subscript} is ignored.
- @noindent
- Associative arrays are created using
- @example
- declare -A @var{name}
- @end example
- Attributes may be
- specified for an array variable using the @code{declare} and
- @code{readonly} builtins. Each attribute applies to all members of
- an array.
- Arrays are assigned to using compound assignments of the form
- @example
- @var{name}=(@var{value1} @var{value2} @dots{} )
- @end example
- @noindent
- where each
- @var{value} may be of the form @code{[@var{subscript}]=}@var{string}.
- Indexed array assignments do not require anything but @var{string}.
- When assigning to indexed arrays, if
- the optional subscript is 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.
- Each @var{value} in the list undergoes all the shell expansions
- described above (@pxref{Shell Expansions}).
- When assigning to an associative array, the words in a compound assignment
- may be either assignment statements, for which the subscript is required,
- or a list of words that is interpreted as a sequence of alternating keys
- and values:
- @var{name}=(@var{key1} @var{value1} @var{key2} @var{value2} @dots{} ).
- These are treated identically to
- @var{name}=( [@var{key1}]=@var{value1} [@var{key2}]=@var{value2} @dots{} ).
- The first word in the list determines how the remaining words
- are interpreted; all assignments in a list must be of the same type.
- When using key/value pairs, the keys may not be missing or empty;
- a final missing value is treated like the empty string.
- This syntax is also accepted by the @code{declare}
- builtin. Individual array elements may be assigned to using the
- @code{@var{name}[@var{subscript}]=@var{value}} syntax introduced above.
- When assigning to an indexed array, if @var{name}
- is subscripted by a negative number, that number is
- interpreted as relative to one greater than the maximum index of
- @var{name}, so negative indices count back from the end of the
- array, and an index of -1 references the last element.
- Any element of an array may be referenced using
- @code{$@{@var{name}[@var{subscript}]@}}.
- The braces are required to avoid
- conflicts with the shell's filename expansion operators. If the
- @var{subscript} is @samp{@@} or @samp{*}, the word expands to all members
- of the array @var{name}. These subscripts differ only when the word
- appears within double quotes.
- If the word is double-quoted,
- @code{$@{@var{name}[*]@}} expands to a single word with
- the value of each array member separated by the first character of the
- @env{IFS} variable, and @code{$@{@var{name}[@@]@}} expands each element of
- @var{name} to a separate word. When there are no array members,
- @code{$@{@var{name}[@@]@}} 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 @samp{@@} and @samp{*}.
- @code{$@{#@var{name}[@var{subscript}]@}} expands to the length of
- @code{$@{@var{name}[@var{subscript}]@}}.
- If @var{subscript} is @samp{@@} or
- @samp{*}, the expansion is the number of elements in the array.
- If the @var{subscript}
- 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 refers to the last element.
- Referencing an array variable without a subscript is equivalent to
- referencing with a subscript of 0.
- Any reference to a variable using a valid subscript is legal, and
- @code{bash} will create an array if necessary.
- An array variable is considered set if a subscript has been assigned a
- value. The null string is a valid value.
- It is possible to obtain the keys (indices) of an array as well as the values.
- $@{!@var{name}[@@]@} and $@{!@var{name}[*]@} expand to the indices
- assigned in array variable @var{name}.
- The treatment when in double quotes is similar to the expansion of the
- special parameters @samp{@@} and @samp{*} within double quotes.
- The @code{unset} builtin is used to destroy arrays.
- @code{unset @var{name}[@var{subscript}]}
- destroys the array element at index @var{subscript}.
- Negative subscripts to indexed arrays are interpreted as described above.
- Unsetting the last element of an array variable does not unset the variable.
- @code{unset @var{name}}, where @var{name} is an array, removes the
- entire array. A subscript of @samp{*} or @samp{@@} also removes the
- entire array.
- When using a variable name with a subscript as an argument to a command,
- such as with @code{unset}, without using the word expansion syntax
- described above, the argument is subject to the shell's filename expansion.
- If filename expansion is not desired, the argument should be quoted.
- The @code{declare}, @code{local}, and @code{readonly}
- builtins each accept a @option{-a} option to specify an indexed
- array and a @option{-A} option to specify an associative array.
- If both options are supplied, @option{-A} takes precedence.
- The @code{read} builtin accepts a @option{-a}
- option to assign a list of words read from the standard input
- to an array, and can read values from the standard input into
- individual array elements. The @code{set} and @code{declare}
- builtins display array values in a way that allows them to be
- reused as input.
- @node The Directory Stack
- @section The Directory Stack
- @cindex directory stack
- @menu
- * Directory Stack Builtins:: Bash builtin commands to manipulate
- the directory stack.
- @end menu
- The directory stack is a list of recently-visited directories. The
- @code{pushd} builtin adds directories to the stack as it changes
- the current directory, and the @code{popd} builtin removes specified
- directories from the stack and changes the current directory to
- the directory removed. The @code{dirs} builtin displays the contents
- of the directory stack. The current directory is always the "top"
- of the directory stack.
- The contents of the directory stack are also visible
- as the value of the @env{DIRSTACK} shell variable.
- @node Directory Stack Builtins
- @subsection Directory Stack Builtins
- @table @code
- @item dirs
- @btindex dirs
- @example
- dirs [-clpv] [+@var{N} | -@var{N}]
- @end example
- Display the list of currently remembered directories. Directories
- are added to the list with the @code{pushd} command; the
- @code{popd} command removes directories from the list.
- The current directory is always the first directory in the stack.
- @table @code
- @item -c
- Clears the directory stack by deleting all of the elements.
- @item -l
- Produces a listing using full pathnames;
- the default listing format uses a tilde to denote the home directory.
- @item -p
- Causes @code{dirs} to print the directory stack with one entry per
- line.
- @item -v
- Causes @code{dirs} to print the directory stack with one entry per
- line, prefixing each entry with its index in the stack.
- @item +@var{N}
- Displays the @var{N}th directory (counting from the left of the
- list printed by @code{dirs} when invoked without options), starting
- with zero.
- @item -@var{N}
- Displays the @var{N}th directory (counting from the right of the
- list printed by @code{dirs} when invoked without options), starting
- with zero.
- @end table
- @item popd
- @btindex popd
- @example
- popd [-n] [+@var{N} | -@var{N}]
- @end example
- When no arguments are given, @code{popd}
- removes the top directory from the stack and
- performs a @code{cd} to the new top directory.
- The elements are numbered from 0 starting at the first directory
- listed with @code{dirs}; that is, @code{popd} is equivalent to @code{popd +0}.
- @table @code
- @item -n
- Suppresses the normal change of directory when removing directories
- from the stack, so that only the stack is manipulated.
- @item +@var{N}
- Removes the @var{N}th directory (counting from the left of the
- list printed by @code{dirs}), starting with zero.
- @item -@var{N}
- Removes the @var{N}th directory (counting from the right of the
- list printed by @code{dirs}), starting with zero.
- @end table
- @btindex pushd
- @item pushd
- @example
- pushd [-n] [@var{+N} | @var{-N} | @var{dir}]
- @end example
- Save the current directory on the top of the directory stack
- and then @code{cd} to @var{dir}.
- With no arguments, @code{pushd} exchanges the top two directories
- and makes the new top the current directory.
- @table @code
- @item -n
- Suppresses the normal change of directory when rotating or
- adding directories to the stack, so that only the stack is manipulated.
- @item +@var{N}
- Brings the @var{N}th directory (counting from the left of the
- list printed by @code{dirs}, starting with zero) to the top of
- the list by rotating the stack.
- @item -@var{N}
- Brings the @var{N}th directory (counting from the right of the
- list printed by @code{dirs}, starting with zero) to the top of
- the list by rotating the stack.
- @item @var{dir}
- Makes @var{dir} be the top of the stack, making
- it the new current directory as if it had been supplied as an argument
- to the @code{cd} builtin.
- @end table
- @end table
- @node Controlling the Prompt
- @section Controlling the Prompt
- @cindex prompting
- Bash examines the value of the array variable @env{PROMPT_COMMANDS} just before
- printing each primary prompt.
- If any elements in @env{PROMPT_COMMANDS} are set and non-null, Bash
- executes each value, in numeric order,
- just as if it had been typed on the command line.
- In addition, the following table describes the special characters which
- can appear in the prompt variables @env{PS0}, @env{PS1}, @env{PS2}, and
- @env{PS4}:
- @table @code
- @item \a
- A bell character.
- @item \d
- The date, in "Weekday Month Date" format (e.g., "Tue May 26").
- @item \D@{@var{format}@}
- The @var{format} is passed to @code{strftime}(3) and the result is inserted
- into the prompt string; an empty @var{format} results in a locale-specific
- time representation. The braces are required.
- @item \e
- An escape character.
- @item \h
- The hostname, up to the first `.'.
- @item \H
- The hostname.
- @item \j
- The number of jobs currently managed by the shell.
- @item \l
- The basename of the shell's terminal device name.
- @item \n
- A newline.
- @item \r
- A carriage return.
- @item \s
- The name of the shell, the basename of @code{$0} (the portion
- following the final slash).
- @item \t
- The time, in 24-hour HH:MM:SS format.
- @item \T
- The time, in 12-hour HH:MM:SS format.
- @item \@@
- The time, in 12-hour am/pm format.
- @item \A
- The time, in 24-hour HH:MM format.
- @item \u
- The username of the current user.
- @item \v
- The version of Bash (e.g., 2.00)
- @item \V
- The release of Bash, version + patchlevel (e.g., 2.00.0)
- @item \w
- The current working directory, with @env{$HOME} abbreviated with a tilde
- (uses the @env{$PROMPT_DIRTRIM} variable).
- @item \W
- The basename of @env{$PWD}, with @env{$HOME} abbreviated with a tilde.
- @item \!
- The history number of this command.
- @item \#
- The command number of this command.
- @item \$
- If the effective uid is 0, @code{#}, otherwise @code{$}.
- @item \@var{nnn}
- The character whose ASCII code is the octal value @var{nnn}.
- @item \\
- A backslash.
- @item \[
- Begin a sequence of non-printing characters. This could be used to
- embed a terminal control sequence into the prompt.
- @item \]
- End a sequence of non-printing characters.
- @end table
- 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
- (@pxref{Bash History Facilities}), 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
- @code{promptvars} shell option (@pxref{The Shopt Builtin}).
- This can have unwanted side effects if escaped portions of the string
- appear within command substitution or contain characters special to
- word expansion.
- @node The Restricted Shell
- @section The Restricted Shell
- @cindex restricted shell
- If Bash is started with the name @code{rbash}, or the
- @option{--restricted}
- or
- @option{-r}
- 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.
- A restricted shell behaves identically to @code{bash}
- with the exception that the following are disallowed or not performed:
- @itemize @bullet
- @item
- Changing directories with the @code{cd} builtin.
- @item
- Setting or unsetting the values of the @env{SHELL}, @env{PATH},
- @env{HISTFILE},
- @env{ENV}, or @env{BASH_ENV} variables.
- @item
- Specifying command names containing slashes.
- @item
- Specifying a filename containing a slash as an argument to the @code{.}
- builtin command.
- @item
- Specifying a filename containing a slash as an argument to the @code{history}
- builtin command.
- @item
- Specifying a filename containing a slash as an argument to the @option{-p}
- option to the @code{hash} builtin command.
- @item
- Importing function definitions from the shell environment at startup.
- @item
- Parsing the value of @env{SHELLOPTS} from the shell environment at startup.
- @item
- Redirecting output using the @samp{>}, @samp{>|}, @samp{<>}, @samp{>&},
- @samp{&>}, and @samp{>>} redirection operators.
- @item
- Using the @code{exec} builtin to replace the shell with another command.
- @item
- Adding or deleting builtin commands with the
- @option{-f} and @option{-d} options to the @code{enable} builtin.
- @item
- Using the @code{enable} builtin command to enable disabled shell builtins.
- @item
- Specifying the @option{-p} option to the @code{command} builtin.
- @item
- Turning off restricted mode with @samp{set +r} or @samp{set +o restricted}.
- @end itemize
- These restrictions are enforced after any startup files are read.
- When a command that is found to be a shell script is executed
- (@pxref{Shell Scripts}), @code{rbash} turns off any restrictions in
- the shell spawned to execute the script.
- The restricted shell mode is only one component of a useful restricted
- environment. It should be accompanied by setting @env{PATH} to a value
- that allows execution of only a few verified commands (commands that
- allow shell escapes are particularly vulnerable), leaving the user
- in a non-writable directory other than his home directory after login,
- not allowing the restricted shell to execute shell scripts, and cleaning
- the environment of variables that cause some commands to modify their
- behavior (e.g., @env{VISUAL} or @env{PAGER}).
- Modern systems provide more secure ways to implement a restricted environment,
- such as @code{jails}, @code{zones}, or @code{containers}.
- @node Bash POSIX Mode
- @section Bash POSIX Mode
- @cindex POSIX Mode
- Starting Bash with the @option{--posix} command-line option or executing
- @samp{set -o posix} while Bash is running will cause Bash to conform more
- closely to the @sc{posix} standard by changing the behavior to
- match that specified by @sc{posix} in areas where the Bash default differs.
- When invoked as @code{sh}, Bash enters @sc{posix} mode after reading the
- startup files.
- The following list is what's changed when `@sc{posix} mode' is in effect:
- @enumerate
- @item
- Bash ensures that the @env{POSIXLY_CORRECT} variable is set.
- @item
- When a command in the hash table no longer exists, Bash will re-search
- @env{$PATH} to find the new location. This is also available with
- @samp{shopt -s checkhash}.
- @item
- Bash will not insert a command without the execute bit set into the
- command hash table, even if it returns it as a (last-ditch) result
- from a @env{$PATH} search.
- @item
- The message printed by the job control code and builtins when a job
- exits with a non-zero status is `Done(status)'.
- @item
- The message printed by the job control code and builtins when a job
- is stopped is `Stopped(@var{signame})', where @var{signame} is, for
- example, @code{SIGTSTP}.
- @item
- Alias expansion is always enabled, even in non-interactive shells.
- @item
- Reserved words appearing in a context where reserved words are recognized
- do not undergo alias expansion.
- @item
- The @sc{posix} @env{PS1} and @env{PS2} expansions of @samp{!} to
- the history number and @samp{!!} to @samp{!} are enabled,
- and parameter expansion is performed on the values of @env{PS1} and
- @env{PS2} regardless of the setting of the @code{promptvars} option.
- @item
- The @sc{posix} startup files are executed (@env{$ENV}) rather than
- the normal Bash files.
- @item
- Tilde expansion is only performed on assignments preceding a command
- name, rather than on all assignment statements on the line.
- @item
- The default history file is @file{~/.sh_history} (this is the
- default value of @env{$HISTFILE}).
- @item
- Redirection operators do not perform filename expansion on the word
- in the redirection unless the shell is interactive.
- @item
- Redirection operators do not perform word splitting on the word in the
- redirection.
- @item
- Function names must be valid shell @code{name}s. That is, they may not
- contain characters other than letters, digits, and underscores, and
- may not start with a digit. Declaring a function with an invalid name
- causes a fatal syntax error in non-interactive shells.
- @item
- Function names may not be the same as one of the @sc{posix} special
- builtins.
- @item
- @sc{posix} special builtins are found before shell functions
- during command lookup.
- @item
- When printing shell function definitions (e.g., by @code{type}), Bash does
- not print the @code{function} keyword.
- @item
- Literal tildes that appear as the first character in elements of
- the @env{PATH} variable are not expanded as described above
- under @ref{Tilde Expansion}.
- @item
- The @code{time} reserved word may be used by itself as a command. When
- used in this way, it displays timing statistics for the shell and its
- completed children. The @env{TIMEFORMAT} variable controls the format
- of the timing information.
- @item
- When parsing and expanding a $@{@dots{}@} expansion that appears within
- double quotes, single quotes are no longer special and cannot be used to
- quote a closing brace or other special character, unless the operator is
- one of those defined to perform pattern removal. In this case, they do
- not have to appear as matched pairs.
- @item
- The parser does not recognize @code{time} as a reserved word if the next
- token begins with a @samp{-}.
- @ignore
- @item
- When parsing @code{$()} command substitutions containing here-documents,
- the parser does not allow a here-document to be delimited by the closing
- right parenthesis. The newline after the here-document delimiter is required.
- @end ignore
- @item
- The @samp{!} character does not introduce history expansion within a
- double-quoted string, even if the @code{histexpand} option is enabled.
- @item
- If a @sc{posix} special builtin returns an error status, a
- non-interactive shell exits. The fatal errors are those listed in
- the @sc{posix} standard, and include things like passing incorrect options,
- redirection errors, variable assignment errors for assignments preceding
- the command name, and so on.
- @item
- A non-interactive shell exits with an error status if a variable
- assignment error occurs when no command name follows the assignment
- statements.
- A variable assignment error occurs, for example, when trying to assign
- a value to a readonly variable.
- @item
- A non-interactive shell exits with an error status if a variable
- assignment error occurs in an assignment statement preceding a special
- builtin, but not with any other simple command.
- @item
- A non-interactive shell exits with an error status if the iteration
- variable in a @code{for} statement or the selection variable in a
- @code{select} statement is a readonly variable.
- @item
- Non-interactive shells exit if @var{filename} in @code{.} @var{filename}
- is not found.
- @item
- Non-interactive shells exit if a syntax error in an arithmetic expansion
- results in an invalid expression.
- @item
- Non-interactive shells exit if a parameter expansion error occurs.
- @item
- Non-interactive shells exit if there is a syntax error in a script read
- with the @code{.} or @code{source} builtins, or in a string processed by
- the @code{eval} builtin.
- @item
- While variable indirection is available, it may not be applied to the
- @samp{#} and @samp{?} special parameters.
- @item
- When expanding the @samp{*} special parameter in a pattern context where the
- expansion is double-quoted does not treat the @code{$*} as if it were
- double-quoted.
- @item
- Assignment statements preceding @sc{posix} special builtins
- persist in the shell environment after the builtin completes.
- @item
- The @code{command} builtin does not prevent builtins that take assignment
- statements as arguments from expanding them as assignment statements;
- when not in @sc{posix} mode, assignment builtins lose their assignment
- statement expansion properties when preceded by @code{command}.
- @item
- The @code{bg} builtin uses the required format to describe each job placed
- in the background, which does not include an indication of whether the job
- is the current or previous job.
- @item
- The output of @samp{kill -l} prints all the signal names on a single line,
- separated by spaces, without the @samp{SIG} prefix.
- @item
- The @code{kill} builtin does not accept signal names with a @samp{SIG}
- prefix.
- @item
- The @code{export} and @code{readonly} builtin commands display their
- output in the format required by @sc{posix}.
- @item
- The @code{trap} builtin displays signal names without the leading
- @code{SIG}.
- @item
- The @code{trap} builtin doesn't check the first argument for a possible
- signal specification and revert the signal handling to the original
- disposition if it is, unless that argument consists solely of digits and
- is a valid signal number. If users want to reset the handler for a given
- signal to the original disposition, they should use @samp{-} as the
- first argument.
- @item
- @code{trap -p} displays signals whose dispositions are set to SIG_DFL and
- those that were ignored when the shell started.
- @item
- The @code{.} and @code{source} builtins do not search the current directory
- for the filename argument if it is not found by searching @env{PATH}.
- @item
- Enabling @sc{posix} mode has the effect of setting the
- @code{inherit_errexit} option, so
- subshells spawned to execute command substitutions inherit the value of
- the @option{-e} option from the parent shell.
- When the @code{inherit_errexit} option is not enabled,
- Bash clears the @option{-e} option in such subshells.
- @item
- Enabling @sc{posix} mode has the effect of setting the
- @code{shift_verbose} option, so numeric arguments to @code{shift}
- that exceed the number of positional parameters will result in an
- error message.
- @item
- When the @code{alias} builtin displays alias definitions, it does not
- display them with a leading @samp{alias } unless the @option{-p} option
- is supplied.
- @item
- When the @code{set} builtin is invoked without options, it does not display
- shell function names and definitions.
- @item
- When the @code{set} builtin is invoked without options, it displays
- variable values without quotes, unless they contain shell metacharacters,
- even if the result contains nonprinting characters.
- @item
- When the @code{cd} builtin is invoked in @var{logical} mode, and the pathname
- constructed from @code{$PWD} and the directory name supplied as an argument
- does not refer to an existing directory, @code{cd} will fail instead of
- falling back to @var{physical} mode.
- @item
- When the @code{cd} builtin cannot change a directory because the
- length of the pathname
- constructed from @code{$PWD} and the directory name supplied as an argument
- exceeds @var{PATH_MAX} when all symbolic links are expanded, @code{cd} will
- fail instead of attempting to use only the supplied directory name.
- @item
- The @code{pwd} builtin verifies that the value it prints is the same as the
- current directory, even if it is not asked to check the file system with the
- @option{-P} option.
- @item
- When listing the history, the @code{fc} builtin does not include an
- indication of whether or not a history entry has been modified.
- @item
- The default editor used by @code{fc} is @code{ed}.
- @item
- The @code{type} and @code{command} builtins will not report a non-executable
- file as having been found, though the shell will attempt to execute such a
- file if it is the only so-named file found in @code{$PATH}.
- @item
- The @code{vi} editing mode will invoke the @code{vi} editor directly when
- the @samp{v} command is run, instead of checking @code{$VISUAL} and
- @code{$EDITOR}.
- @item
- When the @code{xpg_echo} option is enabled, Bash does not attempt to interpret
- any arguments to @code{echo} as options. Each argument is displayed, after
- escape characters are converted.
- @item
- The @code{ulimit} builtin uses a block size of 512 bytes for the @option{-c}
- and @option{-f} options.
- @item
- The arrival of @code{SIGCHLD} when a trap is set on @code{SIGCHLD} does
- not interrupt the @code{wait} builtin and cause it to return immediately.
- The trap command is run once for each child that exits.
- @item
- The @code{read} builtin may be interrupted by a signal for which a trap
- has been set.
- If Bash receives a trapped signal while executing @code{read}, the trap
- handler executes and @code{read} returns an exit status greater than 128.
- @item
- Bash removes an exited background process's status from the list of such
- statuses after the @code{wait} builtin is used to obtain it.
- @end enumerate
- There is other @sc{posix} behavior that Bash does not implement by
- default even when in @sc{posix} mode.
- Specifically:
- @enumerate
- @item
- The @code{fc} builtin checks @code{$EDITOR} as a program to edit history
- entries if @code{FCEDIT} is unset, rather than defaulting directly to
- @code{ed}. @code{fc} uses @code{ed} if @code{EDITOR} is unset.
- @item
- As noted above, Bash requires the @code{xpg_echo} option to be enabled for
- the @code{echo} builtin to be fully conformant.
- @end enumerate
- Bash can be configured to be @sc{posix}-conformant by default, by specifying
- the @option{--enable-strict-posix-default} to @code{configure} when building
- (@pxref{Optional Features}).
- @node Shell Compatibility Mode
- @section Shell Compatibility Mode
- @cindex Compatibility Level
- @cindex Compatibility Mode
- Bash-4.0 introduced the concept of a `shell compatibility level', specified
- as a set of options to the shopt builtin
- (@code{compat31},
- @code{compat32},
- @code{compat40},
- @code{compat41},
- and so on).
- There is only one current
- compatibility level -- each option is mutually exclusive.
- The compatibility level is intended to allow users to select behavior
- from previous versions that is incompatible with newer versions
- while they migrate scripts to use current features and
- behavior. It's intended to be a temporary solution.
- This section does not mention behavior that is standard for a particular
- version (e.g., setting @code{compat32} means that quoting the rhs of the regexp
- matching operator quotes special regexp characters in the word, which is
- default behavior in bash-3.2 and above).
- If a user enables, say, @code{compat32}, it may affect the behavior of other
- compatibility levels up to and including the current compatibility level.
- The idea is that each compatibility level controls behavior that changed
- in that version of Bash,
- but that behavior may have been present in earlier versions.
- For instance, the change to use locale-based comparisons with the @code{[[}
- command came in bash-4.1, and earlier versions used ASCII-based comparisons,
- so enabling @code{compat32} will enable ASCII-based comparisons as well.
- That granularity may not be sufficient for
- all uses, and as a result users should employ compatibility levels carefully.
- Read the documentation for a particular feature to find out the
- current behavior.
- Bash-4.3 introduced a new shell variable: @env{BASH_COMPAT}.
- The value assigned
- to this variable (a decimal version number like 4.2, or an integer
- corresponding to the @code{compat}@var{NN} option, like 42) determines the
- compatibility level.
- Starting with bash-4.4, Bash has begun deprecating older compatibility
- levels.
- Eventually, the options will be removed in favor of @env{BASH_COMPAT}.
- Bash-5.0 is the final version for which there will be an individual shopt
- option for the previous version. Users should use @env{BASH_COMPAT}
- on bash-5.0 and later versions.
- The following table describes the behavior changes controlled by each
- compatibility level setting.
- The @code{compat}@var{NN} tag is used as shorthand for setting the
- compatibility level
- to @var{NN} using one of the following mechanisms.
- For versions prior to bash-5.0, the compatibility level may be set using
- the corresponding @code{compat}@var{NN} shopt option.
- For bash-4.3 and later versions, the @env{BASH_COMPAT} variable is preferred,
- and it is required for bash-5.1 and later versions.
- @table @code
- @item compat31
- @itemize @bullet
- @item
- quoting the rhs of the @code{[[} command's regexp matching operator (=~)
- has no special effect
- @end itemize
- @item compat32
- @itemize @bullet
- @item
- interrupting a command list such as "a ; b ; c" causes the execution
- of the next command in the list (in bash-4.0 and later versions,
- the shell acts as if it received the interrupt, so
- interrupting one command in a list aborts the execution of the
- entire list)
- @end itemize
- @item compat40
- @itemize @bullet
- @item
- the @samp{<} and @samp{>} operators to the @code{[[} command do not
- consider the current locale when comparing strings; they use ASCII
- ordering.
- Bash versions prior to bash-4.1 use ASCII collation and strcmp(3);
- bash-4.1 and later use the current locale's collation sequence and
- strcoll(3).
- @end itemize
- @item compat41
- @itemize @bullet
- @item
- in posix mode, @code{time} may be followed by options and still be
- recognized as a reserved word (this is @sc{posix} interpretation 267)
- @item
- in posix mode, the parser requires that an even number of single
- quotes occur in the @var{word} portion of a double-quoted $@{@dots{}@}
- parameter expansion and treats them specially, so that characters within
- the single quotes are considered quoted
- (this is @sc{posix} interpretation 221)
- @end itemize
- @item compat42
- @itemize @bullet
- @item
- the replacement string in double-quoted pattern substitution does not
- undergo quote removal, as it does in versions after bash-4.2
- @item
- in posix mode, single quotes are considered special when expanding
- the @var{word} portion of a double-quoted $@{@dots{}@} parameter expansion
- and can be used to quote a closing brace or other special character
- (this is part of @sc{posix} interpretation 221);
- in later versions, single quotes
- are not special within double-quoted word expansions
- @end itemize
- @item compat43
- @itemize @bullet
- @item
- the shell does not print a warning message if an attempt is made to
- use a quoted compound assignment as an argument to declare
- (declare -a foo='(1 2)'). Later versions warn that this usage is
- deprecated
- @item
- word expansion errors are considered non-fatal errors that cause the
- current command to fail, even in posix mode
- (the default behavior is to make them fatal errors that cause the shell
- to exit)
- @item
- when executing a shell function, the loop state (while/until/etc.)
- is not reset, so @code{break} or @code{continue} in that function will break
- or continue loops in the calling context. Bash-4.4 and later reset
- the loop state to prevent this
- @end itemize
- @item compat44
- @itemize @bullet
- @item
- the shell sets up the values used by @env{BASH_ARGV} and @env{BASH_ARGC}
- so they can expand to the shell's positional parameters even if extended
- debugging mode is not enabled
- @item
- a subshell inherits loops from its parent context, so @code{break}
- or @code{continue} will cause the subshell to exit.
- Bash-5.0 and later reset the loop state to prevent the exit
- @item
- variable assignments preceding builtins like @code{export} and @code{readonly}
- that set attributes continue to affect variables with the same
- name in the calling environment even if the shell is not in posix
- mode
- @end itemize
- @item compat50 (set using BASH_COMPAT)
- @itemize @bullet
- @item
- Bash-5.1 changed the way @code{$RANDOM} is generated to introduce slightly
- more randomness. If the shell compatibility level is set to 50 or
- lower, it reverts to the method from bash-5.0 and previous versions,
- so seeding the random number generator by assigning a value to
- @env{RANDOM} will produce the same sequence as in bash-5.0
- @item
- If the command hash table is empty, Bash versions prior to bash-5.1
- printed an informational message to that effect, even when producing
- output that can be reused as input. Bash-5.1 suppresses that message
- when the @option{-l} option is supplied.
- @end itemize
- @end table
- @node Job Control
- @chapter Job Control
- This chapter discusses what job control is, how it works, and how
- Bash allows you to access its facilities.
- @menu
- * Job Control Basics:: How job control works.
- * Job Control Builtins:: Bash builtin commands used to interact
- with job control.
- * Job Control Variables:: Variables Bash uses to customize job
- control.
- @end menu
- @node Job Control Basics
- @section Job Control Basics
- @cindex job control
- @cindex foreground
- @cindex background
- @cindex suspending jobs
- Job control
- refers to the ability to selectively stop (suspend)
- the execution of processes and continue (resume)
- 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 Bash.
- The shell associates a @var{job} with each pipeline. It keeps a
- table of currently executing jobs, which may be listed with the
- @code{jobs} command. When Bash starts a job
- asynchronously, it prints a line that looks
- like:
- @example
- [1] 25647
- @end example
- @noindent
- indicating that this job is job number 1 and that the process @sc{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. Bash uses the @var{job} abstraction as the
- basis for job control.
- To facilitate the implementation of the user interface to job
- control, the operating system maintains the notion of a current terminal
- process group @sc{id}. Members of this process group (processes whose
- process group @sc{id} is equal to the current terminal process group
- @sc{id}) receive keyboard-generated signals such as @code{SIGINT}.
- These processes are said to be in the foreground. Background
- processes are those whose process group @sc{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 @code{stty tostop}, write to the terminal.
- Background processes which attempt to
- read from (write to when @code{stty tostop} is in effect) the
- terminal are sent a @code{SIGTTIN} (@code{SIGTTOU})
- signal by the kernel's terminal driver,
- which, unless caught, suspends the process.
- If the operating system on which Bash is running supports
- job control, Bash contains facilities to use it. Typing the
- @var{suspend} character (typically @samp{^Z}, Control-Z) while a
- process is running causes that process to be stopped and returns
- control to Bash. Typing the @var{delayed suspend} character
- (typically @samp{^Y}, Control-Y) causes the process to be stopped
- when it attempts to read input from the terminal, and control to
- be returned to Bash. The user then manipulates the state of
- this job, using the @code{bg} command to continue it in the
- background, the @code{fg} command to continue it in the
- foreground, or the @code{kill} command to kill it. A @samp{^Z}
- takes effect immediately, and has the additional side effect of
- causing pending output and typeahead to be discarded.
- There are a number of ways to refer to a job in the shell. The
- character @samp{%} introduces a job specification (@var{jobspec}).
- Job number @code{n} may be referred to as @samp{%n}.
- The symbols @samp{%%} and @samp{%+} refer to the shell's notion of the
- current job, which is the last job stopped while it was in the foreground
- or started in the background.
- A single @samp{%} (with no accompanying job specification) also refers
- to the current job.
- The previous job may be referenced using @samp{%-}.
- If there is only a single job, @samp{%+} and @samp{%-} can both be used
- to refer to that job.
- In output pertaining to jobs (e.g., the output of the @code{jobs}
- command), the current job is always flagged with a @samp{+}, and the
- previous job with a @samp{-}.
- 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, @samp{%ce} refers
- to a stopped job whose command name begins with @samp{ce}.
- Using @samp{%?ce}, on the
- other hand, refers to any job containing the string @samp{ce} in
- its command line. If the prefix or substring matches more than one job,
- Bash reports an error.
- Simply naming a job can be used to bring it into the foreground:
- @samp{%1} is a synonym for @samp{fg %1}, bringing job 1 from the
- background into the foreground. Similarly, @samp{%1 &} resumes
- job 1 in the background, equivalent to @samp{bg %1}
- The shell learns immediately whenever a job changes state.
- Normally, Bash 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 @option{-b} option to the @code{set} builtin is enabled,
- Bash reports such changes immediately (@pxref{The Set Builtin}).
- Any trap on @code{SIGCHLD} is executed for each child process
- that exits.
- If an attempt to exit Bash is made while jobs are stopped, (or running, if
- the @code{checkjobs} option is enabled -- see @ref{The Shopt Builtin}), the
- shell prints a warning message, and if the @code{checkjobs} option is
- enabled, lists the jobs and their statuses.
- The @code{jobs} command may then be used to inspect their status.
- If a second attempt to exit is made without an intervening command,
- Bash does not print another warning, and any stopped jobs are terminated.
- When the shell is waiting for a job or process using the @code{wait}
- builtin, and job control is enabled, @code{wait} will return when the
- job changes state. The @option{-f} option causes @code{wait} to wait
- until the job or process terminates before returning.
- @node Job Control Builtins
- @section Job Control Builtins
- @table @code
- @item bg
- @btindex bg
- @example
- bg [@var{jobspec} @dots{}]
- @end example
- Resume each suspended job @var{jobspec} in the background, as if it
- had been started with @samp{&}.
- If @var{jobspec} is not supplied, the current job is used.
- The return status is zero unless it is run when job control is not
- enabled, or, when run with job control enabled, any
- @var{jobspec} was not found or specifies a job
- that was started without job control.
- @item fg
- @btindex fg
- @example
- fg [@var{jobspec}]
- @end example
- Resume the job @var{jobspec} in the foreground and make it the current job.
- If @var{jobspec} is not supplied, the current job is used.
- The return status is that of the command placed into the foreground,
- or non-zero if run when job control is disabled or, when run with
- job control enabled, @var{jobspec} does not specify a valid job or
- @var{jobspec} specifies a job that was started without job control.
- @item jobs
- @btindex jobs
- @example
- jobs [-lnprs] [@var{jobspec}]
- jobs -x @var{command} [@var{arguments}]
- @end example
- The first form lists the active jobs. The options have the
- following meanings:
- @table @code
- @item -l
- List process @sc{id}s in addition to the normal information.
- @item -n
- Display information only about jobs that have changed status since
- the user was last notified of their status.
- @item -p
- List only the process @sc{id} of the job's process group leader.
- @item -r
- Display only running jobs.
- @item -s
- Display only stopped jobs.
- @end table
- If @var{jobspec} is given,
- output is restricted to information about that job.
- If @var{jobspec} is not supplied, the status of all jobs is
- listed.
- If the @option{-x} option is supplied, @code{jobs} replaces any
- @var{jobspec} found in @var{command} or @var{arguments} with the
- corresponding process group @sc{id}, and executes @var{command},
- passing it @var{argument}s, returning its exit status.
- @item kill
- @btindex kill
- @example
- kill [-s @var{sigspec}] [-n @var{signum}] [-@var{sigspec}] @var{jobspec} or @var{pid}
- kill -l|-L [@var{exit_status}]
- @end example
- Send a signal specified by @var{sigspec} or @var{signum} to the process
- named by job specification @var{jobspec} or process @sc{id} @var{pid}.
- @var{sigspec} is either a case-insensitive signal name such as
- @code{SIGINT} (with or without the @code{SIG} prefix)
- or a signal number; @var{signum} is a signal number.
- If @var{sigspec} and @var{signum} are not present, @code{SIGTERM} is used.
- The @option{-l} option lists the signal names.
- If any arguments are supplied when @option{-l} is given, the names of the
- signals corresponding to the arguments are listed, and the return status
- is zero.
- @var{exit_status} is a number specifying a signal number or the exit
- status of a process terminated by a signal.
- The @option{-L} option is equivalent to @option{-l}.
- The return status is zero if at least one signal was successfully sent,
- or non-zero if an error occurs or an invalid option is encountered.
- @item wait
- @btindex wait
- @example
- wait [-fn] [-p @var{varname}] [@var{jobspec} or @var{pid} @dots{}]
- @end example
- Wait until the child process specified by each process @sc{id} @var{pid}
- or job specification @var{jobspec} exits and return the exit status of the
- last command waited for.
- If a job spec is given, all processes in the job are waited for.
- If no arguments are given,
- @code{wait} waits for all running background jobs and
- the last-executed process substitution, if its process id is the same as
- @var{$!},
- and the return status is zero.
- If the @option{-n} option is supplied, @code{wait} waits for a single job
- from the list of @var{pids} or @var{jobspecs} or, if no arguments are
- supplied, any job,
- to complete and returns its exit status.
- If none of the supplied arguments is a child of the shell, or if no arguments
- are supplied and the shell has no unwaited-for children, the exit status
- is 127.
- If the @option{-p} option is supplied, the process or job identifier of the job
- for which the exit status is returned is assigned to the variable
- @var{varname} named by the option argument.
- The variable will be unset initially, before any assignment.
- This is useful only when the @option{-n} option is supplied.
- Supplying the @option{-f} option, when job control is enabled,
- forces @code{wait} to wait for each @var{pid} or @var{jobspec} to
- terminate before returning its status, intead of returning when it changes
- status.
- If neither @var{jobspec} nor @var{pid} specifies an active child process
- of the shell, the return status is 127.
- @item disown
- @btindex disown
- @example
- disown [-ar] [-h] [@var{jobspec} @dots{} | @var{pid} @dots{} ]
- @end example
- Without options, remove each @var{jobspec} from the table of
- active jobs.
- If the @option{-h} option is given, the job is not removed from the table,
- but is marked so that @code{SIGHUP} is not sent to the job if the shell
- receives a @code{SIGHUP}.
- If @var{jobspec} is not present, and neither the @option{-a} nor the
- @option{-r} option is supplied, the current job is used.
- If no @var{jobspec} is supplied, the @option{-a} option means to remove or
- mark all jobs; the @option{-r} option without a @var{jobspec}
- argument restricts operation to running jobs.
- @item suspend
- @btindex suspend
- @example
- suspend [-f]
- @end example
- Suspend the execution of this shell until it receives a
- @code{SIGCONT} signal.
- A login shell cannot be suspended; the @option{-f}
- option can be used to override this and force the suspension.
- @end table
- When job control is not active, the @code{kill} and @code{wait}
- builtins do not accept @var{jobspec} arguments. They must be
- supplied process @sc{id}s.
- @node Job Control Variables
- @section Job Control Variables
- @vtable @code
- @item auto_resume
- This variable controls how the shell interacts with the user and
- job control. If this variable exists then single word simple
- commands without redirections are treated as candidates for resumption
- of an existing job. There is no ambiguity allowed; if there is
- more than one job beginning with the string typed, then
- the most recently accessed job will be selected.
- The name of a stopped job, in this context, is the command line
- used to start it. If this variable is set to the value @samp{exact},
- the string supplied must match the name of a stopped job exactly;
- if set to @samp{substring},
- the string supplied needs to match a substring of the name of a
- stopped job. The @samp{substring} value provides functionality
- analogous to the @samp{%?} job @sc{id} (@pxref{Job Control Basics}).
- 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 @samp{%} job @sc{id}.
- @end vtable
- @set readline-appendix
- @set history-appendix
- @cindex Readline, how to use
- @include rluser.texi
- @cindex History, how to use
- @include hsuser.texi
- @clear readline-appendix
- @clear history-appendix
- @node Installing Bash
- @chapter Installing Bash
- This chapter provides basic instructions for installing Bash on
- the various supported platforms. The distribution supports the
- @sc{gnu} operating systems, nearly every version of Unix, and several
- non-Unix systems such as BeOS and Interix.
- Other independent ports exist for
- @sc{ms-dos}, @sc{os/2}, and Windows platforms.
- @menu
- * Basic Installation:: Installation instructions.
- * Compilers and Options:: How to set special options for various
- systems.
- * Compiling For Multiple Architectures:: How to compile Bash for more
- than one kind of system from
- the same source tree.
- * Installation Names:: How to set the various paths used by the installation.
- * Specifying the System Type:: How to configure Bash for a particular system.
- * Sharing Defaults:: How to share default configuration values among GNU
- programs.
- * Operation Controls:: Options recognized by the configuration program.
- * Optional Features:: How to enable and disable optional features when
- building Bash.
- @end menu
- @node Basic Installation
- @section Basic Installation
- @cindex installation
- @cindex configuration
- @cindex Bash installation
- @cindex Bash configuration
- These are installation instructions for Bash.
- The simplest way to compile Bash is:
- @enumerate
- @item
- @code{cd} to the directory containing the source code and type
- @samp{./configure} to configure Bash for your system. If you're
- using @code{csh} on an old version of System V, you might need to
- type @samp{sh ./configure} instead to prevent @code{csh} from trying
- to execute @code{configure} itself.
- Running @code{configure} takes some time.
- While running, it prints messages telling which features it is
- checking for.
- @item
- Type @samp{make} to compile Bash and build the @code{bashbug} bug
- reporting script.
- @item
- Optionally, type @samp{make tests} to run the Bash test suite.
- @item
- Type @samp{make install} to install @code{bash} and @code{bashbug}.
- This will also install the manual pages and Info file.
- @end enumerate
- The @code{configure} shell script attempts to guess correct
- values for various system-dependent variables used during
- compilation. It uses those values to create a @file{Makefile} in
- each directory of the package (the top directory, the
- @file{builtins}, @file{doc}, and @file{support} directories,
- each directory under @file{lib}, and several others). It also creates a
- @file{config.h} file containing system-dependent definitions.
- Finally, it creates a shell script named @code{config.status} that you
- can run in the future to recreate the current configuration, a
- file @file{config.cache} that saves the results of its tests to
- speed up reconfiguring, and a file @file{config.log} containing
- compiler output (useful mainly for debugging @code{configure}).
- If at some point
- @file{config.cache} contains results you don't want to keep, you
- may remove or edit it.
- To find out more about the options and arguments that the
- @code{configure} script understands, type
- @example
- bash-4.2$ ./configure --help
- @end example
- @noindent
- at the Bash prompt in your Bash source directory.
- If you want to build Bash in a directory separate from the source
- directory -- to build for multiple architectures, for example --
- just use the full path to the configure script. The following commands
- will build bash in a directory under @file{/usr/local/build} from
- the source code in @file{/usr/local/src/bash-4.4}:
- @example
- mkdir /usr/local/build/bash-4.4
- cd /usr/local/build/bash-4.4
- bash /usr/local/src/bash-4.4/configure
- make
- @end example
- See @ref{Compiling For Multiple Architectures} for more information
- about building in a directory separate from the source.
- If you need to do unusual things to compile Bash, please
- try to figure out how @code{configure} could check whether or not
- to do them, and mail diffs or instructions to
- @email{bash-maintainers@@gnu.org} so they can be
- considered for the next release.
- The file @file{configure.ac} is used to create @code{configure}
- by a program called Autoconf. You only need
- @file{configure.ac} if you want to change it or regenerate
- @code{configure} using a newer version of Autoconf. If
- you do this, make sure you are using Autoconf version 2.50 or
- newer.
- You can remove the program binaries and object files from the
- source code directory by typing @samp{make clean}. To also remove the
- files that @code{configure} created (so you can compile Bash for
- a different kind of computer), type @samp{make distclean}.
- @node Compilers and Options
- @section Compilers and Options
- Some systems require unusual options for compilation or linking
- that the @code{configure} script does not know about. You can
- give @code{configure} initial values for variables by setting
- them in the environment. Using a Bourne-compatible shell, you
- can do that on the command line like this:
- @example
- CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure
- @end example
- On systems that have the @code{env} program, you can do it like this:
- @example
- env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
- @end example
- The configuration process uses GCC to build Bash if it
- is available.
- @node Compiling For Multiple Architectures
- @section Compiling For Multiple Architectures
- You can compile Bash for more than one kind of computer at the
- same time, by placing the object files for each architecture in their
- own directory. To do this, you must use a version of @code{make} that
- supports the @code{VPATH} variable, such as GNU @code{make}.
- @code{cd} to the
- directory where you want the object files and executables to go and run
- the @code{configure} script from the source directory
- (@pxref{Basic Installation}).
- You may need to
- supply the @option{--srcdir=PATH} argument to tell @code{configure} where the
- source files are. @code{configure} automatically checks for the
- source code in the directory that @code{configure} is in and in `..'.
- If you have to use a @code{make} that does not supports the @code{VPATH}
- variable, you can compile Bash for one architecture at a
- time in the source code directory. After you have installed
- Bash for one architecture, use @samp{make distclean} before
- reconfiguring for another architecture.
- Alternatively, if your system supports symbolic links, you can use the
- @file{support/mkclone} script to create a build tree which has
- symbolic links back to each file in the source directory. Here's an
- example that creates a build directory in the current directory from a
- source directory @file{/usr/gnu/src/bash-2.0}:
- @example
- bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 .
- @end example
- @noindent
- The @code{mkclone} script requires Bash, so you must have already built
- Bash for at least one architecture before you can create build
- directories for other architectures.
- @node Installation Names
- @section Installation Names
- By default, @samp{make install} will install into
- @file{/usr/local/bin}, @file{/usr/local/man}, etc. You can
- specify an installation prefix other than @file{/usr/local} by
- giving @code{configure} the option @option{--prefix=@var{PATH}},
- or by specifying a value for the @code{DESTDIR} @samp{make}
- variable when running @samp{make install}.
- You can specify separate installation prefixes for
- architecture-specific files and architecture-independent files.
- If you give @code{configure} the option
- @option{--exec-prefix=@var{PATH}}, @samp{make install} will use
- @var{PATH} as the prefix for installing programs and libraries.
- Documentation and other data files will still use the regular prefix.
- @node Specifying the System Type
- @section Specifying the System Type
- There may be some features @code{configure} can not figure out
- automatically, but need to determine by the type of host Bash
- will run on. Usually @code{configure} can figure that
- out, but if it prints a message saying it can not guess the host
- type, give it the @option{--host=TYPE} option. @samp{TYPE} can
- either be a short name for the system type, such as @samp{sun4},
- or a canonical name with three fields: @samp{CPU-COMPANY-SYSTEM}
- (e.g., @samp{i386-unknown-freebsd4.2}).
- See the file @file{support/config.sub} for the possible
- values of each field.
- @node Sharing Defaults
- @section Sharing Defaults
- If you want to set default values for @code{configure} scripts to
- share, you can create a site shell script called
- @code{config.site} that gives default values for variables like
- @code{CC}, @code{cache_file}, and @code{prefix}. @code{configure}
- looks for @file{PREFIX/share/config.site} if it exists, then
- @file{PREFIX/etc/config.site} if it exists. Or, you can set the
- @code{CONFIG_SITE} environment variable to the location of the site
- script. A warning: the Bash @code{configure} looks for a site script,
- but not all @code{configure} scripts do.
- @node Operation Controls
- @section Operation Controls
- @code{configure} recognizes the following options to control how it
- operates.
- @table @code
- @item --cache-file=@var{file}
- Use and save the results of the tests in
- @var{file} instead of @file{./config.cache}. Set @var{file} to
- @file{/dev/null} to disable caching, for debugging
- @code{configure}.
- @item --help
- Print a summary of the options to @code{configure}, and exit.
- @item --quiet
- @itemx --silent
- @itemx -q
- Do not print messages saying which checks are being made.
- @item --srcdir=@var{dir}
- Look for the Bash source code in directory @var{dir}. Usually
- @code{configure} can determine that directory automatically.
- @item --version
- Print the version of Autoconf used to generate the @code{configure}
- script, and exit.
- @end table
- @code{configure} also accepts some other, not widely used, boilerplate
- options. @samp{configure --help} prints the complete list.
- @node Optional Features
- @section Optional Features
- The Bash @code{configure} has a number of @option{--enable-@var{feature}}
- options, where @var{feature} indicates an optional part of Bash.
- There are also several @option{--with-@var{package}} options,
- where @var{package} is something like @samp{bash-malloc} or @samp{purify}.
- To turn off the default use of a package, use
- @option{--without-@var{package}}. To configure Bash without a feature
- that is enabled by default, use @option{--disable-@var{feature}}.
- Here is a complete list of the @option{--enable-} and
- @option{--with-} options that the Bash @code{configure} recognizes.
- @table @code
- @item --with-afs
- Define if you are using the Andrew File System from Transarc.
- @item --with-bash-malloc
- Use the Bash version of
- @code{malloc} in the directory @file{lib/malloc}. This is not the same
- @code{malloc} that appears in @sc{gnu} libc, but an older version
- originally derived from the 4.2 @sc{bsd} @code{malloc}. This @code{malloc}
- is very fast, but wastes some space on each allocation.
- This option is enabled by default.
- The @file{NOTES} file contains a list of systems for
- which this should be turned off, and @code{configure} disables this
- option automatically for a number of systems.
- @item --with-curses
- Use the curses library instead of the termcap library. This should
- be supplied if your system has an inadequate or incomplete termcap
- database.
- @item --with-gnu-malloc
- A synonym for @code{--with-bash-malloc}.
- @item --with-installed-readline[=@var{PREFIX}]
- Define this to make Bash link with a locally-installed version of Readline
- rather than the version in @file{lib/readline}. This works only with
- Readline 5.0 and later versions. If @var{PREFIX} is @code{yes} or not
- supplied, @code{configure} uses the values of the make variables
- @code{includedir} and @code{libdir}, which are subdirectories of @code{prefix}
- by default, to find the installed version of Readline if it is not in
- the standard system include and library directories.
- If @var{PREFIX} is @code{no}, Bash links with the version in
- @file{lib/readline}.
- If @var{PREFIX} is set to any other value, @code{configure} treats it as
- a directory pathname and looks for
- the installed version of Readline in subdirectories of that directory
- (include files in @var{PREFIX}/@code{include} and the library in
- @var{PREFIX}/@code{lib}).
- @item --with-purify
- Define this to use the Purify memory allocation checker from Rational
- Software.
- @item --enable-minimal-config
- This produces a shell with minimal features, close to the historical
- Bourne shell.
- @end table
- There are several @option{--enable-} options that alter how Bash is
- compiled and linked, rather than changing run-time features.
- @table @code
- @item --enable-largefile
- Enable support for @uref{http://www.unix.org/version2/whatsnew/lfs20mar.html,
- large files} if the operating system requires special compiler options
- to build programs which can access large files. This is enabled by
- default, if the operating system provides large file support.
- @item --enable-profiling
- This builds a Bash binary that produces profiling information to be
- processed by @code{gprof} each time it is executed.
- @item --enable-static-link
- This causes Bash to be linked statically, if @code{gcc} is being used.
- This could be used to build a version to use as root's shell.
- @end table
- The @samp{minimal-config} option can be used to disable all of
- the following options, but it is processed first, so individual
- options may be enabled using @samp{enable-@var{feature}}.
- All of the following options except for @samp{disabled-builtins},
- @samp{direxpand-default}, and
- @samp{xpg-echo-default} are
- enabled by default, unless the operating system does not provide the
- necessary support.
- @table @code
- @item --enable-alias
- Allow alias expansion and include the @code{alias} and @code{unalias}
- builtins (@pxref{Aliases}).
- @item --enable-arith-for-command
- Include support for the alternate form of the @code{for} command
- that behaves like the C language @code{for} statement
- (@pxref{Looping Constructs}).
- @item --enable-array-variables
- Include support for one-dimensional array shell variables
- (@pxref{Arrays}).
- @item --enable-bang-history
- Include support for @code{csh}-like history substitution
- (@pxref{History Interaction}).
- @item --enable-brace-expansion
- Include @code{csh}-like brace expansion
- ( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ).
- See @ref{Brace Expansion}, for a complete description.
- @item --enable-casemod-attributes
- Include support for case-modifying attributes in the @code{declare} builtin
- and assignment statements. Variables with the @var{uppercase} attribute,
- for example, will have their values converted to uppercase upon assignment.
- @item --enable-casemod-expansion
- Include support for case-modifying word expansions.
- @item --enable-command-timing
- Include support for recognizing @code{time} as a reserved word and for
- displaying timing statistics for the pipeline following @code{time}
- (@pxref{Pipelines}).
- This allows pipelines as well as shell builtins and functions to be timed.
- @item --enable-cond-command
- Include support for the @code{[[} conditional command.
- (@pxref{Conditional Constructs}).
- @item --enable-cond-regexp
- Include support for matching @sc{posix} regular expressions using the
- @samp{=~} binary operator in the @code{[[} conditional command.
- (@pxref{Conditional Constructs}).
- @item --enable-coprocesses
- Include support for coprocesses and the @code{coproc} reserved word
- (@pxref{Pipelines}).
- @item --enable-debugger
- Include support for the bash debugger (distributed separately).
- @item --enable-dev-fd-stat-broken
- If calling @code{stat} on /dev/fd/@var{N} returns different results than
- calling @code{fstat} on file descriptor @var{N}, supply this option to
- enable a workaround.
- This has implications for conditional commands that test file attributes.
- @item --enable-direxpand-default
- Cause the @code{direxpand} shell option (@pxref{The Shopt Builtin})
- to be enabled by default when the shell starts.
- It is normally disabled by default.
- @item --enable-directory-stack
- Include support for a @code{csh}-like directory stack and the
- @code{pushd}, @code{popd}, and @code{dirs} builtins
- (@pxref{The Directory Stack}).
- @item --enable-disabled-builtins
- Allow builtin commands to be invoked via @samp{builtin xxx}
- even after @code{xxx} has been disabled using @samp{enable -n xxx}.
- See @ref{Bash Builtins}, for details of the @code{builtin} and
- @code{enable} builtin commands.
- @item --enable-dparen-arithmetic
- Include support for the @code{((@dots{}))} command
- (@pxref{Conditional Constructs}).
- @item --enable-extended-glob
- Include support for the extended pattern matching features described
- above under @ref{Pattern Matching}.
- @item --enable-extended-glob-default
- Set the default value of the @var{extglob} shell option described
- above under @ref{The Shopt Builtin} to be enabled.
- @item --enable-function-import
- Include support for importing function definitions exported by another
- instance of the shell from the environment. This option is enabled by
- default.
- @item --enable-glob-asciirange-default
- Set the default value of the @var{globasciiranges} shell option described
- above under @ref{The Shopt Builtin} to be enabled.
- This controls the behavior of character ranges when used in pattern matching
- bracket expressions.
- @item --enable-help-builtin
- Include the @code{help} builtin, which displays help on shell builtins and
- variables (@pxref{Bash Builtins}).
- @item --enable-history
- Include command history and the @code{fc} and @code{history}
- builtin commands (@pxref{Bash History Facilities}).
- @item --enable-job-control
- This enables the job control features (@pxref{Job Control}),
- if the operating system supports them.
- @item --enable-multibyte
- This enables support for multibyte characters if the operating
- system provides the necessary support.
- @item --enable-net-redirections
- This enables the special handling of filenames of the form
- @code{/dev/tcp/@var{host}/@var{port}} and
- @code{/dev/udp/@var{host}/@var{port}}
- when used in redirections (@pxref{Redirections}).
- @item --enable-process-substitution
- This enables process substitution (@pxref{Process Substitution}) if
- the operating system provides the necessary support.
- @item --enable-progcomp
- Enable the programmable completion facilities
- (@pxref{Programmable Completion}).
- If Readline is not enabled, this option has no effect.
- @item --enable-prompt-string-decoding
- Turn on the interpretation of a number of backslash-escaped characters
- in the @env{$PS0}, @env{$PS1}, @env{$PS2}, and @env{$PS4} prompt
- strings. See @ref{Controlling the Prompt}, for a complete list of prompt
- string escape sequences.
- @item --enable-readline
- Include support for command-line editing and history with the Bash
- version of the Readline library (@pxref{Command Line Editing}).
- @item --enable-restricted
- Include support for a @dfn{restricted shell}. If this is enabled, Bash,
- when called as @code{rbash}, enters a restricted mode. See
- @ref{The Restricted Shell}, for a description of restricted mode.
- @item --enable-select
- Include the @code{select} compound command, which allows the generation of
- simple menus (@pxref{Conditional Constructs}).
- @item --enable-separate-helpfiles
- Use external files for the documentation displayed by the @code{help} builtin
- instead of storing the text internally.
- @item --enable-single-help-strings
- Store the text displayed by the @code{help} builtin as a single string for
- each help topic. This aids in translating the text to different languages.
- You may need to disable this if your compiler cannot handle very long string
- literals.
- @item --enable-strict-posix-default
- Make Bash @sc{posix}-conformant by default (@pxref{Bash POSIX Mode}).
- @item --enable-usg-echo-default
- A synonym for @code{--enable-xpg-echo-default}.
- @item --enable-xpg-echo-default
- Make the @code{echo} builtin expand backslash-escaped characters by default,
- without requiring the @option{-e} option.
- This sets the default value of the @code{xpg_echo} shell option to @code{on},
- which makes the Bash @code{echo} behave more like the version specified in
- the Single Unix Specification, version 3.
- @xref{Bash Builtins}, for a description of the escape sequences that
- @code{echo} recognizes.
- @end table
- The file @file{config-top.h} contains C Preprocessor
- @samp{#define} statements for options which are not settable from
- @code{configure}.
- Some of these are not meant to be changed; beware of the consequences if
- you do.
- Read the comments associated with each definition for more
- information about its effect.
- @node Reporting Bugs
- @appendix Reporting Bugs
- Please report all bugs you find in Bash.
- But first, you should
- make sure that it really is a bug, and that it appears in the latest
- version of Bash.
- The latest version of Bash is always available for FTP from
- @uref{ftp://ftp.gnu.org/pub/gnu/bash/}.
- Once you have determined that a bug actually exists, use the
- @code{bashbug} 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 @email{bug-bash@@gnu.org} or posted to the Usenet
- newsgroup @code{gnu.bash.bug}.
- All bug reports should include:
- @itemize @bullet
- @item
- The version number of Bash.
- @item
- The hardware and operating system.
- @item
- The compiler used to compile Bash.
- @item
- A description of the bug behaviour.
- @item
- A short script or `recipe' which exercises the bug and may be used
- to reproduce it.
- @end itemize
- @noindent
- @code{bashbug} inserts the first three items automatically into
- the template it provides for filing a bug report.
- Please send all reports concerning this manual to
- @email{bug-bash@@gnu.org}.
- @node Major Differences From The Bourne Shell
- @appendix Major Differences From The Bourne Shell
- Bash implements essentially the same grammar, parameter and
- variable expansion, redirection, and quoting as the Bourne Shell.
- Bash uses the @sc{posix} standard as the specification of
- how these features are to be implemented. There are some
- differences between the traditional Bourne shell and Bash; this
- section quickly details the differences of significance. A
- number of these differences are explained in greater depth in
- previous sections.
- This section uses the version of @code{sh} included in SVR4.2 (the
- last version of the historical Bourne shell) as the baseline reference.
- @itemize @bullet
- @item
- Bash is @sc{posix}-conformant, even where the @sc{posix} specification
- differs from traditional @code{sh} behavior (@pxref{Bash POSIX Mode}).
- @item
- Bash has multi-character invocation options (@pxref{Invoking Bash}).
- @item
- Bash has command-line editing (@pxref{Command Line Editing}) and
- the @code{bind} builtin.
- @item
- Bash provides a programmable word completion mechanism
- (@pxref{Programmable Completion}), and builtin commands
- @code{complete}, @code{compgen}, and @code{compopt}, to
- manipulate it.
- @item
- Bash has command history (@pxref{Bash History Facilities}) and the
- @code{history} and @code{fc} builtins to manipulate it.
- The Bash history list maintains timestamp information and uses the
- value of the @code{HISTTIMEFORMAT} variable to display it.
- @item
- Bash implements @code{csh}-like history expansion
- (@pxref{History Interaction}).
- @item
- Bash has one-dimensional array variables (@pxref{Arrays}), and the
- appropriate variable expansions and assignment syntax to use them.
- Several of the Bash builtins take options to act on arrays.
- Bash provides a number of built-in array variables.
- @item
- The @code{$'@dots{}'} quoting syntax, which expands ANSI-C
- backslash-escaped characters in the text between the single quotes,
- is supported (@pxref{ANSI-C Quoting}).
- @item
- Bash supports the @code{$"@dots{}"} quoting syntax to do
- locale-specific translation of the characters between the double
- quotes. The @option{-D}, @option{--dump-strings}, and @option{--dump-po-strings}
- invocation options list the translatable strings found in a script
- (@pxref{Locale Translation}).
- @item
- Bash implements the @code{!} keyword to negate the return value of
- a pipeline (@pxref{Pipelines}).
- Very useful when an @code{if} statement needs to act only if a test fails.
- The Bash @samp{-o pipefail} option to @code{set} will cause a pipeline to
- return a failure status if any command fails.
- @item
- Bash has the @code{time} reserved word and command timing (@pxref{Pipelines}).
- The display of the timing statistics may be controlled with the
- @env{TIMEFORMAT} variable.
- @item
- Bash implements the @code{for (( @var{expr1} ; @var{expr2} ; @var{expr3} ))}
- arithmetic for command, similar to the C language (@pxref{Looping Constructs}).
- @item
- Bash includes the @code{select} compound command, which allows the
- generation of simple menus (@pxref{Conditional Constructs}).
- @item
- Bash includes the @code{[[} compound command, which makes conditional
- testing part of the shell grammar (@pxref{Conditional Constructs}), including
- optional regular expression matching.
- @item
- Bash provides optional case-insensitive matching for the @code{case} and
- @code{[[} constructs.
- @item
- Bash includes brace expansion (@pxref{Brace Expansion}) and tilde
- expansion (@pxref{Tilde Expansion}).
- @item
- Bash implements command aliases and the @code{alias} and @code{unalias}
- builtins (@pxref{Aliases}).
- @item
- Bash provides shell arithmetic, the @code{((} compound command
- (@pxref{Conditional Constructs}),
- and arithmetic expansion (@pxref{Shell Arithmetic}).
- @item
- Variables present in the shell's initial environment are automatically
- exported to child processes. The Bourne shell does not normally do
- this unless the variables are explicitly marked using the @code{export}
- command.
- @item
- Bash supports the @samp{+=} assignment operator, which appends to the value
- of the variable named on the left hand side.
- @item
- Bash includes the @sc{posix} pattern removal @samp{%}, @samp{#}, @samp{%%}
- and @samp{##} expansions to remove leading or trailing substrings from
- variable values (@pxref{Shell Parameter Expansion}).
- @item
- The expansion @code{$@{#xx@}}, which returns the length of @code{$@{xx@}},
- is supported (@pxref{Shell Parameter Expansion}).
- @item
- The expansion @code{$@{var:}@var{offset}@code{[:}@var{length}@code{]@}},
- which expands to the substring of @code{var}'s value of length
- @var{length}, beginning at @var{offset}, is present
- (@pxref{Shell Parameter Expansion}).
- @item
- The expansion
- @code{$@{var/[/]}@var{pattern}@code{[/}@var{replacement}@code{]@}},
- which matches @var{pattern} and replaces it with @var{replacement} in
- the value of @code{var}, is available (@pxref{Shell Parameter Expansion}).
- @item
- The expansion @code{$@{!@var{prefix}*@}} expansion, which expands to
- the names of all shell variables whose names begin with @var{prefix},
- is available (@pxref{Shell Parameter Expansion}).
- @item
- Bash has @var{indirect} variable expansion using @code{$@{!word@}}
- (@pxref{Shell Parameter Expansion}).
- @item
- Bash can expand positional parameters beyond @code{$9} using
- @code{$@{@var{num}@}}.
- @item
- The @sc{posix} @code{$()} form of command substitution
- is implemented (@pxref{Command Substitution}),
- and preferred to the Bourne shell's @code{``} (which
- is also implemented for backwards compatibility).
- @item
- Bash has process substitution (@pxref{Process Substitution}).
- @item
- Bash automatically assigns variables that provide information about the
- current user (@env{UID}, @env{EUID}, and @env{GROUPS}), the current host
- (@env{HOSTTYPE}, @env{OSTYPE}, @env{MACHTYPE}, and @env{HOSTNAME}),
- and the instance of Bash that is running (@env{BASH},
- @env{BASH_VERSION}, and @env{BASH_VERSINFO}). @xref{Bash Variables},
- for details.
- @item
- The @env{IFS} variable is used to split only the results of expansion,
- not all words (@pxref{Word Splitting}).
- This closes a longstanding shell security hole.
- @item
- The filename expansion bracket expression code uses @samp{!} and @samp{^}
- to negate the set of characters between the brackets.
- The Bourne shell uses only @samp{!}.
- @item
- Bash implements the full set of @sc{posix} filename expansion operators,
- including @var{character classes}, @var{equivalence classes}, and
- @var{collating symbols} (@pxref{Filename Expansion}).
- @item
- Bash implements extended pattern matching features when the @code{extglob}
- shell option is enabled (@pxref{Pattern Matching}).
- @item
- It is possible to have a variable and a function with the same name;
- @code{sh} does not separate the two name spaces.
- @item
- Bash functions are permitted to have local variables using the
- @code{local} builtin, and thus useful recursive functions may be written
- (@pxref{Bash Builtins}).
- @item
- Variable assignments preceding commands affect only that command, even
- builtins and functions (@pxref{Environment}).
- In @code{sh}, all variable assignments
- preceding commands are global unless the command is executed from the
- file system.
- @item
- Bash performs filename expansion on filenames specified as operands
- to input and output redirection operators (@pxref{Redirections}).
- @item
- Bash contains the @samp{<>} redirection operator, allowing a file to be
- opened for both reading and writing, and the @samp{&>} redirection
- operator, for directing standard output and standard error to the same
- file (@pxref{Redirections}).
- @item
- Bash includes the @samp{<<<} redirection operator, allowing a string to
- be used as the standard input to a command.
- @item
- Bash implements the @samp{[n]<&@var{word}} and @samp{[n]>&@var{word}}
- redirection operators, which move one file descriptor to another.
- @item
- Bash treats a number of filenames specially when they are
- used in redirection operators (@pxref{Redirections}).
- @item
- Bash can open network connections to arbitrary machines and services
- with the redirection operators (@pxref{Redirections}).
- @item
- The @code{noclobber} option is available to avoid overwriting existing
- files with output redirection (@pxref{The Set Builtin}).
- The @samp{>|} redirection operator may be used to override @code{noclobber}.
- @item
- The Bash @code{cd} and @code{pwd} builtins (@pxref{Bourne Shell Builtins})
- each take @option{-L} and @option{-P} options to switch between logical and
- physical modes.
- @item
- Bash allows a function to override a builtin with the same name, and provides
- access to that builtin's functionality within the function via the
- @code{builtin} and @code{command} builtins (@pxref{Bash Builtins}).
- @item
- The @code{command} builtin allows selective disabling of functions
- when command lookup is performed (@pxref{Bash Builtins}).
- @item
- Individual builtins may be enabled or disabled using the @code{enable}
- builtin (@pxref{Bash Builtins}).
- @item
- The Bash @code{exec} builtin takes additional options that allow users
- to control the contents of the environment passed to the executed
- command, and what the zeroth argument to the command is to be
- (@pxref{Bourne Shell Builtins}).
- @item
- Shell functions may be exported to children via the environment
- using @code{export -f} (@pxref{Shell Functions}).
- @item
- The Bash @code{export}, @code{readonly}, and @code{declare} builtins can
- take a @option{-f} option to act on shell functions, a @option{-p} option to
- display variables with various attributes set in a format that can be
- used as shell input, a @option{-n} option to remove various variable
- attributes, and @samp{name=value} arguments to set variable attributes
- and values simultaneously.
- @item
- The Bash @code{hash} builtin allows a name to be associated with
- an arbitrary filename, even when that filename cannot be found by
- searching the @env{$PATH}, using @samp{hash -p}
- (@pxref{Bourne Shell Builtins}).
- @item
- Bash includes a @code{help} builtin for quick reference to shell
- facilities (@pxref{Bash Builtins}).
- @item
- The @code{printf} builtin is available to display formatted output
- (@pxref{Bash Builtins}).
- @item
- The Bash @code{read} builtin (@pxref{Bash Builtins})
- will read a line ending in @samp{\} with
- the @option{-r} option, and will use the @env{REPLY} variable as a
- default if no non-option arguments are supplied.
- The Bash @code{read} builtin
- also accepts a prompt string with the @option{-p} option and will use
- Readline to obtain the line when given the @option{-e} option.
- The @code{read} builtin also has additional options to control input:
- the @option{-s} option will turn off echoing of input characters as
- they are read, the @option{-t} option will allow @code{read} to time out
- if input does not arrive within a specified number of seconds, the
- @option{-n} option will allow reading only a specified number of
- characters rather than a full line, and the @option{-d} option will read
- until a particular character rather than newline.
- @item
- The @code{return} builtin may be used to abort execution of scripts
- executed with the @code{.} or @code{source} builtins
- (@pxref{Bourne Shell Builtins}).
- @item
- Bash includes the @code{shopt} builtin, for finer control of shell
- optional capabilities (@pxref{The Shopt Builtin}), and allows these options
- to be set and unset at shell invocation (@pxref{Invoking Bash}).
- @item
- Bash has much more optional behavior controllable with the @code{set}
- builtin (@pxref{The Set Builtin}).
- @item
- The @samp{-x} (@option{xtrace}) option displays commands other than
- simple commands when performing an execution trace
- (@pxref{The Set Builtin}).
- @item
- The @code{test} builtin (@pxref{Bourne Shell Builtins})
- is slightly different, as it implements the @sc{posix} algorithm,
- which specifies the behavior based on the number of arguments.
- @item
- Bash includes the @code{caller} builtin, which displays the context of
- any active subroutine call (a shell function or a script executed with
- the @code{.} or @code{source} builtins). This supports the bash
- debugger.
- @item
- The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a
- @code{DEBUG} pseudo-signal specification, similar to @code{EXIT}.
- Commands specified with a @code{DEBUG} trap are executed before every
- simple command, @code{for} command, @code{case} command,
- @code{select} command, every arithmetic @code{for} command, and before
- the first command executes in a shell function.
- The @code{DEBUG} trap is not inherited by shell functions unless the
- function has been given the @code{trace} attribute or the
- @code{functrace} option has been enabled using the @code{shopt} builtin.
- The @code{extdebug} shell option has additional effects on the
- @code{DEBUG} trap.
- The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows an
- @code{ERR} pseudo-signal specification, similar to @code{EXIT} and @code{DEBUG}.
- Commands specified with an @code{ERR} trap are executed after a simple
- command fails, with a few exceptions.
- The @code{ERR} trap is not inherited by shell functions unless the
- @code{-o errtrace} option to the @code{set} builtin is enabled.
- The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a
- @code{RETURN} pseudo-signal specification, similar to
- @code{EXIT} and @code{DEBUG}.
- Commands specified with an @code{RETURN} trap are executed before
- execution resumes after a shell function or a shell script executed with
- @code{.} or @code{source} returns.
- The @code{RETURN} trap is not inherited by shell functions unless the
- function has been given the @code{trace} attribute or the
- @code{functrace} option has been enabled using the @code{shopt} builtin.
- @item
- The Bash @code{type} builtin is more extensive and gives more information
- about the names it finds (@pxref{Bash Builtins}).
- @item
- The Bash @code{umask} builtin permits a @option{-p} option to cause
- the output to be displayed in the form of a @code{umask} command
- that may be reused as input (@pxref{Bourne Shell Builtins}).
- @item
- Bash implements a @code{csh}-like directory stack, and provides the
- @code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it
- (@pxref{The Directory Stack}).
- Bash also makes the directory stack visible as the value of the
- @env{DIRSTACK} shell variable.
- @item
- Bash interprets special backslash-escaped characters in the prompt
- strings when interactive (@pxref{Controlling the Prompt}).
- @item
- The Bash restricted mode is more useful (@pxref{The Restricted Shell});
- the SVR4.2 shell restricted mode is too limited.
- @item
- The @code{disown} builtin can remove a job from the internal shell
- job table (@pxref{Job Control Builtins}) or suppress the sending
- of @code{SIGHUP} to a job when the shell exits as the result of a
- @code{SIGHUP}.
- @item
- Bash includes a number of features to support a separate debugger for
- shell scripts.
- @item
- The SVR4.2 shell has two privilege-related builtins
- (@code{mldmode} and @code{priv}) not present in Bash.
- @item
- Bash does not have the @code{stop} or @code{newgrp} builtins.
- @item
- Bash does not use the @env{SHACCT} variable or perform shell accounting.
- @item
- The SVR4.2 @code{sh} uses a @env{TIMEOUT} variable like Bash uses
- @env{TMOUT}.
- @end itemize
- @noindent
- More features unique to Bash may be found in @ref{Bash Features}.
- @appendixsec Implementation Differences From The SVR4.2 Shell
- Since Bash is a completely new implementation, it does not suffer from
- many of the limitations of the SVR4.2 shell. For instance:
- @itemize @bullet
- @item
- Bash does not fork a subshell when redirecting into or out of
- a shell control structure such as an @code{if} or @code{while}
- statement.
- @item
- Bash does not allow unbalanced quotes. The SVR4.2 shell will silently
- insert a needed closing quote at @code{EOF} under certain circumstances.
- This can be the cause of some hard-to-find errors.
- @item
- The SVR4.2 shell uses a baroque memory management scheme based on
- trapping @code{SIGSEGV}. If the shell is started from a process with
- @code{SIGSEGV} blocked (e.g., by using the @code{system()} C library
- function call), it misbehaves badly.
- @item
- In a questionable attempt at security, the SVR4.2 shell,
- when invoked without the @option{-p} option, will alter its real
- and effective @sc{uid} and @sc{gid} if they are less than some
- magic threshold value, commonly 100.
- This can lead to unexpected results.
- @item
- The SVR4.2 shell does not allow users to trap @code{SIGSEGV},
- @code{SIGALRM}, or @code{SIGCHLD}.
- @item
- The SVR4.2 shell does not allow the @env{IFS}, @env{MAILCHECK},
- @env{PATH}, @env{PS1}, or @env{PS2} variables to be unset.
- @item
- The SVR4.2 shell treats @samp{^} as the undocumented equivalent of
- @samp{|}.
- @item
- Bash allows multiple option arguments when it is invoked (@code{-x -v});
- the SVR4.2 shell allows only one option argument (@code{-xv}). In
- fact, some versions of the shell dump core if the second argument begins
- with a @samp{-}.
- @item
- The SVR4.2 shell exits a script if any builtin fails; Bash exits
- a script only if one of the @sc{posix} special builtins fails, and
- only for certain failures, as enumerated in the @sc{posix} standard.
- @item
- The SVR4.2 shell behaves differently when invoked as @code{jsh}
- (it turns on job control).
- @end itemize
- @node GNU Free Documentation License
- @appendix GNU Free Documentation License
- @include fdl.texi
- @node Indexes
- @appendix Indexes
- @menu
- * Builtin Index:: Index of Bash builtin commands.
- * Reserved Word Index:: Index of Bash reserved words.
- * Variable Index:: Quick reference helps you find the
- variable you want.
- * Function Index:: Index of bindable Readline functions.
- * Concept Index:: General index for concepts described in
- this manual.
- @end menu
- @node Builtin Index
- @appendixsec Index of Shell Builtin Commands
- @printindex bt
- @node Reserved Word Index
- @appendixsec Index of Shell Reserved Words
- @printindex rw
- @node Variable Index
- @appendixsec Parameter and Variable Index
- @printindex vr
- @node Function Index
- @appendixsec Function Index
- @printindex fn
- @node Concept Index
- @appendixsec Concept Index
- @printindex cp
- @bye
|