1\input texinfo.tex @c -*- texinfo -*- 2@c %**start of header 3@setfilename bash.info 4@settitle Bash Reference Manual 5 6@include version.texi 7@c %**end of header 8 9@copying 10This text is a brief description of the features that are present in 11the Bash shell (version @value{VERSION}, @value{UPDATED}) 12 13This is Edition @value{EDITION}, last updated @value{UPDATED}, 14of @cite{The GNU Bash Reference Manual}, 15for @code{Bash}, Version @value{VERSION}. 16 17Copyright @copyright{} 1988--2020 Free Software Foundation, Inc. 18 19@quotation 20Permission is granted to copy, distribute and/or modify this document 21under the terms of the GNU Free Documentation License, Version 1.3 or 22any later version published by the Free Software Foundation; with no 23Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. 24A copy of the license is included in the section entitled 25``GNU Free Documentation License''. 26@end quotation 27@end copying 28 29@defcodeindex bt 30@defcodeindex rw 31@set BashFeatures 32 33@dircategory Basics 34@direntry 35* Bash: (bash). The GNU Bourne-Again SHell. 36@end direntry 37 38@finalout 39 40@titlepage 41@title Bash Reference Manual 42@subtitle Reference Documentation for Bash 43@subtitle Edition @value{EDITION}, for @code{Bash} Version @value{VERSION}. 44@subtitle @value{UPDATED-MONTH} 45@author Chet Ramey, Case Western Reserve University 46@author Brian Fox, Free Software Foundation 47 48@page 49@vskip 0pt plus 1filll 50@insertcopying 51 52@end titlepage 53 54@contents 55 56@ifnottex 57@node Top, Introduction, (dir), (dir) 58@top Bash Features 59 60This text is a brief description of the features that are present in 61the Bash shell (version @value{VERSION}, @value{UPDATED}). 62The Bash home page is @url{http://www.gnu.org/software/bash/}. 63 64This is Edition @value{EDITION}, last updated @value{UPDATED}, 65of @cite{The GNU Bash Reference Manual}, 66for @code{Bash}, Version @value{VERSION}. 67 68Bash contains features that appear in other popular shells, and some 69features that only appear in Bash. Some of the shells that Bash has 70borrowed concepts from are the Bourne Shell (@file{sh}), the Korn Shell 71(@file{ksh}), and the C-shell (@file{csh} and its successor, 72@file{tcsh}). The following menu breaks the features up into 73categories, noting which features were inspired by other shells and 74which are specific to Bash. 75 76This manual is meant as a brief introduction to features found in 77Bash. The Bash manual page should be used as the definitive 78reference on shell behavior. 79 80@menu 81* Introduction:: An introduction to the shell. 82* Definitions:: Some definitions used in the rest of this 83 manual. 84* Basic Shell Features:: The shell "building blocks". 85* Shell Builtin Commands:: Commands that are a part of the shell. 86* Shell Variables:: Variables used or set by Bash. 87* Bash Features:: Features found only in Bash. 88* Job Control:: What job control is and how Bash allows you 89 to use it. 90* Command Line Editing:: Chapter describing the command line 91 editing features. 92* Using History Interactively:: Command History Expansion 93* Installing Bash:: How to build and install Bash on your system. 94* Reporting Bugs:: How to report bugs in Bash. 95* Major Differences From The Bourne Shell:: A terse list of the differences 96 between Bash and historical 97 versions of /bin/sh. 98* GNU Free Documentation License:: Copying and sharing this documentation. 99* Indexes:: Various indexes for this manual. 100@end menu 101@end ifnottex 102 103@node Introduction 104@chapter Introduction 105@menu 106* What is Bash?:: A short description of Bash. 107* What is a shell?:: A brief introduction to shells. 108@end menu 109 110@node What is Bash? 111@section What is Bash? 112 113Bash is the shell, or command language interpreter, 114for the @sc{gnu} operating system. 115The name is an acronym for the @samp{Bourne-Again SHell}, 116a pun on Stephen Bourne, the author of the direct ancestor of 117the current Unix shell @code{sh}, 118which appeared in the Seventh Edition Bell Labs Research version 119of Unix. 120 121Bash is largely compatible with @code{sh} and incorporates useful 122features from the Korn shell @code{ksh} and the C shell @code{csh}. 123It is intended to be a conformant implementation of the @sc{ieee} 124@sc{posix} Shell and Tools portion of the @sc{ieee} @sc{posix} 125specification (@sc{ieee} Standard 1003.1). 126It offers functional improvements over @code{sh} for both interactive and 127programming use. 128 129While the @sc{gnu} operating system provides other shells, including 130a version of @code{csh}, Bash is the default shell. 131Like other @sc{gnu} software, Bash is quite portable. It currently runs 132on nearly every version of Unix and a few other operating systems @minus{} 133independently-supported ports exist for @sc{ms-dos}, @sc{os/2}, 134and Windows platforms. 135 136@node What is a shell? 137@section What is a shell? 138 139At its base, a shell is simply a macro processor that executes 140commands. The term macro processor means functionality where text 141and symbols are expanded to create larger expressions. 142 143A Unix shell is both a command interpreter and a programming 144language. As a command interpreter, the shell provides the user 145interface to the rich set of @sc{gnu} utilities. The programming 146language features allow these utilities to be combined. 147Files containing commands can be created, and become 148commands themselves. These new commands have the same status as 149system commands in directories such as @file{/bin}, allowing users 150or groups to establish custom environments to automate their common 151tasks. 152 153Shells may be used interactively or non-interactively. In 154interactive mode, they accept input typed from the keyboard. 155When executing non-interactively, shells execute commands read 156from a file. 157 158A shell allows execution of @sc{gnu} commands, both synchronously and 159asynchronously. 160The shell waits for synchronous commands to complete before accepting 161more input; asynchronous commands continue to execute in parallel 162with the shell while it reads and executes additional commands. 163The @dfn{redirection} constructs permit 164fine-grained control of the input and output of those commands. 165Moreover, the shell allows control over the contents of commands' 166environments. 167 168Shells also provide a small set of built-in 169commands (@dfn{builtins}) implementing functionality impossible 170or inconvenient to obtain via separate utilities. 171For example, @code{cd}, @code{break}, @code{continue}, and 172@code{exec} cannot be implemented outside of the shell because 173they directly manipulate the shell itself. 174The @code{history}, @code{getopts}, @code{kill}, or @code{pwd} 175builtins, among others, could be implemented in separate utilities, 176but they are more convenient to use as builtin commands. 177All of the shell builtins are described in 178subsequent sections. 179 180While executing commands is essential, most of the power (and 181complexity) of shells is due to their embedded programming 182languages. Like any high-level language, the shell provides 183variables, flow control constructs, quoting, and functions. 184 185Shells offer features geared specifically for 186interactive use rather than to augment the programming language. 187These interactive features include job control, command line 188editing, command history and aliases. Each of these features is 189described in this manual. 190 191@node Definitions 192@chapter Definitions 193These definitions are used throughout the remainder of this manual. 194 195@table @code 196 197@item POSIX 198@cindex POSIX 199A family of open system standards based on Unix. Bash 200is primarily concerned with the Shell and Utilities portion of the 201@sc{posix} 1003.1 standard. 202 203@item blank 204A space or tab character. 205 206@item builtin 207@cindex builtin 208A command that is implemented internally by the shell itself, rather 209than by an executable program somewhere in the file system. 210 211@item control operator 212@cindex control operator 213A @code{token} that performs a control function. It is a @code{newline} 214or one of the following: 215@samp{||}, @samp{&&}, @samp{&}, @samp{;}, @samp{;;}, @samp{;&}, @samp{;;&}, 216@samp{|}, @samp{|&}, @samp{(}, or @samp{)}. 217 218@item exit status 219@cindex exit status 220The value returned by a command to its caller. The value is restricted 221to eight bits, so the maximum value is 255. 222 223@item field 224@cindex field 225A unit of text that is the result of one of the shell expansions. After 226expansion, when executing a command, the resulting fields are used as 227the command name and arguments. 228 229@item filename 230@cindex filename 231A string of characters used to identify a file. 232 233@item job 234@cindex job 235A set of processes comprising a pipeline, and any processes descended 236from it, that are all in the same process group. 237 238@item job control 239@cindex job control 240A mechanism by which users can selectively stop (suspend) and restart 241(resume) execution of processes. 242 243@item metacharacter 244@cindex metacharacter 245A character that, when unquoted, separates words. A metacharacter is 246a @code{space}, @code{tab}, @code{newline}, or one of the following characters: 247@samp{|}, @samp{&}, @samp{;}, @samp{(}, @samp{)}, @samp{<}, or 248@samp{>}. 249 250@item name 251@cindex name 252@cindex identifier 253A @code{word} consisting solely of letters, numbers, and underscores, 254and beginning with a letter or underscore. @code{Name}s are used as 255shell variable and function names. 256Also referred to as an @code{identifier}. 257 258@item operator 259@cindex operator, shell 260A @code{control operator} or a @code{redirection operator}. 261@xref{Redirections}, for a list of redirection operators. 262Operators contain at least one unquoted @code{metacharacter}. 263 264@item process group 265@cindex process group 266A collection of related processes each having the same process 267group @sc{id}. 268 269@item process group ID 270@cindex process group ID 271A unique identifier that represents a @code{process group} 272during its lifetime. 273 274@item reserved word 275@cindex reserved word 276A @code{word} that has a special meaning to the shell. Most reserved 277words introduce shell flow control constructs, such as @code{for} and 278@code{while}. 279 280@item return status 281@cindex return status 282A synonym for @code{exit status}. 283 284@item signal 285@cindex signal 286A mechanism by which a process may be notified by the kernel 287of an event occurring in the system. 288 289@item special builtin 290@cindex special builtin 291A shell builtin command that has been classified as special by the 292@sc{posix} standard. 293 294@item token 295@cindex token 296A sequence of characters considered a single unit by the shell. 297It is either a @code{word} or an @code{operator}. 298 299@item word 300@cindex word 301A sequence of characters treated as a unit by the shell. 302Words may not include unquoted @code{metacharacters}. 303@end table 304 305@node Basic Shell Features 306@chapter Basic Shell Features 307@cindex Bourne shell 308 309Bash is an acronym for @samp{Bourne-Again SHell}. 310The Bourne shell is 311the traditional Unix shell originally written by Stephen Bourne. 312All of the Bourne shell builtin commands are available in Bash, 313The rules for evaluation and quoting are taken from the @sc{posix} 314specification for the `standard' Unix shell. 315 316This chapter briefly summarizes the shell's `building blocks': 317commands, control structures, shell functions, shell @i{parameters}, 318shell expansions, 319@i{redirections}, which are a way to direct input and output from 320and to named files, and how the shell executes commands. 321 322@menu 323* Shell Syntax:: What your input means to the shell. 324* Shell Commands:: The types of commands you can use. 325* Shell Functions:: Grouping commands by name. 326* Shell Parameters:: How the shell stores values. 327* Shell Expansions:: How Bash expands parameters and the various 328 expansions available. 329* Redirections:: A way to control where input and output go. 330* Executing Commands:: What happens when you run a command. 331* Shell Scripts:: Executing files of shell commands. 332@end menu 333 334@node Shell Syntax 335@section Shell Syntax 336@menu 337* Shell Operation:: The basic operation of the shell. 338* Quoting:: How to remove the special meaning from characters. 339* Comments:: How to specify comments. 340@end menu 341 342When the shell reads input, it proceeds through a 343sequence of operations. If the input indicates the beginning of a 344comment, the shell ignores the comment symbol (@samp{#}), and the rest 345of that line. 346 347Otherwise, roughly speaking, the shell reads its input and 348divides the input into words and operators, employing the quoting rules 349to select which meanings to assign various words and characters. 350 351The shell then parses these tokens into commands and other constructs, 352removes the special meaning of certain words or characters, expands 353others, redirects input and output as needed, executes the specified 354command, waits for the command's exit status, and makes that exit status 355available for further inspection or processing. 356 357@node Shell Operation 358@subsection Shell Operation 359 360The following is a brief description of the shell's operation when it 361reads and executes a command. Basically, the shell does the 362following: 363 364@enumerate 365@item 366Reads its input from a file (@pxref{Shell Scripts}), from a string 367supplied as an argument to the @option{-c} invocation option 368(@pxref{Invoking Bash}), or from the user's terminal. 369 370@item 371Breaks the input into words and operators, obeying the quoting rules 372described in @ref{Quoting}. These tokens are separated by 373@code{metacharacters}. Alias expansion is performed by this step 374(@pxref{Aliases}). 375 376@item 377Parses the tokens into simple and compound commands 378(@pxref{Shell Commands}). 379 380@item 381Performs the various shell expansions (@pxref{Shell Expansions}), breaking 382the expanded tokens into lists of filenames (@pxref{Filename Expansion}) 383and commands and arguments. 384 385@item 386Performs any necessary redirections (@pxref{Redirections}) and removes 387the redirection operators and their operands from the argument list. 388 389@item 390Executes the command (@pxref{Executing Commands}). 391 392@item 393Optionally waits for the command to complete and collects its exit 394status (@pxref{Exit Status}). 395 396@end enumerate 397 398@node Quoting 399@subsection Quoting 400@cindex quoting 401@menu 402* Escape Character:: How to remove the special meaning from a single 403 character. 404* Single Quotes:: How to inhibit all interpretation of a sequence 405 of characters. 406* Double Quotes:: How to suppress most of the interpretation of a 407 sequence of characters. 408* ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings. 409* Locale Translation:: How to translate strings into different languages. 410@end menu 411 412Quoting is used to remove the special meaning of certain 413characters or words to the shell. Quoting can be used to 414disable special treatment for special characters, to prevent 415reserved words from being recognized as such, and to prevent 416parameter expansion. 417 418Each of the shell metacharacters (@pxref{Definitions}) 419has special meaning to the shell and must be quoted if it is to 420represent itself. 421When the command history expansion facilities are being used 422(@pxref{History Interaction}), the 423@var{history expansion} character, usually @samp{!}, must be quoted 424to prevent history expansion. @xref{Bash History Facilities}, for 425more details concerning history expansion. 426 427There are three quoting mechanisms: the 428@var{escape character}, single quotes, and double quotes. 429 430@node Escape Character 431@subsubsection Escape Character 432A non-quoted backslash @samp{\} is the Bash escape character. 433It preserves the literal value of the next character that follows, 434with the exception of @code{newline}. If a @code{\newline} pair 435appears, and the backslash itself is not quoted, the @code{\newline} 436is treated as a line continuation (that is, it is removed from 437the input stream and effectively ignored). 438 439@node Single Quotes 440@subsubsection Single Quotes 441 442Enclosing characters in single quotes (@samp{'}) preserves the literal value 443of each character within the quotes. A single quote may not occur 444between single quotes, even when preceded by a backslash. 445 446@node Double Quotes 447@subsubsection Double Quotes 448 449Enclosing characters in double quotes (@samp{"}) preserves the literal value 450of all characters within the quotes, with the exception of 451@samp{$}, @samp{`}, @samp{\}, 452and, when history expansion is enabled, @samp{!}. 453When the shell is in 454@sc{posix} mode (@pxref{Bash POSIX Mode}), 455the @samp{!} has no special meaning 456within double quotes, even when history expansion is enabled. 457The characters @samp{$} and @samp{`} 458retain their special meaning within double quotes (@pxref{Shell Expansions}). 459The backslash retains its special meaning only when followed by one of 460the following characters: 461@samp{$}, @samp{`}, @samp{"}, @samp{\}, or @code{newline}. 462Within double quotes, backslashes that are followed by one of these 463characters are removed. Backslashes preceding characters without a 464special meaning are left unmodified. 465A double quote may be quoted within double quotes by preceding it with 466a backslash. 467If enabled, history expansion will be performed unless an @samp{!} 468appearing in double quotes is escaped using a backslash. 469The backslash preceding the @samp{!} is not removed. 470 471The special parameters @samp{*} and @samp{@@} have special meaning 472when in double quotes (@pxref{Shell Parameter Expansion}). 473 474@node ANSI-C Quoting 475@subsubsection ANSI-C Quoting 476@cindex quoting, ANSI 477 478Words of the form @code{$'@var{string}'} are treated specially. The 479word expands to @var{string}, with backslash-escaped characters replaced 480as specified by the ANSI C standard. Backslash escape sequences, if 481present, are decoded as follows: 482 483@table @code 484@item \a 485alert (bell) 486@item \b 487backspace 488@item \e 489@itemx \E 490an escape character (not ANSI C) 491@item \f 492form feed 493@item \n 494newline 495@item \r 496carriage return 497@item \t 498horizontal tab 499@item \v 500vertical tab 501@item \\ 502backslash 503@item \' 504single quote 505@item \" 506double quote 507@item \? 508question mark 509@item \@var{nnn} 510the eight-bit character whose value is the octal value @var{nnn} 511(one to three octal digits) 512@item \x@var{HH} 513the eight-bit character whose value is the hexadecimal value @var{HH} 514(one or two hex digits) 515@item \u@var{HHHH} 516the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value 517@var{HHHH} (one to four hex digits) 518@item \U@var{HHHHHHHH} 519the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value 520@var{HHHHHHHH} (one to eight hex digits) 521@item \c@var{x} 522a control-@var{x} character 523@end table 524 525@noindent 526The expanded result is single-quoted, as if the dollar sign had not 527been present. 528 529@node Locale Translation 530@subsubsection Locale-Specific Translation 531@cindex localization 532@cindex internationalization 533@cindex native languages 534@cindex translation, native languages 535 536A double-quoted string preceded by a dollar sign (@samp{$}) 537will cause the string to be translated according to the current locale. 538The @var{gettext} infrastructure performs the message catalog lookup and 539translation, using the @code{LC_MESSAGES} and @code{TEXTDOMAIN} shell 540variables, as explained below. See the gettext documentation for additional 541details. 542If the current locale is @code{C} or @code{POSIX}, 543or if there are no translations available, 544the dollar sign is ignored. 545If the string is translated and replaced, the replacement is 546double-quoted. 547 548@vindex LC_MESSAGES 549@vindex TEXTDOMAIN 550@vindex TEXTDOMAINDIR 551Some systems use the message catalog selected by the @env{LC_MESSAGES} 552shell variable. Others create the name of the message catalog from the 553value of the @env{TEXTDOMAIN} shell variable, possibly adding a 554suffix of @samp{.mo}. If you use the @env{TEXTDOMAIN} variable, you 555may need to set the @env{TEXTDOMAINDIR} variable to the location of 556the message catalog files. Still others use both variables in this 557fashion: 558@env{TEXTDOMAINDIR}/@env{LC_MESSAGES}/LC_MESSAGES/@env{TEXTDOMAIN}.mo. 559 560@node Comments 561@subsection Comments 562@cindex comments, shell 563 564In a non-interactive shell, or an interactive shell in which the 565@code{interactive_comments} option to the @code{shopt} 566builtin is enabled (@pxref{The Shopt Builtin}), 567a word beginning with @samp{#} 568causes that word and all remaining characters on that line to 569be ignored. An interactive shell without the @code{interactive_comments} 570option enabled does not allow comments. The @code{interactive_comments} 571option is on by default in interactive shells. 572@xref{Interactive Shells}, for a description of what makes 573a shell interactive. 574 575@node Shell Commands 576@section Shell Commands 577@cindex commands, shell 578 579A simple shell command such as @code{echo a b c} consists of the command 580itself followed by arguments, separated by spaces. 581 582More complex shell commands are composed of simple commands arranged together 583in a variety of ways: in a pipeline in which the output of one command 584becomes the input of a second, in a loop or conditional construct, or in 585some other grouping. 586 587@menu 588* Reserved Words:: Words that have special meaning to the shell. 589* Simple Commands:: The most common type of command. 590* Pipelines:: Connecting the input and output of several 591 commands. 592* Lists:: How to execute commands sequentially. 593* Compound Commands:: Shell commands for control flow. 594* Coprocesses:: Two-way communication between commands. 595* GNU Parallel:: Running commands in parallel. 596@end menu 597 598@node Reserved Words 599@subsection Reserved Words 600@cindex reserved words 601 602Reserved words are words that have special meaning to the shell. 603They are used to begin and end the shell's compound commands. 604 605The following words are recognized as reserved when unquoted and 606the first word of a command (see below for exceptions): 607 608@multitable @columnfractions .1 .1 .1 .1 .12 .1 609@item @code{if} @tab @code{then} @tab @code{elif} 610@tab @code{else} @tab @code{fi} @tab @code{time} 611@item @code{for} @tab @code{in} @tab @code{until} 612@tab @code{while} @tab @code{do} @tab @code{done} 613@item @code{case} @tab @code{esac} @tab @code{coproc} 614@tab @code{select} @tab @code{function} 615@item @code{@{} @tab @code{@}} @tab @code{[[} @tab @code{]]} @tab @code{!} 616@end multitable 617 618@noindent 619@code{in} is recognized as a reserved word if it is the third word of a 620@code{case} or @code{select} command. 621@code{in} and @code{do} are recognized as reserved 622words if they are the third word in a @code{for} command. 623 624@node Simple Commands 625@subsection Simple Commands 626@cindex commands, simple 627 628A simple command is the kind of command encountered most often. 629It's just a sequence of words separated by @code{blank}s, terminated 630by one of the shell's control operators (@pxref{Definitions}). The 631first word generally specifies a command to be executed, with the 632rest of the words being that command's arguments. 633 634The return status (@pxref{Exit Status}) of a simple command is 635its exit status as provided 636by the @sc{posix} 1003.1 @code{waitpid} function, or 128+@var{n} if 637the command was terminated by signal @var{n}. 638 639@node Pipelines 640@subsection Pipelines 641@cindex pipeline 642@cindex commands, pipelines 643 644A @code{pipeline} is a sequence of one or more commands separated by 645one of the control operators @samp{|} or @samp{|&}. 646 647@rwindex time 648@rwindex ! 649@cindex command timing 650The format for a pipeline is 651@example 652[time [-p]] [!] @var{command1} [ | or |& @var{command2} ] @dots{} 653@end example 654 655@noindent 656The output of each command in the pipeline is connected via a pipe 657to the input of the next command. 658That is, each command reads the previous command's output. This 659connection is performed before any redirections specified by the 660command. 661 662If @samp{|&} is used, @var{command1}'s standard error, in addition to 663its standard output, is connected to 664@var{command2}'s standard input through the pipe; 665it is shorthand for @code{2>&1 |}. 666This implicit redirection of the standard error to the standard output is 667performed after any redirections specified by the command. 668 669The reserved word @code{time} causes timing statistics 670to be printed for the pipeline once it finishes. 671The statistics currently consist of elapsed (wall-clock) time and 672user and system time consumed by the command's execution. 673The @option{-p} option changes the output format to that specified 674by @sc{posix}. 675When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}), 676it does not recognize @code{time} as a reserved word if the next 677token begins with a @samp{-}. 678The @env{TIMEFORMAT} variable may be set to a format string that 679specifies how the timing information should be displayed. 680@xref{Bash Variables}, for a description of the available formats. 681The use of @code{time} as a reserved word permits the timing of 682shell builtins, shell functions, and pipelines. An external 683@code{time} command cannot time these easily. 684 685When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}), @code{time} 686may be followed by a newline. In this case, the shell displays the 687total user and system time consumed by the shell and its children. 688The @env{TIMEFORMAT} variable may be used to specify the format of 689the time information. 690 691If the pipeline is not executed asynchronously (@pxref{Lists}), the 692shell waits for all commands in the pipeline to complete. 693 694Each command in a pipeline is executed in its own subshell, which is a 695separate process (@pxref{Command Execution Environment}). 696If the @code{lastpipe} option is enabled using the @code{shopt} builtin 697(@pxref{The Shopt Builtin}), 698the last element of a pipeline may be run by the shell process. 699 700The exit 701status of a pipeline is the exit status of the last command in the 702pipeline, unless the @code{pipefail} option is enabled 703(@pxref{The Set Builtin}). 704If @code{pipefail} is enabled, the pipeline's return status is the 705value of the last (rightmost) command to exit with a non-zero status, 706or zero if all commands exit successfully. 707If the reserved word @samp{!} precedes the pipeline, the 708exit status is the logical negation of the exit status as described 709above. 710The shell waits for all commands in the pipeline to terminate before 711returning a value. 712 713@node Lists 714@subsection Lists of Commands 715@cindex commands, lists 716 717A @code{list} is a sequence of one or more pipelines separated by one 718of the operators @samp{;}, @samp{&}, @samp{&&}, or @samp{||}, 719and optionally terminated by one of @samp{;}, @samp{&}, or a 720@code{newline}. 721 722Of these list operators, @samp{&&} and @samp{||} 723have equal precedence, followed by @samp{;} and @samp{&}, 724which have equal precedence. 725 726A sequence of one or more newlines may appear in a @code{list} 727to delimit commands, equivalent to a semicolon. 728 729If a command is terminated by the control operator @samp{&}, 730the shell executes the command asynchronously in a subshell. 731This is known as executing the command in the @var{background}, 732and these are referred to as @var{asynchronous} commands. 733The shell does not wait for the command to finish, and the return 734status is 0 (true). 735When job control is not active (@pxref{Job Control}), 736the standard input for asynchronous commands, in the absence of any 737explicit redirections, is redirected from @code{/dev/null}. 738 739Commands separated by a @samp{;} are executed sequentially; the shell 740waits for each command to terminate in turn. The return status is the 741exit status of the last command executed. 742 743@sc{and} and @sc{or} lists are sequences of one or more pipelines 744separated by the control operators @samp{&&} and @samp{||}, 745respectively. @sc{and} and @sc{or} lists are executed with left 746associativity. 747 748An @sc{and} list has the form 749@example 750@var{command1} && @var{command2} 751@end example 752 753@noindent 754@var{command2} is executed if, and only if, @var{command1} 755returns an exit status of zero (success). 756 757An @sc{or} list has the form 758@example 759@var{command1} || @var{command2} 760@end example 761 762@noindent 763@var{command2} is executed if, and only if, @var{command1} 764returns a non-zero exit status. 765 766The return status of 767@sc{and} and @sc{or} lists is the exit status of the last command 768executed in the list. 769 770@node Compound Commands 771@subsection Compound Commands 772@cindex commands, compound 773 774@menu 775* Looping Constructs:: Shell commands for iterative action. 776* Conditional Constructs:: Shell commands for conditional execution. 777* Command Grouping:: Ways to group commands. 778@end menu 779 780Compound commands are the shell programming language constructs. 781Each construct begins with a reserved word or control operator and is 782terminated by a corresponding reserved word or operator. 783Any redirections (@pxref{Redirections}) associated with a compound command 784apply to all commands within that compound command unless explicitly overridden. 785 786In most cases a list of commands in a compound command's description may be 787separated from the rest of the command by one or more newlines, and may be 788followed by a newline in place of a semicolon. 789 790Bash provides looping constructs, conditional commands, and mechanisms 791to group commands and execute them as a unit. 792 793@node Looping Constructs 794@subsubsection Looping Constructs 795@cindex commands, looping 796 797Bash supports the following looping constructs. 798 799Note that wherever a @samp{;} appears in the description of a 800command's syntax, it may be replaced with one or more newlines. 801 802@table @code 803@item until 804@rwindex until 805@rwindex do 806@rwindex done 807The syntax of the @code{until} command is: 808 809@example 810until @var{test-commands}; do @var{consequent-commands}; done 811@end example 812 813Execute @var{consequent-commands} as long as 814@var{test-commands} has an exit status which is not zero. 815The return status is the exit status of the last command executed 816in @var{consequent-commands}, or zero if none was executed. 817 818@item while 819@rwindex while 820The syntax of the @code{while} command is: 821 822@example 823while @var{test-commands}; do @var{consequent-commands}; done 824@end example 825 826Execute @var{consequent-commands} as long as 827@var{test-commands} has an exit status of zero. 828The return status is the exit status of the last command executed 829in @var{consequent-commands}, or zero if none was executed. 830 831@item for 832@rwindex for 833The syntax of the @code{for} command is: 834 835@example 836for @var{name} [ [in [@var{words} @dots{}] ] ; ] do @var{commands}; done 837@end example 838 839Expand @var{words} (@pxref{Shell Expansions}), and execute @var{commands} 840once for each member 841in the resultant list, with @var{name} bound to the current member. 842If @samp{in @var{words}} is not present, the @code{for} command 843executes the @var{commands} once for each positional parameter that is 844set, as if @samp{in "$@@"} had been specified 845(@pxref{Special Parameters}). 846 847The return status is the exit status of the last command that executes. 848If there are no items in the expansion of @var{words}, no commands are 849executed, and the return status is zero. 850 851An alternate form of the @code{for} command is also supported: 852 853@example 854for (( @var{expr1} ; @var{expr2} ; @var{expr3} )) ; do @var{commands} ; done 855@end example 856 857First, the arithmetic expression @var{expr1} is evaluated according 858to the rules described below (@pxref{Shell Arithmetic}). 859The arithmetic expression @var{expr2} is then evaluated repeatedly 860until it evaluates to zero. 861Each time @var{expr2} evaluates to a non-zero value, @var{commands} are 862executed and the arithmetic expression @var{expr3} is evaluated. 863If any expression is omitted, it behaves as if it evaluates to 1. 864The return value is the exit status of the last command in @var{commands} 865that is executed, or false if any of the expressions is invalid. 866@end table 867 868The @code{break} and @code{continue} builtins (@pxref{Bourne Shell Builtins}) 869may be used to control loop execution. 870 871@node Conditional Constructs 872@subsubsection Conditional Constructs 873@cindex commands, conditional 874 875@table @code 876@item if 877@rwindex if 878@rwindex then 879@rwindex else 880@rwindex elif 881@rwindex fi 882The syntax of the @code{if} command is: 883 884@example 885if @var{test-commands}; then 886 @var{consequent-commands}; 887[elif @var{more-test-commands}; then 888 @var{more-consequents};] 889[else @var{alternate-consequents};] 890fi 891@end example 892 893The @var{test-commands} list is executed, and if its return status is zero, 894the @var{consequent-commands} list is executed. 895If @var{test-commands} returns a non-zero status, each @code{elif} list 896is executed in turn, and if its exit status is zero, 897the corresponding @var{more-consequents} is executed and the 898command completes. 899If @samp{else @var{alternate-consequents}} is present, and 900the final command in the final @code{if} or @code{elif} clause 901has a non-zero exit status, then @var{alternate-consequents} is executed. 902The return status is the exit status of the last command executed, or 903zero if no condition tested true. 904 905@item case 906@rwindex case 907@rwindex in 908@rwindex esac 909The syntax of the @code{case} command is: 910 911@example 912case @var{word} in 913 [ [(] @var{pattern} [| @var{pattern}]@dots{}) @var{command-list} ;;]@dots{} 914esac 915@end example 916 917@code{case} will selectively execute the @var{command-list} corresponding to 918the first @var{pattern} that matches @var{word}. 919The match is performed according 920to the rules described below in @ref{Pattern Matching}. 921If the @code{nocasematch} shell option 922(see the description of @code{shopt} in @ref{The Shopt Builtin}) 923is enabled, the match is performed without regard to the case 924of alphabetic characters. 925The @samp{|} is used to separate multiple patterns, and the @samp{)} 926operator terminates a pattern list. 927A list of patterns and an associated command-list is known 928as a @var{clause}. 929 930Each clause must be terminated with @samp{;;}, @samp{;&}, or @samp{;;&}. 931The @var{word} undergoes tilde expansion, parameter expansion, command 932substitution, arithmetic expansion, and quote removal 933(@pxref{Shell Parameter Expansion}) 934before matching is 935attempted. Each @var{pattern} undergoes tilde expansion, parameter 936expansion, command substitution, and arithmetic expansion. 937 938There may be an arbitrary number of @code{case} clauses, each terminated 939by a @samp{;;}, @samp{;&}, or @samp{;;&}. 940The first pattern that matches determines the 941command-list that is executed. 942It's a common idiom to use @samp{*} as the final pattern to define the 943default case, since that pattern will always match. 944 945Here is an example using @code{case} in a script that could be used to 946describe one interesting feature of an animal: 947 948@example 949echo -n "Enter the name of an animal: " 950read ANIMAL 951echo -n "The $ANIMAL has " 952case $ANIMAL in 953 horse | dog | cat) echo -n "four";; 954 man | kangaroo ) echo -n "two";; 955 *) echo -n "an unknown number of";; 956esac 957echo " legs." 958@end example 959 960@noindent 961 962If the @samp{;;} operator is used, no subsequent matches are attempted after 963the first pattern match. 964Using @samp{;&} in place of @samp{;;} causes execution to continue with 965the @var{command-list} associated with the next clause, if any. 966Using @samp{;;&} in place of @samp{;;} causes the shell to test the patterns 967in the next clause, if any, and execute any associated @var{command-list} 968on a successful match, 969continuing the case statement execution as if the pattern list had not matched. 970 971The return status is zero if no @var{pattern} is matched. Otherwise, the 972return status is the exit status of the @var{command-list} executed. 973 974@item select 975@rwindex select 976 977The @code{select} construct allows the easy generation of menus. 978It has almost the same syntax as the @code{for} command: 979 980@example 981select @var{name} [in @var{words} @dots{}]; do @var{commands}; done 982@end example 983 984The list of words following @code{in} is expanded, generating a list 985of items. The set of expanded words is printed on the standard 986error output stream, each preceded by a number. If the 987@samp{in @var{words}} is omitted, the positional parameters are printed, 988as if @samp{in "$@@"} had been specified. 989The @env{PS3} prompt is then displayed and a line is read from the 990standard input. 991If the line consists of a number corresponding to one of the displayed 992words, then the value of @var{name} is set to that word. 993If the line is empty, the words and prompt are displayed again. 994If @code{EOF} is read, the @code{select} command completes. 995Any other value read causes @var{name} to be set to null. 996The line read is saved in the variable @env{REPLY}. 997 998The @var{commands} are executed after each selection until a 999@code{break} command is executed, at which 1000point the @code{select} command completes. 1001 1002Here is an example that allows the user to pick a filename from the 1003current directory, and displays the name and index of the file 1004selected. 1005 1006@example 1007select fname in *; 1008do 1009 echo you picked $fname \($REPLY\) 1010 break; 1011done 1012@end example 1013 1014@item ((@dots{})) 1015@example 1016(( @var{expression} )) 1017@end example 1018 1019The arithmetic @var{expression} is evaluated according to the rules 1020described below (@pxref{Shell Arithmetic}). 1021If the value of the expression is non-zero, the return status is 0; 1022otherwise the return status is 1. This is exactly equivalent to 1023@example 1024let "@var{expression}" 1025@end example 1026@noindent 1027@xref{Bash Builtins}, for a full description of the @code{let} builtin. 1028 1029@item [[@dots{}]] 1030@rwindex [[ 1031@rwindex ]] 1032@example 1033[[ @var{expression} ]] 1034@end example 1035 1036Return a status of 0 or 1 depending on the evaluation of 1037the conditional expression @var{expression}. 1038Expressions are composed of the primaries described below in 1039@ref{Bash Conditional Expressions}. 1040Word splitting and filename expansion are not performed on the words 1041between the @code{[[} and @code{]]}; tilde expansion, parameter and 1042variable expansion, arithmetic expansion, command substitution, process 1043substitution, and quote removal are performed. 1044Conditional operators such as @samp{-f} must be unquoted to be recognized 1045as primaries. 1046 1047When used with @code{[[}, the @samp{<} and @samp{>} operators sort 1048lexicographically using the current locale. 1049 1050When the @samp{==} and @samp{!=} operators are used, the string to the 1051right of the operator is considered a pattern and matched according 1052to the rules described below in @ref{Pattern Matching}, 1053as if the @code{extglob} shell option were enabled. 1054The @samp{=} operator is identical to @samp{==}. 1055If the @code{nocasematch} shell option 1056(see the description of @code{shopt} in @ref{The Shopt Builtin}) 1057is enabled, the match is performed without regard to the case 1058of alphabetic characters. 1059The return value is 0 if the string matches (@samp{==}) or does not 1060match (@samp{!=}) the pattern, and 1 otherwise. 1061Any part of the pattern may be quoted to force the quoted portion 1062to be matched as a string. 1063 1064An additional binary operator, @samp{=~}, is available, with the same 1065precedence as @samp{==} and @samp{!=}. 1066When it is used, the string to the right of the operator is considered 1067a @sc{posix} extended regular expression and matched accordingly 1068(using the @sc{posix} @code{regcomp} and @code{regexec} interfaces 1069usually described in @i{regex}(3)). 1070The return value is 0 if the string matches 1071the pattern, and 1 otherwise. 1072If the regular expression is syntactically incorrect, the conditional 1073expression's return value is 2. 1074If the @code{nocasematch} shell option 1075(see the description of @code{shopt} in @ref{The Shopt Builtin}) 1076is enabled, the match is performed without regard to the case 1077of alphabetic characters. 1078Any part of the pattern may be quoted to force the quoted portion 1079to be matched as a string. 1080Bracket expressions in regular expressions must be treated carefully, 1081since normal quoting characters lose their meanings between brackets. 1082If the pattern is stored in a shell variable, quoting the variable 1083expansion forces the entire pattern to be matched as a string. 1084 1085The pattern will match if it matches any part of the string. 1086Anchor the pattern using the @samp{^} and @samp{$} regular expression 1087operators to force it to match the entire string. 1088The array variable @code{BASH_REMATCH} records which parts of the string 1089matched the pattern. 1090The element of @code{BASH_REMATCH} with index 0 contains the portion of 1091the string matching the entire regular expression. 1092Substrings matched by parenthesized subexpressions within the regular 1093expression are saved in the remaining @code{BASH_REMATCH} indices. 1094The element of @code{BASH_REMATCH} with index @var{n} is the portion of the 1095string matching the @var{n}th parenthesized subexpression. 1096 1097For example, the following will match a line 1098(stored in the shell variable @var{line}) 1099if there is a sequence of characters anywhere in the value consisting of 1100any number, including zero, of 1101characters in the @code{space} character class, 1102zero or one instances of @samp{a}, then a @samp{b}: 1103@example 1104[[ $line =~ [[:space:]]*(a)?b ]] 1105@end example 1106 1107@noindent 1108That means values like @samp{aab} and @samp{ aaaaaab} will match, as 1109will a line containing a @samp{b} anywhere in its value. 1110 1111Storing the regular expression in a shell variable is often a useful 1112way to avoid problems with quoting characters that are special to the 1113shell. 1114It is sometimes difficult to specify a regular expression literally 1115without using quotes, or to keep track of the quoting used by regular 1116expressions while paying attention to the shell's quote removal. 1117Using a shell variable to store the pattern decreases these problems. 1118For example, the following is equivalent to the above: 1119@example 1120pattern='[[:space:]]*(a)?b' 1121[[ $line =~ $pattern ]] 1122@end example 1123 1124@noindent 1125If you want to match a character that's special to the regular expression 1126grammar, it has to be quoted to remove its special meaning. 1127This means that in the pattern @samp{xxx.txt}, the @samp{.} matches any 1128character in the string (its usual regular expression meaning), but in the 1129pattern @samp{"xxx.txt"} it can only match a literal @samp{.}. 1130Shell programmers should take special care with backslashes, since backslashes 1131are used both by the shell and regular expressions to remove the special 1132meaning from the following character. 1133The following two sets of commands are @emph{not} equivalent: 1134@example 1135pattern='\.' 1136 1137[[ . =~ $pattern ]] 1138[[ . =~ \. ]] 1139 1140[[ . =~ "$pattern" ]] 1141[[ . =~ '\.' ]] 1142@end example 1143 1144@noindent 1145The first two matches will succeed, but the second two will not, because 1146in the second two the backslash will be part of the pattern to be matched. 1147In the first two examples, the backslash removes the special meaning from 1148@samp{.}, so the literal @samp{.} matches. 1149If the string in the first examples were anything other than @samp{.}, say 1150@samp{a}, the pattern would not match, because the quoted @samp{.} in the 1151pattern loses its special meaning of matching any single character. 1152 1153Expressions may be combined using the following operators, listed 1154in decreasing order of precedence: 1155 1156@table @code 1157@item ( @var{expression} ) 1158Returns the value of @var{expression}. 1159This may be used to override the normal precedence of operators. 1160 1161@item ! @var{expression} 1162True if @var{expression} is false. 1163 1164@item @var{expression1} && @var{expression2} 1165True if both @var{expression1} and @var{expression2} are true. 1166 1167@item @var{expression1} || @var{expression2} 1168True if either @var{expression1} or @var{expression2} is true. 1169@end table 1170 1171@noindent 1172The @code{&&} and @code{||} operators do not evaluate @var{expression2} if the 1173value of @var{expression1} is sufficient to determine the return 1174value of the entire conditional expression. 1175@end table 1176 1177@node Command Grouping 1178@subsubsection Grouping Commands 1179@cindex commands, grouping 1180 1181Bash provides two ways to group a list of commands to be executed 1182as a unit. When commands are grouped, redirections may be applied 1183to the entire command list. For example, the output of all the 1184commands in the list may be redirected to a single stream. 1185 1186@table @code 1187@item () 1188@example 1189( @var{list} ) 1190@end example 1191 1192Placing a list of commands between parentheses causes a subshell 1193environment to be created (@pxref{Command Execution Environment}), and each 1194of the commands in @var{list} to be executed in that subshell. Since the 1195@var{list} is executed in a subshell, variable assignments do not remain in 1196effect after the subshell completes. 1197 1198@item @{@} 1199@rwindex @{ 1200@rwindex @} 1201@example 1202@{ @var{list}; @} 1203@end example 1204 1205Placing a list of commands between curly braces causes the list to 1206be executed in the current shell context. No subshell is created. 1207The semicolon (or newline) following @var{list} is required. 1208@end table 1209 1210In addition to the creation of a subshell, there is a subtle difference 1211between these two constructs due to historical reasons. The braces 1212are @code{reserved words}, so they must be separated from the @var{list} 1213by @code{blank}s or other shell metacharacters. 1214The parentheses are @code{operators}, and are 1215recognized as separate tokens by the shell even if they are not separated 1216from the @var{list} by whitespace. 1217 1218The exit status of both of these constructs is the exit status of 1219@var{list}. 1220 1221@node Coprocesses 1222@subsection Coprocesses 1223@cindex coprocess 1224 1225A @code{coprocess} is a shell command preceded by the @code{coproc} 1226reserved word. 1227A coprocess is executed asynchronously in a subshell, as if the command 1228had been terminated with the @samp{&} control operator, with a two-way pipe 1229established between the executing shell and the coprocess. 1230 1231The format for a coprocess is: 1232@example 1233coproc [@var{NAME}] @var{command} [@var{redirections}] 1234@end example 1235 1236@noindent 1237This creates a coprocess named @var{NAME}. 1238If @var{NAME} is not supplied, the default name is @var{COPROC}. 1239@var{NAME} must not be supplied if @var{command} is a simple 1240command (@pxref{Simple Commands}); otherwise, it is interpreted as 1241the first word of the simple command. 1242 1243When the coprocess is executed, the shell creates an array variable 1244(@pxref{Arrays}) 1245named @env{NAME} in the context of the executing shell. 1246The standard output of @var{command} 1247is connected via a pipe to a file descriptor in the executing shell, 1248and that file descriptor is assigned to @env{NAME}[0]. 1249The standard input of @var{command} 1250is connected via a pipe to a file descriptor in the executing shell, 1251and that file descriptor is assigned to @env{NAME}[1]. 1252This pipe is established before any redirections specified by the 1253command (@pxref{Redirections}). 1254The file descriptors can be utilized as arguments to shell commands 1255and redirections using standard word expansions. 1256Other than those created to execute command and process substitutions, 1257the file descriptors are not available in subshells. 1258 1259The process ID of the shell spawned to execute the coprocess is 1260available as the value of the variable @env{NAME}_PID. 1261The @code{wait} 1262builtin command may be used to wait for the coprocess to terminate. 1263 1264Since the coprocess is created as an asynchronous command, 1265the @code{coproc} command always returns success. 1266The return status of a coprocess is the exit status of @var{command}. 1267 1268@node GNU Parallel 1269@subsection GNU Parallel 1270 1271There are ways to run commands in parallel that are not built into Bash. 1272GNU Parallel is a tool to do just that. 1273 1274GNU Parallel, as its name suggests, can be used to build and run commands 1275in parallel. You may run the same command with different arguments, whether 1276they are filenames, usernames, hostnames, or lines read from files. GNU 1277Parallel provides shorthand references to many of the most common operations 1278(input lines, various portions of the input line, different ways to specify 1279the input source, and so on). Parallel can replace @code{xargs} or feed 1280commands from its input sources to several different instances of Bash. 1281 1282For a complete description, refer to the GNU Parallel documentation. A few 1283examples should provide a brief introduction to its use. 1284 1285For example, it is easy to replace @code{xargs} to gzip all html files in the 1286current directory and its subdirectories: 1287@example 1288find . -type f -name '*.html' -print | parallel gzip 1289@end example 1290@noindent 1291If you need to protect special characters such as newlines in file names, 1292use find's @option{-print0} option and parallel's @option{-0} option. 1293 1294You can use Parallel to move files from the current directory when the 1295number of files is too large to process with one @code{mv} invocation: 1296@example 1297printf '%s\n' * | parallel mv @{@} destdir 1298@end example 1299 1300As you can see, the @{@} is replaced with each line read from standard input. 1301While using @code{ls} will work in most instances, it is not sufficient to 1302deal with all filenames. @code{printf} is a shell builtin, and therefore is 1303not subject to the kernel's limit on the number of arguments to a program, 1304so you can use @samp{*} (but see below about the @code{dotglob} shell option). 1305If you need to accommodate special characters in filenames, you can use 1306 1307@example 1308printf '%s\0' * | parallel -0 mv @{@} destdir 1309@end example 1310 1311@noindent 1312as alluded to above. 1313 1314This will run as many @code{mv} commands as there are files in the current 1315directory. 1316You can emulate a parallel @code{xargs} by adding the @option{-X} option: 1317@example 1318printf '%s\0' * | parallel -0 -X mv @{@} destdir 1319@end example 1320 1321(You may have to modify the pattern if you have the @code{dotglob} option 1322enabled.) 1323 1324GNU Parallel can replace certain common idioms that operate on lines read 1325from a file (in this case, filenames listed one per line): 1326@example 1327 while IFS= read -r x; do 1328 do-something1 "$x" "config-$x" 1329 do-something2 < "$x" 1330 done < file | process-output 1331@end example 1332 1333@noindent 1334with a more compact syntax reminiscent of lambdas: 1335@example 1336cat list | parallel "do-something1 @{@} config-@{@} ; do-something2 < @{@}" | 1337 process-output 1338@end example 1339 1340Parallel provides a built-in mechanism to remove filename extensions, which 1341lends itself to batch file transformations or renaming: 1342@example 1343ls *.gz | parallel -j+0 "zcat @{@} | bzip2 >@{.@}.bz2 && rm @{@}" 1344@end example 1345@noindent 1346This will recompress all files in the current directory with names ending 1347in .gz using bzip2, running one job per CPU (-j+0) in parallel. 1348(We use @code{ls} for brevity here; using @code{find} as above is more 1349robust in the face of filenames containing unexpected characters.) 1350Parallel can take arguments from the command line; the above can also be 1351written as 1352 1353@example 1354parallel "zcat @{@} | bzip2 >@{.@}.bz2 && rm @{@}" ::: *.gz 1355@end example 1356 1357If a command generates output, you may want to preserve the input order in 1358the output. For instance, the following command 1359@example 1360@{ 1361 echo foss.org.my ; 1362 echo debian.org ; 1363 echo freenetproject.org ; 1364@} | parallel traceroute 1365@end example 1366@noindent 1367will display as output the traceroute invocation that finishes first. 1368Adding the @option{-k} option 1369@example 1370@{ 1371 echo foss.org.my ; 1372 echo debian.org ; 1373 echo freenetproject.org ; 1374@} | parallel -k traceroute 1375@end example 1376@noindent 1377will ensure that the output of @code{traceroute foss.org.my} is displayed first. 1378 1379Finally, Parallel can be used to run a sequence of shell commands in parallel, 1380similar to @samp{cat file | bash}. 1381It is not uncommon to take a list of filenames, create a series of shell 1382commands to operate on them, and feed that list of commands to a shell. 1383Parallel can speed this up. Assuming that @file{file} contains a list of 1384shell commands, one per line, 1385 1386@example 1387parallel -j 10 < file 1388@end example 1389 1390@noindent 1391will evaluate the commands using the shell (since no explicit command is 1392supplied as an argument), in blocks of ten shell jobs at a time. 1393 1394@node Shell Functions 1395@section Shell Functions 1396@cindex shell function 1397@cindex functions, shell 1398 1399Shell functions are a way to group commands for later execution 1400using a single name for the group. They are executed just like 1401a "regular" command. 1402When the name of a shell function is used as a simple command name, 1403the list of commands associated with that function name is executed. 1404Shell functions are executed in the current 1405shell context; no new process is created to interpret them. 1406 1407Functions are declared using this syntax: 1408@rwindex function 1409@example 1410@var{fname} () @var{compound-command} [ @var{redirections} ] 1411@end example 1412 1413or 1414 1415@example 1416function @var{fname} [()] @var{compound-command} [ @var{redirections} ] 1417@end example 1418 1419This defines a shell function named @var{fname}. The reserved 1420word @code{function} is optional. 1421If the @code{function} reserved 1422word is supplied, the parentheses are optional. 1423The @var{body} of the function is the compound command 1424@var{compound-command} (@pxref{Compound Commands}). 1425That command is usually a @var{list} enclosed between @{ and @}, but 1426may be any compound command listed above, 1427with one exception: If the @code{function} reserved word is used, but the 1428parentheses are not supplied, the braces are required. 1429@var{compound-command} is executed whenever @var{fname} is specified as the 1430name of a command. 1431When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}), 1432@var{fname} must be a valid shell @var{name} and 1433may not be the same as one of the special builtins 1434(@pxref{Special Builtins}). 1435In default mode, a function name can be any unquoted shell word that does 1436not contain @samp{$}. 1437Any redirections (@pxref{Redirections}) associated with the shell function 1438are performed when the function is executed. 1439A function definition may be deleted using the @option{-f} option to the 1440@code{unset} builtin (@pxref{Bourne Shell Builtins}). 1441 1442The exit status of a function definition is zero unless a syntax error 1443occurs or a readonly function with the same name already exists. 1444When executed, the exit status of a function is the exit status of the 1445last command executed in the body. 1446 1447Note that for historical reasons, in the most common usage the curly braces 1448that surround the body of the function must be separated from the body by 1449@code{blank}s or newlines. 1450This is because the braces are reserved words and are only recognized 1451as such when they are separated from the command list 1452by whitespace or another shell metacharacter. 1453Also, when using the braces, the @var{list} must be terminated by a semicolon, 1454a @samp{&}, or a newline. 1455 1456When a function is executed, the arguments to the 1457function become the positional parameters 1458during its execution (@pxref{Positional Parameters}). 1459The special parameter @samp{#} that expands to the number of 1460positional parameters is updated to reflect the change. 1461Special parameter @code{0} is unchanged. 1462The first element of the @env{FUNCNAME} variable is set to the 1463name of the function while the function is executing. 1464 1465All other aspects of the shell execution 1466environment are identical between a function and its caller 1467with these exceptions: 1468the @env{DEBUG} and @env{RETURN} traps 1469are not inherited unless the function has been given the 1470@code{trace} attribute using the @code{declare} builtin or 1471the @code{-o functrace} option has been enabled with 1472the @code{set} builtin, 1473(in which case all functions inherit the @env{DEBUG} and @env{RETURN} traps), 1474and the @env{ERR} trap is not inherited unless the @code{-o errtrace} 1475shell option has been enabled. 1476@xref{Bourne Shell Builtins}, for the description of the 1477@code{trap} builtin. 1478 1479The @env{FUNCNEST} variable, if set to a numeric value greater 1480than 0, defines a maximum function nesting level. Function 1481invocations that exceed the limit cause the entire command to 1482abort. 1483 1484If the builtin command @code{return} 1485is executed in a function, the function completes and 1486execution resumes with the next command after the function 1487call. 1488Any command associated with the @code{RETURN} trap is executed 1489before execution resumes. 1490When a function completes, the values of the 1491positional parameters and the special parameter @samp{#} 1492are restored to the values they had prior to the function's 1493execution. If a numeric argument is given to @code{return}, 1494that is the function's return status; otherwise the function's 1495return status is the exit status of the last command executed 1496before the @code{return}. 1497 1498Variables local to the function may be declared with the 1499@code{local} builtin. These variables are visible only to 1500the function and the commands it invokes. This is particularly 1501important when a shell function calls other functions. 1502 1503Local variables "shadow" variables with the same name declared at 1504previous scopes. For instance, a local variable declared in a function 1505hides a global variable of the same name: references and assignments 1506refer to the local variable, leaving the global variable unmodified. 1507When the function returns, the global variable is once again visible. 1508 1509The shell uses @var{dynamic scoping} to control a variable's visibility 1510within functions. 1511With dynamic scoping, visible variables and their values 1512are a result of the sequence of function calls that caused execution 1513to reach the current function. 1514The value of a variable that a function sees depends 1515on its value within its caller, if any, whether that caller is 1516the "global" scope or another shell function. 1517This is also the value that a local variable 1518declaration "shadows", and the value that is restored when the function 1519returns. 1520 1521For example, if a variable @var{var} is declared as local in function 1522@var{func1}, and @var{func1} calls another function @var{func2}, 1523references to @var{var} made from within @var{func2} will resolve to the 1524local variable @var{var} from @var{func1}, shadowing any global variable 1525named @var{var}. 1526 1527The following script demonstrates this behavior. 1528When executed, the script displays 1529 1530@example 1531In func2, var = func1 local 1532@end example 1533 1534@example 1535func1() 1536@{ 1537 local var='func1 local' 1538 func2 1539@} 1540 1541func2() 1542@{ 1543 echo "In func2, var = $var" 1544@} 1545 1546var=global 1547func1 1548@end example 1549 1550The @code{unset} builtin also acts using the same dynamic scope: if a 1551variable is local to the current scope, @code{unset} will unset it; 1552otherwise the unset will refer to the variable found in any calling scope 1553as described above. 1554If a variable at the current local scope is unset, it will remain so 1555until it is reset in that scope or until the function returns. 1556Once the function returns, any instance of the variable at a previous 1557scope will become visible. 1558If the unset acts on a variable at a previous scope, any instance of a 1559variable with that name that had been shadowed will become visible. 1560 1561Function names and definitions may be listed with the 1562@option{-f} option to the @code{declare} (@code{typeset}) 1563builtin command (@pxref{Bash Builtins}). 1564The @option{-F} option to @code{declare} or @code{typeset} 1565will list the function names only 1566(and optionally the source file and line number, if the @code{extdebug} 1567shell option is enabled). 1568Functions may be exported so that subshells 1569automatically have them defined with the 1570@option{-f} option to the @code{export} builtin 1571(@pxref{Bourne Shell Builtins}). 1572 1573Functions may be recursive. 1574The @code{FUNCNEST} variable may be used to limit the depth of the 1575function call stack and restrict the number of function invocations. 1576By default, no limit is placed on the number of recursive calls. 1577 1578@node Shell Parameters 1579@section Shell Parameters 1580@cindex parameters 1581@cindex variable, shell 1582@cindex shell variable 1583 1584@menu 1585* Positional Parameters:: The shell's command-line arguments. 1586* Special Parameters:: Parameters denoted by special characters. 1587@end menu 1588 1589A @var{parameter} is an entity that stores values. 1590It can be a @code{name}, a number, or one of the special characters 1591listed below. 1592A @var{variable} is a parameter denoted by a @code{name}. 1593A variable has a @var{value} and zero or more @var{attributes}. 1594Attributes are assigned using the @code{declare} builtin command 1595(see the description of the @code{declare} builtin in @ref{Bash Builtins}). 1596 1597A parameter is set if it has been assigned a value. The null string is 1598a valid value. Once a variable is set, it may be unset only by using 1599the @code{unset} builtin command. 1600 1601A variable may be assigned to by a statement of the form 1602@example 1603@var{name}=[@var{value}] 1604@end example 1605@noindent 1606If @var{value} 1607is not given, the variable is assigned the null string. All 1608@var{value}s undergo tilde expansion, parameter and variable expansion, 1609command substitution, arithmetic expansion, and quote 1610removal (detailed below). If the variable has its @code{integer} 1611attribute set, then @var{value} 1612is evaluated as an arithmetic expression even if the @code{$((@dots{}))} 1613expansion is not used (@pxref{Arithmetic Expansion}). 1614Word splitting is not performed, with the exception 1615of @code{"$@@"} as explained below. 1616Filename expansion is not performed. 1617Assignment statements may also appear as arguments to the 1618@code{alias}, 1619@code{declare}, @code{typeset}, @code{export}, @code{readonly}, 1620and @code{local} builtin commands (@var{declaration} commands). 1621When in @sc{posix} mode (@pxref{Bash POSIX Mode}), these builtins may appear 1622in a command after one or more instances of the @code{command} builtin 1623and retain these assignment statement properties. 1624 1625In the context where an assignment statement is assigning a value 1626to a shell variable or array index (@pxref{Arrays}), the @samp{+=} 1627operator can be used to 1628append to or add to the variable's previous value. 1629This includes arguments to builtin commands such as @code{declare} that 1630accept assignment statements (@var{declaration} commands). 1631When @samp{+=} is applied to a variable for which the @var{integer} attribute 1632has been set, @var{value} is evaluated as an arithmetic expression and 1633added to the variable's current value, which is also evaluated. 1634When @samp{+=} is applied to an array variable using compound assignment 1635(@pxref{Arrays}), the 1636variable's value is not unset (as it is when using @samp{=}), and new 1637values are appended to the array beginning at one greater than the array's 1638maximum index (for indexed arrays), or added as additional key-value pairs 1639in an associative array. 1640When applied to a string-valued variable, @var{value} is expanded and 1641appended to the variable's value. 1642 1643A variable can be assigned the @var{nameref} attribute using the 1644@option{-n} option to the @code{declare} or @code{local} builtin commands 1645(@pxref{Bash Builtins}) 1646to create a @var{nameref}, or a reference to another variable. 1647This allows variables to be manipulated indirectly. 1648Whenever the nameref variable is referenced, assigned to, unset, or has 1649its attributes modified (other than using or changing the nameref 1650attribute itself), the 1651operation is actually performed on the variable specified by the nameref 1652variable's value. 1653A nameref is commonly used within shell functions to refer to a variable 1654whose name is passed as an argument to the function. 1655For instance, if a variable name is passed to a shell function as its first 1656argument, running 1657@example 1658declare -n ref=$1 1659@end example 1660@noindent 1661inside the function creates a nameref variable @var{ref} whose value is 1662the variable name passed as the first argument. 1663References and assignments to @var{ref}, and changes to its attributes, 1664are treated as references, assignments, and attribute modifications 1665to the variable whose name was passed as @code{$1}. 1666 1667If the control variable in a @code{for} loop has the nameref attribute, 1668the list of words can be a list of shell variables, and a name reference 1669will be established for each word in the list, in turn, when the loop is 1670executed. 1671Array variables cannot be given the nameref attribute. 1672However, nameref variables can reference array variables and subscripted 1673array variables. 1674Namerefs can be unset using the @option{-n} option to the @code{unset} builtin 1675(@pxref{Bourne Shell Builtins}). 1676Otherwise, if @code{unset} is executed with the name of a nameref variable 1677as an argument, the variable referenced by the nameref variable will be unset. 1678 1679@node Positional Parameters 1680@subsection Positional Parameters 1681@cindex parameters, positional 1682 1683A @var{positional parameter} is a parameter denoted by one or more 1684digits, other than the single digit @code{0}. Positional parameters are 1685assigned from the shell's arguments when it is invoked, 1686and may be reassigned using the @code{set} builtin command. 1687Positional parameter @code{N} may be referenced as @code{$@{N@}}, or 1688as @code{$N} when @code{N} consists of a single digit. 1689Positional parameters may not be assigned to with assignment statements. 1690The @code{set} and @code{shift} builtins are used to set and 1691unset them (@pxref{Shell Builtin Commands}). 1692The positional parameters are 1693temporarily replaced when a shell function is executed 1694(@pxref{Shell Functions}). 1695 1696When a positional parameter consisting of more than a single 1697digit is expanded, it must be enclosed in braces. 1698 1699@node Special Parameters 1700@subsection Special Parameters 1701@cindex parameters, special 1702 1703The shell treats several parameters specially. These parameters may 1704only be referenced; assignment to them is not allowed. 1705 1706@vtable @code 1707 1708@item * 1709@vindex $* 1710($*) Expands to the positional parameters, starting from one. 1711When the expansion is not within double quotes, each positional parameter 1712expands to a separate word. 1713In contexts where it is performed, those words 1714are subject to further word splitting and filename expansion. 1715When the expansion occurs within double quotes, it expands to a single word 1716with the value of each parameter separated by the first character of the 1717@env{IFS} special variable. That is, @code{"$*"} is equivalent 1718to @code{"$1@var{c}$2@var{c}@dots{}"}, where @var{c} 1719is the first character of the value of the @code{IFS} 1720variable. 1721If @env{IFS} is unset, the parameters are separated by spaces. 1722If @env{IFS} is null, the parameters are joined without intervening 1723separators. 1724 1725@item @@ 1726@vindex $@@ 1727($@@) Expands to the positional parameters, starting from one. 1728In contexts where word splitting is performed, this expands each 1729positional parameter to a separate word; if not within double 1730quotes, these words are subject to word splitting. 1731In contexts where word splitting is not performed, 1732this expands to a single word 1733with each positional parameter separated by a space. 1734When the 1735expansion occurs within double quotes, and word splitting is performed, 1736each parameter expands to a 1737separate word. That is, @code{"$@@"} is equivalent to 1738@code{"$1" "$2" @dots{}}. 1739If the double-quoted expansion occurs within a word, the expansion of 1740the first parameter is joined with the beginning part of the original 1741word, and the expansion of the last parameter is joined with the last 1742part of the original word. 1743When there are no positional parameters, @code{"$@@"} and 1744@code{$@@} 1745expand to nothing (i.e., they are removed). 1746 1747@item # 1748@vindex $# 1749($#) Expands to the number of positional parameters in decimal. 1750 1751@item ? 1752@vindex $? 1753($?) Expands to the exit status of the most recently executed foreground 1754pipeline. 1755 1756@item - 1757@vindex $- 1758($-, a hyphen.) Expands to the current option flags as specified upon 1759invocation, by the @code{set} 1760builtin command, or those set by the shell itself 1761(such as the @option{-i} option). 1762 1763@item $ 1764@vindex $$ 1765($$) Expands to the process @sc{id} of the shell. In a @code{()} subshell, it 1766expands to the process @sc{id} of the invoking shell, not the subshell. 1767 1768@item ! 1769@vindex $! 1770($!) Expands to the process @sc{id} of the job most recently placed into the 1771background, whether executed as an asynchronous command or using 1772the @code{bg} builtin (@pxref{Job Control Builtins}). 1773 1774@item 0 1775@vindex $0 1776($0) Expands to the name of the shell or shell script. This is set at 1777shell initialization. If Bash is invoked with a file of commands 1778(@pxref{Shell Scripts}), @code{$0} is set to the name of that file. 1779If Bash is started with the @option{-c} option (@pxref{Invoking Bash}), 1780then @code{$0} is set to the first argument after the string to be 1781executed, if one is present. Otherwise, it is set 1782to the filename used to invoke Bash, as given by argument zero. 1783@end vtable 1784 1785@node Shell Expansions 1786@section Shell Expansions 1787@cindex expansion 1788 1789Expansion is performed on the command line after it has been split into 1790@code{token}s. There are seven kinds of expansion performed: 1791 1792@itemize @bullet 1793@item brace expansion 1794@item tilde expansion 1795@item parameter and variable expansion 1796@item command substitution 1797@item arithmetic expansion 1798@item word splitting 1799@item filename expansion 1800@end itemize 1801 1802@menu 1803* Brace Expansion:: Expansion of expressions within braces. 1804* Tilde Expansion:: Expansion of the ~ character. 1805* Shell Parameter Expansion:: How Bash expands variables to their values. 1806* Command Substitution:: Using the output of a command as an argument. 1807* Arithmetic Expansion:: How to use arithmetic in shell expansions. 1808* Process Substitution:: A way to write and read to and from a 1809 command. 1810* Word Splitting:: How the results of expansion are split into separate 1811 arguments. 1812* Filename Expansion:: A shorthand for specifying filenames matching patterns. 1813* Quote Removal:: How and when quote characters are removed from 1814 words. 1815@end menu 1816 1817The order of expansions is: 1818brace expansion; 1819tilde expansion, parameter and variable expansion, arithmetic expansion, 1820and command substitution (done in a left-to-right fashion); 1821word splitting; 1822and filename expansion. 1823 1824On systems that can support it, there is an additional expansion 1825available: @var{process substitution}. 1826This is performed at the 1827same time as tilde, parameter, variable, and arithmetic expansion and 1828command substitution. 1829 1830After these expansions are performed, quote characters present in the 1831original word are removed unless they have been quoted themselves 1832(@var{quote removal}). 1833 1834Only brace expansion, word splitting, and filename expansion 1835can increase the number of words of the expansion; other expansions 1836expand a single word to a single word. 1837The only exceptions to this are the expansions of 1838@code{"$@@"} and @code{$*} (@pxref{Special Parameters}), and 1839@code{"$@{@var{name}[@@]@}"} and @code{$@{@var{name}[*]@}} 1840(@pxref{Arrays}). 1841 1842After all expansions, @code{quote removal} (@pxref{Quote Removal}) 1843is performed. 1844 1845@node Brace Expansion 1846@subsection Brace Expansion 1847@cindex brace expansion 1848@cindex expansion, brace 1849 1850Brace expansion is a mechanism by which arbitrary strings may be generated. 1851This mechanism is similar to 1852@var{filename expansion} (@pxref{Filename Expansion}), 1853but the filenames generated need not exist. 1854Patterns to be brace expanded take the form of an optional @var{preamble}, 1855followed by either a series of comma-separated strings or a sequence expression 1856between a pair of braces, 1857followed by an optional @var{postscript}. 1858The preamble is prefixed to each string contained within the braces, and 1859the postscript is then appended to each resulting string, expanding left 1860to right. 1861 1862Brace expansions may be nested. 1863The results of each expanded string are not sorted; left to right order 1864is preserved. 1865For example, 1866@example 1867bash$ echo a@{d,c,b@}e 1868ade ace abe 1869@end example 1870 1871A sequence expression takes the form @code{@{@var{x}..@var{y}[..@var{incr}]@}}, 1872where @var{x} and @var{y} are either integers or single characters, 1873and @var{incr}, an optional increment, is an integer. 1874When integers are supplied, the expression expands to each number between 1875@var{x} and @var{y}, inclusive. 1876Supplied integers may be prefixed with @samp{0} to force each term to have the 1877same width. 1878When either @var{x} or @var{y} begins with a zero, the shell 1879attempts to force all generated terms to contain the same number of digits, 1880zero-padding where necessary. 1881When characters are supplied, the expression expands to each character 1882lexicographically between @var{x} and @var{y}, inclusive, 1883using the default C locale. 1884Note that both @var{x} and @var{y} must be of the same type. 1885When the increment is supplied, it is used as the difference between 1886each term. The default increment is 1 or -1 as appropriate. 1887 1888Brace expansion is performed before any other expansions, 1889and any characters special to other expansions are preserved 1890in the result. It is strictly textual. Bash 1891does not apply any syntactic interpretation to the context of the 1892expansion or the text between the braces. 1893 1894A correctly-formed brace expansion must contain unquoted opening 1895and closing braces, and at least one unquoted comma or a valid 1896sequence expression. 1897Any incorrectly formed brace expansion is left unchanged. 1898 1899A @{ or @samp{,} may be quoted with a backslash to prevent its 1900being considered part of a brace expression. 1901To avoid conflicts with parameter expansion, the string @samp{$@{} 1902is not considered eligible for brace expansion, 1903and inhibits brace expansion until the closing @samp{@}}. 1904 1905This construct is typically used as shorthand when the common 1906prefix of the strings to be generated is longer than in the 1907above example: 1908@example 1909mkdir /usr/local/src/bash/@{old,new,dist,bugs@} 1910@end example 1911or 1912@example 1913chown root /usr/@{ucb/@{ex,edit@},lib/@{ex?.?*,how_ex@}@} 1914@end example 1915 1916@node Tilde Expansion 1917@subsection Tilde Expansion 1918@cindex tilde expansion 1919@cindex expansion, tilde 1920 1921If a word begins with an unquoted tilde character (@samp{~}), all of the 1922characters up to the first unquoted slash (or all characters, 1923if there is no unquoted slash) are considered a @var{tilde-prefix}. 1924If none of the characters in the tilde-prefix are quoted, the 1925characters in the tilde-prefix following the tilde are treated as a 1926possible @var{login name}. 1927If this login name is the null string, the tilde is replaced with the 1928value of the @env{HOME} shell variable. 1929If @env{HOME} is unset, the home directory of the user executing the 1930shell is substituted instead. 1931Otherwise, the tilde-prefix is replaced with the home directory 1932associated with the specified login name. 1933 1934If the tilde-prefix is @samp{~+}, the value of 1935the shell variable @env{PWD} replaces the tilde-prefix. 1936If the tilde-prefix is @samp{~-}, the value of the shell variable 1937@env{OLDPWD}, if it is set, is substituted. 1938 1939If the characters following the tilde in the tilde-prefix consist of a 1940number @var{N}, optionally prefixed by a @samp{+} or a @samp{-}, 1941the tilde-prefix is replaced with the 1942corresponding element from the directory stack, as it would be displayed 1943by the @code{dirs} builtin invoked with the characters following tilde 1944in the tilde-prefix as an argument (@pxref{The Directory Stack}). 1945If the tilde-prefix, sans the tilde, consists of a number without a 1946leading @samp{+} or @samp{-}, @samp{+} is assumed. 1947 1948If the login name is invalid, or the tilde expansion fails, the word is 1949left unchanged. 1950 1951Each variable assignment is checked for unquoted tilde-prefixes immediately 1952following a @samp{:} or the first @samp{=}. 1953In these cases, tilde expansion is also performed. 1954Consequently, one may use filenames with tildes in assignments to 1955@env{PATH}, @env{MAILPATH}, and @env{CDPATH}, 1956and the shell assigns the expanded value. 1957 1958The following table shows how Bash treats unquoted tilde-prefixes: 1959 1960@table @code 1961@item ~ 1962The value of @code{$HOME} 1963@item ~/foo 1964@file{$HOME/foo} 1965 1966@item ~fred/foo 1967The subdirectory @code{foo} of the home directory of the user 1968@code{fred} 1969 1970@item ~+/foo 1971@file{$PWD/foo} 1972 1973@item ~-/foo 1974@file{$@{OLDPWD-'~-'@}/foo} 1975 1976@item ~@var{N} 1977The string that would be displayed by @samp{dirs +@var{N}} 1978 1979@item ~+@var{N} 1980The string that would be displayed by @samp{dirs +@var{N}} 1981 1982@item ~-@var{N} 1983The string that would be displayed by @samp{dirs -@var{N}} 1984@end table 1985 1986Bash also performs tilde expansion on words satisfying the conditions of 1987variable assignments (@pxref{Shell Parameters}) 1988when they appear as arguments to simple commands. 1989Bash does not do this, except for the @var{declaration} commands listed 1990above, when in @sc{posix} mode. 1991 1992@node Shell Parameter Expansion 1993@subsection Shell Parameter Expansion 1994@cindex parameter expansion 1995@cindex expansion, parameter 1996 1997The @samp{$} character introduces parameter expansion, 1998command substitution, or arithmetic expansion. The parameter name 1999or symbol to be expanded may be enclosed in braces, which 2000are optional but serve to protect the variable to be expanded from 2001characters immediately following it which could be 2002interpreted as part of the name. 2003 2004When braces are used, the matching ending brace is the first @samp{@}} 2005not escaped by a backslash or within a quoted string, and not within an 2006embedded arithmetic expansion, command substitution, or parameter 2007expansion. 2008 2009The basic form of parameter expansion is $@{@var{parameter}@}. 2010The value of @var{parameter} is substituted. 2011The @var{parameter} is a shell parameter as described above 2012(@pxref{Shell Parameters}) or an array reference (@pxref{Arrays}). 2013The braces are required when @var{parameter} 2014is a positional parameter with more than one digit, 2015or when @var{parameter} is followed by a character that is not to be 2016interpreted as part of its name. 2017 2018If the first character of @var{parameter} is an exclamation point (!), 2019and @var{parameter} is not a @var{nameref}, 2020it introduces a level of indirection. 2021Bash uses the value formed by expanding the rest of 2022@var{parameter} as the new @var{parameter}; this is then 2023expanded and that value is used in the rest of the expansion, rather 2024than the expansion of the original @var{parameter}. 2025This is known as @code{indirect expansion}. 2026The value is subject to tilde expansion, 2027parameter expansion, command substitution, and arithmetic expansion. 2028If @var{parameter} is a nameref, this expands to the name of the 2029variable referenced by @var{parameter} instead of performing the 2030complete indirect expansion. 2031The exceptions to this are the expansions of $@{!@var{prefix}*@} 2032and $@{!@var{name}[@@]@} 2033described below. 2034The exclamation point must immediately follow the left brace in order to 2035introduce indirection. 2036 2037In each of the cases below, @var{word} is subject to tilde expansion, 2038parameter expansion, command substitution, and arithmetic expansion. 2039 2040When not performing substring expansion, using the form described 2041below (e.g., @samp{:-}), Bash tests for a parameter that is unset or null. 2042Omitting the colon results in a test only for a parameter that is unset. 2043Put another way, if the colon is included, 2044the operator tests for both @var{parameter}'s existence and that its value 2045is not null; if the colon is omitted, the operator tests only for existence. 2046 2047@table @code 2048 2049@item $@{@var{parameter}:@minus{}@var{word}@} 2050If @var{parameter} is unset or null, the expansion of 2051@var{word} is substituted. Otherwise, the value of 2052@var{parameter} is substituted. 2053 2054@item $@{@var{parameter}:=@var{word}@} 2055If @var{parameter} 2056is unset or null, the expansion of @var{word} 2057is assigned to @var{parameter}. 2058The value of @var{parameter} is then substituted. 2059Positional parameters and special parameters may not be assigned to 2060in this way. 2061 2062@item $@{@var{parameter}:?@var{word}@} 2063If @var{parameter} 2064is null or unset, the expansion of @var{word} (or a message 2065to that effect if @var{word} 2066is not present) is written to the standard error and the shell, if it 2067is not interactive, exits. Otherwise, the value of @var{parameter} is 2068substituted. 2069 2070@item $@{@var{parameter}:+@var{word}@} 2071If @var{parameter} 2072is null or unset, nothing is substituted, otherwise the expansion of 2073@var{word} is substituted. 2074 2075@item $@{@var{parameter}:@var{offset}@} 2076@itemx $@{@var{parameter}:@var{offset}:@var{length}@} 2077This is referred to as Substring Expansion. 2078It expands to up to @var{length} characters of the value of @var{parameter} 2079starting at the character specified by @var{offset}. 2080If @var{parameter} is @samp{@@}, an indexed array subscripted by 2081@samp{@@} or @samp{*}, or an associative array name, the results differ as 2082described below. 2083If @var{length} is omitted, it expands to the substring of the value of 2084@var{parameter} starting at the character specified by @var{offset} 2085and extending to the end of the value. 2086@var{length} and @var{offset} are arithmetic expressions 2087(@pxref{Shell Arithmetic}). 2088 2089If @var{offset} evaluates to a number less than zero, the value 2090is used as an offset in characters 2091from the end of the value of @var{parameter}. 2092If @var{length} evaluates to a number less than zero, 2093it is interpreted as an offset in characters 2094from the end of the value of @var{parameter} rather than 2095a number of characters, and the expansion is the characters between 2096@var{offset} and that result. 2097Note that a negative offset must be separated from the colon by at least 2098one space to avoid being confused with the @samp{:-} expansion. 2099 2100Here are some examples illustrating substring expansion on parameters and 2101subscripted arrays: 2102 2103@verbatim 2104$ string=01234567890abcdefgh 2105$ echo ${string:7} 21067890abcdefgh 2107$ echo ${string:7:0} 2108 2109$ echo ${string:7:2} 211078 2111$ echo ${string:7:-2} 21127890abcdef 2113$ echo ${string: -7} 2114bcdefgh 2115$ echo ${string: -7:0} 2116 2117$ echo ${string: -7:2} 2118bc 2119$ echo ${string: -7:-2} 2120bcdef 2121$ set -- 01234567890abcdefgh 2122$ echo ${1:7} 21237890abcdefgh 2124$ echo ${1:7:0} 2125 2126$ echo ${1:7:2} 212778 2128$ echo ${1:7:-2} 21297890abcdef 2130$ echo ${1: -7} 2131bcdefgh 2132$ echo ${1: -7:0} 2133 2134$ echo ${1: -7:2} 2135bc 2136$ echo ${1: -7:-2} 2137bcdef 2138$ array[0]=01234567890abcdefgh 2139$ echo ${array[0]:7} 21407890abcdefgh 2141$ echo ${array[0]:7:0} 2142 2143$ echo ${array[0]:7:2} 214478 2145$ echo ${array[0]:7:-2} 21467890abcdef 2147$ echo ${array[0]: -7} 2148bcdefgh 2149$ echo ${array[0]: -7:0} 2150 2151$ echo ${array[0]: -7:2} 2152bc 2153$ echo ${array[0]: -7:-2} 2154bcdef 2155@end verbatim 2156 2157If @var{parameter} is @samp{@@}, the result is @var{length} positional 2158parameters beginning at @var{offset}. 2159A negative @var{offset} is taken relative to one greater than the greatest 2160positional parameter, so an offset of -1 evaluates to the last positional 2161parameter. 2162It is an expansion error if @var{length} evaluates to a number less than zero. 2163 2164The following examples illustrate substring expansion using positional 2165parameters: 2166 2167@verbatim 2168$ set -- 1 2 3 4 5 6 7 8 9 0 a b c d e f g h 2169$ echo ${@:7} 21707 8 9 0 a b c d e f g h 2171$ echo ${@:7:0} 2172 2173$ echo ${@:7:2} 21747 8 2175$ echo ${@:7:-2} 2176bash: -2: substring expression < 0 2177$ echo ${@: -7:2} 2178b c 2179$ echo ${@:0} 2180./bash 1 2 3 4 5 6 7 8 9 0 a b c d e f g h 2181$ echo ${@:0:2} 2182./bash 1 2183$ echo ${@: -7:0} 2184 2185@end verbatim 2186 2187If @var{parameter} is an indexed array name subscripted 2188by @samp{@@} or @samp{*}, the result is the @var{length} 2189members of the array beginning with @code{$@{@var{parameter}[@var{offset}]@}}. 2190A negative @var{offset} is taken relative to one greater than the maximum 2191index of the specified array. 2192It is an expansion error if @var{length} evaluates to a number less than zero. 2193 2194These examples show how you can use substring expansion with indexed 2195arrays: 2196 2197@verbatim 2198$ array=(0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h) 2199$ echo ${array[@]:7} 22007 8 9 0 a b c d e f g h 2201$ echo ${array[@]:7:2} 22027 8 2203$ echo ${array[@]: -7:2} 2204b c 2205$ echo ${array[@]: -7:-2} 2206bash: -2: substring expression < 0 2207$ echo ${array[@]:0} 22080 1 2 3 4 5 6 7 8 9 0 a b c d e f g h 2209$ echo ${array[@]:0:2} 22100 1 2211$ echo ${array[@]: -7:0} 2212 2213@end verbatim 2214 2215Substring expansion applied to an associative array produces undefined 2216results. 2217 2218Substring indexing is zero-based unless the positional parameters 2219are used, in which case the indexing starts at 1 by default. 2220If @var{offset} is 0, and the positional parameters are used, @code{$0} is 2221prefixed to the list. 2222 2223@item $@{!@var{prefix}*@} 2224@itemx $@{!@var{prefix}@@@} 2225Expands to the names of variables whose names begin with @var{prefix}, 2226separated by the first character of the @env{IFS} special variable. 2227When @samp{@@} is used and the expansion appears within double quotes, each 2228variable name expands to a separate word. 2229 2230@item $@{!@var{name}[@@]@} 2231@itemx $@{!@var{name}[*]@} 2232If @var{name} is an array variable, expands to the list of array indices 2233(keys) assigned in @var{name}. 2234If @var{name} is not an array, expands to 0 if @var{name} is set and null 2235otherwise. 2236When @samp{@@} is used and the expansion appears within double quotes, each 2237key expands to a separate word. 2238 2239@item $@{#@var{parameter}@} 2240The length in characters of the expanded value of @var{parameter} is 2241substituted. 2242If @var{parameter} is @samp{*} or @samp{@@}, the value substituted 2243is the number of positional parameters. 2244If @var{parameter} is an array name subscripted by @samp{*} or @samp{@@}, 2245the value substituted is the number of elements in the array. 2246If @var{parameter} 2247is an indexed array name subscripted by a negative number, that number is 2248interpreted as relative to one greater than the maximum index of 2249@var{parameter}, so negative indices count back from the end of the 2250array, and an index of -1 references the last element. 2251 2252@item $@{@var{parameter}#@var{word}@} 2253@itemx $@{@var{parameter}##@var{word}@} 2254The @var{word} 2255is expanded to produce a pattern and matched according to the rules 2256described below (@pxref{Pattern Matching}). If the pattern matches 2257the beginning of the expanded value of @var{parameter}, 2258then the result of the expansion is the expanded value of @var{parameter} 2259with the shortest matching pattern (the @samp{#} case) or the 2260longest matching pattern (the @samp{##} case) deleted. 2261If @var{parameter} is @samp{@@} or @samp{*}, 2262the pattern removal operation is applied to each positional 2263parameter in turn, and the expansion is the resultant list. 2264If @var{parameter} is an array variable subscripted with 2265@samp{@@} or @samp{*}, 2266the pattern removal operation is applied to each member of the 2267array in turn, and the expansion is the resultant list. 2268 2269@item $@{@var{parameter}%@var{word}@} 2270@itemx $@{@var{parameter}%%@var{word}@} 2271The @var{word} 2272is expanded to produce a pattern and matched according to the rules 2273described below (@pxref{Pattern Matching}). 2274If the pattern matches a trailing portion of the expanded value of 2275@var{parameter}, then the result of the expansion is the value of 2276@var{parameter} with the shortest matching pattern (the @samp{%} case) 2277or the longest matching pattern (the @samp{%%} case) deleted. 2278If @var{parameter} is @samp{@@} or @samp{*}, 2279the pattern removal operation is applied to each positional 2280parameter in turn, and the expansion is the resultant list. 2281If @var{parameter} 2282is an array variable subscripted with @samp{@@} or @samp{*}, 2283the pattern removal operation is applied to each member of the 2284array in turn, and the expansion is the resultant list. 2285 2286@item $@{@var{parameter}/@var{pattern}/@var{string}@} 2287 2288The @var{pattern} is expanded to produce a pattern just as in 2289filename expansion. 2290@var{Parameter} is expanded and the longest match of @var{pattern} 2291against its value is replaced with @var{string}. 2292The match is performed according to the rules described below 2293(@pxref{Pattern Matching}). 2294If @var{pattern} begins with @samp{/}, all matches of @var{pattern} are 2295replaced with @var{string}. Normally only the first match is replaced. 2296If @var{pattern} begins with @samp{#}, it must match at the beginning 2297of the expanded value of @var{parameter}. 2298If @var{pattern} begins with @samp{%}, it must match at the end 2299of the expanded value of @var{parameter}. 2300If @var{string} is null, matches of @var{pattern} are deleted 2301and the @code{/} following @var{pattern} may be omitted. 2302If the @code{nocasematch} shell option 2303(see the description of @code{shopt} in @ref{The Shopt Builtin}) 2304is enabled, the match is performed without regard to the case 2305of alphabetic characters. 2306If @var{parameter} is @samp{@@} or @samp{*}, 2307the substitution operation is applied to each positional 2308parameter in turn, and the expansion is the resultant list. 2309If @var{parameter} 2310is an array variable subscripted with @samp{@@} or @samp{*}, 2311the substitution operation is applied to each member of the 2312array in turn, and the expansion is the resultant list. 2313 2314@item $@{@var{parameter}^@var{pattern}@} 2315@itemx $@{@var{parameter}^^@var{pattern}@} 2316@itemx $@{@var{parameter},@var{pattern}@} 2317@itemx $@{@var{parameter},,@var{pattern}@} 2318This expansion modifies the case of alphabetic characters in @var{parameter}. 2319The @var{pattern} is expanded to produce a pattern just as in 2320filename expansion. 2321Each character in the expanded value of @var{parameter} is tested against 2322@var{pattern}, and, if it matches the pattern, its case is converted. 2323The pattern should not attempt to match more than one character. 2324The @samp{^} operator converts lowercase letters matching @var{pattern} 2325to uppercase; the @samp{,} operator converts matching uppercase letters 2326to lowercase. 2327The @samp{^^} and @samp{,,} expansions convert each matched character in the 2328expanded value; the @samp{^} and @samp{,} expansions match and convert only 2329the first character in the expanded value. 2330If @var{pattern} is omitted, it is treated like a @samp{?}, which matches 2331every character. 2332If @var{parameter} is @samp{@@} or @samp{*}, 2333the case modification operation is applied to each positional 2334parameter in turn, and the expansion is the resultant list. 2335If @var{parameter} 2336is an array variable subscripted with @samp{@@} or @samp{*}, 2337the case modification operation is applied to each member of the 2338array in turn, and the expansion is the resultant list. 2339 2340@item $@{@var{parameter}@@@var{operator}@} 2341The expansion is either a transformation of the value of @var{parameter} 2342or information about @var{parameter} itself, depending on the value of 2343@var{operator}. Each @var{operator} is a single letter: 2344 2345@table @code 2346@item U 2347The expansion is a string that is the value of @var{parameter} with lowercase 2348alphabetic characters converted to uppercase. 2349@item u 2350The expansion is a string that is the value of @var{parameter} with the first 2351character converted to uppercase, if it is alphabetic. 2352@item L 2353The expansion is a string that is the value of @var{parameter} with uppercase 2354alphabetic characters converted to lowercase. 2355@item Q 2356The expansion is a string that is the value of @var{parameter} quoted in a 2357format that can be reused as input. 2358@item E 2359The expansion is a string that is the value of @var{parameter} with backslash 2360escape sequences expanded as with the @code{$'@dots{}'} quoting mechanism. 2361@item P 2362The expansion is a string that is the result of expanding the value of 2363@var{parameter} as if it were a prompt string (@pxref{Controlling the Prompt}). 2364@item A 2365The expansion is a string in the form of 2366an assignment statement or @code{declare} command that, if 2367evaluated, will recreate @var{parameter} with its attributes and value. 2368@item K 2369Produces a possibly-quoted version of the value of @var{parameter}, 2370except that it prints the values of 2371indexed and associative arrays as a sequence of quoted key-value pairs 2372(@pxref{Arrays}). 2373@item a 2374The expansion is a string consisting of flag values representing 2375@var{parameter}'s attributes. 2376@end table 2377 2378If @var{parameter} is @samp{@@} or @samp{*}, 2379the operation is applied to each positional 2380parameter in turn, and the expansion is the resultant list. 2381If @var{parameter} 2382is an array variable subscripted with @samp{@@} or @samp{*}, 2383the operation is applied to each member of the 2384array in turn, and the expansion is the resultant list. 2385 2386The result of the expansion is subject to word splitting and filename 2387expansion as described below. 2388@end table 2389 2390@node Command Substitution 2391@subsection Command Substitution 2392@cindex command substitution 2393 2394Command substitution allows the output of a command to replace 2395the command itself. 2396Command substitution occurs when a command is enclosed as follows: 2397@example 2398$(@var{command}) 2399@end example 2400@noindent 2401or 2402@example 2403`@var{command}` 2404@end example 2405 2406@noindent 2407Bash performs the expansion by executing @var{command} in a subshell environment 2408and replacing the command substitution with the standard output of the 2409command, with any trailing newlines deleted. 2410Embedded newlines are not deleted, but they may be removed during 2411word splitting. 2412The command substitution @code{$(cat @var{file})} can be 2413replaced by the equivalent but faster @code{$(< @var{file})}. 2414 2415When the old-style backquote form of substitution is used, 2416backslash retains its literal meaning except when followed by 2417@samp{$}, @samp{`}, or @samp{\}. 2418The first backquote not preceded by a backslash terminates the 2419command substitution. 2420When using the @code{$(@var{command})} form, all characters between 2421the parentheses make up the command; none are treated specially. 2422 2423Command substitutions may be nested. To nest when using the backquoted 2424form, escape the inner backquotes with backslashes. 2425 2426If the substitution appears within double quotes, word splitting and 2427filename expansion are not performed on the results. 2428 2429@node Arithmetic Expansion 2430@subsection Arithmetic Expansion 2431@cindex expansion, arithmetic 2432@cindex arithmetic expansion 2433 2434Arithmetic expansion allows the evaluation of an arithmetic expression 2435and the substitution of the result. The format for arithmetic expansion is: 2436 2437@example 2438$(( @var{expression} )) 2439@end example 2440 2441The expression is treated as if it were within double quotes, but 2442a double quote inside the parentheses is not treated specially. 2443All tokens in the expression undergo parameter and variable expansion, 2444command substitution, and quote removal. 2445The result is treated as the arithmetic expression to be evaluated. 2446Arithmetic expansions may be nested. 2447 2448The evaluation is performed according to the rules listed below 2449(@pxref{Shell Arithmetic}). 2450If the expression is invalid, Bash prints a message indicating 2451failure to the standard error and no substitution occurs. 2452 2453@node Process Substitution 2454@subsection Process Substitution 2455@cindex process substitution 2456 2457Process substitution allows a process's input or output to be 2458referred to using a filename. 2459It takes the form of 2460@example 2461<(@var{list}) 2462@end example 2463@noindent 2464or 2465@example 2466>(@var{list}) 2467@end example 2468@noindent 2469The process @var{list} is run asynchronously, and its input or output 2470appears as a filename. 2471This filename is 2472passed as an argument to the current command as the result of the 2473expansion. 2474If the @code{>(@var{list})} form is used, writing to 2475the file will provide input for @var{list}. If the 2476@code{<(@var{list})} form is used, the file passed as an 2477argument should be read to obtain the output of @var{list}. 2478Note that no space may appear between the @code{<} or @code{>} 2479and the left parenthesis, otherwise the construct would be interpreted 2480as a redirection. 2481Process substitution is supported on systems that support named 2482pipes (@sc{fifo}s) or the @file{/dev/fd} method of naming open files. 2483 2484When available, process substitution is performed simultaneously with 2485parameter and variable expansion, command substitution, and arithmetic 2486expansion. 2487 2488@node Word Splitting 2489@subsection Word Splitting 2490@cindex word splitting 2491 2492The shell scans the results of parameter expansion, command substitution, 2493and arithmetic expansion that did not occur within double quotes for 2494word splitting. 2495 2496The shell treats each character of @env{$IFS} as a delimiter, and splits 2497the results of the other expansions into words using these characters 2498as field terminators. 2499If @env{IFS} is unset, or its value is exactly @code{<space><tab><newline>}, 2500the default, then sequences of 2501@code{ <space>}, @code{<tab>}, and @code{<newline>} 2502at the beginning and end of the results of the previous 2503expansions are ignored, and any sequence of @env{IFS} 2504characters not at the beginning or end serves to delimit words. 2505If @env{IFS} has a value other than the default, then sequences of 2506the whitespace characters @code{space}, @code{tab}, and @code{newline} 2507are ignored at the beginning and end of the 2508word, as long as the whitespace character is in the 2509value of @env{IFS} (an @env{IFS} whitespace character). 2510Any character in @env{IFS} that is not @env{IFS} 2511whitespace, along with any adjacent @env{IFS} 2512whitespace characters, delimits a field. A sequence of @env{IFS} 2513whitespace characters is also treated as a delimiter. 2514If the value of @env{IFS} is null, no word splitting occurs. 2515 2516Explicit null arguments (@code{""} or @code{''}) are retained 2517and passed to commands as empty strings. 2518Unquoted implicit null arguments, resulting from the expansion of 2519parameters that have no values, are removed. 2520If a parameter with no value is expanded within double quotes, a 2521null argument results and is retained 2522and passed to a command as an empty string. 2523When a quoted null argument appears as part of a word whose expansion is 2524non-null, the null argument is removed. 2525That is, the word 2526@code{-d''} becomes @code{-d} after word splitting and 2527null argument removal. 2528 2529Note that if no expansion occurs, no splitting 2530is performed. 2531 2532@node Filename Expansion 2533@subsection Filename Expansion 2534@menu 2535* Pattern Matching:: How the shell matches patterns. 2536@end menu 2537@cindex expansion, filename 2538@cindex expansion, pathname 2539@cindex filename expansion 2540@cindex pathname expansion 2541 2542After word splitting, unless the @option{-f} option has been set 2543(@pxref{The Set Builtin}), Bash scans each word for the characters 2544@samp{*}, @samp{?}, and @samp{[}. 2545If one of these characters appears, and is not quoted, then the word is 2546regarded as a @var{pattern}, 2547and replaced with an alphabetically sorted list of 2548filenames matching the pattern (@pxref{Pattern Matching}). 2549If no matching filenames are found, 2550and the shell option @code{nullglob} is disabled, the word is left 2551unchanged. 2552If the @code{nullglob} option is set, and no matches are found, the word 2553is removed. 2554If the @code{failglob} shell option is set, and no matches are found, 2555an error message is printed and the command is not executed. 2556If the shell option @code{nocaseglob} is enabled, the match is performed 2557without regard to the case of alphabetic characters. 2558 2559When a pattern is used for filename expansion, the character @samp{.} 2560at the start of a filename or immediately following a slash 2561must be matched explicitly, unless the shell option @code{dotglob} is set. 2562The filenames @samp{.} and @samp{..} must always be matched explicitly, 2563even if @code{dotglob} is set. 2564In other cases, the @samp{.} character is not treated specially. 2565 2566When matching a filename, the slash character must always be 2567matched explicitly by a slash in the pattern, but in other matching 2568contexts it can be matched by a special pattern character as described 2569below (@pxref{Pattern Matching}). 2570 2571See the description of @code{shopt} in @ref{The Shopt Builtin}, 2572for a description of the @code{nocaseglob}, @code{nullglob}, 2573@code{failglob}, and @code{dotglob} options. 2574 2575The @env{GLOBIGNORE} 2576shell variable may be used to restrict the set of file names matching a 2577pattern. If @env{GLOBIGNORE} 2578is set, each matching file name that also matches one of the patterns in 2579@env{GLOBIGNORE} is removed from the list of matches. 2580If the @code{nocaseglob} option is set, the matching against the patterns in 2581@env{GLOBIGNORE} is performed without regard to case. 2582The filenames 2583@file{.} and @file{..} 2584are always ignored when @env{GLOBIGNORE} 2585is set and not null. 2586However, setting @env{GLOBIGNORE} to a non-null value has the effect of 2587enabling the @code{dotglob} 2588shell option, so all other filenames beginning with a 2589@samp{.} will match. 2590To get the old behavior of ignoring filenames beginning with a 2591@samp{.}, make @samp{.*} one of the patterns in @env{GLOBIGNORE}. 2592The @code{dotglob} option is disabled when @env{GLOBIGNORE} 2593is unset. 2594 2595@node Pattern Matching 2596@subsubsection Pattern Matching 2597@cindex pattern matching 2598@cindex matching, pattern 2599 2600Any character that appears in a pattern, other than the special pattern 2601characters described below, matches itself. 2602The @sc{nul} character may not occur in a pattern. 2603A backslash escapes the following character; the 2604escaping backslash is discarded when matching. 2605The special pattern characters must be quoted if they are to be matched 2606literally. 2607 2608The special pattern characters have the following meanings: 2609@table @code 2610@item * 2611Matches any string, including the null string. 2612When the @code{globstar} shell option is enabled, and @samp{*} is used in 2613a filename expansion context, two adjacent @samp{*}s used as a single 2614pattern will match all files and zero or more directories and 2615subdirectories. 2616If followed by a @samp{/}, two adjacent @samp{*}s will match only 2617directories and subdirectories. 2618@item ? 2619Matches any single character. 2620@item [@dots{}] 2621Matches any one of the enclosed characters. A pair of characters 2622separated by a hyphen denotes a @var{range expression}; 2623any character that falls between those two characters, inclusive, 2624using the current locale's collating sequence and character set, 2625is matched. If the first character following the 2626@samp{[} is a @samp{!} or a @samp{^} 2627then any character not enclosed is matched. A @samp{@minus{}} 2628may be matched by including it as the first or last character 2629in the set. A @samp{]} may be matched by including it as the first 2630character in the set. 2631The sorting order of characters in range expressions is determined by 2632the current locale and the values of the 2633@env{LC_COLLATE} and @env{LC_ALL} shell variables, if set. 2634 2635For example, in the default C locale, @samp{[a-dx-z]} is equivalent to 2636@samp{[abcdxyz]}. Many locales sort characters in dictionary order, and in 2637these locales @samp{[a-dx-z]} is typically not equivalent to @samp{[abcdxyz]}; 2638it might be equivalent to @samp{[aBbCcDdxXyYz]}, for example. To obtain 2639the traditional interpretation of ranges in bracket expressions, you can 2640force the use of the C locale by setting the @env{LC_COLLATE} or 2641@env{LC_ALL} environment variable to the value @samp{C}, or enable the 2642@code{globasciiranges} shell option. 2643 2644Within @samp{[} and @samp{]}, @var{character classes} can be specified 2645using the syntax 2646@code{[:}@var{class}@code{:]}, where @var{class} is one of the 2647following classes defined in the @sc{posix} standard: 2648@example 2649alnum alpha ascii blank cntrl digit graph lower 2650print punct space upper word xdigit 2651@end example 2652@noindent 2653A character class matches any character belonging to that class. 2654The @code{word} character class matches letters, digits, and the character 2655@samp{_}. 2656 2657Within @samp{[} and @samp{]}, an @var{equivalence class} can be 2658specified using the syntax @code{[=}@var{c}@code{=]}, which 2659matches all characters with the same collation weight (as defined 2660by the current locale) as the character @var{c}. 2661 2662Within @samp{[} and @samp{]}, the syntax @code{[.}@var{symbol}@code{.]} 2663matches the collating symbol @var{symbol}. 2664@end table 2665 2666If the @code{extglob} shell option is enabled using the @code{shopt} 2667builtin, several extended pattern matching operators are recognized. 2668In the following description, a @var{pattern-list} is a list of one 2669or more patterns separated by a @samp{|}. 2670Composite patterns may be formed using one or more of the following 2671sub-patterns: 2672 2673@table @code 2674@item ?(@var{pattern-list}) 2675Matches zero or one occurrence of the given patterns. 2676 2677@item *(@var{pattern-list}) 2678Matches zero or more occurrences of the given patterns. 2679 2680@item +(@var{pattern-list}) 2681Matches one or more occurrences of the given patterns. 2682 2683@item @@(@var{pattern-list}) 2684Matches one of the given patterns. 2685 2686@item !(@var{pattern-list}) 2687Matches anything except one of the given patterns. 2688@end table 2689 2690Complicated extended pattern matching against long strings is slow, 2691especially when the patterns contain alternations and the strings 2692contain multiple matches. 2693Using separate matches against shorter strings, or using arrays of 2694strings instead of a single long string, may be faster. 2695 2696@node Quote Removal 2697@subsection Quote Removal 2698 2699After the preceding expansions, all unquoted occurrences of the 2700characters @samp{\}, @samp{'}, and @samp{"} that did not 2701result from one of the above expansions are removed. 2702 2703@node Redirections 2704@section Redirections 2705@cindex redirection 2706 2707Before a command is executed, its input and output 2708may be @var{redirected} 2709using a special notation interpreted by the shell. 2710Redirection allows commands' file handles to be 2711duplicated, opened, closed, 2712made to refer to different files, 2713and can change the files the command reads from and writes to. 2714Redirection may also be used to modify file handles in the 2715current shell execution environment. The following redirection 2716operators may precede or appear anywhere within a 2717simple command or may follow a command. 2718Redirections are processed in the order they appear, from 2719left to right. 2720 2721Each redirection that may be preceded by a file descriptor number 2722may instead be preceded by a word of the form @{@var{varname}@}. 2723In this case, for each redirection operator except 2724>&- and <&-, the shell will allocate a file descriptor greater 2725than 10 and assign it to @{@var{varname}@}. If >&- or <&- is preceded 2726by @{@var{varname}@}, the value of @var{varname} defines the file 2727descriptor to close. 2728If @{@var{varname}@} is supplied, the redirection persists beyond 2729the scope of the command, allowing the shell programmer to manage 2730the file descriptor's lifetime manually. 2731 2732In the following descriptions, if the file descriptor number is 2733omitted, and the first character of the redirection operator is 2734@samp{<}, the redirection refers to the standard input (file 2735descriptor 0). If the first character of the redirection operator 2736is @samp{>}, the redirection refers to the standard output (file 2737descriptor 1). 2738 2739The word following the redirection operator in the following 2740descriptions, unless otherwise noted, is subjected to brace expansion, 2741tilde expansion, parameter expansion, command substitution, arithmetic 2742expansion, quote removal, filename expansion, and word splitting. 2743If it expands to more than one word, Bash reports an error. 2744 2745Note that the order of redirections is significant. For example, 2746the command 2747@example 2748ls > @var{dirlist} 2>&1 2749@end example 2750@noindent 2751directs both standard output (file descriptor 1) and standard error 2752(file descriptor 2) to the file @var{dirlist}, while the command 2753@example 2754ls 2>&1 > @var{dirlist} 2755@end example 2756@noindent 2757directs only the standard output to file @var{dirlist}, 2758because the standard error was made a copy of the standard output 2759before the standard output was redirected to @var{dirlist}. 2760 2761Bash handles several filenames specially when they are used in 2762redirections, as described in the following table. 2763If the operating system on which Bash is running provides these 2764special files, bash will use them; otherwise it will emulate them 2765internally with the behavior described below. 2766 2767@table @code 2768@item /dev/fd/@var{fd} 2769If @var{fd} is a valid integer, file descriptor @var{fd} is duplicated. 2770 2771@item /dev/stdin 2772File descriptor 0 is duplicated. 2773 2774@item /dev/stdout 2775File descriptor 1 is duplicated. 2776 2777@item /dev/stderr 2778File descriptor 2 is duplicated. 2779 2780@item /dev/tcp/@var{host}/@var{port} 2781If @var{host} is a valid hostname or Internet address, and @var{port} 2782is an integer port number or service name, Bash attempts to open 2783the corresponding TCP socket. 2784 2785@item /dev/udp/@var{host}/@var{port} 2786If @var{host} is a valid hostname or Internet address, and @var{port} 2787is an integer port number or service name, Bash attempts to open 2788the corresponding UDP socket. 2789@end table 2790 2791A failure to open or create a file causes the redirection to fail. 2792 2793Redirections using file descriptors greater than 9 should be used with 2794care, as they may conflict with file descriptors the shell uses 2795internally. 2796 2797@subsection Redirecting Input 2798Redirection of input causes the file whose name results from 2799the expansion of @var{word} 2800to be opened for reading on file descriptor @code{n}, 2801or the standard input (file descriptor 0) if @code{n} 2802is not specified. 2803 2804The general format for redirecting input is: 2805@example 2806[@var{n}]<@var{word} 2807@end example 2808 2809@subsection Redirecting Output 2810Redirection of output causes the file whose name results from 2811the expansion of @var{word} 2812to be opened for writing on file descriptor @var{n}, 2813or the standard output (file descriptor 1) if @var{n} 2814is not specified. If the file does not exist it is created; 2815if it does exist it is truncated to zero size. 2816 2817The general format for redirecting output is: 2818@example 2819[@var{n}]>[|]@var{word} 2820@end example 2821 2822If the redirection operator is @samp{>}, and the @code{noclobber} 2823option to the @code{set} builtin has been enabled, the redirection 2824will fail if the file whose name results from the expansion of 2825@var{word} exists and is a regular file. 2826If the redirection operator is @samp{>|}, or the redirection operator is 2827@samp{>} and the @code{noclobber} option is not enabled, the redirection 2828is attempted even if the file named by @var{word} exists. 2829 2830@subsection Appending Redirected Output 2831Redirection of output in this fashion 2832causes the file whose name results from 2833the expansion of @var{word} 2834to be opened for appending on file descriptor @var{n}, 2835or the standard output (file descriptor 1) if @var{n} 2836is not specified. If the file does not exist it is created. 2837 2838The general format for appending output is: 2839@example 2840[@var{n}]>>@var{word} 2841@end example 2842 2843@subsection Redirecting Standard Output and Standard Error 2844This construct allows both the 2845standard output (file descriptor 1) and 2846the standard error output (file descriptor 2) 2847to be redirected to the file whose name is the 2848expansion of @var{word}. 2849 2850There are two formats for redirecting standard output and 2851standard error: 2852@example 2853&>@var{word} 2854@end example 2855@noindent 2856and 2857@example 2858>&@var{word} 2859@end example 2860@noindent 2861Of the two forms, the first is preferred. 2862This is semantically equivalent to 2863@example 2864>@var{word} 2>&1 2865@end example 2866When using the second form, @var{word} may not expand to a number or 2867@samp{-}. If it does, other redirection operators apply 2868(see Duplicating File Descriptors below) for compatibility reasons. 2869 2870@subsection Appending Standard Output and Standard Error 2871This construct allows both the 2872standard output (file descriptor 1) and 2873the standard error output (file descriptor 2) 2874to be appended to the file whose name is the 2875expansion of @var{word}. 2876 2877The format for appending standard output and standard error is: 2878@example 2879&>>@var{word} 2880@end example 2881@noindent 2882This is semantically equivalent to 2883@example 2884>>@var{word} 2>&1 2885@end example 2886(see Duplicating File Descriptors below). 2887 2888@subsection Here Documents 2889This type of redirection instructs the shell to read input from the 2890current source until a line containing only @var{word} 2891(with no trailing blanks) is seen. All of 2892the lines read up to that point are then used as the standard 2893input (or file descriptor @var{n} if @var{n} is specified) for a command. 2894 2895The format of here-documents is: 2896@example 2897[@var{n}]<<[@minus{}]@var{word} 2898 @var{here-document} 2899@var{delimiter} 2900@end example 2901 2902No parameter and variable expansion, command substitution, 2903arithmetic expansion, or filename expansion is performed on 2904@var{word}. If any part of @var{word} is quoted, the 2905@var{delimiter} is the result of quote removal on @var{word}, 2906and the lines in the here-document are not expanded. 2907If @var{word} is unquoted, 2908all lines of the here-document are subjected to 2909parameter expansion, command substitution, and arithmetic expansion, 2910the character sequence @code{\newline} is ignored, and @samp{\} 2911must be used to quote the characters 2912@samp{\}, @samp{$}, and @samp{`}. 2913 2914If the redirection operator is @samp{<<-}, 2915then all leading tab characters are stripped from input lines and the 2916line containing @var{delimiter}. 2917This allows here-documents within shell scripts to be indented in a 2918natural fashion. 2919 2920@subsection Here Strings 2921A variant of here documents, the format is: 2922@example 2923[@var{n}]<<< @var{word} 2924@end example 2925 2926The @var{word} undergoes 2927tilde expansion, parameter and variable expansion, 2928command substitution, arithmetic expansion, and quote removal. 2929Filename expansion and word splitting are not performed. 2930The result is supplied as a single string, 2931with a newline appended, 2932to the command on its 2933standard input (or file descriptor @var{n} if @var{n} is specified). 2934 2935@subsection Duplicating File Descriptors 2936The redirection operator 2937@example 2938[@var{n}]<&@var{word} 2939@end example 2940@noindent 2941is used to duplicate input file descriptors. 2942If @var{word} 2943expands to one or more digits, the file descriptor denoted by @var{n} 2944is made to be a copy of that file descriptor. 2945If the digits in @var{word} do not specify a file descriptor open for 2946input, a redirection error occurs. 2947If @var{word} 2948evaluates to @samp{-}, file descriptor @var{n} is closed. 2949If @var{n} is not specified, the standard input (file descriptor 0) is used. 2950 2951The operator 2952@example 2953[@var{n}]>&@var{word} 2954@end example 2955@noindent 2956is used similarly to duplicate output file descriptors. If 2957@var{n} is not specified, the standard output (file descriptor 1) is used. 2958If the digits in @var{word} do not specify a file descriptor open for 2959output, a redirection error occurs. 2960If @var{word} 2961evaluates to @samp{-}, file descriptor @var{n} is closed. 2962As a special case, if @var{n} is omitted, and @var{word} does not 2963expand to one or more digits or @samp{-}, the standard output and standard 2964error are redirected as described previously. 2965 2966@subsection Moving File Descriptors 2967The redirection operator 2968@example 2969[@var{n}]<&@var{digit}- 2970@end example 2971@noindent 2972moves the file descriptor @var{digit} to file descriptor @var{n}, 2973or the standard input (file descriptor 0) if @var{n} is not specified. 2974@var{digit} is closed after being duplicated to @var{n}. 2975 2976Similarly, the redirection operator 2977@example 2978[@var{n}]>&@var{digit}- 2979@end example 2980@noindent 2981moves the file descriptor @var{digit} to file descriptor @var{n}, 2982or the standard output (file descriptor 1) if @var{n} is not specified. 2983 2984@subsection Opening File Descriptors for Reading and Writing 2985The redirection operator 2986@example 2987[@var{n}]<>@var{word} 2988@end example 2989@noindent 2990causes the file whose name is the expansion of @var{word} 2991to be opened for both reading and writing on file descriptor 2992@var{n}, or on file descriptor 0 if @var{n} 2993is not specified. If the file does not exist, it is created. 2994 2995@node Executing Commands 2996@section Executing Commands 2997 2998@menu 2999* Simple Command Expansion:: How Bash expands simple commands before 3000 executing them. 3001* Command Search and Execution:: How Bash finds commands and runs them. 3002* Command Execution Environment:: The environment in which Bash 3003 executes commands that are not 3004 shell builtins. 3005* Environment:: The environment given to a command. 3006* Exit Status:: The status returned by commands and how Bash 3007 interprets it. 3008* Signals:: What happens when Bash or a command it runs 3009 receives a signal. 3010@end menu 3011 3012@node Simple Command Expansion 3013@subsection Simple Command Expansion 3014@cindex command expansion 3015 3016When a simple command is executed, the shell performs the following 3017expansions, assignments, and redirections, from left to right, in 3018the following order. 3019 3020@enumerate 3021@item 3022The words that the parser has marked as variable assignments (those 3023preceding the command name) and redirections are saved for later 3024processing. 3025 3026@item 3027The words that are not variable assignments or redirections are 3028expanded (@pxref{Shell Expansions}). 3029If any words remain after expansion, the first word 3030is taken to be the name of the command and the remaining words are 3031the arguments. 3032 3033@item 3034Redirections are performed as described above (@pxref{Redirections}). 3035 3036@item 3037The text after the @samp{=} in each variable assignment undergoes tilde 3038expansion, parameter expansion, command substitution, arithmetic expansion, 3039and quote removal before being assigned to the variable. 3040@end enumerate 3041 3042If no command name results, the variable assignments affect the current 3043shell environment. Otherwise, the variables are added to the environment 3044of the executed command and do not affect the current shell environment. 3045If any of the assignments attempts to assign a value to a readonly variable, 3046an error occurs, and the command exits with a non-zero status. 3047 3048If no command name results, redirections are performed, but do not 3049affect the current shell environment. A redirection error causes the 3050command to exit with a non-zero status. 3051 3052If there is a command name left after expansion, execution proceeds as 3053described below. Otherwise, the command exits. If one of the expansions 3054contained a command substitution, the exit status of the command is 3055the exit status of the last command substitution performed. If there 3056were no command substitutions, the command exits with a status of zero. 3057 3058@node Command Search and Execution 3059@subsection Command Search and Execution 3060@cindex command execution 3061@cindex command search 3062 3063After a command has been split into words, if it results in a 3064simple command and an optional list of arguments, the following 3065actions are taken. 3066 3067@enumerate 3068@item 3069If the command name contains no slashes, the shell attempts to 3070locate it. If there exists a shell function by that name, that 3071function is invoked as described in @ref{Shell Functions}. 3072 3073@item 3074If the name does not match a function, the shell searches for 3075it in the list of shell builtins. If a match is found, that 3076builtin is invoked. 3077 3078@item 3079If the name is neither a shell function nor a builtin, 3080and contains no slashes, Bash searches each element of 3081@env{$PATH} for a directory containing an executable file 3082by that name. Bash uses a hash table to remember the full 3083pathnames of executable files to avoid multiple @env{PATH} searches 3084(see the description of @code{hash} in @ref{Bourne Shell Builtins}). 3085A full search of the directories in @env{$PATH} 3086is performed only if the command is not found in the hash table. 3087If the search is unsuccessful, the shell searches for a defined shell 3088function named @code{command_not_found_handle}. 3089If that function exists, it is invoked in a separate execution environment 3090with the original command and 3091the original command's arguments as its arguments, and the function's 3092exit status becomes the exit status of that subshell. 3093If that function is not defined, the shell prints an error 3094message and returns an exit status of 127. 3095 3096@item 3097If the search is successful, or if the command name contains 3098one or more slashes, the shell executes the named program in 3099a separate execution environment. 3100Argument 0 is set to the name given, and the remaining arguments 3101to the command are set to the arguments supplied, if any. 3102 3103@item 3104If this execution fails because the file is not in executable 3105format, and the file is not a directory, it is assumed to be a 3106@var{shell script} and the shell executes it as described in 3107@ref{Shell Scripts}. 3108 3109@item 3110If the command was not begun asynchronously, the shell waits for 3111the command to complete and collects its exit status. 3112 3113@end enumerate 3114 3115@node Command Execution Environment 3116@subsection Command Execution Environment 3117@cindex execution environment 3118 3119The shell has an @var{execution environment}, which consists of the 3120following: 3121 3122@itemize @bullet 3123@item 3124open files inherited by the shell at invocation, as modified by 3125redirections supplied to the @code{exec} builtin 3126 3127@item 3128the current working directory as set by @code{cd}, @code{pushd}, or 3129@code{popd}, or inherited by the shell at invocation 3130 3131@item 3132the file creation mode mask as set by @code{umask} or inherited from 3133the shell's parent 3134 3135@item 3136current traps set by @code{trap} 3137 3138@item 3139shell parameters that are set by variable assignment or with @code{set} 3140or inherited from the shell's parent in the environment 3141 3142@item 3143shell functions defined during execution or inherited from the shell's 3144parent in the environment 3145 3146@item 3147options enabled at invocation (either by default or with command-line 3148arguments) or by @code{set} 3149 3150@item 3151options enabled by @code{shopt} (@pxref{The Shopt Builtin}) 3152 3153@item 3154shell aliases defined with @code{alias} (@pxref{Aliases}) 3155 3156@item 3157various process @sc{id}s, including those of background jobs 3158(@pxref{Lists}), the value of @code{$$}, and the value of 3159@env{$PPID} 3160 3161@end itemize 3162 3163When a simple command other than a builtin or shell function 3164is to be executed, it 3165is invoked in a separate execution environment that consists of 3166the following. Unless otherwise noted, the values are inherited 3167from the shell. 3168 3169@itemize @bullet 3170@item 3171the shell's open files, plus any modifications and additions specified 3172by redirections to the command 3173 3174@item 3175the current working directory 3176 3177@item 3178the file creation mode mask 3179 3180@item 3181shell variables and functions marked for export, along with variables 3182exported for the command, passed in the environment (@pxref{Environment}) 3183 3184@item 3185traps caught by the shell are reset to the values inherited from the 3186shell's parent, and traps ignored by the shell are ignored 3187 3188@end itemize 3189 3190A command invoked in this separate environment cannot affect the 3191shell's execution environment. 3192 3193Command substitution, commands grouped with parentheses, 3194and asynchronous commands are invoked in a 3195subshell environment that is a duplicate of the shell environment, 3196except that traps caught by the shell are reset to the values 3197that the shell inherited from its parent at invocation. Builtin 3198commands that are invoked as part of a pipeline are also executed 3199in a subshell environment. Changes made to the subshell environment 3200cannot affect the shell's execution environment. 3201 3202Subshells spawned to execute command substitutions inherit the value of 3203the @option{-e} option from the parent shell. When not in @sc{posix} mode, 3204Bash clears the @option{-e} option in such subshells. 3205 3206If a command is followed by a @samp{&} and job control is not active, the 3207default standard input for the command is the empty file @file{/dev/null}. 3208Otherwise, the invoked command inherits the file descriptors of the calling 3209shell as modified by redirections. 3210 3211@node Environment 3212@subsection Environment 3213@cindex environment 3214 3215When a program is invoked it is given an array of strings 3216called the @var{environment}. 3217This is a list of name-value pairs, of the form @code{name=value}. 3218 3219Bash provides several ways to manipulate the environment. 3220On invocation, the shell scans its own environment and 3221creates a parameter for each name found, automatically marking 3222it for @var{export} 3223to child processes. Executed commands inherit the environment. 3224The @code{export} and @samp{declare -x} 3225commands allow parameters and functions to be added to and 3226deleted from the environment. If the value of a parameter 3227in the environment is modified, the new value becomes part 3228of the environment, replacing the old. The environment 3229inherited by any executed command consists of the shell's 3230initial environment, whose values may be modified in the shell, 3231less any pairs removed by the @code{unset} and @samp{export -n} 3232commands, plus any additions via the @code{export} and 3233@samp{declare -x} commands. 3234 3235The environment for any simple command 3236or function may be augmented temporarily by prefixing it with 3237parameter assignments, as described in @ref{Shell Parameters}. 3238These assignment statements affect only the environment seen 3239by that command. 3240 3241If the @option{-k} option is set (@pxref{The Set Builtin}), then all 3242parameter assignments are placed in the environment for a command, 3243not just those that precede the command name. 3244 3245When Bash invokes an external command, the variable @samp{$_} 3246is set to the full pathname of the command and passed to that 3247command in its environment. 3248 3249@node Exit Status 3250@subsection Exit Status 3251@cindex exit status 3252 3253The exit status of an executed command is the value returned by the 3254@var{waitpid} system call or equivalent function. Exit statuses 3255fall between 0 and 255, though, as explained below, the shell may 3256use values above 125 specially. Exit statuses from shell builtins and 3257compound commands are also limited to this range. Under certain 3258circumstances, the shell will use special values to indicate specific 3259failure modes. 3260 3261For the shell's purposes, a command which exits with a 3262zero exit status has succeeded. 3263A non-zero exit status indicates failure. 3264This seemingly counter-intuitive scheme is used so there 3265is one well-defined way to indicate success and a variety of 3266ways to indicate various failure modes. 3267When a command terminates on a fatal signal whose number is @var{N}, 3268Bash uses the value 128+@var{N} as the exit status. 3269 3270If a command is not found, the child process created to 3271execute it returns a status of 127. If a command is found 3272but is not executable, the return status is 126. 3273 3274If a command fails because of an error during expansion or redirection, 3275the exit status is greater than zero. 3276 3277The exit status is used by the Bash conditional commands 3278(@pxref{Conditional Constructs}) and some of the list 3279constructs (@pxref{Lists}). 3280 3281All of the Bash builtins return an exit status of zero if they succeed 3282and a non-zero status on failure, so they may be used by the 3283conditional and list constructs. 3284All builtins return an exit status of 2 to indicate incorrect usage, 3285generally invalid options or missing arguments. 3286 3287@node Signals 3288@subsection Signals 3289@cindex signal handling 3290 3291When Bash is interactive, in the absence of any traps, it ignores 3292@code{SIGTERM} (so that @samp{kill 0} does not kill an interactive shell), 3293and @code{SIGINT} 3294is caught and handled (so that the @code{wait} builtin is interruptible). 3295When Bash receives a @code{SIGINT}, it breaks out of any executing loops. 3296In all cases, Bash ignores @code{SIGQUIT}. 3297If job control is in effect (@pxref{Job Control}), Bash 3298ignores @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}. 3299 3300Non-builtin commands started by Bash have signal handlers set to the 3301values inherited by the shell from its parent. 3302When job control is not in effect, asynchronous commands 3303ignore @code{SIGINT} and @code{SIGQUIT} in addition to these inherited 3304handlers. 3305Commands run as a result of 3306command substitution ignore the keyboard-generated job control signals 3307@code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}. 3308 3309The shell exits by default upon receipt of a @code{SIGHUP}. 3310Before exiting, an interactive shell resends the @code{SIGHUP} to 3311all jobs, running or stopped. 3312Stopped jobs are sent @code{SIGCONT} to ensure that they receive 3313the @code{SIGHUP}. 3314To prevent the shell from sending the @code{SIGHUP} signal to a 3315particular job, it should be removed 3316from the jobs table with the @code{disown} 3317builtin (@pxref{Job Control Builtins}) or marked 3318to not receive @code{SIGHUP} using @code{disown -h}. 3319 3320If the @code{huponexit} shell option has been set with @code{shopt} 3321(@pxref{The Shopt Builtin}), Bash sends a @code{SIGHUP} to all jobs when 3322an interactive login shell exits. 3323 3324If Bash is waiting for a command to complete and receives a signal 3325for which a trap has been set, the trap will not be executed until 3326the command completes. 3327When Bash is waiting for an asynchronous 3328command via the @code{wait} builtin, the reception of a signal for 3329which a trap has been set will cause the @code{wait} builtin to return 3330immediately with an exit status greater than 128, immediately after 3331which the trap is executed. 3332 3333@node Shell Scripts 3334@section Shell Scripts 3335@cindex shell script 3336 3337A shell script is a text file containing shell commands. When such 3338a file is used as the first non-option argument when invoking Bash, 3339and neither the @option{-c} nor @option{-s} option is supplied 3340(@pxref{Invoking Bash}), 3341Bash reads and executes commands from the file, then exits. This 3342mode of operation creates a non-interactive shell. The shell first 3343searches for the file in the current directory, and looks in the 3344directories in @env{$PATH} if not found there. 3345 3346When Bash runs 3347a shell script, it sets the special parameter @code{0} to the name 3348of the file, rather than the name of the shell, and the positional 3349parameters are set to the remaining arguments, if any are given. 3350If no additional arguments are supplied, the positional parameters 3351are unset. 3352 3353A shell script may be made executable by using the @code{chmod} command 3354to turn on the execute bit. When Bash finds such a file while 3355searching the @env{$PATH} for a command, it spawns a subshell to 3356execute it. In other words, executing 3357@example 3358filename @var{arguments} 3359@end example 3360@noindent 3361is equivalent to executing 3362@example 3363bash filename @var{arguments} 3364@end example 3365 3366@noindent 3367if @code{filename} is an executable shell script. 3368This subshell reinitializes itself, so that the effect is as if a 3369new shell had been invoked to interpret the script, with the 3370exception that the locations of commands remembered by the parent 3371(see the description of @code{hash} in @ref{Bourne Shell Builtins}) 3372are retained by the child. 3373 3374Most versions of Unix make this a part of the operating system's command 3375execution mechanism. If the first line of a script begins with 3376the two characters @samp{#!}, the remainder of the line specifies 3377an interpreter for the program and, depending on the operating system, one 3378or more optional arguments for that interpreter. 3379Thus, you can specify Bash, @code{awk}, Perl, or some other 3380interpreter and write the rest of the script file in that language. 3381 3382The arguments to the interpreter 3383consist of one or more optional arguments following the interpreter 3384name on the first line of the script file, followed by the name of 3385the script file, followed by the rest of the arguments supplied to the 3386script. 3387The details of how the interpreter line is split into an interpreter name 3388and a set of arguments vary across systems. 3389Bash will perform this action on operating systems that do not handle it 3390themselves. 3391Note that some older versions of Unix limit the interpreter 3392name and a single argument to a maximum of 32 characters, so it's not 3393portable to assume that using more than one argument will work. 3394 3395Bash scripts often begin with @code{#! /bin/bash} (assuming that 3396Bash has been installed in @file{/bin}), since this ensures that 3397Bash will be used to interpret the script, even if it is executed 3398under another shell. It's a common idiom to use @code{env} to find 3399@code{bash} even if it's been installed in another directory: 3400@code{#!/usr/bin/env bash} will find the first occurrence of @code{bash} 3401in @env{$PATH}. 3402 3403@node Shell Builtin Commands 3404@chapter Shell Builtin Commands 3405 3406@menu 3407* Bourne Shell Builtins:: Builtin commands inherited from the Bourne 3408 Shell. 3409* Bash Builtins:: Table of builtins specific to Bash. 3410* Modifying Shell Behavior:: Builtins to modify shell attributes and 3411 optional behavior. 3412* Special Builtins:: Builtin commands classified specially by 3413 POSIX. 3414@end menu 3415 3416Builtin commands are contained within the shell itself. 3417When the name of a builtin command is used as the first word of 3418a simple command (@pxref{Simple Commands}), the shell executes 3419the command directly, without invoking another program. 3420Builtin commands are necessary to implement functionality impossible 3421or inconvenient to obtain with separate utilities. 3422 3423This section briefly describes the builtins which Bash inherits from 3424the Bourne Shell, as well as the builtin commands which are unique 3425to or have been extended in Bash. 3426 3427Several builtin commands are described in other chapters: builtin 3428commands which provide the Bash interface to the job control 3429facilities (@pxref{Job Control Builtins}), the directory stack 3430(@pxref{Directory Stack Builtins}), the command history 3431(@pxref{Bash History Builtins}), and the programmable completion 3432facilities (@pxref{Programmable Completion Builtins}). 3433 3434Many of the builtins have been extended by @sc{posix} or Bash. 3435 3436Unless otherwise noted, each builtin command documented as accepting 3437options preceded by @samp{-} accepts @samp{--} 3438to signify the end of the options. 3439The @code{:}, @code{true}, @code{false}, and @code{test}/@code{[} 3440builtins do not accept options and do not treat @samp{--} specially. 3441The @code{exit}, @code{logout}, @code{return}, 3442@code{break}, @code{continue}, @code{let}, 3443and @code{shift} builtins accept and process arguments beginning 3444with @samp{-} without requiring @samp{--}. 3445Other builtins that accept arguments but are not specified as accepting 3446options interpret arguments beginning with @samp{-} as invalid options and 3447require @samp{--} to prevent this interpretation. 3448 3449@node Bourne Shell Builtins 3450@section Bourne Shell Builtins 3451 3452The following shell builtin commands are inherited from the Bourne Shell. 3453These commands are implemented as specified by the @sc{posix} standard. 3454 3455@table @code 3456@item : @r{(a colon)} 3457@btindex : 3458@example 3459: [@var{arguments}] 3460@end example 3461 3462Do nothing beyond expanding @var{arguments} and performing redirections. 3463The return status is zero. 3464 3465@item . @r{(a period)} 3466@btindex . 3467@example 3468. @var{filename} [@var{arguments}] 3469@end example 3470 3471Read and execute commands from the @var{filename} argument in the 3472current shell context. If @var{filename} does not contain a slash, 3473the @env{PATH} variable is used to find @var{filename}. 3474When Bash is not in @sc{posix} mode, the current directory is searched 3475if @var{filename} is not found in @env{$PATH}. 3476If any @var{arguments} are supplied, they become the positional 3477parameters when @var{filename} is executed. Otherwise the positional 3478parameters are unchanged. 3479If the @option{-T} option is enabled, @code{source} inherits any trap on 3480@code{DEBUG}; if it is not, any @code{DEBUG} trap string is saved and 3481restored around the call to @code{source}, and @code{source} unsets the 3482@code{DEBUG} trap while it executes. 3483If @option{-T} is not set, and the sourced file changes 3484the @code{DEBUG} trap, the new value is retained when @code{source} completes. 3485The return status is the exit status of the last command executed, or 3486zero if no commands are executed. If @var{filename} is not found, or 3487cannot be read, the return status is non-zero. 3488This builtin is equivalent to @code{source}. 3489 3490@item break 3491@btindex break 3492@example 3493break [@var{n}] 3494@end example 3495 3496Exit from a @code{for}, @code{while}, @code{until}, or @code{select} loop. 3497If @var{n} is supplied, the @var{n}th enclosing loop is exited. 3498@var{n} must be greater than or equal to 1. 3499The return status is zero unless @var{n} is not greater than or equal to 1. 3500 3501@item cd 3502@btindex cd 3503@example 3504cd [-L|[-P [-e]] [-@@] [@var{directory}] 3505@end example 3506 3507Change the current working directory to @var{directory}. 3508If @var{directory} is not supplied, the value of the @env{HOME} 3509shell variable is used. 3510Any additional arguments following @var{directory} are ignored. 3511If the shell variable 3512@env{CDPATH} exists, it is used as a search path: 3513each directory name in @env{CDPATH} is searched for 3514@var{directory}, with alternative directory names in @env{CDPATH} 3515separated by a colon (@samp{:}). 3516If @var{directory} begins with a slash, @env{CDPATH} is not used. 3517 3518The @option{-P} option means to not follow symbolic links: symbolic links 3519are resolved while @code{cd} is traversing @var{directory} and before 3520processing an instance of @samp{..} in @var{directory}. 3521 3522By default, or when the @option{-L} option is supplied, symbolic links 3523in @var{directory} are resolved after @code{cd} processes an instance 3524of @samp{..} in @var{directory}. 3525 3526If @samp{..} appears in @var{directory}, it is processed by removing the 3527immediately preceding pathname component, back to a slash or the beginning 3528of @var{directory}. 3529 3530If the @option{-e} option is supplied with @option{-P} 3531and the current working directory cannot be successfully determined 3532after a successful directory change, @code{cd} will return an unsuccessful 3533status. 3534 3535On systems that support it, the @option{-@@} option presents the extended 3536attributes associated with a file as a directory. 3537 3538If @var{directory} is @samp{-}, it is converted to @env{$OLDPWD} 3539before the directory change is attempted. 3540 3541If a non-empty directory name from @env{CDPATH} is used, or if 3542@samp{-} is the first argument, and the directory change is 3543successful, the absolute pathname of the new working directory is 3544written to the standard output. 3545 3546The return status is zero if the directory is successfully changed, 3547non-zero otherwise. 3548 3549@item continue 3550@btindex continue 3551@example 3552continue [@var{n}] 3553@end example 3554 3555Resume the next iteration of an enclosing @code{for}, @code{while}, 3556@code{until}, or @code{select} loop. 3557If @var{n} is supplied, the execution of the @var{n}th enclosing loop 3558is resumed. 3559@var{n} must be greater than or equal to 1. 3560The return status is zero unless @var{n} is not greater than or equal to 1. 3561 3562@item eval 3563@btindex eval 3564@example 3565eval [@var{arguments}] 3566@end example 3567 3568The arguments are concatenated together into a single command, which is 3569then read and executed, and its exit status returned as the exit status 3570of @code{eval}. 3571If there are no arguments or only empty arguments, the return status is 3572zero. 3573 3574@item exec 3575@btindex exec 3576@example 3577exec [-cl] [-a @var{name}] [@var{command} [@var{arguments}]] 3578@end example 3579 3580If @var{command} 3581is supplied, it replaces the shell without creating a new process. 3582If the @option{-l} option is supplied, the shell places a dash at the 3583beginning of the zeroth argument passed to @var{command}. 3584This is what the @code{login} program does. 3585The @option{-c} option causes @var{command} to be executed with an empty 3586environment. 3587If @option{-a} is supplied, the shell passes @var{name} as the zeroth 3588argument to @var{command}. 3589If @var{command} 3590cannot be executed for some reason, a non-interactive shell exits, 3591unless the @code{execfail} shell option 3592is enabled. In that case, it returns failure. 3593An interactive shell returns failure if the file cannot be executed. 3594A subshell exits unconditionally if @code{exec} fails. 3595If no @var{command} is specified, redirections may be used to affect 3596the current shell environment. If there are no redirection errors, the 3597return status is zero; otherwise the return status is non-zero. 3598 3599@item exit 3600@btindex exit 3601@example 3602exit [@var{n}] 3603@end example 3604 3605Exit the shell, returning a status of @var{n} to the shell's parent. 3606If @var{n} is omitted, the exit status is that of the last command executed. 3607Any trap on @code{EXIT} is executed before the shell terminates. 3608 3609@item export 3610@btindex export 3611@example 3612export [-fn] [-p] [@var{name}[=@var{value}]] 3613@end example 3614 3615Mark each @var{name} to be passed to child processes 3616in the environment. If the @option{-f} option is supplied, the @var{name}s 3617refer to shell functions; otherwise the names refer to shell variables. 3618The @option{-n} option means to no longer mark each @var{name} for export. 3619If no @var{names} are supplied, or if the @option{-p} option is given, a 3620list of names of all exported variables is displayed. 3621The @option{-p} option displays output in a form that may be reused as input. 3622If a variable name is followed by =@var{value}, the value of 3623the variable is set to @var{value}. 3624 3625The return status is zero unless an invalid option is supplied, one of 3626the names is not a valid shell variable name, or @option{-f} is supplied 3627with a name that is not a shell function. 3628 3629@item getopts 3630@btindex getopts 3631@example 3632getopts @var{optstring} @var{name} [@var{arg} @dots{}] 3633@end example 3634 3635@code{getopts} is used by shell scripts to parse positional parameters. 3636@var{optstring} contains the option characters to be recognized; if a 3637character is followed by a colon, the option is expected to have an 3638argument, which should be separated from it by whitespace. 3639The colon (@samp{:}) and question mark (@samp{?}) may not be 3640used as option characters. 3641Each time it is invoked, @code{getopts} 3642places the next option in the shell variable @var{name}, initializing 3643@var{name} if it does not exist, 3644and the index of the next argument to be processed into the 3645variable @env{OPTIND}. 3646@env{OPTIND} is initialized to 1 each time the shell or a shell script 3647is invoked. 3648When an option requires an argument, 3649@code{getopts} places that argument into the variable @env{OPTARG}. 3650The shell does not reset @env{OPTIND} automatically; it must be manually 3651reset between multiple calls to @code{getopts} within the same shell 3652invocation if a new set of parameters is to be used. 3653 3654When the end of options is encountered, @code{getopts} exits with a 3655return value greater than zero. 3656@env{OPTIND} is set to the index of the first non-option argument, 3657and @var{name} is set to @samp{?}. 3658 3659@code{getopts} 3660normally parses the positional parameters, but if more arguments are 3661supplied as @var{arg} values, @code{getopts} parses those instead. 3662 3663@code{getopts} can report errors in two ways. If the first character of 3664@var{optstring} is a colon, @var{silent} 3665error reporting is used. In normal operation, diagnostic messages 3666are printed when invalid options or missing option arguments are 3667encountered. 3668If the variable @env{OPTERR} 3669is set to 0, no error messages will be displayed, even if the first 3670character of @code{optstring} is not a colon. 3671 3672If an invalid option is seen, 3673@code{getopts} places @samp{?} into @var{name} and, if not silent, 3674prints an error message and unsets @env{OPTARG}. 3675If @code{getopts} is silent, the option character found is placed in 3676@env{OPTARG} and no diagnostic message is printed. 3677 3678If a required argument is not found, and @code{getopts} 3679is not silent, a question mark (@samp{?}) is placed in @var{name}, 3680@code{OPTARG} is unset, and a diagnostic message is printed. 3681If @code{getopts} is silent, then a colon (@samp{:}) is placed in 3682@var{name} and @env{OPTARG} is set to the option character found. 3683 3684@item hash 3685@btindex hash 3686@example 3687hash [-r] [-p @var{filename}] [-dt] [@var{name}] 3688@end example 3689 3690Each time @code{hash} is invoked, it remembers the full pathnames of the 3691commands specified as @var{name} arguments, 3692so they need not be searched for on subsequent invocations. 3693The commands are found by searching through the directories listed in 3694@env{$PATH}. 3695Any previously-remembered pathname is discarded. 3696The @option{-p} option inhibits the path search, and @var{filename} is 3697used as the location of @var{name}. 3698The @option{-r} option causes the shell to forget all remembered locations. 3699The @option{-d} option causes the shell to forget the remembered location 3700of each @var{name}. 3701If the @option{-t} option is supplied, the full pathname to which each 3702@var{name} corresponds is printed. If multiple @var{name} arguments are 3703supplied with @option{-t}, the @var{name} is printed before the hashed 3704full pathname. 3705The @option{-l} option causes output to be displayed in a format 3706that may be reused as input. 3707If no arguments are given, or if only @option{-l} is supplied, 3708information about remembered commands is printed. 3709The return status is zero unless a @var{name} is not found or an invalid 3710option is supplied. 3711 3712@item pwd 3713@btindex pwd 3714@example 3715pwd [-LP] 3716@end example 3717 3718Print the absolute pathname of the current working directory. 3719If the @option{-P} option is supplied, the pathname printed will not 3720contain symbolic links. 3721If the @option{-L} option is supplied, the pathname printed may contain 3722symbolic links. 3723The return status is zero unless an error is encountered while 3724determining the name of the current directory or an invalid option 3725is supplied. 3726 3727@item readonly 3728@btindex readonly 3729@example 3730readonly [-aAf] [-p] [@var{name}[=@var{value}]] @dots{} 3731@end example 3732 3733Mark each @var{name} as readonly. 3734The values of these names may not be changed by subsequent assignment. 3735If the @option{-f} option is supplied, each @var{name} refers to a shell 3736function. 3737The @option{-a} option means each @var{name} refers to an indexed 3738array variable; the @option{-A} option means each @var{name} refers 3739to an associative array variable. 3740If both options are supplied, @option{-A} takes precedence. 3741If no @var{name} arguments are given, or if the @option{-p} 3742option is supplied, a list of all readonly names is printed. 3743The other options may be used to restrict the output to a subset of 3744the set of readonly names. 3745The @option{-p} option causes output to be displayed in a format that 3746may be reused as input. 3747If a variable name is followed by =@var{value}, the value of 3748the variable is set to @var{value}. 3749The return status is zero unless an invalid option is supplied, one of 3750the @var{name} arguments is not a valid shell variable or function name, 3751or the @option{-f} option is supplied with a name that is not a shell function. 3752 3753@item return 3754@btindex return 3755@example 3756return [@var{n}] 3757@end example 3758 3759Cause a shell function to stop executing and return the value @var{n} 3760to its caller. 3761If @var{n} is not supplied, the return value is the exit status of the 3762last command executed in the function. 3763If @code{return} is executed by a trap handler, the last command used to 3764determine the status is the last command executed before the trap handler. 3765If @code{return} is executed during a @code{DEBUG} trap, the last command 3766used to determine the status is the last command executed by the trap 3767handler before @code{return} was invoked. 3768@code{return} may also be used to terminate execution of a script 3769being executed with the @code{.} (@code{source}) builtin, 3770returning either @var{n} or 3771the exit status of the last command executed within the script as the exit 3772status of the script. 3773If @var{n} is supplied, the return value is its least significant 37748 bits. 3775Any command associated with the @code{RETURN} trap is executed 3776before execution resumes after the function or script. 3777The return status is non-zero if @code{return} is supplied a non-numeric 3778argument or is used outside a function 3779and not during the execution of a script by @code{.} or @code{source}. 3780 3781@item shift 3782@btindex shift 3783@example 3784shift [@var{n}] 3785@end example 3786 3787Shift the positional parameters to the left by @var{n}. 3788The positional parameters from @var{n}+1 @dots{} @code{$#} are 3789renamed to @code{$1} @dots{} @code{$#}-@var{n}. 3790Parameters represented by the numbers @code{$#} down to @code{$#}-@var{n}+1 3791are unset. 3792@var{n} must be a non-negative number less than or equal to @code{$#}. 3793If @var{n} is zero or greater than @code{$#}, the positional parameters 3794are not changed. 3795If @var{n} is not supplied, it is assumed to be 1. 3796The return status is zero unless @var{n} is greater than @code{$#} or 3797less than zero, non-zero otherwise. 3798 3799@item test 3800@itemx [ 3801@btindex test 3802@btindex [ 3803@example 3804test @var{expr} 3805@end example 3806 3807Evaluate a conditional expression @var{expr} and return a status of 0 3808(true) or 1 (false). 3809Each operator and operand must be a separate argument. 3810Expressions are composed of the primaries described below in 3811@ref{Bash Conditional Expressions}. 3812@code{test} does not accept any options, nor does it accept and ignore 3813an argument of @option{--} as signifying the end of options. 3814 3815When the @code{[} form is used, the last argument to the command must 3816be a @code{]}. 3817 3818Expressions may be combined using the following operators, listed in 3819decreasing order of precedence. 3820The evaluation depends on the number of arguments; see below. 3821Operator precedence is used when there are five or more arguments. 3822 3823@table @code 3824@item ! @var{expr} 3825True if @var{expr} is false. 3826 3827@item ( @var{expr} ) 3828Returns the value of @var{expr}. 3829This may be used to override the normal precedence of operators. 3830 3831@item @var{expr1} -a @var{expr2} 3832True if both @var{expr1} and @var{expr2} are true. 3833 3834@item @var{expr1} -o @var{expr2} 3835True if either @var{expr1} or @var{expr2} is true. 3836@end table 3837 3838The @code{test} and @code{[} builtins evaluate conditional 3839expressions using a set of rules based on the number of arguments. 3840 3841@table @asis 3842@item 0 arguments 3843The expression is false. 3844 3845@item 1 argument 3846The expression is true if, and only if, the argument is not null. 3847 3848@item 2 arguments 3849If the first argument is @samp{!}, the expression is true if and 3850only if the second argument is null. 3851If the first argument is one of the unary conditional operators 3852(@pxref{Bash Conditional Expressions}), the expression 3853is true if the unary test is true. 3854If the first argument is not a valid unary operator, the expression is 3855false. 3856 3857@item 3 arguments 3858The following conditions are applied in the order listed. 3859 3860@enumerate 3861@item 3862If the second argument is one of the binary conditional 3863operators (@pxref{Bash Conditional Expressions}), the 3864result of the expression is the result of the binary test using the 3865first and third arguments as operands. 3866The @samp{-a} and @samp{-o} operators are considered binary operators 3867when there are three arguments. 3868@item 3869If the first argument is @samp{!}, the value is the negation of 3870the two-argument test using the second and third arguments. 3871@item 3872If the first argument is exactly @samp{(} and the third argument is 3873exactly @samp{)}, the result is the one-argument test of the second 3874argument. 3875@item 3876Otherwise, the expression is false. 3877@end enumerate 3878 3879@item 4 arguments 3880If the first argument is @samp{!}, the result is the negation of 3881the three-argument expression composed of the remaining arguments. 3882Otherwise, the expression is parsed and evaluated according to 3883precedence using the rules listed above. 3884 3885@item 5 or more arguments 3886The expression is parsed and evaluated according to precedence 3887using the rules listed above. 3888@end table 3889 3890When used with @code{test} or @samp{[}, the @samp{<} and @samp{>} 3891operators sort lexicographically using ASCII ordering. 3892 3893@item times 3894@btindex times 3895@example 3896times 3897@end example 3898 3899Print out the user and system times used by the shell and its children. 3900The return status is zero. 3901 3902@item trap 3903@btindex trap 3904@example 3905trap [-lp] [@var{arg}] [@var{sigspec} @dots{}] 3906@end example 3907 3908The commands in @var{arg} are to be read and executed when the 3909shell receives signal @var{sigspec}. If @var{arg} is absent (and 3910there is a single @var{sigspec}) or 3911equal to @samp{-}, each specified signal's disposition is reset 3912to the value it had when the shell was started. 3913If @var{arg} is the null string, then the signal specified by 3914each @var{sigspec} is ignored by the shell and commands it invokes. 3915If @var{arg} is not present and @option{-p} has been supplied, 3916the shell displays the trap commands associated with each @var{sigspec}. 3917If no arguments are supplied, or 3918only @option{-p} is given, @code{trap} prints the list of commands 3919associated with each signal number in a form that may be reused as 3920shell input. 3921The @option{-l} option causes the shell to print a list of signal names 3922and their corresponding numbers. 3923Each @var{sigspec} is either a signal name or a signal number. 3924Signal names are case insensitive and the @code{SIG} prefix is optional. 3925 3926If a @var{sigspec} 3927is @code{0} or @code{EXIT}, @var{arg} is executed when the shell exits. 3928If a @var{sigspec} is @code{DEBUG}, the command @var{arg} is executed 3929before every simple command, @code{for} command, @code{case} command, 3930@code{select} command, every arithmetic @code{for} command, and before 3931the first command executes in a shell function. 3932Refer to the description of the @code{extdebug} option to the 3933@code{shopt} builtin (@pxref{The Shopt Builtin}) for details of its 3934effect on the @code{DEBUG} trap. 3935If a @var{sigspec} is @code{RETURN}, the command @var{arg} is executed 3936each time a shell function or a script executed with the @code{.} or 3937@code{source} builtins finishes executing. 3938 3939If a @var{sigspec} is @code{ERR}, the command @var{arg} 3940is executed whenever 3941a pipeline (which may consist of a single simple 3942command), a list, or a compound command returns a 3943non-zero exit status, 3944subject to the following conditions. 3945The @code{ERR} trap is not executed if the failed command is part of the 3946command list immediately following an @code{until} or @code{while} keyword, 3947part of the test following the @code{if} or @code{elif} reserved words, 3948part of a command executed in a @code{&&} or @code{||} list 3949except the command following the final @code{&&} or @code{||}, 3950any command in a pipeline but the last, 3951or if the command's return 3952status is being inverted using @code{!}. 3953These are the same conditions obeyed by the @code{errexit} (@option{-e}) 3954option. 3955 3956Signals ignored upon entry to the shell cannot be trapped or reset. 3957Trapped signals that are not being ignored are reset to their original 3958values in a subshell or subshell environment when one is created. 3959 3960The return status is zero unless a @var{sigspec} does not specify a 3961valid signal. 3962 3963@item umask 3964@btindex umask 3965@example 3966umask [-p] [-S] [@var{mode}] 3967@end example 3968 3969Set the shell process's file creation mask to @var{mode}. If 3970@var{mode} begins with a digit, it is interpreted as an octal number; 3971if not, it is interpreted as a symbolic mode mask similar 3972to that accepted by the @code{chmod} command. If @var{mode} is 3973omitted, the current value of the mask is printed. If the @option{-S} 3974option is supplied without a @var{mode} argument, the mask is printed 3975in a symbolic format. 3976If the @option{-p} option is supplied, and @var{mode} 3977is omitted, the output is in a form that may be reused as input. 3978The return status is zero if the mode is successfully changed or if 3979no @var{mode} argument is supplied, and non-zero otherwise. 3980 3981Note that when the mode is interpreted as an octal number, each number 3982of the umask is subtracted from @code{7}. Thus, a umask of @code{022} 3983results in permissions of @code{755}. 3984 3985@item unset 3986@btindex unset 3987@example 3988unset [-fnv] [@var{name}] 3989@end example 3990 3991Remove each variable or function @var{name}. 3992If the @option{-v} option is given, each 3993@var{name} refers to a shell variable and that variable is removed. 3994If the @option{-f} option is given, the @var{name}s refer to shell 3995functions, and the function definition is removed. 3996If the @option{-n} option is supplied, and @var{name} is a variable with 3997the @var{nameref} attribute, @var{name} will be unset rather than the 3998variable it references. 3999@option{-n} has no effect if the @option{-f} option is supplied. 4000If no options are supplied, each @var{name} refers to a variable; if 4001there is no variable by that name, a function with that name, if any, is 4002unset. 4003Readonly variables and functions may not be unset. 4004Some shell variables lose their special behavior if they are unset; such 4005behavior is noted in the description of the individual variables. 4006The return status is zero unless a @var{name} is readonly. 4007@end table 4008 4009@node Bash Builtins 4010@section Bash Builtin Commands 4011 4012This section describes builtin commands which are unique to 4013or have been extended in Bash. 4014Some of these commands are specified in the @sc{posix} standard. 4015 4016@table @code 4017 4018@item alias 4019@btindex alias 4020@example 4021alias [-p] [@var{name}[=@var{value}] @dots{}] 4022@end example 4023 4024Without arguments or with the @option{-p} option, @code{alias} prints 4025the list of aliases on the standard output in a form that allows 4026them to be reused as input. 4027If arguments are supplied, an alias is defined for each @var{name} 4028whose @var{value} is given. If no @var{value} is given, the name 4029and value of the alias is printed. 4030Aliases are described in @ref{Aliases}. 4031 4032@item bind 4033@btindex bind 4034@example 4035bind [-m @var{keymap}] [-lpsvPSVX] 4036bind [-m @var{keymap}] [-q @var{function}] [-u @var{function}] [-r @var{keyseq}] 4037bind [-m @var{keymap}] -f @var{filename} 4038bind [-m @var{keymap}] -x @var{keyseq:shell-command} 4039bind [-m @var{keymap}] @var{keyseq:function-name} 4040bind [-m @var{keymap}] @var{keyseq:readline-command} 4041@end example 4042 4043Display current Readline (@pxref{Command Line Editing}) 4044key and function bindings, 4045bind a key sequence to a Readline function or macro, 4046or set a Readline variable. 4047Each non-option argument is a command as it would appear in a 4048Readline initialization file (@pxref{Readline Init File}), 4049but each binding or command must be passed as a separate argument; e.g., 4050@samp{"\C-x\C-r":re-read-init-file}. 4051 4052Options, if supplied, have the following meanings: 4053 4054@table @code 4055@item -m @var{keymap} 4056Use @var{keymap} as the keymap to be affected by 4057the subsequent bindings. Acceptable @var{keymap} 4058names are 4059@code{emacs}, 4060@code{emacs-standard}, 4061@code{emacs-meta}, 4062@code{emacs-ctlx}, 4063@code{vi}, 4064@code{vi-move}, 4065@code{vi-command}, and 4066@code{vi-insert}. 4067@code{vi} is equivalent to @code{vi-command} (@code{vi-move} is also a 4068synonym); @code{emacs} is equivalent to @code{emacs-standard}. 4069 4070@item -l 4071List the names of all Readline functions. 4072 4073@item -p 4074Display Readline function names and bindings in such a way that they 4075can be used as input or in a Readline initialization file. 4076 4077@item -P 4078List current Readline function names and bindings. 4079 4080@item -v 4081Display Readline variable names and values in such a way that they 4082can be used as input or in a Readline initialization file. 4083 4084@item -V 4085List current Readline variable names and values. 4086 4087@item -s 4088Display Readline key sequences bound to macros and the strings they output 4089in such a way that they can be used as input or in a Readline 4090initialization file. 4091 4092@item -S 4093Display Readline key sequences bound to macros and the strings they output. 4094 4095@item -f @var{filename} 4096Read key bindings from @var{filename}. 4097 4098@item -q @var{function} 4099Query about which keys invoke the named @var{function}. 4100 4101@item -u @var{function} 4102Unbind all keys bound to the named @var{function}. 4103 4104@item -r @var{keyseq} 4105Remove any current binding for @var{keyseq}. 4106 4107@item -x @var{keyseq:shell-command} 4108Cause @var{shell-command} to be executed whenever @var{keyseq} is 4109entered. 4110When @var{shell-command} is executed, the shell sets the 4111@code{READLINE_LINE} variable to the contents of the Readline line 4112buffer and the @code{READLINE_POINT} and @code{READLINE_MARK} variables 4113to the current location of the insertion point and the saved insertion 4114point (the @var{mark}), respectively. 4115If the executed command changes the value of any of @code{READLINE_LINE}, 4116@code{READLINE_POINT}, or @code{READLINE_MARK}, those new values will be 4117reflected in the editing state. 4118 4119@item -X 4120List all key sequences bound to shell commands and the associated commands 4121in a format that can be reused as input. 4122@end table 4123 4124@noindent 4125The return status is zero unless an invalid option is supplied or an 4126error occurs. 4127 4128@item builtin 4129@btindex builtin 4130@example 4131builtin [@var{shell-builtin} [@var{args}]] 4132@end example 4133 4134Run a shell builtin, passing it @var{args}, and return its exit status. 4135This is useful when defining a shell function with the same 4136name as a shell builtin, retaining the functionality of the builtin within 4137the function. 4138The return status is non-zero if @var{shell-builtin} is not a shell 4139builtin command. 4140 4141@item caller 4142@btindex caller 4143@example 4144caller [@var{expr}] 4145@end example 4146 4147Returns the context of any active subroutine call (a shell function or 4148a script executed with the @code{.} or @code{source} builtins). 4149 4150Without @var{expr}, @code{caller} displays the line number and source 4151filename of the current subroutine call. 4152If a non-negative integer is supplied as @var{expr}, @code{caller} 4153displays the line number, subroutine name, and source file corresponding 4154to that position in the current execution call stack. This extra 4155information may be used, for example, to print a stack trace. The 4156current frame is frame 0. 4157 4158The return value is 0 unless the shell is not executing a subroutine 4159call or @var{expr} does not correspond to a valid position in the 4160call stack. 4161 4162@item command 4163@btindex command 4164@example 4165command [-pVv] @var{command} [@var{arguments} @dots{}] 4166@end example 4167 4168Runs @var{command} with @var{arguments} ignoring any shell function 4169named @var{command}. 4170Only shell builtin commands or commands found by searching the 4171@env{PATH} are executed. 4172If there is a shell function named @code{ls}, running @samp{command ls} 4173within the function will execute the external command @code{ls} 4174instead of calling the function recursively. 4175The @option{-p} option means to use a default value for @env{PATH} 4176that is guaranteed to find all of the standard utilities. 4177The return status in this case is 127 if @var{command} cannot be 4178found or an error occurred, and the exit status of @var{command} 4179otherwise. 4180 4181If either the @option{-V} or @option{-v} option is supplied, a 4182description of @var{command} is printed. The @option{-v} option 4183causes a single word indicating the command or file name used to 4184invoke @var{command} to be displayed; the @option{-V} option produces 4185a more verbose description. In this case, the return status is 4186zero if @var{command} is found, and non-zero if not. 4187 4188@item declare 4189@btindex declare 4190@example 4191declare [-aAfFgiIlnrtux] [-p] [@var{name}[=@var{value}] @dots{}] 4192@end example 4193 4194Declare variables and give them attributes. If no @var{name}s 4195are given, then display the values of variables instead. 4196 4197The @option{-p} option will display the attributes and values of each 4198@var{name}. 4199When @option{-p} is used with @var{name} arguments, additional options, 4200other than @option{-f} and @option{-F}, are ignored. 4201 4202When @option{-p} is supplied without @var{name} arguments, @code{declare} 4203will display the attributes and values of all variables having the 4204attributes specified by the additional options. 4205If no other options are supplied with @option{-p}, @code{declare} will 4206display the attributes and values of all shell variables. The @option{-f} 4207option will restrict the display to shell functions. 4208 4209The @option{-F} option inhibits the display of function definitions; 4210only the function name and attributes are printed. 4211If the @code{extdebug} shell option is enabled using @code{shopt} 4212(@pxref{The Shopt Builtin}), the source file name and line number where 4213each @var{name} is defined are displayed as well. 4214@option{-F} implies @option{-f}. 4215 4216The @option{-g} option forces variables to be created or modified at 4217the global scope, even when @code{declare} is executed in a shell function. 4218It is ignored in all other cases. 4219 4220The @option{-I} option causes local variables to inherit the attributes 4221(except the @var{nameref} attribute) 4222and value of any existing variable with the same 4223@var{name} at a surrounding scope. 4224If there is no existing variable, the local variable is initially unset. 4225 4226The following options can be used to restrict output to variables with 4227the specified attributes or to give variables attributes: 4228 4229@table @code 4230@item -a 4231Each @var{name} is an indexed array variable (@pxref{Arrays}). 4232 4233@item -A 4234Each @var{name} is an associative array variable (@pxref{Arrays}). 4235 4236@item -f 4237Use function names only. 4238 4239@item -i 4240The variable is to be treated as 4241an integer; arithmetic evaluation (@pxref{Shell Arithmetic}) is 4242performed when the variable is assigned a value. 4243 4244@item -l 4245When the variable is assigned a value, all upper-case characters are 4246converted to lower-case. 4247The upper-case attribute is disabled. 4248 4249@item -n 4250Give each @var{name} the @var{nameref} attribute, making 4251it a name reference to another variable. 4252That other variable is defined by the value of @var{name}. 4253All references, assignments, and attribute modifications 4254to @var{name}, except for those using or changing the 4255@option{-n} attribute itself, are performed on the variable referenced by 4256@var{name}'s value. 4257The nameref attribute cannot be applied to array variables. 4258 4259@item -r 4260Make @var{name}s readonly. These names cannot then be assigned values 4261by subsequent assignment statements or unset. 4262 4263@item -t 4264Give each @var{name} the @code{trace} attribute. 4265Traced functions inherit the @code{DEBUG} and @code{RETURN} traps from 4266the calling shell. 4267The trace attribute has no special meaning for variables. 4268 4269@item -u 4270When the variable is assigned a value, all lower-case characters are 4271converted to upper-case. 4272The lower-case attribute is disabled. 4273 4274@item -x 4275Mark each @var{name} for export to subsequent commands via 4276the environment. 4277@end table 4278 4279Using @samp{+} instead of @samp{-} turns off the attribute instead, 4280with the exceptions that @samp{+a} and @samp{+A} 4281may not be used to destroy array variables and @samp{+r} will not 4282remove the readonly attribute. 4283When used in a function, @code{declare} makes each @var{name} local, 4284as with the @code{local} command, unless the @option{-g} option is used. 4285If a variable name is followed by =@var{value}, the value of the variable 4286is set to @var{value}. 4287 4288When using @option{-a} or @option{-A} and the compound assignment syntax to 4289create array variables, additional attributes do not take effect until 4290subsequent assignments. 4291 4292The return status is zero unless an invalid option is encountered, 4293an attempt is made to define a function using @samp{-f foo=bar}, 4294an attempt is made to assign a value to a readonly variable, 4295an attempt is made to assign a value to an array variable without 4296using the compound assignment syntax (@pxref{Arrays}), 4297one of the @var{names} is not a valid shell variable name, 4298an attempt is made to turn off readonly status for a readonly variable, 4299an attempt is made to turn off array status for an array variable, 4300or an attempt is made to display a non-existent function with @option{-f}. 4301 4302@item echo 4303@btindex echo 4304@example 4305echo [-neE] [@var{arg} @dots{}] 4306@end example 4307 4308Output the @var{arg}s, separated by spaces, terminated with a 4309newline. 4310The return status is 0 unless a write error occurs. 4311If @option{-n} is specified, the trailing newline is suppressed. 4312If the @option{-e} option is given, interpretation of the following 4313backslash-escaped characters is enabled. 4314The @option{-E} option disables the interpretation of these escape characters, 4315even on systems where they are interpreted by default. 4316The @code{xpg_echo} shell option may be used to 4317dynamically determine whether or not @code{echo} expands these 4318escape characters by default. 4319@code{echo} does not interpret @option{--} to mean the end of options. 4320 4321@code{echo} interprets the following escape sequences: 4322@table @code 4323@item \a 4324alert (bell) 4325@item \b 4326backspace 4327@item \c 4328suppress further output 4329@item \e 4330@itemx \E 4331escape 4332@item \f 4333form feed 4334@item \n 4335new line 4336@item \r 4337carriage return 4338@item \t 4339horizontal tab 4340@item \v 4341vertical tab 4342@item \\ 4343backslash 4344@item \0@var{nnn} 4345the eight-bit character whose value is the octal value @var{nnn} 4346(zero to three octal digits) 4347@item \x@var{HH} 4348the eight-bit character whose value is the hexadecimal value @var{HH} 4349(one or two hex digits) 4350@item \u@var{HHHH} 4351the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value 4352@var{HHHH} (one to four hex digits) 4353@item \U@var{HHHHHHHH} 4354the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value 4355@var{HHHHHHHH} (one to eight hex digits) 4356@end table 4357 4358@item enable 4359@btindex enable 4360@example 4361enable [-a] [-dnps] [-f @var{filename}] [@var{name} @dots{}] 4362@end example 4363 4364Enable and disable builtin shell commands. 4365Disabling a builtin allows a disk command which has the same name 4366as a shell builtin to be executed without specifying a full pathname, 4367even though the shell normally searches for builtins before disk commands. 4368If @option{-n} is used, the @var{name}s become disabled. Otherwise 4369@var{name}s are enabled. For example, to use the @code{test} binary 4370found via @env{$PATH} instead of the shell builtin version, type 4371@samp{enable -n test}. 4372 4373If the @option{-p} option is supplied, or no @var{name} arguments appear, 4374a list of shell builtins is printed. With no other arguments, the list 4375consists of all enabled shell builtins. 4376The @option{-a} option means to list 4377each builtin with an indication of whether or not it is enabled. 4378 4379The @option{-f} option means to load the new builtin command @var{name} 4380from shared object @var{filename}, on systems that support dynamic loading. 4381The @option{-d} option will delete a builtin loaded with @option{-f}. 4382 4383If there are no options, a list of the shell builtins is displayed. 4384The @option{-s} option restricts @code{enable} to the @sc{posix} special 4385builtins. If @option{-s} is used with @option{-f}, the new builtin becomes 4386a special builtin (@pxref{Special Builtins}). 4387 4388The return status is zero unless a @var{name} is not a shell builtin 4389or there is an error loading a new builtin from a shared object. 4390 4391@item help 4392@btindex help 4393@example 4394help [-dms] [@var{pattern}] 4395@end example 4396 4397Display helpful information about builtin commands. 4398If @var{pattern} is specified, @code{help} gives detailed help 4399on all commands matching @var{pattern}, otherwise a list of 4400the builtins is printed. 4401 4402Options, if supplied, have the following meanings: 4403 4404@table @code 4405@item -d 4406Display a short description of each @var{pattern} 4407@item -m 4408Display the description of each @var{pattern} in a manpage-like format 4409@item -s 4410Display only a short usage synopsis for each @var{pattern} 4411@end table 4412 4413The return status is zero unless no command matches @var{pattern}. 4414 4415@item let 4416@btindex let 4417@example 4418let @var{expression} [@var{expression} @dots{}] 4419@end example 4420 4421The @code{let} builtin allows arithmetic to be performed on shell 4422variables. Each @var{expression} is evaluated according to the 4423rules given below in @ref{Shell Arithmetic}. If the 4424last @var{expression} evaluates to 0, @code{let} returns 1; 4425otherwise 0 is returned. 4426 4427@item local 4428@btindex local 4429@example 4430local [@var{option}] @var{name}[=@var{value}] @dots{} 4431@end example 4432 4433For each argument, a local variable named @var{name} is created, 4434and assigned @var{value}. 4435The @var{option} can be any of the options accepted by @code{declare}. 4436@code{local} can only be used within a function; it makes the variable 4437@var{name} have a visible scope restricted to that function and its 4438children. 4439If @var{name} is @samp{-}, the set of shell options is made local to the 4440function in which @code{local} is invoked: shell options changed using 4441the @code{set} builtin inside the function are restored to their original 4442values when the function returns. 4443The restore is effected as if a series of @code{set} commands were executed 4444to restore the values that were in place before the function. 4445The return status is zero unless @code{local} is used outside 4446a function, an invalid @var{name} is supplied, or @var{name} is a 4447readonly variable. 4448 4449@item logout 4450@btindex logout 4451@example 4452logout [@var{n}] 4453@end example 4454 4455Exit a login shell, returning a status of @var{n} to the shell's 4456parent. 4457 4458@item mapfile 4459@btindex mapfile 4460@example 4461mapfile [-d @var{delim}] [-n @var{count}] [-O @var{origin}] [-s @var{count}] 4462 [-t] [-u @var{fd}] [-C @var{callback}] [-c @var{quantum}] [@var{array}] 4463@end example 4464 4465Read lines from the standard input into the indexed array variable @var{array}, 4466or from file descriptor @var{fd} 4467if the @option{-u} option is supplied. 4468The variable @code{MAPFILE} is the default @var{array}. 4469Options, if supplied, have the following meanings: 4470 4471@table @code 4472 4473@item -d 4474The first character of @var{delim} is used to terminate each input line, 4475rather than newline. 4476If @var{delim} is the empty string, @code{mapfile} will terminate a line 4477when it reads a NUL character. 4478@item -n 4479Copy at most @var{count} lines. If @var{count} is 0, all lines are copied. 4480@item -O 4481Begin assigning to @var{array} at index @var{origin}. 4482The default index is 0. 4483@item -s 4484Discard the first @var{count} lines read. 4485@item -t 4486Remove a trailing @var{delim} (default newline) from each line read. 4487@item -u 4488Read lines from file descriptor @var{fd} instead of the standard input. 4489@item -C 4490Evaluate @var{callback} each time @var{quantum} lines are read. 4491The @option{-c} option specifies @var{quantum}. 4492@item -c 4493Specify the number of lines read between each call to @var{callback}. 4494@end table 4495 4496If @option{-C} is specified without @option{-c}, 4497the default quantum is 5000. 4498When @var{callback} is evaluated, it is supplied the index of the next 4499array element to be assigned and the line to be assigned to that element 4500as additional arguments. 4501@var{callback} is evaluated after the line is read but before the 4502array element is assigned. 4503 4504If not supplied with an explicit origin, @code{mapfile} will clear @var{array} 4505before assigning to it. 4506 4507@code{mapfile} returns successfully unless an invalid option or option 4508argument is supplied, @var{array} is invalid or unassignable, or @var{array} 4509is not an indexed array. 4510 4511@item printf 4512@btindex printf 4513@example 4514printf [-v @var{var}] @var{format} [@var{arguments}] 4515@end example 4516 4517Write the formatted @var{arguments} to the standard output under the 4518control of the @var{format}. 4519The @option{-v} option causes the output to be assigned to the variable 4520@var{var} rather than being printed to the standard output. 4521 4522The @var{format} is a character string which contains three types of objects: 4523plain characters, which are simply copied to standard output, character 4524escape sequences, which are converted and copied to the standard output, and 4525format specifications, each of which causes printing of the next successive 4526@var{argument}. 4527In addition to the standard @code{printf(1)} formats, @code{printf} 4528interprets the following extensions: 4529 4530@table @code 4531@item %b 4532Causes @code{printf} to expand backslash escape sequences in the 4533corresponding @var{argument} in the same way as @code{echo -e} 4534(@pxref{Bash Builtins}). 4535@item %q 4536Causes @code{printf} to output the 4537corresponding @var{argument} in a format that can be reused as shell input. 4538@item %(@var{datefmt})T 4539Causes @code{printf} to output the date-time string resulting from using 4540@var{datefmt} as a format string for @code{strftime}(3). 4541The corresponding @var{argument} is an integer representing the number of 4542seconds since the epoch. 4543Two special argument values may be used: -1 represents the current 4544time, and -2 represents the time the shell was invoked. 4545If no argument is specified, conversion behaves as if -1 had been given. 4546This is an exception to the usual @code{printf} behavior. 4547@end table 4548 4549@noindent 4550The %b, %q, and %T directives all use the field width and precision 4551arguments from the format specification and write that many bytes from 4552(or use that wide a field for) the expanded argument, which usually 4553contains more characters than the original. 4554 4555Arguments to non-string format specifiers are treated as C language constants, 4556except that a leading plus or minus sign is allowed, and if the leading 4557character is a single or double quote, the value is the ASCII value of 4558the following character. 4559 4560The @var{format} is reused as necessary to consume all of the @var{arguments}. 4561If the @var{format} requires more @var{arguments} than are supplied, the 4562extra format specifications behave as if a zero value or null string, as 4563appropriate, had been supplied. The return value is zero on success, 4564non-zero on failure. 4565 4566@item read 4567@btindex read 4568@example 4569read [-ers] [-a @var{aname}] [-d @var{delim}] [-i @var{text}] [-n @var{nchars}] 4570 [-N @var{nchars}] [-p @var{prompt}] [-t @var{timeout}] [-u @var{fd}] [@var{name} @dots{}] 4571@end example 4572 4573One line is read from the standard input, or from the file descriptor 4574@var{fd} supplied as an argument to the @option{-u} option, 4575split into words as described above in @ref{Word Splitting}, 4576and the first word 4577is assigned to the first @var{name}, the second word to the second @var{name}, 4578and so on. 4579If there are more words than names, 4580the remaining words and their intervening delimiters are assigned 4581to the last @var{name}. 4582If there are fewer words read from the input stream than names, 4583the remaining names are assigned empty values. 4584The characters in the value of the @env{IFS} variable 4585are used to split the line into words using the same rules the shell 4586uses for expansion (described above in @ref{Word Splitting}). 4587The backslash character @samp{\} may be used to remove any special 4588meaning for the next character read and for line continuation. 4589 4590Options, if supplied, have the following meanings: 4591 4592@table @code 4593@item -a @var{aname} 4594The words are assigned to sequential indices of the array variable 4595@var{aname}, starting at 0. 4596All elements are removed from @var{aname} before the assignment. 4597Other @var{name} arguments are ignored. 4598 4599@item -d @var{delim} 4600The first character of @var{delim} is used to terminate the input line, 4601rather than newline. 4602If @var{delim} is the empty string, @code{read} will terminate a line 4603when it reads a NUL character. 4604 4605@item -e 4606Readline (@pxref{Command Line Editing}) is used to obtain the line. 4607Readline uses the current (or default, if line editing was not previously 4608active) editing settings, but uses Readline's default filename completion. 4609 4610@item -i @var{text} 4611If Readline is being used to read the line, @var{text} is placed into 4612the editing buffer before editing begins. 4613 4614@item -n @var{nchars} 4615@code{read} returns after reading @var{nchars} characters rather than 4616waiting for a complete line of input, but honors a delimiter if fewer 4617than @var{nchars} characters are read before the delimiter. 4618 4619@item -N @var{nchars} 4620@code{read} returns after reading exactly @var{nchars} characters rather 4621than waiting for a complete line of input, unless EOF is encountered or 4622@code{read} times out. 4623Delimiter characters encountered in the input are 4624not treated specially and do not cause @code{read} to return until 4625@var{nchars} characters are read. 4626The result is not split on the characters in @code{IFS}; the intent is 4627that the variable is assigned exactly the characters read 4628(with the exception of backslash; see the @option{-r} option below). 4629 4630@item -p @var{prompt} 4631Display @var{prompt}, without a trailing newline, before attempting 4632to read any input. 4633The prompt is displayed only if input is coming from a terminal. 4634 4635@item -r 4636If this option is given, backslash does not act as an escape character. 4637The backslash is considered to be part of the line. 4638In particular, a backslash-newline pair may not then be used as a line 4639continuation. 4640 4641@item -s 4642Silent mode. If input is coming from a terminal, characters are 4643not echoed. 4644 4645@item -t @var{timeout} 4646Cause @code{read} to time out and return failure if a complete line of 4647input (or a specified number of characters) 4648is not read within @var{timeout} seconds. 4649@var{timeout} may be a decimal number with a fractional portion following 4650the decimal point. 4651This option is only effective if @code{read} is reading input from a 4652terminal, pipe, or other special file; it has no effect when reading 4653from regular files. 4654If @code{read} times out, @code{read} saves any partial input read into 4655the specified variable @var{name}. 4656If @var{timeout} is 0, @code{read} returns immediately, without trying to 4657read any data. The exit status is 0 if input is available on 4658the specified file descriptor, non-zero otherwise. 4659The exit status is greater than 128 if the timeout is exceeded. 4660 4661@item -u @var{fd} 4662Read input from file descriptor @var{fd}. 4663@end table 4664 4665If no @var{name}s are supplied, the line read, 4666without the ending delimiter but otherwise unmodified, 4667is assigned to the 4668variable @env{REPLY}. 4669The exit status is zero, unless end-of-file is encountered, @code{read} 4670times out (in which case the status is greater than 128), 4671a variable assignment error (such as assigning to a readonly variable) occurs, 4672or an invalid file descriptor is supplied as the argument to @option{-u}. 4673 4674@item readarray 4675@btindex readarray 4676@example 4677readarray [-d @var{delim}] [-n @var{count}] [-O @var{origin}] [-s @var{count}] 4678 [-t] [-u @var{fd}] [-C @var{callback}] [-c @var{quantum}] [@var{array}] 4679@end example 4680 4681Read lines from the standard input into the indexed array variable @var{array}, 4682or from file descriptor @var{fd} 4683if the @option{-u} option is supplied. 4684 4685A synonym for @code{mapfile}. 4686 4687@item source 4688@btindex source 4689@example 4690source @var{filename} 4691@end example 4692 4693A synonym for @code{.} (@pxref{Bourne Shell Builtins}). 4694 4695@item type 4696@btindex type 4697@example 4698type [-afptP] [@var{name} @dots{}] 4699@end example 4700 4701For each @var{name}, indicate how it would be interpreted if used as a 4702command name. 4703 4704If the @option{-t} option is used, @code{type} prints a single word 4705which is one of @samp{alias}, @samp{function}, @samp{builtin}, 4706@samp{file} or @samp{keyword}, 4707if @var{name} is an alias, shell function, shell builtin, 4708disk file, or shell reserved word, respectively. 4709If the @var{name} is not found, then nothing is printed, and 4710@code{type} returns a failure status. 4711 4712If the @option{-p} option is used, @code{type} either returns the name 4713of the disk file that would be executed, or nothing if @option{-t} 4714would not return @samp{file}. 4715 4716The @option{-P} option forces a path search for each @var{name}, even if 4717@option{-t} would not return @samp{file}. 4718 4719If a command is hashed, @option{-p} and @option{-P} print the hashed value, 4720which is not necessarily the file that appears first in @code{$PATH}. 4721 4722If the @option{-a} option is used, @code{type} returns all of the places 4723that contain an executable named @var{file}. 4724This includes aliases and functions, if and only if the @option{-p} option 4725is not also used. 4726 4727If the @option{-f} option is used, @code{type} does not attempt to find 4728shell functions, as with the @code{command} builtin. 4729 4730The return status is zero if all of the @var{names} are found, non-zero 4731if any are not found. 4732 4733@item typeset 4734@btindex typeset 4735@example 4736typeset [-afFgrxilnrtux] [-p] [@var{name}[=@var{value}] @dots{}] 4737@end example 4738 4739The @code{typeset} command is supplied for compatibility with the Korn 4740shell. 4741It is a synonym for the @code{declare} builtin command. 4742 4743@item ulimit 4744@btindex ulimit 4745@example 4746ulimit [-HS] -a 4747ulimit [-HS] [-bcdefiklmnpqrstuvxPRT] [@var{limit}] 4748@end example 4749 4750@code{ulimit} provides control over the resources available to processes 4751started by the shell, on systems that allow such control. If an 4752option is given, it is interpreted as follows: 4753 4754@table @code 4755@item -S 4756Change and report the soft limit associated with a resource. 4757 4758@item -H 4759Change and report the hard limit associated with a resource. 4760 4761@item -a 4762All current limits are reported; no limits are set. 4763 4764@item -b 4765The maximum socket buffer size. 4766 4767@item -c 4768The maximum size of core files created. 4769 4770@item -d 4771The maximum size of a process's data segment. 4772 4773@item -e 4774The maximum scheduling priority ("nice"). 4775 4776@item -f 4777The maximum size of files written by the shell and its children. 4778 4779@item -i 4780The maximum number of pending signals. 4781 4782@item -k 4783The maximum number of kqueues that may be allocated. 4784 4785@item -l 4786The maximum size that may be locked into memory. 4787 4788@item -m 4789The maximum resident set size (many systems do not honor this limit). 4790 4791@item -n 4792The maximum number of open file descriptors (most systems do not 4793allow this value to be set). 4794 4795@item -p 4796The pipe buffer size. 4797 4798@item -q 4799The maximum number of bytes in @sc{posix} message queues. 4800 4801@item -r 4802The maximum real-time scheduling priority. 4803 4804@item -s 4805The maximum stack size. 4806 4807@item -t 4808The maximum amount of cpu time in seconds. 4809 4810@item -u 4811The maximum number of processes available to a single user. 4812 4813@item -v 4814The maximum amount of virtual memory available to the shell, and, on 4815some systems, to its children. 4816 4817@item -x 4818The maximum number of file locks. 4819 4820@item -P 4821The maximum number of pseudoterminals. 4822 4823@item -R 4824The maximum time a real-time process can run before blocking, in microseconds. 4825 4826@item -T 4827The maximum number of threads. 4828@end table 4829 4830If @var{limit} is given, and the @option{-a} option is not used, 4831@var{limit} is the new value of the specified resource. 4832The special @var{limit} values @code{hard}, @code{soft}, and 4833@code{unlimited} stand for the current hard limit, the current soft limit, 4834and no limit, respectively. 4835A hard limit cannot be increased by a non-root user once it is set; 4836a soft limit may be increased up to the value of the hard limit. 4837Otherwise, the current value of the soft limit for the specified resource 4838is printed, unless the @option{-H} option is supplied. 4839When more than one 4840resource is specified, the limit name and unit, if appropriate, 4841are printed before the value. 4842When setting new limits, if neither @option{-H} nor @option{-S} is supplied, 4843both the hard and soft limits are set. 4844If no option is given, then @option{-f} is assumed. Values are in 1024-byte 4845increments, except for 4846@option{-t}, which is in seconds; 4847@option{-R}, which is in microseconds; 4848@option{-p}, which is in units of 512-byte blocks; 4849@option{-P}, 4850@option{-T}, 4851@option{-b}, 4852@option{-k}, 4853@option{-n} and @option{-u}, which are unscaled values; 4854and, when in @sc{posix} Mode (@pxref{Bash POSIX Mode}), 4855@option{-c} and @option{-f}, which are in 512-byte increments. 4856 4857The return status is zero unless an invalid option or argument is supplied, 4858or an error occurs while setting a new limit. 4859 4860@item unalias 4861@btindex unalias 4862@example 4863unalias [-a] [@var{name} @dots{} ] 4864@end example 4865 4866Remove each @var{name} from the list of aliases. If @option{-a} is 4867supplied, all aliases are removed. 4868Aliases are described in @ref{Aliases}. 4869@end table 4870 4871@node Modifying Shell Behavior 4872@section Modifying Shell Behavior 4873 4874@menu 4875* The Set Builtin:: Change the values of shell attributes and 4876 positional parameters. 4877* The Shopt Builtin:: Modify shell optional behavior. 4878@end menu 4879 4880@node The Set Builtin 4881@subsection The Set Builtin 4882 4883This builtin is so complicated that it deserves its own section. @code{set} 4884allows you to change the values of shell options and set the positional 4885parameters, or to display the names and values of shell variables. 4886 4887@table @code 4888@item set 4889@btindex set 4890@example 4891set [--abefhkmnptuvxBCEHPT] [-o @var{option-name}] [@var{argument} @dots{}] 4892set [+abefhkmnptuvxBCEHPT] [+o @var{option-name}] [@var{argument} @dots{}] 4893@end example 4894 4895If no options or arguments are supplied, @code{set} displays the names 4896and values of all shell variables and functions, sorted according to the 4897current locale, in a format that may be reused as input 4898for setting or resetting the currently-set variables. 4899Read-only variables cannot be reset. 4900In @sc{posix} mode, only shell variables are listed. 4901 4902When options are supplied, they set or unset shell attributes. 4903Options, if specified, have the following meanings: 4904 4905@table @code 4906@item -a 4907Each variable or function that is created or modified is given the 4908export attribute and marked for export to the environment of 4909subsequent commands. 4910 4911@item -b 4912Cause the status of terminated background jobs to be reported 4913immediately, rather than before printing the next primary prompt. 4914 4915@item -e 4916Exit immediately if 4917a pipeline (@pxref{Pipelines}), which may consist of a single simple command 4918(@pxref{Simple Commands}), 4919a list (@pxref{Lists}), 4920or a compound command (@pxref{Compound Commands}) 4921returns a non-zero status. 4922The shell does not exit if the command that fails is part of the 4923command list immediately following a @code{while} or @code{until} keyword, 4924part of the test in an @code{if} statement, 4925part of any command executed in a @code{&&} or @code{||} list except 4926the command following the final @code{&&} or @code{||}, 4927any command in a pipeline but the last, 4928or if the command's return status is being inverted with @code{!}. 4929If a compound command other than a subshell 4930returns a non-zero status because a command failed 4931while @option{-e} was being ignored, the shell does not exit. 4932A trap on @code{ERR}, if set, is executed before the shell exits. 4933 4934This option applies to the shell environment and each subshell environment 4935separately (@pxref{Command Execution Environment}), and may cause 4936subshells to exit before executing all the commands in the subshell. 4937 4938If a compound command or shell function executes in a context where 4939@option{-e} is being ignored, 4940none of the commands executed within the compound command or function body 4941will be affected by the @option{-e} setting, even if @option{-e} is set 4942and a command returns a failure status. 4943If a compound command or shell function sets @option{-e} while executing in 4944a context where @option{-e} is ignored, that setting will not have any 4945effect until the compound command or the command containing the function 4946call completes. 4947 4948@item -f 4949Disable filename expansion (globbing). 4950 4951@item -h 4952Locate and remember (hash) commands as they are looked up for execution. 4953This option is enabled by default. 4954 4955@item -k 4956All arguments in the form of assignment statements are placed 4957in the environment for a command, not just those that precede 4958the command name. 4959 4960@item -m 4961Job control is enabled (@pxref{Job Control}). 4962All processes run in a separate process group. 4963When a background job completes, the shell prints a line 4964containing its exit status. 4965 4966@item -n 4967Read commands but do not execute them. 4968This may be used to check a script for syntax errors. 4969This option is ignored by interactive shells. 4970 4971@item -o @var{option-name} 4972 4973Set the option corresponding to @var{option-name}: 4974 4975@table @code 4976@item allexport 4977Same as @code{-a}. 4978 4979@item braceexpand 4980Same as @code{-B}. 4981 4982@item emacs 4983Use an @code{emacs}-style line editing interface (@pxref{Command Line Editing}). 4984This also affects the editing interface used for @code{read -e}. 4985 4986@item errexit 4987Same as @code{-e}. 4988 4989@item errtrace 4990Same as @code{-E}. 4991 4992@item functrace 4993Same as @code{-T}. 4994 4995@item hashall 4996Same as @code{-h}. 4997 4998@item histexpand 4999Same as @code{-H}. 5000 5001@item history 5002Enable command history, as described in @ref{Bash History Facilities}. 5003This option is on by default in interactive shells. 5004 5005@item ignoreeof 5006An interactive shell will not exit upon reading EOF. 5007 5008@item keyword 5009Same as @code{-k}. 5010 5011@item monitor 5012Same as @code{-m}. 5013 5014@item noclobber 5015Same as @code{-C}. 5016 5017@item noexec 5018Same as @code{-n}. 5019 5020@item noglob 5021Same as @code{-f}. 5022 5023@item nolog 5024Currently ignored. 5025 5026@item notify 5027Same as @code{-b}. 5028 5029@item nounset 5030Same as @code{-u}. 5031 5032@item onecmd 5033Same as @code{-t}. 5034 5035@item physical 5036Same as @code{-P}. 5037 5038@item pipefail 5039If set, the return value of a pipeline is the value of the last 5040(rightmost) command to exit with a non-zero status, or zero if all 5041commands in the pipeline exit successfully. 5042This option is disabled by default. 5043 5044@item posix 5045Change the behavior of Bash where the default operation differs 5046from the @sc{posix} standard to match the standard 5047(@pxref{Bash POSIX Mode}). 5048This is intended to make Bash behave as a strict superset of that 5049standard. 5050 5051@item privileged 5052Same as @code{-p}. 5053 5054@item verbose 5055Same as @code{-v}. 5056 5057@item vi 5058Use a @code{vi}-style line editing interface. 5059This also affects the editing interface used for @code{read -e}. 5060 5061@item xtrace 5062Same as @code{-x}. 5063@end table 5064 5065@item -p 5066Turn on privileged mode. 5067In this mode, the @env{$BASH_ENV} and @env{$ENV} files are not 5068processed, shell functions are not inherited from the environment, 5069and the @env{SHELLOPTS}, @env{BASHOPTS}, @env{CDPATH} and @env{GLOBIGNORE} 5070variables, if they appear in the environment, are ignored. 5071If the shell is started with the effective user (group) id not equal to the 5072real user (group) id, and the @option{-p} option is not supplied, these actions 5073are taken and the effective user id is set to the real user id. 5074If the @option{-p} option is supplied at startup, the effective user id is 5075not reset. 5076Turning this option off causes the effective user 5077and group ids to be set to the real user and group ids. 5078 5079@item -t 5080Exit after reading and executing one command. 5081 5082@item -u 5083Treat unset variables and parameters other than the special parameters 5084@samp{@@} or @samp{*} as an error when performing parameter expansion. 5085An error message will be written to the standard error, and a non-interactive 5086shell will exit. 5087 5088@item -v 5089Print shell input lines as they are read. 5090 5091@item -x 5092Print a trace of simple commands, @code{for} commands, @code{case} 5093commands, @code{select} commands, and arithmetic @code{for} commands 5094and their arguments or associated word lists after they are 5095expanded and before they are executed. The value of the @env{PS4} 5096variable is expanded and the resultant value is printed before 5097the command and its expanded arguments. 5098 5099@item -B 5100The shell will perform brace expansion (@pxref{Brace Expansion}). 5101This option is on by default. 5102 5103@item -C 5104Prevent output redirection using @samp{>}, @samp{>&}, and @samp{<>} 5105from overwriting existing files. 5106 5107@item -E 5108If set, any trap on @code{ERR} is inherited by shell functions, command 5109substitutions, and commands executed in a subshell environment. 5110The @code{ERR} trap is normally not inherited in such cases. 5111 5112@item -H 5113Enable @samp{!} style history substitution (@pxref{History Interaction}). 5114This option is on by default for interactive shells. 5115 5116@item -P 5117If set, do not resolve symbolic links when performing commands such as 5118@code{cd} which change the current directory. The physical directory 5119is used instead. By default, Bash follows 5120the logical chain of directories when performing commands 5121which change the current directory. 5122 5123For example, if @file{/usr/sys} is a symbolic link to @file{/usr/local/sys} 5124then: 5125@example 5126$ cd /usr/sys; echo $PWD 5127/usr/sys 5128$ cd ..; pwd 5129/usr 5130@end example 5131 5132@noindent 5133If @code{set -P} is on, then: 5134@example 5135$ cd /usr/sys; echo $PWD 5136/usr/local/sys 5137$ cd ..; pwd 5138/usr/local 5139@end example 5140 5141@item -T 5142If set, any trap on @code{DEBUG} and @code{RETURN} are inherited by 5143shell functions, command substitutions, and commands executed 5144in a subshell environment. 5145The @code{DEBUG} and @code{RETURN} traps are normally not inherited 5146in such cases. 5147 5148@item -- 5149If no arguments follow this option, then the positional parameters are 5150unset. Otherwise, the positional parameters are set to the 5151@var{arguments}, even if some of them begin with a @samp{-}. 5152 5153@item - 5154Signal the end of options, cause all remaining @var{arguments} 5155to be assigned to the positional parameters. The @option{-x} 5156and @option{-v} options are turned off. 5157If there are no arguments, the positional parameters remain unchanged. 5158@end table 5159 5160Using @samp{+} rather than @samp{-} causes these options to be 5161turned off. The options can also be used upon invocation of the 5162shell. The current set of options may be found in @code{$-}. 5163 5164The remaining N @var{arguments} are positional parameters and are 5165assigned, in order, to @code{$1}, @code{$2}, @dots{} @code{$N}. 5166The special parameter @code{#} is set to N. 5167 5168The return status is always zero unless an invalid option is supplied. 5169@end table 5170 5171@node The Shopt Builtin 5172@subsection The Shopt Builtin 5173 5174This builtin allows you to change additional shell optional behavior. 5175 5176@table @code 5177 5178@item shopt 5179@btindex shopt 5180@example 5181shopt [-pqsu] [-o] [@var{optname} @dots{}] 5182@end example 5183 5184Toggle the values of settings controlling optional shell behavior. 5185The settings can be either those listed below, or, if the 5186@option{-o} option is used, those available with the @option{-o} 5187option to the @code{set} builtin command (@pxref{The Set Builtin}). 5188With no options, or with the @option{-p} option, a list of all settable 5189options is displayed, with an indication of whether or not each is set; 5190if @var{optnames} are supplied, the output is restricted to those options. 5191The @option{-p} option causes output to be displayed in a form that 5192may be reused as input. 5193Other options have the following meanings: 5194 5195@table @code 5196@item -s 5197Enable (set) each @var{optname}. 5198 5199@item -u 5200Disable (unset) each @var{optname}. 5201 5202@item -q 5203Suppresses normal output; the return status 5204indicates whether the @var{optname} is set or unset. 5205If multiple @var{optname} arguments are given with @option{-q}, 5206the return status is zero if all @var{optnames} are enabled; 5207non-zero otherwise. 5208 5209@item -o 5210Restricts the values of 5211@var{optname} to be those defined for the @option{-o} option to the 5212@code{set} builtin (@pxref{The Set Builtin}). 5213@end table 5214 5215If either @option{-s} or @option{-u} 5216is used with no @var{optname} arguments, @code{shopt} shows only 5217those options which are set or unset, respectively. 5218 5219Unless otherwise noted, the @code{shopt} options are disabled (off) 5220by default. 5221 5222The return status when listing options is zero if all @var{optnames} 5223are enabled, non-zero otherwise. When setting or unsetting options, 5224the return status is zero unless an @var{optname} is not a valid shell 5225option. 5226 5227The list of @code{shopt} options is: 5228@table @code 5229 5230@item assoc_expand_once 5231If set, the shell suppresses multiple evaluation of associative array 5232subscripts during arithmetic expression evaluation, while executing 5233builtins that can perform variable assignments, 5234and while executing builtins that perform array dereferencing. 5235 5236@item autocd 5237If set, a command name that is the name of a directory is executed as if 5238it were the argument to the @code{cd} command. 5239This option is only used by interactive shells. 5240 5241@item cdable_vars 5242If this is set, an argument to the @code{cd} builtin command that 5243is not a directory is assumed to be the name of a variable whose 5244value is the directory to change to. 5245 5246@item cdspell 5247If set, minor errors in the spelling of a directory component in a 5248@code{cd} command will be corrected. 5249The errors checked for are transposed characters, 5250a missing character, and a character too many. 5251If a correction is found, the corrected path is printed, 5252and the command proceeds. 5253This option is only used by interactive shells. 5254 5255@item checkhash 5256If this is set, Bash checks that a command found in the hash 5257table exists before trying to execute it. If a hashed command no 5258longer exists, a normal path search is performed. 5259 5260@item checkjobs 5261If set, Bash lists the status of any stopped and running jobs before 5262exiting an interactive shell. If any jobs are running, this causes 5263the exit to be deferred until a second exit is attempted without an 5264intervening command (@pxref{Job Control}). 5265The shell always postpones exiting if any jobs are stopped. 5266 5267@item checkwinsize 5268If set, Bash checks the window size after each external (non-builtin) 5269command and, if necessary, updates the values of 5270@env{LINES} and @env{COLUMNS}. 5271This option is enabled by default. 5272 5273@item cmdhist 5274If set, Bash 5275attempts to save all lines of a multiple-line 5276command in the same history entry. This allows 5277easy re-editing of multi-line commands. 5278This option is enabled by default, but only has an effect if command 5279history is enabled (@pxref{Bash History Facilities}). 5280 5281@item compat31 5282@itemx compat32 5283@itemx compat40 5284@itemx compat41 5285@itemx compat42 5286@itemx compat43 5287@itemx compat44 5288These control aspects of the shell's compatibility mode 5289(@pxref{Shell Compatibility Mode}). 5290 5291@item complete_fullquote 5292If set, Bash 5293quotes all shell metacharacters in filenames and directory names when 5294performing completion. 5295If not set, Bash 5296removes metacharacters such as the dollar sign from the set of 5297characters that will be quoted in completed filenames 5298when these metacharacters appear in shell variable references in words to be 5299completed. 5300This means that dollar signs in variable names that expand to directories 5301will not be quoted; 5302however, any dollar signs appearing in filenames will not be quoted, either. 5303This is active only when bash is using backslashes to quote completed 5304filenames. 5305This variable is set by default, which is the default Bash behavior in 5306versions through 4.2. 5307 5308@item direxpand 5309If set, Bash 5310replaces directory names with the results of word expansion when performing 5311filename completion. This changes the contents of the readline editing 5312buffer. 5313If not set, Bash attempts to preserve what the user typed. 5314 5315@item dirspell 5316If set, Bash 5317attempts spelling correction on directory names during word completion 5318if the directory name initially supplied does not exist. 5319 5320@item dotglob 5321If set, Bash includes filenames beginning with a `.' in 5322the results of filename expansion. 5323The filenames @samp{.} and @samp{..} must always be matched explicitly, 5324even if @code{dotglob} is set. 5325 5326@item execfail 5327If this is set, a non-interactive shell will not exit if 5328it cannot execute the file specified as an argument to the @code{exec} 5329builtin command. An interactive shell does not exit if @code{exec} 5330fails. 5331 5332@item expand_aliases 5333If set, aliases are expanded as described below under Aliases, 5334@ref{Aliases}. 5335This option is enabled by default for interactive shells. 5336 5337@item extdebug 5338If set at shell invocation, 5339or in a shell startup file, 5340arrange to execute the debugger profile 5341before the shell starts, identical to the @option{--debugger} option. 5342If set after invocation, behavior intended for use by debuggers is enabled: 5343 5344@enumerate 5345@item 5346The @option{-F} option to the @code{declare} builtin (@pxref{Bash Builtins}) 5347displays the source file name and line number corresponding to each function 5348name supplied as an argument. 5349 5350@item 5351If the command run by the @code{DEBUG} trap returns a non-zero value, the 5352next command is skipped and not executed. 5353 5354@item 5355If the command run by the @code{DEBUG} trap returns a value of 2, and the 5356shell is executing in a subroutine (a shell function or a shell script 5357executed by the @code{.} or @code{source} builtins), the shell simulates 5358a call to @code{return}. 5359 5360@item 5361@code{BASH_ARGC} and @code{BASH_ARGV} are updated as described in their 5362descriptions (@pxref{Bash Variables}). 5363 5364@item 5365Function tracing is enabled: command substitution, shell functions, and 5366subshells invoked with @code{( @var{command} )} inherit the 5367@code{DEBUG} and @code{RETURN} traps. 5368 5369@item 5370Error tracing is enabled: command substitution, shell functions, and 5371subshells invoked with @code{( @var{command} )} inherit the 5372@code{ERR} trap. 5373@end enumerate 5374 5375@item extglob 5376If set, the extended pattern matching features described above 5377(@pxref{Pattern Matching}) are enabled. 5378 5379@item extquote 5380If set, @code{$'@var{string}'} and @code{$"@var{string}"} quoting is 5381performed within @code{$@{@var{parameter}@}} expansions 5382enclosed in double quotes. This option is enabled by default. 5383 5384@item failglob 5385If set, patterns which fail to match filenames during filename expansion 5386result in an expansion error. 5387 5388@item force_fignore 5389If set, the suffixes specified by the @env{FIGNORE} shell variable 5390cause words to be ignored when performing word completion even if 5391the ignored words are the only possible completions. 5392@xref{Bash Variables}, for a description of @env{FIGNORE}. 5393This option is enabled by default. 5394 5395@item globasciiranges 5396If set, range expressions used in pattern matching bracket expressions 5397(@pxref{Pattern Matching}) 5398behave as if in the traditional C locale when performing 5399comparisons. That is, the current locale's collating sequence 5400is not taken into account, so 5401@samp{b} will not collate between @samp{A} and @samp{B}, 5402and upper-case and lower-case ASCII characters will collate together. 5403 5404@item globstar 5405If set, the pattern @samp{**} used in a filename expansion context will 5406match all files and zero or more directories and subdirectories. 5407If the pattern is followed by a @samp{/}, only directories and 5408subdirectories match. 5409 5410@item gnu_errfmt 5411If set, shell error messages are written in the standard @sc{gnu} error 5412message format. 5413 5414@item histappend 5415If set, the history list is appended to the file named by the value 5416of the @env{HISTFILE} 5417variable when the shell exits, rather than overwriting the file. 5418 5419@item histreedit 5420If set, and Readline 5421is being used, a user is given the opportunity to re-edit a 5422failed history substitution. 5423 5424@item histverify 5425If set, and Readline 5426is being used, the results of history substitution are not immediately 5427passed to the shell parser. Instead, the resulting line is loaded into 5428the Readline editing buffer, allowing further modification. 5429 5430@item hostcomplete 5431If set, and Readline is being used, Bash will attempt to perform 5432hostname completion when a word containing a @samp{@@} is being 5433completed (@pxref{Commands For Completion}). This option is enabled 5434by default. 5435 5436@item huponexit 5437If set, Bash will send @code{SIGHUP} to all jobs when an interactive 5438login shell exits (@pxref{Signals}). 5439 5440@item inherit_errexit 5441If set, command substitution inherits the value of the @code{errexit} option, 5442instead of unsetting it in the subshell environment. 5443This option is enabled when @sc{posix} mode is enabled. 5444 5445@item interactive_comments 5446Allow a word beginning with @samp{#} 5447to cause that word and all remaining characters on that 5448line to be ignored in an interactive shell. 5449This option is enabled by default. 5450 5451@item lastpipe 5452If set, and job control is not active, the shell runs the last command of 5453a pipeline not executed in the background in the current shell environment. 5454 5455@item lithist 5456If enabled, and the @code{cmdhist} 5457option is enabled, multi-line commands are saved to the history with 5458embedded newlines rather than using semicolon separators where possible. 5459 5460@item localvar_inherit 5461If set, local variables inherit the value and attributes of a variable of 5462the same name that exists at a previous scope before any new value is 5463assigned. The @var{nameref} attribute is not inherited. 5464 5465@item localvar_unset 5466If set, calling @code{unset} on local variables in previous function scopes 5467marks them so subsequent lookups find them unset until that function 5468returns. This is identical to the behavior of unsetting local variables 5469at the current function scope. 5470 5471@item login_shell 5472The shell sets this option if it is started as a login shell 5473(@pxref{Invoking Bash}). 5474The value may not be changed. 5475 5476@item mailwarn 5477If set, and a file that Bash is checking for mail has been 5478accessed since the last time it was checked, the message 5479@code{"The mail in @var{mailfile} has been read"} is displayed. 5480 5481@item no_empty_cmd_completion 5482If set, and Readline is being used, Bash will not attempt to search 5483the @env{PATH} for possible completions when completion is attempted 5484on an empty line. 5485 5486@item nocaseglob 5487If set, Bash matches filenames in a case-insensitive fashion when 5488performing filename expansion. 5489 5490@item nocasematch 5491If set, Bash matches patterns in a case-insensitive fashion when 5492performing matching while executing @code{case} or @code{[[} 5493conditional commands, 5494when performing pattern substitution word expansions, 5495or when filtering possible completions as part of programmable completion. 5496 5497@item nullglob 5498If set, Bash allows filename patterns which match no 5499files to expand to a null string, rather than themselves. 5500 5501@item progcomp 5502If set, the programmable completion facilities 5503(@pxref{Programmable Completion}) are enabled. 5504This option is enabled by default. 5505 5506@item progcomp_alias 5507If set, and programmable completion is enabled, Bash treats a command 5508name that doesn't have any completions as a possible alias and attempts 5509alias expansion. If it has an alias, Bash attempts programmable 5510completion using the command word resulting from the expanded alias. 5511 5512@item promptvars 5513If set, prompt strings undergo 5514parameter expansion, command substitution, arithmetic 5515expansion, and quote removal after being expanded 5516as described below (@pxref{Controlling the Prompt}). 5517This option is enabled by default. 5518 5519@item restricted_shell 5520The shell sets this option if it is started in restricted mode 5521(@pxref{The Restricted Shell}). 5522The value may not be changed. 5523This is not reset when the startup files are executed, allowing 5524the startup files to discover whether or not a shell is restricted. 5525 5526@item shift_verbose 5527If this is set, the @code{shift} 5528builtin prints an error message when the shift count exceeds the 5529number of positional parameters. 5530 5531@item sourcepath 5532If set, the @code{source} builtin uses the value of @env{PATH} 5533to find the directory containing the file supplied as an argument. 5534This option is enabled by default. 5535 5536@item xpg_echo 5537If set, the @code{echo} builtin expands backslash-escape sequences 5538by default. 5539 5540@end table 5541@end table 5542 5543@node Special Builtins 5544@section Special Builtins 5545@cindex special builtin 5546 5547For historical reasons, the @sc{posix} standard has classified 5548several builtin commands as @emph{special}. 5549When Bash is executing in @sc{posix} mode, the special builtins 5550differ from other builtin commands in three respects: 5551 5552@enumerate 5553@item 5554Special builtins are found before shell functions during command lookup. 5555 5556@item 5557If a special builtin returns an error status, a non-interactive shell exits. 5558 5559@item 5560Assignment statements preceding the command stay in effect in the shell 5561environment after the command completes. 5562@end enumerate 5563 5564When Bash is not executing in @sc{posix} mode, these builtins behave no 5565differently than the rest of the Bash builtin commands. 5566The Bash @sc{posix} mode is described in @ref{Bash POSIX Mode}. 5567 5568These are the @sc{posix} special builtins: 5569@example 5570@w{break : . continue eval exec exit export readonly return set} 5571@w{shift trap unset} 5572@end example 5573 5574@node Shell Variables 5575@chapter Shell Variables 5576 5577@menu 5578* Bourne Shell Variables:: Variables which Bash uses in the same way 5579 as the Bourne Shell. 5580* Bash Variables:: List of variables that exist in Bash. 5581@end menu 5582 5583This chapter describes the shell variables that Bash uses. 5584Bash automatically assigns default values to a number of variables. 5585 5586@node Bourne Shell Variables 5587@section Bourne Shell Variables 5588 5589Bash uses certain shell variables in the same way as the Bourne shell. 5590In some cases, Bash assigns a default value to the variable. 5591 5592@vtable @code 5593 5594@item CDPATH 5595A colon-separated list of directories used as a search path for 5596the @code{cd} builtin command. 5597 5598@item HOME 5599The current user's home directory; the default for the @code{cd} builtin 5600command. 5601The value of this variable is also used by tilde expansion 5602(@pxref{Tilde Expansion}). 5603 5604@item IFS 5605A list of characters that separate fields; used when the shell splits 5606words as part of expansion. 5607 5608@item MAIL 5609If this parameter is set to a filename or directory name 5610and the @env{MAILPATH} variable 5611is not set, Bash informs the user of the arrival of mail in 5612the specified file or Maildir-format directory. 5613 5614@item MAILPATH 5615A colon-separated list of filenames which the shell periodically checks 5616for new mail. 5617Each list entry can specify the message that is printed when new mail 5618arrives in the mail file by separating the filename from the message with 5619a @samp{?}. 5620When used in the text of the message, @code{$_} expands to the name of 5621the current mail file. 5622 5623@item OPTARG 5624The value of the last option argument processed by the @code{getopts} builtin. 5625 5626@item OPTIND 5627The index of the last option argument processed by the @code{getopts} builtin. 5628 5629@item PATH 5630A colon-separated list of directories in which the shell looks for 5631commands. 5632A zero-length (null) directory name in the value of @code{PATH} indicates the 5633current directory. 5634A null directory name may appear as two adjacent colons, or as an initial 5635or trailing colon. 5636 5637@item PS1 5638The primary prompt string. The default value is @samp{[\u@@\h \w]\$ }. 5639@xref{Controlling the Prompt}, for the complete list of escape 5640sequences that are expanded before @env{PS1} is displayed. 5641 5642@item PS2 5643The secondary prompt string. The default value is @samp{> }. 5644@env{PS2} is expanded in the same way as @env{PS1} before being 5645displayed. 5646 5647@end vtable 5648 5649@node Bash Variables 5650@section Bash Variables 5651 5652These variables are set or used by Bash, but other shells 5653do not normally treat them specially. 5654 5655A few variables used by Bash are described in different chapters: 5656variables for controlling the job control facilities 5657(@pxref{Job Control Variables}). 5658 5659@vtable @code 5660 5661@item _ 5662@vindex $_ 5663($_, an underscore.) 5664At shell startup, set to the pathname used to invoke the 5665shell or shell script being executed as passed in the environment 5666or argument list. 5667Subsequently, expands to the last argument to the previous simple 5668command executed in the foreground, after expansion. 5669Also set to the full pathname used to invoke each command executed 5670and placed in the environment exported to that command. 5671When checking mail, this parameter holds the name of the mail file. 5672 5673@item BASH 5674The full pathname used to execute the current instance of Bash. 5675 5676@item BASHOPTS 5677A colon-separated list of enabled shell options. Each word in 5678the list is a valid argument for the @option{-s} option to the 5679@code{shopt} builtin command (@pxref{The Shopt Builtin}). 5680The options appearing in @env{BASHOPTS} are those reported 5681as @samp{on} by @samp{shopt}. 5682If this variable is in the environment when Bash 5683starts up, each shell option in the list will be enabled before 5684reading any startup files. This variable is readonly. 5685 5686@item BASHPID 5687Expands to the process ID of the current Bash process. 5688This differs from @code{$$} under certain circumstances, such as subshells 5689that do not require Bash to be re-initialized. 5690Assignments to @env{BASHPID} have no effect. 5691If @env{BASHPID} 5692is unset, it loses its special properties, even if it is 5693subsequently reset. 5694 5695@item BASH_ALIASES 5696An associative array variable whose members correspond to the internal 5697list of aliases as maintained by the @code{alias} builtin. 5698(@pxref{Bourne Shell Builtins}). 5699Elements added to this array appear in the alias list; however, 5700unsetting array elements currently does not cause aliases to be removed 5701from the alias list. 5702If @env{BASH_ALIASES} 5703is unset, it loses its special properties, even if it is 5704subsequently reset. 5705 5706@item BASH_ARGC 5707An array variable whose values are the number of parameters in each 5708frame of the current bash execution call stack. The number of 5709parameters to the current subroutine (shell function or script executed 5710with @code{.} or @code{source}) is at the top of the stack. When a 5711subroutine is executed, the number of parameters passed is pushed onto 5712@code{BASH_ARGC}. 5713The shell sets @code{BASH_ARGC} only when in extended debugging mode 5714(see @ref{The Shopt Builtin} 5715for a description of the @code{extdebug} option to the @code{shopt} 5716builtin). 5717Setting @code{extdebug} after the shell has started to execute a script, 5718or referencing this variable when @code{extdebug} is not set, 5719may result in inconsistent values. 5720 5721@item BASH_ARGV 5722An array variable containing all of the parameters in the current bash 5723execution call stack. The final parameter of the last subroutine call 5724is at the top of the stack; the first parameter of the initial call is 5725at the bottom. When a subroutine is executed, the parameters supplied 5726are pushed onto @code{BASH_ARGV}. 5727The shell sets @code{BASH_ARGV} only when in extended debugging mode 5728(see @ref{The Shopt Builtin} 5729for a description of the @code{extdebug} option to the @code{shopt} 5730builtin). 5731Setting @code{extdebug} after the shell has started to execute a script, 5732or referencing this variable when @code{extdebug} is not set, 5733may result in inconsistent values. 5734 5735@item BASH_ARGV0 5736When referenced, this variable expands to the name of the shell or shell 5737script (identical to @code{$0}; @xref{Special Parameters}, 5738for the description of special parameter 0). 5739Assignment to @code{BASH_ARGV0} 5740causes the value assigned to also be assigned to @code{$0}. 5741If @env{BASH_ARGV0} 5742is unset, it loses its special properties, even if it is 5743subsequently reset. 5744 5745@item BASH_CMDS 5746An associative array variable whose members correspond to the internal 5747hash table of commands as maintained by the @code{hash} builtin 5748(@pxref{Bourne Shell Builtins}). 5749Elements added to this array appear in the hash table; however, 5750unsetting array elements currently does not cause command names to be removed 5751from the hash table. 5752If @env{BASH_CMDS} 5753is unset, it loses its special properties, even if it is 5754subsequently reset. 5755 5756@item BASH_COMMAND 5757The command currently being executed or about to be executed, unless the 5758shell is executing a command as the result of a trap, 5759in which case it is the command executing at the time of the trap. 5760If @env{BASH_COMMAND} 5761is unset, it loses its special properties, even if it is 5762subsequently reset. 5763 5764@item BASH_COMPAT 5765The value is used to set the shell's compatibility level. 5766@xref{Shell Compatibility Mode}, for a description of the various 5767compatibility levels and their effects. 5768The value may be a decimal number (e.g., 4.2) or an integer (e.g., 42) 5769corresponding to the desired compatibility level. 5770If @env{BASH_COMPAT} is unset or set to the empty string, the compatibility 5771level is set to the default for the current version. 5772If @env{BASH_COMPAT} is set to a value that is not one of the valid 5773compatibility levels, the shell prints an error message and sets the 5774compatibility level to the default for the current version. 5775The valid values correspond to the compatibility levels 5776described below (@pxref{Shell Compatibility Mode}). 5777For example, 4.2 and 42 are valid values that correspond 5778to the @code{compat42} @code{shopt} option 5779and set the compatibility level to 42. 5780The current version is also a valid value. 5781 5782@item BASH_ENV 5783If this variable is set when Bash is invoked to execute a shell 5784script, its value is expanded and used as the name of a startup file 5785to read before executing the script. @xref{Bash Startup Files}. 5786 5787@item BASH_EXECUTION_STRING 5788The command argument to the @option{-c} invocation option. 5789 5790@item BASH_LINENO 5791An array variable whose members are the line numbers in source files 5792where each corresponding member of @var{FUNCNAME} was invoked. 5793@code{$@{BASH_LINENO[$i]@}} is the line number in the source file 5794(@code{$@{BASH_SOURCE[$i+1]@}}) where 5795@code{$@{FUNCNAME[$i]@}} was called (or @code{$@{BASH_LINENO[$i-1]@}} if 5796referenced within another shell function). 5797Use @code{LINENO} to obtain the current line number. 5798 5799@item BASH_LOADABLES_PATH 5800A colon-separated list of directories in which the shell looks for 5801dynamically loadable builtins specified by the 5802@code{enable} command. 5803 5804@item BASH_REMATCH 5805An array variable whose members are assigned by the @samp{=~} binary 5806operator to the @code{[[} conditional command 5807(@pxref{Conditional Constructs}). 5808The element with index 0 is the portion of the string 5809matching the entire regular expression. 5810The element with index @var{n} is the portion of the 5811string matching the @var{n}th parenthesized subexpression. 5812 5813@item BASH_SOURCE 5814An array variable whose members are the source filenames where the 5815corresponding shell function names in the @code{FUNCNAME} array 5816variable are defined. 5817The shell function @code{$@{FUNCNAME[$i]@}} is defined in the file 5818@code{$@{BASH_SOURCE[$i]@}} and called from @code{$@{BASH_SOURCE[$i+1]@}} 5819 5820@item BASH_SUBSHELL 5821Incremented by one within each subshell or subshell environment when 5822the shell begins executing in that environment. 5823The initial value is 0. 5824If @env{BASH_SUBSHELL} 5825is unset, it loses its special properties, even if it is 5826subsequently reset. 5827 5828@item BASH_VERSINFO 5829A readonly array variable (@pxref{Arrays}) 5830whose members hold version information for this instance of Bash. 5831The values assigned to the array members are as follows: 5832 5833@table @code 5834 5835@item BASH_VERSINFO[0] 5836The major version number (the @var{release}). 5837 5838@item BASH_VERSINFO[1] 5839The minor version number (the @var{version}). 5840 5841@item BASH_VERSINFO[2] 5842The patch level. 5843 5844@item BASH_VERSINFO[3] 5845The build version. 5846 5847@item BASH_VERSINFO[4] 5848The release status (e.g., @var{beta1}). 5849 5850@item BASH_VERSINFO[5] 5851The value of @env{MACHTYPE}. 5852@end table 5853 5854@item BASH_VERSION 5855The version number of the current instance of Bash. 5856 5857@item BASH_XTRACEFD 5858If set to an integer corresponding to a valid file descriptor, Bash 5859will write the trace output generated when @samp{set -x} 5860is enabled to that file descriptor. 5861This allows tracing output to be separated from diagnostic and error 5862messages. 5863The file descriptor is closed when @code{BASH_XTRACEFD} is unset or assigned 5864a new value. 5865Unsetting @code{BASH_XTRACEFD} or assigning it the empty string causes the 5866trace output to be sent to the standard error. 5867Note that setting @code{BASH_XTRACEFD} to 2 (the standard error file 5868descriptor) and then unsetting it will result in the standard error 5869being closed. 5870 5871@item CHILD_MAX 5872Set the number of exited child status values for the shell to remember. 5873Bash will not allow this value to be decreased below a @sc{posix}-mandated 5874minimum, and there is a maximum value (currently 8192) that this may 5875not exceed. 5876The minimum value is system-dependent. 5877 5878@item COLUMNS 5879Used by the @code{select} command to determine the terminal width 5880when printing selection lists. 5881Automatically set if the @code{checkwinsize} option is enabled 5882(@pxref{The Shopt Builtin}), or in an interactive shell upon receipt of a 5883@code{SIGWINCH}. 5884 5885@item COMP_CWORD 5886An index into @env{$@{COMP_WORDS@}} of the word containing the current 5887cursor position. 5888This variable is available only in shell functions invoked by the 5889programmable completion facilities (@pxref{Programmable Completion}). 5890 5891@item COMP_LINE 5892The current command line. 5893This variable is available only in shell functions and external 5894commands invoked by the 5895programmable completion facilities (@pxref{Programmable Completion}). 5896 5897@item COMP_POINT 5898The index of the current cursor position relative to the beginning of 5899the current command. 5900If the current cursor position is at the end of the current command, 5901the value of this variable is equal to @code{$@{#COMP_LINE@}}. 5902This variable is available only in shell functions and external 5903commands invoked by the 5904programmable completion facilities (@pxref{Programmable Completion}). 5905 5906@item COMP_TYPE 5907Set to an integer value corresponding to the type of completion attempted 5908that caused a completion function to be called: 5909@var{TAB}, for normal completion, 5910@samp{?}, for listing completions after successive tabs, 5911@samp{!}, for listing alternatives on partial word completion, 5912@samp{@@}, to list completions if the word is not unmodified, 5913or 5914@samp{%}, for menu completion. 5915This variable is available only in shell functions and external 5916commands invoked by the 5917programmable completion facilities (@pxref{Programmable Completion}). 5918 5919@item COMP_KEY 5920The key (or final key of a key sequence) used to invoke the current 5921completion function. 5922 5923@item COMP_WORDBREAKS 5924The set of characters that the Readline library treats as word 5925separators when performing word completion. 5926If @env{COMP_WORDBREAKS} 5927is unset, it loses its special properties, 5928even if it is subsequently reset. 5929 5930@item COMP_WORDS 5931An array variable consisting of the individual 5932words in the current command line. 5933The line is split into words as Readline would split it, using 5934@code{COMP_WORDBREAKS} as described above. 5935This variable is available only in shell functions invoked by the 5936programmable completion facilities (@pxref{Programmable Completion}). 5937 5938@item COMPREPLY 5939An array variable from which Bash reads the possible completions 5940generated by a shell function invoked by the programmable completion 5941facility (@pxref{Programmable Completion}). 5942Each array element contains one possible completion. 5943 5944@item COPROC 5945An array variable created to hold the file descriptors 5946for output from and input to an unnamed coprocess (@pxref{Coprocesses}). 5947 5948@item DIRSTACK 5949An array variable containing the current contents of the directory stack. 5950Directories appear in the stack in the order they are displayed by the 5951@code{dirs} builtin. 5952Assigning to members of this array variable may be used to modify 5953directories already in the stack, but the @code{pushd} and @code{popd} 5954builtins must be used to add and remove directories. 5955Assignment to this variable will not change the current directory. 5956If @env{DIRSTACK} 5957is unset, it loses its special properties, even if 5958it is subsequently reset. 5959 5960@item EMACS 5961If Bash finds this variable in the environment when the shell 5962starts with value @samp{t}, it assumes that the shell is running in an 5963Emacs shell buffer and disables line editing. 5964 5965@item ENV 5966Expanded and executed similarlty to @code{BASH_ENV} 5967(@pxref{Bash Startup Files}) 5968when an interactive shell is invoked in 5969@sc{posix} Mode (@pxref{Bash POSIX Mode}). 5970 5971@item EPOCHREALTIME 5972Each time this parameter is referenced, it expands to the number of seconds 5973since the Unix Epoch as a floating point value with micro-second granularity 5974(see the documentation for the C library function @var{time} for the 5975definition of Epoch). 5976Assignments to @env{EPOCHREALTIME} are ignored. 5977If @env{EPOCHREALTIME} 5978is unset, it loses its special properties, even if 5979it is subsequently reset. 5980 5981@item EPOCHSECONDS 5982Each time this parameter is referenced, it expands to the number of seconds 5983since the Unix Epoch (see the documentation for the C library function 5984@var{time} for the definition of Epoch). 5985Assignments to @env{EPOCHSECONDS} are ignored. 5986If @env{EPOCHSECONDS} 5987is unset, it loses its special properties, even if 5988it is subsequently reset. 5989 5990@item EUID 5991The numeric effective user id of the current user. This variable 5992is readonly. 5993 5994@item EXECIGNORE 5995A colon-separated list of shell patterns (@pxref{Pattern Matching}) 5996defining the list of filenames to be ignored by command search using 5997@code{PATH}. 5998Files whose full pathnames match one of these patterns are not considered 5999executable files for the purposes of completion and command execution 6000via @code{PATH} lookup. 6001This does not affect the behavior of the @code{[}, @code{test}, and @code{[[} 6002commands. 6003Full pathnames in the command hash table are not subject to @code{EXECIGNORE}. 6004Use this variable to ignore shared library files that have the executable 6005bit set, but are not executable files. 6006The pattern matching honors the setting of the @code{extglob} shell 6007option. 6008 6009@item FCEDIT 6010The editor used as a default by the @option{-e} option to the @code{fc} 6011builtin command. 6012 6013@item FIGNORE 6014A colon-separated list of suffixes to ignore when performing 6015filename completion. 6016A filename whose suffix matches one of the entries in 6017@env{FIGNORE} 6018is excluded from the list of matched filenames. A sample 6019value is @samp{.o:~} 6020 6021@item FUNCNAME 6022An array variable containing the names of all shell functions 6023currently in the execution call stack. 6024The element with index 0 is the name of any currently-executing 6025shell function. 6026The bottom-most element (the one with the highest index) 6027is @code{"main"}. 6028This variable exists only when a shell function is executing. 6029Assignments to @env{FUNCNAME} have no effect. 6030If @env{FUNCNAME} 6031is unset, it loses its special properties, even if 6032it is subsequently reset. 6033 6034This variable can be used with @code{BASH_LINENO} and @code{BASH_SOURCE}. 6035Each element of @code{FUNCNAME} has corresponding elements in 6036@code{BASH_LINENO} and @code{BASH_SOURCE} to describe the call stack. 6037For instance, @code{$@{FUNCNAME[$i]@}} was called from the file 6038@code{$@{BASH_SOURCE[$i+1]@}} at line number @code{$@{BASH_LINENO[$i]@}}. 6039The @code{caller} builtin displays the current call stack using this 6040information. 6041 6042@item FUNCNEST 6043If set to a numeric value greater than 0, defines a maximum function 6044nesting level. Function invocations that exceed this nesting level 6045will cause the current command to abort. 6046 6047@item GLOBIGNORE 6048A colon-separated list of patterns defining the set of file names to 6049be ignored by filename expansion. 6050If a file name matched by a filename expansion pattern also matches one 6051of the patterns in @env{GLOBIGNORE}, it is removed from the list 6052of matches. 6053The pattern matching honors the setting of the @code{extglob} shell 6054option. 6055 6056@item GROUPS 6057An array variable containing the list of groups of which the current 6058user is a member. 6059Assignments to @env{GROUPS} have no effect. 6060If @env{GROUPS} 6061is unset, it loses its special properties, even if it is 6062subsequently reset. 6063 6064@item histchars 6065Up to three characters which control history expansion, quick 6066substitution, and tokenization (@pxref{History Interaction}). 6067The first character is the 6068@var{history expansion} character, that is, the character which signifies the 6069start of a history expansion, normally @samp{!}. The second character is the 6070character which signifies `quick substitution' when seen as the first 6071character on a line, normally @samp{^}. The optional third character is the 6072character which indicates that the remainder of the line is a comment when 6073found as the first character of a word, usually @samp{#}. The history 6074comment character causes history substitution to be skipped for the 6075remaining words on the line. It does not necessarily cause the shell 6076parser to treat the rest of the line as a comment. 6077 6078@item HISTCMD 6079The history number, or index in the history list, of the current 6080command. 6081Assignments to @env{HISTCMD} are ignored. 6082If @env{HISTCMD} 6083is unset, it loses its special properties, 6084even if it is subsequently reset. 6085 6086@item HISTCONTROL 6087A colon-separated list of values controlling how commands are saved on 6088the history list. 6089If the list of values includes @samp{ignorespace}, lines which begin 6090with a space character are not saved in the history list. 6091A value of @samp{ignoredups} causes lines which match the previous 6092history entry to not be saved. 6093A value of @samp{ignoreboth} is shorthand for 6094@samp{ignorespace} and @samp{ignoredups}. 6095A value of @samp{erasedups} causes all previous lines matching the 6096current line to be removed from the history list before that line 6097is saved. 6098Any value not in the above list is ignored. 6099If @env{HISTCONTROL} is unset, or does not include a valid value, 6100all lines read by the shell parser are saved on the history list, 6101subject to the value of @env{HISTIGNORE}. 6102The second and subsequent lines of a multi-line compound command are 6103not tested, and are added to the history regardless of the value of 6104@env{HISTCONTROL}. 6105 6106@item HISTFILE 6107The name of the file to which the command history is saved. The 6108default value is @file{~/.bash_history}. 6109 6110@item HISTFILESIZE 6111The maximum number of lines contained in the history file. 6112When this variable is assigned a value, the history file is truncated, 6113if necessary, to contain no more than that number of lines 6114by removing the oldest entries. 6115The history file is also truncated to this size after 6116writing it when a shell exits. 6117If the value is 0, the history file is truncated to zero size. 6118Non-numeric values and numeric values less than zero inhibit truncation. 6119The shell sets the default value to the value of @env{HISTSIZE} 6120after reading any startup files. 6121 6122@item HISTIGNORE 6123A colon-separated list of patterns used to decide which command 6124lines should be saved on the history list. Each pattern is 6125anchored at the beginning of the line and must match the complete 6126line (no implicit @samp{*} is appended). Each pattern is tested 6127against the line after the checks specified by @env{HISTCONTROL} 6128are applied. In addition to the normal shell pattern matching 6129characters, @samp{&} matches the previous history line. @samp{&} 6130may be escaped using a backslash; the backslash is removed 6131before attempting a match. 6132The second and subsequent lines of a multi-line compound command are 6133not tested, and are added to the history regardless of the value of 6134@env{HISTIGNORE}. 6135The pattern matching honors the setting of the @code{extglob} shell 6136option. 6137 6138@env{HISTIGNORE} subsumes the function of @env{HISTCONTROL}. A 6139pattern of @samp{&} is identical to @code{ignoredups}, and a 6140pattern of @samp{[ ]*} is identical to @code{ignorespace}. 6141Combining these two patterns, separating them with a colon, 6142provides the functionality of @code{ignoreboth}. 6143 6144@item HISTSIZE 6145The maximum number of commands to remember on the history list. 6146If the value is 0, commands are not saved in the history list. 6147Numeric values less than zero result in every command being saved 6148on the history list (there is no limit). 6149The shell sets the default value to 500 after reading any startup files. 6150 6151@item HISTTIMEFORMAT 6152If this variable is set and not null, its value is used as a format string 6153for @var{strftime} to print the time stamp associated with each history 6154entry displayed by the @code{history} builtin. 6155If this variable is set, time stamps are written to the history file so 6156they may be preserved across shell sessions. 6157This uses the history comment character to distinguish timestamps from 6158other history lines. 6159 6160@item HOSTFILE 6161Contains the name of a file in the same format as @file{/etc/hosts} that 6162should be read when the shell needs to complete a hostname. 6163The list of possible hostname completions may be changed while the shell 6164is running; 6165the next time hostname completion is attempted after the 6166value is changed, Bash adds the contents of the new file to the 6167existing list. 6168If @env{HOSTFILE} is set, but has no value, or does not name a readable file, 6169Bash attempts to read 6170@file{/etc/hosts} to obtain the list of possible hostname completions. 6171When @env{HOSTFILE} is unset, the hostname list is cleared. 6172 6173@item HOSTNAME 6174The name of the current host. 6175 6176@item HOSTTYPE 6177A string describing the machine Bash is running on. 6178 6179@item IGNOREEOF 6180Controls the action of the shell on receipt of an @code{EOF} character 6181as the sole input. If set, the value denotes the number 6182of consecutive @code{EOF} characters that can be read as the 6183first character on an input line 6184before the shell will exit. If the variable exists but does not 6185have a numeric value, or has no value, then the default is 10. 6186If the variable does not exist, then @code{EOF} signifies the end of 6187input to the shell. This is only in effect for interactive shells. 6188 6189@item INPUTRC 6190The name of the Readline initialization file, overriding the default 6191of @file{~/.inputrc}. 6192 6193@item INSIDE_EMACS 6194If Bash finds this variable in the environment when the shell 6195starts, it assumes that the shell is running in an Emacs shell buffer 6196and may disable line editing depending on the value of @env{TERM}. 6197 6198@item LANG 6199Used to determine the locale category for any category not specifically 6200selected with a variable starting with @code{LC_}. 6201 6202@item LC_ALL 6203This variable overrides the value of @env{LANG} and any other 6204@code{LC_} variable specifying a locale category. 6205 6206@item LC_COLLATE 6207This variable determines the collation order used when sorting the 6208results of filename expansion, and 6209determines the behavior of range expressions, equivalence classes, 6210and collating sequences within filename expansion and pattern matching 6211(@pxref{Filename Expansion}). 6212 6213@item LC_CTYPE 6214This variable determines the interpretation of characters and the 6215behavior of character classes within filename expansion and pattern 6216matching (@pxref{Filename Expansion}). 6217 6218@item LC_MESSAGES 6219This variable determines the locale used to translate double-quoted 6220strings preceded by a @samp{$} (@pxref{Locale Translation}). 6221 6222@item LC_NUMERIC 6223This variable determines the locale category used for number formatting. 6224 6225@item LC_TIME 6226This variable determines the locale category used for data and time 6227formatting. 6228 6229@item LINENO 6230The line number in the script or shell function currently executing. 6231If @env{LINENO} 6232is unset, it loses its special properties, even if it is 6233subsequently reset. 6234 6235@item LINES 6236Used by the @code{select} command to determine the column length 6237for printing selection lists. 6238Automatically set if the @code{checkwinsize} option is enabled 6239(@pxref{The Shopt Builtin}), or in an interactive shell upon receipt of a 6240@code{SIGWINCH}. 6241 6242@item MACHTYPE 6243A string that fully describes the system type on which Bash 6244is executing, in the standard @sc{gnu} @var{cpu-company-system} format. 6245 6246@item MAILCHECK 6247How often (in seconds) that the shell should check for mail in the 6248files specified in the @env{MAILPATH} or @env{MAIL} variables. 6249The default is 60 seconds. When it is time to check 6250for mail, the shell does so before displaying the primary prompt. 6251If this variable is unset, or set to a value that is not a number 6252greater than or equal to zero, the shell disables mail checking. 6253 6254@item MAPFILE 6255An array variable created to hold the text read by the 6256@code{mapfile} builtin when no variable name is supplied. 6257 6258@item OLDPWD 6259The previous working directory as set by the @code{cd} builtin. 6260 6261@item OPTERR 6262If set to the value 1, Bash displays error messages 6263generated by the @code{getopts} builtin command. 6264 6265@item OSTYPE 6266A string describing the operating system Bash is running on. 6267 6268@item PIPESTATUS 6269An array variable (@pxref{Arrays}) 6270containing a list of exit status values from the processes 6271in the most-recently-executed foreground pipeline (which may 6272contain only a single command). 6273 6274@item POSIXLY_CORRECT 6275If this variable is in the environment when Bash starts, the shell 6276enters @sc{posix} mode (@pxref{Bash POSIX Mode}) before reading the 6277startup files, as if the @option{--posix} invocation option had been supplied. 6278If it is set while the shell is running, Bash enables @sc{posix} mode, 6279as if the command 6280@example 6281@code{set -o posix} 6282@end example 6283@noindent 6284had been executed. 6285When the shell enters @sc{posix} mode, it sets this variable if it was 6286not already set. 6287 6288@item PPID 6289The process @sc{id} of the shell's parent process. This variable 6290is readonly. 6291 6292@item PROMPT_COMMAND 6293If this variable is set, and is an array, 6294the value of each set element is interpreted as a command to execute 6295before printing the primary prompt (@env{$PS1}). 6296If this is set but not an array variable, 6297its value is used as a command to execute instead. 6298 6299@item PROMPT_DIRTRIM 6300If set to a number greater than zero, the value is used as the number of 6301trailing directory components to retain when expanding the @code{\w} and 6302@code{\W} prompt string escapes (@pxref{Controlling the Prompt}). 6303Characters removed are replaced with an ellipsis. 6304 6305@item PS0 6306The value of this parameter is expanded like @env{PS1} 6307and displayed by interactive shells after reading a command 6308and before the command is executed. 6309 6310@item PS3 6311The value of this variable is used as the prompt for the 6312@code{select} command. If this variable is not set, the 6313@code{select} command prompts with @samp{#? } 6314 6315@item PS4 6316The value of this parameter is expanded like @var{PS1} 6317and the expanded value is the prompt printed before the command line 6318is echoed when the @option{-x} option is set (@pxref{The Set Builtin}). 6319The first character of the expanded value is replicated multiple times, 6320as necessary, to indicate multiple levels of indirection. 6321The default is @samp{+ }. 6322 6323@item PWD 6324The current working directory as set by the @code{cd} builtin. 6325 6326@item RANDOM 6327Each time this parameter is referenced, it expands to a random integer 6328between 0 and 32767. Assigning a value to this 6329variable seeds the random number generator. 6330If @env{RANDOM} 6331is unset, it loses its special properties, even if it is 6332subsequently reset. 6333 6334@item READLINE_LINE 6335The contents of the Readline line buffer, for use 6336with @samp{bind -x} (@pxref{Bash Builtins}). 6337 6338@item READLINE_MARK 6339The position of the @var{mark} (saved insertion point) in the 6340Readline line buffer, for use 6341with @samp{bind -x} (@pxref{Bash Builtins}). 6342The characters between the insertion point and the mark are often 6343called the @var{region}. 6344 6345@item READLINE_POINT 6346The position of the insertion point in the Readline line buffer, for use 6347with @samp{bind -x} (@pxref{Bash Builtins}). 6348 6349@item REPLY 6350The default variable for the @code{read} builtin. 6351 6352@item SECONDS 6353This variable expands to the number of seconds since the 6354shell was started. Assignment to this variable resets 6355the count to the value assigned, and the expanded value 6356becomes the value assigned plus the number of seconds 6357since the assignment. 6358The number of seconds at shell invocation and the current time is always 6359determined by querying the system clock. 6360If @env{SECONDS} 6361is unset, it loses its special properties, 6362even if it is subsequently reset. 6363 6364@item SHELL 6365This environment variable expands to the full pathname to the shell. 6366If it is not set when the shell starts, 6367Bash assigns to it the full pathname of the current user's login shell. 6368 6369@item SHELLOPTS 6370A colon-separated list of enabled shell options. Each word in 6371the list is a valid argument for the @option{-o} option to the 6372@code{set} builtin command (@pxref{The Set Builtin}). 6373The options appearing in @env{SHELLOPTS} are those reported 6374as @samp{on} by @samp{set -o}. 6375If this variable is in the environment when Bash 6376starts up, each shell option in the list will be enabled before 6377reading any startup files. This variable is readonly. 6378 6379@item SHLVL 6380Incremented by one each time a new instance of Bash is started. This is 6381intended to be a count of how deeply your Bash shells are nested. 6382 6383@item SRANDOM 6384This variable expands to a 32-bit pseudo-random number each time it is 6385referenced. The random number generator is not linear on systems that 6386support @file{/dev/urandom} or @code{arc4random}, so each returned number 6387has no relationship to the numbers preceding it. 6388The random number generator cannot be seeded, so assignments to this 6389variable have no effect. 6390If @env{SRANDOM} 6391is unset, it loses its special properties, 6392even if it is subsequently reset. 6393 6394@item TIMEFORMAT 6395The value of this parameter is used as a format string specifying 6396how the timing information for pipelines prefixed with the @code{time} 6397reserved word should be displayed. 6398The @samp{%} character introduces an 6399escape sequence that is expanded to a time value or other 6400information. 6401The escape sequences and their meanings are as 6402follows; the braces denote optional portions. 6403 6404@table @code 6405 6406@item %% 6407A literal @samp{%}. 6408 6409@item %[@var{p}][l]R 6410The elapsed time in seconds. 6411 6412@item %[@var{p}][l]U 6413The number of CPU seconds spent in user mode. 6414 6415@item %[@var{p}][l]S 6416The number of CPU seconds spent in system mode. 6417 6418@item %P 6419The CPU percentage, computed as (%U + %S) / %R. 6420@end table 6421 6422The optional @var{p} is a digit specifying the precision, the number of 6423fractional digits after a decimal point. 6424A value of 0 causes no decimal point or fraction to be output. 6425At most three places after the decimal point may be specified; values 6426of @var{p} greater than 3 are changed to 3. 6427If @var{p} is not specified, the value 3 is used. 6428 6429The optional @code{l} specifies a longer format, including minutes, of 6430the form @var{MM}m@var{SS}.@var{FF}s. 6431The value of @var{p} determines whether or not the fraction is included. 6432 6433If this variable is not set, Bash acts as if it had the value 6434@example 6435@code{$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'} 6436@end example 6437If the value is null, no timing information is displayed. 6438A trailing newline is added when the format string is displayed. 6439 6440@item TMOUT 6441If set to a value greater than zero, @code{TMOUT} is treated as the 6442default timeout for the @code{read} builtin (@pxref{Bash Builtins}). 6443The @code{select} command (@pxref{Conditional Constructs}) terminates 6444if input does not arrive after @code{TMOUT} seconds when input is coming 6445from a terminal. 6446 6447In an interactive shell, the value is interpreted as 6448the number of seconds to wait for a line of input after issuing 6449the primary prompt. 6450Bash 6451terminates after waiting for that number of seconds if a complete 6452line of input does not arrive. 6453 6454@item TMPDIR 6455If set, Bash uses its value as the name of a directory in which 6456Bash creates temporary files for the shell's use. 6457 6458@item UID 6459The numeric real user id of the current user. This variable is readonly. 6460 6461@end vtable 6462 6463@node Bash Features 6464@chapter Bash Features 6465 6466This chapter describes features unique to Bash. 6467 6468@menu 6469* Invoking Bash:: Command line options that you can give 6470 to Bash. 6471* Bash Startup Files:: When and how Bash executes scripts. 6472* Interactive Shells:: What an interactive shell is. 6473* Bash Conditional Expressions:: Primitives used in composing expressions for 6474 the @code{test} builtin. 6475* Shell Arithmetic:: Arithmetic on shell variables. 6476* Aliases:: Substituting one command for another. 6477* Arrays:: Array Variables. 6478* The Directory Stack:: History of visited directories. 6479* Controlling the Prompt:: Customizing the various prompt strings. 6480* The Restricted Shell:: A more controlled mode of shell execution. 6481* Bash POSIX Mode:: Making Bash behave more closely to what 6482 the POSIX standard specifies. 6483* Shell Compatibility Mode:: How Bash supports behavior that was present 6484 in earlier versions and has changed. 6485@end menu 6486 6487@node Invoking Bash 6488@section Invoking Bash 6489 6490@example 6491bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o @var{option}] 6492 [-O @var{shopt_option}] [@var{argument} @dots{}] 6493bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o @var{option}] 6494 [-O @var{shopt_option}] -c @var{string} [@var{argument} @dots{}] 6495bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o @var{option}] 6496 [-O @var{shopt_option}] [@var{argument} @dots{}] 6497@end example 6498 6499All of the single-character options used with the @code{set} builtin 6500(@pxref{The Set Builtin}) can be used as options when the shell is invoked. 6501In addition, there are several multi-character 6502options that you can use. These options must appear on the command 6503line before the single-character options to be recognized. 6504 6505@table @code 6506@item --debugger 6507Arrange for the debugger profile to be executed before the shell 6508starts. Turns on extended debugging mode (see @ref{The Shopt Builtin} 6509for a description of the @code{extdebug} option to the @code{shopt} 6510builtin). 6511 6512@item --dump-po-strings 6513A list of all double-quoted strings preceded by @samp{$} 6514is printed on the standard output 6515in the @sc{gnu} @code{gettext} PO (portable object) file format. 6516Equivalent to @option{-D} except for the output format. 6517 6518@item --dump-strings 6519Equivalent to @option{-D}. 6520 6521@item --help 6522Display a usage message on standard output and exit successfully. 6523 6524@item --init-file @var{filename} 6525@itemx --rcfile @var{filename} 6526Execute commands from @var{filename} (instead of @file{~/.bashrc}) 6527in an interactive shell. 6528 6529@item --login 6530Equivalent to @option{-l}. 6531 6532@item --noediting 6533Do not use the @sc{gnu} Readline library (@pxref{Command Line Editing}) 6534to read command lines when the shell is interactive. 6535 6536@item --noprofile 6537Don't load the system-wide startup file @file{/etc/profile} 6538or any of the personal initialization files 6539@file{~/.bash_profile}, @file{~/.bash_login}, or @file{~/.profile} 6540when Bash is invoked as a login shell. 6541 6542@item --norc 6543Don't read the @file{~/.bashrc} initialization file in an 6544interactive shell. This is on by default if the shell is 6545invoked as @code{sh}. 6546 6547@item --posix 6548Change the behavior of Bash where the default operation differs 6549from the @sc{posix} standard to match the standard. This 6550is intended to make Bash behave as a strict superset of that 6551standard. @xref{Bash POSIX Mode}, for a description of the Bash 6552@sc{posix} mode. 6553 6554@item --restricted 6555Make the shell a restricted shell (@pxref{The Restricted Shell}). 6556 6557@item --verbose 6558Equivalent to @option{-v}. Print shell input lines as they're read. 6559 6560@item --version 6561Show version information for this instance of 6562Bash on the standard output and exit successfully. 6563@end table 6564 6565There are several single-character options that may be supplied at 6566invocation which are not available with the @code{set} builtin. 6567 6568@table @code 6569@item -c 6570Read and execute commands from the first non-option argument 6571@var{command_string}, then exit. 6572If there are arguments after the @var{command_string}, 6573the first argument is assigned to @code{$0} 6574and any remaining arguments are assigned to the positional parameters. 6575The assignment to @code{$0} sets the name of the shell, which is used 6576in warning and error messages. 6577 6578@item -i 6579Force the shell to run interactively. Interactive shells are 6580described in @ref{Interactive Shells}. 6581 6582@item -l 6583Make this shell act as if it had been directly invoked by login. 6584When the shell is interactive, this is equivalent to starting a 6585login shell with @samp{exec -l bash}. 6586When the shell is not interactive, the login shell startup files will 6587be executed. 6588@samp{exec bash -l} or @samp{exec bash --login} 6589will replace the current shell with a Bash login shell. 6590@xref{Bash Startup Files}, for a description of the special behavior 6591of a login shell. 6592 6593@item -r 6594Make the shell a restricted shell (@pxref{The Restricted Shell}). 6595 6596@item -s 6597If this option is present, or if no arguments remain after option 6598processing, then commands are read from the standard input. 6599This option allows the positional parameters to be set 6600when invoking an interactive shell or when reading input 6601through a pipe. 6602 6603@item -D 6604A list of all double-quoted strings preceded by @samp{$} 6605is printed on the standard output. 6606These are the strings that 6607are subject to language translation when the current locale 6608is not @code{C} or @code{POSIX} (@pxref{Locale Translation}). 6609This implies the @option{-n} option; no commands will be executed. 6610 6611@item [-+]O [@var{shopt_option}] 6612@var{shopt_option} is one of the shell options accepted by the 6613@code{shopt} builtin (@pxref{The Shopt Builtin}). 6614If @var{shopt_option} is present, @option{-O} sets the value of that option; 6615@option{+O} unsets it. 6616If @var{shopt_option} is not supplied, the names and values of the shell 6617options accepted by @code{shopt} are printed on the standard output. 6618If the invocation option is @option{+O}, the output is displayed in a format 6619that may be reused as input. 6620 6621@item -- 6622A @code{--} signals the end of options and disables further option 6623processing. 6624Any arguments after the @code{--} are treated as filenames and arguments. 6625@end table 6626 6627@cindex login shell 6628A @emph{login} shell is one whose first character of argument zero is 6629@samp{-}, or one invoked with the @option{--login} option. 6630 6631@cindex interactive shell 6632An @emph{interactive} shell is one started without non-option arguments, 6633unless @option{-s} is specified, 6634without specifying the @option{-c} option, and whose input and output are both 6635connected to terminals (as determined by @code{isatty(3)}), or one 6636started with the @option{-i} option. @xref{Interactive Shells}, for more 6637information. 6638 6639If arguments remain after option processing, and neither the 6640@option{-c} nor the @option{-s} 6641option has been supplied, the first argument is assumed to 6642be the name of a file containing shell commands (@pxref{Shell Scripts}). 6643When Bash is invoked in this fashion, @code{$0} 6644is set to the name of the file, and the positional parameters 6645are set to the remaining arguments. 6646Bash reads and executes commands from this file, then exits. 6647Bash's exit status is the exit status of the last command executed 6648in the script. If no commands are executed, the exit status is 0. 6649 6650@node Bash Startup Files 6651@section Bash Startup Files 6652@cindex startup files 6653 6654This section describes how Bash executes its startup files. 6655If any of the files exist but cannot be read, Bash reports an error. 6656Tildes are expanded in filenames as described above under 6657Tilde Expansion (@pxref{Tilde Expansion}). 6658 6659Interactive shells are described in @ref{Interactive Shells}. 6660 6661@subsubheading Invoked as an interactive login shell, or with @option{--login} 6662 6663When Bash is invoked as an interactive login shell, or as a 6664non-interactive shell with the @option{--login} option, it first reads and 6665executes commands from the file @file{/etc/profile}, if that file exists. 6666After reading that file, it looks for @file{~/.bash_profile}, 6667@file{~/.bash_login}, and @file{~/.profile}, in that order, and reads 6668and executes commands from the first one that exists and is readable. 6669The @option{--noprofile} option may be used when the shell is started to 6670inhibit this behavior. 6671 6672When an interactive login shell exits, 6673or a non-interactive login shell executes the @code{exit} builtin command, 6674Bash reads and executes commands from 6675the file @file{~/.bash_logout}, if it exists. 6676 6677@subsubheading Invoked as an interactive non-login shell 6678 6679When an interactive shell that is not a login shell is started, Bash 6680reads and executes commands from @file{~/.bashrc}, if that file exists. 6681This may be inhibited by using the @option{--norc} option. 6682The @option{--rcfile @var{file}} option will force Bash to read and 6683execute commands from @var{file} instead of @file{~/.bashrc}. 6684 6685So, typically, your @file{~/.bash_profile} contains the line 6686@example 6687@code{if [ -f ~/.bashrc ]; then . ~/.bashrc; fi} 6688@end example 6689@noindent 6690after (or before) any login-specific initializations. 6691 6692@subsubheading Invoked non-interactively 6693 6694When Bash is started non-interactively, to run a shell script, 6695for example, it looks for the variable @env{BASH_ENV} in the environment, 6696expands its value if it appears there, and uses the expanded value as 6697the name of a file to read and execute. Bash behaves as if the 6698following command were executed: 6699@example 6700@code{if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi} 6701@end example 6702@noindent 6703but the value of the @env{PATH} variable is not used to search for the 6704filename. 6705 6706As noted above, if a non-interactive shell is invoked with the 6707@option{--login} option, Bash attempts to read and execute commands from the 6708login shell startup files. 6709 6710@subsubheading Invoked with name @code{sh} 6711 6712If Bash is invoked with the name @code{sh}, it tries to mimic the 6713startup behavior of historical versions of @code{sh} as closely as 6714possible, while conforming to the @sc{posix} standard as well. 6715 6716When invoked as an interactive login shell, or as a non-interactive 6717shell with the @option{--login} option, it first attempts to read 6718and execute commands from @file{/etc/profile} and @file{~/.profile}, in 6719that order. 6720The @option{--noprofile} option may be used to inhibit this behavior. 6721When invoked as an interactive shell with the name @code{sh}, Bash 6722looks for the variable @env{ENV}, expands its value if it is defined, 6723and uses the expanded value as the name of a file to read and execute. 6724Since a shell invoked as @code{sh} does not attempt to read and execute 6725commands from any other startup files, the @option{--rcfile} option has 6726no effect. 6727A non-interactive shell invoked with the name @code{sh} does not attempt 6728to read any other startup files. 6729 6730When invoked as @code{sh}, Bash enters @sc{posix} mode after 6731the startup files are read. 6732 6733@subsubheading Invoked in @sc{posix} mode 6734 6735When Bash is started in @sc{posix} mode, as with the 6736@option{--posix} command line option, it follows the @sc{posix} standard 6737for startup files. 6738In this mode, interactive shells expand the @env{ENV} variable 6739and commands are read and executed from the file whose name is the 6740expanded value. 6741No other startup files are read. 6742 6743@subsubheading Invoked by remote shell daemon 6744 6745Bash attempts to determine when it is being run with its standard input 6746connected to a network connection, as when executed by the remote shell 6747daemon, usually @code{rshd}, or the secure shell daemon @code{sshd}. 6748If Bash determines it is being run in 6749this fashion, it reads and executes commands from @file{~/.bashrc}, if that 6750file exists and is readable. 6751It will not do this if invoked as @code{sh}. 6752The @option{--norc} option may be used to inhibit this behavior, and the 6753@option{--rcfile} option may be used to force another file to be read, but 6754neither @code{rshd} nor @code{sshd} generally invoke the shell with those 6755options or allow them to be specified. 6756 6757@subsubheading Invoked with unequal effective and real @sc{uid/gid}s 6758 6759If Bash is started with the effective user (group) id not equal to the 6760real user (group) id, and the @option{-p} option is not supplied, no startup 6761files are read, shell functions are not inherited from the environment, 6762the @env{SHELLOPTS}, @env{BASHOPTS}, @env{CDPATH}, and @env{GLOBIGNORE} 6763variables, if they appear in the environment, are ignored, and the effective 6764user id is set to the real user id. 6765If the @option{-p} option is supplied at invocation, the startup behavior is 6766the same, but the effective user id is not reset. 6767 6768@node Interactive Shells 6769@section Interactive Shells 6770@cindex interactive shell 6771@cindex shell, interactive 6772 6773@menu 6774* What is an Interactive Shell?:: What determines whether a shell is Interactive. 6775* Is this Shell Interactive?:: How to tell if a shell is interactive. 6776* Interactive Shell Behavior:: What changes in a interactive shell? 6777@end menu 6778 6779@node What is an Interactive Shell? 6780@subsection What is an Interactive Shell? 6781 6782An interactive shell 6783is one started without non-option arguments, unless @option{-s} is 6784specified, without specifying the @option{-c} option, and 6785whose input and error output are both 6786connected to terminals (as determined by @code{isatty(3)}), 6787or one started with the @option{-i} option. 6788 6789An interactive shell generally reads from and writes to a user's 6790terminal. 6791 6792The @option{-s} invocation option may be used to set the positional parameters 6793when an interactive shell is started. 6794 6795@node Is this Shell Interactive? 6796@subsection Is this Shell Interactive? 6797 6798To determine within a startup script whether or not Bash is 6799running interactively, 6800test the value of the @samp{-} special parameter. 6801It contains @code{i} when the shell is interactive. For example: 6802 6803@example 6804case "$-" in 6805*i*) echo This shell is interactive ;; 6806*) echo This shell is not interactive ;; 6807esac 6808@end example 6809 6810Alternatively, startup scripts may examine the variable 6811@env{PS1}; it is unset in non-interactive shells, and set in 6812interactive shells. Thus: 6813 6814@example 6815if [ -z "$PS1" ]; then 6816 echo This shell is not interactive 6817else 6818 echo This shell is interactive 6819fi 6820@end example 6821 6822@node Interactive Shell Behavior 6823@subsection Interactive Shell Behavior 6824 6825When the shell is running interactively, it changes its behavior in 6826several ways. 6827 6828@enumerate 6829@item 6830Startup files are read and executed as described in @ref{Bash Startup Files}. 6831 6832@item 6833Job Control (@pxref{Job Control}) is enabled by default. When job 6834control is in effect, Bash ignores the keyboard-generated job control 6835signals @code{SIGTTIN}, @code{SIGTTOU}, and @code{SIGTSTP}. 6836 6837@item 6838Bash expands and displays @env{PS1} before reading the first line 6839of a command, and expands and displays @env{PS2} before reading the 6840second and subsequent lines of a multi-line command. 6841Bash expands and displays @env{PS0} after it reads a command but before 6842executing it. 6843See @ref{Controlling the Prompt}, for a complete list of prompt 6844string escape sequences. 6845 6846@item 6847Bash executes the values of the set elements of the @env{PROMPT_COMMANDS} 6848array variable as commands before printing the primary prompt, @env{$PS1} 6849(@pxref{Bash Variables}). 6850 6851@item 6852Readline (@pxref{Command Line Editing}) is used to read commands from 6853the user's terminal. 6854 6855@item 6856Bash inspects the value of the @code{ignoreeof} option to @code{set -o} 6857instead of exiting immediately when it receives an @code{EOF} on its 6858standard input when reading a command (@pxref{The Set Builtin}). 6859 6860@item 6861Command history (@pxref{Bash History Facilities}) 6862and history expansion (@pxref{History Interaction}) 6863are enabled by default. 6864Bash will save the command history to the file named by @env{$HISTFILE} 6865when a shell with history enabled exits. 6866 6867@item 6868Alias expansion (@pxref{Aliases}) is performed by default. 6869 6870@item 6871In the absence of any traps, Bash ignores @code{SIGTERM} 6872(@pxref{Signals}). 6873 6874@item 6875In the absence of any traps, @code{SIGINT} is caught and handled 6876(@pxref{Signals}). 6877@code{SIGINT} will interrupt some shell builtins. 6878 6879@item 6880An interactive login shell sends a @code{SIGHUP} to all jobs on exit 6881if the @code{huponexit} shell option has been enabled (@pxref{Signals}). 6882 6883@item 6884The @option{-n} invocation option is ignored, and @samp{set -n} has 6885no effect (@pxref{The Set Builtin}). 6886 6887@item 6888Bash will check for mail periodically, depending on the values of the 6889@env{MAIL}, @env{MAILPATH}, and @env{MAILCHECK} shell variables 6890(@pxref{Bash Variables}). 6891 6892@item 6893Expansion errors due to references to unbound shell variables after 6894@samp{set -u} has been enabled will not cause the shell to exit 6895(@pxref{The Set Builtin}). 6896 6897@item 6898The shell will not exit on expansion errors caused by @var{var} being unset 6899or null in @code{$@{@var{var}:?@var{word}@}} expansions 6900(@pxref{Shell Parameter Expansion}). 6901 6902@item 6903Redirection errors encountered by shell builtins will not cause the 6904shell to exit. 6905 6906@item 6907When running in @sc{posix} mode, a special builtin returning an error 6908status will not cause the shell to exit (@pxref{Bash POSIX Mode}). 6909 6910@item 6911A failed @code{exec} will not cause the shell to exit 6912(@pxref{Bourne Shell Builtins}). 6913 6914@item 6915Parser syntax errors will not cause the shell to exit. 6916 6917@item 6918Simple spelling correction for directory arguments to the @code{cd} 6919builtin is enabled by default (see the description of the @code{cdspell} 6920option to the @code{shopt} builtin in @ref{The Shopt Builtin}). 6921 6922@item 6923The shell will check the value of the @env{TMOUT} variable and exit 6924if a command is not read within the specified number of seconds after 6925printing @env{$PS1} (@pxref{Bash Variables}). 6926 6927@end enumerate 6928 6929@node Bash Conditional Expressions 6930@section Bash Conditional Expressions 6931@cindex expressions, conditional 6932 6933Conditional expressions are used by the @code{[[} compound command 6934and the @code{test} and @code{[} builtin commands. The @code{test} 6935and @code{[} commands determine their behavior based on the number 6936of arguments; see the descriptions of those commands for any other 6937command-specific actions. 6938 6939Expressions may be unary or binary, 6940and are formed from the following primaries. 6941Unary expressions are often used to examine the status of a file. 6942There are string operators and numeric comparison operators as well. 6943Bash handles several filenames specially when they are used in 6944expressions. 6945If the operating system on which Bash is running provides these 6946special files, Bash will use them; otherwise it will emulate them 6947internally with this behavior: 6948If the @var{file} argument to one of the primaries is of the form 6949@file{/dev/fd/@var{N}}, then file descriptor @var{N} is checked. 6950If the @var{file} argument to one of the primaries is one of 6951@file{/dev/stdin}, @file{/dev/stdout}, or @file{/dev/stderr}, file 6952descriptor 0, 1, or 2, respectively, is checked. 6953 6954When used with @code{[[}, the @samp{<} and @samp{>} operators sort 6955lexicographically using the current locale. 6956The @code{test} command uses ASCII ordering. 6957 6958Unless otherwise specified, primaries that operate on files follow symbolic 6959links and operate on the target of the link, rather than the link itself. 6960 6961@table @code 6962@item -a @var{file} 6963True if @var{file} exists. 6964 6965@item -b @var{file} 6966True if @var{file} exists and is a block special file. 6967 6968@item -c @var{file} 6969True if @var{file} exists and is a character special file. 6970 6971@item -d @var{file} 6972True if @var{file} exists and is a directory. 6973 6974@item -e @var{file} 6975True if @var{file} exists. 6976 6977@item -f @var{file} 6978True if @var{file} exists and is a regular file. 6979 6980@item -g @var{file} 6981True if @var{file} exists and its set-group-id bit is set. 6982 6983@item -h @var{file} 6984True if @var{file} exists and is a symbolic link. 6985 6986@item -k @var{file} 6987True if @var{file} exists and its "sticky" bit is set. 6988 6989@item -p @var{file} 6990True if @var{file} exists and is a named pipe (FIFO). 6991 6992@item -r @var{file} 6993True if @var{file} exists and is readable. 6994 6995@item -s @var{file} 6996True if @var{file} exists and has a size greater than zero. 6997 6998@item -t @var{fd} 6999True if file descriptor @var{fd} is open and refers to a terminal. 7000 7001@item -u @var{file} 7002True if @var{file} exists and its set-user-id bit is set. 7003 7004@item -w @var{file} 7005True if @var{file} exists and is writable. 7006 7007@item -x @var{file} 7008True if @var{file} exists and is executable. 7009 7010@item -G @var{file} 7011True if @var{file} exists and is owned by the effective group id. 7012 7013@item -L @var{file} 7014True if @var{file} exists and is a symbolic link. 7015 7016@item -N @var{file} 7017True if @var{file} exists and has been modified since it was last read. 7018 7019@item -O @var{file} 7020True if @var{file} exists and is owned by the effective user id. 7021 7022@item -S @var{file} 7023True if @var{file} exists and is a socket. 7024 7025@item @var{file1} -ef @var{file2} 7026True if @var{file1} and @var{file2} refer to the same device and 7027inode numbers. 7028 7029@item @var{file1} -nt @var{file2} 7030True if @var{file1} is newer (according to modification date) 7031than @var{file2}, or if @var{file1} exists and @var{file2} does not. 7032 7033@item @var{file1} -ot @var{file2} 7034True if @var{file1} is older than @var{file2}, 7035or if @var{file2} exists and @var{file1} does not. 7036 7037@item -o @var{optname} 7038True if the shell option @var{optname} is enabled. 7039The list of options appears in the description of the @option{-o} 7040option to the @code{set} builtin (@pxref{The Set Builtin}). 7041 7042@item -v @var{varname} 7043True if the shell variable @var{varname} is set (has been assigned a value). 7044 7045@item -R @var{varname} 7046True if the shell variable @var{varname} is set and is a name reference. 7047 7048@item -z @var{string} 7049True if the length of @var{string} is zero. 7050 7051@item -n @var{string} 7052@itemx @var{string} 7053True if the length of @var{string} is non-zero. 7054 7055@item @var{string1} == @var{string2} 7056@itemx @var{string1} = @var{string2} 7057True if the strings are equal. 7058When used with the @code{[[} command, this performs pattern matching as 7059described above (@pxref{Conditional Constructs}). 7060 7061@samp{=} should be used with the @code{test} command for @sc{posix} conformance. 7062 7063@item @var{string1} != @var{string2} 7064True if the strings are not equal. 7065 7066@item @var{string1} < @var{string2} 7067True if @var{string1} sorts before @var{string2} lexicographically. 7068 7069@item @var{string1} > @var{string2} 7070True if @var{string1} sorts after @var{string2} lexicographically. 7071 7072@item @var{arg1} OP @var{arg2} 7073@code{OP} is one of 7074@samp{-eq}, @samp{-ne}, @samp{-lt}, @samp{-le}, @samp{-gt}, or @samp{-ge}. 7075These arithmetic binary operators return true if @var{arg1} 7076is equal to, not equal to, less than, less than or equal to, 7077greater than, or greater than or equal to @var{arg2}, 7078respectively. @var{Arg1} and @var{arg2} 7079may be positive or negative integers. 7080When used with the @code{[[} command, @var{Arg1} and @var{Arg2} 7081are evaluated as arithmetic expressions (@pxref{Shell Arithmetic}). 7082@end table 7083 7084@node Shell Arithmetic 7085@section Shell Arithmetic 7086@cindex arithmetic, shell 7087@cindex shell arithmetic 7088@cindex expressions, arithmetic 7089@cindex evaluation, arithmetic 7090@cindex arithmetic evaluation 7091 7092The shell allows arithmetic expressions to be evaluated, as one of 7093the shell expansions or by using the @code{((} compound command, the 7094@code{let} builtin, or the @option{-i} option to the @code{declare} builtin. 7095 7096Evaluation is done in fixed-width integers with no check for overflow, 7097though division by 0 is trapped and flagged as an error. 7098The operators and their precedence, associativity, and values 7099are the same as in the C language. 7100The following list of operators is grouped into levels of 7101equal-precedence operators. 7102The levels are listed in order of decreasing precedence. 7103 7104@table @code 7105 7106@item @var{id}++ @var{id}-- 7107variable post-increment and post-decrement 7108 7109@item ++@var{id} --@var{id} 7110variable pre-increment and pre-decrement 7111 7112@item - + 7113unary minus and plus 7114 7115@item ! ~ 7116logical and bitwise negation 7117 7118@item ** 7119exponentiation 7120 7121@item * / % 7122multiplication, division, remainder 7123 7124@item + - 7125addition, subtraction 7126 7127@item << >> 7128left and right bitwise shifts 7129 7130@item <= >= < > 7131comparison 7132 7133@item == != 7134equality and inequality 7135 7136@item & 7137bitwise AND 7138 7139@item ^ 7140bitwise exclusive OR 7141 7142@item | 7143bitwise OR 7144 7145@item && 7146logical AND 7147 7148@item || 7149logical OR 7150 7151@item expr ? expr : expr 7152conditional operator 7153 7154@item = *= /= %= += -= <<= >>= &= ^= |= 7155assignment 7156 7157@item expr1 , expr2 7158comma 7159@end table 7160 7161Shell variables are allowed as operands; parameter expansion is 7162performed before the expression is evaluated. 7163Within an expression, shell variables may also be referenced by name 7164without using the parameter expansion syntax. 7165A shell variable that is null or unset evaluates to 0 when referenced 7166by name without using the parameter expansion syntax. 7167The value of a variable is evaluated as an arithmetic expression 7168when it is referenced, or when a variable which has been given the 7169@var{integer} attribute using @samp{declare -i} is assigned a value. 7170A null value evaluates to 0. 7171A shell variable need not have its @var{integer} attribute turned on 7172to be used in an expression. 7173 7174Integer constants follow the C language definition, without suffixes or 7175character constants. 7176Constants with a leading 0 are interpreted as octal numbers. 7177A leading @samp{0x} or @samp{0X} denotes hexadecimal. Otherwise, 7178numbers take the form [@var{base}@code{#}]@var{n}, where the optional @var{base} 7179is a decimal number between 2 and 64 representing the arithmetic 7180base, and @var{n} is a number in that base. 7181If @var{base}@code{#} is omitted, then base 10 is used. 7182When specifying @var{n}, 7183if a non-digit is required, 7184the digits greater than 9 are represented by the lowercase letters, 7185the uppercase letters, @samp{@@}, and @samp{_}, in that order. 7186If @var{base} is less than or equal to 36, lowercase and uppercase 7187letters may be used interchangeably to represent numbers between 10 7188and 35. 7189 7190Operators are evaluated in order of precedence. Sub-expressions in 7191parentheses are evaluated first and may override the precedence 7192rules above. 7193 7194@node Aliases 7195@section Aliases 7196@cindex alias expansion 7197 7198@var{Aliases} allow a string to be substituted for a word when it is used 7199as the first word of a simple command. 7200The shell maintains a list of aliases that may be set and unset with 7201the @code{alias} and @code{unalias} builtin commands. 7202 7203The first word of each simple command, if unquoted, is checked to see 7204if it has an alias. 7205If so, that word is replaced by the text of the alias. 7206The characters @samp{/}, @samp{$}, @samp{`}, @samp{=} and any of the 7207shell metacharacters or quoting characters listed above may not appear 7208in an alias name. 7209The replacement text may contain any valid 7210shell input, including shell metacharacters. 7211The first word of the replacement text is tested for 7212aliases, but a word that is identical to an alias being expanded 7213is not expanded a second time. 7214This means that one may alias @code{ls} to @code{"ls -F"}, 7215for instance, and Bash does not try to recursively expand the 7216replacement text. 7217If the last character of the alias value is a 7218@var{blank}, then the next command word following the 7219alias is also checked for alias expansion. 7220 7221Aliases are created and listed with the @code{alias} 7222command, and removed with the @code{unalias} command. 7223 7224There is no mechanism for using arguments in the replacement text, 7225as in @code{csh}. 7226If arguments are needed, a shell function should be used 7227(@pxref{Shell Functions}). 7228 7229Aliases are not expanded when the shell is not interactive, 7230unless the @code{expand_aliases} shell option is set using 7231@code{shopt} (@pxref{The Shopt Builtin}). 7232 7233The rules concerning the definition and use of aliases are 7234somewhat confusing. Bash 7235always reads at least one complete line of input, 7236and all lines that make up a compound command, 7237before executing any of the commands on that line or the compound command. 7238Aliases are expanded when a 7239command is read, not when it is executed. Therefore, an 7240alias definition appearing on the same line as another 7241command does not take effect until the next line of input is read. 7242The commands following the alias definition 7243on that line are not affected by the new alias. 7244This behavior is also an issue when functions are executed. 7245Aliases are expanded when a function definition is read, 7246not when the function is executed, because a function definition 7247is itself a command. As a consequence, aliases 7248defined in a function are not available until after that 7249function is executed. To be safe, always put 7250alias definitions on a separate line, and do not use @code{alias} 7251in compound commands. 7252 7253For almost every purpose, shell functions are preferred over aliases. 7254 7255@node Arrays 7256@section Arrays 7257@cindex arrays 7258 7259Bash provides one-dimensional indexed and associative array variables. 7260Any variable may be used as an indexed array; 7261the @code{declare} builtin will explicitly declare an array. 7262There is no maximum 7263limit on the size of an array, nor any requirement that members 7264be indexed or assigned contiguously. 7265Indexed arrays are referenced using integers (including arithmetic 7266expressions (@pxref{Shell Arithmetic})) and are zero-based; 7267associative arrays use arbitrary strings. 7268Unless otherwise noted, indexed array indices must be non-negative integers. 7269 7270An indexed array is created automatically if any variable is assigned to 7271using the syntax 7272@example 7273@var{name}[@var{subscript}]=@var{value} 7274@end example 7275 7276@noindent 7277The @var{subscript} 7278is treated as an arithmetic expression that must evaluate to a number. 7279To explicitly declare an array, use 7280@example 7281declare -a @var{name} 7282@end example 7283@noindent 7284The syntax 7285@example 7286declare -a @var{name}[@var{subscript}] 7287@end example 7288@noindent 7289is also accepted; the @var{subscript} is ignored. 7290 7291@noindent 7292Associative arrays are created using 7293@example 7294declare -A @var{name} 7295@end example 7296 7297Attributes may be 7298specified for an array variable using the @code{declare} and 7299@code{readonly} builtins. Each attribute applies to all members of 7300an array. 7301 7302Arrays are assigned to using compound assignments of the form 7303@example 7304@var{name}=(@var{value1} @var{value2} @dots{} ) 7305@end example 7306@noindent 7307where each 7308@var{value} may be of the form @code{[@var{subscript}]=}@var{string}. 7309Indexed array assignments do not require anything but @var{string}. 7310When assigning to indexed arrays, if 7311the optional subscript is supplied, that index is assigned to; 7312otherwise the index of the element assigned is the last index assigned 7313to by the statement plus one. Indexing starts at zero. 7314 7315Each @var{value} in the list undergoes all the shell expansions 7316described above (@pxref{Shell Expansions}). 7317 7318When assigning to an associative array, the words in a compound assignment 7319may be either assignment statements, for which the subscript is required, 7320or a list of words that is interpreted as a sequence of alternating keys 7321and values: 7322@var{name}=(@var{key1} @var{value1} @var{key2} @var{value2} @dots{} ). 7323These are treated identically to 7324@var{name}=( [@var{key1}]=@var{value1} [@var{key2}]=@var{value2} @dots{} ). 7325The first word in the list determines how the remaining words 7326are interpreted; all assignments in a list must be of the same type. 7327When using key/value pairs, the keys may not be missing or empty; 7328a final missing value is treated like the empty string. 7329 7330This syntax is also accepted by the @code{declare} 7331builtin. Individual array elements may be assigned to using the 7332@code{@var{name}[@var{subscript}]=@var{value}} syntax introduced above. 7333 7334When assigning to an indexed array, if @var{name} 7335is subscripted by a negative number, that number is 7336interpreted as relative to one greater than the maximum index of 7337@var{name}, so negative indices count back from the end of the 7338array, and an index of -1 references the last element. 7339 7340Any element of an array may be referenced using 7341@code{$@{@var{name}[@var{subscript}]@}}. 7342The braces are required to avoid 7343conflicts with the shell's filename expansion operators. If the 7344@var{subscript} is @samp{@@} or @samp{*}, the word expands to all members 7345of the array @var{name}. These subscripts differ only when the word 7346appears within double quotes. 7347If the word is double-quoted, 7348@code{$@{@var{name}[*]@}} expands to a single word with 7349the value of each array member separated by the first character of the 7350@env{IFS} variable, and @code{$@{@var{name}[@@]@}} expands each element of 7351@var{name} to a separate word. When there are no array members, 7352@code{$@{@var{name}[@@]@}} expands to nothing. 7353If the double-quoted expansion occurs within a word, the expansion of 7354the first parameter is joined with the beginning part of the original 7355word, and the expansion of the last parameter is joined with the last 7356part of the original word. 7357This is analogous to the 7358expansion of the special parameters @samp{@@} and @samp{*}. 7359@code{$@{#@var{name}[@var{subscript}]@}} expands to the length of 7360@code{$@{@var{name}[@var{subscript}]@}}. 7361If @var{subscript} is @samp{@@} or 7362@samp{*}, the expansion is the number of elements in the array. 7363If the @var{subscript} 7364used to reference an element of an indexed array 7365evaluates to a number less than zero, it is 7366interpreted as relative to one greater than the maximum index of the array, 7367so negative indices count back from the end of the array, 7368and an index of -1 refers to the last element. 7369 7370Referencing an array variable without a subscript is equivalent to 7371referencing with a subscript of 0. 7372Any reference to a variable using a valid subscript is legal, and 7373@code{bash} will create an array if necessary. 7374 7375An array variable is considered set if a subscript has been assigned a 7376value. The null string is a valid value. 7377 7378It is possible to obtain the keys (indices) of an array as well as the values. 7379$@{!@var{name}[@@]@} and $@{!@var{name}[*]@} expand to the indices 7380assigned in array variable @var{name}. 7381The treatment when in double quotes is similar to the expansion of the 7382special parameters @samp{@@} and @samp{*} within double quotes. 7383 7384The @code{unset} builtin is used to destroy arrays. 7385@code{unset @var{name}[@var{subscript}]} 7386destroys the array element at index @var{subscript}. 7387Negative subscripts to indexed arrays are interpreted as described above. 7388Unsetting the last element of an array variable does not unset the variable. 7389@code{unset @var{name}}, where @var{name} is an array, removes the 7390entire array. A subscript of @samp{*} or @samp{@@} also removes the 7391entire array. 7392 7393When using a variable name with a subscript as an argument to a command, 7394such as with @code{unset}, without using the word expansion syntax 7395described above, the argument is subject to the shell's filename expansion. 7396If filename expansion is not desired, the argument should be quoted. 7397 7398The @code{declare}, @code{local}, and @code{readonly} 7399builtins each accept a @option{-a} option to specify an indexed 7400array and a @option{-A} option to specify an associative array. 7401If both options are supplied, @option{-A} takes precedence. 7402The @code{read} builtin accepts a @option{-a} 7403option to assign a list of words read from the standard input 7404to an array, and can read values from the standard input into 7405individual array elements. The @code{set} and @code{declare} 7406builtins display array values in a way that allows them to be 7407reused as input. 7408 7409@node The Directory Stack 7410@section The Directory Stack 7411@cindex directory stack 7412 7413@menu 7414* Directory Stack Builtins:: Bash builtin commands to manipulate 7415 the directory stack. 7416@end menu 7417 7418The directory stack is a list of recently-visited directories. The 7419@code{pushd} builtin adds directories to the stack as it changes 7420the current directory, and the @code{popd} builtin removes specified 7421directories from the stack and changes the current directory to 7422the directory removed. The @code{dirs} builtin displays the contents 7423of the directory stack. The current directory is always the "top" 7424of the directory stack. 7425 7426The contents of the directory stack are also visible 7427as the value of the @env{DIRSTACK} shell variable. 7428 7429@node Directory Stack Builtins 7430@subsection Directory Stack Builtins 7431 7432@table @code 7433 7434@item dirs 7435@btindex dirs 7436@example 7437dirs [-clpv] [+@var{N} | -@var{N}] 7438@end example 7439 7440Display the list of currently remembered directories. Directories 7441are added to the list with the @code{pushd} command; the 7442@code{popd} command removes directories from the list. 7443The current directory is always the first directory in the stack. 7444 7445@table @code 7446@item -c 7447Clears the directory stack by deleting all of the elements. 7448@item -l 7449Produces a listing using full pathnames; 7450the default listing format uses a tilde to denote the home directory. 7451@item -p 7452Causes @code{dirs} to print the directory stack with one entry per 7453line. 7454@item -v 7455Causes @code{dirs} to print the directory stack with one entry per 7456line, prefixing each entry with its index in the stack. 7457@item +@var{N} 7458Displays the @var{N}th directory (counting from the left of the 7459list printed by @code{dirs} when invoked without options), starting 7460with zero. 7461@item -@var{N} 7462Displays the @var{N}th directory (counting from the right of the 7463list printed by @code{dirs} when invoked without options), starting 7464with zero. 7465@end table 7466 7467@item popd 7468@btindex popd 7469@example 7470popd [-n] [+@var{N} | -@var{N}] 7471@end example 7472 7473When no arguments are given, @code{popd} 7474removes the top directory from the stack and 7475performs a @code{cd} to the new top directory. 7476The elements are numbered from 0 starting at the first directory 7477listed with @code{dirs}; that is, @code{popd} is equivalent to @code{popd +0}. 7478 7479@table @code 7480@item -n 7481Suppresses the normal change of directory when removing directories 7482from the stack, so that only the stack is manipulated. 7483@item +@var{N} 7484Removes the @var{N}th directory (counting from the left of the 7485list printed by @code{dirs}), starting with zero. 7486@item -@var{N} 7487Removes the @var{N}th directory (counting from the right of the 7488list printed by @code{dirs}), starting with zero. 7489@end table 7490 7491@btindex pushd 7492@item pushd 7493@example 7494pushd [-n] [@var{+N} | @var{-N} | @var{dir}] 7495@end example 7496 7497Save the current directory on the top of the directory stack 7498and then @code{cd} to @var{dir}. 7499With no arguments, @code{pushd} exchanges the top two directories 7500and makes the new top the current directory. 7501 7502@table @code 7503@item -n 7504Suppresses the normal change of directory when rotating or 7505adding directories to the stack, so that only the stack is manipulated. 7506@item +@var{N} 7507Brings the @var{N}th directory (counting from the left of the 7508list printed by @code{dirs}, starting with zero) to the top of 7509the list by rotating the stack. 7510@item -@var{N} 7511Brings the @var{N}th directory (counting from the right of the 7512list printed by @code{dirs}, starting with zero) to the top of 7513the list by rotating the stack. 7514@item @var{dir} 7515Makes @var{dir} be the top of the stack, making 7516it the new current directory as if it had been supplied as an argument 7517to the @code{cd} builtin. 7518@end table 7519@end table 7520 7521@node Controlling the Prompt 7522@section Controlling the Prompt 7523@cindex prompting 7524 7525Bash examines the value of the array variable @env{PROMPT_COMMANDS} just before 7526printing each primary prompt. 7527If any elements in @env{PROMPT_COMMANDS} are set and non-null, Bash 7528executes each value, in numeric order, 7529just as if it had been typed on the command line. 7530 7531In addition, the following table describes the special characters which 7532can appear in the prompt variables @env{PS0}, @env{PS1}, @env{PS2}, and 7533@env{PS4}: 7534 7535@table @code 7536@item \a 7537A bell character. 7538@item \d 7539The date, in "Weekday Month Date" format (e.g., "Tue May 26"). 7540@item \D@{@var{format}@} 7541The @var{format} is passed to @code{strftime}(3) and the result is inserted 7542into the prompt string; an empty @var{format} results in a locale-specific 7543time representation. The braces are required. 7544@item \e 7545An escape character. 7546@item \h 7547The hostname, up to the first `.'. 7548@item \H 7549The hostname. 7550@item \j 7551The number of jobs currently managed by the shell. 7552@item \l 7553The basename of the shell's terminal device name. 7554@item \n 7555A newline. 7556@item \r 7557A carriage return. 7558@item \s 7559The name of the shell, the basename of @code{$0} (the portion 7560following the final slash). 7561@item \t 7562The time, in 24-hour HH:MM:SS format. 7563@item \T 7564The time, in 12-hour HH:MM:SS format. 7565@item \@@ 7566The time, in 12-hour am/pm format. 7567@item \A 7568The time, in 24-hour HH:MM format. 7569@item \u 7570The username of the current user. 7571@item \v 7572The version of Bash (e.g., 2.00) 7573@item \V 7574The release of Bash, version + patchlevel (e.g., 2.00.0) 7575@item \w 7576The current working directory, with @env{$HOME} abbreviated with a tilde 7577(uses the @env{$PROMPT_DIRTRIM} variable). 7578@item \W 7579The basename of @env{$PWD}, with @env{$HOME} abbreviated with a tilde. 7580@item \! 7581The history number of this command. 7582@item \# 7583The command number of this command. 7584@item \$ 7585If the effective uid is 0, @code{#}, otherwise @code{$}. 7586@item \@var{nnn} 7587The character whose ASCII code is the octal value @var{nnn}. 7588@item \\ 7589A backslash. 7590@item \[ 7591Begin a sequence of non-printing characters. This could be used to 7592embed a terminal control sequence into the prompt. 7593@item \] 7594End a sequence of non-printing characters. 7595@end table 7596 7597The command number and the history number are usually different: 7598the history number of a command is its position in the history 7599list, which may include commands restored from the history file 7600(@pxref{Bash History Facilities}), while the command number is 7601the position in the sequence of commands executed during the current 7602shell session. 7603 7604After the string is decoded, it is expanded via 7605parameter expansion, command substitution, arithmetic 7606expansion, and quote removal, subject to the value of the 7607@code{promptvars} shell option (@pxref{The Shopt Builtin}). 7608This can have unwanted side effects if escaped portions of the string 7609appear within command substitution or contain characters special to 7610word expansion. 7611 7612@node The Restricted Shell 7613@section The Restricted Shell 7614@cindex restricted shell 7615 7616If Bash is started with the name @code{rbash}, or the 7617@option{--restricted} 7618or 7619@option{-r} 7620option is supplied at invocation, the shell becomes restricted. 7621A restricted shell is used to 7622set up an environment more controlled than the standard shell. 7623A restricted shell behaves identically to @code{bash} 7624with the exception that the following are disallowed or not performed: 7625 7626@itemize @bullet 7627@item 7628Changing directories with the @code{cd} builtin. 7629@item 7630Setting or unsetting the values of the @env{SHELL}, @env{PATH}, 7631@env{HISTFILE}, 7632@env{ENV}, or @env{BASH_ENV} variables. 7633@item 7634Specifying command names containing slashes. 7635@item 7636Specifying a filename containing a slash as an argument to the @code{.} 7637builtin command. 7638@item 7639Specifying a filename containing a slash as an argument to the @code{history} 7640builtin command. 7641@item 7642Specifying a filename containing a slash as an argument to the @option{-p} 7643option to the @code{hash} builtin command. 7644@item 7645Importing function definitions from the shell environment at startup. 7646@item 7647Parsing the value of @env{SHELLOPTS} from the shell environment at startup. 7648@item 7649Redirecting output using the @samp{>}, @samp{>|}, @samp{<>}, @samp{>&}, 7650@samp{&>}, and @samp{>>} redirection operators. 7651@item 7652Using the @code{exec} builtin to replace the shell with another command. 7653@item 7654Adding or deleting builtin commands with the 7655@option{-f} and @option{-d} options to the @code{enable} builtin. 7656@item 7657Using the @code{enable} builtin command to enable disabled shell builtins. 7658@item 7659Specifying the @option{-p} option to the @code{command} builtin. 7660@item 7661Turning off restricted mode with @samp{set +r} or @samp{set +o restricted}. 7662@end itemize 7663 7664These restrictions are enforced after any startup files are read. 7665 7666When a command that is found to be a shell script is executed 7667(@pxref{Shell Scripts}), @code{rbash} turns off any restrictions in 7668the shell spawned to execute the script. 7669 7670The restricted shell mode is only one component of a useful restricted 7671environment. It should be accompanied by setting @env{PATH} to a value 7672that allows execution of only a few verified commands (commands that 7673allow shell escapes are particularly vulnerable), leaving the user 7674in a non-writable directory other than his home directory after login, 7675not allowing the restricted shell to execute shell scripts, and cleaning 7676the environment of variables that cause some commands to modify their 7677behavior (e.g., @env{VISUAL} or @env{PAGER}). 7678 7679Modern systems provide more secure ways to implement a restricted environment, 7680such as @code{jails}, @code{zones}, or @code{containers}. 7681 7682 7683@node Bash POSIX Mode 7684@section Bash POSIX Mode 7685@cindex POSIX Mode 7686 7687Starting Bash with the @option{--posix} command-line option or executing 7688@samp{set -o posix} while Bash is running will cause Bash to conform more 7689closely to the @sc{posix} standard by changing the behavior to 7690match that specified by @sc{posix} in areas where the Bash default differs. 7691 7692When invoked as @code{sh}, Bash enters @sc{posix} mode after reading the 7693startup files. 7694 7695The following list is what's changed when `@sc{posix} mode' is in effect: 7696 7697@enumerate 7698@item 7699Bash ensures that the @env{POSIXLY_CORRECT} variable is set. 7700 7701@item 7702When a command in the hash table no longer exists, Bash will re-search 7703@env{$PATH} to find the new location. This is also available with 7704@samp{shopt -s checkhash}. 7705 7706@item 7707Bash will not insert a command without the execute bit set into the 7708command hash table, even if it returns it as a (last-ditch) result 7709from a @env{$PATH} search. 7710 7711@item 7712The message printed by the job control code and builtins when a job 7713exits with a non-zero status is `Done(status)'. 7714 7715@item 7716The message printed by the job control code and builtins when a job 7717is stopped is `Stopped(@var{signame})', where @var{signame} is, for 7718example, @code{SIGTSTP}. 7719 7720@item 7721Alias expansion is always enabled, even in non-interactive shells. 7722 7723@item 7724Reserved words appearing in a context where reserved words are recognized 7725do not undergo alias expansion. 7726 7727@item 7728The @sc{posix} @env{PS1} and @env{PS2} expansions of @samp{!} to 7729the history number and @samp{!!} to @samp{!} are enabled, 7730and parameter expansion is performed on the values of @env{PS1} and 7731@env{PS2} regardless of the setting of the @code{promptvars} option. 7732 7733@item 7734The @sc{posix} startup files are executed (@env{$ENV}) rather than 7735the normal Bash files. 7736 7737@item 7738Tilde expansion is only performed on assignments preceding a command 7739name, rather than on all assignment statements on the line. 7740 7741@item 7742The default history file is @file{~/.sh_history} (this is the 7743default value of @env{$HISTFILE}). 7744 7745@item 7746Redirection operators do not perform filename expansion on the word 7747in the redirection unless the shell is interactive. 7748 7749@item 7750Redirection operators do not perform word splitting on the word in the 7751redirection. 7752 7753@item 7754Function names must be valid shell @code{name}s. That is, they may not 7755contain characters other than letters, digits, and underscores, and 7756may not start with a digit. Declaring a function with an invalid name 7757causes a fatal syntax error in non-interactive shells. 7758 7759@item 7760Function names may not be the same as one of the @sc{posix} special 7761builtins. 7762 7763@item 7764@sc{posix} special builtins are found before shell functions 7765during command lookup. 7766 7767@item 7768When printing shell function definitions (e.g., by @code{type}), Bash does 7769not print the @code{function} keyword. 7770 7771@item 7772Literal tildes that appear as the first character in elements of 7773the @env{PATH} variable are not expanded as described above 7774under @ref{Tilde Expansion}. 7775 7776@item 7777The @code{time} reserved word may be used by itself as a command. When 7778used in this way, it displays timing statistics for the shell and its 7779completed children. The @env{TIMEFORMAT} variable controls the format 7780of the timing information. 7781 7782@item 7783When parsing and expanding a $@{@dots{}@} expansion that appears within 7784double quotes, single quotes are no longer special and cannot be used to 7785quote a closing brace or other special character, unless the operator is 7786one of those defined to perform pattern removal. In this case, they do 7787not have to appear as matched pairs. 7788 7789@item 7790The parser does not recognize @code{time} as a reserved word if the next 7791token begins with a @samp{-}. 7792 7793@ignore 7794@item 7795When parsing @code{$()} command substitutions containing here-documents, 7796the parser does not allow a here-document to be delimited by the closing 7797right parenthesis. The newline after the here-document delimiter is required. 7798@end ignore 7799 7800@item 7801The @samp{!} character does not introduce history expansion within a 7802double-quoted string, even if the @code{histexpand} option is enabled. 7803 7804@item 7805If a @sc{posix} special builtin returns an error status, a 7806non-interactive shell exits. The fatal errors are those listed in 7807the @sc{posix} standard, and include things like passing incorrect options, 7808redirection errors, variable assignment errors for assignments preceding 7809the command name, and so on. 7810 7811@item 7812A non-interactive shell exits with an error status if a variable 7813assignment error occurs when no command name follows the assignment 7814statements. 7815A variable assignment error occurs, for example, when trying to assign 7816a value to a readonly variable. 7817 7818@item 7819A non-interactive shell exits with an error status if a variable 7820assignment error occurs in an assignment statement preceding a special 7821builtin, but not with any other simple command. 7822 7823@item 7824A non-interactive shell exits with an error status if the iteration 7825variable in a @code{for} statement or the selection variable in a 7826@code{select} statement is a readonly variable. 7827 7828@item 7829Non-interactive shells exit if @var{filename} in @code{.} @var{filename} 7830is not found. 7831 7832@item 7833Non-interactive shells exit if a syntax error in an arithmetic expansion 7834results in an invalid expression. 7835 7836@item 7837Non-interactive shells exit if a parameter expansion error occurs. 7838 7839@item 7840Non-interactive shells exit if there is a syntax error in a script read 7841with the @code{.} or @code{source} builtins, or in a string processed by 7842the @code{eval} builtin. 7843 7844@item 7845While variable indirection is available, it may not be applied to the 7846@samp{#} and @samp{?} special parameters. 7847 7848@item 7849When expanding the @samp{*} special parameter in a pattern context where the 7850expansion is double-quoted does not treat the @code{$*} as if it were 7851double-quoted. 7852 7853@item 7854Assignment statements preceding @sc{posix} special builtins 7855persist in the shell environment after the builtin completes. 7856 7857@item 7858The @code{command} builtin does not prevent builtins that take assignment 7859statements as arguments from expanding them as assignment statements; 7860when not in @sc{posix} mode, assignment builtins lose their assignment 7861statement expansion properties when preceded by @code{command}. 7862 7863@item 7864The @code{bg} builtin uses the required format to describe each job placed 7865in the background, which does not include an indication of whether the job 7866is the current or previous job. 7867 7868@item 7869The output of @samp{kill -l} prints all the signal names on a single line, 7870separated by spaces, without the @samp{SIG} prefix. 7871 7872@item 7873The @code{kill} builtin does not accept signal names with a @samp{SIG} 7874prefix. 7875 7876@item 7877The @code{export} and @code{readonly} builtin commands display their 7878output in the format required by @sc{posix}. 7879 7880@item 7881The @code{trap} builtin displays signal names without the leading 7882@code{SIG}. 7883 7884@item 7885The @code{trap} builtin doesn't check the first argument for a possible 7886signal specification and revert the signal handling to the original 7887disposition if it is, unless that argument consists solely of digits and 7888is a valid signal number. If users want to reset the handler for a given 7889signal to the original disposition, they should use @samp{-} as the 7890first argument. 7891 7892@item 7893@code{trap -p} displays signals whose dispositions are set to SIG_DFL and 7894those that were ignored when the shell started. 7895 7896@item 7897The @code{.} and @code{source} builtins do not search the current directory 7898for the filename argument if it is not found by searching @env{PATH}. 7899 7900@item 7901Enabling @sc{posix} mode has the effect of setting the 7902@code{inherit_errexit} option, so 7903subshells spawned to execute command substitutions inherit the value of 7904the @option{-e} option from the parent shell. 7905When the @code{inherit_errexit} option is not enabled, 7906Bash clears the @option{-e} option in such subshells. 7907 7908@item 7909Enabling @sc{posix} mode has the effect of setting the 7910@code{shift_verbose} option, so numeric arguments to @code{shift} 7911that exceed the number of positional parameters will result in an 7912error message. 7913 7914@item 7915When the @code{alias} builtin displays alias definitions, it does not 7916display them with a leading @samp{alias } unless the @option{-p} option 7917is supplied. 7918 7919@item 7920When the @code{set} builtin is invoked without options, it does not display 7921shell function names and definitions. 7922 7923@item 7924When the @code{set} builtin is invoked without options, it displays 7925variable values without quotes, unless they contain shell metacharacters, 7926even if the result contains nonprinting characters. 7927 7928@item 7929When the @code{cd} builtin is invoked in @var{logical} mode, and the pathname 7930constructed from @code{$PWD} and the directory name supplied as an argument 7931does not refer to an existing directory, @code{cd} will fail instead of 7932falling back to @var{physical} mode. 7933 7934@item 7935When the @code{cd} builtin cannot change a directory because the 7936length of the pathname 7937constructed from @code{$PWD} and the directory name supplied as an argument 7938exceeds @var{PATH_MAX} when all symbolic links are expanded, @code{cd} will 7939fail instead of attempting to use only the supplied directory name. 7940 7941@item 7942The @code{pwd} builtin verifies that the value it prints is the same as the 7943current directory, even if it is not asked to check the file system with the 7944@option{-P} option. 7945 7946@item 7947When listing the history, the @code{fc} builtin does not include an 7948indication of whether or not a history entry has been modified. 7949 7950@item 7951The default editor used by @code{fc} is @code{ed}. 7952 7953@item 7954The @code{type} and @code{command} builtins will not report a non-executable 7955file as having been found, though the shell will attempt to execute such a 7956file if it is the only so-named file found in @code{$PATH}. 7957 7958@item 7959The @code{vi} editing mode will invoke the @code{vi} editor directly when 7960the @samp{v} command is run, instead of checking @code{$VISUAL} and 7961@code{$EDITOR}. 7962 7963@item 7964When the @code{xpg_echo} option is enabled, Bash does not attempt to interpret 7965any arguments to @code{echo} as options. Each argument is displayed, after 7966escape characters are converted. 7967 7968@item 7969The @code{ulimit} builtin uses a block size of 512 bytes for the @option{-c} 7970and @option{-f} options. 7971 7972@item 7973The arrival of @code{SIGCHLD} when a trap is set on @code{SIGCHLD} does 7974not interrupt the @code{wait} builtin and cause it to return immediately. 7975The trap command is run once for each child that exits. 7976 7977@item 7978The @code{read} builtin may be interrupted by a signal for which a trap 7979has been set. 7980If Bash receives a trapped signal while executing @code{read}, the trap 7981handler executes and @code{read} returns an exit status greater than 128. 7982 7983@item 7984Bash removes an exited background process's status from the list of such 7985statuses after the @code{wait} builtin is used to obtain it. 7986 7987@end enumerate 7988 7989There is other @sc{posix} behavior that Bash does not implement by 7990default even when in @sc{posix} mode. 7991Specifically: 7992 7993@enumerate 7994 7995@item 7996The @code{fc} builtin checks @code{$EDITOR} as a program to edit history 7997entries if @code{FCEDIT} is unset, rather than defaulting directly to 7998@code{ed}. @code{fc} uses @code{ed} if @code{EDITOR} is unset. 7999 8000@item 8001As noted above, Bash requires the @code{xpg_echo} option to be enabled for 8002the @code{echo} builtin to be fully conformant. 8003 8004@end enumerate 8005 8006Bash can be configured to be @sc{posix}-conformant by default, by specifying 8007the @option{--enable-strict-posix-default} to @code{configure} when building 8008(@pxref{Optional Features}). 8009 8010@node Shell Compatibility Mode 8011@section Shell Compatibility Mode 8012@cindex Compatibility Level 8013@cindex Compatibility Mode 8014 8015Bash-4.0 introduced the concept of a `shell compatibility level', specified 8016as a set of options to the shopt builtin 8017(@code{compat31}, 8018@code{compat32}, 8019@code{compat40}, 8020@code{compat41}, 8021and so on). 8022There is only one current 8023compatibility level -- each option is mutually exclusive. 8024The compatibility level is intended to allow users to select behavior 8025from previous versions that is incompatible with newer versions 8026while they migrate scripts to use current features and 8027behavior. It's intended to be a temporary solution. 8028 8029This section does not mention behavior that is standard for a particular 8030version (e.g., setting @code{compat32} means that quoting the rhs of the regexp 8031matching operator quotes special regexp characters in the word, which is 8032default behavior in bash-3.2 and above). 8033 8034If a user enables, say, @code{compat32}, it may affect the behavior of other 8035compatibility levels up to and including the current compatibility level. 8036The idea is that each compatibility level controls behavior that changed 8037in that version of Bash, 8038but that behavior may have been present in earlier versions. 8039For instance, the change to use locale-based comparisons with the @code{[[} 8040command came in bash-4.1, and earlier versions used ASCII-based comparisons, 8041so enabling @code{compat32} will enable ASCII-based comparisons as well. 8042That granularity may not be sufficient for 8043all uses, and as a result users should employ compatibility levels carefully. 8044Read the documentation for a particular feature to find out the 8045current behavior. 8046 8047Bash-4.3 introduced a new shell variable: @env{BASH_COMPAT}. 8048The value assigned 8049to this variable (a decimal version number like 4.2, or an integer 8050corresponding to the @code{compat}@var{NN} option, like 42) determines the 8051compatibility level. 8052 8053Starting with bash-4.4, Bash has begun deprecating older compatibility 8054levels. 8055Eventually, the options will be removed in favor of @env{BASH_COMPAT}. 8056 8057Bash-5.0 is the final version for which there will be an individual shopt 8058option for the previous version. Users should use @env{BASH_COMPAT} 8059on bash-5.0 and later versions. 8060 8061The following table describes the behavior changes controlled by each 8062compatibility level setting. 8063The @code{compat}@var{NN} tag is used as shorthand for setting the 8064compatibility level 8065to @var{NN} using one of the following mechanisms. 8066For versions prior to bash-5.0, the compatibility level may be set using 8067the corresponding @code{compat}@var{NN} shopt option. 8068For bash-4.3 and later versions, the @env{BASH_COMPAT} variable is preferred, 8069and it is required for bash-5.1 and later versions. 8070 8071@table @code 8072@item compat31 8073@itemize @bullet 8074@item 8075quoting the rhs of the @code{[[} command's regexp matching operator (=~) 8076has no special effect 8077@end itemize 8078 8079@item compat32 8080@itemize @bullet 8081@item 8082interrupting a command list such as "a ; b ; c" causes the execution 8083of the next command in the list (in bash-4.0 and later versions, 8084the shell acts as if it received the interrupt, so 8085interrupting one command in a list aborts the execution of the 8086entire list) 8087@end itemize 8088 8089@item compat40 8090@itemize @bullet 8091@item 8092the @samp{<} and @samp{>} operators to the @code{[[} command do not 8093consider the current locale when comparing strings; they use ASCII 8094ordering. 8095Bash versions prior to bash-4.1 use ASCII collation and strcmp(3); 8096bash-4.1 and later use the current locale's collation sequence and 8097strcoll(3). 8098@end itemize 8099 8100@item compat41 8101@itemize @bullet 8102@item 8103in posix mode, @code{time} may be followed by options and still be 8104recognized as a reserved word (this is @sc{posix} interpretation 267) 8105@item 8106in posix mode, the parser requires that an even number of single 8107quotes occur in the @var{word} portion of a double-quoted $@{@dots{}@} 8108parameter expansion and treats them specially, so that characters within 8109the single quotes are considered quoted 8110(this is @sc{posix} interpretation 221) 8111@end itemize 8112 8113@item compat42 8114@itemize @bullet 8115@item 8116the replacement string in double-quoted pattern substitution does not 8117undergo quote removal, as it does in versions after bash-4.2 8118@item 8119in posix mode, single quotes are considered special when expanding 8120the @var{word} portion of a double-quoted $@{@dots{}@} parameter expansion 8121and can be used to quote a closing brace or other special character 8122(this is part of @sc{posix} interpretation 221); 8123in later versions, single quotes 8124are not special within double-quoted word expansions 8125@end itemize 8126 8127@item compat43 8128@itemize @bullet 8129@item 8130the shell does not print a warning message if an attempt is made to 8131use a quoted compound assignment as an argument to declare 8132(declare -a foo='(1 2)'). Later versions warn that this usage is 8133deprecated 8134@item 8135word expansion errors are considered non-fatal errors that cause the 8136current command to fail, even in posix mode 8137(the default behavior is to make them fatal errors that cause the shell 8138to exit) 8139@item 8140when executing a shell function, the loop state (while/until/etc.) 8141is not reset, so @code{break} or @code{continue} in that function will break 8142or continue loops in the calling context. Bash-4.4 and later reset 8143the loop state to prevent this 8144@end itemize 8145 8146@item compat44 8147@itemize @bullet 8148@item 8149the shell sets up the values used by @env{BASH_ARGV} and @env{BASH_ARGC} 8150so they can expand to the shell's positional parameters even if extended 8151debugging mode is not enabled 8152@item 8153a subshell inherits loops from its parent context, so @code{break} 8154or @code{continue} will cause the subshell to exit. 8155Bash-5.0 and later reset the loop state to prevent the exit 8156@item 8157variable assignments preceding builtins like @code{export} and @code{readonly} 8158that set attributes continue to affect variables with the same 8159name in the calling environment even if the shell is not in posix 8160mode 8161@end itemize 8162 8163@item compat50 (set using BASH_COMPAT) 8164@itemize @bullet 8165@item 8166Bash-5.1 changed the way @code{$RANDOM} is generated to introduce slightly 8167more randomness. If the shell compatibility level is set to 50 or 8168lower, it reverts to the method from bash-5.0 and previous versions, 8169so seeding the random number generator by assigning a value to 8170@env{RANDOM} will produce the same sequence as in bash-5.0 8171@item 8172If the command hash table is empty, Bash versions prior to bash-5.1 8173printed an informational message to that effect, even when producing 8174output that can be reused as input. Bash-5.1 suppresses that message 8175when the @option{-l} option is supplied. 8176@end itemize 8177@end table 8178 8179@node Job Control 8180@chapter Job Control 8181 8182This chapter discusses what job control is, how it works, and how 8183Bash allows you to access its facilities. 8184 8185@menu 8186* Job Control Basics:: How job control works. 8187* Job Control Builtins:: Bash builtin commands used to interact 8188 with job control. 8189* Job Control Variables:: Variables Bash uses to customize job 8190 control. 8191@end menu 8192 8193@node Job Control Basics 8194@section Job Control Basics 8195@cindex job control 8196@cindex foreground 8197@cindex background 8198@cindex suspending jobs 8199 8200Job control 8201refers to the ability to selectively stop (suspend) 8202the execution of processes and continue (resume) 8203their execution at a later point. A user typically employs 8204this facility via an interactive interface supplied jointly 8205by the operating system kernel's terminal driver and Bash. 8206 8207The shell associates a @var{job} with each pipeline. It keeps a 8208table of currently executing jobs, which may be listed with the 8209@code{jobs} command. When Bash starts a job 8210asynchronously, it prints a line that looks 8211like: 8212@example 8213[1] 25647 8214@end example 8215@noindent 8216indicating that this job is job number 1 and that the process @sc{id} 8217of the last process in the pipeline associated with this job is 821825647. All of the processes in a single pipeline are members of 8219the same job. Bash uses the @var{job} abstraction as the 8220basis for job control. 8221 8222To facilitate the implementation of the user interface to job 8223control, the operating system maintains the notion of a current terminal 8224process group @sc{id}. Members of this process group (processes whose 8225process group @sc{id} is equal to the current terminal process group 8226@sc{id}) receive keyboard-generated signals such as @code{SIGINT}. 8227These processes are said to be in the foreground. Background 8228processes are those whose process group @sc{id} differs from the 8229terminal's; such processes are immune to keyboard-generated 8230signals. Only foreground processes are allowed to read from or, if 8231the user so specifies with @code{stty tostop}, write to the terminal. 8232Background processes which attempt to 8233read from (write to when @code{stty tostop} is in effect) the 8234terminal are sent a @code{SIGTTIN} (@code{SIGTTOU}) 8235signal by the kernel's terminal driver, 8236which, unless caught, suspends the process. 8237 8238If the operating system on which Bash is running supports 8239job control, Bash contains facilities to use it. Typing the 8240@var{suspend} character (typically @samp{^Z}, Control-Z) while a 8241process is running causes that process to be stopped and returns 8242control to Bash. Typing the @var{delayed suspend} character 8243(typically @samp{^Y}, Control-Y) causes the process to be stopped 8244when it attempts to read input from the terminal, and control to 8245be returned to Bash. The user then manipulates the state of 8246this job, using the @code{bg} command to continue it in the 8247background, the @code{fg} command to continue it in the 8248foreground, or the @code{kill} command to kill it. A @samp{^Z} 8249takes effect immediately, and has the additional side effect of 8250causing pending output and typeahead to be discarded. 8251 8252There are a number of ways to refer to a job in the shell. The 8253character @samp{%} introduces a job specification (@var{jobspec}). 8254 8255Job number @code{n} may be referred to as @samp{%n}. 8256The symbols @samp{%%} and @samp{%+} refer to the shell's notion of the 8257current job, which is the last job stopped while it was in the foreground 8258or started in the background. 8259A single @samp{%} (with no accompanying job specification) also refers 8260to the current job. 8261The previous job may be referenced using @samp{%-}. 8262If there is only a single job, @samp{%+} and @samp{%-} can both be used 8263to refer to that job. 8264In output pertaining to jobs (e.g., the output of the @code{jobs} 8265command), the current job is always flagged with a @samp{+}, and the 8266previous job with a @samp{-}. 8267 8268A job may also be referred to 8269using a prefix of the name used to start it, or using a substring 8270that appears in its command line. For example, @samp{%ce} refers 8271to a stopped job whose command name begins with @samp{ce}. 8272Using @samp{%?ce}, on the 8273other hand, refers to any job containing the string @samp{ce} in 8274its command line. If the prefix or substring matches more than one job, 8275Bash reports an error. 8276 8277Simply naming a job can be used to bring it into the foreground: 8278@samp{%1} is a synonym for @samp{fg %1}, bringing job 1 from the 8279background into the foreground. Similarly, @samp{%1 &} resumes 8280job 1 in the background, equivalent to @samp{bg %1} 8281 8282The shell learns immediately whenever a job changes state. 8283Normally, Bash waits until it is about to print a prompt 8284before reporting changes in a job's status so as to not interrupt 8285any other output. 8286If the @option{-b} option to the @code{set} builtin is enabled, 8287Bash reports such changes immediately (@pxref{The Set Builtin}). 8288Any trap on @code{SIGCHLD} is executed for each child process 8289that exits. 8290 8291If an attempt to exit Bash is made while jobs are stopped, (or running, if 8292the @code{checkjobs} option is enabled -- see @ref{The Shopt Builtin}), the 8293shell prints a warning message, and if the @code{checkjobs} option is 8294enabled, lists the jobs and their statuses. 8295The @code{jobs} command may then be used to inspect their status. 8296If a second attempt to exit is made without an intervening command, 8297Bash does not print another warning, and any stopped jobs are terminated. 8298 8299When the shell is waiting for a job or process using the @code{wait} 8300builtin, and job control is enabled, @code{wait} will return when the 8301job changes state. The @option{-f} option causes @code{wait} to wait 8302until the job or process terminates before returning. 8303 8304@node Job Control Builtins 8305@section Job Control Builtins 8306 8307@table @code 8308 8309@item bg 8310@btindex bg 8311@example 8312bg [@var{jobspec} @dots{}] 8313@end example 8314 8315Resume each suspended job @var{jobspec} in the background, as if it 8316had been started with @samp{&}. 8317If @var{jobspec} is not supplied, the current job is used. 8318The return status is zero unless it is run when job control is not 8319enabled, or, when run with job control enabled, any 8320@var{jobspec} was not found or specifies a job 8321that was started without job control. 8322 8323@item fg 8324@btindex fg 8325@example 8326fg [@var{jobspec}] 8327@end example 8328 8329Resume the job @var{jobspec} in the foreground and make it the current job. 8330If @var{jobspec} is not supplied, the current job is used. 8331The return status is that of the command placed into the foreground, 8332or non-zero if run when job control is disabled or, when run with 8333job control enabled, @var{jobspec} does not specify a valid job or 8334@var{jobspec} specifies a job that was started without job control. 8335 8336@item jobs 8337@btindex jobs 8338@example 8339jobs [-lnprs] [@var{jobspec}] 8340jobs -x @var{command} [@var{arguments}] 8341@end example 8342 8343The first form lists the active jobs. The options have the 8344following meanings: 8345 8346@table @code 8347@item -l 8348List process @sc{id}s in addition to the normal information. 8349 8350@item -n 8351Display information only about jobs that have changed status since 8352the user was last notified of their status. 8353 8354@item -p 8355List only the process @sc{id} of the job's process group leader. 8356 8357@item -r 8358Display only running jobs. 8359 8360@item -s 8361Display only stopped jobs. 8362@end table 8363 8364If @var{jobspec} is given, 8365output is restricted to information about that job. 8366If @var{jobspec} is not supplied, the status of all jobs is 8367listed. 8368 8369If the @option{-x} option is supplied, @code{jobs} replaces any 8370@var{jobspec} found in @var{command} or @var{arguments} with the 8371corresponding process group @sc{id}, and executes @var{command}, 8372passing it @var{argument}s, returning its exit status. 8373 8374@item kill 8375@btindex kill 8376@example 8377kill [-s @var{sigspec}] [-n @var{signum}] [-@var{sigspec}] @var{jobspec} or @var{pid} 8378kill -l|-L [@var{exit_status}] 8379@end example 8380 8381Send a signal specified by @var{sigspec} or @var{signum} to the process 8382named by job specification @var{jobspec} or process @sc{id} @var{pid}. 8383@var{sigspec} is either a case-insensitive signal name such as 8384@code{SIGINT} (with or without the @code{SIG} prefix) 8385or a signal number; @var{signum} is a signal number. 8386If @var{sigspec} and @var{signum} are not present, @code{SIGTERM} is used. 8387The @option{-l} option lists the signal names. 8388If any arguments are supplied when @option{-l} is given, the names of the 8389signals corresponding to the arguments are listed, and the return status 8390is zero. 8391@var{exit_status} is a number specifying a signal number or the exit 8392status of a process terminated by a signal. 8393The @option{-L} option is equivalent to @option{-l}. 8394The return status is zero if at least one signal was successfully sent, 8395or non-zero if an error occurs or an invalid option is encountered. 8396 8397@item wait 8398@btindex wait 8399@example 8400wait [-fn] [-p @var{varname}] [@var{jobspec} or @var{pid} @dots{}] 8401@end example 8402 8403Wait until the child process specified by each process @sc{id} @var{pid} 8404or job specification @var{jobspec} exits and return the exit status of the 8405last command waited for. 8406If a job spec is given, all processes in the job are waited for. 8407If no arguments are given, 8408@code{wait} waits for all running background jobs and 8409the last-executed process substitution, if its process id is the same as 8410@var{$!}, 8411and the return status is zero. 8412If the @option{-n} option is supplied, @code{wait} waits for a single job 8413from the list of @var{pids} or @var{jobspecs} or, if no arguments are 8414supplied, any job, 8415to complete and returns its exit status. 8416If none of the supplied arguments is a child of the shell, or if no arguments 8417are supplied and the shell has no unwaited-for children, the exit status 8418is 127. 8419If the @option{-p} option is supplied, the process or job identifier of the job 8420for which the exit status is returned is assigned to the variable 8421@var{varname} named by the option argument. 8422The variable will be unset initially, before any assignment. 8423This is useful only when the @option{-n} option is supplied. 8424Supplying the @option{-f} option, when job control is enabled, 8425forces @code{wait} to wait for each @var{pid} or @var{jobspec} to 8426terminate before returning its status, intead of returning when it changes 8427status. 8428If neither @var{jobspec} nor @var{pid} specifies an active child process 8429of the shell, the return status is 127. 8430 8431@item disown 8432@btindex disown 8433@example 8434disown [-ar] [-h] [@var{jobspec} @dots{} | @var{pid} @dots{} ] 8435@end example 8436 8437Without options, remove each @var{jobspec} from the table of 8438active jobs. 8439If the @option{-h} option is given, the job is not removed from the table, 8440but is marked so that @code{SIGHUP} is not sent to the job if the shell 8441receives a @code{SIGHUP}. 8442If @var{jobspec} is not present, and neither the @option{-a} nor the 8443@option{-r} option is supplied, the current job is used. 8444If no @var{jobspec} is supplied, the @option{-a} option means to remove or 8445mark all jobs; the @option{-r} option without a @var{jobspec} 8446argument restricts operation to running jobs. 8447 8448@item suspend 8449@btindex suspend 8450@example 8451suspend [-f] 8452@end example 8453 8454Suspend the execution of this shell until it receives a 8455@code{SIGCONT} signal. 8456A login shell cannot be suspended; the @option{-f} 8457option can be used to override this and force the suspension. 8458@end table 8459 8460When job control is not active, the @code{kill} and @code{wait} 8461builtins do not accept @var{jobspec} arguments. They must be 8462supplied process @sc{id}s. 8463 8464@node Job Control Variables 8465@section Job Control Variables 8466 8467@vtable @code 8468 8469@item auto_resume 8470This variable controls how the shell interacts with the user and 8471job control. If this variable exists then single word simple 8472commands without redirections are treated as candidates for resumption 8473of an existing job. There is no ambiguity allowed; if there is 8474more than one job beginning with the string typed, then 8475the most recently accessed job will be selected. 8476The name of a stopped job, in this context, is the command line 8477used to start it. If this variable is set to the value @samp{exact}, 8478the string supplied must match the name of a stopped job exactly; 8479if set to @samp{substring}, 8480the string supplied needs to match a substring of the name of a 8481stopped job. The @samp{substring} value provides functionality 8482analogous to the @samp{%?} job @sc{id} (@pxref{Job Control Basics}). 8483If set to any other value, the supplied string must 8484be a prefix of a stopped job's name; this provides functionality 8485analogous to the @samp{%} job @sc{id}. 8486 8487@end vtable 8488 8489@set readline-appendix 8490@set history-appendix 8491@cindex Readline, how to use 8492@include rluser.texi 8493@cindex History, how to use 8494@include hsuser.texi 8495@clear readline-appendix 8496@clear history-appendix 8497 8498@node Installing Bash 8499@chapter Installing Bash 8500 8501This chapter provides basic instructions for installing Bash on 8502the various supported platforms. The distribution supports the 8503@sc{gnu} operating systems, nearly every version of Unix, and several 8504non-Unix systems such as BeOS and Interix. 8505Other independent ports exist for 8506@sc{ms-dos}, @sc{os/2}, and Windows platforms. 8507 8508@menu 8509* Basic Installation:: Installation instructions. 8510* Compilers and Options:: How to set special options for various 8511 systems. 8512* Compiling For Multiple Architectures:: How to compile Bash for more 8513 than one kind of system from 8514 the same source tree. 8515* Installation Names:: How to set the various paths used by the installation. 8516* Specifying the System Type:: How to configure Bash for a particular system. 8517* Sharing Defaults:: How to share default configuration values among GNU 8518 programs. 8519* Operation Controls:: Options recognized by the configuration program. 8520* Optional Features:: How to enable and disable optional features when 8521 building Bash. 8522@end menu 8523 8524@node Basic Installation 8525@section Basic Installation 8526@cindex installation 8527@cindex configuration 8528@cindex Bash installation 8529@cindex Bash configuration 8530 8531These are installation instructions for Bash. 8532 8533The simplest way to compile Bash is: 8534 8535@enumerate 8536@item 8537@code{cd} to the directory containing the source code and type 8538@samp{./configure} to configure Bash for your system. If you're 8539using @code{csh} on an old version of System V, you might need to 8540type @samp{sh ./configure} instead to prevent @code{csh} from trying 8541to execute @code{configure} itself. 8542 8543Running @code{configure} takes some time. 8544While running, it prints messages telling which features it is 8545checking for. 8546 8547@item 8548Type @samp{make} to compile Bash and build the @code{bashbug} bug 8549reporting script. 8550 8551@item 8552Optionally, type @samp{make tests} to run the Bash test suite. 8553 8554@item 8555Type @samp{make install} to install @code{bash} and @code{bashbug}. 8556This will also install the manual pages and Info file. 8557 8558@end enumerate 8559 8560The @code{configure} shell script attempts to guess correct 8561values for various system-dependent variables used during 8562compilation. It uses those values to create a @file{Makefile} in 8563each directory of the package (the top directory, the 8564@file{builtins}, @file{doc}, and @file{support} directories, 8565each directory under @file{lib}, and several others). It also creates a 8566@file{config.h} file containing system-dependent definitions. 8567Finally, it creates a shell script named @code{config.status} that you 8568can run in the future to recreate the current configuration, a 8569file @file{config.cache} that saves the results of its tests to 8570speed up reconfiguring, and a file @file{config.log} containing 8571compiler output (useful mainly for debugging @code{configure}). 8572If at some point 8573@file{config.cache} contains results you don't want to keep, you 8574may remove or edit it. 8575 8576To find out more about the options and arguments that the 8577@code{configure} script understands, type 8578 8579@example 8580bash-4.2$ ./configure --help 8581@end example 8582 8583@noindent 8584at the Bash prompt in your Bash source directory. 8585 8586If you want to build Bash in a directory separate from the source 8587directory -- to build for multiple architectures, for example -- 8588just use the full path to the configure script. The following commands 8589will build bash in a directory under @file{/usr/local/build} from 8590the source code in @file{/usr/local/src/bash-4.4}: 8591 8592@example 8593mkdir /usr/local/build/bash-4.4 8594cd /usr/local/build/bash-4.4 8595bash /usr/local/src/bash-4.4/configure 8596make 8597@end example 8598 8599See @ref{Compiling For Multiple Architectures} for more information 8600about building in a directory separate from the source. 8601 8602If you need to do unusual things to compile Bash, please 8603try to figure out how @code{configure} could check whether or not 8604to do them, and mail diffs or instructions to 8605@email{bash-maintainers@@gnu.org} so they can be 8606considered for the next release. 8607 8608The file @file{configure.ac} is used to create @code{configure} 8609by a program called Autoconf. You only need 8610@file{configure.ac} if you want to change it or regenerate 8611@code{configure} using a newer version of Autoconf. If 8612you do this, make sure you are using Autoconf version 2.50 or 8613newer. 8614 8615You can remove the program binaries and object files from the 8616source code directory by typing @samp{make clean}. To also remove the 8617files that @code{configure} created (so you can compile Bash for 8618a different kind of computer), type @samp{make distclean}. 8619 8620@node Compilers and Options 8621@section Compilers and Options 8622 8623Some systems require unusual options for compilation or linking 8624that the @code{configure} script does not know about. You can 8625give @code{configure} initial values for variables by setting 8626them in the environment. Using a Bourne-compatible shell, you 8627can do that on the command line like this: 8628 8629@example 8630CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure 8631@end example 8632 8633On systems that have the @code{env} program, you can do it like this: 8634 8635@example 8636env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure 8637@end example 8638 8639The configuration process uses GCC to build Bash if it 8640is available. 8641 8642@node Compiling For Multiple Architectures 8643@section Compiling For Multiple Architectures 8644 8645You can compile Bash for more than one kind of computer at the 8646same time, by placing the object files for each architecture in their 8647own directory. To do this, you must use a version of @code{make} that 8648supports the @code{VPATH} variable, such as GNU @code{make}. 8649@code{cd} to the 8650directory where you want the object files and executables to go and run 8651the @code{configure} script from the source directory 8652(@pxref{Basic Installation}). 8653You may need to 8654supply the @option{--srcdir=PATH} argument to tell @code{configure} where the 8655source files are. @code{configure} automatically checks for the 8656source code in the directory that @code{configure} is in and in `..'. 8657 8658If you have to use a @code{make} that does not supports the @code{VPATH} 8659variable, you can compile Bash for one architecture at a 8660time in the source code directory. After you have installed 8661Bash for one architecture, use @samp{make distclean} before 8662reconfiguring for another architecture. 8663 8664Alternatively, if your system supports symbolic links, you can use the 8665@file{support/mkclone} script to create a build tree which has 8666symbolic links back to each file in the source directory. Here's an 8667example that creates a build directory in the current directory from a 8668source directory @file{/usr/gnu/src/bash-2.0}: 8669 8670@example 8671bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 . 8672@end example 8673 8674@noindent 8675The @code{mkclone} script requires Bash, so you must have already built 8676Bash for at least one architecture before you can create build 8677directories for other architectures. 8678 8679@node Installation Names 8680@section Installation Names 8681 8682By default, @samp{make install} will install into 8683@file{/usr/local/bin}, @file{/usr/local/man}, etc. You can 8684specify an installation prefix other than @file{/usr/local} by 8685giving @code{configure} the option @option{--prefix=@var{PATH}}, 8686or by specifying a value for the @code{DESTDIR} @samp{make} 8687variable when running @samp{make install}. 8688 8689You can specify separate installation prefixes for 8690architecture-specific files and architecture-independent files. 8691If you give @code{configure} the option 8692@option{--exec-prefix=@var{PATH}}, @samp{make install} will use 8693@var{PATH} as the prefix for installing programs and libraries. 8694Documentation and other data files will still use the regular prefix. 8695 8696@node Specifying the System Type 8697@section Specifying the System Type 8698 8699There may be some features @code{configure} can not figure out 8700automatically, but need to determine by the type of host Bash 8701will run on. Usually @code{configure} can figure that 8702out, but if it prints a message saying it can not guess the host 8703type, give it the @option{--host=TYPE} option. @samp{TYPE} can 8704either be a short name for the system type, such as @samp{sun4}, 8705or a canonical name with three fields: @samp{CPU-COMPANY-SYSTEM} 8706(e.g., @samp{i386-unknown-freebsd4.2}). 8707 8708See the file @file{support/config.sub} for the possible 8709values of each field. 8710 8711@node Sharing Defaults 8712@section Sharing Defaults 8713 8714If you want to set default values for @code{configure} scripts to 8715share, you can create a site shell script called 8716@code{config.site} that gives default values for variables like 8717@code{CC}, @code{cache_file}, and @code{prefix}. @code{configure} 8718looks for @file{PREFIX/share/config.site} if it exists, then 8719@file{PREFIX/etc/config.site} if it exists. Or, you can set the 8720@code{CONFIG_SITE} environment variable to the location of the site 8721script. A warning: the Bash @code{configure} looks for a site script, 8722but not all @code{configure} scripts do. 8723 8724@node Operation Controls 8725@section Operation Controls 8726 8727@code{configure} recognizes the following options to control how it 8728operates. 8729 8730@table @code 8731 8732@item --cache-file=@var{file} 8733Use and save the results of the tests in 8734@var{file} instead of @file{./config.cache}. Set @var{file} to 8735@file{/dev/null} to disable caching, for debugging 8736@code{configure}. 8737 8738@item --help 8739Print a summary of the options to @code{configure}, and exit. 8740 8741@item --quiet 8742@itemx --silent 8743@itemx -q 8744Do not print messages saying which checks are being made. 8745 8746@item --srcdir=@var{dir} 8747Look for the Bash source code in directory @var{dir}. Usually 8748@code{configure} can determine that directory automatically. 8749 8750@item --version 8751Print the version of Autoconf used to generate the @code{configure} 8752script, and exit. 8753@end table 8754 8755@code{configure} also accepts some other, not widely used, boilerplate 8756options. @samp{configure --help} prints the complete list. 8757 8758@node Optional Features 8759@section Optional Features 8760 8761The Bash @code{configure} has a number of @option{--enable-@var{feature}} 8762options, where @var{feature} indicates an optional part of Bash. 8763There are also several @option{--with-@var{package}} options, 8764where @var{package} is something like @samp{bash-malloc} or @samp{purify}. 8765To turn off the default use of a package, use 8766@option{--without-@var{package}}. To configure Bash without a feature 8767that is enabled by default, use @option{--disable-@var{feature}}. 8768 8769Here is a complete list of the @option{--enable-} and 8770@option{--with-} options that the Bash @code{configure} recognizes. 8771 8772@table @code 8773@item --with-afs 8774Define if you are using the Andrew File System from Transarc. 8775 8776@item --with-bash-malloc 8777Use the Bash version of 8778@code{malloc} in the directory @file{lib/malloc}. This is not the same 8779@code{malloc} that appears in @sc{gnu} libc, but an older version 8780originally derived from the 4.2 @sc{bsd} @code{malloc}. This @code{malloc} 8781is very fast, but wastes some space on each allocation. 8782This option is enabled by default. 8783The @file{NOTES} file contains a list of systems for 8784which this should be turned off, and @code{configure} disables this 8785option automatically for a number of systems. 8786 8787@item --with-curses 8788Use the curses library instead of the termcap library. This should 8789be supplied if your system has an inadequate or incomplete termcap 8790database. 8791 8792@item --with-gnu-malloc 8793A synonym for @code{--with-bash-malloc}. 8794 8795@item --with-installed-readline[=@var{PREFIX}] 8796Define this to make Bash link with a locally-installed version of Readline 8797rather than the version in @file{lib/readline}. This works only with 8798Readline 5.0 and later versions. If @var{PREFIX} is @code{yes} or not 8799supplied, @code{configure} uses the values of the make variables 8800@code{includedir} and @code{libdir}, which are subdirectories of @code{prefix} 8801by default, to find the installed version of Readline if it is not in 8802the standard system include and library directories. 8803If @var{PREFIX} is @code{no}, Bash links with the version in 8804@file{lib/readline}. 8805If @var{PREFIX} is set to any other value, @code{configure} treats it as 8806a directory pathname and looks for 8807the installed version of Readline in subdirectories of that directory 8808(include files in @var{PREFIX}/@code{include} and the library in 8809@var{PREFIX}/@code{lib}). 8810 8811@item --with-purify 8812Define this to use the Purify memory allocation checker from Rational 8813Software. 8814 8815@item --enable-minimal-config 8816This produces a shell with minimal features, close to the historical 8817Bourne shell. 8818@end table 8819 8820There are several @option{--enable-} options that alter how Bash is 8821compiled and linked, rather than changing run-time features. 8822 8823@table @code 8824@item --enable-largefile 8825Enable support for @uref{http://www.unix.org/version2/whatsnew/lfs20mar.html, 8826large files} if the operating system requires special compiler options 8827to build programs which can access large files. This is enabled by 8828default, if the operating system provides large file support. 8829 8830@item --enable-profiling 8831This builds a Bash binary that produces profiling information to be 8832processed by @code{gprof} each time it is executed. 8833 8834@item --enable-static-link 8835This causes Bash to be linked statically, if @code{gcc} is being used. 8836This could be used to build a version to use as root's shell. 8837@end table 8838 8839The @samp{minimal-config} option can be used to disable all of 8840the following options, but it is processed first, so individual 8841options may be enabled using @samp{enable-@var{feature}}. 8842 8843All of the following options except for @samp{disabled-builtins}, 8844@samp{direxpand-default}, and 8845@samp{xpg-echo-default} are 8846enabled by default, unless the operating system does not provide the 8847necessary support. 8848 8849@table @code 8850@item --enable-alias 8851Allow alias expansion and include the @code{alias} and @code{unalias} 8852builtins (@pxref{Aliases}). 8853 8854@item --enable-arith-for-command 8855Include support for the alternate form of the @code{for} command 8856that behaves like the C language @code{for} statement 8857(@pxref{Looping Constructs}). 8858 8859@item --enable-array-variables 8860Include support for one-dimensional array shell variables 8861(@pxref{Arrays}). 8862 8863@item --enable-bang-history 8864Include support for @code{csh}-like history substitution 8865(@pxref{History Interaction}). 8866 8867@item --enable-brace-expansion 8868Include @code{csh}-like brace expansion 8869( @code{b@{a,b@}c} @expansion{} @code{bac bbc} ). 8870See @ref{Brace Expansion}, for a complete description. 8871 8872@item --enable-casemod-attributes 8873Include support for case-modifying attributes in the @code{declare} builtin 8874and assignment statements. Variables with the @var{uppercase} attribute, 8875for example, will have their values converted to uppercase upon assignment. 8876 8877@item --enable-casemod-expansion 8878Include support for case-modifying word expansions. 8879 8880@item --enable-command-timing 8881Include support for recognizing @code{time} as a reserved word and for 8882displaying timing statistics for the pipeline following @code{time} 8883(@pxref{Pipelines}). 8884This allows pipelines as well as shell builtins and functions to be timed. 8885 8886@item --enable-cond-command 8887Include support for the @code{[[} conditional command. 8888(@pxref{Conditional Constructs}). 8889 8890@item --enable-cond-regexp 8891Include support for matching @sc{posix} regular expressions using the 8892@samp{=~} binary operator in the @code{[[} conditional command. 8893(@pxref{Conditional Constructs}). 8894 8895@item --enable-coprocesses 8896Include support for coprocesses and the @code{coproc} reserved word 8897(@pxref{Pipelines}). 8898 8899@item --enable-debugger 8900Include support for the bash debugger (distributed separately). 8901 8902@item --enable-dev-fd-stat-broken 8903If calling @code{stat} on /dev/fd/@var{N} returns different results than 8904calling @code{fstat} on file descriptor @var{N}, supply this option to 8905enable a workaround. 8906This has implications for conditional commands that test file attributes. 8907 8908@item --enable-direxpand-default 8909Cause the @code{direxpand} shell option (@pxref{The Shopt Builtin}) 8910to be enabled by default when the shell starts. 8911It is normally disabled by default. 8912 8913@item --enable-directory-stack 8914Include support for a @code{csh}-like directory stack and the 8915@code{pushd}, @code{popd}, and @code{dirs} builtins 8916(@pxref{The Directory Stack}). 8917 8918@item --enable-disabled-builtins 8919Allow builtin commands to be invoked via @samp{builtin xxx} 8920even after @code{xxx} has been disabled using @samp{enable -n xxx}. 8921See @ref{Bash Builtins}, for details of the @code{builtin} and 8922@code{enable} builtin commands. 8923 8924@item --enable-dparen-arithmetic 8925Include support for the @code{((@dots{}))} command 8926(@pxref{Conditional Constructs}). 8927 8928@item --enable-extended-glob 8929Include support for the extended pattern matching features described 8930above under @ref{Pattern Matching}. 8931 8932@item --enable-extended-glob-default 8933Set the default value of the @var{extglob} shell option described 8934above under @ref{The Shopt Builtin} to be enabled. 8935 8936@item --enable-function-import 8937Include support for importing function definitions exported by another 8938instance of the shell from the environment. This option is enabled by 8939default. 8940 8941@item --enable-glob-asciirange-default 8942Set the default value of the @var{globasciiranges} shell option described 8943above under @ref{The Shopt Builtin} to be enabled. 8944This controls the behavior of character ranges when used in pattern matching 8945bracket expressions. 8946 8947@item --enable-help-builtin 8948Include the @code{help} builtin, which displays help on shell builtins and 8949variables (@pxref{Bash Builtins}). 8950 8951@item --enable-history 8952Include command history and the @code{fc} and @code{history} 8953builtin commands (@pxref{Bash History Facilities}). 8954 8955@item --enable-job-control 8956This enables the job control features (@pxref{Job Control}), 8957if the operating system supports them. 8958 8959@item --enable-multibyte 8960This enables support for multibyte characters if the operating 8961system provides the necessary support. 8962 8963@item --enable-net-redirections 8964This enables the special handling of filenames of the form 8965@code{/dev/tcp/@var{host}/@var{port}} and 8966@code{/dev/udp/@var{host}/@var{port}} 8967when used in redirections (@pxref{Redirections}). 8968 8969@item --enable-process-substitution 8970This enables process substitution (@pxref{Process Substitution}) if 8971the operating system provides the necessary support. 8972 8973@item --enable-progcomp 8974Enable the programmable completion facilities 8975(@pxref{Programmable Completion}). 8976If Readline is not enabled, this option has no effect. 8977 8978@item --enable-prompt-string-decoding 8979Turn on the interpretation of a number of backslash-escaped characters 8980in the @env{$PS0}, @env{$PS1}, @env{$PS2}, and @env{$PS4} prompt 8981strings. See @ref{Controlling the Prompt}, for a complete list of prompt 8982string escape sequences. 8983 8984@item --enable-readline 8985Include support for command-line editing and history with the Bash 8986version of the Readline library (@pxref{Command Line Editing}). 8987 8988@item --enable-restricted 8989Include support for a @dfn{restricted shell}. If this is enabled, Bash, 8990when called as @code{rbash}, enters a restricted mode. See 8991@ref{The Restricted Shell}, for a description of restricted mode. 8992 8993@item --enable-select 8994Include the @code{select} compound command, which allows the generation of 8995simple menus (@pxref{Conditional Constructs}). 8996 8997@item --enable-separate-helpfiles 8998Use external files for the documentation displayed by the @code{help} builtin 8999instead of storing the text internally. 9000 9001@item --enable-single-help-strings 9002Store the text displayed by the @code{help} builtin as a single string for 9003each help topic. This aids in translating the text to different languages. 9004You may need to disable this if your compiler cannot handle very long string 9005literals. 9006 9007@item --enable-strict-posix-default 9008Make Bash @sc{posix}-conformant by default (@pxref{Bash POSIX Mode}). 9009 9010@item --enable-usg-echo-default 9011A synonym for @code{--enable-xpg-echo-default}. 9012 9013@item --enable-xpg-echo-default 9014Make the @code{echo} builtin expand backslash-escaped characters by default, 9015without requiring the @option{-e} option. 9016This sets the default value of the @code{xpg_echo} shell option to @code{on}, 9017which makes the Bash @code{echo} behave more like the version specified in 9018the Single Unix Specification, version 3. 9019@xref{Bash Builtins}, for a description of the escape sequences that 9020@code{echo} recognizes. 9021@end table 9022 9023The file @file{config-top.h} contains C Preprocessor 9024@samp{#define} statements for options which are not settable from 9025@code{configure}. 9026Some of these are not meant to be changed; beware of the consequences if 9027you do. 9028Read the comments associated with each definition for more 9029information about its effect. 9030 9031@node Reporting Bugs 9032@appendix Reporting Bugs 9033 9034Please report all bugs you find in Bash. 9035But first, you should 9036make sure that it really is a bug, and that it appears in the latest 9037version of Bash. 9038The latest version of Bash is always available for FTP from 9039@uref{ftp://ftp.gnu.org/pub/gnu/bash/}. 9040 9041Once you have determined that a bug actually exists, use the 9042@code{bashbug} command to submit a bug report. 9043If you have a fix, you are encouraged to mail that as well! 9044Suggestions and `philosophical' bug reports may be mailed 9045to @email{bug-bash@@gnu.org} or posted to the Usenet 9046newsgroup @code{gnu.bash.bug}. 9047 9048All bug reports should include: 9049@itemize @bullet 9050@item 9051The version number of Bash. 9052@item 9053The hardware and operating system. 9054@item 9055The compiler used to compile Bash. 9056@item 9057A description of the bug behaviour. 9058@item 9059A short script or `recipe' which exercises the bug and may be used 9060to reproduce it. 9061@end itemize 9062 9063@noindent 9064@code{bashbug} inserts the first three items automatically into 9065the template it provides for filing a bug report. 9066 9067Please send all reports concerning this manual to 9068@email{bug-bash@@gnu.org}. 9069 9070@node Major Differences From The Bourne Shell 9071@appendix Major Differences From The Bourne Shell 9072 9073Bash implements essentially the same grammar, parameter and 9074variable expansion, redirection, and quoting as the Bourne Shell. 9075Bash uses the @sc{posix} standard as the specification of 9076how these features are to be implemented. There are some 9077differences between the traditional Bourne shell and Bash; this 9078section quickly details the differences of significance. A 9079number of these differences are explained in greater depth in 9080previous sections. 9081This section uses the version of @code{sh} included in SVR4.2 (the 9082last version of the historical Bourne shell) as the baseline reference. 9083 9084@itemize @bullet 9085 9086@item 9087Bash is @sc{posix}-conformant, even where the @sc{posix} specification 9088differs from traditional @code{sh} behavior (@pxref{Bash POSIX Mode}). 9089 9090@item 9091Bash has multi-character invocation options (@pxref{Invoking Bash}). 9092 9093@item 9094Bash has command-line editing (@pxref{Command Line Editing}) and 9095the @code{bind} builtin. 9096 9097@item 9098Bash provides a programmable word completion mechanism 9099(@pxref{Programmable Completion}), and builtin commands 9100@code{complete}, @code{compgen}, and @code{compopt}, to 9101manipulate it. 9102 9103@item 9104Bash has command history (@pxref{Bash History Facilities}) and the 9105@code{history} and @code{fc} builtins to manipulate it. 9106The Bash history list maintains timestamp information and uses the 9107value of the @code{HISTTIMEFORMAT} variable to display it. 9108 9109@item 9110Bash implements @code{csh}-like history expansion 9111(@pxref{History Interaction}). 9112 9113@item 9114Bash has one-dimensional array variables (@pxref{Arrays}), and the 9115appropriate variable expansions and assignment syntax to use them. 9116Several of the Bash builtins take options to act on arrays. 9117Bash provides a number of built-in array variables. 9118 9119@item 9120The @code{$'@dots{}'} quoting syntax, which expands ANSI-C 9121backslash-escaped characters in the text between the single quotes, 9122is supported (@pxref{ANSI-C Quoting}). 9123 9124@item 9125Bash supports the @code{$"@dots{}"} quoting syntax to do 9126locale-specific translation of the characters between the double 9127quotes. The @option{-D}, @option{--dump-strings}, and @option{--dump-po-strings} 9128invocation options list the translatable strings found in a script 9129(@pxref{Locale Translation}). 9130 9131@item 9132Bash implements the @code{!} keyword to negate the return value of 9133a pipeline (@pxref{Pipelines}). 9134Very useful when an @code{if} statement needs to act only if a test fails. 9135The Bash @samp{-o pipefail} option to @code{set} will cause a pipeline to 9136return a failure status if any command fails. 9137 9138@item 9139Bash has the @code{time} reserved word and command timing (@pxref{Pipelines}). 9140The display of the timing statistics may be controlled with the 9141@env{TIMEFORMAT} variable. 9142 9143@item 9144Bash implements the @code{for (( @var{expr1} ; @var{expr2} ; @var{expr3} ))} 9145arithmetic for command, similar to the C language (@pxref{Looping Constructs}). 9146 9147@item 9148Bash includes the @code{select} compound command, which allows the 9149generation of simple menus (@pxref{Conditional Constructs}). 9150 9151@item 9152Bash includes the @code{[[} compound command, which makes conditional 9153testing part of the shell grammar (@pxref{Conditional Constructs}), including 9154optional regular expression matching. 9155 9156@item 9157Bash provides optional case-insensitive matching for the @code{case} and 9158@code{[[} constructs. 9159 9160@item 9161Bash includes brace expansion (@pxref{Brace Expansion}) and tilde 9162expansion (@pxref{Tilde Expansion}). 9163 9164@item 9165Bash implements command aliases and the @code{alias} and @code{unalias} 9166builtins (@pxref{Aliases}). 9167 9168@item 9169Bash provides shell arithmetic, the @code{((} compound command 9170(@pxref{Conditional Constructs}), 9171and arithmetic expansion (@pxref{Shell Arithmetic}). 9172 9173@item 9174Variables present in the shell's initial environment are automatically 9175exported to child processes. The Bourne shell does not normally do 9176this unless the variables are explicitly marked using the @code{export} 9177command. 9178 9179@item 9180Bash supports the @samp{+=} assignment operator, which appends to the value 9181of the variable named on the left hand side. 9182 9183@item 9184Bash includes the @sc{posix} pattern removal @samp{%}, @samp{#}, @samp{%%} 9185and @samp{##} expansions to remove leading or trailing substrings from 9186variable values (@pxref{Shell Parameter Expansion}). 9187 9188@item 9189The expansion @code{$@{#xx@}}, which returns the length of @code{$@{xx@}}, 9190is supported (@pxref{Shell Parameter Expansion}). 9191 9192@item 9193The expansion @code{$@{var:}@var{offset}@code{[:}@var{length}@code{]@}}, 9194which expands to the substring of @code{var}'s value of length 9195@var{length}, beginning at @var{offset}, is present 9196(@pxref{Shell Parameter Expansion}). 9197 9198@item 9199The expansion 9200@code{$@{var/[/]}@var{pattern}@code{[/}@var{replacement}@code{]@}}, 9201which matches @var{pattern} and replaces it with @var{replacement} in 9202the value of @code{var}, is available (@pxref{Shell Parameter Expansion}). 9203 9204@item 9205The expansion @code{$@{!@var{prefix}*@}} expansion, which expands to 9206the names of all shell variables whose names begin with @var{prefix}, 9207is available (@pxref{Shell Parameter Expansion}). 9208 9209@item 9210Bash has @var{indirect} variable expansion using @code{$@{!word@}} 9211(@pxref{Shell Parameter Expansion}). 9212 9213@item 9214Bash can expand positional parameters beyond @code{$9} using 9215@code{$@{@var{num}@}}. 9216 9217@item 9218The @sc{posix} @code{$()} form of command substitution 9219is implemented (@pxref{Command Substitution}), 9220and preferred to the Bourne shell's @code{``} (which 9221is also implemented for backwards compatibility). 9222 9223@item 9224Bash has process substitution (@pxref{Process Substitution}). 9225 9226@item 9227Bash automatically assigns variables that provide information about the 9228current user (@env{UID}, @env{EUID}, and @env{GROUPS}), the current host 9229(@env{HOSTTYPE}, @env{OSTYPE}, @env{MACHTYPE}, and @env{HOSTNAME}), 9230and the instance of Bash that is running (@env{BASH}, 9231@env{BASH_VERSION}, and @env{BASH_VERSINFO}). @xref{Bash Variables}, 9232for details. 9233 9234@item 9235The @env{IFS} variable is used to split only the results of expansion, 9236not all words (@pxref{Word Splitting}). 9237This closes a longstanding shell security hole. 9238 9239@item 9240The filename expansion bracket expression code uses @samp{!} and @samp{^} 9241to negate the set of characters between the brackets. 9242The Bourne shell uses only @samp{!}. 9243 9244@item 9245Bash implements the full set of @sc{posix} filename expansion operators, 9246including @var{character classes}, @var{equivalence classes}, and 9247@var{collating symbols} (@pxref{Filename Expansion}). 9248 9249@item 9250Bash implements extended pattern matching features when the @code{extglob} 9251shell option is enabled (@pxref{Pattern Matching}). 9252 9253@item 9254It is possible to have a variable and a function with the same name; 9255@code{sh} does not separate the two name spaces. 9256 9257@item 9258Bash functions are permitted to have local variables using the 9259@code{local} builtin, and thus useful recursive functions may be written 9260(@pxref{Bash Builtins}). 9261 9262@item 9263Variable assignments preceding commands affect only that command, even 9264builtins and functions (@pxref{Environment}). 9265In @code{sh}, all variable assignments 9266preceding commands are global unless the command is executed from the 9267file system. 9268 9269@item 9270Bash performs filename expansion on filenames specified as operands 9271to input and output redirection operators (@pxref{Redirections}). 9272 9273@item 9274Bash contains the @samp{<>} redirection operator, allowing a file to be 9275opened for both reading and writing, and the @samp{&>} redirection 9276operator, for directing standard output and standard error to the same 9277file (@pxref{Redirections}). 9278 9279@item 9280Bash includes the @samp{<<<} redirection operator, allowing a string to 9281be used as the standard input to a command. 9282 9283@item 9284Bash implements the @samp{[n]<&@var{word}} and @samp{[n]>&@var{word}} 9285redirection operators, which move one file descriptor to another. 9286 9287@item 9288Bash treats a number of filenames specially when they are 9289used in redirection operators (@pxref{Redirections}). 9290 9291@item 9292Bash can open network connections to arbitrary machines and services 9293with the redirection operators (@pxref{Redirections}). 9294 9295@item 9296The @code{noclobber} option is available to avoid overwriting existing 9297files with output redirection (@pxref{The Set Builtin}). 9298The @samp{>|} redirection operator may be used to override @code{noclobber}. 9299 9300@item 9301The Bash @code{cd} and @code{pwd} builtins (@pxref{Bourne Shell Builtins}) 9302each take @option{-L} and @option{-P} options to switch between logical and 9303physical modes. 9304 9305@item 9306Bash allows a function to override a builtin with the same name, and provides 9307access to that builtin's functionality within the function via the 9308@code{builtin} and @code{command} builtins (@pxref{Bash Builtins}). 9309 9310@item 9311The @code{command} builtin allows selective disabling of functions 9312when command lookup is performed (@pxref{Bash Builtins}). 9313 9314@item 9315Individual builtins may be enabled or disabled using the @code{enable} 9316builtin (@pxref{Bash Builtins}). 9317 9318@item 9319The Bash @code{exec} builtin takes additional options that allow users 9320to control the contents of the environment passed to the executed 9321command, and what the zeroth argument to the command is to be 9322(@pxref{Bourne Shell Builtins}). 9323 9324@item 9325Shell functions may be exported to children via the environment 9326using @code{export -f} (@pxref{Shell Functions}). 9327 9328@item 9329The Bash @code{export}, @code{readonly}, and @code{declare} builtins can 9330take a @option{-f} option to act on shell functions, a @option{-p} option to 9331display variables with various attributes set in a format that can be 9332used as shell input, a @option{-n} option to remove various variable 9333attributes, and @samp{name=value} arguments to set variable attributes 9334and values simultaneously. 9335 9336@item 9337The Bash @code{hash} builtin allows a name to be associated with 9338an arbitrary filename, even when that filename cannot be found by 9339searching the @env{$PATH}, using @samp{hash -p} 9340(@pxref{Bourne Shell Builtins}). 9341 9342@item 9343Bash includes a @code{help} builtin for quick reference to shell 9344facilities (@pxref{Bash Builtins}). 9345 9346@item 9347The @code{printf} builtin is available to display formatted output 9348(@pxref{Bash Builtins}). 9349 9350@item 9351The Bash @code{read} builtin (@pxref{Bash Builtins}) 9352will read a line ending in @samp{\} with 9353the @option{-r} option, and will use the @env{REPLY} variable as a 9354default if no non-option arguments are supplied. 9355The Bash @code{read} builtin 9356also accepts a prompt string with the @option{-p} option and will use 9357Readline to obtain the line when given the @option{-e} option. 9358The @code{read} builtin also has additional options to control input: 9359the @option{-s} option will turn off echoing of input characters as 9360they are read, the @option{-t} option will allow @code{read} to time out 9361if input does not arrive within a specified number of seconds, the 9362@option{-n} option will allow reading only a specified number of 9363characters rather than a full line, and the @option{-d} option will read 9364until a particular character rather than newline. 9365 9366@item 9367The @code{return} builtin may be used to abort execution of scripts 9368executed with the @code{.} or @code{source} builtins 9369(@pxref{Bourne Shell Builtins}). 9370 9371@item 9372Bash includes the @code{shopt} builtin, for finer control of shell 9373optional capabilities (@pxref{The Shopt Builtin}), and allows these options 9374to be set and unset at shell invocation (@pxref{Invoking Bash}). 9375 9376@item 9377Bash has much more optional behavior controllable with the @code{set} 9378builtin (@pxref{The Set Builtin}). 9379 9380@item 9381The @samp{-x} (@option{xtrace}) option displays commands other than 9382simple commands when performing an execution trace 9383(@pxref{The Set Builtin}). 9384 9385@item 9386The @code{test} builtin (@pxref{Bourne Shell Builtins}) 9387is slightly different, as it implements the @sc{posix} algorithm, 9388which specifies the behavior based on the number of arguments. 9389 9390@item 9391Bash includes the @code{caller} builtin, which displays the context of 9392any active subroutine call (a shell function or a script executed with 9393the @code{.} or @code{source} builtins). This supports the bash 9394debugger. 9395 9396@item 9397The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a 9398@code{DEBUG} pseudo-signal specification, similar to @code{EXIT}. 9399Commands specified with a @code{DEBUG} trap are executed before every 9400simple command, @code{for} command, @code{case} command, 9401@code{select} command, every arithmetic @code{for} command, and before 9402the first command executes in a shell function. 9403The @code{DEBUG} trap is not inherited by shell functions unless the 9404function has been given the @code{trace} attribute or the 9405@code{functrace} option has been enabled using the @code{shopt} builtin. 9406The @code{extdebug} shell option has additional effects on the 9407@code{DEBUG} trap. 9408 9409The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows an 9410@code{ERR} pseudo-signal specification, similar to @code{EXIT} and @code{DEBUG}. 9411Commands specified with an @code{ERR} trap are executed after a simple 9412command fails, with a few exceptions. 9413The @code{ERR} trap is not inherited by shell functions unless the 9414@code{-o errtrace} option to the @code{set} builtin is enabled. 9415 9416The @code{trap} builtin (@pxref{Bourne Shell Builtins}) allows a 9417@code{RETURN} pseudo-signal specification, similar to 9418@code{EXIT} and @code{DEBUG}. 9419Commands specified with an @code{RETURN} trap are executed before 9420execution resumes after a shell function or a shell script executed with 9421@code{.} or @code{source} returns. 9422The @code{RETURN} trap is not inherited by shell functions unless the 9423function has been given the @code{trace} attribute or the 9424@code{functrace} option has been enabled using the @code{shopt} builtin. 9425 9426@item 9427The Bash @code{type} builtin is more extensive and gives more information 9428about the names it finds (@pxref{Bash Builtins}). 9429 9430@item 9431The Bash @code{umask} builtin permits a @option{-p} option to cause 9432the output to be displayed in the form of a @code{umask} command 9433that may be reused as input (@pxref{Bourne Shell Builtins}). 9434 9435@item 9436Bash implements a @code{csh}-like directory stack, and provides the 9437@code{pushd}, @code{popd}, and @code{dirs} builtins to manipulate it 9438(@pxref{The Directory Stack}). 9439Bash also makes the directory stack visible as the value of the 9440@env{DIRSTACK} shell variable. 9441 9442@item 9443Bash interprets special backslash-escaped characters in the prompt 9444strings when interactive (@pxref{Controlling the Prompt}). 9445 9446@item 9447The Bash restricted mode is more useful (@pxref{The Restricted Shell}); 9448the SVR4.2 shell restricted mode is too limited. 9449 9450@item 9451The @code{disown} builtin can remove a job from the internal shell 9452job table (@pxref{Job Control Builtins}) or suppress the sending 9453of @code{SIGHUP} to a job when the shell exits as the result of a 9454@code{SIGHUP}. 9455 9456@item 9457Bash includes a number of features to support a separate debugger for 9458shell scripts. 9459 9460@item 9461The SVR4.2 shell has two privilege-related builtins 9462(@code{mldmode} and @code{priv}) not present in Bash. 9463 9464@item 9465Bash does not have the @code{stop} or @code{newgrp} builtins. 9466 9467@item 9468Bash does not use the @env{SHACCT} variable or perform shell accounting. 9469 9470@item 9471The SVR4.2 @code{sh} uses a @env{TIMEOUT} variable like Bash uses 9472@env{TMOUT}. 9473 9474@end itemize 9475 9476@noindent 9477More features unique to Bash may be found in @ref{Bash Features}. 9478 9479 9480@appendixsec Implementation Differences From The SVR4.2 Shell 9481 9482Since Bash is a completely new implementation, it does not suffer from 9483many of the limitations of the SVR4.2 shell. For instance: 9484 9485@itemize @bullet 9486 9487@item 9488Bash does not fork a subshell when redirecting into or out of 9489a shell control structure such as an @code{if} or @code{while} 9490statement. 9491 9492@item 9493Bash does not allow unbalanced quotes. The SVR4.2 shell will silently 9494insert a needed closing quote at @code{EOF} under certain circumstances. 9495This can be the cause of some hard-to-find errors. 9496 9497@item 9498The SVR4.2 shell uses a baroque memory management scheme based on 9499trapping @code{SIGSEGV}. If the shell is started from a process with 9500@code{SIGSEGV} blocked (e.g., by using the @code{system()} C library 9501function call), it misbehaves badly. 9502 9503@item 9504In a questionable attempt at security, the SVR4.2 shell, 9505when invoked without the @option{-p} option, will alter its real 9506and effective @sc{uid} and @sc{gid} if they are less than some 9507magic threshold value, commonly 100. 9508This can lead to unexpected results. 9509 9510@item 9511The SVR4.2 shell does not allow users to trap @code{SIGSEGV}, 9512@code{SIGALRM}, or @code{SIGCHLD}. 9513 9514@item 9515The SVR4.2 shell does not allow the @env{IFS}, @env{MAILCHECK}, 9516@env{PATH}, @env{PS1}, or @env{PS2} variables to be unset. 9517 9518@item 9519The SVR4.2 shell treats @samp{^} as the undocumented equivalent of 9520@samp{|}. 9521 9522@item 9523Bash allows multiple option arguments when it is invoked (@code{-x -v}); 9524the SVR4.2 shell allows only one option argument (@code{-xv}). In 9525fact, some versions of the shell dump core if the second argument begins 9526with a @samp{-}. 9527 9528@item 9529The SVR4.2 shell exits a script if any builtin fails; Bash exits 9530a script only if one of the @sc{posix} special builtins fails, and 9531only for certain failures, as enumerated in the @sc{posix} standard. 9532 9533@item 9534The SVR4.2 shell behaves differently when invoked as @code{jsh} 9535(it turns on job control). 9536@end itemize 9537 9538@node GNU Free Documentation License 9539@appendix GNU Free Documentation License 9540 9541@include fdl.texi 9542 9543@node Indexes 9544@appendix Indexes 9545 9546@menu 9547* Builtin Index:: Index of Bash builtin commands. 9548* Reserved Word Index:: Index of Bash reserved words. 9549* Variable Index:: Quick reference helps you find the 9550 variable you want. 9551* Function Index:: Index of bindable Readline functions. 9552* Concept Index:: General index for concepts described in 9553 this manual. 9554@end menu 9555 9556@node Builtin Index 9557@appendixsec Index of Shell Builtin Commands 9558@printindex bt 9559 9560@node Reserved Word Index 9561@appendixsec Index of Shell Reserved Words 9562@printindex rw 9563 9564@node Variable Index 9565@appendixsec Parameter and Variable Index 9566@printindex vr 9567 9568@node Function Index 9569@appendixsec Function Index 9570@printindex fn 9571 9572@node Concept Index 9573@appendixsec Concept Index 9574@printindex cp 9575 9576@bye 9577