1\input texinfo.tex @c -*- texinfo -*- 2@c %**start of header 3@setfilename bashref.info 4@settitle Bash Reference Manual 5@c %**end of header 6 7@setchapternewpage odd 8 9@include version.texi 10 11@copying 12This text is a brief description of the features that are present in 13the Bash shell (version @value{VERSION}, @value{UPDATED}). 14 15This is Edition @value{EDITION}, last updated @value{UPDATED}, 16of @cite{The GNU Bash Reference Manual}, 17for @code{Bash}, Version @value{VERSION}. 18 19Copyright @copyright{} 1988-2005 Free Software Foundation, Inc. 20 21Permission is granted to make and distribute verbatim copies of 22this manual provided the copyright notice and this permission notice 23are preserved on all copies. 24 25@quotation 26Permission is granted to copy, distribute and/or modify this document 27under the terms of the GNU Free Documentation License, Version 1.2 or 28any later version published by the Free Software Foundation; with no 29Invariant Sections, with the Front-Cover texts being ``A GNU Manual,'' 30and with the Back-Cover Texts as in (a) below. A copy of the license is 31included in the section entitled ``GNU Free Documentation License.'' 32 33(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify 34this GNU Manual, like GNU software. Copies published by the Free 35Software Foundation raise funds for GNU development.'' 36@end quotation 37@end copying 38 39@defcodeindex bt 40@defcodeindex rw 41@set BashFeatures 42 43@dircategory Basics 44@direntry 45* Bash: (bash). The GNU Bourne-Again SHell. 46@end direntry 47 48@finalout 49 50@titlepage 51@title Bash Reference Manual 52@subtitle Reference Documentation for Bash 53@subtitle Edition @value{EDITION}, for @code{Bash} Version @value{VERSION}. 54@subtitle @value{UPDATED-MONTH} 55@author Chet Ramey, Case Western Reserve University 56@author Brian Fox, Free Software Foundation 57 58@page 59@vskip 0pt plus 1filll 60@insertcopying 61 62@sp 1 63Published by the Free Software Foundation @* 6459 Temple Place, Suite 330, @* 65Boston, MA 02111-1307 @* 66USA @* 67 68@end titlepage 69 70@contents 71 72@ifnottex 73@node Top, Introduction, (dir), (dir) 74@top Bash Features 75 76This text is a brief description of the features that are present in 77the Bash shell (version @value{VERSION}, @value{UPDATED}). 78 79This is Edition @value{EDITION}, last updated @value{UPDATED}, 80of @cite{The GNU Bash Reference Manual}, 81for @code{Bash}, Version @value{VERSION}. 82 83Bash contains features that appear in other popular shells, and some 84features that only appear in Bash. Some of the shells that Bash has 85borrowed concepts from are the Bourne Shell (@file{sh}), the Korn Shell 86(@file{ksh}), and the C-shell (@file{csh} and its successor, 87@file{tcsh}). The following menu breaks the features up into 88categories based upon which one of these other shells inspired the 89feature. 90 91This manual is meant as a brief introduction to features found in 92Bash. The Bash manual page should be used as the definitive 93reference on shell behavior. 94 95@menu 96* Introduction:: An introduction to the shell. 97* Definitions:: Some definitions used in the rest of this 98 manual. 99* Basic Shell Features:: The shell "building blocks". 100* Shell Builtin Commands:: Commands that are a part of the shell. 101* Shell Variables:: Variables used or set by Bash. 102* Bash Features:: Features found only in Bash. 103* Job Control:: What job control is and how Bash allows you 104 to use it. 105* Using History Interactively:: Command History Expansion 106* Command Line Editing:: Chapter describing the command line 107 editing features. 108* Installing Bash:: How to build and install Bash on your system. 109* Reporting Bugs:: How to report bugs in Bash. 110* Major Differences From The Bourne Shell:: A terse list of the differences 111 between Bash and historical 112 versions of /bin/sh. 113* Copying This Manual:: Copying this manual. 114* Builtin Index:: Index of Bash builtin commands. 115* Reserved Word Index:: Index of Bash reserved words. 116* Variable Index:: Quick reference helps you find the 117 variable you want. 118* Function Index:: Index of bindable Readline functions. 119* Concept Index:: General index for concepts described in 120 this manual. 121@end menu 122@end ifnottex 123 124@node Introduction 125@chapter Introduction 126@menu 127* What is Bash?:: A short description of Bash. 128* What is a shell?:: A brief introduction to shells. 129@end menu 130 131@node What is Bash? 132@section What is Bash? 133 134Bash is the shell, or command language interpreter, 135for the @sc{gnu} operating system. 136The name is an acronym for the @samp{Bourne-Again SHell}, 137a pun on Stephen Bourne, the author of the direct ancestor of 138the current Unix shell @code{sh}, 139which appeared in the Seventh Edition Bell Labs Research version 140of Unix. 141 142Bash is largely compatible with @code{sh} and incorporates useful 143features from the Korn shell @code{ksh} and the C shell @code{csh}. 144It is intended to be a conformant implementation of the @sc{ieee} 145@sc{posix} Shell and Tools portion of the @sc{ieee} @sc{posix} 146specification (@sc{ieee} Standard 1003.1). 147It offers functional improvements over @code{sh} for both interactive and 148programming use. 149 150While the @sc{gnu} operating system provides other shells, including 151a version of @code{csh}, Bash is the default shell. 152Like other @sc{gnu} software, Bash is quite portable. It currently runs 153on nearly every version of Unix and a few other operating systems @minus{} 154independently-supported ports exist for @sc{ms-dos}, @sc{os/2}, 155and Windows platforms. 156 157@node What is a shell? 158@section What is a shell? 159 160At its base, a shell is simply a macro processor that executes 161commands. The term macro processor means functionality where text 162and symbols are expanded to create larger expressions. 163 164A Unix shell is both a command interpreter and a programming 165language. As a command interpreter, the shell provides the user 166interface to the rich set of @sc{gnu} utilities. The programming 167language features allow these utilitites to be combined. 168Files containing commands can be created, and become 169commands themselves. These new commands have the same status as 170system commands in directories such as @file{/bin}, allowing users 171or groups to establish custom environments to automate their common 172tasks. 173 174Shells may be used interactively or non-interactively. In 175interactive mode, they accept input typed from the keyboard. 176When executing non-interactively, shells execute commands read 177from a file. 178 179A shell allows execution of @sc{gnu} commands, both synchronously and 180asynchronously. 181The shell waits for synchronous commands to complete before accepting 182more input; asynchronous commands continue to execute in parallel 183with the shell while it reads and executes additional commands. 184The @dfn{redirection} constructs permit 185fine-grained control of the input and output of those commands. 186Moreover, the shell allows control over the contents of commands' 187environments. 188 189Shells also provide a small set of built-in 190commands (@dfn{builtins}) implementing functionality impossible 191or inconvenient to obtain via separate utilities. 192For example, @code{cd}, @code{break}, @code{continue}, and 193@code{exec}) cannot be implemented outside of the shell because 194they directly manipulate the shell itself. 195The @code{history}, @code{getopts}, @code{kill}, or @code{pwd} 196builtins, among others, could be implemented in separate utilities, 197but they are more convenient to use as builtin commands. 198All of the shell builtins are described in 199subsequent sections. 200 201While executing commands is essential, most of the power (and 202complexity) of shells is due to their embedded programming 203languages. Like any high-level language, the shell provides 204variables, flow control constructs, quoting, and functions. 205 206Shells offer features geared specifically for 207interactive use rather than to augment the programming language. 208These interactive features include job control, command line 209editing, command history and aliases. Each of these features is 210described in this manual. 211 212@node Definitions 213@chapter Definitions 214These definitions are used throughout the remainder of this manual. 215 216@table @code 217 218@item POSIX 219@cindex POSIX 220A family of open system standards based on Unix. Bash 221is primarily concerned with the Shell and Utilities portion of the 222@sc{posix} 1003.1 standard. 223 224@item blank 225A space or tab character. 226 227@item builtin 228@cindex builtin 229A command that is implemented internally by the shell itself, rather 230than by an executable program somewhere in the file system. 231 232@item control operator 233@cindex control operator 234A @code{word} that performs a control function. It is a @code{newline} 235or one of the following: 236@samp{||}, @samp{&&}, @samp{&}, @samp{;}, @samp{;;}, 237@samp{|}, @samp{(}, or @samp{)}. 238 239@item exit status 240@cindex exit status 241The value returned by a command to its caller. The value is restricted 242to eight bits, so the maximum value is 255. 243 244@item field 245@cindex field 246A unit of text that is the result of one of the shell expansions. After 247expansion, when executing a command, the resulting fields are used as 248the command name and arguments. 249 250@item filename 251@cindex filename 252A string of characters used to identify a file. 253 254@item job 255@cindex job 256A set of processes comprising a pipeline, and any processes descended 257from it, that are all in the same process group. 258 259@item job control 260@cindex job control 261A mechanism by which users can selectively stop (suspend) and restart 262(resume) execution of processes. 263 264@item metacharacter 265@cindex metacharacter 266A character that, when unquoted, separates words. A metacharacter is 267a @code{blank} or one of the following characters: 268@samp{|}, @samp{&}, @samp{;}, @samp{(}, @samp{)}, @samp{<}, or 269@samp{>}. 270 271@item name 272@cindex name 273@cindex identifier 274A @code{word} consisting solely of letters, numbers, and underscores, 275and beginning with a letter or underscore. @code{Name}s are used as 276shell variable and function names. 277Also referred to as an @code{identifier}. 278 279@item operator 280@cindex operator, shell 281A @code{control operator} or a @code{redirection operator}. 282@xref{Redirections}, for a list of redirection operators. 283 284@item process group 285@cindex process group 286A collection of related processes each having the same process 287group @sc{id}. 288 289@item process group ID 290@cindex process group ID 291A unique identifer that represents a @code{process group} 292during its lifetime. 293 294@item reserved word 295@cindex reserved word 296A @code{word} that has a special meaning to the shell. Most reserved 297words introduce shell flow control constructs, such as @code{for} and 298@code{while}. 299 300@item return status 301@cindex return status 302A synonym for @code{exit status}. 303 304@item signal 305@cindex signal 306A mechanism by which a process may be notified by the kernel 307of an event occurring in the system. 308 309@item special builtin 310@cindex special builtin 311A shell builtin command that has been classified as special by the 312@sc{posix} standard. 313 314@item token 315@cindex token 316A sequence of characters considered a single unit by the shell. It is 317either a @code{word} or an @code{operator}. 318 319@item word 320@cindex word 321A @code{token} that is not an @code{operator}. 322@end table 323 324@node Basic Shell Features 325@chapter Basic Shell Features 326@cindex Bourne shell 327 328Bash is an acronym for @samp{Bourne-Again SHell}. 329The Bourne shell is 330the traditional Unix shell originally written by Stephen Bourne. 331All of the Bourne shell builtin commands are available in Bash, 332The rules for evaluation and quoting are taken from the @sc{posix} 333specification for the `standard' Unix shell. 334 335This chapter briefly summarizes the shell's `building blocks': 336commands, control structures, shell functions, shell @i{parameters}, 337shell expansions, 338@i{redirections}, which are a way to direct input and output from 339and to named files, and how the shell executes commands. 340 341@menu 342* Shell Syntax:: What your input means to the shell. 343* Shell Commands:: The types of commands you can use. 344* Shell Functions:: Grouping commands by name. 345* Shell Parameters:: How the shell stores values. 346* Shell Expansions:: How Bash expands parameters and the various 347 expansions available. 348* Redirections:: A way to control where input and output go. 349* Executing Commands:: What happens when you run a command. 350* Shell Scripts:: Executing files of shell commands. 351@end menu 352 353@node Shell Syntax 354@section Shell Syntax 355@menu 356* Shell Operation:: The basic operation of the shell. 357* Quoting:: How to remove the special meaning from characters. 358* Comments:: How to specify comments. 359@end menu 360 361When the shell reads input, it proceeds through a 362sequence of operations. If the input indicates the beginning of a 363comment, the shell ignores the comment symbol (@samp{#}), and the rest 364of that line. 365 366Otherwise, roughly speaking, the shell reads its input and 367divides the input into words and operators, employing the quoting rules 368to select which meanings to assign various words and characters. 369 370The shell then parses these tokens into commands and other constructs, 371removes the special meaning of certain words or characters, expands 372others, redirects input and output as needed, executes the specified 373command, waits for the command's exit status, and makes that exit status 374available for further inspection or processing. 375 376@node Shell Operation 377@subsection Shell Operation 378 379The following is a brief description of the shell's operation when it 380reads and executes a command. Basically, the shell does the 381following: 382 383@enumerate 384@item 385Reads its input from a file (@pxref{Shell Scripts}), from a string 386supplied as an argument to the @option{-c} invocation option 387(@pxref{Invoking Bash}), or from the user's terminal. 388 389@item 390Breaks the input into words and operators, obeying the quoting rules 391described in @ref{Quoting}. These tokens are separated by 392@code{metacharacters}. Alias expansion is performed by this step 393(@pxref{Aliases}). 394 395@item 396Parses the tokens into simple and compound commands 397(@pxref{Shell Commands}). 398 399@item 400Performs the various shell expansions (@pxref{Shell Expansions}), breaking 401the expanded tokens into lists of filenames (@pxref{Filename Expansion}) 402and commands and arguments. 403 404@item 405Performs any necessary redirections (@pxref{Redirections}) and removes 406the redirection operators and their operands from the argument list. 407 408@item 409Executes the command (@pxref{Executing Commands}). 410 411@item 412Optionally waits for the command to complete and collects its exit 413status (@pxref{Exit Status}). 414 415@end enumerate 416 417@node Quoting 418@subsection Quoting 419@cindex quoting 420@menu 421* Escape Character:: How to remove the special meaning from a single 422 character. 423* Single Quotes:: How to inhibit all interpretation of a sequence 424 of characters. 425* Double Quotes:: How to suppress most of the interpretation of a 426 sequence of characters. 427* ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings. 428* Locale Translation:: How to translate strings into different languages. 429@end menu 430 431Quoting is used to remove the special meaning of certain 432characters or words to the shell. Quoting can be used to 433disable special treatment for special characters, to prevent 434reserved words from being recognized as such, and to prevent 435parameter expansion. 436 437Each of the shell metacharacters (@pxref{Definitions}) 438has special meaning to the shell and must be quoted if it is to 439represent itself. 440When the command history expansion facilities are being used 441(@pxref{History Interaction}), the 442@var{history expansion} character, usually @samp{!}, must be quoted 443to prevent history expansion. @xref{Bash History Facilities}, for 444more details concerning history expansion. 445 446There are three quoting mechanisms: the 447@var{escape character}, single quotes, and double quotes. 448 449@node Escape Character 450@subsubsection Escape Character 451A non-quoted backslash @samp{\} is the Bash escape character. 452It preserves the literal value of the next character that follows, 453with the exception of @code{newline}. If a @code{\newline} pair 454appears, and the backslash itself is not quoted, the @code{\newline} 455is treated as a line continuation (that is, it is removed from 456the input stream and effectively ignored). 457 458@node Single Quotes 459@subsubsection Single Quotes 460 461Enclosing characters in single quotes (@samp{'}) preserves the literal value 462of each character within the quotes. A single quote may not occur 463between single quotes, even when preceded by a backslash. 464 465@node Double Quotes 466@subsubsection Double Quotes 467 468Enclosing characters in double quotes (@samp{"}) preserves the literal value 469of all characters within the quotes, with the exception of 470@samp{$}, @samp{`}, @samp{\}, 471and, when history expansion is enabled, @samp{!}. 472The characters @samp{$} and @samp{`} 473retain their special meaning within double quotes (@pxref{Shell Expansions}). 474The backslash retains its special meaning only when followed by one of 475the following characters: 476@samp{$}, @samp{`}, @samp{"}, @samp{\}, or @code{newline}. 477Within double quotes, backslashes that are followed by one of these 478characters are removed. Backslashes preceding characters without a 479special meaning are left unmodified. 480A double quote may be quoted within double quotes by preceding it with 481a backslash. 482If enabled, history expansion will be performed unless an @samp{!} 483appearing in double quotes is escaped using a backslash. 484The backslash preceding the @samp{!} is not removed. 485 486The special parameters @samp{*} and @samp{@@} have special meaning 487when in double quotes (@pxref{Shell Parameter Expansion}). 488 489@node ANSI-C Quoting 490@subsubsection ANSI-C Quoting 491@cindex quoting, ANSI 492 493Words of the form @code{$'@var{string}'} are treated specially. The 494word expands to @var{string}, with backslash-escaped characters replaced 495as specified by the ANSI C standard. Backslash escape sequences, if 496present, are decoded as follows: 497 498@table @code 499@item \a 500alert (bell) 501@item \b 502backspace 503@item \e 504an escape character (not ANSI C) 505@item \f 506form feed 507@item \n 508newline 509@item \r 510carriage return 511@item \t 512horizontal tab 513@item \v 514vertical tab 515@item \\ 516backslash 517@item \' 518single quote 519@item \@var{nnn} 520the eight-bit character whose value is the octal value @var{nnn} 521(one to three digits) 522@item \x@var{HH} 523the eight-bit character whose value is the hexadecimal value @var{HH} 524(one or two hex digits) 525@item \c@var{x} 526a control-@var{x} character 527@end table 528 529@noindent 530The expanded result is single-quoted, as if the dollar sign had not 531been present. 532 533@node Locale Translation 534@subsubsection Locale-Specific Translation 535@cindex localization 536@cindex internationalization 537@cindex native languages 538@cindex translation, native languages 539 540A double-quoted string preceded by a dollar sign (@samp{$}) will cause 541the string to be translated according to the current locale. 542If the current locale is @code{C} or @code{POSIX}, the dollar sign 543is ignored. 544If the string is translated and replaced, the replacement is 545double-quoted. 546 547@vindex LC_MESSAGES 548@vindex TEXTDOMAIN 549@vindex TEXTDOMAINDIR 550Some systems use the message catalog selected by the @env{LC_MESSAGES} 551shell variable. Others create the name of the message catalog from the 552value of the @env{TEXTDOMAIN} shell variable, possibly adding a 553suffix of @samp{.mo}. If you use the @env{TEXTDOMAIN} variable, you 554may need to set the @env{TEXTDOMAINDIR} variable to the location of 555the message catalog files. Still others use both variables in this 556fashion: 557@env{TEXTDOMAINDIR}/@env{LC_MESSAGES}/LC_MESSAGES/@env{TEXTDOMAIN}.mo. 558 559@node Comments 560@subsection Comments 561@cindex comments, shell 562 563In a non-interactive shell, or an interactive shell in which the 564@code{interactive_comments} option to the @code{shopt} 565builtin is enabled (@pxref{Bash Builtins}), 566a word beginning with @samp{#} 567causes that word and all remaining characters on that line to 568be ignored. An interactive shell without the @code{interactive_comments} 569option enabled does not allow comments. The @code{interactive_comments} 570option is on by default in interactive shells. 571@xref{Interactive Shells}, for a description of what makes 572a shell interactive. 573 574@node Shell Commands 575@section Shell Commands 576@cindex commands, shell 577 578A simple shell command such as @code{echo a b c} consists of the command 579itself followed by arguments, separated by spaces. 580 581More complex shell commands are composed of simple commands arranged together 582in a variety of ways: in a pipeline in which the output of one command 583becomes the input of a second, in a loop or conditional construct, or in 584some other grouping. 585 586@menu 587* Simple Commands:: The most common type of command. 588* Pipelines:: Connecting the input and output of several 589 commands. 590* Lists:: How to execute commands sequentially. 591* Compound Commands:: Shell commands for control flow. 592@end menu 593 594@node Simple Commands 595@subsection Simple Commands 596@cindex commands, simple 597 598A simple command is the kind of command encountered most often. 599It's just a sequence of words separated by @code{blank}s, terminated 600by one of the shell's control operators (@pxref{Definitions}). The 601first word generally specifies a command to be executed, with the 602rest of the words being that command's arguments. 603 604The return status (@pxref{Exit Status}) of a simple command is 605its exit status as provided 606by the @sc{posix} 1003.1 @code{waitpid} function, or 128+@var{n} if 607the command was terminated by signal @var{n}. 608 609@node Pipelines 610@subsection Pipelines 611@cindex pipeline 612@cindex commands, pipelines 613 614A @code{pipeline} is a sequence of simple commands separated by 615@samp{|}. 616 617@rwindex time 618@rwindex ! 619@cindex command timing 620The format for a pipeline is 621@example 622[@code{time} [@code{-p}]] [@code{!}] @var{command1} [@code{|} @var{command2} @dots{}] 623@end example 624 625@noindent 626The output of each command in the pipeline is connected via a pipe 627to the input of the next command. 628That is, each command reads the previous command's output. 629 630The reserved word @code{time} causes timing statistics 631to be printed for the pipeline once it finishes. 632The statistics currently consist of elapsed (wall-clock) time and 633user and system time consumed by the command's execution. 634The @option{-p} option changes the output format to that specified 635by @sc{posix}. 636The @env{TIMEFORMAT} variable may be set to a format string that 637specifies how the timing information should be displayed. 638@xref{Bash Variables}, for a description of the available formats. 639The use of @code{time} as a reserved word permits the timing of 640shell builtins, shell functions, and pipelines. An external 641@code{time} command cannot time these easily. 642 643If the pipeline is not executed asynchronously (@pxref{Lists}), the 644shell waits for all commands in the pipeline to complete. 645 646Each command in a pipeline is executed in its own subshell 647(@pxref{Command Execution Environment}). The exit 648status of a pipeline is the exit status of the last command in the 649pipeline, unless the @code{pipefail} option is enabled 650(@pxref{The Set Builtin}). 651If @code{pipefail} is enabled, the pipeline's return status is the 652value of the last (rightmost) command to exit with a non-zero status, 653or zero if all commands exit successfully. 654If the reserved word @samp{!} precedes the pipeline, the 655exit status is the logical negation of the exit status as described 656above. 657The shell waits for all commands in the pipeline to terminate before 658returning a value. 659 660@node Lists 661@subsection Lists of Commands 662@cindex commands, lists 663 664A @code{list} is a sequence of one or more pipelines separated by one 665of the operators @samp{;}, @samp{&}, @samp{&&}, or @samp{||}, 666and optionally terminated by one of @samp{;}, @samp{&}, or a 667@code{newline}. 668 669Of these list operators, @samp{&&} and @samp{||} 670have equal precedence, followed by @samp{;} and @samp{&}, 671which have equal precedence. 672 673A sequence of one or more newlines may appear in a @code{list} 674to delimit commands, equivalent to a semicolon. 675 676If a command is terminated by the control operator @samp{&}, 677the shell executes the command asynchronously in a subshell. 678This is known as executing the command in the @var{background}. 679The shell does not wait for the command to finish, and the return 680status is 0 (true). 681When job control is not active (@pxref{Job Control}), 682the standard input for asynchronous commands, in the absence of any 683explicit redirections, is redirected from @code{/dev/null}. 684 685Commands separated by a @samp{;} are executed sequentially; the shell 686waits for each command to terminate in turn. The return status is the 687exit status of the last command executed. 688 689The control operators @samp{&&} and @samp{||} 690denote @sc{and} lists and @sc{or} lists, respectively. 691An @sc{and} list has the form 692@example 693@var{command1} && @var{command2} 694@end example 695 696@noindent 697@var{command2} is executed if, and only if, @var{command1} 698returns an exit status of zero. 699 700An @sc{or} list has the form 701@example 702@var{command1} || @var{command2} 703@end example 704 705@noindent 706@var{command2} is executed if, and only if, @var{command1} 707returns a non-zero exit status. 708 709The return status of 710@sc{and} and @sc{or} lists is the exit status of the last command 711executed in the list. 712 713@node Compound Commands 714@subsection Compound Commands 715@cindex commands, compound 716 717@menu 718* Looping Constructs:: Shell commands for iterative action. 719* Conditional Constructs:: Shell commands for conditional execution. 720* Command Grouping:: Ways to group commands. 721@end menu 722 723Compound commands are the shell programming constructs. 724Each construct begins with a reserved word or control operator and is 725terminated by a corresponding reserved word or operator. 726Any redirections (@pxref{Redirections}) associated with a compound command 727apply to all commands within that compound command unless explicitly overridden. 728 729Bash provides looping constructs, conditional commands, and mechanisms 730to group commands and execute them as a unit. 731 732@node Looping Constructs 733@subsubsection Looping Constructs 734@cindex commands, looping 735 736Bash supports the following looping constructs. 737 738Note that wherever a @samp{;} appears in the description of a 739command's syntax, it may be replaced with one or more newlines. 740 741@table @code 742@item until 743@rwindex until 744@rwindex do 745@rwindex done 746The syntax of the @code{until} command is: 747@example 748until @var{test-commands}; do @var{consequent-commands}; done 749@end example 750Execute @var{consequent-commands} as long as 751@var{test-commands} has an exit status which is not zero. 752The return status is the exit status of the last command executed 753in @var{consequent-commands}, or zero if none was executed. 754 755@item while 756@rwindex while 757The syntax of the @code{while} command is: 758@example 759while @var{test-commands}; do @var{consequent-commands}; done 760@end example 761 762Execute @var{consequent-commands} as long as 763@var{test-commands} has an exit status of zero. 764The return status is the exit status of the last command executed 765in @var{consequent-commands}, or zero if none was executed. 766 767@item for 768@rwindex for 769The syntax of the @code{for} command is: 770 771@example 772for @var{name} [in @var{words} @dots{}]; do @var{commands}; done 773@end example 774Expand @var{words}, and execute @var{commands} once for each member 775in the resultant list, with @var{name} bound to the current member. 776If @samp{in @var{words}} is not present, the @code{for} command 777executes the @var{commands} once for each positional parameter that is 778set, as if @samp{in "$@@"} had been specified 779(@pxref{Special Parameters}). 780The return status is the exit status of the last command that executes. 781If there are no items in the expansion of @var{words}, no commands are 782executed, and the return status is zero. 783 784An alternate form of the @code{for} command is also supported: 785 786@example 787for (( @var{expr1} ; @var{expr2} ; @var{expr3} )) ; do @var{commands} ; done 788@end example 789First, the arithmetic expression @var{expr1} is evaluated according 790to the rules described below (@pxref{Shell Arithmetic}). 791The arithmetic expression @var{expr2} is then evaluated repeatedly 792until it evaluates to zero. 793Each time @var{expr2} evaluates to a non-zero value, @var{commands} are 794executed and the arithmetic expression @var{expr3} is evaluated. 795If any expression is omitted, it behaves as if it evaluates to 1. 796The return value is the exit status of the last command in @var{list} 797that is executed, or false if any of the expressions is invalid. 798 799@end table 800 801The @code{break} and @code{continue} builtins (@pxref{Bourne Shell Builtins}) 802may be used to control loop execution. 803 804@node Conditional Constructs 805@subsubsection Conditional Constructs 806@cindex commands, conditional 807 808@table @code 809@item if 810@rwindex if 811@rwindex then 812@rwindex else 813@rwindex elif 814@rwindex fi 815The syntax of the @code{if} command is: 816 817@example 818if @var{test-commands}; then 819 @var{consequent-commands}; 820[elif @var{more-test-commands}; then 821 @var{more-consequents};] 822[else @var{alternate-consequents};] 823fi 824@end example 825 826The @var{test-commands} list is executed, and if its return status is zero, 827the @var{consequent-commands} list is executed. 828If @var{test-commands} returns a non-zero status, each @code{elif} list 829is executed in turn, and if its exit status is zero, 830the corresponding @var{more-consequents} is executed and the 831command completes. 832If @samp{else @var{alternate-consequents}} is present, and 833the final command in the final @code{if} or @code{elif} clause 834has a non-zero exit status, then @var{alternate-consequents} is executed. 835The return status is the exit status of the last command executed, or 836zero if no condition tested true. 837 838@item case 839@rwindex case 840@rwindex in 841@rwindex esac 842The syntax of the @code{case} command is: 843 844@example 845@code{case @var{word} in [ [(] @var{pattern} [| @var{pattern}]@dots{}) @var{command-list} ;;]@dots{} esac} 846@end example 847 848@code{case} will selectively execute the @var{command-list} corresponding to 849the first @var{pattern} that matches @var{word}. 850If the shell option @code{nocasematch} 851(see the description of @code{shopt} in @ref{Bash Builtins}) 852is enabled, the match is performed without regard to the case 853of alphabetic characters. 854The @samp{|} is used to separate multiple patterns, and the @samp{)} 855operator terminates a pattern list. 856A list of patterns and an associated command-list is known 857as a @var{clause}. Each clause must be terminated with @samp{;;}. 858The @var{word} undergoes tilde expansion, parameter expansion, command 859substitution, arithmetic expansion, and quote removal before matching is 860attempted. Each @var{pattern} undergoes tilde expansion, parameter 861expansion, command substitution, and arithmetic expansion. 862 863There may be an arbitrary number of @code{case} clauses, each terminated 864by a @samp{;;}. The first pattern that matches determines the 865command-list that is executed. 866 867Here is an example using @code{case} in a script that could be used to 868describe one interesting feature of an animal: 869 870@example 871echo -n "Enter the name of an animal: " 872read ANIMAL 873echo -n "The $ANIMAL has " 874case $ANIMAL in 875 horse | dog | cat) echo -n "four";; 876 man | kangaroo ) echo -n "two";; 877 *) echo -n "an unknown number of";; 878esac 879echo " legs." 880@end example 881 882@noindent 883The return status is zero if no @var{pattern} is matched. Otherwise, the 884return status is the exit status of the @var{command-list} executed. 885 886@item select 887@rwindex select 888 889The @code{select} construct allows the easy generation of menus. 890It has almost the same syntax as the @code{for} command: 891 892@example 893select @var{name} [in @var{words} @dots{}]; do @var{commands}; done 894@end example 895 896The list of words following @code{in} is expanded, generating a list 897of items. The set of expanded words is printed on the standard 898error output stream, each preceded by a number. If the 899@samp{in @var{words}} is omitted, the positional parameters are printed, 900as if @samp{in "$@@"} had been specifed. 901The @env{PS3} prompt is then displayed and a line is read from the 902standard input. 903If the line consists of a number corresponding to one of the displayed 904words, then the value of @var{name} is set to that word. 905If the line is empty, the words and prompt are displayed again. 906If @code{EOF} is read, the @code{select} command completes. 907Any other value read causes @var{name} to be set to null. 908The line read is saved in the variable @env{REPLY}. 909 910The @var{commands} are executed after each selection until a 911@code{break} command is executed, at which 912point the @code{select} command completes. 913 914Here is an example that allows the user to pick a filename from the 915current directory, and displays the name and index of the file 916selected. 917 918@example 919select fname in *; 920do 921 echo you picked $fname \($REPLY\) 922 break; 923done 924@end example 925 926@item ((@dots{})) 927@example 928(( @var{expression} )) 929@end example 930 931The arithmetic @var{expression} is evaluated according to the rules 932described below (@pxref{Shell Arithmetic}). 933If the value of the expression is non-zero, the return status is 0; 934otherwise the return status is 1. This is exactly equivalent to 935@example 936let "@var{expression}" 937@end example 938@noindent 939@xref{Bash Builtins}, for a full description of the @code{let} builtin. 940 941@item [[@dots{}]] 942@rwindex [[ 943@rwindex ]] 944@example 945[[ @var{expression} ]] 946@end example 947 948Return a status of 0 or 1 depending on the evaluation of 949the conditional expression @var{expression}. 950Expressions are composed of the primaries described below in 951@ref{Bash Conditional Expressions}. 952Word splitting and filename expansion are not performed on the words 953between the @samp{[[} and @samp{]]}; tilde expansion, parameter and 954variable expansion, arithmetic expansion, command substitution, process 955substitution, and quote removal are performed. 956Conditional operators such as @samp{-f} must be unquoted to be recognized 957as primaries. 958 959When the @samp{==} and @samp{!=} operators are used, the string to the 960right of the operator is considered a pattern and matched according 961to the rules described below in @ref{Pattern Matching}. 962If the shell option @code{nocasematch} 963(see the description of @code{shopt} in @ref{Bash Builtins}) 964is enabled, the match is performed without regard to the case 965of alphabetic characters. 966The return value is 0 if the string matches (@samp{==}) or does not 967match (@samp{!=})the pattern, and 1 otherwise. 968Any part of the pattern may be quoted to force it to be matched as a 969string. 970 971An additional binary operator, @samp{=~}, is available, with the same 972precedence as @samp{==} and @samp{!=}. 973When it is used, the string to the right of the operator is considered 974an extended regular expression and matched accordingly (as in @i{regex}3)). 975The return value is 0 if the string matches 976the pattern, and 1 otherwise. 977If the regular expression is syntactically incorrect, the conditional 978expression's return value is 2. 979If the shell option @code{nocasematch} 980(see the description of @code{shopt} in @ref{Bash Builtins}) 981is enabled, the match is performed without regard to the case 982of alphabetic characters. 983Substrings matched by parenthesized subexpressions within the regular 984expression are saved in the array variable @code{BASH_REMATCH}. 985The element of @code{BASH_REMATCH} with index 0 is the portion of the string 986matching the entire regular expression. 987The element of @code{BASH_REMATCH} with index @var{n} is the portion of the 988string matching the @var{n}th parenthesized subexpression. 989 990Expressions may be combined using the following operators, listed 991in decreasing order of precedence: 992 993@table @code 994@item ( @var{expression} ) 995Returns the value of @var{expression}. 996This may be used to override the normal precedence of operators. 997 998@item ! @var{expression} 999True if @var{expression} is false. 1000 1001@item @var{expression1} && @var{expression2} 1002True if both @var{expression1} and @var{expression2} are true. 1003 1004@item @var{expression1} || @var{expression2} 1005True if either @var{expression1} or @var{expression2} is true. 1006@end table 1007@noindent 1008The @code{&&} and @code{||} operators do not evaluate @var{expression2} if the 1009value of @var{expression1} is sufficient to determine the return 1010value of the entire conditional expression. 1011 1012@end table 1013 1014@node Command Grouping 1015@subsubsection Grouping Commands 1016@cindex commands, grouping 1017 1018Bash provides two ways to group a list of commands to be executed 1019as a unit. When commands are grouped, redirections may be applied 1020to the entire command list. For example, the output of all the 1021commands in the list may be redirected to a single stream. 1022 1023@table @code 1024@item () 1025@example 1026( @var{list} ) 1027@end example 1028 1029Placing a list of commands between parentheses causes a subshell 1030environment to be created (@pxref{Command Execution Environment}), and each 1031of the commands in @var{list} to be executed in that subshell. Since the 1032@var{list} is executed in a subshell, variable assignments do not remain in 1033effect after the subshell completes. 1034 1035@item @{@} 1036@rwindex @{ 1037@rwindex @} 1038@example 1039@{ @var{list}; @} 1040@end example 1041 1042Placing a list of commands between curly braces causes the list to 1043be executed in the current shell context. No subshell is created. 1044The semicolon (or newline) following @var{list} is required. 1045@end table 1046 1047In addition to the creation of a subshell, there is a subtle difference 1048between these two constructs due to historical reasons. The braces 1049are @code{reserved words}, so they must be separated from the @var{list} 1050by @code{blank}s. The parentheses are @code{operators}, and are 1051recognized as separate tokens by the shell even if they are not separated 1052from the @var{list} by whitespace. 1053 1054The exit status of both of these constructs is the exit status of 1055@var{list}. 1056 1057@node Shell Functions 1058@section Shell Functions 1059@cindex shell function 1060@cindex functions, shell 1061 1062Shell functions are a way to group commands for later execution 1063using a single name for the group. They are executed just like 1064a "regular" command. 1065When the name of a shell function is used as a simple command name, 1066the list of commands associated with that function name is executed. 1067Shell functions are executed in the current 1068shell context; no new process is created to interpret them. 1069 1070Functions are declared using this syntax: 1071@rwindex function 1072@example 1073[ @code{function} ] @var{name} () @var{compound-command} [ @var{redirections} ] 1074@end example 1075 1076This defines a shell function named @var{name}. The reserved 1077word @code{function} is optional. 1078If the @code{function} reserved 1079word is supplied, the parentheses are optional. 1080The @var{body} of the function is the compound command 1081@var{compound-command} (@pxref{Compound Commands}). 1082That command is usually a @var{list} enclosed between @{ and @}, but 1083may be any compound command listed above. 1084@var{compound-command} is executed whenever @var{name} is specified as the 1085name of a command. 1086Any redirections (@pxref{Redirections}) associated with the shell function 1087are performed when the function is executed. 1088 1089A function definition may be deleted using the @option{-f} option to the 1090@code{unset} builtin (@pxref{Bourne Shell Builtins}). 1091 1092The exit status of a function definition is zero unless a syntax error 1093occurs or a readonly function with the same name already exists. 1094When executed, the exit status of a function is the exit status of the 1095last command executed in the body. 1096 1097Note that for historical reasons, in the most common usage the curly braces 1098that surround the body of the function must be separated from the body by 1099@code{blank}s or newlines. 1100This is because the braces are reserved words and are only recognized 1101as such when they are separated by whitespace. 1102Also, when using the braces, the @var{list} must be terminated by a semicolon, 1103a @samp{&}, or a newline. 1104 1105When a function is executed, the arguments to the 1106function become the positional parameters 1107during its execution (@pxref{Positional Parameters}). 1108The special parameter @samp{#} that expands to the number of 1109positional parameters is updated to reflect the change. 1110Special parameter @code{0} is unchanged. 1111The first element of the @env{FUNCNAME} variable is set to the 1112name of the function while the function is executing. 1113All other aspects of the shell execution 1114environment are identical between a function and its caller 1115with the exception that the @env{DEBUG} and @env{RETURN} traps 1116are not inherited unless the function has been given the 1117@code{trace} attribute using the @code{declare} builtin or 1118the @code{-o functrace} option has been enabled with 1119the @code{set} builtin, 1120(in which case all functions inherit the @env{DEBUG} and @env{RETURN} traps). 1121@xref{Bourne Shell Builtins}, for the description of the 1122@code{trap} builtin. 1123 1124If the builtin command @code{return} 1125is executed in a function, the function completes and 1126execution resumes with the next command after the function 1127call. 1128Any command associated with the @code{RETURN} trap is executed 1129before execution resumes. 1130When a function completes, the values of the 1131positional parameters and the special parameter @samp{#} 1132are restored to the values they had prior to the function's 1133execution. If a numeric argument is given to @code{return}, 1134that is the function's return status; otherwise the function's 1135return status is the exit status of the last command executed 1136before the @code{return}. 1137 1138Variables local to the function may be declared with the 1139@code{local} builtin. These variables are visible only to 1140the function and the commands it invokes. 1141 1142Function names and definitions may be listed with the 1143@option{-f} option to the @code{declare} or @code{typeset} 1144builtin commands (@pxref{Bash Builtins}). 1145The @option{-F} option to @code{declare} or @code{typeset} 1146will list the function names only 1147(and optionally the source file and line number, if the @code{extdebug} 1148shell option is enabled). 1149Functions may be exported so that subshells 1150automatically have them defined with the 1151@option{-f} option to the @code{export} builtin 1152(@pxref{Bourne Shell Builtins}). 1153Note that shell functions and variables with the same name may result 1154in multiple identically-named entries in the environment passed to the 1155shell's children. 1156Care should be taken in cases where this may cause a problem. 1157 1158Functions may be recursive. No limit is placed on the number of 1159recursive calls. 1160 1161@node Shell Parameters 1162@section Shell Parameters 1163@cindex parameters 1164@cindex variable, shell 1165@cindex shell variable 1166 1167@menu 1168* Positional Parameters:: The shell's command-line arguments. 1169* Special Parameters:: Parameters denoted by special characters. 1170@end menu 1171 1172A @var{parameter} is an entity that stores values. 1173It can be a @code{name}, a number, or one of the special characters 1174listed below. 1175A @var{variable} is a parameter denoted by a @code{name}. 1176A variable has a @var{value} and zero or more @var{attributes}. 1177Attributes are assigned using the @code{declare} builtin command 1178(see the description of the @code{declare} builtin in @ref{Bash Builtins}). 1179 1180A parameter is set if it has been assigned a value. The null string is 1181a valid value. Once a variable is set, it may be unset only by using 1182the @code{unset} builtin command. 1183 1184A variable may be assigned to by a statement of the form 1185@example 1186@var{name}=[@var{value}] 1187@end example 1188@noindent 1189If @var{value} 1190is not given, the variable is assigned the null string. All 1191@var{value}s undergo tilde expansion, parameter and variable expansion, 1192command substitution, arithmetic expansion, and quote 1193removal (detailed below). If the variable has its @code{integer} 1194attribute set, then @var{value} 1195is evaluated as an arithmetic expression even if the @code{$((@dots{}))} 1196expansion is not used (@pxref{Arithmetic Expansion}). 1197Word splitting is not performed, with the exception 1198of @code{"$@@"} as explained below. 1199Filename expansion is not performed. 1200Assignment statements may also appear as arguments to the 1201@code{alias}, 1202@code{declare}, @code{typeset}, @code{export}, @code{readonly}, 1203and @code{local} builtin commands. 1204 1205In the context where an assignment statement is assigning a value 1206to a shell variable or array index (@pxref{Arrays}), the @samp{+=} 1207operator can be used to 1208append to or add to the variable's previous value. 1209When @samp{+=} is applied to a variable for which the integer attribute 1210has been set, @var{value} is evaluated as an arithmetic expression and 1211added to the variable's current value, which is also evaluated. 1212When @samp{+=} is applied to an array variable using compound assignment 1213(@pxref{Arrays}), the 1214variable's value is not unset (as it is when using @samp{=}), and new 1215values are appended to the array beginning at one greater than the array's 1216maximum index. 1217When applied to a string-valued variable, @var{value} is expanded and 1218appended to the variable's value. 1219 1220@node Positional Parameters 1221@subsection Positional Parameters 1222@cindex parameters, positional 1223 1224A @var{positional parameter} is a parameter denoted by one or more 1225digits, other than the single digit @code{0}. Positional parameters are 1226assigned from the shell's arguments when it is invoked, 1227and may be reassigned using the @code{set} builtin command. 1228Positional parameter @code{N} may be referenced as @code{$@{N@}}, or 1229as @code{$N} when @code{N} consists of a single digit. 1230Positional parameters may not be assigned to with assignment statements. 1231The @code{set} and @code{shift} builtins are used to set and 1232unset them (@pxref{Shell Builtin Commands}). 1233The positional parameters are 1234temporarily replaced when a shell function is executed 1235(@pxref{Shell Functions}). 1236 1237When a positional parameter consisting of more than a single 1238digit is expanded, it must be enclosed in braces. 1239 1240@node Special Parameters 1241@subsection Special Parameters 1242@cindex parameters, special 1243 1244The shell treats several parameters specially. These parameters may 1245only be referenced; assignment to them is not allowed. 1246 1247@vtable @code 1248 1249@item * 1250Expands to the positional parameters, starting from one. When the 1251expansion occurs within double quotes, it expands to a single word 1252with the value of each parameter separated by the first character 1253of the @env{IFS} 1254special variable. That is, @code{"$*"} is equivalent 1255to @code{"$1@var{c}$2@var{c}@dots{}"}, where @var{c} 1256is the first character of the value of the @code{IFS} 1257variable. 1258If @env{IFS} is unset, the parameters are separated by spaces. 1259If @env{IFS} is null, the parameters are joined without intervening 1260separators. 1261 1262 1263@item @@ 1264Expands to the positional parameters, starting from one. When the 1265expansion occurs within double quotes, each parameter expands to a 1266separate word. That is, @code{"$@@"} is equivalent to 1267@code{"$1" "$2" @dots{}}. 1268If the double-quoted expansion occurs within a word, the expansion of 1269the first parameter is joined with the beginning part of the original 1270word, and the expansion of the last parameter is joined with the last 1271part of the original word. 1272When there are no positional parameters, @code{"$@@"} and 1273@code{$@@} 1274expand to nothing (i.e., they are removed). 1275 1276@item # 1277Expands to the number of positional parameters in decimal. 1278 1279@item ? 1280Expands to the exit status of the most recently executed foreground 1281pipeline. 1282 1283@item - 1284(A hyphen.) Expands to the current option flags as specified upon 1285invocation, by the @code{set} 1286builtin command, or those set by the shell itself 1287(such as the @option{-i} option). 1288 1289@item $ 1290Expands to the process @sc{id} of the shell. In a @code{()} subshell, it 1291expands to the process @sc{id} of the invoking shell, not the subshell. 1292 1293@item ! 1294Expands to the process @sc{id} of the most recently executed background 1295(asynchronous) command. 1296 1297@item 0 1298Expands to the name of the shell or shell script. This is set at 1299shell initialization. If Bash is invoked with a file of commands 1300(@pxref{Shell Scripts}), @code{$0} is set to the name of that file. 1301If Bash is started with the @option{-c} option (@pxref{Invoking Bash}), 1302then @code{$0} is set to the first argument after the string to be 1303executed, if one is present. Otherwise, it is set 1304to the filename used to invoke Bash, as given by argument zero. 1305 1306@item _ 1307(An underscore.) 1308At shell startup, set to the absolute pathname used to invoke the 1309shell or shell script being executed as passed in the environment 1310or argument list. 1311Subsequently, expands to the last argument to the previous command, 1312after expansion. 1313Also set to the full pathname used to invoke each command executed 1314and placed in the environment exported to that command. 1315When checking mail, this parameter holds the name of the mail file. 1316@end vtable 1317 1318@node Shell Expansions 1319@section Shell Expansions 1320@cindex expansion 1321 1322Expansion is performed on the command line after it has been split into 1323@code{token}s. There are seven kinds of expansion performed: 1324@itemize @bullet 1325@item brace expansion 1326@item tilde expansion 1327@item parameter and variable expansion 1328@item command substitution 1329@item arithmetic expansion 1330@item word splitting 1331@item filename expansion 1332@end itemize 1333 1334@menu 1335* Brace Expansion:: Expansion of expressions within braces. 1336* Tilde Expansion:: Expansion of the ~ character. 1337* Shell Parameter Expansion:: How Bash expands variables to their values. 1338* Command Substitution:: Using the output of a command as an argument. 1339* Arithmetic Expansion:: How to use arithmetic in shell expansions. 1340* Process Substitution:: A way to write and read to and from a 1341 command. 1342* Word Splitting:: How the results of expansion are split into separate 1343 arguments. 1344* Filename Expansion:: A shorthand for specifying filenames matching patterns. 1345* Quote Removal:: How and when quote characters are removed from 1346 words. 1347@end menu 1348 1349The order of expansions is: brace expansion, tilde expansion, 1350parameter, variable, and arithmetic expansion and 1351command substitution 1352(done in a left-to-right fashion), word splitting, and filename 1353expansion. 1354 1355On systems that can support it, there is an additional expansion 1356available: @var{process substitution}. This is performed at the 1357same time as parameter, variable, and arithmetic expansion and 1358command substitution. 1359 1360Only brace expansion, word splitting, and filename expansion 1361can change the number of words of the expansion; other expansions 1362expand a single word to a single word. 1363The only exceptions to this are the expansions of 1364@code{"$@@"} (@pxref{Special Parameters}) and @code{"$@{@var{name}[@@]@}"} 1365(@pxref{Arrays}). 1366 1367After all expansions, @code{quote removal} (@pxref{Quote Removal}) 1368is performed. 1369 1370@node Brace Expansion 1371@subsection Brace Expansion 1372@cindex brace expansion 1373@cindex expansion, brace 1374 1375Brace expansion is a mechanism by which arbitrary strings may be generated. 1376This mechanism is similar to 1377@var{filename expansion} (@pxref{Filename Expansion}), 1378but the file names generated need not exist. 1379Patterns to be brace expanded take the form of an optional @var{preamble}, 1380followed by either a series of comma-separated strings or a sequnce expression 1381between a pair of braces, 1382followed by an optional @var{postscript}. 1383The preamble is prefixed to each string contained within the braces, and 1384the postscript is then appended to each resulting string, expanding left 1385to right. 1386 1387Brace expansions may be nested. 1388The results of each expanded string are not sorted; left to right order 1389is preserved. 1390For example, 1391@example 1392bash$ echo a@{d,c,b@}e 1393ade ace abe 1394@end example 1395 1396A sequence expression takes the form @code{@{@var{x}..@var{y}@}}, 1397where @var{x} and @var{y} are either integers or single characters. 1398When integers are supplied, the expression expands to each number between 1399@var{x} and @var{y}, inclusive. 1400When characters are supplied, the expression expands to each character 1401lexicographically between @var{x} and @var{y}, inclusive. Note that 1402both @var{x} and @var{y} must be of the same type. 1403 1404Brace expansion is performed before any other expansions, 1405and any characters special to other expansions are preserved 1406in the result. It is strictly textual. Bash 1407does not apply any syntactic interpretation to the context of the 1408expansion or the text between the braces. 1409To avoid conflicts with parameter expansion, the string @samp{$@{} 1410is not considered eligible for brace expansion. 1411 1412A correctly-formed brace expansion must contain unquoted opening 1413and closing braces, and at least one unquoted comma or a valid 1414sequence expression. 1415Any incorrectly formed brace expansion is left unchanged. 1416 1417A @{ or @samp{,} may be quoted with a backslash to prevent its 1418being considered part of a brace expression. 1419To avoid conflicts with parameter expansion, the string @samp{$@{} 1420is not considered eligible for brace expansion. 1421 1422This construct is typically used as shorthand when the common 1423prefix of the strings to be generated is longer than in the 1424above example: 1425@example 1426mkdir /usr/local/src/bash/@{old,new,dist,bugs@} 1427@end example 1428or 1429@example 1430chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@} 1431@end example 1432 1433@node Tilde Expansion 1434@subsection Tilde Expansion 1435@cindex tilde expansion 1436@cindex expansion, tilde 1437 1438If a word begins with an unquoted tilde character (@samp{~}), all of the 1439characters up to the first unquoted slash (or all characters, 1440if there is no unquoted slash) are considered a @var{tilde-prefix}. 1441If none of the characters in the tilde-prefix are quoted, the 1442characters in the tilde-prefix following the tilde are treated as a 1443possible @var{login name}. 1444If this login name is the null string, the tilde is replaced with the 1445value of the @env{HOME} shell variable. 1446If @env{HOME} is unset, the home directory of the user executing the 1447shell is substituted instead. 1448Otherwise, the tilde-prefix is replaced with the home directory 1449associated with the specified login name. 1450 1451If the tilde-prefix is @samp{~+}, the value of 1452the shell variable @env{PWD} replaces the tilde-prefix. 1453If the tilde-prefix is @samp{~-}, the value of the shell variable 1454@env{OLDPWD}, if it is set, is substituted. 1455 1456If the characters following the tilde in the tilde-prefix consist of a 1457number @var{N}, optionally prefixed by a @samp{+} or a @samp{-}, 1458the tilde-prefix is replaced with the 1459corresponding element from the directory stack, as it would be displayed 1460by the @code{dirs} builtin invoked with the characters following tilde 1461in the tilde-prefix as an argument (@pxref{The Directory Stack}). 1462If the tilde-prefix, sans the tilde, consists of a number without a 1463leading @samp{+} or @samp{-}, @samp{+} is assumed. 1464 1465If the login name is invalid, or the tilde expansion fails, the word is 1466left unchanged. 1467 1468Each variable assignment is checked for unquoted tilde-prefixes immediately 1469following a @samp{:} or the first @samp{=}. 1470In these cases, tilde expansion is also performed. 1471Consequently, one may use file names with tildes in assignments to 1472@env{PATH}, @env{MAILPATH}, and @env{CDPATH}, 1473and the shell assigns the expanded value. 1474 1475The following table shows how Bash treats unquoted tilde-prefixes: 1476 1477@table @code 1478@item ~ 1479The value of @code{$HOME} 1480@item ~/foo 1481@file{$HOME/foo} 1482 1483@item ~fred/foo 1484The subdirectory @code{foo} of the home directory of the user 1485@code{fred} 1486 1487@item ~+/foo 1488@file{$PWD/foo} 1489 1490@item ~-/foo 1491@file{$@{OLDPWD-'~-'@}/foo} 1492 1493@item ~@var{N} 1494The string that would be displayed by @samp{dirs +@var{N}} 1495 1496@item ~+@var{N} 1497The string that would be displayed by @samp{dirs +@var{N}} 1498 1499@item ~-@var{N} 1500The string that would be displayed by @samp{dirs -@var{N}} 1501 1502@end table 1503 1504@node Shell Parameter Expansion 1505@subsection Shell Parameter Expansion 1506@cindex parameter expansion 1507@cindex expansion, parameter 1508 1509The @samp{$} character introduces parameter expansion, 1510command substitution, or arithmetic expansion. The parameter name 1511or symbol to be expanded may be enclosed in braces, which 1512are optional but serve to protect the variable to be expanded from 1513characters immediately following it which could be 1514interpreted as part of the name. 1515 1516When braces are used, the matching ending brace is the first @samp{@}} 1517not escaped by a backslash or within a quoted string, and not within an 1518embedded arithmetic expansion, command substitution, or parameter 1519expansion. 1520 1521The basic form of parameter expansion is $@{@var{parameter}@}. 1522The value of @var{parameter} is substituted. The braces are required 1523when @var{parameter} 1524is a positional parameter with more than one digit, 1525or when @var{parameter} 1526is followed by a character that is not to be 1527interpreted as part of its name. 1528 1529If the first character of @var{parameter} is an exclamation point, 1530a level of variable indirection is introduced. 1531Bash uses the value of the variable formed from the rest of 1532@var{parameter} as the name of the variable; this variable is then 1533expanded and that value is used in the rest of the substitution, rather 1534than the value of @var{parameter} itself. 1535This is known as @code{indirect expansion}. 1536The exceptions to this are the expansions of $@{!@var{prefix*}@} 1537and $@{!@var{name}[@@]@} 1538described below. 1539The exclamation point must immediately follow the left brace in order to 1540introduce indirection. 1541 1542In each of the cases below, @var{word} is subject to tilde expansion, 1543parameter expansion, command substitution, and arithmetic expansion. 1544 1545When not performing substring expansion, Bash tests for a parameter 1546that is unset or null; omitting the colon results in a test only for a 1547parameter that is unset. Put another way, if the colon is included, 1548the operator tests for both existence and that the value is not null; 1549if the colon is omitted, the operator tests only for existence. 1550 1551@table @code 1552 1553@item $@{@var{parameter}:@minus{}@var{word}@} 1554If @var{parameter} is unset or null, the expansion of 1555@var{word} is substituted. Otherwise, the value of 1556@var{parameter} is substituted. 1557 1558@item $@{@var{parameter}:=@var{word}@} 1559If @var{parameter} 1560is unset or null, the expansion of @var{word} 1561is assigned to @var{parameter}. 1562The value of @var{parameter} is then substituted. 1563Positional parameters and special parameters may not be assigned to 1564in this way. 1565 1566@item $@{@var{parameter}:?@var{word}@} 1567If @var{parameter} 1568is null or unset, the expansion of @var{word} (or a message 1569to that effect if @var{word} 1570is not present) is written to the standard error and the shell, if it 1571is not interactive, exits. Otherwise, the value of @var{parameter} is 1572substituted. 1573 1574@item $@{@var{parameter}:+@var{word}@} 1575If @var{parameter} 1576is null or unset, nothing is substituted, otherwise the expansion of 1577@var{word} is substituted. 1578 1579@item $@{@var{parameter}:@var{offset}@} 1580@itemx $@{@var{parameter}:@var{offset}:@var{length}@} 1581Expands to up to @var{length} characters of @var{parameter} 1582starting at the character specified by @var{offset}. 1583If @var{length} is omitted, expands to the substring of 1584@var{parameter} starting at the character specified by @var{offset}. 1585@var{length} and @var{offset} are arithmetic expressions 1586(@pxref{Shell Arithmetic}). 1587This is referred to as Substring Expansion. 1588 1589@var{length} must evaluate to a number greater than or equal to zero. 1590If @var{offset} evaluates to a number less than zero, the value 1591is used as an offset from the end of the value of @var{parameter}. 1592If @var{parameter} is @samp{@@}, the result is @var{length} positional 1593parameters beginning at @var{offset}. 1594If @var{parameter} is an array name indexed by @samp{@@} or @samp{*}, 1595the result is the @var{length} 1596members of the array beginning with @code{$@{@var{parameter}[@var{offset}]@}}. 1597A negative @var{offset} is taken relative to one greater than the maximum 1598index of the specified array. 1599Note that a negative offset must be separated from the colon by at least 1600one space to avoid being confused with the @samp{:-} expansion. 1601Substring indexing is zero-based unless the positional parameters 1602are used, in which case the indexing starts at 1. 1603 1604@item $@{!@var{prefix}*@} 1605@itemx $@{!@var{prefix}@@@} 1606Expands to the names of variables whose names begin with @var{prefix}, 1607separated by the first character of the @env{IFS} special variable. 1608 1609@item $@{!@var{name}[@@]@} 1610@itemx $@{!@var{name}[*]@} 1611If @var{name} is an array variable, expands to the list of array indices 1612(keys) assigned in @var{name}. 1613If @var{name} is not an array, expands to 0 if @var{name} is set and null 1614otherwise. 1615When @samp{@@} is used and the expansion appears within double quotes, each 1616key expands to a separate word. 1617 1618@item $@{#@var{parameter}@} 1619The length in characters of the expanded value of @var{parameter} is 1620substituted. 1621If @var{parameter} is @samp{*} or @samp{@@}, the value substituted 1622is the number of positional parameters. 1623If @var{parameter} is an array name subscripted by @samp{*} or @samp{@@}, 1624the value substituted is the number of elements in the array. 1625 1626@item $@{@var{parameter}#@var{word}@} 1627@itemx $@{@var{parameter}##@var{word}@} 1628The @var{word} 1629is expanded to produce a pattern just as in filename 1630expansion (@pxref{Filename Expansion}). If the pattern matches 1631the beginning of the expanded value of @var{parameter}, 1632then the result of the expansion is the expanded value of @var{parameter} 1633with the shortest matching pattern (the @samp{#} case) or the 1634longest matching pattern (the @samp{##} case) deleted. 1635If @var{parameter} is @samp{@@} or @samp{*}, 1636the pattern removal operation is applied to each positional 1637parameter in turn, and the expansion is the resultant list. 1638If @var{parameter} is an array variable subscripted with 1639@samp{@@} or @samp{*}, 1640the pattern removal operation is applied to each member of the 1641array in turn, and the expansion is the resultant list. 1642 1643@item $@{@var{parameter}%@var{word}@} 1644@itemx $@{@var{parameter}%%@var{word}@} 1645The @var{word} is expanded to produce a pattern just as in 1646filename expansion. 1647If the pattern matches a trailing portion of the expanded value of 1648@var{parameter}, then the result of the expansion is the value of 1649@var{parameter} with the shortest matching pattern (the @samp{%} case) 1650or the longest matching pattern (the @samp{%%} case) deleted. 1651If @var{parameter} is @samp{@@} or @samp{*}, 1652the pattern removal operation is applied to each positional 1653parameter in turn, and the expansion is the resultant list. 1654If @var{parameter} 1655is an array variable subscripted with @samp{@@} or @samp{*}, 1656the pattern removal operation is applied to each member of the 1657array in turn, and the expansion is the resultant list. 1658 1659@item $@{@var{parameter}/@var{pattern}/@var{string}@} 1660 1661The @var{pattern} is expanded to produce a pattern just as in 1662filename expansion. 1663@var{Parameter} is expanded and the longest match of @var{pattern} 1664against its value is replaced with @var{string}. 1665If @var{pattern} begins with @samp{/}, all matches of @var{pattern} are 1666replaced with @var{string}. Normally only the first match is replaced. 1667If @var{pattern} begins with @samp{#}, it must match at the beginning 1668of the expanded value of @var{parameter}. 1669If @var{pattern} begins with @samp{%}, it must match at the end 1670of the expanded value of @var{parameter}. 1671If @var{string} is null, matches of @var{pattern} are deleted 1672and the @code{/} following @var{pattern} may be omitted. 1673If @var{parameter} is @samp{@@} or @samp{*}, 1674the substitution operation is applied to each positional 1675parameter in turn, and the expansion is the resultant list. 1676If @var{parameter} 1677is an array variable subscripted with @samp{@@} or @samp{*}, 1678the substitution operation is applied to each member of the 1679array in turn, and the expansion is the resultant list. 1680 1681@end table 1682 1683@node Command Substitution 1684@subsection Command Substitution 1685@cindex command substitution 1686 1687Command substitution allows the output of a command to replace 1688the command itself. 1689Command substitution occurs when a command is enclosed as follows: 1690@example 1691$(@var{command}) 1692@end example 1693@noindent 1694or 1695@example 1696`@var{command}` 1697@end example 1698 1699@noindent 1700Bash performs the expansion by executing @var{command} and 1701replacing the command substitution with the standard output of the 1702command, with any trailing newlines deleted. 1703Embedded newlines are not deleted, but they may be removed during 1704word splitting. 1705The command substitution @code{$(cat @var{file})} can be 1706replaced by the equivalent but faster @code{$(< @var{file})}. 1707 1708When the old-style backquote form of substitution is used, 1709backslash retains its literal meaning except when followed by 1710@samp{$}, @samp{`}, or @samp{\}. 1711The first backquote not preceded by a backslash terminates the 1712command substitution. 1713When using the @code{$(@var{command})} form, all characters between 1714the parentheses make up the command; none are treated specially. 1715 1716Command substitutions may be nested. To nest when using the backquoted 1717form, escape the inner backquotes with backslashes. 1718 1719If the substitution appears within double quotes, word splitting and 1720filename expansion are not performed on the results. 1721 1722@node Arithmetic Expansion 1723@subsection Arithmetic Expansion 1724@cindex expansion, arithmetic 1725@cindex arithmetic expansion 1726 1727Arithmetic expansion allows the evaluation of an arithmetic expression 1728and the substitution of the result. The format for arithmetic expansion is: 1729 1730@example 1731$(( @var{expression} )) 1732@end example 1733 1734The expression is treated as if it were within double quotes, but 1735a double quote inside the parentheses is not treated specially. 1736All tokens in the expression undergo parameter expansion, command 1737substitution, and quote removal. 1738Arithmetic expansions may be nested. 1739 1740The evaluation is performed according to the rules listed below 1741(@pxref{Shell Arithmetic}). 1742If the expression is invalid, Bash prints a message indicating 1743failure to the standard error and no substitution occurs. 1744 1745@node Process Substitution 1746@subsection Process Substitution 1747@cindex process substitution 1748 1749Process substitution is supported on systems that support named 1750pipes (@sc{fifo}s) or the @file{/dev/fd} method of naming open files. 1751It takes the form of 1752@example 1753<(@var{list}) 1754@end example 1755@noindent 1756or 1757@example 1758>(@var{list}) 1759@end example 1760@noindent 1761The process @var{list} is run with its input or output connected to a 1762@sc{fifo} or some file in @file{/dev/fd}. The name of this file is 1763passed as an argument to the current command as the result of the 1764expansion. If the @code{>(@var{list})} form is used, writing to 1765the file will provide input for @var{list}. If the 1766@code{<(@var{list})} form is used, the file passed as an 1767argument should be read to obtain the output of @var{list}. 1768Note that no space may appear between the @code{<} or @code{>} 1769and the left parenthesis, otherwise the construct would be interpreted 1770as a redirection. 1771 1772When available, process substitution is performed simultaneously with 1773parameter and variable expansion, command substitution, and arithmetic 1774expansion. 1775 1776@node Word Splitting 1777@subsection Word Splitting 1778@cindex word splitting 1779 1780The shell scans the results of parameter expansion, command substitution, 1781and arithmetic expansion that did not occur within double quotes for 1782word splitting. 1783 1784The shell treats each character of @env{$IFS} 1785as a delimiter, and splits the results of the other 1786expansions into words on these characters. If 1787@env{IFS} is unset, or its value is exactly @code{<space><tab><newline>}, 1788the default, then any sequence of @env{IFS} 1789characters serves to delimit words. If @env{IFS} 1790has a value other than the default, then sequences of 1791the whitespace characters @code{space} and @code{tab} 1792are ignored at the beginning and end of the 1793word, as long as the whitespace character is in the 1794value of @env{IFS} (an @env{IFS} whitespace character). 1795Any character in @env{IFS} that is not @env{IFS} 1796whitespace, along with any adjacent @env{IFS} 1797whitespace characters, delimits a field. A sequence of @env{IFS} 1798whitespace characters is also treated as a delimiter. 1799If the value of @env{IFS} is null, no word splitting occurs. 1800 1801Explicit null arguments (@code{""} or @code{''}) are retained. 1802Unquoted implicit null arguments, resulting from the expansion of 1803parameters that have no values, are removed. 1804If a parameter with no value is expanded within double quotes, a 1805null argument results and is retained. 1806 1807Note that if no expansion occurs, no splitting 1808is performed. 1809 1810@node Filename Expansion 1811@subsection Filename Expansion 1812@menu 1813* Pattern Matching:: How the shell matches patterns. 1814@end menu 1815@cindex expansion, filename 1816@cindex expansion, pathname 1817@cindex filename expansion 1818@cindex pathname expansion 1819 1820After word splitting, unless the @option{-f} option has been set 1821(@pxref{The Set Builtin}), Bash scans each word for the characters 1822@samp{*}, @samp{?}, and @samp{[}. 1823If one of these characters appears, then the word is 1824regarded as a @var{pattern}, 1825and replaced with an alphabetically sorted list of 1826file names matching the pattern. If no matching file names are found, 1827and the shell option @code{nullglob} is disabled, the word is left 1828unchanged. 1829If the @code{nullglob} option is set, and no matches are found, the word 1830is removed. 1831If the @code{failglob} shell option is set, and no matches are found, 1832an error message is printed and the command is not executed. 1833If the shell option @code{nocaseglob} is enabled, the match is performed 1834without regard to the case of alphabetic characters. 1835 1836When a pattern is used for filename generation, the character @samp{.} 1837at the start of a filename or immediately following a slash 1838must be matched explicitly, unless the shell option @code{dotglob} is set. 1839When matching a file name, the slash character must always be 1840matched explicitly. 1841In other cases, the @samp{.} character is not treated specially. 1842 1843See the description of @code{shopt} in @ref{Bash Builtins}, 1844for a description of the @code{nocaseglob}, @code{nullglob}, 1845@code{failglob}, and @code{dotglob} options. 1846 1847The @env{GLOBIGNORE} 1848shell variable may be used to restrict the set of filenames matching a 1849pattern. If @env{GLOBIGNORE} 1850is set, each matching filename that also matches one of the patterns in 1851@env{GLOBIGNORE} is removed from the list of matches. The filenames 1852@file{.} and @file{..} 1853are always ignored when @env{GLOBIGNORE} 1854is set and not null. 1855However, setting @env{GLOBIGNORE} to a non-null value has the effect of 1856enabling the @code{dotglob} 1857shell option, so all other filenames beginning with a 1858@samp{.} will match. 1859To get the old behavior of ignoring filenames beginning with a 1860@samp{.}, make @samp{.*} one of the patterns in @env{GLOBIGNORE}. 1861The @code{dotglob} option is disabled when @env{GLOBIGNORE} 1862is unset. 1863 1864@node Pattern Matching 1865@subsubsection Pattern Matching 1866@cindex pattern matching 1867@cindex matching, pattern 1868 1869Any character that appears in a pattern, other than the special pattern 1870characters described below, matches itself. 1871The @sc{nul} character may not occur in a pattern. 1872A backslash escapes the following character; the 1873escaping backslash is discarded when matching. 1874The special pattern characters must be quoted if they are to be matched 1875literally. 1876 1877The special pattern characters have the following meanings: 1878@table @code 1879@item * 1880Matches any string, including the null string. 1881@item ? 1882Matches any single character. 1883@item [@dots{}] 1884Matches any one of the enclosed characters. A pair of characters 1885separated by a hyphen denotes a @var{range expression}; 1886any character that sorts between those two characters, inclusive, 1887using the current locale's collating sequence and character set, 1888is matched. If the first character following the 1889@samp{[} is a @samp{!} or a @samp{^} 1890then any character not enclosed is matched. A @samp{@minus{}} 1891may be matched by including it as the first or last character 1892in the set. A @samp{]} may be matched by including it as the first 1893character in the set. 1894The sorting order of characters in range expressions is determined by 1895the current locale and the value of the @env{LC_COLLATE} shell variable, 1896if set. 1897 1898For example, in the default C locale, @samp{[a-dx-z]} is equivalent to 1899@samp{[abcdxyz]}. Many locales sort characters in dictionary order, and in 1900these locales @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]}; 1901it might be equivalent to @samp{[aBbCcDdxXyYz]}, for example. To obtain 1902the traditional interpretation of ranges in bracket expressions, you can 1903force the use of the C locale by setting the @env{LC_COLLATE} or 1904@env{LC_ALL} environment variable to the value @samp{C}. 1905 1906Within @samp{[} and @samp{]}, @var{character classes} can be specified 1907using the syntax 1908@code{[:}@var{class}@code{:]}, where @var{class} is one of the 1909following classes defined in the @sc{posix} standard: 1910@example 1911alnum alpha ascii blank cntrl digit graph lower 1912print punct space upper word xdigit 1913@end example 1914@noindent 1915A character class matches any character belonging to that class. 1916The @code{word} character class matches letters, digits, and the character 1917@samp{_}. 1918 1919Within @samp{[} and @samp{]}, an @var{equivalence class} can be 1920specified using the syntax @code{[=}@var{c}@code{=]}, which 1921matches all characters with the same collation weight (as defined 1922by the current locale) as the character @var{c}. 1923 1924Within @samp{[} and @samp{]}, the syntax @code{[.}@var{symbol}@code{.]} 1925matches the collating symbol @var{symbol}. 1926@end table 1927 1928If the @code{extglob} shell option is enabled using the @code{shopt} 1929builtin, several extended pattern matching operators are recognized. 1930In the following description, a @var{pattern-list} is a list of one 1931or more patterns separated by a @samp{|}. 1932Composite patterns may be formed using one or more of the following 1933sub-patterns: 1934 1935@table @code 1936@item ?(@var{pattern-list}) 1937Matches zero or one occurrence of the given patterns. 1938 1939@item *(@var{pattern-list}) 1940Matches zero or more occurrences of the given patterns. 1941 1942@item +(@var{pattern-list}) 1943Matches one or more occurrences of the given patterns. 1944 1945@item @@(@var{pattern-list}) 1946Matches one of the given patterns. 1947 1948@item !(@var{pattern-list}) 1949Matches anything except one of the given patterns. 1950@end table 1951 1952@node Quote Removal 1953@subsection Quote Removal 1954 1955After the preceding expansions, all unquoted occurrences of the 1956characters @samp{\}, @samp{'}, and @samp{"} that did not 1957result from one of the above expansions are removed. 1958 1959@node Redirections 1960@section Redirections 1961@cindex redirection 1962 1963Before a command is executed, its input and output 1964may be @var{redirected} 1965using a special notation interpreted by the shell. 1966Redirection may also be used to open and close files for the 1967current shell execution environment. The following redirection 1968operators may precede or appear anywhere within a 1969simple command or may follow a command. 1970Redirections are processed in the order they appear, from 1971left to right. 1972 1973In the following descriptions, if the file descriptor number is 1974omitted, and the first character of the redirection operator is 1975@samp{<}, the redirection refers to the standard input (file 1976descriptor 0). If the first character of the redirection operator 1977is @samp{>}, the redirection refers to the standard output (file 1978descriptor 1). 1979 1980The word following the redirection operator in the following 1981descriptions, unless otherwise noted, is subjected to brace expansion, 1982tilde expansion, parameter expansion, command substitution, arithmetic 1983expansion, quote removal, filename expansion, and word splitting. 1984If it expands to more than one word, Bash reports an error. 1985 1986Note that the order of redirections is significant. For example, 1987the command 1988@example 1989ls > @var{dirlist} 2>&1 1990@end example 1991@noindent 1992directs both standard output (file descriptor 1) and standard error 1993(file descriptor 2) to the file @var{dirlist}, while the command 1994@example 1995ls 2>&1 > @var{dirlist} 1996@end example 1997@noindent 1998directs only the standard output to file @var{dirlist}, 1999because the standard error was duplicated as standard output 2000before the standard output was redirected to @var{dirlist}. 2001 2002Bash handles several filenames specially when they are used in 2003redirections, as described in the following table: 2004 2005@table @code 2006@item /dev/fd/@var{fd} 2007If @var{fd} is a valid integer, file descriptor @var{fd} is duplicated. 2008 2009@item /dev/stdin 2010File descriptor 0 is duplicated. 2011 2012@item /dev/stdout 2013File descriptor 1 is duplicated. 2014 2015@item /dev/stderr 2016File descriptor 2 is duplicated. 2017 2018@item /dev/tcp/@var{host}/@var{port} 2019If @var{host} is a valid hostname or Internet address, and @var{port} 2020is an integer port number or service name, Bash attempts to open a TCP 2021connection to the corresponding socket. 2022 2023@item /dev/udp/@var{host}/@var{port} 2024If @var{host} is a valid hostname or Internet address, and @var{port} 2025is an integer port number or service name, Bash attempts to open a UDP 2026connection to the corresponding socket. 2027 2028@end table 2029 2030A failure to open or create a file causes the redirection to fail. 2031 2032Redirections using file descriptors greater than 9 should be used with 2033care, as they may conflict with file descriptors the shell uses 2034internally. 2035 2036@subsection Redirecting Input 2037Redirection of input causes the file whose name results from 2038the expansion of @var{word} 2039to be opened for reading on file descriptor @code{n}, 2040or the standard input (file descriptor 0) if @code{n} 2041is not specified. 2042 2043The general format for redirecting input is: 2044@example 2045[@var{n}]<@var{word} 2046@end example 2047 2048@subsection Redirecting Output 2049Redirection of output causes the file whose name results from 2050the expansion of @var{word} 2051to be opened for writing on file descriptor @var{n}, 2052or the standard output (file descriptor 1) if @var{n} 2053is not specified. If the file does not exist it is created; 2054if it does exist it is truncated to zero size. 2055 2056The general format for redirecting output is: 2057@example 2058[@var{n}]>[|]@var{word} 2059@end example 2060 2061If the redirection operator is @samp{>}, and the @code{noclobber} 2062option to the @code{set} builtin has been enabled, the redirection 2063will fail if the file whose name results from the expansion of 2064@var{word} exists and is a regular file. 2065If the redirection operator is @samp{>|}, or the redirection operator is 2066@samp{>} and the @code{noclobber} option is not enabled, the redirection 2067is attempted even if the file named by @var{word} exists. 2068 2069@subsection Appending Redirected Output 2070Redirection of output in this fashion 2071causes the file whose name results from 2072the expansion of @var{word} 2073to be opened for appending on file descriptor @var{n}, 2074or the standard output (file descriptor 1) if @var{n} 2075is not specified. If the file does not exist it is created. 2076 2077The general format for appending output is: 2078@example 2079[@var{n}]>>@var{word} 2080@end example 2081 2082@subsection Redirecting Standard Output and Standard Error 2083Bash allows both the 2084standard output (file descriptor 1) and 2085the standard error output (file descriptor 2) 2086to be redirected to the file whose name is the 2087expansion of @var{word} with this construct. 2088 2089There are two formats for redirecting standard output and 2090standard error: 2091@example 2092&>@var{word} 2093@end example 2094@noindent 2095and 2096@example 2097>&@var{word} 2098@end example 2099@noindent 2100Of the two forms, the first is preferred. 2101This is semantically equivalent to 2102@example 2103>@var{word} 2>&1 2104@end example 2105 2106@subsection Here Documents 2107This type of redirection instructs the shell to read input from the 2108current source until a line containing only @var{word} 2109(with no trailing blanks) is seen. All of 2110the lines read up to that point are then used as the standard 2111input for a command. 2112 2113The format of here-documents is: 2114@example 2115<<[@minus{}]@var{word} 2116 @var{here-document} 2117@var{delimiter} 2118@end example 2119 2120No parameter expansion, command substitution, arithmetic expansion, 2121or filename expansion is performed on 2122@var{word}. If any characters in @var{word} are quoted, the 2123@var{delimiter} is the result of quote removal on @var{word}, 2124and the lines in the here-document are not expanded. 2125If @var{word} is unquoted, 2126all lines of the here-document are subjected to parameter expansion, 2127command substitution, and arithmetic expansion. In the latter 2128case, the character sequence @code{\newline} is ignored, and @samp{\} 2129must be used to quote the characters 2130@samp{\}, @samp{$}, and @samp{`}. 2131 2132If the redirection operator is @samp{<<-}, 2133then all leading tab characters are stripped from input lines and the 2134line containing @var{delimiter}. 2135This allows here-documents within shell scripts to be indented in a 2136natural fashion. 2137 2138@subsection Here Strings 2139A variant of here documents, the format is: 2140@example 2141<<< @var{word} 2142@end example 2143 2144The @var{word} is expanded and supplied to the command on its standard 2145input. 2146 2147@subsection Duplicating File Descriptors 2148The redirection operator 2149@example 2150[@var{n}]<&@var{word} 2151@end example 2152@noindent 2153is used to duplicate input file descriptors. 2154If @var{word} 2155expands to one or more digits, the file descriptor denoted by @var{n} 2156is made to be a copy of that file descriptor. 2157If the digits in @var{word} do not specify a file descriptor open for 2158input, a redirection error occurs. 2159If @var{word} 2160evaluates to @samp{-}, file descriptor @var{n} is closed. If 2161@var{n} is not specified, the standard input (file descriptor 0) is used. 2162 2163The operator 2164@example 2165[@var{n}]>&@var{word} 2166@end example 2167@noindent 2168is used similarly to duplicate output file descriptors. If 2169@var{n} is not specified, the standard output (file descriptor 1) is used. 2170If the digits in @var{word} do not specify a file descriptor open for 2171output, a redirection error occurs. 2172As a special case, if @var{n} is omitted, and @var{word} does not 2173expand to one or more digits, the standard output and standard 2174error are redirected as described previously. 2175 2176@subsection Moving File Descriptors 2177The redirection operator 2178@example 2179[@var{n}]<&@var{digit}- 2180@end example 2181@noindent 2182moves the file descriptor @var{digit} to file descriptor @var{n}, 2183or the standard input (file descriptor 0) if @var{n} is not specified. 2184@var{digit} is closed after being duplicated to @var{n}. 2185 2186Similarly, the redirection operator 2187@example 2188[@var{n}]>&@var{digit}- 2189@end example 2190@noindent 2191moves the file descriptor @var{digit} to file descriptor @var{n}, 2192or the standard output (file descriptor 1) if @var{n} is not specified. 2193 2194@subsection Opening File Descriptors for Reading and Writing 2195The redirection operator 2196@example 2197[@var{n}]<>@var{word} 2198@end example 2199@noindent 2200causes the file whose name is the expansion of @var{word} 2201to be opened for both reading and writing on file descriptor 2202@var{n}, or on file descriptor 0 if @var{n} 2203is not specified. If the file does not exist, it is created. 2204 2205@node Executing Commands 2206@section Executing Commands 2207 2208@menu 2209* Simple Command Expansion:: How Bash expands simple commands before 2210 executing them. 2211* Command Search and Execution:: How Bash finds commands and runs them. 2212* Command Execution Environment:: The environment in which Bash 2213 executes commands that are not 2214 shell builtins. 2215* Environment:: The environment given to a command. 2216* Exit Status:: The status returned by commands and how Bash 2217 interprets it. 2218* Signals:: What happens when Bash or a command it runs 2219 receives a signal. 2220@end menu 2221 2222@node Simple Command Expansion 2223@subsection Simple Command Expansion 2224@cindex command expansion 2225 2226When a simple command is executed, the shell performs the following 2227expansions, assignments, and redirections, from left to right. 2228 2229@enumerate 2230@item 2231The words that the parser has marked as variable assignments (those 2232preceding the command name) and redirections are saved for later 2233processing. 2234 2235@item 2236The words that are not variable assignments or redirections are 2237expanded (@pxref{Shell Expansions}). 2238If any words remain after expansion, the first word 2239is taken to be the name of the command and the remaining words are 2240the arguments. 2241 2242@item 2243Redirections are performed as described above (@pxref{Redirections}). 2244 2245@item 2246The text after the @samp{=} in each variable assignment undergoes tilde 2247expansion, parameter expansion, command substitution, arithmetic expansion, 2248and quote removal before being assigned to the variable. 2249@end enumerate 2250 2251If no command name results, the variable assignments affect the current 2252shell environment. Otherwise, the variables are added to the environment 2253of the executed command and do not affect the current shell environment. 2254If any of the assignments attempts to assign a value to a readonly variable, 2255an error occurs, and the command exits with a non-zero status. 2256 2257If no command name results, redirections are performed, but do not 2258affect the current shell environment. A redirection error causes the 2259command to exit with a non-zero status. 2260 2261If there is a command name left after expansion, execution proceeds as 2262described below. Otherwise, the command exits. If one of the expansions 2263contained a command substitution, the exit status of the command is 2264the exit status of the last command substitution performed. If there 2265were no command substitutions, the command exits with a status of zero. 2266 2267@node Command Search and Execution 2268@subsection Command Search and Execution 2269@cindex command execution 2270@cindex command search 2271 2272After a command has been split into words, if it results in a 2273simple command and an optional list of arguments, the following 2274actions are taken. 2275 2276@enumerate 2277@item 2278If the command name contains no slashes, the shell attempts to 2279locate it. If there exists a shell function by that name, that 2280function is invoked as described in @ref{Shell Functions}. 2281 2282@item 2283If the name does not match a function, the shell searches for 2284it in the list of shell builtins. If a match is found, that 2285builtin is invoked. 2286 2287@item 2288If the name is neither a shell function nor a builtin, 2289and contains no slashes, Bash searches each element of 2290@env{$PATH} for a directory containing an executable file 2291by that name. Bash uses a hash table to remember the full 2292pathnames of executable files to avoid multiple @env{PATH} searches 2293(see the description of @code{hash} in @ref{Bourne Shell Builtins}). 2294A full search of the directories in @env{$PATH} 2295is performed only if the command is not found in the hash table. 2296If the search is unsuccessful, the shell prints an error 2297message and returns an exit status of 127. 2298 2299@item 2300If the search is successful, or if the command name contains 2301one or more slashes, the shell executes the named program in 2302a separate execution environment. 2303Argument 0 is set to the name given, and the remaining arguments 2304to the command are set to the arguments supplied, if any. 2305 2306@item 2307If this execution fails because the file is not in executable 2308format, and the file is not a directory, it is assumed to be a 2309@var{shell script} and the shell executes it as described in 2310@ref{Shell Scripts}. 2311 2312@item 2313If the command was not begun asynchronously, the shell waits for 2314the command to complete and collects its exit status. 2315 2316@end enumerate 2317 2318@node Command Execution Environment 2319@subsection Command Execution Environment 2320@cindex execution environment 2321 2322The shell has an @var{execution environment}, which consists of the 2323following: 2324 2325@itemize @bullet 2326@item 2327open files inherited by the shell at invocation, as modified by 2328redirections supplied to the @code{exec} builtin 2329 2330@item 2331the current working directory as set by @code{cd}, @code{pushd}, or 2332@code{popd}, or inherited by the shell at invocation 2333 2334@item 2335the file creation mode mask as set by @code{umask} or inherited from 2336the shell's parent 2337 2338@item 2339current traps set by @code{trap} 2340 2341@item 2342shell parameters that are set by variable assignment or with @code{set} 2343or inherited from the shell's parent in the environment 2344 2345@item 2346shell functions defined during execution or inherited from the shell's 2347parent in the environment 2348 2349@item 2350options enabled at invocation (either by default or with command-line 2351arguments) or by @code{set} 2352 2353@item 2354options enabled by @code{shopt} 2355 2356@item 2357shell aliases defined with @code{alias} (@pxref{Aliases}) 2358 2359@item 2360various process @sc{id}s, including those of background jobs 2361(@pxref{Lists}), the value of @code{$$}, and the value of 2362@env{$PPID} 2363 2364@end itemize 2365 2366When a simple command other than a builtin or shell function 2367is to be executed, it 2368is invoked in a separate execution environment that consists of 2369the following. Unless otherwise noted, the values are inherited 2370from the shell. 2371 2372@itemize @bullet 2373@item 2374the shell's open files, plus any modifications and additions specified 2375by redirections to the command 2376 2377@item 2378the current working directory 2379 2380@item 2381the file creation mode mask 2382 2383@item 2384shell variables and functions marked for export, along with variables 2385exported for the command, passed in the environment (@pxref{Environment}) 2386 2387@item 2388traps caught by the shell are reset to the values inherited from the 2389shell's parent, and traps ignored by the shell are ignored 2390 2391@end itemize 2392 2393A command invoked in this separate environment cannot affect the 2394shell's execution environment. 2395 2396Command substitution, commands grouped with parentheses, 2397and asynchronous commands are invoked in a 2398subshell environment that is a duplicate of the shell environment, 2399except that traps caught by the shell are reset to the values 2400that the shell inherited from its parent at invocation. Builtin 2401commands that are invoked as part of a pipeline are also executed 2402in a subshell environment. Changes made to the subshell environment 2403cannot affect the shell's execution environment. 2404 2405If a command is followed by a @samp{&} and job control is not active, the 2406default standard input for the command is the empty file @file{/dev/null}. 2407Otherwise, the invoked command inherits the file descriptors of the calling 2408shell as modified by redirections. 2409 2410@node Environment 2411@subsection Environment 2412@cindex environment 2413 2414When a program is invoked it is given an array of strings 2415called the @var{environment}. 2416This is a list of name-value pairs, of the form @code{name=value}. 2417 2418Bash provides several ways to manipulate the environment. 2419On invocation, the shell scans its own environment and 2420creates a parameter for each name found, automatically marking 2421it for @var{export} 2422to child processes. Executed commands inherit the environment. 2423The @code{export} and @samp{declare -x} 2424commands allow parameters and functions to be added to and 2425deleted from the environment. If the value of a parameter 2426in the environment is modified, the new value becomes part 2427of the environment, replacing the old. The environment 2428inherited by any executed command consists of the shell's 2429initial environment, whose values may be modified in the shell, 2430less any pairs removed by the @code{unset} and @samp{export -n} 2431commands, plus any additions via the @code{export} and 2432@samp{declare -x} commands. 2433 2434The environment for any simple command 2435or function may be augmented temporarily by prefixing it with 2436parameter assignments, as described in @ref{Shell Parameters}. 2437These assignment statements affect only the environment seen 2438by that command. 2439 2440If the @option{-k} option is set (@pxref{The Set Builtin}), then all 2441parameter assignments are placed in the environment for a command, 2442not just those that precede the command name. 2443 2444When Bash invokes an external command, the variable @samp{$_} 2445is set to the full path name of the command and passed to that 2446command in its environment. 2447 2448@node Exit Status 2449@subsection Exit Status 2450@cindex exit status 2451 2452For the shell's purposes, a command which exits with a 2453zero exit status has succeeded. 2454A non-zero exit status indicates failure. 2455This seemingly counter-intuitive scheme is used so there 2456is one well-defined way to indicate success and a variety of 2457ways to indicate various failure modes. 2458When a command terminates on a fatal signal whose number is @var{N}, 2459Bash uses the value 128+@var{N} as the exit status. 2460 2461If a command is not found, the child process created to 2462execute it returns a status of 127. If a command is found 2463but is not executable, the return status is 126. 2464 2465If a command fails because of an error during expansion or redirection, 2466the exit status is greater than zero. 2467 2468The exit status is used by the Bash conditional commands 2469(@pxref{Conditional Constructs}) and some of the list 2470constructs (@pxref{Lists}). 2471 2472All of the Bash builtins return an exit status of zero if they succeed 2473and a non-zero status on failure, so they may be used by the 2474conditional and list constructs. 2475All builtins return an exit status of 2 to indicate incorrect usage. 2476 2477@node Signals 2478@subsection Signals 2479@cindex signal handling 2480 2481When Bash is interactive, in the absence of any traps, it ignores 2482@code{SIGTERM} (so that @samp{kill 0} does not kill an interactive shell), 2483and @code{SIGINT} 2484is caught and handled (so that the @code{wait} builtin is interruptible). 2485When Bash receives a @code{SIGINT}, it breaks out of any executing loops. 2486In all cases, Bash ignores @code{SIGQUIT}. 2487If job control is in effect (@pxref{Job Control}), Bash 2488ignores @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}. 2489 2490Non-builtin commands started by Bash have signal handlers set to the 2491values inherited by the shell from its parent. 2492When job control is not in effect, asynchronous commands 2493ignore @code{SIGINT} and @code{SIGQUIT} in addition to these inherited 2494handlers. 2495Commands run as a result of 2496command substitution ignore the keyboard-generated job control signals 2497@code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}. 2498 2499The shell exits by default upon receipt of a @code{SIGHUP}. 2500Before exiting, an interactive shell resends the @code{SIGHUP} to 2501all jobs, running or stopped. 2502Stopped jobs are sent @code{SIGCONT} to ensure that they receive 2503the @code{SIGHUP}. 2504To prevent the shell from sending the @code{SIGHUP} signal to a 2505particular job, it should be removed 2506from the jobs table with the @code{disown} 2507builtin (@pxref{Job Control Builtins}) or marked 2508to not receive @code{SIGHUP} using @code{disown -h}. 2509 2510If the @code{huponexit} shell option has been set with @code{shopt} 2511(@pxref{Bash Builtins}), Bash sends a @code{SIGHUP} to all jobs when 2512an interactive login shell exits. 2513 2514If Bash is waiting for a command to complete and receives a signal 2515for which a trap has been set, the trap will not be executed until 2516the command completes. 2517When Bash is waiting for an asynchronous 2518command via the @code{wait} builtin, the reception of a signal for 2519which a trap has been set will cause the @code{wait} builtin to return 2520immediately with an exit status greater than 128, immediately after 2521which the trap is executed. 2522 2523@node Shell Scripts 2524@section Shell Scripts 2525@cindex shell script 2526 2527A shell script is a text file containing shell commands. When such 2528a file is used as the first non-option argument when invoking Bash, 2529and neither the @option{-c} nor @option{-s} option is supplied 2530(@pxref{Invoking Bash}), 2531Bash reads and executes commands from the file, then exits. This 2532mode of operation creates a non-interactive shell. The shell first 2533searches for the file in the current directory, and looks in the 2534directories in @env{$PATH} if not found there. 2535 2536When Bash runs 2537a shell script, it sets the special parameter @code{0} to the name 2538of the file, rather than the name of the shell, and the positional 2539parameters are set to the remaining arguments, if any are given. 2540If no additional arguments are supplied, the positional parameters 2541are unset. 2542 2543A shell script may be made executable by using the @code{chmod} command 2544to turn on the execute bit. When Bash finds such a file while 2545searching the @env{$PATH} for a command, it spawns a subshell to 2546execute it. In other words, executing 2547@example 2548filename @var{arguments} 2549@end example 2550@noindent 2551is equivalent to executing 2552@example 2553bash filename @var{arguments} 2554@end example 2555 2556@noindent 2557if @code{filename} is an executable shell script. 2558This subshell reinitializes itself, so that the effect is as if a 2559new shell had been invoked to interpret the script, with the 2560exception that the locations of commands remembered by the parent 2561(see the description of @code{hash} in @ref{Bourne Shell Builtins}) 2562are retained by the child. 2563 2564Most versions of Unix make this a part of the operating system's command 2565execution mechanism. If the first line of a script begins with 2566the two characters @samp{#!}, the remainder of the line specifies 2567an interpreter for the program. 2568Thus, you can specify Bash, @code{awk}, Perl, or some other 2569interpreter and write the rest of the script file in that language. 2570 2571The arguments to the interpreter 2572consist of a single optional argument following the interpreter 2573name on the first line of the script file, followed by the name of 2574the script file, followed by the rest of the arguments. Bash 2575will perform this action on operating systems that do not handle it 2576themselves. Note that some older versions of Unix limit the interpreter 2577name and argument to a maximum of 32 characters. 2578 2579Bash scripts often begin with @code{#! /bin/bash} (assuming that 2580Bash has been installed in @file{/bin}), since this ensures that 2581Bash will be used to interpret the script, even if it is executed 2582under another shell. 2583 2584@node Shell Builtin Commands 2585@chapter Shell Builtin Commands 2586 2587@menu 2588* Bourne Shell Builtins:: Builtin commands inherited from the Bourne 2589 Shell. 2590* Bash Builtins:: Table of builtins specific to Bash. 2591* The Set Builtin:: This builtin is so overloaded it 2592 deserves its own section. 2593* Special Builtins:: Builtin commands classified specially by 2594 POSIX. 2595@end menu 2596 2597Builtin commands are contained within the shell itself. 2598When the name of a builtin command is used as the first word of 2599a simple command (@pxref{Simple Commands}), the shell executes 2600the command directly, without invoking another program. 2601Builtin commands are necessary to implement functionality impossible 2602or inconvenient to obtain with separate utilities. 2603 2604This section briefly describes the builtins which Bash inherits from 2605the Bourne Shell, as well as the builtin commands which are unique 2606to or have been extended in Bash. 2607 2608Several builtin commands are described in other chapters: builtin 2609commands which provide the Bash interface to the job control 2610facilities (@pxref{Job Control Builtins}), the directory stack 2611(@pxref{Directory Stack Builtins}), the command history 2612(@pxref{Bash History Builtins}), and the programmable completion 2613facilities (@pxref{Programmable Completion Builtins}). 2614 2615Many of the builtins have been extended by @sc{posix} or Bash. 2616 2617Unless otherwise noted, each builtin command documented as accepting 2618options preceded by @samp{-} accepts @samp{--} 2619to signify the end of the options. 2620For example, the @code{:}, @code{true}, @code{false}, and @code{test} 2621builtins do not accept options. 2622 2623@node Bourne Shell Builtins 2624@section Bourne Shell Builtins 2625 2626The following shell builtin commands are inherited from the Bourne Shell. 2627These commands are implemented as specified by the @sc{posix} standard. 2628 2629@table @code 2630@item : @r{(a colon)} 2631@btindex : 2632@example 2633: [@var{arguments}] 2634@end example 2635Do nothing beyond expanding @var{arguments} and performing redirections. 2636The return status is zero. 2637 2638@item . @r{(a period)} 2639@btindex . 2640@example 2641. @var{filename} [@var{arguments}] 2642@end example 2643Read and execute commands from the @var{filename} argument in the 2644current shell context. If @var{filename} does not contain a slash, 2645the @env{PATH} variable is used to find @var{filename}. 2646When Bash is not in @sc{posix} mode, the current directory is searched 2647if @var{filename} is not found in @env{$PATH}. 2648If any @var{arguments} are supplied, they become the positional 2649parameters when @var{filename} is executed. Otherwise the positional 2650parameters are unchanged. 2651The return status is the exit status of the last command executed, or 2652zero if no commands are executed. If @var{filename} is not found, or 2653cannot be read, the return status is non-zero. 2654This builtin is equivalent to @code{source}. 2655 2656@item break 2657@btindex break 2658@example 2659break [@var{n}] 2660@end example 2661Exit from a @code{for}, @code{while}, @code{until}, or @code{select} loop. 2662If @var{n} is supplied, the @var{n}th enclosing loop is exited. 2663@var{n} must be greater than or equal to 1. 2664The return status is zero unless @var{n} is not greater than or equal to 1. 2665 2666@item cd 2667@btindex cd 2668@example 2669cd [-L|-P] [@var{directory}] 2670@end example 2671Change the current working directory to @var{directory}. 2672If @var{directory} is not given, the value of the @env{HOME} shell 2673variable is used. 2674If the shell variable @env{CDPATH} exists, it is used as a search path. 2675If @var{directory} begins with a slash, @env{CDPATH} is not used. 2676 2677The @option{-P} option means to not follow symbolic links; symbolic 2678links are followed by default or with the @option{-L} option. 2679If @var{directory} is @samp{-}, it is equivalent to @env{$OLDPWD}. 2680 2681If a non-empty directory name from @env{CDPATH} is used, or if 2682@samp{-} is the first argument, and the directory change is 2683successful, the absolute pathname of the new working directory is 2684written to the standard output. 2685 2686The return status is zero if the directory is successfully changed, 2687non-zero otherwise. 2688 2689@item continue 2690@btindex continue 2691@example 2692continue [@var{n}] 2693@end example 2694Resume the next iteration of an enclosing @code{for}, @code{while}, 2695@code{until}, or @code{select} loop. 2696If @var{n} is supplied, the execution of the @var{n}th enclosing loop 2697is resumed. 2698@var{n} must be greater than or equal to 1. 2699The return status is zero unless @var{n} is not greater than or equal to 1. 2700 2701@item eval 2702@btindex eval 2703@example 2704eval [@var{arguments}] 2705@end example 2706The arguments are concatenated together into a single command, which is 2707then read and executed, and its exit status returned as the exit status 2708of @code{eval}. 2709If there are no arguments or only empty arguments, the return status is 2710zero. 2711 2712@item exec 2713@btindex exec 2714@example 2715exec [-cl] [-a @var{name}] [@var{command} [@var{arguments}]] 2716@end example 2717If @var{command} 2718is supplied, it replaces the shell without creating a new process. 2719If the @option{-l} option is supplied, the shell places a dash at the 2720beginning of the zeroth arg passed to @var{command}. 2721This is what the @code{login} program does. 2722The @option{-c} option causes @var{command} to be executed with an empty 2723environment. 2724If @option{-a} is supplied, the shell passes @var{name} as the zeroth 2725argument to @var{command}. 2726If no @var{command} is specified, redirections may be used to affect 2727the current shell environment. If there are no redirection errors, the 2728return status is zero; otherwise the return status is non-zero. 2729 2730@item exit 2731@btindex exit 2732@example 2733exit [@var{n}] 2734@end example 2735Exit the shell, returning a status of @var{n} to the shell's parent. 2736If @var{n} is omitted, the exit status is that of the last command executed. 2737Any trap on @code{EXIT} is executed before the shell terminates. 2738 2739@item export 2740@btindex export 2741@example 2742export [-fn] [-p] [@var{name}[=@var{value}]] 2743@end example 2744Mark each @var{name} to be passed to child processes 2745in the environment. If the @option{-f} option is supplied, the @var{name}s 2746refer to shell functions; otherwise the names refer to shell variables. 2747The @option{-n} option means to no longer mark each @var{name} for export. 2748If no @var{names} are supplied, or if the @option{-p} option is given, a 2749list of exported names is displayed. 2750The @option{-p} option displays output in a form that may be reused as input. 2751If a variable name is followed by =@var{value}, the value of 2752the variable is set to @var{value}. 2753 2754The return status is zero unless an invalid option is supplied, one of 2755the names is not a valid shell variable name, or @option{-f} is supplied 2756with a name that is not a shell function. 2757 2758@item getopts 2759@btindex getopts 2760@example 2761getopts @var{optstring} @var{name} [@var{args}] 2762@end example 2763@code{getopts} is used by shell scripts to parse positional parameters. 2764@var{optstring} contains the option characters to be recognized; if a 2765character is followed by a colon, the option is expected to have an 2766argument, which should be separated from it by white space. 2767The colon (@samp{:}) and question mark (@samp{?}) may not be 2768used as option characters. 2769Each time it is invoked, @code{getopts} 2770places the next option in the shell variable @var{name}, initializing 2771@var{name} if it does not exist, 2772and the index of the next argument to be processed into the 2773variable @env{OPTIND}. 2774@env{OPTIND} is initialized to 1 each time the shell or a shell script 2775is invoked. 2776When an option requires an argument, 2777@code{getopts} places that argument into the variable @env{OPTARG}. 2778The shell does not reset @env{OPTIND} automatically; it must be manually 2779reset between multiple calls to @code{getopts} within the same shell 2780invocation if a new set of parameters is to be used. 2781 2782When the end of options is encountered, @code{getopts} exits with a 2783return value greater than zero. 2784@env{OPTIND} is set to the index of the first non-option argument, 2785and @code{name} is set to @samp{?}. 2786 2787@code{getopts} 2788normally parses the positional parameters, but if more arguments are 2789given in @var{args}, @code{getopts} parses those instead. 2790 2791@code{getopts} can report errors in two ways. If the first character of 2792@var{optstring} is a colon, @var{silent} 2793error reporting is used. In normal operation diagnostic messages 2794are printed when invalid options or missing option arguments are 2795encountered. 2796If the variable @env{OPTERR} 2797is set to 0, no error messages will be displayed, even if the first 2798character of @code{optstring} is not a colon. 2799 2800If an invalid option is seen, 2801@code{getopts} places @samp{?} into @var{name} and, if not silent, 2802prints an error message and unsets @env{OPTARG}. 2803If @code{getopts} is silent, the option character found is placed in 2804@env{OPTARG} and no diagnostic message is printed. 2805 2806If a required argument is not found, and @code{getopts} 2807is not silent, a question mark (@samp{?}) is placed in @var{name}, 2808@code{OPTARG} is unset, and a diagnostic message is printed. 2809If @code{getopts} is silent, then a colon (@samp{:}) is placed in 2810@var{name} and @env{OPTARG} is set to the option character found. 2811 2812@item hash 2813@btindex hash 2814@example 2815hash [-r] [-p @var{filename}] [-dt] [@var{name}] 2816@end example 2817Remember the full pathnames of commands specified as @var{name} arguments, 2818so they need not be searched for on subsequent invocations. 2819The commands are found by searching through the directories listed in 2820@env{$PATH}. 2821The @option{-p} option inhibits the path search, and @var{filename} is 2822used as the location of @var{name}. 2823The @option{-r} option causes the shell to forget all remembered locations. 2824The @option{-d} option causes the shell to forget the remembered location 2825of each @var{name}. 2826If the @option{-t} option is supplied, the full pathname to which each 2827@var{name} corresponds is printed. If multiple @var{name} arguments are 2828supplied with @option{-t} the @var{name} is printed before the hashed 2829full pathname. 2830The @option{-l} option causes output to be displayed in a format 2831that may be reused as input. 2832If no arguments are given, or if only @option{-l} is supplied, 2833information about remembered commands is printed. 2834The return status is zero unless a @var{name} is not found or an invalid 2835option is supplied. 2836 2837@item pwd 2838@btindex pwd 2839@example 2840pwd [-LP] 2841@end example 2842Print the absolute pathname of the current working directory. 2843If the @option{-P} option is supplied, the pathname printed will not 2844contain symbolic links. 2845If the @option{-L} option is supplied, the pathname printed may contain 2846symbolic links. 2847The return status is zero unless an error is encountered while 2848determining the name of the current directory or an invalid option 2849is supplied. 2850 2851@item readonly 2852@btindex readonly 2853@example 2854readonly [-apf] [@var{name}[=@var{value}]] @dots{} 2855@end example 2856Mark each @var{name} as readonly. 2857The values of these names may not be changed by subsequent assignment. 2858If the @option{-f} option is supplied, each @var{name} refers to a shell 2859function. 2860The @option{-a} option means each @var{name} refers to an array variable. 2861If no @var{name} arguments are given, or if the @option{-p} 2862option is supplied, a list of all readonly names is printed. 2863The @option{-p} option causes output to be displayed in a format that 2864may be reused as input. 2865If a variable name is followed by =@var{value}, the value of 2866the variable is set to @var{value}. 2867The return status is zero unless an invalid option is supplied, one of 2868the @var{name} arguments is not a valid shell variable or function name, 2869or the @option{-f} option is supplied with a name that is not a shell function. 2870 2871@item return 2872@btindex return 2873@example 2874return [@var{n}] 2875@end example 2876Cause a shell function to exit with the return value @var{n}. 2877If @var{n} is not supplied, the return value is the exit status of the 2878last command executed in the function. 2879This may also be used to terminate execution of a script being executed 2880with the @code{.} (or @code{source}) builtin, returning either @var{n} or 2881the exit status of the last command executed within the script as the exit 2882status of the script. 2883Any command associated with the @code{RETURN} trap is executed 2884before execution resumes after the function or script. 2885The return status is non-zero if @code{return} is used outside a function 2886and not during the execution of a script by @code{.} or @code{source}. 2887 2888@item shift 2889@btindex shift 2890@example 2891shift [@var{n}] 2892@end example 2893Shift the positional parameters to the left by @var{n}. 2894The positional parameters from @var{n}+1 @dots{} @code{$#} are 2895renamed to @code{$1} @dots{} @code{$#}-@var{n}+1. 2896Parameters represented by the numbers @code{$#} to @var{n}+1 are unset. 2897@var{n} must be a non-negative number less than or equal to @code{$#}. 2898If @var{n} is zero or greater than @code{$#}, the positional parameters 2899are not changed. 2900If @var{n} is not supplied, it is assumed to be 1. 2901The return status is zero unless @var{n} is greater than @code{$#} or 2902less than zero, non-zero otherwise. 2903 2904@item test 2905@itemx [ 2906@btindex test 2907@btindex [ 2908Evaluate a conditional expression @var{expr}. 2909Each operator and operand must be a separate argument. 2910Expressions are composed of the primaries described below in 2911@ref{Bash Conditional Expressions}. 2912@code{test} does not accept any options, nor does it accept and ignore 2913an argument of @option{--} as signifying the end of options. 2914 2915When the @code{[} form is used, the last argument to the command must 2916be a @code{]}. 2917 2918Expressions may be combined using the following operators, listed in 2919decreasing order of precedence. 2920 2921@table @code 2922@item ! @var{expr} 2923True if @var{expr} is false. 2924 2925@item ( @var{expr} ) 2926Returns the value of @var{expr}. 2927This may be used to override the normal precedence of operators. 2928 2929@item @var{expr1} -a @var{expr2} 2930True if both @var{expr1} and @var{expr2} are true. 2931 2932@item @var{expr1} -o @var{expr2} 2933True if either @var{expr1} or @var{expr2} is true. 2934@end table 2935 2936The @code{test} and @code{[} builtins evaluate conditional 2937expressions using a set of rules based on the number of arguments. 2938 2939@table @asis 2940@item 0 arguments 2941The expression is false. 2942 2943@item 1 argument 2944The expression is true if and only if the argument is not null. 2945 2946@item 2 arguments 2947If the first argument is @samp{!}, the expression is true if and 2948only if the second argument is null. 2949If the first argument is one of the unary conditional operators 2950(@pxref{Bash Conditional Expressions}), the expression 2951is true if the unary test is true. 2952If the first argument is not a valid unary operator, the expression is 2953false. 2954 2955@item 3 arguments 2956If the second argument is one of the binary conditional 2957operators (@pxref{Bash Conditional Expressions}), the 2958result of the expression is the result of the binary test using the 2959first and third arguments as operands. 2960If the first argument is @samp{!}, the value is the negation of 2961the two-argument test using the second and third arguments. 2962If the first argument is exactly @samp{(} and the third argument is 2963exactly @samp{)}, the result is the one-argument test of the second 2964argument. 2965Otherwise, the expression is false. 2966The @samp{-a} and @samp{-o} operators are considered binary operators 2967in this case. 2968 2969@item 4 arguments 2970If the first argument is @samp{!}, the result is the negation of 2971the three-argument expression composed of the remaining arguments. 2972Otherwise, the expression is parsed and evaluated according to 2973precedence using the rules listed above. 2974 2975@item 5 or more arguments 2976The expression is parsed and evaluated according to precedence 2977using the rules listed above. 2978@end table 2979 2980@item times 2981@btindex times 2982@example 2983times 2984@end example 2985Print out the user and system times used by the shell and its children. 2986The return status is zero. 2987 2988@item trap 2989@btindex trap 2990@example 2991trap [-lp] [@var{arg}] [@var{sigspec} @dots{}] 2992@end example 2993The commands in @var{arg} are to be read and executed when the 2994shell receives signal @var{sigspec}. If @var{arg} is absent (and 2995there is a single @var{sigspec}) or 2996equal to @samp{-}, each specified signal's disposition is reset 2997to the value it had when the shell was started. 2998If @var{arg} is the null string, then the signal specified by 2999each @var{sigspec} is ignored by the shell and commands it invokes. 3000If @var{arg} is not present and @option{-p} has been supplied, 3001the shell displays the trap commands associated with each @var{sigspec}. 3002If no arguments are supplied, or 3003only @option{-p} is given, @code{trap} prints the list of commands 3004associated with each signal number in a form that may be reused as 3005shell input. 3006The @option{-l} option causes the shell to print a list of signal names 3007and their corresponding numbers. 3008Each @var{sigspec} is either a signal name or a signal number. 3009Signal names are case insensitive and the @code{SIG} prefix is optional. 3010If a @var{sigspec} 3011is @code{0} or @code{EXIT}, @var{arg} is executed when the shell exits. 3012If a @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed 3013before every simple command, @code{for} command, @code{case} command, 3014@code{select} command, every arithmetic @code{for} command, and before 3015the first command executes in a shell function. 3016Refer to the description of the @code{extglob} option to the 3017@code{shopt} builtin (@pxref{Bash Builtins}) for details of its 3018effect on the @code{DEBUG} trap. 3019If a @var{sigspec} is @code{ERR}, the command @var{arg} 3020is executed whenever a simple command has a non-zero exit status, 3021subject to the following conditions. 3022The @code{ERR} trap is not executed if the failed command is part of the 3023command list immediately following an @code{until} or @code{while} keyword, 3024part of the test in an @code{if} statement, 3025part of a @code{&&} or @code{||} list, or if the command's return 3026status is being inverted using @code{!}. 3027These are the same conditions obeyed by the @code{errexit} option. 3028If a @var{sigspec} is @code{RETURN}, the command @var{arg} is executed 3029each time a shell function or a script executed with the @code{.} or 3030@code{source} builtins finishes executing. 3031 3032Signals ignored upon entry to the shell cannot be trapped or reset. 3033Trapped signals that are not being ignored are reset to their original 3034values in a child process when it is created. 3035 3036The return status is zero unless a @var{sigspec} does not specify a 3037valid signal. 3038 3039@item umask 3040@btindex umask 3041@example 3042umask [-p] [-S] [@var{mode}] 3043@end example 3044Set the shell process's file creation mask to @var{mode}. If 3045@var{mode} begins with a digit, it is interpreted as an octal number; 3046if not, it is interpreted as a symbolic mode mask similar 3047to that accepted by the @code{chmod} command. If @var{mode} is 3048omitted, the current value of the mask is printed. If the @option{-S} 3049option is supplied without a @var{mode} argument, the mask is printed 3050in a symbolic format. 3051If the @option{-p} option is supplied, and @var{mode} 3052is omitted, the output is in a form that may be reused as input. 3053The return status is zero if the mode is successfully changed or if 3054no @var{mode} argument is supplied, and non-zero otherwise. 3055 3056Note that when the mode is interpreted as an octal number, each number 3057of the umask is subtracted from @code{7}. Thus, a umask of @code{022} 3058results in permissions of @code{755}. 3059 3060@item unset 3061@btindex unset 3062@example 3063unset [-fv] [@var{name}] 3064@end example 3065Each variable or function @var{name} is removed. 3066If no options are supplied, or the @option{-v} option is given, each 3067@var{name} refers to a shell variable. 3068If the @option{-f} option is given, the @var{name}s refer to shell 3069functions, and the function definition is removed. 3070Readonly variables and functions may not be unset. 3071The return status is zero unless a @var{name} is readonly. 3072@end table 3073 3074@node Bash Builtins 3075@section Bash Builtin Commands 3076 3077This section describes builtin commands which are unique to 3078or have been extended in Bash. 3079Some of these commands are specified in the @sc{posix} standard. 3080 3081@table @code 3082 3083@item alias 3084@btindex alias 3085@example 3086alias [@code{-p}] [@var{name}[=@var{value}] @dots{}] 3087@end example 3088 3089Without arguments or with the @option{-p} option, @code{alias} prints 3090the list of aliases on the standard output in a form that allows 3091them to be reused as input. 3092If arguments are supplied, an alias is defined for each @var{name} 3093whose @var{value} is given. If no @var{value} is given, the name 3094and value of the alias is printed. 3095Aliases are described in @ref{Aliases}. 3096 3097@item bind 3098@btindex bind 3099@example 3100bind [-m @var{keymap}] [-lpsvPSV] 3101bind [-m @var{keymap}] [-q @var{function}] [-u @var{function}] [-r @var{keyseq}] 3102bind [-m @var{keymap}] -f @var{filename} 3103bind [-m @var{keymap}] -x @var{keyseq:shell-command} 3104bind [-m @var{keymap}] @var{keyseq:function-name} 3105bind @var{readline-command} 3106@end example 3107 3108Display current Readline (@pxref{Command Line Editing}) 3109key and function bindings, 3110bind a key sequence to a Readline function or macro, 3111or set a Readline variable. 3112Each non-option argument is a command as it would appear in a 3113a Readline initialization file (@pxref{Readline Init File}), 3114but each binding or command must be passed as a separate argument; e.g., 3115@samp{"\C-x\C-r":re-read-init-file}. 3116Options, if supplied, have the following meanings: 3117 3118@table @code 3119@item -m @var{keymap} 3120Use @var{keymap} as the keymap to be affected by 3121the subsequent bindings. Acceptable @var{keymap} 3122names are 3123@code{emacs}, 3124@code{emacs-standard}, 3125@code{emacs-meta}, 3126@code{emacs-ctlx}, 3127@code{vi}, 3128@code{vi-move}, 3129@code{vi-command}, and 3130@code{vi-insert}. 3131@code{vi} is equivalent to @code{vi-command}; 3132@code{emacs} is equivalent to @code{emacs-standard}. 3133 3134@item -l 3135List the names of all Readline functions. 3136 3137@item -p 3138Display Readline function names and bindings in such a way that they 3139can be used as input or in a Readline initialization file. 3140 3141@item -P 3142List current Readline function names and bindings. 3143 3144@item -v 3145Display Readline variable names and values in such a way that they 3146can be used as input or in a Readline initialization file. 3147 3148@item -V 3149List current Readline variable names and values. 3150 3151@item -s 3152Display Readline key sequences bound to macros and the strings they output 3153in such a way that they can be used as input or in a Readline 3154initialization file. 3155 3156@item -S 3157Display Readline key sequences bound to macros and the strings they output. 3158 3159@item -f @var{filename} 3160Read key bindings from @var{filename}. 3161 3162@item -q @var{function} 3163Query about which keys invoke the named @var{function}. 3164 3165@item -u @var{function} 3166Unbind all keys bound to the named @var{function}. 3167 3168@item -r @var{keyseq} 3169Remove any current binding for @var{keyseq}. 3170 3171@item -x @var{keyseq:shell-command} 3172Cause @var{shell-command} to be executed whenever @var{keyseq} is 3173entered. 3174 3175@end table 3176 3177@noindent 3178The return status is zero unless an invalid option is supplied or an 3179error occurs. 3180 3181@item builtin 3182@btindex builtin 3183@example 3184builtin [@var{shell-builtin} [@var{args}]] 3185@end example 3186Run a shell builtin, passing it @var{args}, and return its exit status. 3187This is useful when defining a shell function with the same 3188name as a shell builtin, retaining the functionality of the builtin within 3189the function. 3190The return status is non-zero if @var{shell-builtin} is not a shell 3191builtin command. 3192 3193@item caller 3194@btindex caller 3195@example 3196caller [@var{expr}] 3197@end example 3198Returns the context of any active subroutine call (a shell function or 3199a script executed with the @code{.} or @code{source} builtins). 3200 3201Without @var{expr}, @code{caller} displays the line number and source 3202filename of the current subroutine call. 3203If a non-negative integer is supplied as @var{expr}, @code{caller} 3204displays the line number, subroutine name, and source file corresponding 3205to that position in the current execution call stack. This extra 3206information may be used, for example, to print a stack trace. The 3207current frame is frame 0. 3208 3209The return value is 0 unless the shell is not executing a subroutine 3210call or @var{expr} does not correspond to a valid position in the 3211call stack. 3212 3213@item command 3214@btindex command 3215@example 3216command [-pVv] @var{command} [@var{arguments} @dots{}] 3217@end example 3218Runs @var{command} with @var{arguments} ignoring any shell function 3219named @var{command}. 3220Only shell builtin commands or commands found by searching the 3221@env{PATH} are executed. 3222If there is a shell function named @code{ls}, running @samp{command ls} 3223within the function will execute the external command @code{ls} 3224instead of calling the function recursively. 3225The @option{-p} option means to use a default value for @env{PATH} 3226that is guaranteed to find all of the standard utilities. 3227The return status in this case is 127 if @var{command} cannot be 3228found or an error occurred, and the exit status of @var{command} 3229otherwise. 3230 3231If either the @option{-V} or @option{-v} option is supplied, a 3232description of @var{command} is printed. The @option{-v} option 3233causes a single word indicating the command or file name used to 3234invoke @var{command} to be displayed; the @option{-V} option produces 3235a more verbose description. In this case, the return status is 3236zero if @var{command} is found, and non-zero if not. 3237 3238@item declare 3239@btindex declare 3240@example 3241declare [-afFirtx] [-p] [@var{name}[=@var{value}] @dots{}] 3242@end example 3243 3244Declare variables and give them attributes. If no @var{name}s 3245are given, then display the values of variables instead. 3246 3247The @option{-p} option will display the attributes and values of each 3248@var{name}. 3249When @option{-p} is used, additional options are ignored. 3250The @option{-F} option inhibits the display of function definitions; 3251only the function name and attributes are printed. 3252If the @code{extdebug} shell option is enabled using @code{shopt} 3253(@pxref{Bash Builtins}), the source file name and line number where 3254the function is defined are displayed as well. 3255@option{-F} implies @option{-f}. 3256The following options can be used to restrict output to variables with 3257the specified attributes or to give variables attributes: 3258 3259@table @code 3260@item -a 3261Each @var{name} is an array variable (@pxref{Arrays}). 3262 3263@item -f 3264Use function names only. 3265 3266@item -i 3267The variable is to be treated as 3268an integer; arithmetic evaluation (@pxref{Shell Arithmetic}) is 3269performed when the variable is assigned a value. 3270 3271@item -r 3272Make @var{name}s readonly. These names cannot then be assigned values 3273by subsequent assignment statements or unset. 3274 3275@item -t 3276Give each @var{name} the @code{trace} attribute. 3277Traced functions inherit the @code{DEBUG} and @code{RETURN} traps from 3278the calling shell. 3279The trace attribute has no special meaning for variables. 3280 3281@item -x 3282Mark each @var{name} for export to subsequent commands via 3283the environment. 3284@end table 3285 3286Using @samp{+} instead of @samp{-} turns off the attribute instead. 3287When used in a function, @code{declare} makes each @var{name} local, 3288as with the @code{local} command. If a variable name is followed by 3289=@var{value}, the value of the variable is set to @var{value}. 3290 3291The return status is zero unless an invalid option is encountered, 3292an attempt is made to define a function using @samp{-f foo=bar}, 3293an attempt is made to assign a value to a readonly variable, 3294an attempt is made to assign a value to an array variable without 3295using the compound assignment syntax (@pxref{Arrays}), 3296one of the @var{names} is not a valid shell variable name, 3297an attempt is made to turn off readonly status for a readonly variable, 3298an attempt is made to turn off array status for an array variable, 3299or an attempt is made to display a non-existent function with @option{-f}. 3300 3301@item echo 3302@btindex echo 3303@example 3304echo [-neE] [@var{arg} @dots{}] 3305@end example 3306Output the @var{arg}s, separated by spaces, terminated with a 3307newline. 3308The return status is always 0. 3309If @option{-n} is specified, the trailing newline is suppressed. 3310If the @option{-e} option is given, interpretation of the following 3311backslash-escaped characters is enabled. 3312The @option{-E} option disables the interpretation of these escape characters, 3313even on systems where they are interpreted by default. 3314The @code{xpg_echo} shell option may be used to 3315dynamically determine whether or not @code{echo} expands these 3316escape characters by default. 3317@code{echo} does not interpret @option{--} to mean the end of options. 3318 3319@code{echo} interprets the following escape sequences: 3320@table @code 3321@item \a 3322alert (bell) 3323@item \b 3324backspace 3325@item \c 3326suppress trailing newline 3327@item \e 3328escape 3329@item \f 3330form feed 3331@item \n 3332new line 3333@item \r 3334carriage return 3335@item \t 3336horizontal tab 3337@item \v 3338vertical tab 3339@item \\ 3340backslash 3341@item \0@var{nnn} 3342the eight-bit character whose value is the octal value @var{nnn} 3343(zero to three octal digits) 3344@item \x@var{HH} 3345the eight-bit character whose value is the hexadecimal value @var{HH} 3346(one or two hex digits) 3347@end table 3348 3349@item enable 3350@btindex enable 3351@example 3352enable [-n] [-p] [-f @var{filename}] [-ads] [@var{name} @dots{}] 3353@end example 3354Enable and disable builtin shell commands. 3355Disabling a builtin allows a disk command which has the same name 3356as a shell builtin to be executed without specifying a full pathname, 3357even though the shell normally searches for builtins before disk commands. 3358If @option{-n} is used, the @var{name}s become disabled. Otherwise 3359@var{name}s are enabled. For example, to use the @code{test} binary 3360found via @env{$PATH} instead of the shell builtin version, type 3361@samp{enable -n test}. 3362 3363If the @option{-p} option is supplied, or no @var{name} arguments appear, 3364a list of shell builtins is printed. With no other arguments, the list 3365consists of all enabled shell builtins. 3366The @option{-a} option means to list 3367each builtin with an indication of whether or not it is enabled. 3368 3369The @option{-f} option means to load the new builtin command @var{name} 3370from shared object @var{filename}, on systems that support dynamic loading. 3371The @option{-d} option will delete a builtin loaded with @option{-f}. 3372 3373If there are no options, a list of the shell builtins is displayed. 3374The @option{-s} option restricts @code{enable} to the @sc{posix} special 3375builtins. If @option{-s} is used with @option{-f}, the new builtin becomes 3376a special builtin (@pxref{Special Builtins}). 3377 3378The return status is zero unless a @var{name} is not a shell builtin 3379or there is an error loading a new builtin from a shared object. 3380 3381@item help 3382@btindex help 3383@example 3384help [-s] [@var{pattern}] 3385@end example 3386Display helpful information about builtin commands. 3387If @var{pattern} is specified, @code{help} gives detailed help 3388on all commands matching @var{pattern}, otherwise a list of 3389the builtins is printed. 3390The @option{-s} option restricts the information displayed to a short 3391usage synopsis. 3392The return status is zero unless no command matches @var{pattern}. 3393 3394@item let 3395@btindex let 3396@example 3397let @var{expression} [@var{expression}] 3398@end example 3399The @code{let} builtin allows arithmetic to be performed on shell 3400variables. Each @var{expression} is evaluated according to the 3401rules given below in @ref{Shell Arithmetic}. If the 3402last @var{expression} evaluates to 0, @code{let} returns 1; 3403otherwise 0 is returned. 3404 3405@item local 3406@btindex local 3407@example 3408local [@var{option}] @var{name}[=@var{value}] @dots{} 3409@end example 3410For each argument, a local variable named @var{name} is created, 3411and assigned @var{value}. 3412The @var{option} can be any of the options accepted by @code{declare}. 3413@code{local} can only be used within a function; it makes the variable 3414@var{name} have a visible scope restricted to that function and its 3415children. The return status is zero unless @code{local} is used outside 3416a function, an invalid @var{name} is supplied, or @var{name} is a 3417readonly variable. 3418 3419@item logout 3420@btindex logout 3421@example 3422logout [@var{n}] 3423@end example 3424Exit a login shell, returning a status of @var{n} to the shell's 3425parent. 3426 3427@item printf 3428@btindex printf 3429@example 3430@code{printf} [-v @var{var}] @var{format} [@var{arguments}] 3431@end example 3432Write the formatted @var{arguments} to the standard output under the 3433control of the @var{format}. 3434The @var{format} is a character string which contains three types of objects: 3435plain characters, which are simply copied to standard output, character 3436escape sequences, which are converted and copied to the standard output, and 3437format specifications, each of which causes printing of the next successive 3438@var{argument}. 3439In addition to the standard @code{printf(1)} formats, @samp{%b} causes 3440@code{printf} to expand backslash escape sequences in the corresponding 3441@var{argument}, 3442(except that @samp{\c} terminates output, backslashes in 3443@samp{\'}, @samp{\"}, and @samp{\?} are not removed, and octal escapes 3444beginning with @samp{\0} may contain up to four digits), 3445and @samp{%q} causes @code{printf} to output the 3446corresponding @var{argument} in a format that can be reused as shell input. 3447 3448The @option{-v} option causes the output to be assigned to the variable 3449@var{var} rather than being printed to the standard output. 3450 3451The @var{format} is reused as necessary to consume all of the @var{arguments}. 3452If the @var{format} requires more @var{arguments} than are supplied, the 3453extra format specifications behave as if a zero value or null string, as 3454appropriate, had been supplied. The return value is zero on success, 3455non-zero on failure. 3456 3457@item read 3458@btindex read 3459@example 3460read [-ers] [-a @var{aname}] [-d @var{delim}] [-n @var{nchars}] [-p @var{prompt}] [-t @var{timeout}] [-u @var{fd}] [@var{name} @dots{}] 3461@end example 3462One line is read from the standard input, or from the file descriptor 3463@var{fd} supplied as an argument to the @option{-u} option, and the first word 3464is assigned to the first @var{name}, the second word to the second @var{name}, 3465and so on, with leftover words and their intervening separators assigned 3466to the last @var{name}. 3467If there are fewer words read from the input stream than names, 3468the remaining names are assigned empty values. 3469The characters in the value of the @env{IFS} variable 3470are used to split the line into words. 3471The backslash character @samp{\} may be used to remove any special 3472meaning for the next character read and for line continuation. 3473If no names are supplied, the line read is assigned to the 3474variable @env{REPLY}. 3475The return code is zero, unless end-of-file is encountered, @code{read} 3476times out, or an invalid file descriptor is supplied as the argument to 3477@option{-u}. 3478Options, if supplied, have the following meanings: 3479 3480@table @code 3481@item -a @var{aname} 3482The words are assigned to sequential indices of the array variable 3483@var{aname}, starting at 0. 3484All elements are removed from @var{aname} before the assignment. 3485Other @var{name} arguments are ignored. 3486 3487@item -d @var{delim} 3488The first character of @var{delim} is used to terminate the input line, 3489rather than newline. 3490 3491@item -e 3492Readline (@pxref{Command Line Editing}) is used to obtain the line. 3493 3494@item -n @var{nchars} 3495@code{read} returns after reading @var{nchars} characters rather than 3496waiting for a complete line of input. 3497 3498@item -p @var{prompt} 3499Display @var{prompt}, without a trailing newline, before attempting 3500to read any input. 3501The prompt is displayed only if input is coming from a terminal. 3502 3503@item -r 3504If this option is given, backslash does not act as an escape character. 3505The backslash is considered to be part of the line. 3506In particular, a backslash-newline pair may not be used as a line 3507continuation. 3508 3509@item -s 3510Silent mode. If input is coming from a terminal, characters are 3511not echoed. 3512 3513@item -t @var{timeout} 3514Cause @code{read} to time out and return failure if a complete line of 3515input is not read within @var{timeout} seconds. 3516This option has no effect if @code{read} is not reading input from the 3517terminal or a pipe. 3518 3519@item -u @var{fd} 3520Read input from file descriptor @var{fd}. 3521 3522@end table 3523 3524@item shopt 3525@btindex shopt 3526@example 3527shopt [-pqsu] [-o] [@var{optname} @dots{}] 3528@end example 3529Toggle the values of variables controlling optional shell behavior. 3530With no options, or with the @option{-p} option, a list of all settable 3531options is displayed, with an indication of whether or not each is set. 3532The @option{-p} option causes output to be displayed in a form that 3533may be reused as input. 3534Other options have the following meanings: 3535 3536@table @code 3537@item -s 3538Enable (set) each @var{optname}. 3539 3540@item -u 3541Disable (unset) each @var{optname}. 3542 3543@item -q 3544Suppresses normal output; the return status 3545indicates whether the @var{optname} is set or unset. 3546If multiple @var{optname} arguments are given with @option{-q}, 3547the return status is zero if all @var{optnames} are enabled; 3548non-zero otherwise. 3549 3550@item -o 3551Restricts the values of 3552@var{optname} to be those defined for the @option{-o} option to the 3553@code{set} builtin (@pxref{The Set Builtin}). 3554@end table 3555 3556If either @option{-s} or @option{-u} 3557is used with no @var{optname} arguments, the display is limited to 3558those options which are set or unset, respectively. 3559 3560Unless otherwise noted, the @code{shopt} options are disabled (off) 3561by default. 3562 3563The return status when listing options is zero if all @var{optnames} 3564are enabled, non-zero otherwise. When setting or unsetting options, 3565the return status is zero unless an @var{optname} is not a valid shell 3566option. 3567 3568The list of @code{shopt} options is: 3569@table @code 3570@item cdable_vars 3571If this is set, an argument to the @code{cd} 3572builtin command that 3573is not a directory is assumed to be the name of a variable whose 3574value is the directory to change to. 3575 3576@item cdspell 3577If set, minor errors in the spelling of a directory component in a 3578@code{cd} command will be corrected. 3579The errors checked for are transposed characters, 3580a missing character, and a character too many. 3581If a correction is found, the corrected path is printed, 3582and the command proceeds. 3583This option is only used by interactive shells. 3584 3585@item checkhash 3586If this is set, Bash checks that a command found in the hash 3587table exists before trying to execute it. If a hashed command no 3588longer exists, a normal path search is performed. 3589 3590@item checkwinsize 3591If set, Bash checks the window size after each command 3592and, if necessary, updates the values of 3593@env{LINES} and @env{COLUMNS}. 3594 3595@item cmdhist 3596If set, Bash 3597attempts to save all lines of a multiple-line 3598command in the same history entry. This allows 3599easy re-editing of multi-line commands. 3600 3601@item compat31 3602If set, Bash 3603changes its behavior to that of version 3.1 with respect to quoted 3604arguments to the conditional command's =~ operator. 3605 3606@item dotglob 3607If set, Bash includes filenames beginning with a `.' in 3608the results of filename expansion. 3609 3610@item execfail 3611If this is set, a non-interactive shell will not exit if 3612it cannot execute the file specified as an argument to the @code{exec} 3613builtin command. An interactive shell does not exit if @code{exec} 3614fails. 3615 3616@item expand_aliases 3617If set, aliases are expanded as described below under Aliases, 3618@ref{Aliases}. 3619This option is enabled by default for interactive shells. 3620 3621@item extdebug 3622If set, behavior intended for use by debuggers is enabled: 3623 3624@enumerate 3625@item 3626The @option{-F} option to the @code{declare} builtin (@pxref{Bash Builtins}) 3627displays the source file name and line number corresponding to each function 3628name supplied as an argument. 3629 3630@item 3631If the command run by the @code{DEBUG} trap returns a non-zero value, the 3632next command is skipped and not executed. 3633 3634@item 3635If the command run by the @code{DEBUG} trap returns a value of 2, and the 3636shell is executing in a subroutine (a shell function or a shell script 3637executed by the @code{.} or @code{source} builtins), a call to 3638@code{return} is simulated. 3639 3640@item 3641@code{BASH_ARGC} and @code{BASH_ARGV} are updated as described in their 3642descriptions (@pxref{Bash Variables}). 3643 3644@item 3645Function tracing is enabled: command substitution, shell functions, and 3646subshells invoked with @code{( @var{command} )} inherit the 3647@code{DEBUG} and @code{RETURN} traps. 3648 3649@item 3650Error tracing is enabled: command substitution, shell functions, and 3651subshells invoked with @code{( @var{command} )} inherit the 3652@code{ERROR} trap. 3653@end enumerate 3654 3655@item extglob 3656If set, the extended pattern matching features described above 3657(@pxref{Pattern Matching}) are enabled. 3658 3659@item extquote 3660If set, @code{$'@var{string}'} and @code{$"@var{string}"} quoting is 3661performed within @code{$@{@var{parameter}@}} expansions 3662enclosed in double quotes. This option is enabled by default. 3663 3664@item failglob 3665If set, patterns which fail to match filenames during pathname expansion 3666result in an expansion error. 3667 3668@item force_fignore 3669If set, the suffixes specified by the @env{FIGNORE} shell variable 3670cause words to be ignored when performing word completion even if 3671the ignored words are the only possible completions. 3672@xref{Bash Variables}, for a description of @env{FIGNORE}. 3673This option is enabled by default. 3674 3675@item gnu_errfmt 3676If set, shell error messages are written in the standard @sc{gnu} error 3677message format. 3678 3679@item histappend 3680If set, the history list is appended to the file named by the value 3681of the @env{HISTFILE} 3682variable when the shell exits, rather than overwriting the file. 3683 3684@item histreedit 3685If set, and Readline 3686is being used, a user is given the opportunity to re-edit a 3687failed history substitution. 3688 3689@item histverify 3690If set, and Readline 3691is being used, the results of history substitution are not immediately 3692passed to the shell parser. Instead, the resulting line is loaded into 3693the Readline editing buffer, allowing further modification. 3694 3695@item hostcomplete 3696If set, and Readline is being used, Bash will attempt to perform 3697hostname completion when a word containing a @samp{@@} is being 3698completed (@pxref{Commands For Completion}). This option is enabled 3699by default. 3700 3701@item huponexit 3702If set, Bash will send @code{SIGHUP} to all jobs when an interactive 3703login shell exits (@pxref{Signals}). 3704 3705@item interactive_comments 3706Allow a word beginning with @samp{#} 3707to cause that word and all remaining characters on that 3708line to be ignored in an interactive shell. 3709This option is enabled by default. 3710 3711@item lithist 3712If enabled, and the @code{cmdhist} 3713option is enabled, multi-line commands are saved to the history with 3714embedded newlines rather than using semicolon separators where possible. 3715 3716@item login_shell 3717The shell sets this option if it is started as a login shell 3718(@pxref{Invoking Bash}). 3719The value may not be changed. 3720 3721@item mailwarn 3722If set, and a file that Bash is checking for mail has been 3723accessed since the last time it was checked, the message 3724@code{"The mail in @var{mailfile} has been read"} is displayed. 3725 3726@item no_empty_cmd_completion 3727If set, and Readline is being used, Bash will not attempt to search 3728the @env{PATH} for possible completions when completion is attempted 3729on an empty line. 3730 3731@item nocaseglob 3732If set, Bash matches filenames in a case-insensitive fashion when 3733performing filename expansion. 3734 3735@item nocasematch 3736If set, Bash matches patterns in a case-insensitive fashion when 3737performing matching while executing @code{case} or @code{[[} 3738conditional commands. 3739 3740@item nullglob 3741If set, Bash allows filename patterns which match no 3742files to expand to a null string, rather than themselves. 3743 3744@item progcomp 3745If set, the programmable completion facilities 3746(@pxref{Programmable Completion}) are enabled. 3747This option is enabled by default. 3748 3749@item promptvars 3750If set, prompt strings undergo 3751parameter expansion, command substitution, arithmetic 3752expansion, and quote removal after being expanded 3753as described below (@pxref{Printing a Prompt}). 3754This option is enabled by default. 3755 3756@item restricted_shell 3757The shell sets this option if it is started in restricted mode 3758(@pxref{The Restricted Shell}). 3759The value may not be changed. 3760This is not reset when the startup files are executed, allowing 3761the startup files to discover whether or not a shell is restricted. 3762 3763@item shift_verbose 3764If this is set, the @code{shift} 3765builtin prints an error message when the shift count exceeds the 3766number of positional parameters. 3767 3768@item sourcepath 3769If set, the @code{source} builtin uses the value of @env{PATH} 3770to find the directory containing the file supplied as an argument. 3771This option is enabled by default. 3772 3773@item xpg_echo 3774If set, the @code{echo} builtin expands backslash-escape sequences 3775by default. 3776 3777@end table 3778 3779@noindent 3780The return status when listing options is zero if all @var{optnames} 3781are enabled, non-zero otherwise. 3782When setting or unsetting options, the return status is zero unless an 3783@var{optname} is not a valid shell option. 3784 3785@item source 3786@btindex source 3787@example 3788source @var{filename} 3789@end example 3790A synonym for @code{.} (@pxref{Bourne Shell Builtins}). 3791 3792@item type 3793@btindex type 3794@example 3795type [-afptP] [@var{name} @dots{}] 3796@end example 3797For each @var{name}, indicate how it would be interpreted if used as a 3798command name. 3799 3800If the @option{-t} option is used, @code{type} prints a single word 3801which is one of @samp{alias}, @samp{function}, @samp{builtin}, 3802@samp{file} or @samp{keyword}, 3803if @var{name} is an alias, shell function, shell builtin, 3804disk file, or shell reserved word, respectively. 3805If the @var{name} is not found, then nothing is printed, and 3806@code{type} returns a failure status. 3807 3808If the @option{-p} option is used, @code{type} either returns the name 3809of the disk file that would be executed, or nothing if @option{-t} 3810would not return @samp{file}. 3811 3812The @option{-P} option forces a path search for each @var{name}, even if 3813@option{-t} would not return @samp{file}. 3814 3815If a command is hashed, @option{-p} and @option{-P} print the hashed value, 3816not necessarily the file that appears first in @code{$PATH}. 3817 3818If the @option{-a} option is used, @code{type} returns all of the places 3819that contain an executable named @var{file}. 3820This includes aliases and functions, if and only if the @option{-p} option 3821is not also used. 3822 3823If the @option{-f} option is used, @code{type} does not attempt to find 3824shell functions, as with the @code{command} builtin. 3825 3826The return status is zero if any of the @var{names} are found, non-zero 3827if none are found. 3828 3829@item typeset 3830@btindex typeset 3831@example 3832typeset [-afFrxi] [-p] [@var{name}[=@var{value}] @dots{}] 3833@end example 3834The @code{typeset} command is supplied for compatibility with the Korn 3835shell; however, it has been deprecated in favor of the @code{declare} 3836builtin command. 3837 3838@item ulimit 3839@btindex ulimit 3840@example 3841ulimit [-acdefilmnpqrstuvxSH] [@var{limit}] 3842@end example 3843@code{ulimit} provides control over the resources available to processes 3844started by the shell, on systems that allow such control. If an 3845option is given, it is interpreted as follows: 3846@table @code 3847@item -S 3848Change and report the soft limit associated with a resource. 3849 3850@item -H 3851Change and report the hard limit associated with a resource. 3852 3853@item -a 3854All current limits are reported. 3855 3856@item -c 3857The maximum size of core files created. 3858 3859@item -d 3860The maximum size of a process's data segment. 3861 3862@item -e 3863The maximum scheduling priority ("nice"). 3864 3865@item -f 3866The maximum size of files written by the shell and its children. 3867 3868@item -i 3869The maximum number of pending signals. 3870 3871@item -l 3872The maximum size that may be locked into memory. 3873 3874@item -m 3875The maximum resident set size. 3876 3877@item -n 3878The maximum number of open file descriptors. 3879 3880@item -p 3881The pipe buffer size. 3882 3883@item -q 3884The maximum number of bytes in POSIX message queues. 3885 3886@item -r 3887The maximum real-time scheduling priority. 3888 3889@item -s 3890The maximum stack size. 3891 3892@item -t 3893The maximum amount of cpu time in seconds. 3894 3895@item -u 3896The maximum number of processes available to a single user. 3897 3898@item -v 3899The maximum amount of virtual memory available to the process. 3900 3901@item -x 3902The maximum number of file locks. 3903 3904@end table 3905 3906If @var{limit} is given, it is the new value of the specified resource; 3907the special @var{limit} values @code{hard}, @code{soft}, and 3908@code{unlimited} stand for the current hard limit, the current soft limit, 3909and no limit, respectively. 3910Otherwise, the current value of the soft limit for the specified resource 3911is printed, unless the @option{-H} option is supplied. 3912When setting new limits, if neither @option{-H} nor @option{-S} is supplied, 3913both the hard and soft limits are set. 3914If no option is given, then @option{-f} is assumed. Values are in 1024-byte 3915increments, except for @option{-t}, which is in seconds, @option{-p}, 3916which is in units of 512-byte blocks, and @option{-n} and @option{-u}, which 3917are unscaled values. 3918 3919The return status is zero unless an invalid option or argument is supplied, 3920or an error occurs while setting a new limit. 3921 3922@item unalias 3923@btindex unalias 3924@example 3925unalias [-a] [@var{name} @dots{} ] 3926@end example 3927 3928Remove each @var{name} from the list of aliases. If @option{-a} is 3929supplied, all aliases are removed. 3930Aliases are described in @ref{Aliases}. 3931 3932@end table 3933 3934@node The Set Builtin 3935@section The Set Builtin 3936 3937This builtin is so complicated that it deserves its own section. 3938 3939@table @code 3940@item set 3941@btindex set 3942@example 3943set [--abefhkmnptuvxBCHP] [-o @var{option}] [@var{argument} @dots{}] 3944@end example 3945 3946If no options or arguments are supplied, @code{set} displays the names 3947and values of all shell variables and functions, sorted according to the 3948current locale, in a format that may be reused as input 3949for setting or resetting the currently-set variables. 3950Read-only variables cannot be reset. 3951In @sc{posix} mode, only shell variables are listed. 3952 3953When options are supplied, they set or unset shell attributes. 3954Options, if specified, have the following meanings: 3955 3956@table @code 3957@item -a 3958Mark variables and function which are modified or created for export 3959to the environment of subsequent commands. 3960 3961@item -b 3962Cause the status of terminated background jobs to be reported 3963immediately, rather than before printing the next primary prompt. 3964 3965@item -e 3966Exit immediately if a simple command (@pxref{Simple Commands}) exits 3967with a non-zero status, unless the command that fails is part of the 3968command list immediately following a @code{while} or @code{until} 3969keyword, part of the test in an @code{if} statement, 3970part of a @code{&&} or @code{||} list, or if the command's return 3971status is being inverted using @code{!}. 3972A trap on @code{ERR}, if set, is executed before the shell exits. 3973 3974@item -f 3975Disable file name generation (globbing). 3976 3977@item -h 3978Locate and remember (hash) commands as they are looked up for execution. 3979This option is enabled by default. 3980 3981@item -k 3982All arguments in the form of assignment statements are placed 3983in the environment for a command, not just those that precede 3984the command name. 3985 3986@item -m 3987Job control is enabled (@pxref{Job Control}). 3988 3989@item -n 3990Read commands but do not execute them; this may be used to check a 3991script for syntax errors. 3992This option is ignored by interactive shells. 3993 3994@item -o @var{option-name} 3995 3996Set the option corresponding to @var{option-name}: 3997 3998@table @code 3999@item allexport 4000Same as @code{-a}. 4001 4002@item braceexpand 4003Same as @code{-B}. 4004 4005@item emacs 4006Use an @code{emacs}-style line editing interface (@pxref{Command Line Editing}). 4007 4008@item errexit 4009Same as @code{-e}. 4010 4011@item errtrace 4012Same as @code{-E}. 4013 4014@item functrace 4015Same as @code{-T}. 4016 4017@item hashall 4018Same as @code{-h}. 4019 4020@item histexpand 4021Same as @code{-H}. 4022 4023@item history 4024Enable command history, as described in @ref{Bash History Facilities}. 4025This option is on by default in interactive shells. 4026 4027@item ignoreeof 4028An interactive shell will not exit upon reading EOF. 4029 4030@item keyword 4031Same as @code{-k}. 4032 4033@item monitor 4034Same as @code{-m}. 4035 4036@item noclobber 4037Same as @code{-C}. 4038 4039@item noexec 4040Same as @code{-n}. 4041 4042@item noglob 4043Same as @code{-f}. 4044 4045@item nolog 4046Currently ignored. 4047 4048@item notify 4049Same as @code{-b}. 4050 4051@item nounset 4052Same as @code{-u}. 4053 4054@item onecmd 4055Same as @code{-t}. 4056 4057@item physical 4058Same as @code{-P}. 4059 4060@item pipefail 4061If set, the return value of a pipeline is the value of the last 4062(rightmost) command to exit with a non-zero status, or zero if all 4063commands in the pipeline exit successfully. 4064This option is disabled by default. 4065 4066@item posix 4067Change the behavior of Bash where the default operation differs 4068from the @sc{posix} standard to match the standard 4069(@pxref{Bash POSIX Mode}). 4070This is intended to make Bash behave as a strict superset of that 4071standard. 4072 4073@item privileged 4074Same as @code{-p}. 4075 4076@item verbose 4077Same as @code{-v}. 4078 4079@item vi 4080Use a @code{vi}-style line editing interface. 4081 4082@item xtrace 4083Same as @code{-x}. 4084@end table 4085 4086@item -p 4087Turn on privileged mode. 4088In this mode, the @env{$BASH_ENV} and @env{$ENV} files are not 4089processed, shell functions are not inherited from the environment, 4090and the @env{SHELLOPTS} variable, if it appears in the environment, 4091is ignored. 4092If the shell is started with the effective user (group) id not equal to the 4093real user (group) id, and the @code{-p} option is not supplied, these actions 4094are taken and the effective user id is set to the real user id. 4095If the @code{-p} option is supplied at startup, the effective user id is 4096not reset. 4097Turning this option off causes the effective user 4098and group ids to be set to the real user and group ids. 4099 4100@item -t 4101Exit after reading and executing one command. 4102 4103@item -u 4104Treat unset variables as an error when performing parameter expansion. 4105An error message will be written to the standard error, and a non-interactive 4106shell will exit. 4107 4108@item -v 4109Print shell input lines as they are read. 4110 4111@item -x 4112Print a trace of simple commands, @code{for} commands, @code{case} 4113commands, @code{select} commands, and arithmetic @code{for} commands 4114and their arguments or associated word lists after they are 4115expanded and before they are executed. The value of the @env{PS4} 4116variable is expanded and the resultant value is printed before 4117the command and its expanded arguments. 4118 4119@item -B 4120The shell will perform brace expansion (@pxref{Brace Expansion}). 4121This option is on by default. 4122 4123@item -C 4124Prevent output redirection using @samp{>}, @samp{>&}, and @samp{<>} 4125from overwriting existing files. 4126 4127@item -E 4128If set, any trap on @code{ERR} is inherited by shell functions, command 4129substitutions, and commands executed in a subshell environment. 4130The @code{ERR} trap is normally not inherited in such cases. 4131 4132@item -H 4133Enable @samp{!} style history substitution (@pxref{History Interaction}). 4134This option is on by default for interactive shells. 4135 4136@item -P 4137If set, do not follow symbolic links when performing commands such as 4138@code{cd} which change the current directory. The physical directory 4139is used instead. By default, Bash follows 4140the logical chain of directories when performing commands 4141which change the current directory. 4142 4143For example, if @file{/usr/sys} is a symbolic link to @file{/usr/local/sys} 4144then: 4145@example 4146$ cd /usr/sys; echo $PWD 4147/usr/sys 4148$ cd ..; pwd 4149/usr 4150@end example 4151 4152@noindent 4153If @code{set -P} is on, then: 4154@example 4155$ cd /usr/sys; echo $PWD 4156/usr/local/sys 4157$ cd ..; pwd 4158/usr/local 4159@end example 4160 4161@item -T 4162If set, any trap on @code{DEBUG} and @code{RETURN} are inherited by 4163shell functions, command substitutions, and commands executed 4164in a subshell environment. 4165The @code{DEBUG} and @code{RETURN} traps are normally not inherited 4166in such cases. 4167 4168@item -- 4169If no arguments follow this option, then the positional parameters are 4170unset. Otherwise, the positional parameters are set to the 4171@var{arguments}, even if some of them begin with a @samp{-}. 4172 4173@item - 4174Signal the end of options, cause all remaining @var{arguments} 4175to be assigned to the positional parameters. The @option{-x} 4176and @option{-v} options are turned off. 4177If there are no arguments, the positional parameters remain unchanged. 4178@end table 4179 4180Using @samp{+} rather than @samp{-} causes these options to be 4181turned off. The options can also be used upon invocation of the 4182shell. The current set of options may be found in @code{$-}. 4183 4184The remaining N @var{arguments} are positional parameters and are 4185assigned, in order, to @code{$1}, @code{$2}, @dots{} @code{$N}. 4186The special parameter @code{#} is set to N. 4187 4188The return status is always zero unless an invalid option is supplied. 4189@end table 4190 4191@node Special Builtins 4192@section Special Builtins 4193@cindex special builtin 4194 4195For historical reasons, the @sc{posix} standard has classified 4196several builtin commands as @emph{special}. 4197When Bash is executing in @sc{posix} mode, the special builtins 4198differ from other builtin commands in three respects: 4199 4200@enumerate 4201@item 4202Special builtins are found before shell functions during command lookup. 4203 4204@item 4205If a special builtin returns an error status, a non-interactive shell exits. 4206 4207@item 4208Assignment statements preceding the command stay in effect in the shell 4209environment after the command completes. 4210@end enumerate 4211 4212When Bash is not executing in @sc{posix} mode, these builtins behave no 4213differently than the rest of the Bash builtin commands. 4214The Bash @sc{posix} mode is described in @ref{Bash POSIX Mode}. 4215 4216These are the @sc{posix} special builtins: 4217@example 4218@w{break : . continue eval exec exit export readonly return set} 4219@w{shift trap unset} 4220@end example 4221 4222@node Shell Variables 4223@chapter Shell Variables 4224 4225@menu 4226* Bourne Shell Variables:: Variables which Bash uses in the same way 4227 as the Bourne Shell. 4228* Bash Variables:: List of variables that exist in Bash. 4229@end menu 4230 4231This chapter describes the shell variables that Bash uses. 4232Bash automatically assigns default values to a number of variables. 4233 4234@node Bourne Shell Variables 4235@section Bourne Shell Variables 4236 4237Bash uses certain shell variables in the same way as the Bourne shell. 4238In some cases, Bash assigns a default value to the variable. 4239 4240@vtable @code 4241 4242@item CDPATH 4243A colon-separated list of directories used as a search path for 4244the @code{cd} builtin command. 4245 4246@item HOME 4247The current user's home directory; the default for the @code{cd} builtin 4248command. 4249The value of this variable is also used by tilde expansion 4250(@pxref{Tilde Expansion}). 4251 4252@item IFS 4253A list of characters that separate fields; used when the shell splits 4254words as part of expansion. 4255 4256@item MAIL 4257If this parameter is set to a filename and the @env{MAILPATH} variable 4258is not set, Bash informs the user of the arrival of mail in 4259the specified file. 4260 4261@item MAILPATH 4262A colon-separated list of filenames which the shell periodically checks 4263for new mail. 4264Each list entry can specify the message that is printed when new mail 4265arrives in the mail file by separating the file name from the message with 4266a @samp{?}. 4267When used in the text of the message, @code{$_} expands to the name of 4268the current mail file. 4269 4270@item OPTARG 4271The value of the last option argument processed by the @code{getopts} builtin. 4272 4273@item OPTIND 4274The index of the last option argument processed by the @code{getopts} builtin. 4275 4276@item PATH 4277A colon-separated list of directories in which the shell looks for 4278commands. 4279A zero-length (null) directory name in the value of @code{PATH} indicates the 4280current directory. 4281A null directory name may appear as two adjacent colons, or as an initial 4282or trailing colon. 4283 4284 4285@item PS1 4286The primary prompt string. The default value is @samp{\s-\v\$ }. 4287@xref{Printing a Prompt}, for the complete list of escape 4288sequences that are expanded before @env{PS1} is displayed. 4289 4290@item PS2 4291The secondary prompt string. The default value is @samp{> }. 4292 4293@end vtable 4294 4295@node Bash Variables 4296@section Bash Variables 4297 4298These variables are set or used by Bash, but other shells 4299do not normally treat them specially. 4300 4301A few variables used by Bash are described in different chapters: 4302variables for controlling the job control facilities 4303(@pxref{Job Control Variables}). 4304 4305@vtable @code 4306 4307@item BASH 4308The full pathname used to execute the current instance of Bash. 4309 4310@item BASH_ARGC 4311An array variable whose values are the number of parameters in each 4312frame of the current bash execution call stack. The number of 4313parameters to the current subroutine (shell function or script executed 4314with @code{.} or @code{source}) is at the top of the stack. When a 4315subroutine is executed, the number of parameters passed is pushed onto 4316@code{BASH_ARGC}. 4317The shell sets @code{BASH_ARGC} only when in extended debugging mode 4318(see @ref{Bash Builtins} 4319for a description of the @code{extdebug} option to the @code{shopt} 4320builtin). 4321 4322@item BASH_ARGV 4323An array variable containing all of the parameters in the current bash 4324execution call stack. The final parameter of the last subroutine call 4325is at the top of the stack; the first parameter of the initial call is 4326at the bottom. When a subroutine is executed, the parameters supplied 4327are pushed onto @code{BASH_ARGV}. 4328The shell sets @code{BASH_ARGV} only when in extended debugging mode 4329(see @ref{Bash Builtins} 4330for a description of the @code{extdebug} option to the @code{shopt} 4331builtin). 4332 4333@item BASH_COMMAND 4334The command currently being executed or about to be executed, unless the 4335shell is executing a command as the result of a trap, 4336in which case it is the command executing at the time of the trap. 4337 4338@item BASH_ENV 4339If this variable is set when Bash is invoked to execute a shell 4340script, its value is expanded and used as the name of a startup file 4341to read before executing the script. @xref{Bash Startup Files}. 4342 4343@item BASH_EXECUTION_STRING 4344The command argument to the @option{-c} invocation option. 4345 4346@item BASH_LINENO 4347An array variable whose members are the line numbers in source files 4348corresponding to each member of @var{FUNCNAME}. 4349@code{$@{BASH_LINENO[$i]@}} is the line number in the source file where 4350@code{$@{FUNCNAME[$i]@}} was called. 4351The corresponding source file name is @code{$@{BASH_SOURCE[$i]@}}. 4352Use @code{LINENO} to obtain the current line number. 4353 4354@item BASH_REMATCH 4355An array variable whose members are assigned by the @samp{=~} binary 4356operator to the @code{[[} conditional command 4357(@pxref{Conditional Constructs}). 4358The element with index 0 is the portion of the string 4359matching the entire regular expression. 4360The element with index @var{n} is the portion of the 4361string matching the @var{n}th parenthesized subexpression. 4362This variable is read-only. 4363 4364@item BASH_SOURCE 4365An array variable whose members are the source filenames corresponding 4366to the elements in the @code{FUNCNAME} array variable. 4367 4368@item BASH_SUBSHELL 4369Incremented by one each time a subshell or subshell environment is spawned. 4370The initial value is 0. 4371 4372@item BASH_VERSINFO 4373A readonly array variable (@pxref{Arrays}) 4374whose members hold version information for this instance of Bash. 4375The values assigned to the array members are as follows: 4376 4377@table @code 4378 4379@item BASH_VERSINFO[0] 4380The major version number (the @var{release}). 4381 4382@item BASH_VERSINFO[1] 4383The minor version number (the @var{version}). 4384 4385@item BASH_VERSINFO[2] 4386The patch level. 4387 4388@item BASH_VERSINFO[3] 4389The build version. 4390 4391@item BASH_VERSINFO[4] 4392The release status (e.g., @var{beta1}). 4393 4394@item BASH_VERSINFO[5] 4395The value of @env{MACHTYPE}. 4396 4397@end table 4398 4399@item BASH_VERSION 4400The version number of the current instance of Bash. 4401 4402@item COLUMNS 4403Used by the @code{select} builtin command to determine the terminal width 4404when printing selection lists. Automatically set upon receipt of a 4405@code{SIGWINCH}. 4406 4407@item COMP_CWORD 4408An index into @env{$@{COMP_WORDS@}} of the word containing the current 4409cursor position. 4410This variable is available only in shell functions invoked by the 4411programmable completion facilities (@pxref{Programmable Completion}). 4412 4413@item COMP_LINE 4414The current command line. 4415This variable is available only in shell functions and external 4416commands invoked by the 4417programmable completion facilities (@pxref{Programmable Completion}). 4418 4419@item COMP_POINT 4420The index of the current cursor position relative to the beginning of 4421the current command. 4422If the current cursor position is at the end of the current command, 4423the value of this variable is equal to @code{$@{#COMP_LINE@}}. 4424This variable is available only in shell functions and external 4425commands invoked by the 4426programmable completion facilities (@pxref{Programmable Completion}). 4427 4428@item COMP_WORDBREAKS 4429The set of characters that the Readline library treats as word 4430separators when performing word completion. 4431If @code{COMP_WORDBREAKS} is unset, it loses its special properties, 4432even if it is subsequently reset. 4433 4434@item COMP_WORDS 4435An array variable consisting of the individual 4436words in the current command line. 4437The words are split on shell metacharacters as the shell parser would 4438separate them. 4439This variable is available only in shell functions invoked by the 4440programmable completion facilities (@pxref{Programmable Completion}). 4441 4442@item COMPREPLY 4443An array variable from which Bash reads the possible completions 4444generated by a shell function invoked by the programmable completion 4445facility (@pxref{Programmable Completion}). 4446 4447@item DIRSTACK 4448An array variable containing the current contents of the directory stack. 4449Directories appear in the stack in the order they are displayed by the 4450@code{dirs} builtin. 4451Assigning to members of this array variable may be used to modify 4452directories already in the stack, but the @code{pushd} and @code{popd} 4453builtins must be used to add and remove directories. 4454Assignment to this variable will not change the current directory. 4455If @env{DIRSTACK} is unset, it loses its special properties, even if 4456it is subsequently reset. 4457 4458@item EMACS 4459If Bash finds this variable in the environment when the shell 4460starts with value @samp{t}, it assumes that the shell is running in an 4461emacs shell buffer and disables line editing. 4462 4463@item EUID 4464The numeric effective user id of the current user. This variable 4465is readonly. 4466 4467@item FCEDIT 4468The editor used as a default by the @option{-e} option to the @code{fc} 4469builtin command. 4470 4471@item FIGNORE 4472A colon-separated list of suffixes to ignore when performing 4473filename completion. 4474A file name whose suffix matches one of the entries in 4475@env{FIGNORE} 4476is excluded from the list of matched file names. A sample 4477value is @samp{.o:~} 4478 4479@item FUNCNAME 4480An array variable containing the names of all shell functions 4481currently in the execution call stack. 4482The element with index 0 is the name of any currently-executing 4483shell function. 4484The bottom-most element is "main". 4485This variable exists only when a shell function is executing. 4486Assignments to @env{FUNCNAME} have no effect and return an error status. 4487If @env{FUNCNAME} is unset, it loses its special properties, even if 4488it is subsequently reset. 4489 4490@item GLOBIGNORE 4491A colon-separated list of patterns defining the set of filenames to 4492be ignored by filename expansion. 4493If a filename matched by a filename expansion pattern also matches one 4494of the patterns in @env{GLOBIGNORE}, it is removed from the list 4495of matches. 4496 4497@item GROUPS 4498An array variable containing the list of groups of which the current 4499user is a member. 4500Assignments to @env{GROUPS} have no effect and return an error status. 4501If @env{GROUPS} is unset, it loses its special properties, even if it is 4502subsequently reset. 4503 4504@item histchars 4505Up to three characters which control history expansion, quick 4506substitution, and tokenization (@pxref{History Interaction}). 4507The first character is the 4508@var{history expansion} character, that is, the character which signifies the 4509start of a history expansion, normally @samp{!}. The second character is the 4510character which signifies `quick substitution' when seen as the first 4511character on a line, normally @samp{^}. The optional third character is the 4512character which indicates that the remainder of the line is a comment when 4513found as the first character of a word, usually @samp{#}. The history 4514comment character causes history substitution to be skipped for the 4515remaining words on the line. It does not necessarily cause the shell 4516parser to treat the rest of the line as a comment. 4517 4518@item HISTCMD 4519The history number, or index in the history list, of the current 4520command. If @env{HISTCMD} is unset, it loses its special properties, 4521even if it is subsequently reset. 4522 4523@item HISTCONTROL 4524A colon-separated list of values controlling how commands are saved on 4525the history list. 4526If the list of values includes @samp{ignorespace}, lines which begin 4527with a space character are not saved in the history list. 4528A value of @samp{ignoredups} causes lines which match the previous 4529history entry to not be saved. 4530A value of @samp{ignoreboth} is shorthand for 4531@samp{ignorespace} and @samp{ignoredups}. 4532A value of @samp{erasedups} causes all previous lines matching the 4533current line to be removed from the history list before that line 4534is saved. 4535Any value not in the above list is ignored. 4536If @env{HISTCONTROL} is unset, or does not include a valid value, 4537all lines read by the shell parser are saved on the history list, 4538subject to the value of @env{HISTIGNORE}. 4539The second and subsequent lines of a multi-line compound command are 4540not tested, and are added to the history regardless of the value of 4541@env{HISTCONTROL}. 4542 4543@item HISTFILE 4544The name of the file to which the command history is saved. The 4545default value is @file{~/.bash_history}. 4546 4547@item HISTFILESIZE 4548The maximum number of lines contained in the history file. When this 4549variable is assigned a value, the history file is truncated, if 4550necessary, by removing the oldest entries, 4551to contain no more than that number of lines. 4552The history file is also truncated to this size after 4553writing it when an interactive shell exits. 4554The default value is 500. 4555 4556@item HISTIGNORE 4557A colon-separated list of patterns used to decide which command 4558lines should be saved on the history list. Each pattern is 4559anchored at the beginning of the line and must match the complete 4560line (no implicit @samp{*} is appended). Each pattern is tested 4561against the line after the checks specified by @env{HISTCONTROL} 4562are applied. In addition to the normal shell pattern matching 4563characters, @samp{&} matches the previous history line. @samp{&} 4564may be escaped using a backslash; the backslash is removed 4565before attempting a match. 4566The second and subsequent lines of a multi-line compound command are 4567not tested, and are added to the history regardless of the value of 4568@env{HISTIGNORE}. 4569 4570@env{HISTIGNORE} subsumes the function of @env{HISTCONTROL}. A 4571pattern of @samp{&} is identical to @code{ignoredups}, and a 4572pattern of @samp{[ ]*} is identical to @code{ignorespace}. 4573Combining these two patterns, separating them with a colon, 4574provides the functionality of @code{ignoreboth}. 4575 4576@item HISTSIZE 4577The maximum number of commands to remember on the history list. 4578The default value is 500. 4579 4580@item HISTTIMEFORMAT 4581If this variable is set and not null, its value is used as a format string 4582for @var{strftime} to print the time stamp associated with each history 4583entry displayed by the @code{history} builtin. 4584If this variable is set, time stamps are written to the history file so 4585they may be preserved across shell sessions. 4586 4587@item HOSTFILE 4588Contains the name of a file in the same format as @file{/etc/hosts} that 4589should be read when the shell needs to complete a hostname. 4590The list of possible hostname completions may be changed while the shell 4591is running; 4592the next time hostname completion is attempted after the 4593value is changed, Bash adds the contents of the new file to the 4594existing list. 4595If @env{HOSTFILE} is set, but has no value, Bash attempts to read 4596@file{/etc/hosts} to obtain the list of possible hostname completions. 4597When @env{HOSTFILE} is unset, the hostname list is cleared. 4598 4599@item HOSTNAME 4600The name of the current host. 4601 4602@item HOSTTYPE 4603A string describing the machine Bash is running on. 4604 4605@item IGNOREEOF 4606Controls the action of the shell on receipt of an @code{EOF} character 4607as the sole input. If set, the value denotes the number 4608of consecutive @code{EOF} characters that can be read as the 4609first character on an input line 4610before the shell will exit. If the variable exists but does not 4611have a numeric value (or has no value) then the default is 10. 4612If the variable does not exist, then @code{EOF} signifies the end of 4613input to the shell. This is only in effect for interactive shells. 4614 4615@item INPUTRC 4616The name of the Readline initialization file, overriding the default 4617of @file{~/.inputrc}. 4618 4619@item LANG 4620Used to determine the locale category for any category not specifically 4621selected with a variable starting with @code{LC_}. 4622 4623@item LC_ALL 4624This variable overrides the value of @env{LANG} and any other 4625@code{LC_} variable specifying a locale category. 4626 4627@item LC_COLLATE 4628This variable determines the collation order used when sorting the 4629results of filename expansion, and 4630determines the behavior of range expressions, equivalence classes, 4631and collating sequences within filename expansion and pattern matching 4632(@pxref{Filename Expansion}). 4633 4634@item LC_CTYPE 4635This variable determines the interpretation of characters and the 4636behavior of character classes within filename expansion and pattern 4637matching (@pxref{Filename Expansion}). 4638 4639@item LC_MESSAGES 4640This variable determines the locale used to translate double-quoted 4641strings preceded by a @samp{$} (@pxref{Locale Translation}). 4642 4643@item LC_NUMERIC 4644This variable determines the locale category used for number formatting. 4645 4646@item LINENO 4647The line number in the script or shell function currently executing. 4648 4649@item LINES 4650Used by the @code{select} builtin command to determine the column length 4651for printing selection lists. Automatically set upon receipt of a 4652@code{SIGWINCH}. 4653 4654@item MACHTYPE 4655A string that fully describes the system type on which Bash 4656is executing, in the standard @sc{gnu} @var{cpu-company-system} format. 4657 4658@item MAILCHECK 4659How often (in seconds) that the shell should check for mail in the 4660files specified in the @env{MAILPATH} or @env{MAIL} variables. 4661The default is 60 seconds. When it is time to check 4662for mail, the shell does so before displaying the primary prompt. 4663If this variable is unset, or set to a value that is not a number 4664greater than or equal to zero, the shell disables mail checking. 4665 4666@item OLDPWD 4667The previous working directory as set by the @code{cd} builtin. 4668 4669@item OPTERR 4670If set to the value 1, Bash displays error messages 4671generated by the @code{getopts} builtin command. 4672 4673@item OSTYPE 4674A string describing the operating system Bash is running on. 4675 4676@item PIPESTATUS 4677An array variable (@pxref{Arrays}) 4678containing a list of exit status values from the processes 4679in the most-recently-executed foreground pipeline (which may 4680contain only a single command). 4681 4682@item POSIXLY_CORRECT 4683If this variable is in the environment when @code{bash} starts, the shell 4684enters @sc{posix} mode (@pxref{Bash POSIX Mode}) before reading the 4685startup files, as if the @option{--posix} invocation option had been supplied. 4686If it is set while the shell is running, @code{bash} enables @sc{posix} mode, 4687as if the command 4688@example 4689@code{set -o posix} 4690@end example 4691@noindent 4692had been executed. 4693 4694@item PPID 4695The process @sc{id} of the shell's parent process. This variable 4696is readonly. 4697 4698@item PROMPT_COMMAND 4699If set, the value is interpreted as a command to execute 4700before the printing of each primary prompt (@env{$PS1}). 4701 4702@item PS3 4703The value of this variable is used as the prompt for the 4704@code{select} command. If this variable is not set, the 4705@code{select} command prompts with @samp{#? } 4706 4707@item PS4 4708The value is the prompt printed before the command line is echoed 4709when the @option{-x} option is set (@pxref{The Set Builtin}). 4710The first character of @env{PS4} is replicated multiple times, as 4711necessary, to indicate multiple levels of indirection. 4712The default is @samp{+ }. 4713 4714@item PWD 4715The current working directory as set by the @code{cd} builtin. 4716 4717@item RANDOM 4718Each time this parameter is referenced, a random integer 4719between 0 and 32767 is generated. Assigning a value to this 4720variable seeds the random number generator. 4721 4722@item REPLY 4723The default variable for the @code{read} builtin. 4724 4725@item SECONDS 4726This variable expands to the number of seconds since the 4727shell was started. Assignment to this variable resets 4728the count to the value assigned, and the expanded value 4729becomes the value assigned plus the number of seconds 4730since the assignment. 4731 4732@item SHELL 4733The full pathname to the shell is kept in this environment variable. 4734If it is not set when the shell starts, 4735Bash assigns to it the full pathname of the current user's login shell. 4736 4737@item SHELLOPTS 4738A colon-separated list of enabled shell options. Each word in 4739the list is a valid argument for the @option{-o} option to the 4740@code{set} builtin command (@pxref{The Set Builtin}). 4741The options appearing in @env{SHELLOPTS} are those reported 4742as @samp{on} by @samp{set -o}. 4743If this variable is in the environment when Bash 4744starts up, each shell option in the list will be enabled before 4745reading any startup files. This variable is readonly. 4746 4747@item SHLVL 4748Incremented by one each time a new instance of Bash is started. This is 4749intended to be a count of how deeply your Bash shells are nested. 4750 4751@item TIMEFORMAT 4752The value of this parameter is used as a format string specifying 4753how the timing information for pipelines prefixed with the @code{time} 4754reserved word should be displayed. 4755The @samp{%} character introduces an 4756escape sequence that is expanded to a time value or other 4757information. 4758The escape sequences and their meanings are as 4759follows; the braces denote optional portions. 4760 4761@table @code 4762 4763@item %% 4764A literal @samp{%}. 4765 4766@item %[@var{p}][l]R 4767The elapsed time in seconds. 4768 4769@item %[@var{p}][l]U 4770The number of CPU seconds spent in user mode. 4771 4772@item %[@var{p}][l]S 4773The number of CPU seconds spent in system mode. 4774 4775@item %P 4776The CPU percentage, computed as (%U + %S) / %R. 4777@end table 4778 4779The optional @var{p} is a digit specifying the precision, the number of 4780fractional digits after a decimal point. 4781A value of 0 causes no decimal point or fraction to be output. 4782At most three places after the decimal point may be specified; values 4783of @var{p} greater than 3 are changed to 3. 4784If @var{p} is not specified, the value 3 is used. 4785 4786The optional @code{l} specifies a longer format, including minutes, of 4787the form @var{MM}m@var{SS}.@var{FF}s. 4788The value of @var{p} determines whether or not the fraction is included. 4789 4790If this variable is not set, Bash acts as if it had the value 4791@example 4792@code{$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'} 4793@end example 4794If the value is null, no timing information is displayed. 4795A trailing newline is added when the format string is displayed. 4796 4797@item TMOUT 4798If set to a value greater than zero, @code{TMOUT} is treated as the 4799default timeout for the @code{read} builtin (@pxref{Bash Builtins}). 4800The @code{select} command (@pxref{Conditional Constructs}) terminates 4801if input does not arrive after @code{TMOUT} seconds when input is coming 4802from a terminal. 4803 4804In an interative shell, the value is interpreted as 4805the number of seconds to wait for input after issuing the primary 4806prompt when the shell is interactive. 4807Bash terminates after that number of seconds if input does 4808not arrive. 4809 4810@item TMPDIR 4811If set, Bash uses its value as the name of a directory in which 4812Bash creates temporary files for the shell's use. 4813 4814@item UID 4815The numeric real user id of the current user. This variable is readonly. 4816 4817@end vtable 4818 4819@node Bash Features 4820@chapter Bash Features 4821 4822This section describes features unique to Bash. 4823 4824@menu 4825* Invoking Bash:: Command line options that you can give 4826 to Bash. 4827* Bash Startup Files:: When and how Bash executes scripts. 4828* Interactive Shells:: What an interactive shell is. 4829* Bash Conditional Expressions:: Primitives used in composing expressions for 4830 the @code{test} builtin. 4831* Shell Arithmetic:: Arithmetic on shell variables. 4832* Aliases:: Substituting one command for another. 4833* Arrays:: Array Variables. 4834* The Directory Stack:: History of visited directories. 4835* Printing a Prompt:: Controlling the PS1 string. 4836* The Restricted Shell:: A more controlled mode of shell execution. 4837* Bash POSIX Mode:: Making Bash behave more closely to what 4838 the POSIX standard specifies. 4839@end menu 4840 4841@node Invoking Bash 4842@section Invoking Bash 4843 4844@example 4845bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] [@var{argument} @dots{}] 4846bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] -c @var{string} [@var{argument} @dots{}] 4847bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o @var{option}] [-O @var{shopt_option}] [@var{argument} @dots{}] 4848@end example 4849 4850In addition to the single-character shell command-line options 4851(@pxref{The Set Builtin}), there are several multi-character 4852options that you can use. These options must appear on the command 4853line before the single-character options to be recognized. 4854 4855@table @code 4856@item --debugger 4857Arrange for the debugger profile to be executed before the shell 4858starts. Turns on extended debugging mode (see @ref{Bash Builtins} 4859for a description of the @code{extdebug} option to the @code{shopt} 4860builtin) and shell function tracing 4861(see @ref{The Set Builtin} for a description of the @code{-o functrace} 4862option). 4863 4864@item --dump-po-strings 4865A list of all double-quoted strings preceded by @samp{$} 4866is printed on the standard output 4867in the @sc{gnu} @code{gettext} PO (portable object) file format. 4868Equivalent to @option{-D} except for the output format. 4869 4870@item --dump-strings 4871Equivalent to @option{-D}. 4872 4873@item --help 4874Display a usage message on standard output and exit sucessfully. 4875 4876@item --init-file @var{filename} 4877@itemx --rcfile @var{filename} 4878Execute commands from @var{filename} (instead of @file{~/.bashrc}) 4879in an interactive shell. 4880 4881@item --login 4882Equivalent to @option{-l}. 4883 4884@item --noediting 4885Do not use the @sc{gnu} Readline library (@pxref{Command Line Editing}) 4886to read command lines when the shell is interactive. 4887 4888@item --noprofile 4889Don't load the system-wide startup file @file{/etc/profile} 4890or any of the personal initialization files 4891@file{~/.bash_profile}, @file{~/.bash_login}, or @file{~/.profile} 4892when Bash is invoked as a login shell. 4893 4894@item --norc 4895Don't read the @file{~/.bashrc} initialization file in an 4896interactive shell. This is on by default if the shell is 4897invoked as @code{sh}. 4898 4899@item --posix 4900Change the behavior of Bash where the default operation differs 4901from the @sc{posix} standard to match the standard. This 4902is intended to make Bash behave as a strict superset of that 4903standard. @xref{Bash POSIX Mode}, for a description of the Bash 4904@sc{posix} mode. 4905 4906@item --restricted 4907Make the shell a restricted shell (@pxref{The Restricted Shell}). 4908 4909@item --verbose 4910Equivalent to @option{-v}. Print shell input lines as they're read. 4911 4912@item --version 4913Show version information for this instance of 4914Bash on the standard output and exit successfully. 4915 4916@end table 4917 4918There are several single-character options that may be supplied at 4919invocation which are not available with the @code{set} builtin. 4920 4921@table @code 4922@item -c @var{string} 4923Read and execute commands from @var{string} after processing the 4924options, then exit. Any remaining arguments are assigned to the 4925positional parameters, starting with @code{$0}. 4926 4927@item -i 4928Force the shell to run interactively. Interactive shells are 4929described in @ref{Interactive Shells}. 4930 4931@item -l 4932Make this shell act as if it had been directly invoked by login. 4933When the shell is interactive, this is equivalent to starting a 4934login shell with @samp{exec -l bash}. 4935When the shell is not interactive, the login shell startup files will 4936be executed. 4937@samp{exec bash -l} or @samp{exec bash --login} 4938will replace the current shell with a Bash login shell. 4939@xref{Bash Startup Files}, for a description of the special behavior 4940of a login shell. 4941 4942@item -r 4943Make the shell a restricted shell (@pxref{The Restricted Shell}). 4944 4945@item -s 4946If this option is present, or if no arguments remain after option 4947processing, then commands are read from the standard input. 4948This option allows the positional parameters to be set 4949when invoking an interactive shell. 4950 4951@item -D 4952A list of all double-quoted strings preceded by @samp{$} 4953is printed on the standard output. 4954These are the strings that 4955are subject to language translation when the current locale 4956is not @code{C} or @code{POSIX} (@pxref{Locale Translation}). 4957This implies the @option{-n} option; no commands will be executed. 4958 4959@item [-+]O [@var{shopt_option}] 4960@var{shopt_option} is one of the shell options accepted by the 4961@code{shopt} builtin (@pxref{Shell Builtin Commands}). 4962If @var{shopt_option} is present, @option{-O} sets the value of that option; 4963@option{+O} unsets it. 4964If @var{shopt_option} is not supplied, the names and values of the shell 4965options accepted by @code{shopt} are printed on the standard output. 4966If the invocation option is @option{+O}, the output is displayed in a format 4967that may be reused as input. 4968 4969@item -- 4970A @code{--} signals the end of options and disables further option 4971processing. 4972Any arguments after the @code{--} are treated as filenames and arguments. 4973 4974@end table 4975 4976@cindex login shell 4977A @emph{login} shell is one whose first character of argument zero is 4978@samp{-}, or one invoked with the @option{--login} option. 4979 4980@cindex interactive shell 4981An @emph{interactive} shell is one started without non-option arguments, 4982unless @option{-s} is specified, 4983without specifying the @option{-c} option, and whose input and output are both 4984connected to terminals (as determined by @code{isatty(3)}), or one 4985started with the @option{-i} option. @xref{Interactive Shells}, for more 4986information. 4987 4988If arguments remain after option processing, and neither the 4989@option{-c} nor the @option{-s} 4990option has been supplied, the first argument is assumed to 4991be the name of a file containing shell commands (@pxref{Shell Scripts}). 4992When Bash is invoked in this fashion, @code{$0} 4993is set to the name of the file, and the positional parameters 4994are set to the remaining arguments. 4995Bash reads and executes commands from this file, then exits. 4996Bash's exit status is the exit status of the last command executed 4997in the script. If no commands are executed, the exit status is 0. 4998 4999@node Bash Startup Files 5000@section Bash Startup Files 5001@cindex startup files 5002 5003This section describs how Bash executes its startup files. 5004If any of the files exist but cannot be read, Bash reports an error. 5005Tildes are expanded in file names as described above under 5006Tilde Expansion (@pxref{Tilde Expansion}). 5007 5008Interactive shells are described in @ref{Interactive Shells}. 5009 5010@subsubheading Invoked as an interactive login shell, or with @option{--login} 5011 5012When Bash is invoked as an interactive login shell, or as a 5013non-interactive shell with the @option{--login} option, it first reads and 5014executes commands from the file @file{/etc/profile}, if that file exists. 5015After reading that file, it looks for @file{~/.bash_profile}, 5016@file{~/.bash_login}, and @file{~/.profile}, in that order, and reads 5017and executes commands from the first one that exists and is readable. 5018The @option{--noprofile} option may be used when the shell is started to 5019inhibit this behavior. 5020 5021When a login shell exits, Bash reads and executes commands from 5022the file @file{~/.bash_logout}, if it exists. 5023 5024@subsubheading Invoked as an interactive non-login shell 5025 5026When an interactive shell that is not a login shell is started, Bash 5027reads and executes commands from @file{~/.bashrc}, if that file exists. 5028This may be inhibited by using the @option{--norc} option. 5029The @option{--rcfile @var{file}} option will force Bash to read and 5030execute commands from @var{file} instead of @file{~/.bashrc}. 5031 5032So, typically, your @file{~/.bash_profile} contains the line 5033@example 5034@code{if [ -f ~/.bashrc ]; then . ~/.bashrc; fi} 5035@end example 5036@noindent 5037after (or before) any login-specific initializations. 5038 5039@subsubheading Invoked non-interactively 5040 5041When Bash is started non-interactively, to run a shell script, 5042for example, it looks for the variable @env{BASH_ENV} in the environment, 5043expands its value if it appears there, and uses the expanded value as 5044the name of a file to read and execute. Bash behaves as if the 5045following command were executed: 5046@example 5047@code{if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi} 5048@end example 5049@noindent 5050but the value of the @env{PATH} variable is not used to search for the 5051file name. 5052 5053As noted above, if a non-interactive shell is invoked with the 5054@option{--login} option, Bash attempts to read and execute commands from the 5055login shell startup files. 5056 5057@subsubheading Invoked with name @code{sh} 5058 5059If Bash is invoked with the name @code{sh}, it tries to mimic the 5060startup behavior of historical versions of @code{sh} as closely as 5061possible, while conforming to the @sc{posix} standard as well. 5062 5063When invoked as an interactive login shell, or as a non-interactive 5064shell with the @option{--login} option, it first attempts to read 5065and execute commands from @file{/etc/profile} and @file{~/.profile}, in 5066that order. 5067The @option{--noprofile} option may be used to inhibit this behavior. 5068When invoked as an interactive shell with the name @code{sh}, Bash 5069looks for the variable @env{ENV}, expands its value if it is defined, 5070and uses the expanded value as the name of a file to read and execute. 5071Since a shell invoked as @code{sh} does not attempt to read and execute 5072commands from any other startup files, the @option{--rcfile} option has 5073no effect. 5074A non-interactive shell invoked with the name @code{sh} does not attempt 5075to read any other startup files. 5076 5077When invoked as @code{sh}, Bash enters @sc{posix} mode after 5078the startup files are read. 5079 5080@subsubheading Invoked in @sc{posix} mode 5081 5082When Bash is started in @sc{posix} mode, as with the 5083@option{--posix} command line option, it follows the @sc{posix} standard 5084for startup files. 5085In this mode, interactive shells expand the @env{ENV} variable 5086and commands are read and executed from the file whose name is the 5087expanded value. 5088No other startup files are read. 5089 5090@subsubheading Invoked by remote shell daemon 5091 5092Bash attempts to determine when it is being run by the remote shell 5093daemon, usually @code{rshd}. If Bash determines it is being run by 5094rshd, it reads and executes commands from @file{~/.bashrc}, if that 5095file exists and is readable. 5096It will not do this if invoked as @code{sh}. 5097The @option{--norc} option may be used to inhibit this behavior, and the 5098@option{--rcfile} option may be used to force another file to be read, but 5099@code{rshd} does not generally invoke the shell with those options or 5100allow them to be specified. 5101 5102@subsubheading Invoked with unequal effective and real @sc{uid/gid}s 5103 5104If Bash is started with the effective user (group) id not equal to the 5105real user (group) id, and the @code{-p} option is not supplied, no startup 5106files are read, shell functions are not inherited from the environment, 5107the @env{SHELLOPTS} variable, if it appears in the environment, is ignored, 5108and the effective user id is set to the real user id. 5109If the @code{-p} option is supplied at invocation, the startup behavior is 5110the same, but the effective user id is not reset. 5111 5112@node Interactive Shells 5113@section Interactive Shells 5114@cindex interactive shell 5115@cindex shell, interactive 5116 5117@menu 5118* What is an Interactive Shell?:: What determines whether a shell is Interactive. 5119* Is this Shell Interactive?:: How to tell if a shell is interactive. 5120* Interactive Shell Behavior:: What changes in a interactive shell? 5121@end menu 5122 5123@node What is an Interactive Shell? 5124@subsection What is an Interactive Shell? 5125 5126An interactive shell 5127is one started without non-option arguments, unless @option{-s} is 5128specified, without specifiying the @option{-c} option, and 5129whose input and error output are both 5130connected to terminals (as determined by @code{isatty(3)}), 5131or one started with the @option{-i} option. 5132 5133An interactive shell generally reads from and writes to a user's 5134terminal. 5135 5136The @option{-s} invocation option may be used to set the positional parameters 5137when an interactive shell is started. 5138 5139@node Is this Shell Interactive? 5140@subsection Is this Shell Interactive? 5141 5142To determine within a startup script whether or not Bash is 5143running interactively, 5144test the value of the @samp{-} special parameter. 5145It contains @code{i} when the shell is interactive. For example: 5146 5147@example 5148case "$-" in 5149*i*) echo This shell is interactive ;; 5150*) echo This shell is not interactive ;; 5151esac 5152@end example 5153 5154Alternatively, startup scripts may examine the variable 5155@env{PS1}; it is unset in non-interactive shells, and set in 5156interactive shells. Thus: 5157 5158@example 5159if [ -z "$PS1" ]; then 5160 echo This shell is not interactive 5161else 5162 echo This shell is interactive 5163fi 5164@end example 5165 5166@node Interactive Shell Behavior 5167@subsection Interactive Shell Behavior 5168 5169When the shell is running interactively, it changes its behavior in 5170several ways. 5171 5172@enumerate 5173@item 5174Startup files are read and executed as described in @ref{Bash Startup Files}. 5175 5176@item 5177Job Control (@pxref{Job Control}) is enabled by default. When job 5178control is in effect, Bash ignores the keyboard-generated job control 5179signals @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}. 5180 5181@item 5182Bash expands and displays @env{PS1} before reading the first line 5183of a command, and expands and displays @env{PS2} before reading the 5184second and subsequent lines of a multi-line command. 5185 5186@item 5187Bash executes the value of the @env{PROMPT_COMMAND} variable as a command 5188before printing the primary prompt, @env{$PS1} 5189(@pxref{Bash Variables}). 5190 5191@item 5192Readline (@pxref{Command Line Editing}) is used to read commands from 5193the user's terminal. 5194 5195@item 5196Bash inspects the value of the @code{ignoreeof} option to @code{set -o} 5197instead of exiting immediately when it receives an @code{EOF} on its 5198standard input when reading a command (@pxref{The Set Builtin}). 5199 5200@item 5201Command history (@pxref{Bash History Facilities}) 5202and history expansion (@pxref{History Interaction}) 5203are enabled by default. 5204Bash will save the command history to the file named by @env{$HISTFILE} 5205when an interactive shell exits. 5206 5207@item 5208Alias expansion (@pxref{Aliases}) is performed by default. 5209 5210@item 5211In the absence of any traps, Bash ignores @code{SIGTERM} 5212(@pxref{Signals}). 5213 5214@item 5215In the absence of any traps, @code{SIGINT} is caught and handled 5216((@pxref{Signals}). 5217@code{SIGINT} will interrupt some shell builtins. 5218 5219@item 5220An interactive login shell sends a @code{SIGHUP} to all jobs on exit 5221if the @code{hupoxexit} shell option has been enabled (@pxref{Signals}). 5222 5223@item 5224The @option{-n} invocation option is ignored, and @samp{set -n} has 5225no effect (@pxref{The Set Builtin}). 5226 5227@item 5228Bash will check for mail periodically, depending on the values of the 5229@env{MAIL}, @env{MAILPATH}, and @env{MAILCHECK} shell variables 5230(@pxref{Bash Variables}). 5231 5232@item 5233Expansion errors due to references to unbound shell variables after 5234@samp{set -u} has been enabled will not cause the shell to exit 5235(@pxref{The Set Builtin}). 5236 5237@item 5238The shell will not exit on expansion errors caused by @var{var} being unset 5239or null in @code{$@{@var{var}:?@var{word}@}} expansions 5240(@pxref{Shell Parameter Expansion}). 5241 5242@item 5243Redirection errors encountered by shell builtins will not cause the 5244shell to exit. 5245 5246@item 5247When running in @sc{posix} mode, a special builtin returning an error 5248status will not cause the shell to exit (@pxref{Bash POSIX Mode}). 5249 5250@item 5251A failed @code{exec} will not cause the shell to exit 5252(@pxref{Bourne Shell Builtins}). 5253 5254@item 5255Parser syntax errors will not cause the shell to exit. 5256 5257@item 5258Simple spelling correction for directory arguments to the @code{cd} 5259builtin is enabled by default (see the description of the @code{cdspell} 5260option to the @code{shopt} builtin in @ref{Bash Builtins}). 5261 5262@item 5263The shell will check the value of the @env{TMOUT} variable and exit 5264if a command is not read within the specified number of seconds after 5265printing @env{$PS1} (@pxref{Bash Variables}). 5266 5267@end enumerate 5268 5269@node Bash Conditional Expressions 5270@section Bash Conditional Expressions 5271@cindex expressions, conditional 5272 5273Conditional expressions are used by the @code{[[} compound command 5274and the @code{test} and @code{[} builtin commands. 5275 5276Expressions may be unary or binary. 5277Unary expressions are often used to examine the status of a file. 5278There are string operators and numeric comparison operators as well. 5279If the @var{file} argument to one of the primaries is of the form 5280@file{/dev/fd/@var{N}}, then file descriptor @var{N} is checked. 5281If the @var{file} argument to one of the primaries is one of 5282@file{/dev/stdin}, @file{/dev/stdout}, or @file{/dev/stderr}, file 5283descriptor 0, 1, or 2, respectively, is checked. 5284 5285Unless otherwise specified, primaries that operate on files follow symbolic 5286links and operate on the target of the link, rather than the link itself. 5287 5288@table @code 5289@item -a @var{file} 5290True if @var{file} exists. 5291 5292@item -b @var{file} 5293True if @var{file} exists and is a block special file. 5294 5295@item -c @var{file} 5296True if @var{file} exists and is a character special file. 5297 5298@item -d @var{file} 5299True if @var{file} exists and is a directory. 5300 5301@item -e @var{file} 5302True if @var{file} exists. 5303 5304@item -f @var{file} 5305True if @var{file} exists and is a regular file. 5306 5307@item -g @var{file} 5308True if @var{file} exists and its set-group-id bit is set. 5309 5310@item -h @var{file} 5311True if @var{file} exists and is a symbolic link. 5312 5313@item -k @var{file} 5314True if @var{file} exists and its "sticky" bit is set. 5315 5316@item -p @var{file} 5317True if @var{file} exists and is a named pipe (FIFO). 5318 5319@item -r @var{file} 5320True if @var{file} exists and is readable. 5321 5322@item -s @var{file} 5323True if @var{file} exists and has a size greater than zero. 5324 5325@item -t @var{fd} 5326True if file descriptor @var{fd} is open and refers to a terminal. 5327 5328@item -u @var{file} 5329True if @var{file} exists and its set-user-id bit is set. 5330 5331@item -w @var{file} 5332True if @var{file} exists and is writable. 5333 5334@item -x @var{file} 5335True if @var{file} exists and is executable. 5336 5337@item -O @var{file} 5338True if @var{file} exists and is owned by the effective user id. 5339 5340@item -G @var{file} 5341True if @var{file} exists and is owned by the effective group id. 5342 5343@item -L @var{file} 5344True if @var{file} exists and is a symbolic link. 5345 5346@item -S @var{file} 5347True if @var{file} exists and is a socket. 5348 5349@item -N @var{file} 5350True if @var{file} exists and has been modified since it was last read. 5351 5352@item @var{file1} -nt @var{file2} 5353True if @var{file1} is newer (according to modification date) 5354than @var{file2}, or if @var{file1} exists and @var{file2} does not. 5355 5356@item @var{file1} -ot @var{file2} 5357True if @var{file1} is older than @var{file2}, 5358or if @var{file2} exists and @var{file1} does not. 5359 5360@item @var{file1} -ef @var{file2} 5361True if @var{file1} and @var{file2} refer to the same device and 5362inode numbers. 5363 5364@item -o @var{optname} 5365True if shell option @var{optname} is enabled. 5366The list of options appears in the description of the @option{-o} 5367option to the @code{set} builtin (@pxref{The Set Builtin}). 5368 5369@item -z @var{string} 5370True if the length of @var{string} is zero. 5371 5372@item -n @var{string} 5373@itemx @var{string} 5374True if the length of @var{string} is non-zero. 5375 5376@item @var{string1} == @var{string2} 5377True if the strings are equal. 5378@samp{=} may be used in place of @samp{==} for strict @sc{posix} compliance. 5379 5380@item @var{string1} != @var{string2} 5381True if the strings are not equal. 5382 5383@item @var{string1} < @var{string2} 5384True if @var{string1} sorts before @var{string2} lexicographically 5385in the current locale. 5386 5387@item @var{string1} > @var{string2} 5388True if @var{string1} sorts after @var{string2} lexicographically 5389in the current locale. 5390 5391@item @var{arg1} OP @var{arg2} 5392@code{OP} is one of 5393@samp{-eq}, @samp{-ne}, @samp{-lt}, @samp{-le}, @samp{-gt}, or @samp{-ge}. 5394These arithmetic binary operators return true if @var{arg1} 5395is equal to, not equal to, less than, less than or equal to, 5396greater than, or greater than or equal to @var{arg2}, 5397respectively. @var{Arg1} and @var{arg2} 5398may be positive or negative integers. 5399 5400@end table 5401 5402@node Shell Arithmetic 5403@section Shell Arithmetic 5404@cindex arithmetic, shell 5405@cindex shell arithmetic 5406@cindex expressions, arithmetic 5407@cindex evaluation, arithmetic 5408@cindex arithmetic evaluation 5409 5410The shell allows arithmetic expressions to be evaluated, as one of 5411the shell expansions or by the @code{let} and the @option{-i} option 5412to the @code{declare} builtins. 5413 5414Evaluation is done in fixed-width integers with no check for overflow, 5415though division by 0 is trapped and flagged as an error. 5416The operators and their precedence, associativity, and values 5417are the same as in the C language. 5418The following list of operators is grouped into levels of 5419equal-precedence operators. 5420The levels are listed in order of decreasing precedence. 5421 5422@table @code 5423 5424@item @var{id}++ @var{id}-- 5425variable post-increment and post-decrement 5426 5427@item ++@var{id} --@var{id} 5428variable pre-increment and pre-decrement 5429 5430@item - + 5431unary minus and plus 5432 5433@item ! ~ 5434logical and bitwise negation 5435 5436@item ** 5437exponentiation 5438 5439@item * / % 5440multiplication, division, remainder 5441 5442@item + - 5443addition, subtraction 5444 5445@item << >> 5446left and right bitwise shifts 5447 5448@item <= >= < > 5449comparison 5450 5451@item == != 5452equality and inequality 5453 5454@item & 5455bitwise AND 5456 5457@item ^ 5458bitwise exclusive OR 5459 5460@item | 5461bitwise OR 5462 5463@item && 5464logical AND 5465 5466@item || 5467logical OR 5468 5469@item expr ? expr : expr 5470conditional operator 5471 5472@item = *= /= %= += -= <<= >>= &= ^= |= 5473assignment 5474 5475@item expr1 , expr2 5476comma 5477@end table 5478 5479Shell variables are allowed as operands; parameter expansion is 5480performed before the expression is evaluated. 5481Within an expression, shell variables may also be referenced by name 5482without using the parameter expansion syntax. 5483A shell variable that is null or unset evaluates to 0 when referenced 5484by name without using the parameter expansion syntax. 5485The value of a variable is evaluated as an arithmetic expression 5486when it is referenced, or when a variable which has been given the 5487@var{integer} attribute using @samp{declare -i} is assigned a value. 5488A null value evaluates to 0. 5489A shell variable need not have its integer attribute turned on 5490to be used in an expression. 5491 5492Constants with a leading 0 are interpreted as octal numbers. 5493A leading @samp{0x} or @samp{0X} denotes hexadecimal. Otherwise, 5494numbers take the form [@var{base}@code{#}]@var{n}, where @var{base} 5495is a decimal number between 2 and 64 representing the arithmetic 5496base, and @var{n} is a number in that base. If @var{base}@code{#} is 5497omitted, then base 10 is used. 5498The digits greater than 9 are represented by the lowercase letters, 5499the uppercase letters, @samp{@@}, and @samp{_}, in that order. 5500If @var{base} is less than or equal to 36, lowercase and uppercase 5501letters may be used interchangeably to represent numbers between 10 5502and 35. 5503 5504Operators are evaluated in order of precedence. Sub-expressions in 5505parentheses are evaluated first and may override the precedence 5506rules above. 5507 5508@node Aliases 5509@section Aliases 5510@cindex alias expansion 5511 5512@var{Aliases} allow a string to be substituted for a word when it is used 5513as the first word of a simple command. 5514The shell maintains a list of aliases that may be set and unset with 5515the @code{alias} and @code{unalias} builtin commands. 5516 5517The first word of each simple command, if unquoted, is checked to see 5518if it has an alias. 5519If so, that word is replaced by the text of the alias. 5520The characters @samp{/}, @samp{$}, @samp{`}, @samp{=} and any of the 5521shell metacharacters or quoting characters listed above may not appear 5522in an alias name. 5523The replacement text may contain any valid 5524shell input, including shell metacharacters. 5525The first word of the replacement text is tested for 5526aliases, but a word that is identical to an alias being expanded 5527is not expanded a second time. 5528This means that one may alias @code{ls} to @code{"ls -F"}, 5529for instance, and Bash does not try to recursively expand the 5530replacement text. If the last character of the alias value is a 5531space or tab character, then the next command word following the 5532alias is also checked for alias expansion. 5533 5534Aliases are created and listed with the @code{alias} 5535command, and removed with the @code{unalias} command. 5536 5537There is no mechanism for using arguments in the replacement text, 5538as in @code{csh}. 5539If arguments are needed, a shell function should be used 5540(@pxref{Shell Functions}). 5541 5542Aliases are not expanded when the shell is not interactive, 5543unless the @code{expand_aliases} shell option is set using 5544@code{shopt} (@pxref{Bash Builtins}). 5545 5546The rules concerning the definition and use of aliases are 5547somewhat confusing. Bash 5548always reads at least one complete line 5549of input before executing any 5550of the commands on that line. Aliases are expanded when a 5551command is read, not when it is executed. Therefore, an 5552alias definition appearing on the same line as another 5553command does not take effect until the next line of input is read. 5554The commands following the alias definition 5555on that line are not affected by the new alias. 5556This behavior is also an issue when functions are executed. 5557Aliases are expanded when a function definition is read, 5558not when the function is executed, because a function definition 5559is itself a compound command. As a consequence, aliases 5560defined in a function are not available until after that 5561function is executed. To be safe, always put 5562alias definitions on a separate line, and do not use @code{alias} 5563in compound commands. 5564 5565For almost every purpose, shell functions are preferred over aliases. 5566 5567@node Arrays 5568@section Arrays 5569@cindex arrays 5570 5571Bash provides one-dimensional array variables. Any variable may be used as 5572an array; the @code{declare} builtin will explicitly declare an array. 5573There is no maximum 5574limit on the size of an array, nor any requirement that members 5575be indexed or assigned contiguously. Arrays are zero-based. 5576 5577An array is created automatically if any variable is assigned to using 5578the syntax 5579@example 5580name[@var{subscript}]=@var{value} 5581@end example 5582 5583@noindent 5584The @var{subscript} 5585is treated as an arithmetic expression that must evaluate to a number 5586greater than or equal to zero. To explicitly declare an array, use 5587@example 5588declare -a @var{name} 5589@end example 5590@noindent 5591The syntax 5592@example 5593declare -a @var{name}[@var{subscript}] 5594@end example 5595@noindent 5596is also accepted; the @var{subscript} is ignored. Attributes may be 5597specified for an array variable using the @code{declare} and 5598@code{readonly} builtins. Each attribute applies to all members of 5599an array. 5600 5601Arrays are assigned to using compound assignments of the form 5602@example 5603name=(value@var{1} @dots{} value@var{n}) 5604@end example 5605@noindent 5606where each 5607@var{value} is of the form @code{[[@var{subscript}]=]}@var{string}. If 5608the optional subscript is supplied, that index is assigned to; 5609otherwise the index of the element assigned is the last index assigned 5610to by the statement plus one. Indexing starts at zero. 5611This syntax is also accepted by the @code{declare} 5612builtin. Individual array elements may be assigned to using the 5613@code{name[}@var{subscript}@code{]=}@var{value} syntax introduced above. 5614 5615Any element of an array may be referenced using 5616@code{$@{name[}@var{subscript}@code{]@}}. 5617The braces are required to avoid 5618conflicts with the shell's filename expansion operators. If the 5619@var{subscript} is @samp{@@} or @samp{*}, the word expands to all members 5620of the array @var{name}. These subscripts differ only when the word 5621appears within double quotes. 5622If the word is double-quoted, 5623@code{$@{name[*]@}} expands to a single word with 5624the value of each array member separated by the first character of the 5625@env{IFS} variable, and @code{$@{name[@@]@}} expands each element of 5626@var{name} to a separate word. When there are no array members, 5627@code{$@{name[@@]@}} expands to nothing. 5628If the double-quoted expansion occurs within a word, the expansion of 5629the first parameter is joined with the beginning part of the original 5630word, and the expansion of the last parameter is joined with the last 5631part of the original word. 5632This is analogous to the 5633expansion of the special parameters @samp{@@} and @samp{*}. 5634@code{$@{#name[}@var{subscript}@code{]@}} expands to the length of 5635@code{$@{name[}@var{subscript}@code{]@}}. 5636If @var{subscript} is @samp{@@} or 5637@samp{*}, the expansion is the number of elements in the array. 5638Referencing an array variable without a subscript is equivalent to 5639referencing element zero. 5640 5641The @code{unset} builtin is used to destroy arrays. 5642@code{unset} @var{name}[@var{subscript}] 5643destroys the array element at index @var{subscript}. 5644Care must be taken to avoid unwanted side effects caused by filename 5645generation. 5646@code{unset} @var{name}, where @var{name} is an array, removes the 5647entire array. A subscript of @samp{*} or @samp{@@} also removes the 5648entire array. 5649 5650The @code{declare}, @code{local}, and @code{readonly} 5651builtins each accept a @option{-a} 5652option to specify an array. The @code{read} 5653builtin accepts a @option{-a} 5654option to assign a list of words read from the standard input 5655to an array, and can read values from the standard input into 5656individual array elements. The @code{set} and @code{declare} 5657builtins display array values in a way that allows them to be 5658reused as input. 5659 5660@node The Directory Stack 5661@section The Directory Stack 5662@cindex directory stack 5663 5664@menu 5665* Directory Stack Builtins:: Bash builtin commands to manipulate 5666 the directory stack. 5667@end menu 5668 5669The directory stack is a list of recently-visited directories. The 5670@code{pushd} builtin adds directories to the stack as it changes 5671the current directory, and the @code{popd} builtin removes specified 5672directories from the stack and changes the current directory to 5673the directory removed. The @code{dirs} builtin displays the contents 5674of the directory stack. 5675 5676The contents of the directory stack are also visible 5677as the value of the @env{DIRSTACK} shell variable. 5678 5679@node Directory Stack Builtins 5680@subsection Directory Stack Builtins 5681 5682@table @code 5683 5684@item dirs 5685@btindex dirs 5686@example 5687dirs [+@var{N} | -@var{N}] [-clpv] 5688@end example 5689Display the list of currently remembered directories. Directories 5690are added to the list with the @code{pushd} command; the 5691@code{popd} command removes directories from the list. 5692@table @code 5693@item +@var{N} 5694Displays the @var{N}th directory (counting from the left of the 5695list printed by @code{dirs} when invoked without options), starting 5696with zero. 5697@item -@var{N} 5698Displays the @var{N}th directory (counting from the right of the 5699list printed by @code{dirs} when invoked without options), starting 5700with zero. 5701@item -c 5702Clears the directory stack by deleting all of the elements. 5703@item -l 5704Produces a longer listing; the default listing format uses a 5705tilde to denote the home directory. 5706@item -p 5707Causes @code{dirs} to print the directory stack with one entry per 5708line. 5709@item -v 5710Causes @code{dirs} to print the directory stack with one entry per 5711line, prefixing each entry with its index in the stack. 5712@end table 5713 5714@item popd 5715@btindex popd 5716@example 5717popd [+@var{N} | -@var{N}] [-n] 5718@end example 5719 5720Remove the top entry from the directory stack, and @code{cd} 5721to the new top directory. 5722When no arguments are given, @code{popd} 5723removes the top directory from the stack and 5724performs a @code{cd} to the new top directory. The 5725elements are numbered from 0 starting at the first directory listed with 5726@code{dirs}; i.e., @code{popd} is equivalent to @code{popd +0}. 5727@table @code 5728@item +@var{N} 5729Removes the @var{N}th directory (counting from the left of the 5730list printed by @code{dirs}), starting with zero. 5731@item -@var{N} 5732Removes the @var{N}th directory (counting from the right of the 5733list printed by @code{dirs}), starting with zero. 5734@item -n 5735Suppresses the normal change of directory when removing directories 5736from the stack, so that only the stack is manipulated. 5737@end table 5738 5739@btindex pushd 5740@item pushd 5741@example 5742pushd [@var{dir} | @var{+N} | @var{-N}] [-n] 5743@end example 5744 5745Save the current directory on the top of the directory stack 5746and then @code{cd} to @var{dir}. 5747With no arguments, @code{pushd} exchanges the top two directories. 5748 5749@table @code 5750@item +@var{N} 5751Brings the @var{N}th directory (counting from the left of the 5752list printed by @code{dirs}, starting with zero) to the top of 5753the list by rotating the stack. 5754@item -@var{N} 5755Brings the @var{N}th directory (counting from the right of the 5756list printed by @code{dirs}, starting with zero) to the top of 5757the list by rotating the stack. 5758@item -n 5759Suppresses the normal change of directory when adding directories 5760to the stack, so that only the stack is manipulated. 5761@item @var{dir} 5762Makes the current working directory be the top of the stack, and then 5763executes the equivalent of `@code{cd} @var{dir}'. 5764@code{cd}s to @var{dir}. 5765@end table 5766 5767@end table 5768 5769@node Printing a Prompt 5770@section Controlling the Prompt 5771@cindex prompting 5772 5773The value of the variable @env{PROMPT_COMMAND} is examined just before 5774Bash prints each primary prompt. If @env{PROMPT_COMMAND} is set and 5775has a non-null value, then the 5776value is executed just as if it had been typed on the command line. 5777 5778In addition, the following table describes the special characters which 5779can appear in the prompt variables: 5780 5781@table @code 5782@item \a 5783A bell character. 5784@item \d 5785The date, in "Weekday Month Date" format (e.g., "Tue May 26"). 5786@item \D@{@var{format}@} 5787The @var{format} is passed to @code{strftime}(3) and the result is inserted 5788into the prompt string; an empty @var{format} results in a locale-specific 5789time representation. The braces are required. 5790@item \e 5791An escape character. 5792@item \h 5793The hostname, up to the first `.'. 5794@item \H 5795The hostname. 5796@item \j 5797The number of jobs currently managed by the shell. 5798@item \l 5799The basename of the shell's terminal device name. 5800@item \n 5801A newline. 5802@item \r 5803A carriage return. 5804@item \s 5805The name of the shell, the basename of @code{$0} (the portion 5806following the final slash). 5807@item \t 5808The time, in 24-hour HH:MM:SS format. 5809@item \T 5810The time, in 12-hour HH:MM:SS format. 5811@item \@@ 5812The time, in 12-hour am/pm format. 5813@item \A 5814The time, in 24-hour HH:MM format. 5815@item \u 5816The username of the current user. 5817@item \v 5818The version of Bash (e.g., 2.00) 5819@item \V 5820The release of Bash, version + patchlevel (e.g., 2.00.0) 5821@item \w 5822The current working directory, with @env{$HOME} abbreviated with a tilde. 5823@item \W 5824The basename of @env{$PWD}, with @env{$HOME} abbreviated with a tilde. 5825@item \! 5826The history number of this command. 5827@item \# 5828The command number of this command. 5829@item \$ 5830If the effective uid is 0, @code{#}, otherwise @code{$}. 5831@item \@var{nnn} 5832The character whose ASCII code is the octal value @var{nnn}. 5833@item \\ 5834A backslash. 5835@item \[ 5836Begin a sequence of non-printing characters. This could be used to 5837embed a terminal control sequence into the prompt. 5838@item \] 5839End a sequence of non-printing characters. 5840@end table 5841 5842The command number and the history number are usually different: 5843the history number of a command is its position in the history 5844list, which may include commands restored from the history file 5845(@pxref{Bash History Facilities}), while the command number is 5846the position in the sequence of commands executed during the current 5847shell session. 5848 5849After the string is decoded, it is expanded via 5850parameter expansion, command substitution, arithmetic 5851expansion, and quote removal, subject to the value of the 5852@code{promptvars} shell option (@pxref{Bash Builtins}). 5853 5854@node The Restricted Shell 5855@section The Restricted Shell 5856@cindex restricted shell 5857 5858If Bash is started with the name @code{rbash}, or the 5859@option{--restricted} 5860or 5861@option{-r} 5862option is supplied at invocation, the shell becomes restricted. 5863A restricted shell is used to 5864set up an environment more controlled than the standard shell. 5865A restricted shell behaves identically to @code{bash} 5866with the exception that the following are disallowed or not performed: 5867 5868@itemize @bullet 5869@item 5870Changing directories with the @code{cd} builtin. 5871@item 5872Setting or unsetting the values of the @env{SHELL}, @env{PATH}, 5873@env{ENV}, or @env{BASH_ENV} variables. 5874@item 5875Specifying command names containing slashes. 5876@item 5877Specifying a filename containing a slash as an argument to the @code{.} 5878builtin command. 5879@item 5880Specifying a filename containing a slash as an argument to the @option{-p} 5881option to the @code{hash} builtin command. 5882@item 5883Importing function definitions from the shell environment at startup. 5884@item 5885Parsing the value of @env{SHELLOPTS} from the shell environment at startup. 5886@item 5887Redirecting output using the @samp{>}, @samp{>|}, @samp{<>}, @samp{>&}, 5888@samp{&>}, and @samp{>>} redirection operators. 5889@item 5890Using the @code{exec} builtin to replace the shell with another command. 5891@item 5892Adding or deleting builtin commands with the 5893@option{-f} and @option{-d} options to the @code{enable} builtin. 5894@item 5895Using the @code{enable} builtin command to enable disabled shell builtins. 5896@item 5897Specifying the @option{-p} option to the @code{command} builtin. 5898@item 5899Turning off restricted mode with @samp{set +r} or @samp{set +o restricted}. 5900@end itemize 5901 5902These restrictions are enforced after any startup files are read. 5903 5904When a command that is found to be a shell script is executed 5905(@pxref{Shell Scripts}), @code{rbash} turns off any restrictions in 5906the shell spawned to execute the script. 5907 5908@node Bash POSIX Mode 5909@section Bash POSIX Mode 5910@cindex POSIX Mode 5911 5912Starting Bash with the @option{--posix} command-line option or executing 5913@samp{set -o posix} while Bash is running will cause Bash to conform more 5914closely to the @sc{posix} standard by changing the behavior to 5915match that specified by @sc{posix} in areas where the Bash default differs. 5916 5917When invoked as @code{sh}, Bash enters @sc{posix} mode after reading the 5918startup files. 5919 5920The following list is what's changed when `@sc{posix} mode' is in effect: 5921 5922@enumerate 5923@item 5924When a command in the hash table no longer exists, Bash will re-search 5925@env{$PATH} to find the new location. This is also available with 5926@samp{shopt -s checkhash}. 5927 5928@item 5929The message printed by the job control code and builtins when a job 5930exits with a non-zero status is `Done(status)'. 5931 5932@item 5933The message printed by the job control code and builtins when a job 5934is stopped is `Stopped(@var{signame})', where @var{signame} is, for 5935example, @code{SIGTSTP}. 5936 5937@item 5938The @code{bg} builtin uses the required format to describe each job placed 5939in the background, which does not include an indication of whether the job 5940is the current or previous job. 5941 5942@item 5943Reserved words appearing in a context where reserved words are recognized 5944do not undergo alias expansion. 5945 5946@item 5947The @sc{posix} @env{PS1} and @env{PS2} expansions of @samp{!} to 5948the history number and @samp{!!} to @samp{!} are enabled, 5949and parameter expansion is performed on the values of @env{PS1} and 5950@env{PS2} regardless of the setting of the @code{promptvars} option. 5951 5952@item 5953The @sc{posix} startup files are executed (@env{$ENV}) rather than 5954the normal Bash files. 5955 5956@item 5957Tilde expansion is only performed on assignments preceding a command 5958name, rather than on all assignment statements on the line. 5959 5960@item 5961The default history file is @file{~/.sh_history} (this is the 5962default value of @env{$HISTFILE}). 5963 5964@item 5965The output of @samp{kill -l} prints all the signal names on a single line, 5966separated by spaces, without the @samp{SIG} prefix. 5967 5968@item 5969The @code{kill} builtin does not accept signal names with a @samp{SIG} 5970prefix. 5971 5972@item 5973Non-interactive shells exit if @var{filename} in @code{.} @var{filename} 5974is not found. 5975 5976@item 5977Non-interactive shells exit if a syntax error in an arithmetic expansion 5978results in an invalid expression. 5979 5980@item 5981Redirection operators do not perform filename expansion on the word 5982in the redirection unless the shell is interactive. 5983 5984@item 5985Redirection operators do not perform word splitting on the word in the 5986redirection. 5987 5988@item 5989Function names must be valid shell @code{name}s. That is, they may not 5990contain characters other than letters, digits, and underscores, and 5991may not start with a digit. Declaring a function with an invalid name 5992causes a fatal syntax error in non-interactive shells. 5993 5994@item 5995@sc{posix} special builtins are found before shell functions 5996during command lookup. 5997 5998@item 5999If a @sc{posix} special builtin returns an error status, a 6000non-interactive shell exits. The fatal errors are those listed in 6001the POSIX standard, and include things like passing incorrect options, 6002redirection errors, variable assignment errors for assignments preceding 6003the command name, and so on. 6004 6005@item 6006If @env{CDPATH} is set, the @code{cd} builtin will not implicitly 6007append the current directory to it. This means that @code{cd} will 6008fail if no valid directory name can be constructed from 6009any of the entries in @env{$CDPATH}, even if the a directory with 6010the same name as the name given as an argument to @code{cd} exists 6011in the current directory. 6012 6013@item 6014A non-interactive shell exits with an error status if a variable 6015assignment error occurs when no command name follows the assignment 6016statements. 6017A variable assignment error occurs, for example, when trying to assign 6018a value to a readonly variable. 6019 6020@item 6021A non-interactive shell exits with an error status if the iteration 6022variable in a @code{for} statement or the selection variable in a 6023@code{select} statement is a readonly variable. 6024 6025@item 6026Process substitution is not available. 6027 6028@item 6029Assignment statements preceding @sc{posix} special builtins 6030persist in the shell environment after the builtin completes. 6031 6032@item 6033Assignment statements preceding shell function calls persist in the 6034shell environment after the function returns, as if a @sc{posix} 6035special builtin command had been executed. 6036 6037@item 6038The @code{export} and @code{readonly} builtin commands display their 6039output in the format required by @sc{posix}. 6040 6041@item 6042The @code{trap} builtin displays signal names without the leading 6043@code{SIG}. 6044 6045@item 6046The @code{trap} builtin doesn't check the first argument for a possible 6047signal specification and revert the signal handling to the original 6048disposition if it is, unless that argument consists solely of digits and 6049is a valid signal number. If users want to reset the handler for a given 6050signal to the original disposition, they should use @samp{-} as the 6051first argument. 6052 6053@item 6054The @code{.} and @code{source} builtins do not search the current directory 6055for the filename argument if it is not found by searching @env{PATH}. 6056 6057@item 6058Subshells spawned to execute command substitutions inherit the value of 6059the @option{-e} option from the parent shell. When not in @sc{posix} mode, 6060Bash clears the @option{-e} option in such subshells. 6061 6062@item 6063Alias expansion is always enabled, even in non-interactive shells. 6064 6065@item 6066When the @code{alias} builtin displays alias definitions, it does not 6067display them with a leading @samp{alias } unless the @option{-p} option 6068is supplied. 6069 6070@item 6071When the @code{set} builtin is invoked without options, it does not display 6072shell function names and definitions. 6073 6074@item 6075When the @code{set} builtin is invoked without options, it displays 6076variable values without quotes, unless they contain shell metacharacters, 6077even if the result contains nonprinting characters. 6078 6079@item 6080When the @code{cd} builtin is invoked in @var{logical} mode, and the pathname 6081constructed from @code{$PWD} and the directory name supplied as an argument 6082does not refer to an existing directory, @code{cd} will fail instead of 6083falling back to @var{physical} mode. 6084 6085@item 6086When the @code{pwd} builtin is supplied the @option{-P} option, it resets 6087@code{$PWD} to a pathname containing no symlinks. 6088 6089@item 6090The @code{pwd} builtin verifies that the value it prints is the same as the 6091current directory, even if it is not asked to check the file system with the 6092@option{-P} option. 6093 6094@item 6095When listing the history, the @code{fc} builtin does not include an 6096indication of whether or not a history entry has been modified. 6097 6098@item 6099The default editor used by @code{fc} is @code{ed}. 6100 6101@item 6102The @code{type} and @code{command} builtins will not report a non-executable 6103file as having been found, though the shell will attempt to execute such a 6104file if it is the only so-named file found in @code{$PATH}. 6105 6106@item 6107The @code{vi} editing mode will invoke the @code{vi} editor directly when 6108the @samp{v} command is run, instead of checking @code{$FCEDIT} and 6109@code{$EDITOR}. 6110 6111@item 6112When the @code{xpg_echo} option is enabled, Bash does not attempt to interpret 6113any arguments to @code{echo} as options. Each argument is displayed, after 6114escape characters are converted. 6115 6116@end enumerate 6117 6118There is other @sc{posix} behavior that Bash does not implement by 6119default even when in @sc{posix} mode. 6120Specifically: 6121 6122@enumerate 6123 6124@item 6125The @code{fc} builtin checks @code{$EDITOR} as a program to edit history 6126entries if @code{FCEDIT} is unset, rather than defaulting directly to 6127@code{ed}. @code{fc} uses @code{ed} if @code{EDITOR} is unset. 6128 6129@item 6130As noted above, Bash requires the @code{xpg_echo} option to be enabled for 6131the @code{echo} builtin to be fully conformant. 6132 6133@end enumerate 6134 6135Bash can be configured to be @sc{posix}-conformant by default, by specifying 6136the @option{--enable-strict-posix-default} to @code{configure} when building 6137(@pxref{Optional Features}). 6138 6139@node Job Control 6140@chapter Job Control 6141 6142This chapter discusses what job control is, how it works, and how 6143Bash allows you to access its facilities. 6144 6145@menu 6146* Job Control Basics:: How job control works. 6147* Job Control Builtins:: Bash builtin commands used to interact 6148 with job control. 6149* Job Control Variables:: Variables Bash uses to customize job 6150 control. 6151@end menu 6152 6153@node Job Control Basics 6154@section Job Control Basics 6155@cindex job control 6156@cindex foreground 6157@cindex background 6158@cindex suspending jobs 6159 6160Job control 6161refers to the ability to selectively stop (suspend) 6162the execution of processes and continue (resume) 6163their execution at a later point. A user typically employs 6164this facility via an interactive interface supplied jointly 6165by the system's terminal driver and Bash. 6166 6167The shell associates a @var{job} with each pipeline. It keeps a 6168table of currently executing jobs, which may be listed with the 6169@code{jobs} command. When Bash starts a job 6170asynchronously, it prints a line that looks 6171like: 6172@example 6173[1] 25647 6174@end example 6175@noindent 6176indicating that this job is job number 1 and that the process @sc{id} 6177of the last process in the pipeline associated with this job is 617825647. All of the processes in a single pipeline are members of 6179the same job. Bash uses the @var{job} abstraction as the 6180basis for job control. 6181 6182To facilitate the implementation of the user interface to job 6183control, the operating system maintains the notion of a current terminal 6184process group @sc{id}. Members of this process group (processes whose 6185process group @sc{id} is equal to the current terminal process group 6186@sc{id}) receive keyboard-generated signals such as @code{SIGINT}. 6187These processes are said to be in the foreground. Background 6188processes are those whose process group @sc{id} differs from the 6189terminal's; such processes are immune to keyboard-generated 6190signals. Only foreground processes are allowed to read from or 6191write to the terminal. Background processes which attempt to 6192read from (write to) the terminal are sent a @code{SIGTTIN} 6193(@code{SIGTTOU}) signal by the terminal driver, which, unless 6194caught, suspends the process. 6195 6196If the operating system on which Bash is running supports 6197job control, Bash contains facilities to use it. Typing the 6198@var{suspend} character (typically @samp{^Z}, Control-Z) while a 6199process is running causes that process to be stopped and returns 6200control to Bash. Typing the @var{delayed suspend} character 6201(typically @samp{^Y}, Control-Y) causes the process to be stopped 6202when it attempts to read input from the terminal, and control to 6203be returned to Bash. The user then manipulates the state of 6204this job, using the @code{bg} command to continue it in the 6205background, the @code{fg} command to continue it in the 6206foreground, or the @code{kill} command to kill it. A @samp{^Z} 6207takes effect immediately, and has the additional side effect of 6208causing pending output and typeahead to be discarded. 6209 6210There are a number of ways to refer to a job in the shell. The 6211character @samp{%} introduces a job name. 6212 6213Job number @code{n} may be referred to as @samp{%n}. 6214The symbols @samp{%%} and @samp{%+} refer to the shell's notion of the 6215current job, which is the last job stopped while it was in the foreground 6216or started in the background. 6217A single @samp{%} (with no accompanying job specification) also refers 6218to the current job. 6219The previous job may be referenced using @samp{%-}. In output 6220pertaining to jobs (e.g., the output of the @code{jobs} command), 6221the current job is always flagged with a @samp{+}, and the 6222previous job with a @samp{-}. 6223 6224A job may also be referred to 6225using a prefix of the name used to start it, or using a substring 6226that appears in its command line. For example, @samp{%ce} refers 6227to a stopped @code{ce} job. Using @samp{%?ce}, on the 6228other hand, refers to any job containing the string @samp{ce} in 6229its command line. If the prefix or substring matches more than one job, 6230Bash reports an error. 6231 6232Simply naming a job can be used to bring it into the foreground: 6233@samp{%1} is a synonym for @samp{fg %1}, bringing job 1 from the 6234background into the foreground. Similarly, @samp{%1 &} resumes 6235job 1 in the background, equivalent to @samp{bg %1} 6236 6237The shell learns immediately whenever a job changes state. 6238Normally, Bash waits until it is about to print a prompt 6239before reporting changes in a job's status so as to not interrupt 6240any other output. 6241If the @option{-b} option to the @code{set} builtin is enabled, 6242Bash reports such changes immediately (@pxref{The Set Builtin}). 6243Any trap on @code{SIGCHLD} is executed for each child process 6244that exits. 6245 6246If an attempt to exit Bash is made while jobs are stopped, the 6247shell prints a message warning that there are stopped jobs. 6248The @code{jobs} command may then be used to inspect their status. 6249If a second attempt to exit is made without an intervening command, 6250Bash does not print another warning, and the stopped jobs are terminated. 6251 6252@node Job Control Builtins 6253@section Job Control Builtins 6254 6255@table @code 6256 6257@item bg 6258@btindex bg 6259@example 6260bg [@var{jobspec} @dots{}] 6261@end example 6262Resume each suspended job @var{jobspec} in the background, as if it 6263had been started with @samp{&}. 6264If @var{jobspec} is not supplied, the current job is used. 6265The return status is zero unless it is run when job control is not 6266enabled, or, when run with job control enabled, any 6267@var{jobspec} was not found or specifies a job 6268that was started without job control. 6269 6270@item fg 6271@btindex fg 6272@example 6273fg [@var{jobspec}] 6274@end example 6275Resume the job @var{jobspec} in the foreground and make it the current job. 6276If @var{jobspec} is not supplied, the current job is used. 6277The return status is that of the command placed into the foreground, 6278or non-zero if run when job control is disabled or, when run with 6279job control enabled, @var{jobspec} does not specify a valid job or 6280@var{jobspec} specifies a job that was started without job control. 6281 6282@item jobs 6283@btindex jobs 6284@example 6285jobs [-lnprs] [@var{jobspec}] 6286jobs -x @var{command} [@var{arguments}] 6287@end example 6288 6289The first form lists the active jobs. The options have the 6290following meanings: 6291 6292@table @code 6293@item -l 6294List process @sc{id}s in addition to the normal information. 6295 6296@item -n 6297Display information only about jobs that have changed status since 6298the user was last notified of their status. 6299 6300@item -p 6301List only the process @sc{id} of the job's process group leader. 6302 6303@item -r 6304Restrict output to running jobs. 6305 6306@item -s 6307Restrict output to stopped jobs. 6308@end table 6309 6310If @var{jobspec} is given, 6311output is restricted to information about that job. 6312If @var{jobspec} is not supplied, the status of all jobs is 6313listed. 6314 6315If the @option{-x} option is supplied, @code{jobs} replaces any 6316@var{jobspec} found in @var{command} or @var{arguments} with the 6317corresponding process group @sc{id}, and executes @var{command}, 6318passing it @var{argument}s, returning its exit status. 6319 6320@item kill 6321@btindex kill 6322@example 6323kill [-s @var{sigspec}] [-n @var{signum}] [-@var{sigspec}] @var{jobspec} or @var{pid} 6324kill -l [@var{exit_status}] 6325@end example 6326Send a signal specified by @var{sigspec} or @var{signum} to the process 6327named by job specification @var{jobspec} or process @sc{id} @var{pid}. 6328@var{sigspec} is either a case-insensitive signal name such as 6329@code{SIGINT} (with or without the @code{SIG} prefix) 6330or a signal number; @var{signum} is a signal number. 6331If @var{sigspec} and @var{signum} are not present, @code{SIGTERM} is used. 6332The @option{-l} option lists the signal names. 6333If any arguments are supplied when @option{-l} is given, the names of the 6334signals corresponding to the arguments are listed, and the return status 6335is zero. 6336@var{exit_status} is a number specifying a signal number or the exit 6337status of a process terminated by a signal. 6338The return status is zero if at least one signal was successfully sent, 6339or non-zero if an error occurs or an invalid option is encountered. 6340 6341@item wait 6342@btindex wait 6343@example 6344wait [@var{jobspec} or @var{pid} ...] 6345@end example 6346Wait until the child process specified by each process @sc{id} @var{pid} 6347or job specification @var{jobspec} exits and return the exit status of the 6348last command waited for. 6349If a job spec is given, all processes in the job are waited for. 6350If no arguments are given, all currently active child processes are 6351waited for, and the return status is zero. 6352If neither @var{jobspec} nor @var{pid} specifies an active child process 6353of the shell, the return status is 127. 6354 6355@item disown 6356@btindex disown 6357@example 6358disown [-ar] [-h] [@var{jobspec} @dots{}] 6359@end example 6360Without options, each @var{jobspec} is removed from the table of 6361active jobs. 6362If the @option{-h} option is given, the job is not removed from the table, 6363but is marked so that @code{SIGHUP} is not sent to the job if the shell 6364receives a @code{SIGHUP}. 6365If @var{jobspec} is not present, and neither the @option{-a} nor @option{-r} 6366option is supplied, the current job is used. 6367If no @var{jobspec} is supplied, the @option{-a} option means to remove or 6368mark all jobs; the @option{-r} option without a @var{jobspec} 6369argument restricts operation to running jobs. 6370 6371@item suspend 6372@btindex suspend 6373@example 6374suspend [-f] 6375@end example 6376Suspend the execution of this shell until it receives a 6377@code{SIGCONT} signal. The @option{-f} option means to suspend 6378even if the shell is a login shell. 6379 6380@end table 6381 6382When job control is not active, the @code{kill} and @code{wait} 6383builtins do not accept @var{jobspec} arguments. They must be 6384supplied process @sc{id}s. 6385 6386@node Job Control Variables 6387@section Job Control Variables 6388 6389@vtable @code 6390 6391@item auto_resume 6392This variable controls how the shell interacts with the user and 6393job control. If this variable exists then single word simple 6394commands without redirections are treated as candidates for resumption 6395of an existing job. There is no ambiguity allowed; if there is 6396more than one job beginning with the string typed, then 6397the most recently accessed job will be selected. 6398The name of a stopped job, in this context, is the command line 6399used to start it. If this variable is set to the value @samp{exact}, 6400the string supplied must match the name of a stopped job exactly; 6401if set to @samp{substring}, 6402the string supplied needs to match a substring of the name of a 6403stopped job. The @samp{substring} value provides functionality 6404analogous to the @samp{%?} job @sc{id} (@pxref{Job Control Basics}). 6405If set to any other value, the supplied string must 6406be a prefix of a stopped job's name; this provides functionality 6407analogous to the @samp{%} job @sc{id}. 6408 6409@end vtable 6410 6411@set readline-appendix 6412@set history-appendix 6413@cindex Readline, how to use 6414@include rluser.texi 6415@cindex History, how to use 6416@include hsuser.texi 6417@clear readline-appendix 6418@clear history-appendix 6419 6420@node Installing Bash 6421@chapter Installing Bash 6422 6423This chapter provides basic instructions for installing Bash on 6424the various supported platforms. The distribution supports the 6425@sc{gnu} operating systems, nearly every version of Unix, and several 6426non-Unix systems such as BeOS and Interix. 6427Other independent ports exist for 6428@sc{ms-dos}, @sc{os/2}, and Windows platforms. 6429 6430@menu 6431* Basic Installation:: Installation instructions. 6432* Compilers and Options:: How to set special options for various 6433 systems. 6434* Compiling For Multiple Architectures:: How to compile Bash for more 6435 than one kind of system from 6436 the same source tree. 6437* Installation Names:: How to set the various paths used by the installation. 6438* Specifying the System Type:: How to configure Bash for a particular system. 6439* Sharing Defaults:: How to share default configuration values among GNU 6440 programs. 6441* Operation Controls:: Options recognized by the configuration program. 6442* Optional Features:: How to enable and disable optional features when 6443 building Bash. 6444@end menu 6445 6446@node Basic Installation 6447@section Basic Installation 6448@cindex installation 6449@cindex configuration 6450@cindex Bash installation 6451@cindex Bash configuration 6452 6453These are installation instructions for Bash. 6454 6455The simplest way to compile Bash is: 6456 6457@enumerate 6458@item 6459@code{cd} to the directory containing the source code and type 6460@samp{./configure} to configure Bash for your system. If you're 6461using @code{csh} on an old version of System V, you might need to 6462type @samp{sh ./configure} instead to prevent @code{csh} from trying 6463to execute @code{configure} itself. 6464 6465Running @code{configure} takes some time. 6466While running, it prints messages telling which features it is 6467checking for. 6468 6469@item 6470Type @samp{make} to compile Bash and build the @code{bashbug} bug 6471reporting script. 6472 6473@item 6474Optionally, type @samp{make tests} to run the Bash test suite. 6475 6476@item 6477Type @samp{make install} to install @code{bash} and @code{bashbug}. 6478This will also install the manual pages and Info file. 6479 6480@end enumerate 6481 6482The @code{configure} shell script attempts to guess correct 6483values for various system-dependent variables used during 6484compilation. It uses those values to create a @file{Makefile} in 6485each directory of the package (the top directory, the 6486@file{builtins}, @file{doc}, and @file{support} directories, 6487each directory under @file{lib}, and several others). It also creates a 6488@file{config.h} file containing system-dependent definitions. 6489Finally, it creates a shell script named @code{config.status} that you 6490can run in the future to recreate the current configuration, a 6491file @file{config.cache} that saves the results of its tests to 6492speed up reconfiguring, and a file @file{config.log} containing 6493compiler output (useful mainly for debugging @code{configure}). 6494If at some point 6495@file{config.cache} contains results you don't want to keep, you 6496may remove or edit it. 6497 6498To find out more about the options and arguments that the 6499@code{configure} script understands, type 6500 6501@example 6502bash-2.04$ ./configure --help 6503@end example 6504 6505@noindent 6506at the Bash prompt in your Bash source directory. 6507 6508If you need to do unusual things to compile Bash, please 6509try to figure out how @code{configure} could check whether or not 6510to do them, and mail diffs or instructions to 6511@email{bash-maintainers@@gnu.org} so they can be 6512considered for the next release. 6513 6514The file @file{configure.in} is used to create @code{configure} 6515by a program called Autoconf. You only need 6516@file{configure.in} if you want to change it or regenerate 6517@code{configure} using a newer version of Autoconf. If 6518you do this, make sure you are using Autoconf version 2.50 or 6519newer. 6520 6521You can remove the program binaries and object files from the 6522source code directory by typing @samp{make clean}. To also remove the 6523files that @code{configure} created (so you can compile Bash for 6524a different kind of computer), type @samp{make distclean}. 6525 6526@node Compilers and Options 6527@section Compilers and Options 6528 6529Some systems require unusual options for compilation or linking 6530that the @code{configure} script does not know about. You can 6531give @code{configure} initial values for variables by setting 6532them in the environment. Using a Bourne-compatible shell, you 6533can do that on the command line like this: 6534 6535@example 6536CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure 6537@end example 6538 6539On systems that have the @code{env} program, you can do it like this: 6540 6541@example 6542env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure 6543@end example 6544 6545The configuration process uses GCC to build Bash if it 6546is available. 6547 6548@node Compiling For Multiple Architectures 6549@section Compiling For Multiple Architectures 6550 6551You can compile Bash for more than one kind of computer at the 6552same time, by placing the object files for each architecture in their 6553own directory. To do this, you must use a version of @code{make} that 6554supports the @code{VPATH} variable, such as GNU @code{make}. 6555@code{cd} to the 6556directory where you want the object files and executables to go and run 6557the @code{configure} script from the source directory. You may need to 6558supply the @option{--srcdir=PATH} argument to tell @code{configure} where the 6559source files are. @code{configure} automatically checks for the 6560source code in the directory that @code{configure} is in and in `..'. 6561 6562If you have to use a @code{make} that does not supports the @code{VPATH} 6563variable, you can compile Bash for one architecture at a 6564time in the source code directory. After you have installed 6565Bash for one architecture, use @samp{make distclean} before 6566reconfiguring for another architecture. 6567 6568Alternatively, if your system supports symbolic links, you can use the 6569@file{support/mkclone} script to create a build tree which has 6570symbolic links back to each file in the source directory. Here's an 6571example that creates a build directory in the current directory from a 6572source directory @file{/usr/gnu/src/bash-2.0}: 6573 6574@example 6575bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 . 6576@end example 6577 6578@noindent 6579The @code{mkclone} script requires Bash, so you must have already built 6580Bash for at least one architecture before you can create build 6581directories for other architectures. 6582 6583@node Installation Names 6584@section Installation Names 6585 6586By default, @samp{make install} will install into 6587@file{/usr/local/bin}, @file{/usr/local/man}, etc. You can 6588specify an installation prefix other than @file{/usr/local} by 6589giving @code{configure} the option @option{--prefix=@var{PATH}}, 6590or by specifying a value for the @code{DESTDIR} @samp{make} 6591variable when running @samp{make install}. 6592 6593You can specify separate installation prefixes for 6594architecture-specific files and architecture-independent files. 6595If you give @code{configure} the option 6596@option{--exec-prefix=@var{PATH}}, @samp{make install} will use 6597@var{PATH} as the prefix for installing programs and libraries. 6598Documentation and other data files will still use the regular prefix. 6599 6600@node Specifying the System Type 6601@section Specifying the System Type 6602 6603There may be some features @code{configure} can not figure out 6604automatically, but need to determine by the type of host Bash 6605will run on. Usually @code{configure} can figure that 6606out, but if it prints a message saying it can not guess the host 6607type, give it the @option{--host=TYPE} option. @samp{TYPE} can 6608either be a short name for the system type, such as @samp{sun4}, 6609or a canonical name with three fields: @samp{CPU-COMPANY-SYSTEM} 6610(e.g., @samp{i386-unknown-freebsd4.2}). 6611 6612See the file @file{support/config.sub} for the possible 6613values of each field. 6614 6615@node Sharing Defaults 6616@section Sharing Defaults 6617 6618If you want to set default values for @code{configure} scripts to 6619share, you can create a site shell script called 6620@code{config.site} that gives default values for variables like 6621@code{CC}, @code{cache_file}, and @code{prefix}. @code{configure} 6622looks for @file{PREFIX/share/config.site} if it exists, then 6623@file{PREFIX/etc/config.site} if it exists. Or, you can set the 6624@code{CONFIG_SITE} environment variable to the location of the site 6625script. A warning: the Bash @code{configure} looks for a site script, 6626but not all @code{configure} scripts do. 6627 6628@node Operation Controls 6629@section Operation Controls 6630 6631@code{configure} recognizes the following options to control how it 6632operates. 6633 6634@table @code 6635 6636@item --cache-file=@var{file} 6637Use and save the results of the tests in 6638@var{file} instead of @file{./config.cache}. Set @var{file} to 6639@file{/dev/null} to disable caching, for debugging 6640@code{configure}. 6641 6642@item --help 6643Print a summary of the options to @code{configure}, and exit. 6644 6645@item --quiet 6646@itemx --silent 6647@itemx -q 6648Do not print messages saying which checks are being made. 6649 6650@item --srcdir=@var{dir} 6651Look for the Bash source code in directory @var{dir}. Usually 6652@code{configure} can determine that directory automatically. 6653 6654@item --version 6655Print the version of Autoconf used to generate the @code{configure} 6656script, and exit. 6657@end table 6658 6659@code{configure} also accepts some other, not widely used, boilerplate 6660options. @samp{configure --help} prints the complete list. 6661 6662@node Optional Features 6663@section Optional Features 6664 6665The Bash @code{configure} has a number of @option{--enable-@var{feature}} 6666options, where @var{feature} indicates an optional part of Bash. 6667There are also several @option{--with-@var{package}} options, 6668where @var{package} is something like @samp{bash-malloc} or @samp{purify}. 6669To turn off the default use of a package, use 6670@option{--without-@var{package}}. To configure Bash without a feature 6671that is enabled by default, use @option{--disable-@var{feature}}. 6672 6673Here is a complete list of the @option{--enable-} and 6674@option{--with-} options that the Bash @code{configure} recognizes. 6675 6676@table @code 6677@item --with-afs 6678Define if you are using the Andrew File System from Transarc. 6679 6680@item --with-bash-malloc 6681Use the Bash version of 6682@code{malloc} in the directory @file{lib/malloc}. This is not the same 6683@code{malloc} that appears in @sc{gnu} libc, but an older version 6684originally derived from the 4.2 @sc{bsd} @code{malloc}. This @code{malloc} 6685is very fast, but wastes some space on each allocation. 6686This option is enabled by default. 6687The @file{NOTES} file contains a list of systems for 6688which this should be turned off, and @code{configure} disables this 6689option automatically for a number of systems. 6690 6691@item --with-curses 6692Use the curses library instead of the termcap library. This should 6693be supplied if your system has an inadequate or incomplete termcap 6694database. 6695 6696@item --with-gnu-malloc 6697A synonym for @code{--with-bash-malloc}. 6698 6699@item --with-installed-readline[=@var{PREFIX}] 6700Define this to make Bash link with a locally-installed version of Readline 6701rather than the version in @file{lib/readline}. This works only with 6702Readline 5.0 and later versions. If @var{PREFIX} is @code{yes} or not 6703supplied, @code{configure} uses the values of the make variables 6704@code{includedir} and @code{libdir}, which are subdirectories of @code{prefix} 6705by default, to find the installed version of Readline if it is not in 6706the standard system include and library directories. 6707If @var{PREFIX} is @code{no}, Bash links with the version in 6708@file{lib/readline}. 6709If @var{PREFIX} is set to any other value, @code{configure} treats it as 6710a directory pathname and looks for 6711the installed version of Readline in subdirectories of that directory 6712(include files in @var{PREFIX}/@code{include} and the library in 6713@var{PREFIX}/@code{lib}). 6714 6715@item --with-purify 6716Define this to use the Purify memory allocation checker from Rational 6717Software. 6718 6719@item --enable-minimal-config 6720This produces a shell with minimal features, close to the historical 6721Bourne shell. 6722@end table 6723 6724There are several @option{--enable-} options that alter how Bash is 6725compiled and linked, rather than changing run-time features. 6726 6727@table @code 6728@item --enable-largefile 6729Enable support for @uref{http://www.sas.com/standards/large_file/x_open.20Mar96.html, 6730large files} if the operating system requires special compiler options 6731to build programs which can access large files. This is enabled by 6732default, if the operating system provides large file support. 6733 6734@item --enable-profiling 6735This builds a Bash binary that produces profiling information to be 6736processed by @code{gprof} each time it is executed. 6737 6738@item --enable-static-link 6739This causes Bash to be linked statically, if @code{gcc} is being used. 6740This could be used to build a version to use as root's shell. 6741@end table 6742 6743The @samp{minimal-config} option can be used to disable all of 6744the following options, but it is processed first, so individual 6745options may be enabled using @samp{enable-@var{feature}}. 6746 6747All of the following options except for @samp{disabled-builtins} and 6748@samp{xpg-echo-default} are 6749enabled by default, unless the operating system does not provide the 6750necessary support. 6751 6752@table @code 6753@item --enable-alias 6754Allow alias expansion and include the @code{alias} and @code{unalias} 6755builtins (@pxref{Aliases}). 6756 6757@item --enable-arith-for-command 6758Include support for the alternate form of the @code{for} command 6759that behaves like the C language @code{for} statement 6760(@pxref{Looping Constructs}). 6761 6762@item --enable-array-variables 6763Include support for one-dimensional array shell variables 6764(@pxref{Arrays}). 6765 6766@item --enable-bang-history 6767Include support for @code{csh}-like history substitution 6768(@pxref{History Interaction}). 6769 6770@item --enable-brace-expansion 6771Include @code{csh}-like brace expansion 6772( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ). 6773See @ref{Brace Expansion}, for a complete description. 6774 6775@item --enable-command-timing 6776Include support for recognizing @code{time} as a reserved word and for 6777displaying timing statistics for the pipeline following @code{time} 6778(@pxref{Pipelines}). 6779This allows pipelines as well as shell builtins and functions to be timed. 6780 6781@item --enable-cond-command 6782Include support for the @code{[[} conditional command. 6783(@pxref{Conditional Constructs}). 6784 6785@item --enable-cond-regexp 6786Include support for matching POSIX regular expressions using the 6787@samp{=~} binary operator in the @code{[[} conditional command. 6788(@pxref{Conditional Constructs}). 6789 6790@item --enable-debugger 6791Include support for the bash debugger (distributed separately). 6792 6793@item --enable-directory-stack 6794Include support for a @code{csh}-like directory stack and the 6795@code{pushd}, @code{popd}, and @code{dirs} builtins 6796(@pxref{The Directory Stack}). 6797 6798@item --enable-disabled-builtins 6799Allow builtin commands to be invoked via @samp{builtin xxx} 6800even after @code{xxx} has been disabled using @samp{enable -n xxx}. 6801See @ref{Bash Builtins}, for details of the @code{builtin} and 6802@code{enable} builtin commands. 6803 6804@item --enable-dparen-arithmetic 6805Include support for the @code{((@dots{}))} command 6806(@pxref{Conditional Constructs}). 6807 6808@item --enable-extended-glob 6809Include support for the extended pattern matching features described 6810above under @ref{Pattern Matching}. 6811 6812@item --enable-help-builtin 6813Include the @code{help} builtin, which displays help on shell builtins and 6814variables (@pxref{Bash Builtins}). 6815 6816@item --enable-history 6817Include command history and the @code{fc} and @code{history} 6818builtin commands (@pxref{Bash History Facilities}). 6819 6820@item --enable-job-control 6821This enables the job control features (@pxref{Job Control}), 6822if the operating system supports them. 6823 6824@item --enable-multibyte 6825This enables support for multibyte characters if the operating 6826system provides the necessary support. 6827 6828@item --enable-net-redirections 6829This enables the special handling of filenames of the form 6830@code{/dev/tcp/@var{host}/@var{port}} and 6831@code{/dev/udp/@var{host}/@var{port}} 6832when used in redirections (@pxref{Redirections}). 6833 6834@item --enable-process-substitution 6835This enables process substitution (@pxref{Process Substitution}) if 6836the operating system provides the necessary support. 6837 6838@item --enable-progcomp 6839Enable the programmable completion facilities 6840(@pxref{Programmable Completion}). 6841If Readline is not enabled, this option has no effect. 6842 6843@item --enable-prompt-string-decoding 6844Turn on the interpretation of a number of backslash-escaped characters 6845in the @env{$PS1}, @env{$PS2}, @env{$PS3}, and @env{$PS4} prompt 6846strings. See @ref{Printing a Prompt}, for a complete list of prompt 6847string escape sequences. 6848 6849@item --enable-readline 6850Include support for command-line editing and history with the Bash 6851version of the Readline library (@pxref{Command Line Editing}). 6852 6853@item --enable-restricted 6854Include support for a @dfn{restricted shell}. If this is enabled, Bash, 6855when called as @code{rbash}, enters a restricted mode. See 6856@ref{The Restricted Shell}, for a description of restricted mode. 6857 6858@item --enable-select 6859Include the @code{select} builtin, which allows the generation of simple 6860menus (@pxref{Conditional Constructs}). 6861 6862@item --enable-separate-helpfiles 6863Use external files for the documentation displayed by the @code{help} builtin 6864instead of storing the text internally. 6865 6866@item --enable-single-help-strings 6867Store the text displayed by the @code{help} builtin as a single string for 6868each help topic. This aids in translating the text to different languages. 6869You may need to disable this if your compiler cannot handle very long string 6870literals. 6871 6872@item --enable-strict-posix-default 6873Make Bash @sc{posix}-conformant by default (@pxref{Bash POSIX Mode}). 6874 6875@item --enable-usg-echo-default 6876A synonym for @code{--enable-xpg-echo-default}. 6877 6878@item --enable-xpg-echo-default 6879Make the @code{echo} builtin expand backslash-escaped characters by default, 6880without requiring the @option{-e} option. 6881This sets the default value of the @code{xpg_echo} shell option to @code{on}, 6882which makes the Bash @code{echo} behave more like the version specified in 6883the Single Unix Specification, version 3. 6884@xref{Bash Builtins}, for a description of the escape sequences that 6885@code{echo} recognizes. 6886 6887@end table 6888 6889The file @file{config-top.h} contains C Preprocessor 6890@samp{#define} statements for options which are not settable from 6891@code{configure}. 6892Some of these are not meant to be changed; beware of the consequences if 6893you do. 6894Read the comments associated with each definition for more 6895information about its effect. 6896 6897@node Reporting Bugs 6898@appendix Reporting Bugs 6899 6900Please report all bugs you find in Bash. 6901But first, you should 6902make sure that it really is a bug, and that it appears in the latest 6903version of Bash. 6904The latest version of Bash is always available for FTP from 6905@uref{ftp://ftp.gnu.org/pub/bash/}. 6906 6907Once you have determined that a bug actually exists, use the 6908@code{bashbug} command to submit a bug report. 6909If you have a fix, you are encouraged to mail that as well! 6910Suggestions and `philosophical' bug reports may be mailed 6911to @email{bug-bash@@gnu.org} or posted to the Usenet 6912newsgroup @code{gnu.bash.bug}. 6913 6914All bug reports should include: 6915@itemize @bullet 6916@item 6917The version number of Bash. 6918@item 6919The hardware and operating system. 6920@item 6921The compiler used to compile Bash. 6922@item 6923A description of the bug behaviour. 6924@item 6925A short script or `recipe' which exercises the bug and may be used 6926to reproduce it. 6927@end itemize 6928 6929@noindent 6930@code{bashbug} inserts the first three items automatically into 6931the template it provides for filing a bug report. 6932 6933Please send all reports concerning this manual to 6934@email{chet@@po.CWRU.Edu}. 6935 6936@node Major Differences From The Bourne Shell 6937@appendix Major Differences From The Bourne Shell 6938 6939Bash implements essentially the same grammar, parameter and 6940variable expansion, redirection, and quoting as the Bourne Shell. 6941Bash uses the @sc{posix} standard as the specification of 6942how these features are to be implemented. There are some 6943differences between the traditional Bourne shell and Bash; this 6944section quickly details the differences of significance. A 6945number of these differences are explained in greater depth in 6946previous sections. 6947This section uses the version of @code{sh} included in SVR4.2 (the 6948last version of the historical Bourne shell) as the baseline reference. 6949 6950@itemize @bullet 6951 6952@item 6953Bash is @sc{posix}-conformant, even where the @sc{posix} specification 6954differs from traditional @code{sh} behavior (@pxref{Bash POSIX Mode}). 6955 6956@item 6957Bash has multi-character invocation options (@pxref{Invoking Bash}). 6958 6959@item 6960Bash has command-line editing (@pxref{Command Line Editing}) and 6961the @code{bind} builtin. 6962 6963@item 6964Bash provides a programmable word completion mechanism 6965(@pxref{Programmable Completion}), and two builtin commands, 6966@code{complete} and @code{compgen}, to manipulate it. 6967 6968@item 6969Bash has command history (@pxref{Bash History Facilities}) and the 6970@code{history} and @code{fc} builtins to manipulate it. 6971The Bash history list maintains timestamp information and uses the 6972value of the @code{HISTTIMEFORMAT} variable to display it. 6973 6974@item 6975Bash implements @code{csh}-like history expansion 6976(@pxref{History Interaction}). 6977 6978@item 6979Bash has one-dimensional array variables (@pxref{Arrays}), and the 6980appropriate variable expansions and assignment syntax to use them. 6981Several of the Bash builtins take options to act on arrays. 6982Bash provides a number of built-in array variables. 6983 6984@item 6985The @code{$'@dots{}'} quoting syntax, which expands ANSI-C 6986backslash-escaped characters in the text between the single quotes, 6987is supported (@pxref{ANSI-C Quoting}). 6988 6989@item 6990Bash supports the @code{$"@dots{}"} quoting syntax to do 6991locale-specific translation of the characters between the double 6992quotes. The @option{-D}, @option{--dump-strings}, and @option{--dump-po-strings} 6993invocation options list the translatable strings found in a script 6994(@pxref{Locale Translation}). 6995 6996@item 6997Bash implements the @code{!} keyword to negate the return value of 6998a pipeline (@pxref{Pipelines}). 6999Very useful when an @code{if} statement needs to act only if a test fails. 7000The Bash @samp{-o pipefail} option to @code{set} will cause a pipeline to 7001return a failure status if any command fails. 7002 7003@item 7004Bash has the @code{time} reserved word and command timing (@pxref{Pipelines}). 7005The display of the timing statistics may be controlled with the 7006@env{TIMEFORMAT} variable. 7007 7008@item 7009Bash implements the @code{for (( @var{expr1} ; @var{expr2} ; @var{expr3} ))} 7010arithmetic for command, similar to the C language (@pxref{Looping Constructs}). 7011 7012@item 7013Bash includes the @code{select} compound command, which allows the 7014generation of simple menus (@pxref{Conditional Constructs}). 7015 7016@item 7017Bash includes the @code{[[} compound command, which makes conditional 7018testing part of the shell grammar (@pxref{Conditional Constructs}), including 7019optional regular expression matching. 7020 7021@item 7022Bash provides optional case-insensitive matching for the @code{case} and 7023@code{[[} constructs. 7024 7025@item 7026Bash includes brace expansion (@pxref{Brace Expansion}) and tilde 7027expansion (@pxref{Tilde Expansion}). 7028 7029@item 7030Bash implements command aliases and the @code{alias} and @code{unalias} 7031builtins (@pxref{Aliases}). 7032 7033@item 7034Bash provides shell arithmetic, the @code{((} compound command 7035(@pxref{Conditional Constructs}), 7036and arithmetic expansion (@pxref{Shell Arithmetic}). 7037 7038@item 7039Variables present in the shell's initial environment are automatically 7040exported to child processes. The Bourne shell does not normally do 7041this unless the variables are explicitly marked using the @code{export} 7042command. 7043 7044@item 7045Bash supports the @samp{+=} assignment operator, which appends to the value 7046of the variable named on the left hand side. 7047 7048@item 7049Bash includes the @sc{posix} pattern removal @samp{%}, @samp{#}, @samp{%%} 7050and @samp{##} expansions to remove leading or trailing substrings from 7051variable values (@pxref{Shell Parameter Expansion}). 7052 7053@item 7054The expansion @code{$@{#xx@}}, which returns the length of @code{$@{xx@}}, 7055is supported (@pxref{Shell Parameter Expansion}). 7056 7057@item 7058The expansion @code{$@{var:}@var{offset}@code{[:}@var{length}@code{]@}}, 7059which expands to the substring of @code{var}'s value of length 7060@var{length}, beginning at @var{offset}, is present 7061(@pxref{Shell Parameter Expansion}). 7062 7063@item 7064The expansion 7065@code{$@{var/[/]}@var{pattern}@code{[/}@var{replacement}@code{]@}}, 7066which matches @var{pattern} and replaces it with @var{replacement} in 7067the value of @code{var}, is available (@pxref{Shell Parameter Expansion}). 7068 7069@item 7070The expansion @code{$@{!@var{prefix@}*}} expansion, which expands to 7071the names of all shell variables whose names begin with @var{prefix}, 7072is available (@pxref{Shell Parameter Expansion}). 7073 7074@item 7075Bash has @var{indirect} variable expansion using @code{$@{!word@}} 7076(@pxref{Shell Parameter Expansion}). 7077 7078@item 7079Bash can expand positional parameters beyond @code{$9} using 7080@code{$@{@var{num}@}}. 7081 7082@item 7083The @sc{posix} @code{$()} form of command substitution 7084is implemented (@pxref{Command Substitution}), 7085and preferred to the Bourne shell's @code{``} (which 7086is also implemented for backwards compatibility). 7087 7088@item 7089Bash has process substitution (@pxref{Process Substitution}). 7090 7091@item 7092Bash automatically assigns variables that provide information about the 7093current user (@env{UID}, @env{EUID}, and @env{GROUPS}), the current host 7094(@env{HOSTTYPE}, @env{OSTYPE}, @env{MACHTYPE}, and @env{HOSTNAME}), 7095and the instance of Bash that is running (@env{BASH}, 7096@env{BASH_VERSION}, and @env{BASH_VERSINFO}). @xref{Bash Variables}, 7097for details. 7098 7099@item 7100The @env{IFS} variable is used to split only the results of expansion, 7101not all words (@pxref{Word Splitting}). 7102This closes a longstanding shell security hole. 7103 7104@item 7105Bash implements the full set of @sc{posix} filename expansion operators, 7106including @var{character classes}, @var{equivalence classes}, and 7107@var{collating symbols} (@pxref{Filename Expansion}). 7108 7109@item 7110Bash implements extended pattern matching features when the @code{extglob} 7111shell option is enabled (@pxref{Pattern Matching}). 7112 7113@item 7114It is possible to have a variable and a function with the same name; 7115@code{sh} does not separate the two name spaces. 7116 7117@item 7118Bash functions are permitted to have local variables using the 7119@code{local} builtin, and thus useful recursive functions may be written 7120(@pxref{Bash Builtins}). 7121 7122@item 7123Variable assignments preceding commands affect only that command, even 7124builtins and functions (@pxref{Environment}). 7125In @code{sh}, all variable assignments 7126preceding commands are global unless the command is executed from the 7127file system. 7128 7129@item 7130Bash performs filename expansion on filenames specified as operands 7131to input and output redirection operators (@pxref{Redirections}). 7132 7133@item 7134Bash contains the @samp{<>} redirection operator, allowing a file to be 7135opened for both reading and writing, and the @samp{&>} redirection 7136operator, for directing standard output and standard error to the same 7137file (@pxref{Redirections}). 7138 7139@item 7140Bash includes the @samp{<<<} redirection operator, allowing a string to 7141be used as the standard input to a command. 7142 7143@item 7144Bash implements the @samp{[n]<&@var{word}} and @samp{[n]>&@var{word}} 7145redirection operators, which move one file descriptor to another. 7146 7147@item 7148Bash treats a number of filenames specially when they are 7149used in redirection operators (@pxref{Redirections}). 7150 7151@item 7152Bash can open network connections to arbitrary machines and services 7153with the redirection operators (@pxref{Redirections}). 7154 7155@item 7156The @code{noclobber} option is available to avoid overwriting existing 7157files with output redirection (@pxref{The Set Builtin}). 7158The @samp{>|} redirection operator may be used to override @code{noclobber}. 7159 7160@item 7161The Bash @code{cd} and @code{pwd} builtins (@pxref{Bourne Shell Builtins}) 7162each take @option{-L} and @option{-P} options to switch between logical and 7163physical modes. 7164 7165@item 7166Bash allows a function to override a builtin with the same name, and provides 7167access to that builtin's functionality within the function via the 7168@code{builtin} and @code{command} builtins (@pxref{Bash Builtins}). 7169 7170@item 7171The @code{command} builtin allows selective disabling of functions 7172when command lookup is performed (@pxref{Bash Builtins}). 7173 7174@item 7175Individual builtins may be enabled or disabled using the @code{enable} 7176builtin (@pxref{Bash Builtins}). 7177 7178@item 7179The Bash @code{exec} builtin takes additional options that allow users 7180to control the contents of the environment passed to the executed 7181command, and what the zeroth argument to the command is to be 7182(@pxref{Bourne Shell Builtins}). 7183 7184@item 7185Shell functions may be exported to children via the environment 7186using @code{export -f} (@pxref{Shell Functions}). 7187 7188@item 7189The Bash @code{export}, @code{readonly}, and @code{declare} builtins can 7190take a @option{-f} option to act on shell functions, a @option{-p} option to 7191display variables with various attributes set in a format that can be 7192used as shell input, a @option{-n} option to remove various variable 7193attributes, and @samp{name=value} arguments to set variable attributes 7194and values simultaneously. 7195 7196@item 7197The Bash @code{hash} builtin allows a name to be associated with 7198an arbitrary filename, even when that filename cannot be found by 7199searching the @env{$PATH}, using @samp{hash -p} 7200(@pxref{Bourne Shell Builtins}). 7201 7202@item 7203Bash includes a @code{help} builtin for quick reference to shell 7204facilities (@pxref{Bash Builtins}). 7205 7206@item 7207The @code{printf} builtin is available to display formatted output 7208(@pxref{Bash Builtins}). 7209 7210@item 7211The Bash @code{read} builtin (@pxref{Bash Builtins}) 7212will read a line ending in @samp{\} with 7213the @option{-r} option, and will use the @env{REPLY} variable as a 7214default if no non-option arguments are supplied. 7215The Bash @code{read} builtin 7216also accepts a prompt string with the @option{-p} option and will use 7217Readline to obtain the line when given the @option{-e} option. 7218The @code{read} builtin also has additional options to control input: 7219the @option{-s} option will turn off echoing of input characters as 7220they are read, the @option{-t} option will allow @code{read} to time out 7221if input does not arrive within a specified number of seconds, the 7222@option{-n} option will allow reading only a specified number of 7223characters rather than a full line, and the @option{-d} option will read 7224until a particular character rather than newline. 7225 7226@item 7227The @code{return} builtin may be used to abort execution of scripts 7228executed with the @code{.} or @code{source} builtins 7229(@pxref{Bourne Shell Builtins}). 7230 7231@item 7232Bash includes the @code{shopt} builtin, for finer control of shell 7233optional capabilities (@pxref{Bash Builtins}), and allows these options 7234to be set and unset at shell invocation (@pxref{Invoking Bash}). 7235 7236@item 7237Bash has much more optional behavior controllable with the @code{set} 7238builtin (@pxref{The Set Builtin}). 7239 7240@item 7241The @samp{-x} (@code{xtrace}) option displays commands other than 7242simple commands when performing an execution trace 7243(@pxref{The Set Builtin}). 7244 7245@item 7246The @code{test} builtin (@pxref{Bourne Shell Builtins}) 7247is slightly different, as it implements the @sc{posix} algorithm, 7248which specifies the behavior based on the number of arguments. 7249 7250@item 7251Bash includes the @code{caller} builtin, which displays the context of 7252any active subroutine call (a shell function or a script executed with 7253the @code{.} or @code{source} builtins). This supports the bash 7254debugger. 7255 7256@item 7257The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a 7258@code{DEBUG} pseudo-signal specification, similar to @code{EXIT}. 7259Commands specified with a @code{DEBUG} trap are executed before every 7260simple command, @code{for} command, @code{case} command, 7261@code{select} command, every arithmetic @code{for} command, and before 7262the first command executes in a shell function. 7263The @code{DEBUG} trap is not inherited by shell functions unless the 7264function has been given the @code{trace} attribute or the 7265@code{functrace} option has been enabled using the @code{shopt} builtin. 7266The @code{extdebug} shell option has additional effects on the 7267@code{DEBUG} trap. 7268 7269The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows an 7270@code{ERR} pseudo-signal specification, similar to @code{EXIT} and @code{DEBUG}. 7271Commands specified with an @code{ERR} trap are executed after a simple 7272command fails, with a few exceptions. 7273The @code{ERR} trap is not inherited by shell functions unless the 7274@code{-o errtrace} option to the @code{set} builtin is enabled. 7275 7276The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a 7277@code{RETURN} pseudo-signal specification, similar to 7278@code{EXIT} and @code{DEBUG}. 7279Commands specified with an @code{RETURN} trap are executed before 7280execution resumes after a shell function or a shell script executed with 7281@code{.} or @code{source} returns. 7282The @code{RETURN} trap is not inherited by shell functions unless the 7283function has been given the @code{trace} attribute or the 7284@code{functrace} option has been enabled using the @code{shopt} builtin. 7285 7286@item 7287The Bash @code{type} builtin is more extensive and gives more information 7288about the names it finds (@pxref{Bash Builtins}). 7289 7290@item 7291The Bash @code{umask} builtin permits a @option{-p} option to cause 7292the output to be displayed in the form of a @code{umask} command 7293that may be reused as input (@pxref{Bourne Shell Builtins}). 7294 7295@item 7296Bash implements a @code{csh}-like directory stack, and provides the 7297@code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it 7298(@pxref{The Directory Stack}). 7299Bash also makes the directory stack visible as the value of the 7300@env{DIRSTACK} shell variable. 7301 7302@item 7303Bash interprets special backslash-escaped characters in the prompt 7304strings when interactive (@pxref{Printing a Prompt}). 7305 7306@item 7307The Bash restricted mode is more useful (@pxref{The Restricted Shell}); 7308the SVR4.2 shell restricted mode is too limited. 7309 7310@item 7311The @code{disown} builtin can remove a job from the internal shell 7312job table (@pxref{Job Control Builtins}) or suppress the sending 7313of @code{SIGHUP} to a job when the shell exits as the result of a 7314@code{SIGHUP}. 7315 7316@item 7317Bash includes a number of features to support a separate debugger for 7318shell scripts. 7319 7320@item 7321The SVR4.2 shell has two privilege-related builtins 7322(@code{mldmode} and @code{priv}) not present in Bash. 7323 7324@item 7325Bash does not have the @code{stop} or @code{newgrp} builtins. 7326 7327@item 7328Bash does not use the @env{SHACCT} variable or perform shell accounting. 7329 7330@item 7331The SVR4.2 @code{sh} uses a @env{TIMEOUT} variable like Bash uses 7332@env{TMOUT}. 7333 7334@end itemize 7335 7336@noindent 7337More features unique to Bash may be found in @ref{Bash Features}. 7338 7339 7340@appendixsec Implementation Differences From The SVR4.2 Shell 7341 7342Since Bash is a completely new implementation, it does not suffer from 7343many of the limitations of the SVR4.2 shell. For instance: 7344 7345@itemize @bullet 7346 7347@item 7348Bash does not fork a subshell when redirecting into or out of 7349a shell control structure such as an @code{if} or @code{while} 7350statement. 7351 7352@item 7353Bash does not allow unbalanced quotes. The SVR4.2 shell will silently 7354insert a needed closing quote at @code{EOF} under certain circumstances. 7355This can be the cause of some hard-to-find errors. 7356 7357@item 7358The SVR4.2 shell uses a baroque memory management scheme based on 7359trapping @code{SIGSEGV}. If the shell is started from a process with 7360@code{SIGSEGV} blocked (e.g., by using the @code{system()} C library 7361function call), it misbehaves badly. 7362 7363@item 7364In a questionable attempt at security, the SVR4.2 shell, 7365when invoked without the @option{-p} option, will alter its real 7366and effective @sc{uid} and @sc{gid} if they are less than some 7367magic threshold value, commonly 100. 7368This can lead to unexpected results. 7369 7370@item 7371The SVR4.2 shell does not allow users to trap @code{SIGSEGV}, 7372@code{SIGALRM}, or @code{SIGCHLD}. 7373 7374@item 7375The SVR4.2 shell does not allow the @env{IFS}, @env{MAILCHECK}, 7376@env{PATH}, @env{PS1}, or @env{PS2} variables to be unset. 7377 7378@item 7379The SVR4.2 shell treats @samp{^} as the undocumented equivalent of 7380@samp{|}. 7381 7382@item 7383Bash allows multiple option arguments when it is invoked (@code{-x -v}); 7384the SVR4.2 shell allows only one option argument (@code{-xv}). In 7385fact, some versions of the shell dump core if the second argument begins 7386with a @samp{-}. 7387 7388@item 7389The SVR4.2 shell exits a script if any builtin fails; Bash exits 7390a script only if one of the @sc{posix} special builtins fails, and 7391only for certain failures, as enumerated in the @sc{posix} standard. 7392 7393@item 7394The SVR4.2 shell behaves differently when invoked as @code{jsh} 7395(it turns on job control). 7396@end itemize 7397 7398@node Copying This Manual 7399@appendix Copying This Manual 7400 7401@menu 7402* GNU Free Documentation License:: License for copying this manual. 7403@end menu 7404 7405@include fdl.texi 7406 7407@node Builtin Index 7408@unnumbered Index of Shell Builtin Commands 7409@printindex bt 7410 7411@node Reserved Word Index 7412@unnumbered Index of Shell Reserved Words 7413@printindex rw 7414 7415@node Variable Index 7416@unnumbered Parameter and Variable Index 7417@printindex vr 7418 7419@node Function Index 7420@unnumbered Function Index 7421@printindex fn 7422 7423@node Concept Index 7424@unnumbered Concept Index 7425@printindex cp 7426 7427@bye 7428