1This is bash.info, produced by makeinfo version 6.7 from 2bashref.texi. 3 4This text is a brief description of the features that are present in the 5Bash shell (version 5.1, 29 October 2020). 6 7 This is Edition 5.1, last updated 29 October 2020, of 'The GNU Bash 8Reference Manual', for 'Bash', Version 5.1. 9 10 Copyright (C) 1988-2020 Free Software Foundation, Inc. 11 12 Permission is granted to copy, distribute and/or modify this 13 document under the terms of the GNU Free Documentation License, 14 Version 1.3 or any later version published by the Free Software 15 Foundation; with no Invariant Sections, no Front-Cover Texts, and 16 no Back-Cover Texts. A copy of the license is included in the 17 section entitled "GNU Free Documentation License". 18INFO-DIR-SECTION Basics 19START-INFO-DIR-ENTRY 20* Bash: (bash). The GNU Bourne-Again SHell. 21END-INFO-DIR-ENTRY 22 23 24File: bash.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) 25 26Bash Features 27************* 28 29This text is a brief description of the features that are present in the 30Bash shell (version 5.1, 29 October 2020). The Bash home page is 31<http://www.gnu.org/software/bash/>. 32 33 This is Edition 5.1, last updated 29 October 2020, of 'The GNU Bash 34Reference Manual', for 'Bash', Version 5.1. 35 36 Bash contains features that appear in other popular shells, and some 37features that only appear in Bash. Some of the shells that Bash has 38borrowed concepts from are the Bourne Shell ('sh'), the Korn Shell 39('ksh'), and the C-shell ('csh' and its successor, 'tcsh'). The 40following menu breaks the features up into categories, noting which 41features were inspired by other shells and which are specific to Bash. 42 43 This manual is meant as a brief introduction to features found in 44Bash. The Bash manual page should be used as the definitive reference 45on shell behavior. 46 47* Menu: 48 49* Introduction:: An introduction to the shell. 50* Definitions:: Some definitions used in the rest of this 51 manual. 52* Basic Shell Features:: The shell "building blocks". 53* Shell Builtin Commands:: Commands that are a part of the shell. 54* Shell Variables:: Variables used or set by Bash. 55* Bash Features:: Features found only in Bash. 56* Job Control:: What job control is and how Bash allows you 57 to use it. 58* Command Line Editing:: Chapter describing the command line 59 editing features. 60* Using History Interactively:: Command History Expansion 61* Installing Bash:: How to build and install Bash on your system. 62* Reporting Bugs:: How to report bugs in Bash. 63* Major Differences From The Bourne Shell:: A terse list of the differences 64 between Bash and historical 65 versions of /bin/sh. 66* GNU Free Documentation License:: Copying and sharing this documentation. 67* Indexes:: Various indexes for this manual. 68 69 70File: bash.info, Node: Introduction, Next: Definitions, Up: Top 71 721 Introduction 73************** 74 75* Menu: 76 77* What is Bash?:: A short description of Bash. 78* What is a shell?:: A brief introduction to shells. 79 80 81File: bash.info, Node: What is Bash?, Next: What is a shell?, Up: Introduction 82 831.1 What is Bash? 84================= 85 86Bash is the shell, or command language interpreter, for the GNU 87operating system. The name is an acronym for the 'Bourne-Again SHell', 88a pun on Stephen Bourne, the author of the direct ancestor of the 89current Unix shell 'sh', which appeared in the Seventh Edition Bell Labs 90Research version of Unix. 91 92 Bash is largely compatible with 'sh' and incorporates useful features 93from the Korn shell 'ksh' and the C shell 'csh'. It is intended to be a 94conformant implementation of the IEEE POSIX Shell and Tools portion of 95the IEEE POSIX specification (IEEE Standard 1003.1). It offers 96functional improvements over 'sh' for both interactive and programming 97use. 98 99 While the GNU operating system provides other shells, including a 100version of 'csh', Bash is the default shell. Like other GNU software, 101Bash is quite portable. It currently runs on nearly every version of 102Unix and a few other operating systems - independently-supported ports 103exist for MS-DOS, OS/2, and Windows platforms. 104 105 106File: bash.info, Node: What is a shell?, Prev: What is Bash?, Up: Introduction 107 1081.2 What is a shell? 109==================== 110 111At its base, a shell is simply a macro processor that executes commands. 112The term macro processor means functionality where text and symbols are 113expanded to create larger expressions. 114 115 A Unix shell is both a command interpreter and a programming 116language. As a command interpreter, the shell provides the user 117interface to the rich set of GNU utilities. The programming language 118features allow these utilities to be combined. Files containing 119commands can be created, and become commands themselves. These new 120commands have the same status as system commands in directories such as 121'/bin', allowing users or groups to establish custom environments to 122automate their common tasks. 123 124 Shells may be used interactively or non-interactively. In 125interactive mode, they accept input typed from the keyboard. When 126executing non-interactively, shells execute commands read from a file. 127 128 A shell allows execution of GNU commands, both synchronously and 129asynchronously. The shell waits for synchronous commands to complete 130before accepting more input; asynchronous commands continue to execute 131in parallel with the shell while it reads and executes additional 132commands. The "redirection" constructs permit fine-grained control of 133the input and output of those commands. Moreover, the shell allows 134control over the contents of commands' environments. 135 136 Shells also provide a small set of built-in commands ("builtins") 137implementing functionality impossible or inconvenient to obtain via 138separate utilities. For example, 'cd', 'break', 'continue', and 'exec' 139cannot be implemented outside of the shell because they directly 140manipulate the shell itself. The 'history', 'getopts', 'kill', or 'pwd' 141builtins, among others, could be implemented in separate utilities, but 142they are more convenient to use as builtin commands. All of the shell 143builtins are described in subsequent sections. 144 145 While executing commands is essential, most of the power (and 146complexity) of shells is due to their embedded programming languages. 147Like any high-level language, the shell provides variables, flow control 148constructs, quoting, and functions. 149 150 Shells offer features geared specifically for interactive use rather 151than to augment the programming language. These interactive features 152include job control, command line editing, command history and aliases. 153Each of these features is described in this manual. 154 155 156File: bash.info, Node: Definitions, Next: Basic Shell Features, Prev: Introduction, Up: Top 157 1582 Definitions 159************* 160 161These definitions are used throughout the remainder of this manual. 162 163'POSIX' 164 A family of open system standards based on Unix. Bash is primarily 165 concerned with the Shell and Utilities portion of the POSIX 1003.1 166 standard. 167 168'blank' 169 A space or tab character. 170 171'builtin' 172 A command that is implemented internally by the shell itself, 173 rather than by an executable program somewhere in the file system. 174 175'control operator' 176 A 'token' that performs a control function. It is a 'newline' or 177 one of the following: '||', '&&', '&', ';', ';;', ';&', ';;&', '|', 178 '|&', '(', or ')'. 179 180'exit status' 181 The value returned by a command to its caller. The value is 182 restricted to eight bits, so the maximum value is 255. 183 184'field' 185 A unit of text that is the result of one of the shell expansions. 186 After expansion, when executing a command, the resulting fields are 187 used as the command name and arguments. 188 189'filename' 190 A string of characters used to identify a file. 191 192'job' 193 A set of processes comprising a pipeline, and any processes 194 descended from it, that are all in the same process group. 195 196'job control' 197 A mechanism by which users can selectively stop (suspend) and 198 restart (resume) execution of processes. 199 200'metacharacter' 201 A character that, when unquoted, separates words. A metacharacter 202 is a 'space', 'tab', 'newline', or one of the following characters: 203 '|', '&', ';', '(', ')', '<', or '>'. 204 205'name' 206 A 'word' consisting solely of letters, numbers, and underscores, 207 and beginning with a letter or underscore. 'Name's are used as 208 shell variable and function names. Also referred to as an 209 'identifier'. 210 211'operator' 212 A 'control operator' or a 'redirection operator'. *Note 213 Redirections::, for a list of redirection operators. Operators 214 contain at least one unquoted 'metacharacter'. 215 216'process group' 217 A collection of related processes each having the same process 218 group ID. 219 220'process group ID' 221 A unique identifier that represents a 'process group' during its 222 lifetime. 223 224'reserved word' 225 A 'word' that has a special meaning to the shell. Most reserved 226 words introduce shell flow control constructs, such as 'for' and 227 'while'. 228 229'return status' 230 A synonym for 'exit status'. 231 232'signal' 233 A mechanism by which a process may be notified by the kernel of an 234 event occurring in the system. 235 236'special builtin' 237 A shell builtin command that has been classified as special by the 238 POSIX standard. 239 240'token' 241 A sequence of characters considered a single unit by the shell. It 242 is either a 'word' or an 'operator'. 243 244'word' 245 A sequence of characters treated as a unit by the shell. Words may 246 not include unquoted 'metacharacters'. 247 248 249File: bash.info, Node: Basic Shell Features, Next: Shell Builtin Commands, Prev: Definitions, Up: Top 250 2513 Basic Shell Features 252********************** 253 254Bash is an acronym for 'Bourne-Again SHell'. The Bourne shell is the 255traditional Unix shell originally written by Stephen Bourne. All of the 256Bourne shell builtin commands are available in Bash, The rules for 257evaluation and quoting are taken from the POSIX specification for the 258'standard' Unix shell. 259 260 This chapter briefly summarizes the shell's 'building blocks': 261commands, control structures, shell functions, shell parameters, shell 262expansions, redirections, which are a way to direct input and output 263from and to named files, and how the shell executes commands. 264 265* Menu: 266 267* Shell Syntax:: What your input means to the shell. 268* Shell Commands:: The types of commands you can use. 269* Shell Functions:: Grouping commands by name. 270* Shell Parameters:: How the shell stores values. 271* Shell Expansions:: How Bash expands parameters and the various 272 expansions available. 273* Redirections:: A way to control where input and output go. 274* Executing Commands:: What happens when you run a command. 275* Shell Scripts:: Executing files of shell commands. 276 277 278File: bash.info, Node: Shell Syntax, Next: Shell Commands, Up: Basic Shell Features 279 2803.1 Shell Syntax 281================ 282 283* Menu: 284 285* Shell Operation:: The basic operation of the shell. 286* Quoting:: How to remove the special meaning from characters. 287* Comments:: How to specify comments. 288 289When the shell reads input, it proceeds through a sequence of 290operations. If the input indicates the beginning of a comment, the 291shell ignores the comment symbol ('#'), and the rest of that line. 292 293 Otherwise, roughly speaking, the shell reads its input and divides 294the input into words and operators, employing the quoting rules to 295select which meanings to assign various words and characters. 296 297 The shell then parses these tokens into commands and other 298constructs, removes the special meaning of certain words or characters, 299expands others, redirects input and output as needed, executes the 300specified command, waits for the command's exit status, and makes that 301exit status available for further inspection or processing. 302 303 304File: bash.info, Node: Shell Operation, Next: Quoting, Up: Shell Syntax 305 3063.1.1 Shell Operation 307--------------------- 308 309The following is a brief description of the shell's operation when it 310reads and executes a command. Basically, the shell does the following: 311 312 1. Reads its input from a file (*note Shell Scripts::), from a string 313 supplied as an argument to the '-c' invocation option (*note 314 Invoking Bash::), or from the user's terminal. 315 316 2. Breaks the input into words and operators, obeying the quoting 317 rules described in *note Quoting::. These tokens are separated by 318 'metacharacters'. Alias expansion is performed by this step (*note 319 Aliases::). 320 321 3. Parses the tokens into simple and compound commands (*note Shell 322 Commands::). 323 324 4. Performs the various shell expansions (*note Shell Expansions::), 325 breaking the expanded tokens into lists of filenames (*note 326 Filename Expansion::) and commands and arguments. 327 328 5. Performs any necessary redirections (*note Redirections::) and 329 removes the redirection operators and their operands from the 330 argument list. 331 332 6. Executes the command (*note Executing Commands::). 333 334 7. Optionally waits for the command to complete and collects its exit 335 status (*note Exit Status::). 336 337 338File: bash.info, Node: Quoting, Next: Comments, Prev: Shell Operation, Up: Shell Syntax 339 3403.1.2 Quoting 341------------- 342 343* Menu: 344 345* Escape Character:: How to remove the special meaning from a single 346 character. 347* Single Quotes:: How to inhibit all interpretation of a sequence 348 of characters. 349* Double Quotes:: How to suppress most of the interpretation of a 350 sequence of characters. 351* ANSI-C Quoting:: How to expand ANSI-C sequences in quoted strings. 352* Locale Translation:: How to translate strings into different languages. 353 354Quoting is used to remove the special meaning of certain characters or 355words to the shell. Quoting can be used to disable special treatment 356for special characters, to prevent reserved words from being recognized 357as such, and to prevent parameter expansion. 358 359 Each of the shell metacharacters (*note Definitions::) has special 360meaning to the shell and must be quoted if it is to represent itself. 361When the command history expansion facilities are being used (*note 362History Interaction::), the HISTORY EXPANSION character, usually '!', 363must be quoted to prevent history expansion. *Note Bash History 364Facilities::, for more details concerning history expansion. 365 366 There are three quoting mechanisms: the ESCAPE CHARACTER, single 367quotes, and double quotes. 368 369 370File: bash.info, Node: Escape Character, Next: Single Quotes, Up: Quoting 371 3723.1.2.1 Escape Character 373........................ 374 375A non-quoted backslash '\' is the Bash escape character. It preserves 376the literal value of the next character that follows, with the exception 377of 'newline'. If a '\newline' pair appears, and the backslash itself is 378not quoted, the '\newline' is treated as a line continuation (that is, 379it is removed from the input stream and effectively ignored). 380 381 382File: bash.info, Node: Single Quotes, Next: Double Quotes, Prev: Escape Character, Up: Quoting 383 3843.1.2.2 Single Quotes 385..................... 386 387Enclosing characters in single quotes (''') preserves the literal value 388of each character within the quotes. A single quote may not occur 389between single quotes, even when preceded by a backslash. 390 391 392File: bash.info, Node: Double Quotes, Next: ANSI-C Quoting, Prev: Single Quotes, Up: Quoting 393 3943.1.2.3 Double Quotes 395..................... 396 397Enclosing characters in double quotes ('"') preserves the literal value 398of all characters within the quotes, with the exception of '$', '`', 399'\', and, when history expansion is enabled, '!'. When the shell is in 400POSIX mode (*note Bash POSIX Mode::), the '!' has no special meaning 401within double quotes, even when history expansion is enabled. The 402characters '$' and '`' retain their special meaning within double quotes 403(*note Shell Expansions::). The backslash retains its special meaning 404only when followed by one of the following characters: '$', '`', '"', 405'\', or 'newline'. Within double quotes, backslashes that are followed 406by one of these characters are removed. Backslashes preceding 407characters without a special meaning are left unmodified. A double 408quote may be quoted within double quotes by preceding it with a 409backslash. If enabled, history expansion will be performed unless an 410'!' appearing in double quotes is escaped using a backslash. The 411backslash preceding the '!' is not removed. 412 413 The special parameters '*' and '@' have special meaning when in 414double quotes (*note Shell Parameter Expansion::). 415 416 417File: bash.info, Node: ANSI-C Quoting, Next: Locale Translation, Prev: Double Quotes, Up: Quoting 418 4193.1.2.4 ANSI-C Quoting 420...................... 421 422Words of the form '$'STRING'' are treated specially. The word expands 423to STRING, with backslash-escaped characters replaced as specified by 424the ANSI C standard. Backslash escape sequences, if present, are 425decoded as follows: 426 427'\a' 428 alert (bell) 429'\b' 430 backspace 431'\e' 432'\E' 433 an escape character (not ANSI C) 434'\f' 435 form feed 436'\n' 437 newline 438'\r' 439 carriage return 440'\t' 441 horizontal tab 442'\v' 443 vertical tab 444'\\' 445 backslash 446'\'' 447 single quote 448'\"' 449 double quote 450'\?' 451 question mark 452'\NNN' 453 the eight-bit character whose value is the octal value NNN (one to 454 three octal digits) 455'\xHH' 456 the eight-bit character whose value is the hexadecimal value HH 457 (one or two hex digits) 458'\uHHHH' 459 the Unicode (ISO/IEC 10646) character whose value is the 460 hexadecimal value HHHH (one to four hex digits) 461'\UHHHHHHHH' 462 the Unicode (ISO/IEC 10646) character whose value is the 463 hexadecimal value HHHHHHHH (one to eight hex digits) 464'\cX' 465 a control-X character 466 467The expanded result is single-quoted, as if the dollar sign had not been 468present. 469 470 471File: bash.info, Node: Locale Translation, Prev: ANSI-C Quoting, Up: Quoting 472 4733.1.2.5 Locale-Specific Translation 474................................... 475 476A double-quoted string preceded by a dollar sign ('$') will cause the 477string to be translated according to the current locale. The GETTEXT 478infrastructure performs the message catalog lookup and translation, 479using the 'LC_MESSAGES' and 'TEXTDOMAIN' shell variables, as explained 480below. See the gettext documentation for additional details. If the 481current locale is 'C' or 'POSIX', or if there are no translations 482available, the dollar sign is ignored. If the string is translated and 483replaced, the replacement is double-quoted. 484 485 Some systems use the message catalog selected by the 'LC_MESSAGES' 486shell variable. Others create the name of the message catalog from the 487value of the 'TEXTDOMAIN' shell variable, possibly adding a suffix of 488'.mo'. If you use the 'TEXTDOMAIN' variable, you may need to set the 489'TEXTDOMAINDIR' variable to the location of the message catalog files. 490Still others use both variables in this fashion: 491'TEXTDOMAINDIR'/'LC_MESSAGES'/LC_MESSAGES/'TEXTDOMAIN'.mo. 492 493 494File: bash.info, Node: Comments, Prev: Quoting, Up: Shell Syntax 495 4963.1.3 Comments 497-------------- 498 499In a non-interactive shell, or an interactive shell in which the 500'interactive_comments' option to the 'shopt' builtin is enabled (*note 501The Shopt Builtin::), a word beginning with '#' causes that word and all 502remaining characters on that line to be ignored. An interactive shell 503without the 'interactive_comments' option enabled does not allow 504comments. The 'interactive_comments' option is on by default in 505interactive shells. *Note Interactive Shells::, for a description of 506what makes a shell interactive. 507 508 509File: bash.info, Node: Shell Commands, Next: Shell Functions, Prev: Shell Syntax, Up: Basic Shell Features 510 5113.2 Shell Commands 512================== 513 514A simple shell command such as 'echo a b c' consists of the command 515itself followed by arguments, separated by spaces. 516 517 More complex shell commands are composed of simple commands arranged 518together in a variety of ways: in a pipeline in which the output of one 519command becomes the input of a second, in a loop or conditional 520construct, or in some other grouping. 521 522* Menu: 523 524* Reserved Words:: Words that have special meaning to the shell. 525* Simple Commands:: The most common type of command. 526* Pipelines:: Connecting the input and output of several 527 commands. 528* Lists:: How to execute commands sequentially. 529* Compound Commands:: Shell commands for control flow. 530* Coprocesses:: Two-way communication between commands. 531* GNU Parallel:: Running commands in parallel. 532 533 534File: bash.info, Node: Reserved Words, Next: Simple Commands, Up: Shell Commands 535 5363.2.1 Reserved Words 537-------------------- 538 539Reserved words are words that have special meaning to the shell. They 540are used to begin and end the shell's compound commands. 541 542 The following words are recognized as reserved when unquoted and the 543first word of a command (see below for exceptions): 544 545'if' 'then' 'elif' 'else' 'fi' 'time' 546'for' 'in' 'until' 'while' 'do' 'done' 547'case' 'esac' 'coproc''select''function' 548'{' '}' '[[' ']]' '!' 549 550'in' is recognized as a reserved word if it is the third word of a 551'case' or 'select' command. 'in' and 'do' are recognized as reserved 552words if they are the third word in a 'for' command. 553 554 555File: bash.info, Node: Simple Commands, Next: Pipelines, Prev: Reserved Words, Up: Shell Commands 556 5573.2.2 Simple Commands 558--------------------- 559 560A simple command is the kind of command encountered most often. It's 561just a sequence of words separated by 'blank's, terminated by one of the 562shell's control operators (*note Definitions::). The first word 563generally specifies a command to be executed, with the rest of the words 564being that command's arguments. 565 566 The return status (*note Exit Status::) of a simple command is its 567exit status as provided by the POSIX 1003.1 'waitpid' function, or 128+N 568if the command was terminated by signal N. 569 570 571File: bash.info, Node: Pipelines, Next: Lists, Prev: Simple Commands, Up: Shell Commands 572 5733.2.3 Pipelines 574--------------- 575 576A 'pipeline' is a sequence of one or more commands separated by one of 577the control operators '|' or '|&'. 578 579 The format for a pipeline is 580 [time [-p]] [!] COMMAND1 [ | or |& COMMAND2 ] ... 581 582The output of each command in the pipeline is connected via a pipe to 583the input of the next command. That is, each command reads the previous 584command's output. This connection is performed before any redirections 585specified by the command. 586 587 If '|&' is used, COMMAND1's standard error, in addition to its 588standard output, is connected to COMMAND2's standard input through the 589pipe; it is shorthand for '2>&1 |'. This implicit redirection of the 590standard error to the standard output is performed after any 591redirections specified by the command. 592 593 The reserved word 'time' causes timing statistics to be printed for 594the pipeline once it finishes. The statistics currently consist of 595elapsed (wall-clock) time and user and system time consumed by the 596command's execution. The '-p' option changes the output format to that 597specified by POSIX. When the shell is in POSIX mode (*note Bash POSIX 598Mode::), it does not recognize 'time' as a reserved word if the next 599token begins with a '-'. The 'TIMEFORMAT' variable may be set to a 600format string that specifies how the timing information should be 601displayed. *Note Bash Variables::, for a description of the available 602formats. The use of 'time' as a reserved word permits the timing of 603shell builtins, shell functions, and pipelines. An external 'time' 604command cannot time these easily. 605 606 When the shell is in POSIX mode (*note Bash POSIX Mode::), 'time' may 607be followed by a newline. In this case, the shell displays the total 608user and system time consumed by the shell and its children. The 609'TIMEFORMAT' variable may be used to specify the format of the time 610information. 611 612 If the pipeline is not executed asynchronously (*note Lists::), the 613shell waits for all commands in the pipeline to complete. 614 615 Each command in a pipeline is executed in its own subshell, which is 616a separate process (*note Command Execution Environment::). If the 617'lastpipe' option is enabled using the 'shopt' builtin (*note The Shopt 618Builtin::), the last element of a pipeline may be run by the shell 619process. 620 621 The exit status of a pipeline is the exit status of the last command 622in the pipeline, unless the 'pipefail' option is enabled (*note The Set 623Builtin::). If 'pipefail' is enabled, the pipeline's return status is 624the value of the last (rightmost) command to exit with a non-zero 625status, or zero if all commands exit successfully. If the reserved word 626'!' precedes the pipeline, the exit status is the logical negation of 627the exit status as described above. The shell waits for all commands in 628the pipeline to terminate before returning a value. 629 630 631File: bash.info, Node: Lists, Next: Compound Commands, Prev: Pipelines, Up: Shell Commands 632 6333.2.4 Lists of Commands 634----------------------- 635 636A 'list' is a sequence of one or more pipelines separated by one of the 637operators ';', '&', '&&', or '||', and optionally terminated by one of 638';', '&', or a 'newline'. 639 640 Of these list operators, '&&' and '||' have equal precedence, 641followed by ';' and '&', which have equal precedence. 642 643 A sequence of one or more newlines may appear in a 'list' to delimit 644commands, equivalent to a semicolon. 645 646 If a command is terminated by the control operator '&', the shell 647executes the command asynchronously in a subshell. This is known as 648executing the command in the BACKGROUND, and these are referred to as 649ASYNCHRONOUS commands. The shell does not wait for the command to 650finish, and the return status is 0 (true). When job control is not 651active (*note Job Control::), the standard input for asynchronous 652commands, in the absence of any explicit redirections, is redirected 653from '/dev/null'. 654 655 Commands separated by a ';' are executed sequentially; the shell 656waits for each command to terminate in turn. The return status is the 657exit status of the last command executed. 658 659 AND and OR lists are sequences of one or more pipelines separated by 660the control operators '&&' and '||', respectively. AND and OR lists are 661executed with left associativity. 662 663 An AND list has the form 664 COMMAND1 && COMMAND2 665 666COMMAND2 is executed if, and only if, COMMAND1 returns an exit status of 667zero (success). 668 669 An OR list has the form 670 COMMAND1 || COMMAND2 671 672COMMAND2 is executed if, and only if, COMMAND1 returns a non-zero exit 673status. 674 675 The return status of AND and OR lists is the exit status of the last 676command executed in the list. 677 678 679File: bash.info, Node: Compound Commands, Next: Coprocesses, Prev: Lists, Up: Shell Commands 680 6813.2.5 Compound Commands 682----------------------- 683 684* Menu: 685 686* Looping Constructs:: Shell commands for iterative action. 687* Conditional Constructs:: Shell commands for conditional execution. 688* Command Grouping:: Ways to group commands. 689 690Compound commands are the shell programming language constructs. Each 691construct begins with a reserved word or control operator and is 692terminated by a corresponding reserved word or operator. Any 693redirections (*note Redirections::) associated with a compound command 694apply to all commands within that compound command unless explicitly 695overridden. 696 697 In most cases a list of commands in a compound command's description 698may be separated from the rest of the command by one or more newlines, 699and may be followed by a newline in place of a semicolon. 700 701 Bash provides looping constructs, conditional commands, and 702mechanisms to group commands and execute them as a unit. 703 704 705File: bash.info, Node: Looping Constructs, Next: Conditional Constructs, Up: Compound Commands 706 7073.2.5.1 Looping Constructs 708.......................... 709 710Bash supports the following looping constructs. 711 712 Note that wherever a ';' appears in the description of a command's 713syntax, it may be replaced with one or more newlines. 714 715'until' 716 The syntax of the 'until' command is: 717 718 until TEST-COMMANDS; do CONSEQUENT-COMMANDS; done 719 720 Execute CONSEQUENT-COMMANDS as long as TEST-COMMANDS has an exit 721 status which is not zero. The return status is the exit status of 722 the last command executed in CONSEQUENT-COMMANDS, or zero if none 723 was executed. 724 725'while' 726 The syntax of the 'while' command is: 727 728 while TEST-COMMANDS; do CONSEQUENT-COMMANDS; done 729 730 Execute CONSEQUENT-COMMANDS as long as TEST-COMMANDS has an exit 731 status of zero. The return status is the exit status of the last 732 command executed in CONSEQUENT-COMMANDS, or zero if none was 733 executed. 734 735'for' 736 The syntax of the 'for' command is: 737 738 for NAME [ [in [WORDS ...] ] ; ] do COMMANDS; done 739 740 Expand WORDS (*note Shell Expansions::), and execute COMMANDS once 741 for each member in the resultant list, with NAME bound to the 742 current member. If 'in WORDS' is not present, the 'for' command 743 executes the COMMANDS once for each positional parameter that is 744 set, as if 'in "$@"' had been specified (*note Special 745 Parameters::). 746 747 The return status is the exit status of the last command that 748 executes. If there are no items in the expansion of WORDS, no 749 commands are executed, and the return status is zero. 750 751 An alternate form of the 'for' command is also supported: 752 753 for (( EXPR1 ; EXPR2 ; EXPR3 )) ; do COMMANDS ; done 754 755 First, the arithmetic expression EXPR1 is evaluated according to 756 the rules described below (*note Shell Arithmetic::). The 757 arithmetic expression EXPR2 is then evaluated repeatedly until it 758 evaluates to zero. Each time EXPR2 evaluates to a non-zero value, 759 COMMANDS are executed and the arithmetic expression EXPR3 is 760 evaluated. If any expression is omitted, it behaves as if it 761 evaluates to 1. The return value is the exit status of the last 762 command in COMMANDS that is executed, or false if any of the 763 expressions is invalid. 764 765 The 'break' and 'continue' builtins (*note Bourne Shell Builtins::) 766may be used to control loop execution. 767 768 769File: bash.info, Node: Conditional Constructs, Next: Command Grouping, Prev: Looping Constructs, Up: Compound Commands 770 7713.2.5.2 Conditional Constructs 772.............................. 773 774'if' 775 The syntax of the 'if' command is: 776 777 if TEST-COMMANDS; then 778 CONSEQUENT-COMMANDS; 779 [elif MORE-TEST-COMMANDS; then 780 MORE-CONSEQUENTS;] 781 [else ALTERNATE-CONSEQUENTS;] 782 fi 783 784 The TEST-COMMANDS list is executed, and if its return status is 785 zero, the CONSEQUENT-COMMANDS list is executed. If TEST-COMMANDS 786 returns a non-zero status, each 'elif' list is executed in turn, 787 and if its exit status is zero, the corresponding MORE-CONSEQUENTS 788 is executed and the command completes. If 'else 789 ALTERNATE-CONSEQUENTS' is present, and the final command in the 790 final 'if' or 'elif' clause has a non-zero exit status, then 791 ALTERNATE-CONSEQUENTS is executed. The return status is the exit 792 status of the last command executed, or zero if no condition tested 793 true. 794 795'case' 796 The syntax of the 'case' command is: 797 798 case WORD in 799 [ [(] PATTERN [| PATTERN]...) COMMAND-LIST ;;]... 800 esac 801 802 'case' will selectively execute the COMMAND-LIST corresponding to 803 the first PATTERN that matches WORD. The match is performed 804 according to the rules described below in *note Pattern Matching::. 805 If the 'nocasematch' shell option (see the description of 'shopt' 806 in *note The Shopt Builtin::) is enabled, the match is performed 807 without regard to the case of alphabetic characters. The '|' is 808 used to separate multiple patterns, and the ')' operator terminates 809 a pattern list. A list of patterns and an associated command-list 810 is known as a CLAUSE. 811 812 Each clause must be terminated with ';;', ';&', or ';;&'. The WORD 813 undergoes tilde expansion, parameter expansion, command 814 substitution, arithmetic expansion, and quote removal (*note Shell 815 Parameter Expansion::) before matching is attempted. Each PATTERN 816 undergoes tilde expansion, parameter expansion, command 817 substitution, and arithmetic expansion. 818 819 There may be an arbitrary number of 'case' clauses, each terminated 820 by a ';;', ';&', or ';;&'. The first pattern that matches 821 determines the command-list that is executed. It's a common idiom 822 to use '*' as the final pattern to define the default case, since 823 that pattern will always match. 824 825 Here is an example using 'case' in a script that could be used to 826 describe one interesting feature of an animal: 827 828 echo -n "Enter the name of an animal: " 829 read ANIMAL 830 echo -n "The $ANIMAL has " 831 case $ANIMAL in 832 horse | dog | cat) echo -n "four";; 833 man | kangaroo ) echo -n "two";; 834 *) echo -n "an unknown number of";; 835 esac 836 echo " legs." 837 838 839 If the ';;' operator is used, no subsequent matches are attempted 840 after the first pattern match. Using ';&' in place of ';;' causes 841 execution to continue with the COMMAND-LIST associated with the 842 next clause, if any. Using ';;&' in place of ';;' causes the shell 843 to test the patterns in the next clause, if any, and execute any 844 associated COMMAND-LIST on a successful match, continuing the case 845 statement execution as if the pattern list had not matched. 846 847 The return status is zero if no PATTERN is matched. Otherwise, the 848 return status is the exit status of the COMMAND-LIST executed. 849 850'select' 851 852 The 'select' construct allows the easy generation of menus. It has 853 almost the same syntax as the 'for' command: 854 855 select NAME [in WORDS ...]; do COMMANDS; done 856 857 The list of words following 'in' is expanded, generating a list of 858 items. The set of expanded words is printed on the standard error 859 output stream, each preceded by a number. If the 'in WORDS' is 860 omitted, the positional parameters are printed, as if 'in "$@"' had 861 been specified. The 'PS3' prompt is then displayed and a line is 862 read from the standard input. If the line consists of a number 863 corresponding to one of the displayed words, then the value of NAME 864 is set to that word. If the line is empty, the words and prompt 865 are displayed again. If 'EOF' is read, the 'select' command 866 completes. Any other value read causes NAME to be set to null. 867 The line read is saved in the variable 'REPLY'. 868 869 The COMMANDS are executed after each selection until a 'break' 870 command is executed, at which point the 'select' command completes. 871 872 Here is an example that allows the user to pick a filename from the 873 current directory, and displays the name and index of the file 874 selected. 875 876 select fname in *; 877 do 878 echo you picked $fname \($REPLY\) 879 break; 880 done 881 882'((...))' 883 (( EXPRESSION )) 884 885 The arithmetic EXPRESSION is evaluated according to the rules 886 described below (*note Shell Arithmetic::). If the value of the 887 expression is non-zero, the return status is 0; otherwise the 888 return status is 1. This is exactly equivalent to 889 let "EXPRESSION" 890 *Note Bash Builtins::, for a full description of the 'let' builtin. 891 892'[[...]]' 893 [[ EXPRESSION ]] 894 895 Return a status of 0 or 1 depending on the evaluation of the 896 conditional expression EXPRESSION. Expressions are composed of the 897 primaries described below in *note Bash Conditional Expressions::. 898 Word splitting and filename expansion are not performed on the 899 words between the '[[' and ']]'; tilde expansion, parameter and 900 variable expansion, arithmetic expansion, command substitution, 901 process substitution, and quote removal are performed. Conditional 902 operators such as '-f' must be unquoted to be recognized as 903 primaries. 904 905 When used with '[[', the '<' and '>' operators sort 906 lexicographically using the current locale. 907 908 When the '==' and '!=' operators are used, the string to the right 909 of the operator is considered a pattern and matched according to 910 the rules described below in *note Pattern Matching::, as if the 911 'extglob' shell option were enabled. The '=' operator is identical 912 to '=='. If the 'nocasematch' shell option (see the description of 913 'shopt' in *note The Shopt Builtin::) is enabled, the match is 914 performed without regard to the case of alphabetic characters. The 915 return value is 0 if the string matches ('==') or does not match 916 ('!=') the pattern, and 1 otherwise. Any part of the pattern may 917 be quoted to force the quoted portion to be matched as a string. 918 919 An additional binary operator, '=~', is available, with the same 920 precedence as '==' and '!='. When it is used, the string to the 921 right of the operator is considered a POSIX extended regular 922 expression and matched accordingly (using the POSIX 'regcomp' and 923 'regexec' interfaces usually described in regex(3)). The return 924 value is 0 if the string matches the pattern, and 1 otherwise. If 925 the regular expression is syntactically incorrect, the conditional 926 expression's return value is 2. If the 'nocasematch' shell option 927 (see the description of 'shopt' in *note The Shopt Builtin::) is 928 enabled, the match is performed without regard to the case of 929 alphabetic characters. Any part of the pattern may be quoted to 930 force the quoted portion to be matched as a string. Bracket 931 expressions in regular expressions must be treated carefully, since 932 normal quoting characters lose their meanings between brackets. If 933 the pattern is stored in a shell variable, quoting the variable 934 expansion forces the entire pattern to be matched as a string. 935 936 The pattern will match if it matches any part of the string. 937 Anchor the pattern using the '^' and '$' regular expression 938 operators to force it to match the entire string. The array 939 variable 'BASH_REMATCH' records which parts of the string matched 940 the pattern. The element of 'BASH_REMATCH' with index 0 contains 941 the portion of the string matching the entire regular expression. 942 Substrings matched by parenthesized subexpressions within the 943 regular expression are saved in the remaining 'BASH_REMATCH' 944 indices. The element of 'BASH_REMATCH' with index N is the portion 945 of the string matching the Nth parenthesized subexpression. 946 947 For example, the following will match a line (stored in the shell 948 variable LINE) if there is a sequence of characters anywhere in the 949 value consisting of any number, including zero, of characters in 950 the 'space' character class, zero or one instances of 'a', then a 951 'b': 952 [[ $line =~ [[:space:]]*(a)?b ]] 953 954 That means values like 'aab' and ' aaaaaab' will match, as will a 955 line containing a 'b' anywhere in its value. 956 957 Storing the regular expression in a shell variable is often a 958 useful way to avoid problems with quoting characters that are 959 special to the shell. It is sometimes difficult to specify a 960 regular expression literally without using quotes, or to keep track 961 of the quoting used by regular expressions while paying attention 962 to the shell's quote removal. Using a shell variable to store the 963 pattern decreases these problems. For example, the following is 964 equivalent to the above: 965 pattern='[[:space:]]*(a)?b' 966 [[ $line =~ $pattern ]] 967 968 If you want to match a character that's special to the regular 969 expression grammar, it has to be quoted to remove its special 970 meaning. This means that in the pattern 'xxx.txt', the '.' matches 971 any character in the string (its usual regular expression meaning), 972 but in the pattern '"xxx.txt"' it can only match a literal '.'. 973 Shell programmers should take special care with backslashes, since 974 backslashes are used both by the shell and regular expressions to 975 remove the special meaning from the following character. The 976 following two sets of commands are _not_ equivalent: 977 pattern='\.' 978 979 [[ . =~ $pattern ]] 980 [[ . =~ \. ]] 981 982 [[ . =~ "$pattern" ]] 983 [[ . =~ '\.' ]] 984 985 The first two matches will succeed, but the second two will not, 986 because in the second two the backslash will be part of the pattern 987 to be matched. In the first two examples, the backslash removes 988 the special meaning from '.', so the literal '.' matches. If the 989 string in the first examples were anything other than '.', say 'a', 990 the pattern would not match, because the quoted '.' in the pattern 991 loses its special meaning of matching any single character. 992 993 Expressions may be combined using the following operators, listed 994 in decreasing order of precedence: 995 996 '( EXPRESSION )' 997 Returns the value of EXPRESSION. This may be used to override 998 the normal precedence of operators. 999 1000 '! EXPRESSION' 1001 True if EXPRESSION is false. 1002 1003 'EXPRESSION1 && EXPRESSION2' 1004 True if both EXPRESSION1 and EXPRESSION2 are true. 1005 1006 'EXPRESSION1 || EXPRESSION2' 1007 True if either EXPRESSION1 or EXPRESSION2 is true. 1008 1009 The '&&' and '||' operators do not evaluate EXPRESSION2 if the 1010 value of EXPRESSION1 is sufficient to determine the return value of 1011 the entire conditional expression. 1012 1013 1014File: bash.info, Node: Command Grouping, Prev: Conditional Constructs, Up: Compound Commands 1015 10163.2.5.3 Grouping Commands 1017......................... 1018 1019Bash provides two ways to group a list of commands to be executed as a 1020unit. When commands are grouped, redirections may be applied to the 1021entire command list. For example, the output of all the commands in the 1022list may be redirected to a single stream. 1023 1024'()' 1025 ( LIST ) 1026 1027 Placing a list of commands between parentheses causes a subshell 1028 environment to be created (*note Command Execution Environment::), 1029 and each of the commands in LIST to be executed in that subshell. 1030 Since the LIST is executed in a subshell, variable assignments do 1031 not remain in effect after the subshell completes. 1032 1033'{}' 1034 { LIST; } 1035 1036 Placing a list of commands between curly braces causes the list to 1037 be executed in the current shell context. No subshell is created. 1038 The semicolon (or newline) following LIST is required. 1039 1040 In addition to the creation of a subshell, there is a subtle 1041difference between these two constructs due to historical reasons. The 1042braces are 'reserved words', so they must be separated from the LIST by 1043'blank's or other shell metacharacters. The parentheses are 1044'operators', and are recognized as separate tokens by the shell even if 1045they are not separated from the LIST by whitespace. 1046 1047 The exit status of both of these constructs is the exit status of 1048LIST. 1049 1050 1051File: bash.info, Node: Coprocesses, Next: GNU Parallel, Prev: Compound Commands, Up: Shell Commands 1052 10533.2.6 Coprocesses 1054----------------- 1055 1056A 'coprocess' is a shell command preceded by the 'coproc' reserved word. 1057A coprocess is executed asynchronously in a subshell, as if the command 1058had been terminated with the '&' control operator, with a two-way pipe 1059established between the executing shell and the coprocess. 1060 1061 The format for a coprocess is: 1062 coproc [NAME] COMMAND [REDIRECTIONS] 1063 1064This creates a coprocess named NAME. If NAME is not supplied, the 1065default name is COPROC. NAME must not be supplied if COMMAND is a 1066simple command (*note Simple Commands::); otherwise, it is interpreted 1067as the first word of the simple command. 1068 1069 When the coprocess is executed, the shell creates an array variable 1070(*note Arrays::) named 'NAME' in the context of the executing shell. 1071The standard output of COMMAND is connected via a pipe to a file 1072descriptor in the executing shell, and that file descriptor is assigned 1073to 'NAME'[0]. The standard input of COMMAND is connected via a pipe to 1074a file descriptor in the executing shell, and that file descriptor is 1075assigned to 'NAME'[1]. This pipe is established before any redirections 1076specified by the command (*note Redirections::). The file descriptors 1077can be utilized as arguments to shell commands and redirections using 1078standard word expansions. Other than those created to execute command 1079and process substitutions, the file descriptors are not available in 1080subshells. 1081 1082 The process ID of the shell spawned to execute the coprocess is 1083available as the value of the variable 'NAME'_PID. The 'wait' builtin 1084command may be used to wait for the coprocess to terminate. 1085 1086 Since the coprocess is created as an asynchronous command, the 1087'coproc' command always returns success. The return status of a 1088coprocess is the exit status of COMMAND. 1089 1090 1091File: bash.info, Node: GNU Parallel, Prev: Coprocesses, Up: Shell Commands 1092 10933.2.7 GNU Parallel 1094------------------ 1095 1096There are ways to run commands in parallel that are not built into Bash. 1097GNU Parallel is a tool to do just that. 1098 1099 GNU Parallel, as its name suggests, can be used to build and run 1100commands in parallel. You may run the same command with different 1101arguments, whether they are filenames, usernames, hostnames, or lines 1102read from files. GNU Parallel provides shorthand references to many of 1103the most common operations (input lines, various portions of the input 1104line, different ways to specify the input source, and so on). Parallel 1105can replace 'xargs' or feed commands from its input sources to several 1106different instances of Bash. 1107 1108 For a complete description, refer to the GNU Parallel documentation. 1109A few examples should provide a brief introduction to its use. 1110 1111 For example, it is easy to replace 'xargs' to gzip all html files in 1112the current directory and its subdirectories: 1113 find . -type f -name '*.html' -print | parallel gzip 1114If you need to protect special characters such as newlines in file 1115names, use find's '-print0' option and parallel's '-0' option. 1116 1117 You can use Parallel to move files from the current directory when 1118the number of files is too large to process with one 'mv' invocation: 1119 printf '%s\n' * | parallel mv {} destdir 1120 1121 As you can see, the {} is replaced with each line read from standard 1122input. While using 'ls' will work in most instances, it is not 1123sufficient to deal with all filenames. 'printf' is a shell builtin, and 1124therefore is not subject to the kernel's limit on the number of 1125arguments to a program, so you can use '*' (but see below about the 1126'dotglob' shell option). If you need to accommodate special characters 1127in filenames, you can use 1128 1129 printf '%s\0' * | parallel -0 mv {} destdir 1130 1131as alluded to above. 1132 1133 This will run as many 'mv' commands as there are files in the current 1134directory. You can emulate a parallel 'xargs' by adding the '-X' 1135option: 1136 printf '%s\0' * | parallel -0 -X mv {} destdir 1137 1138 (You may have to modify the pattern if you have the 'dotglob' option 1139enabled.) 1140 1141 GNU Parallel can replace certain common idioms that operate on lines 1142read from a file (in this case, filenames listed one per line): 1143 while IFS= read -r x; do 1144 do-something1 "$x" "config-$x" 1145 do-something2 < "$x" 1146 done < file | process-output 1147 1148with a more compact syntax reminiscent of lambdas: 1149 cat list | parallel "do-something1 {} config-{} ; do-something2 < {}" | 1150 process-output 1151 1152 Parallel provides a built-in mechanism to remove filename extensions, 1153which lends itself to batch file transformations or renaming: 1154 ls *.gz | parallel -j+0 "zcat {} | bzip2 >{.}.bz2 && rm {}" 1155This will recompress all files in the current directory with names 1156ending in .gz using bzip2, running one job per CPU (-j+0) in parallel. 1157(We use 'ls' for brevity here; using 'find' as above is more robust in 1158the face of filenames containing unexpected characters.) Parallel can 1159take arguments from the command line; the above can also be written as 1160 1161 parallel "zcat {} | bzip2 >{.}.bz2 && rm {}" ::: *.gz 1162 1163 If a command generates output, you may want to preserve the input 1164order in the output. For instance, the following command 1165 { 1166 echo foss.org.my ; 1167 echo debian.org ; 1168 echo freenetproject.org ; 1169 } | parallel traceroute 1170will display as output the traceroute invocation that finishes first. 1171Adding the '-k' option 1172 { 1173 echo foss.org.my ; 1174 echo debian.org ; 1175 echo freenetproject.org ; 1176 } | parallel -k traceroute 1177will ensure that the output of 'traceroute foss.org.my' is displayed 1178first. 1179 1180 Finally, Parallel can be used to run a sequence of shell commands in 1181parallel, similar to 'cat file | bash'. It is not uncommon to take a 1182list of filenames, create a series of shell commands to operate on them, 1183and feed that list of commands to a shell. Parallel can speed this up. 1184Assuming that 'file' contains a list of shell commands, one per line, 1185 1186 parallel -j 10 < file 1187 1188will evaluate the commands using the shell (since no explicit command is 1189supplied as an argument), in blocks of ten shell jobs at a time. 1190 1191 1192File: bash.info, Node: Shell Functions, Next: Shell Parameters, Prev: Shell Commands, Up: Basic Shell Features 1193 11943.3 Shell Functions 1195=================== 1196 1197Shell functions are a way to group commands for later execution using a 1198single name for the group. They are executed just like a "regular" 1199command. When the name of a shell function is used as a simple command 1200name, the list of commands associated with that function name is 1201executed. Shell functions are executed in the current shell context; no 1202new process is created to interpret them. 1203 1204 Functions are declared using this syntax: 1205 FNAME () COMPOUND-COMMAND [ REDIRECTIONS ] 1206 1207 or 1208 1209 function FNAME [()] COMPOUND-COMMAND [ REDIRECTIONS ] 1210 1211 This defines a shell function named FNAME. The reserved word 1212'function' is optional. If the 'function' reserved word is supplied, 1213the parentheses are optional. The BODY of the function is the compound 1214command COMPOUND-COMMAND (*note Compound Commands::). That command is 1215usually a LIST enclosed between { and }, but may be any compound command 1216listed above, with one exception: If the 'function' reserved word is 1217used, but the parentheses are not supplied, the braces are required. 1218COMPOUND-COMMAND is executed whenever FNAME is specified as the name of 1219a command. When the shell is in POSIX mode (*note Bash POSIX Mode::), 1220FNAME must be a valid shell NAME and may not be the same as one of the 1221special builtins (*note Special Builtins::). In default mode, a 1222function name can be any unquoted shell word that does not contain '$'. 1223Any redirections (*note Redirections::) associated with the shell 1224function are performed when the function is executed. A function 1225definition may be deleted using the '-f' option to the 'unset' builtin 1226(*note Bourne Shell Builtins::). 1227 1228 The exit status of a function definition is zero unless a syntax 1229error occurs or a readonly function with the same name already exists. 1230When executed, the exit status of a function is the exit status of the 1231last command executed in the body. 1232 1233 Note that for historical reasons, in the most common usage the curly 1234braces that surround the body of the function must be separated from the 1235body by 'blank's or newlines. This is because the braces are reserved 1236words and are only recognized as such when they are separated from the 1237command list by whitespace or another shell metacharacter. Also, when 1238using the braces, the LIST must be terminated by a semicolon, a '&', or 1239a newline. 1240 1241 When a function is executed, the arguments to the function become the 1242positional parameters during its execution (*note Positional 1243Parameters::). The special parameter '#' that expands to the number of 1244positional parameters is updated to reflect the change. Special 1245parameter '0' is unchanged. The first element of the 'FUNCNAME' 1246variable is set to the name of the function while the function is 1247executing. 1248 1249 All other aspects of the shell execution environment are identical 1250between a function and its caller with these exceptions: the 'DEBUG' and 1251'RETURN' traps are not inherited unless the function has been given the 1252'trace' attribute using the 'declare' builtin or the '-o functrace' 1253option has been enabled with the 'set' builtin, (in which case all 1254functions inherit the 'DEBUG' and 'RETURN' traps), and the 'ERR' trap is 1255not inherited unless the '-o errtrace' shell option has been enabled. 1256*Note Bourne Shell Builtins::, for the description of the 'trap' 1257builtin. 1258 1259 The 'FUNCNEST' variable, if set to a numeric value greater than 0, 1260defines a maximum function nesting level. Function invocations that 1261exceed the limit cause the entire command to abort. 1262 1263 If the builtin command 'return' is executed in a function, the 1264function completes and execution resumes with the next command after the 1265function call. Any command associated with the 'RETURN' trap is 1266executed before execution resumes. When a function completes, the 1267values of the positional parameters and the special parameter '#' are 1268restored to the values they had prior to the function's execution. If a 1269numeric argument is given to 'return', that is the function's return 1270status; otherwise the function's return status is the exit status of the 1271last command executed before the 'return'. 1272 1273 Variables local to the function may be declared with the 'local' 1274builtin. These variables are visible only to the function and the 1275commands it invokes. This is particularly important when a shell 1276function calls other functions. 1277 1278 Local variables "shadow" variables with the same name declared at 1279previous scopes. For instance, a local variable declared in a function 1280hides a global variable of the same name: references and assignments 1281refer to the local variable, leaving the global variable unmodified. 1282When the function returns, the global variable is once again visible. 1283 1284 The shell uses DYNAMIC SCOPING to control a variable's visibility 1285within functions. With dynamic scoping, visible variables and their 1286values are a result of the sequence of function calls that caused 1287execution to reach the current function. The value of a variable that a 1288function sees depends on its value within its caller, if any, whether 1289that caller is the "global" scope or another shell function. This is 1290also the value that a local variable declaration "shadows", and the 1291value that is restored when the function returns. 1292 1293 For example, if a variable VAR is declared as local in function 1294FUNC1, and FUNC1 calls another function FUNC2, references to VAR made 1295from within FUNC2 will resolve to the local variable VAR from FUNC1, 1296shadowing any global variable named VAR. 1297 1298 The following script demonstrates this behavior. When executed, the 1299script displays 1300 1301 In func2, var = func1 local 1302 1303 func1() 1304 { 1305 local var='func1 local' 1306 func2 1307 } 1308 1309 func2() 1310 { 1311 echo "In func2, var = $var" 1312 } 1313 1314 var=global 1315 func1 1316 1317 The 'unset' builtin also acts using the same dynamic scope: if a 1318variable is local to the current scope, 'unset' will unset it; otherwise 1319the unset will refer to the variable found in any calling scope as 1320described above. If a variable at the current local scope is unset, it 1321will remain so until it is reset in that scope or until the function 1322returns. Once the function returns, any instance of the variable at a 1323previous scope will become visible. If the unset acts on a variable at 1324a previous scope, any instance of a variable with that name that had 1325been shadowed will become visible. 1326 1327 Function names and definitions may be listed with the '-f' option to 1328the 'declare' ('typeset') builtin command (*note Bash Builtins::). The 1329'-F' option to 'declare' or 'typeset' will list the function names only 1330(and optionally the source file and line number, if the 'extdebug' shell 1331option is enabled). Functions may be exported so that subshells 1332automatically have them defined with the '-f' option to the 'export' 1333builtin (*note Bourne Shell Builtins::). 1334 1335 Functions may be recursive. The 'FUNCNEST' variable may be used to 1336limit the depth of the function call stack and restrict the number of 1337function invocations. By default, no limit is placed on the number of 1338recursive calls. 1339 1340 1341File: bash.info, Node: Shell Parameters, Next: Shell Expansions, Prev: Shell Functions, Up: Basic Shell Features 1342 13433.4 Shell Parameters 1344==================== 1345 1346* Menu: 1347 1348* Positional Parameters:: The shell's command-line arguments. 1349* Special Parameters:: Parameters denoted by special characters. 1350 1351A PARAMETER is an entity that stores values. It can be a 'name', a 1352number, or one of the special characters listed below. A VARIABLE is a 1353parameter denoted by a 'name'. A variable has a VALUE and zero or more 1354ATTRIBUTES. Attributes are assigned using the 'declare' builtin command 1355(see the description of the 'declare' builtin in *note Bash Builtins::). 1356 1357 A parameter is set if it has been assigned a value. The null string 1358is a valid value. Once a variable is set, it may be unset only by using 1359the 'unset' builtin command. 1360 1361 A variable may be assigned to by a statement of the form 1362 NAME=[VALUE] 1363If VALUE is not given, the variable is assigned the null string. All 1364VALUEs undergo tilde expansion, parameter and variable expansion, 1365command substitution, arithmetic expansion, and quote removal (detailed 1366below). If the variable has its 'integer' attribute set, then VALUE is 1367evaluated as an arithmetic expression even if the '$((...))' expansion 1368is not used (*note Arithmetic Expansion::). Word splitting is not 1369performed, with the exception of '"$@"' as explained below. Filename 1370expansion is not performed. Assignment statements may also appear as 1371arguments to the 'alias', 'declare', 'typeset', 'export', 'readonly', 1372and 'local' builtin commands (DECLARATION commands). When in POSIX mode 1373(*note Bash POSIX Mode::), these builtins may appear in a command after 1374one or more instances of the 'command' builtin and retain these 1375assignment statement properties. 1376 1377 In the context where an assignment statement is assigning a value to 1378a shell variable or array index (*note Arrays::), the '+=' operator can 1379be used to append to or add to the variable's previous value. This 1380includes arguments to builtin commands such as 'declare' that accept 1381assignment statements (DECLARATION commands). When '+=' is applied to a 1382variable for which the INTEGER attribute has been set, VALUE is 1383evaluated as an arithmetic expression and added to the variable's 1384current value, which is also evaluated. When '+=' is applied to an 1385array variable using compound assignment (*note Arrays::), the 1386variable's value is not unset (as it is when using '='), and new values 1387are appended to the array beginning at one greater than the array's 1388maximum index (for indexed arrays), or added as additional key-value 1389pairs in an associative array. When applied to a string-valued 1390variable, VALUE is expanded and appended to the variable's value. 1391 1392 A variable can be assigned the NAMEREF attribute using the '-n' 1393option to the 'declare' or 'local' builtin commands (*note Bash 1394Builtins::) to create a NAMEREF, or a reference to another variable. 1395This allows variables to be manipulated indirectly. Whenever the 1396nameref variable is referenced, assigned to, unset, or has its 1397attributes modified (other than using or changing the nameref attribute 1398itself), the operation is actually performed on the variable specified 1399by the nameref variable's value. A nameref is commonly used within 1400shell functions to refer to a variable whose name is passed as an 1401argument to the function. For instance, if a variable name is passed to 1402a shell function as its first argument, running 1403 declare -n ref=$1 1404inside the function creates a nameref variable REF whose value is the 1405variable name passed as the first argument. References and assignments 1406to REF, and changes to its attributes, are treated as references, 1407assignments, and attribute modifications to the variable whose name was 1408passed as '$1'. 1409 1410 If the control variable in a 'for' loop has the nameref attribute, 1411the list of words can be a list of shell variables, and a name reference 1412will be established for each word in the list, in turn, when the loop is 1413executed. Array variables cannot be given the nameref attribute. 1414However, nameref variables can reference array variables and subscripted 1415array variables. Namerefs can be unset using the '-n' option to the 1416'unset' builtin (*note Bourne Shell Builtins::). Otherwise, if 'unset' 1417is executed with the name of a nameref variable as an argument, the 1418variable referenced by the nameref variable will be unset. 1419 1420 1421File: bash.info, Node: Positional Parameters, Next: Special Parameters, Up: Shell Parameters 1422 14233.4.1 Positional Parameters 1424--------------------------- 1425 1426A POSITIONAL PARAMETER is a parameter denoted by one or more digits, 1427other than the single digit '0'. Positional parameters are assigned 1428from the shell's arguments when it is invoked, and may be reassigned 1429using the 'set' builtin command. Positional parameter 'N' may be 1430referenced as '${N}', or as '$N' when 'N' consists of a single digit. 1431Positional parameters may not be assigned to with assignment statements. 1432The 'set' and 'shift' builtins are used to set and unset them (*note 1433Shell Builtin Commands::). The positional parameters are temporarily 1434replaced when a shell function is executed (*note Shell Functions::). 1435 1436 When a positional parameter consisting of more than a single digit is 1437expanded, it must be enclosed in braces. 1438 1439 1440File: bash.info, Node: Special Parameters, Prev: Positional Parameters, Up: Shell Parameters 1441 14423.4.2 Special Parameters 1443------------------------ 1444 1445The shell treats several parameters specially. These parameters may 1446only be referenced; assignment to them is not allowed. 1447 1448'*' 1449 ($*) Expands to the positional parameters, starting from one. When 1450 the expansion is not within double quotes, each positional 1451 parameter expands to a separate word. In contexts where it is 1452 performed, those words are subject to further word splitting and 1453 filename expansion. When the expansion occurs within double 1454 quotes, it expands to a single word with the value of each 1455 parameter separated by the first character of the 'IFS' special 1456 variable. That is, '"$*"' is equivalent to '"$1C$2C..."', where C 1457 is the first character of the value of the 'IFS' variable. If 1458 'IFS' is unset, the parameters are separated by spaces. If 'IFS' 1459 is null, the parameters are joined without intervening separators. 1460 1461'@' 1462 ($@) Expands to the positional parameters, starting from one. In 1463 contexts where word splitting is performed, this expands each 1464 positional parameter to a separate word; if not within double 1465 quotes, these words are subject to word splitting. In contexts 1466 where word splitting is not performed, this expands to a single 1467 word with each positional parameter separated by a space. When the 1468 expansion occurs within double quotes, and word splitting is 1469 performed, each parameter expands to a separate word. That is, 1470 '"$@"' is equivalent to '"$1" "$2" ...'. If the double-quoted 1471 expansion occurs within a word, the expansion of the first 1472 parameter is joined with the beginning part of the original word, 1473 and the expansion of the last parameter is joined with the last 1474 part of the original word. When there are no positional 1475 parameters, '"$@"' and '$@' expand to nothing (i.e., they are 1476 removed). 1477 1478'#' 1479 ($#) Expands to the number of positional parameters in decimal. 1480 1481'?' 1482 ($?) Expands to the exit status of the most recently executed 1483 foreground pipeline. 1484 1485'-' 1486 ($-, a hyphen.) Expands to the current option flags as specified 1487 upon invocation, by the 'set' builtin command, or those set by the 1488 shell itself (such as the '-i' option). 1489 1490'$' 1491 ($$) Expands to the process ID of the shell. In a '()' subshell, 1492 it expands to the process ID of the invoking shell, not the 1493 subshell. 1494 1495'!' 1496 ($!) Expands to the process ID of the job most recently placed 1497 into the background, whether executed as an asynchronous command or 1498 using the 'bg' builtin (*note Job Control Builtins::). 1499 1500'0' 1501 ($0) Expands to the name of the shell or shell script. This is set 1502 at shell initialization. If Bash is invoked with a file of 1503 commands (*note Shell Scripts::), '$0' is set to the name of that 1504 file. If Bash is started with the '-c' option (*note Invoking 1505 Bash::), then '$0' is set to the first argument after the string to 1506 be executed, if one is present. Otherwise, it is set to the 1507 filename used to invoke Bash, as given by argument zero. 1508 1509 1510File: bash.info, Node: Shell Expansions, Next: Redirections, Prev: Shell Parameters, Up: Basic Shell Features 1511 15123.5 Shell Expansions 1513==================== 1514 1515Expansion is performed on the command line after it has been split into 1516'token's. There are seven kinds of expansion performed: 1517 1518 * brace expansion 1519 * tilde expansion 1520 * parameter and variable expansion 1521 * command substitution 1522 * arithmetic expansion 1523 * word splitting 1524 * filename expansion 1525 1526* Menu: 1527 1528* Brace Expansion:: Expansion of expressions within braces. 1529* Tilde Expansion:: Expansion of the ~ character. 1530* Shell Parameter Expansion:: How Bash expands variables to their values. 1531* Command Substitution:: Using the output of a command as an argument. 1532* Arithmetic Expansion:: How to use arithmetic in shell expansions. 1533* Process Substitution:: A way to write and read to and from a 1534 command. 1535* Word Splitting:: How the results of expansion are split into separate 1536 arguments. 1537* Filename Expansion:: A shorthand for specifying filenames matching patterns. 1538* Quote Removal:: How and when quote characters are removed from 1539 words. 1540 1541 The order of expansions is: brace expansion; tilde expansion, 1542parameter and variable expansion, arithmetic expansion, and command 1543substitution (done in a left-to-right fashion); word splitting; and 1544filename expansion. 1545 1546 On systems that can support it, there is an additional expansion 1547available: PROCESS SUBSTITUTION. This is performed at the same time as 1548tilde, parameter, variable, and arithmetic expansion and command 1549substitution. 1550 1551 After these expansions are performed, quote characters present in the 1552original word are removed unless they have been quoted themselves (QUOTE 1553REMOVAL). 1554 1555 Only brace expansion, word splitting, and filename expansion can 1556increase the number of words of the expansion; other expansions expand a 1557single word to a single word. The only exceptions to this are the 1558expansions of '"$@"' and '$*' (*note Special Parameters::), and 1559'"${NAME[@]}"' and '${NAME[*]}' (*note Arrays::). 1560 1561 After all expansions, 'quote removal' (*note Quote Removal::) is 1562performed. 1563 1564 1565File: bash.info, Node: Brace Expansion, Next: Tilde Expansion, Up: Shell Expansions 1566 15673.5.1 Brace Expansion 1568--------------------- 1569 1570Brace expansion is a mechanism by which arbitrary strings may be 1571generated. This mechanism is similar to FILENAME EXPANSION (*note 1572Filename Expansion::), but the filenames generated need not exist. 1573Patterns to be brace expanded take the form of an optional PREAMBLE, 1574followed by either a series of comma-separated strings or a sequence 1575expression between a pair of braces, followed by an optional POSTSCRIPT. 1576The preamble is prefixed to each string contained within the braces, and 1577the postscript is then appended to each resulting string, expanding left 1578to right. 1579 1580 Brace expansions may be nested. The results of each expanded string 1581are not sorted; left to right order is preserved. For example, 1582 bash$ echo a{d,c,b}e 1583 ade ace abe 1584 1585 A sequence expression takes the form '{X..Y[..INCR]}', where X and Y 1586are either integers or single characters, and INCR, an optional 1587increment, is an integer. When integers are supplied, the expression 1588expands to each number between X and Y, inclusive. Supplied integers 1589may be prefixed with '0' to force each term to have the same width. 1590When either X or Y begins with a zero, the shell attempts to force all 1591generated terms to contain the same number of digits, zero-padding where 1592necessary. When characters are supplied, the expression expands to each 1593character lexicographically between X and Y, inclusive, using the 1594default C locale. Note that both X and Y must be of the same type. 1595When the increment is supplied, it is used as the difference between 1596each term. The default increment is 1 or -1 as appropriate. 1597 1598 Brace expansion is performed before any other expansions, and any 1599characters special to other expansions are preserved in the result. It 1600is strictly textual. Bash does not apply any syntactic interpretation 1601to the context of the expansion or the text between the braces. 1602 1603 A correctly-formed brace expansion must contain unquoted opening and 1604closing braces, and at least one unquoted comma or a valid sequence 1605expression. Any incorrectly formed brace expansion is left unchanged. 1606 1607 A { or ',' may be quoted with a backslash to prevent its being 1608considered part of a brace expression. To avoid conflicts with 1609parameter expansion, the string '${' is not considered eligible for 1610brace expansion, and inhibits brace expansion until the closing '}'. 1611 1612 This construct is typically used as shorthand when the common prefix 1613of the strings to be generated is longer than in the above example: 1614 mkdir /usr/local/src/bash/{old,new,dist,bugs} 1615 or 1616 chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} 1617 1618 1619File: bash.info, Node: Tilde Expansion, Next: Shell Parameter Expansion, Prev: Brace Expansion, Up: Shell Expansions 1620 16213.5.2 Tilde Expansion 1622--------------------- 1623 1624If a word begins with an unquoted tilde character ('~'), all of the 1625characters up to the first unquoted slash (or all characters, if there 1626is no unquoted slash) are considered a TILDE-PREFIX. If none of the 1627characters in the tilde-prefix are quoted, the characters in the 1628tilde-prefix following the tilde are treated as a possible LOGIN NAME. 1629If this login name is the null string, the tilde is replaced with the 1630value of the 'HOME' shell variable. If 'HOME' is unset, the home 1631directory of the user executing the shell is substituted instead. 1632Otherwise, the tilde-prefix is replaced with the home directory 1633associated with the specified login name. 1634 1635 If the tilde-prefix is '~+', the value of the shell variable 'PWD' 1636replaces the tilde-prefix. If the tilde-prefix is '~-', the value of 1637the shell variable 'OLDPWD', if it is set, is substituted. 1638 1639 If the characters following the tilde in the tilde-prefix consist of 1640a number N, optionally prefixed by a '+' or a '-', the tilde-prefix is 1641replaced with the corresponding element from the directory stack, as it 1642would be displayed by the 'dirs' builtin invoked with the characters 1643following tilde in the tilde-prefix as an argument (*note The Directory 1644Stack::). If the tilde-prefix, sans the tilde, consists of a number 1645without a leading '+' or '-', '+' is assumed. 1646 1647 If the login name is invalid, or the tilde expansion fails, the word 1648is left unchanged. 1649 1650 Each variable assignment is checked for unquoted tilde-prefixes 1651immediately following a ':' or the first '='. In these cases, tilde 1652expansion is also performed. Consequently, one may use filenames with 1653tildes in assignments to 'PATH', 'MAILPATH', and 'CDPATH', and the shell 1654assigns the expanded value. 1655 1656 The following table shows how Bash treats unquoted tilde-prefixes: 1657 1658'~' 1659 The value of '$HOME' 1660'~/foo' 1661 '$HOME/foo' 1662 1663'~fred/foo' 1664 The subdirectory 'foo' of the home directory of the user 'fred' 1665 1666'~+/foo' 1667 '$PWD/foo' 1668 1669'~-/foo' 1670 '${OLDPWD-'~-'}/foo' 1671 1672'~N' 1673 The string that would be displayed by 'dirs +N' 1674 1675'~+N' 1676 The string that would be displayed by 'dirs +N' 1677 1678'~-N' 1679 The string that would be displayed by 'dirs -N' 1680 1681 Bash also performs tilde expansion on words satisfying the conditions 1682of variable assignments (*note Shell Parameters::) when they appear as 1683arguments to simple commands. Bash does not do this, except for the 1684DECLARATION commands listed above, when in POSIX mode. 1685 1686 1687File: bash.info, Node: Shell Parameter Expansion, Next: Command Substitution, Prev: Tilde Expansion, Up: Shell Expansions 1688 16893.5.3 Shell Parameter Expansion 1690------------------------------- 1691 1692The '$' character introduces parameter expansion, command substitution, 1693or arithmetic expansion. The parameter name or symbol to be expanded 1694may be enclosed in braces, which are optional but serve to protect the 1695variable to be expanded from characters immediately following it which 1696could be interpreted as part of the name. 1697 1698 When braces are used, the matching ending brace is the first '}' not 1699escaped by a backslash or within a quoted string, and not within an 1700embedded arithmetic expansion, command substitution, or parameter 1701expansion. 1702 1703 The basic form of parameter expansion is ${PARAMETER}. The value of 1704PARAMETER is substituted. The PARAMETER is a shell parameter as 1705described above (*note Shell Parameters::) or an array reference (*note 1706Arrays::). The braces are required when PARAMETER is a positional 1707parameter with more than one digit, or when PARAMETER is followed by a 1708character that is not to be interpreted as part of its name. 1709 1710 If the first character of PARAMETER is an exclamation point (!), and 1711PARAMETER is not a NAMEREF, it introduces a level of indirection. Bash 1712uses the value formed by expanding the rest of PARAMETER as the new 1713PARAMETER; this is then expanded and that value is used in the rest of 1714the expansion, rather than the expansion of the original PARAMETER. 1715This is known as 'indirect expansion'. The value is subject to tilde 1716expansion, parameter expansion, command substitution, and arithmetic 1717expansion. If PARAMETER is a nameref, this expands to the name of the 1718variable referenced by PARAMETER instead of performing the complete 1719indirect expansion. The exceptions to this are the expansions of 1720${!PREFIX*} and ${!NAME[@]} described below. The exclamation point must 1721immediately follow the left brace in order to introduce indirection. 1722 1723 In each of the cases below, WORD is subject to tilde expansion, 1724parameter expansion, command substitution, and arithmetic expansion. 1725 1726 When not performing substring expansion, using the form described 1727below (e.g., ':-'), Bash tests for a parameter that is unset or null. 1728Omitting the colon results in a test only for a parameter that is unset. 1729Put another way, if the colon is included, the operator tests for both 1730PARAMETER's existence and that its value is not null; if the colon is 1731omitted, the operator tests only for existence. 1732 1733'${PARAMETER:-WORD}' 1734 If PARAMETER is unset or null, the expansion of WORD is 1735 substituted. Otherwise, the value of PARAMETER is substituted. 1736 1737'${PARAMETER:=WORD}' 1738 If PARAMETER is unset or null, the expansion of WORD is assigned to 1739 PARAMETER. The value of PARAMETER is then substituted. Positional 1740 parameters and special parameters may not be assigned to in this 1741 way. 1742 1743'${PARAMETER:?WORD}' 1744 If PARAMETER is null or unset, the expansion of WORD (or a message 1745 to that effect if WORD is not present) is written to the standard 1746 error and the shell, if it is not interactive, exits. Otherwise, 1747 the value of PARAMETER is substituted. 1748 1749'${PARAMETER:+WORD}' 1750 If PARAMETER is null or unset, nothing is substituted, otherwise 1751 the expansion of WORD is substituted. 1752 1753'${PARAMETER:OFFSET}' 1754'${PARAMETER:OFFSET:LENGTH}' 1755 This is referred to as Substring Expansion. It expands to up to 1756 LENGTH characters of the value of PARAMETER starting at the 1757 character specified by OFFSET. If PARAMETER is '@', an indexed 1758 array subscripted by '@' or '*', or an associative array name, the 1759 results differ as described below. If LENGTH is omitted, it 1760 expands to the substring of the value of PARAMETER starting at the 1761 character specified by OFFSET and extending to the end of the 1762 value. LENGTH and OFFSET are arithmetic expressions (*note Shell 1763 Arithmetic::). 1764 1765 If OFFSET evaluates to a number less than zero, the value is used 1766 as an offset in characters from the end of the value of PARAMETER. 1767 If LENGTH evaluates to a number less than zero, it is interpreted 1768 as an offset in characters from the end of the value of PARAMETER 1769 rather than a number of characters, and the expansion is the 1770 characters between OFFSET and that result. Note that a negative 1771 offset must be separated from the colon by at least one space to 1772 avoid being confused with the ':-' expansion. 1773 1774 Here are some examples illustrating substring expansion on 1775 parameters and subscripted arrays: 1776 1777 $ string=01234567890abcdefgh 1778 $ echo ${string:7} 1779 7890abcdefgh 1780 $ echo ${string:7:0} 1781 1782 $ echo ${string:7:2} 1783 78 1784 $ echo ${string:7:-2} 1785 7890abcdef 1786 $ echo ${string: -7} 1787 bcdefgh 1788 $ echo ${string: -7:0} 1789 1790 $ echo ${string: -7:2} 1791 bc 1792 $ echo ${string: -7:-2} 1793 bcdef 1794 $ set -- 01234567890abcdefgh 1795 $ echo ${1:7} 1796 7890abcdefgh 1797 $ echo ${1:7:0} 1798 1799 $ echo ${1:7:2} 1800 78 1801 $ echo ${1:7:-2} 1802 7890abcdef 1803 $ echo ${1: -7} 1804 bcdefgh 1805 $ echo ${1: -7:0} 1806 1807 $ echo ${1: -7:2} 1808 bc 1809 $ echo ${1: -7:-2} 1810 bcdef 1811 $ array[0]=01234567890abcdefgh 1812 $ echo ${array[0]:7} 1813 7890abcdefgh 1814 $ echo ${array[0]:7:0} 1815 1816 $ echo ${array[0]:7:2} 1817 78 1818 $ echo ${array[0]:7:-2} 1819 7890abcdef 1820 $ echo ${array[0]: -7} 1821 bcdefgh 1822 $ echo ${array[0]: -7:0} 1823 1824 $ echo ${array[0]: -7:2} 1825 bc 1826 $ echo ${array[0]: -7:-2} 1827 bcdef 1828 1829 If PARAMETER is '@', the result is LENGTH positional parameters 1830 beginning at OFFSET. A negative OFFSET is taken relative to one 1831 greater than the greatest positional parameter, so an offset of -1 1832 evaluates to the last positional parameter. It is an expansion 1833 error if LENGTH evaluates to a number less than zero. 1834 1835 The following examples illustrate substring expansion using 1836 positional parameters: 1837 1838 $ set -- 1 2 3 4 5 6 7 8 9 0 a b c d e f g h 1839 $ echo ${@:7} 1840 7 8 9 0 a b c d e f g h 1841 $ echo ${@:7:0} 1842 1843 $ echo ${@:7:2} 1844 7 8 1845 $ echo ${@:7:-2} 1846 bash: -2: substring expression < 0 1847 $ echo ${@: -7:2} 1848 b c 1849 $ echo ${@:0} 1850 ./bash 1 2 3 4 5 6 7 8 9 0 a b c d e f g h 1851 $ echo ${@:0:2} 1852 ./bash 1 1853 $ echo ${@: -7:0} 1854 1855 1856 If PARAMETER is an indexed array name subscripted by '@' or '*', 1857 the result is the LENGTH members of the array beginning with 1858 '${PARAMETER[OFFSET]}'. A negative OFFSET is taken relative to one 1859 greater than the maximum index of the specified array. It is an 1860 expansion error if LENGTH evaluates to a number less than zero. 1861 1862 These examples show how you can use substring expansion with 1863 indexed arrays: 1864 1865 $ array=(0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h) 1866 $ echo ${array[@]:7} 1867 7 8 9 0 a b c d e f g h 1868 $ echo ${array[@]:7:2} 1869 7 8 1870 $ echo ${array[@]: -7:2} 1871 b c 1872 $ echo ${array[@]: -7:-2} 1873 bash: -2: substring expression < 0 1874 $ echo ${array[@]:0} 1875 0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h 1876 $ echo ${array[@]:0:2} 1877 0 1 1878 $ echo ${array[@]: -7:0} 1879 1880 1881 Substring expansion applied to an associative array produces 1882 undefined results. 1883 1884 Substring indexing is zero-based unless the positional parameters 1885 are used, in which case the indexing starts at 1 by default. If 1886 OFFSET is 0, and the positional parameters are used, '$0' is 1887 prefixed to the list. 1888 1889'${!PREFIX*}' 1890'${!PREFIX@}' 1891 Expands to the names of variables whose names begin with PREFIX, 1892 separated by the first character of the 'IFS' special variable. 1893 When '@' is used and the expansion appears within double quotes, 1894 each variable name expands to a separate word. 1895 1896'${!NAME[@]}' 1897'${!NAME[*]}' 1898 If NAME is an array variable, expands to the list of array indices 1899 (keys) assigned in NAME. If NAME is not an array, expands to 0 if 1900 NAME is set and null otherwise. When '@' is used and the expansion 1901 appears within double quotes, each key expands to a separate word. 1902 1903'${#PARAMETER}' 1904 The length in characters of the expanded value of PARAMETER is 1905 substituted. If PARAMETER is '*' or '@', the value substituted is 1906 the number of positional parameters. If PARAMETER is an array name 1907 subscripted by '*' or '@', the value substituted is the number of 1908 elements in the array. If PARAMETER is an indexed array name 1909 subscripted by a negative number, that number is interpreted as 1910 relative to one greater than the maximum index of PARAMETER, so 1911 negative indices count back from the end of the array, and an index 1912 of -1 references the last element. 1913 1914'${PARAMETER#WORD}' 1915'${PARAMETER##WORD}' 1916 The WORD is expanded to produce a pattern and matched according to 1917 the rules described below (*note Pattern Matching::). If the 1918 pattern matches the beginning of the expanded value of PARAMETER, 1919 then the result of the expansion is the expanded value of PARAMETER 1920 with the shortest matching pattern (the '#' case) or the longest 1921 matching pattern (the '##' case) deleted. If PARAMETER is '@' or 1922 '*', the pattern removal operation is applied to each positional 1923 parameter in turn, and the expansion is the resultant list. If 1924 PARAMETER is an array variable subscripted with '@' or '*', the 1925 pattern removal operation is applied to each member of the array in 1926 turn, and the expansion is the resultant list. 1927 1928'${PARAMETER%WORD}' 1929'${PARAMETER%%WORD}' 1930 The WORD is expanded to produce a pattern and matched according to 1931 the rules described below (*note Pattern Matching::). If the 1932 pattern matches a trailing portion of the expanded value of 1933 PARAMETER, then the result of the expansion is the value of 1934 PARAMETER with the shortest matching pattern (the '%' case) or the 1935 longest matching pattern (the '%%' case) deleted. If PARAMETER is 1936 '@' or '*', the pattern removal operation is applied to each 1937 positional parameter in turn, and the expansion is the resultant 1938 list. If PARAMETER is an array variable subscripted with '@' or 1939 '*', the pattern removal operation is applied to each member of the 1940 array in turn, and the expansion is the resultant list. 1941 1942'${PARAMETER/PATTERN/STRING}' 1943 1944 The PATTERN is expanded to produce a pattern just as in filename 1945 expansion. PARAMETER is expanded and the longest match of PATTERN 1946 against its value is replaced with STRING. The match is performed 1947 according to the rules described below (*note Pattern Matching::). 1948 If PATTERN begins with '/', all matches of PATTERN are replaced 1949 with STRING. Normally only the first match is replaced. If 1950 PATTERN begins with '#', it must match at the beginning of the 1951 expanded value of PARAMETER. If PATTERN begins with '%', it must 1952 match at the end of the expanded value of PARAMETER. If STRING is 1953 null, matches of PATTERN are deleted and the '/' following PATTERN 1954 may be omitted. If the 'nocasematch' shell option (see the 1955 description of 'shopt' in *note The Shopt Builtin::) is enabled, 1956 the match is performed without regard to the case of alphabetic 1957 characters. If PARAMETER is '@' or '*', the substitution operation 1958 is applied to each positional parameter in turn, and the expansion 1959 is the resultant list. If PARAMETER is an array variable 1960 subscripted with '@' or '*', the substitution operation is applied 1961 to each member of the array in turn, and the expansion is the 1962 resultant list. 1963 1964'${PARAMETER^PATTERN}' 1965'${PARAMETER^^PATTERN}' 1966'${PARAMETER,PATTERN}' 1967'${PARAMETER,,PATTERN}' 1968 This expansion modifies the case of alphabetic characters in 1969 PARAMETER. The PATTERN is expanded to produce a pattern just as in 1970 filename expansion. Each character in the expanded value of 1971 PARAMETER is tested against PATTERN, and, if it matches the 1972 pattern, its case is converted. The pattern should not attempt to 1973 match more than one character. The '^' operator converts lowercase 1974 letters matching PATTERN to uppercase; the ',' operator converts 1975 matching uppercase letters to lowercase. The '^^' and ',,' 1976 expansions convert each matched character in the expanded value; 1977 the '^' and ',' expansions match and convert only the first 1978 character in the expanded value. If PATTERN is omitted, it is 1979 treated like a '?', which matches every character. If PARAMETER is 1980 '@' or '*', the case modification operation is applied to each 1981 positional parameter in turn, and the expansion is the resultant 1982 list. If PARAMETER is an array variable subscripted with '@' or 1983 '*', the case modification operation is applied to each member of 1984 the array in turn, and the expansion is the resultant list. 1985 1986'${PARAMETER@OPERATOR}' 1987 The expansion is either a transformation of the value of PARAMETER 1988 or information about PARAMETER itself, depending on the value of 1989 OPERATOR. Each OPERATOR is a single letter: 1990 1991 'U' 1992 The expansion is a string that is the value of PARAMETER with 1993 lowercase alphabetic characters converted to uppercase. 1994 'u' 1995 The expansion is a string that is the value of PARAMETER with 1996 the first character converted to uppercase, if it is 1997 alphabetic. 1998 'L' 1999 The expansion is a string that is the value of PARAMETER with 2000 uppercase alphabetic characters converted to lowercase. 2001 'Q' 2002 The expansion is a string that is the value of PARAMETER 2003 quoted in a format that can be reused as input. 2004 'E' 2005 The expansion is a string that is the value of PARAMETER with 2006 backslash escape sequences expanded as with the '$'...'' 2007 quoting mechanism. 2008 'P' 2009 The expansion is a string that is the result of expanding the 2010 value of PARAMETER as if it were a prompt string (*note 2011 Controlling the Prompt::). 2012 'A' 2013 The expansion is a string in the form of an assignment 2014 statement or 'declare' command that, if evaluated, will 2015 recreate PARAMETER with its attributes and value. 2016 'K' 2017 Produces a possibly-quoted version of the value of PARAMETER, 2018 except that it prints the values of indexed and associative 2019 arrays as a sequence of quoted key-value pairs (*note 2020 Arrays::). 2021 'a' 2022 The expansion is a string consisting of flag values 2023 representing PARAMETER's attributes. 2024 2025 If PARAMETER is '@' or '*', the operation is applied to each 2026 positional parameter in turn, and the expansion is the resultant 2027 list. If PARAMETER is an array variable subscripted with '@' or 2028 '*', the operation is applied to each member of the array in turn, 2029 and the expansion is the resultant list. 2030 2031 The result of the expansion is subject to word splitting and 2032 filename expansion as described below. 2033 2034 2035File: bash.info, Node: Command Substitution, Next: Arithmetic Expansion, Prev: Shell Parameter Expansion, Up: Shell Expansions 2036 20373.5.4 Command Substitution 2038-------------------------- 2039 2040Command substitution allows the output of a command to replace the 2041command itself. Command substitution occurs when a command is enclosed 2042as follows: 2043 $(COMMAND) 2044or 2045 `COMMAND` 2046 2047Bash performs the expansion by executing COMMAND in a subshell 2048environment and replacing the command substitution with the standard 2049output of the command, with any trailing newlines deleted. Embedded 2050newlines are not deleted, but they may be removed during word splitting. 2051The command substitution '$(cat FILE)' can be replaced by the equivalent 2052but faster '$(< FILE)'. 2053 2054 When the old-style backquote form of substitution is used, backslash 2055retains its literal meaning except when followed by '$', '`', or '\'. 2056The first backquote not preceded by a backslash terminates the command 2057substitution. When using the '$(COMMAND)' form, all characters between 2058the parentheses make up the command; none are treated specially. 2059 2060 Command substitutions may be nested. To nest when using the 2061backquoted form, escape the inner backquotes with backslashes. 2062 2063 If the substitution appears within double quotes, word splitting and 2064filename expansion are not performed on the results. 2065 2066 2067File: bash.info, Node: Arithmetic Expansion, Next: Process Substitution, Prev: Command Substitution, Up: Shell Expansions 2068 20693.5.5 Arithmetic Expansion 2070-------------------------- 2071 2072Arithmetic expansion allows the evaluation of an arithmetic expression 2073and the substitution of the result. The format for arithmetic expansion 2074is: 2075 2076 $(( EXPRESSION )) 2077 2078 The expression is treated as if it were within double quotes, but a 2079double quote inside the parentheses is not treated specially. All 2080tokens in the expression undergo parameter and variable expansion, 2081command substitution, and quote removal. The result is treated as the 2082arithmetic expression to be evaluated. Arithmetic expansions may be 2083nested. 2084 2085 The evaluation is performed according to the rules listed below 2086(*note Shell Arithmetic::). If the expression is invalid, Bash prints a 2087message indicating failure to the standard error and no substitution 2088occurs. 2089 2090 2091File: bash.info, Node: Process Substitution, Next: Word Splitting, Prev: Arithmetic Expansion, Up: Shell Expansions 2092 20933.5.6 Process Substitution 2094-------------------------- 2095 2096Process substitution allows a process's input or output to be referred 2097to using a filename. It takes the form of 2098 <(LIST) 2099or 2100 >(LIST) 2101The process LIST is run asynchronously, and its input or output appears 2102as a filename. This filename is passed as an argument to the current 2103command as the result of the expansion. If the '>(LIST)' form is used, 2104writing to the file will provide input for LIST. If the '<(LIST)' form 2105is used, the file passed as an argument should be read to obtain the 2106output of LIST. Note that no space may appear between the '<' or '>' 2107and the left parenthesis, otherwise the construct would be interpreted 2108as a redirection. Process substitution is supported on systems that 2109support named pipes (FIFOs) or the '/dev/fd' method of naming open 2110files. 2111 2112 When available, process substitution is performed simultaneously with 2113parameter and variable expansion, command substitution, and arithmetic 2114expansion. 2115 2116 2117File: bash.info, Node: Word Splitting, Next: Filename Expansion, Prev: Process Substitution, Up: Shell Expansions 2118 21193.5.7 Word Splitting 2120-------------------- 2121 2122The shell scans the results of parameter expansion, command 2123substitution, and arithmetic expansion that did not occur within double 2124quotes for word splitting. 2125 2126 The shell treats each character of '$IFS' as a delimiter, and splits 2127the results of the other expansions into words using these characters as 2128field terminators. If 'IFS' is unset, or its value is exactly 2129'<space><tab><newline>', the default, then sequences of ' <space>', 2130'<tab>', and '<newline>' at the beginning and end of the results of the 2131previous expansions are ignored, and any sequence of 'IFS' characters 2132not at the beginning or end serves to delimit words. If 'IFS' has a 2133value other than the default, then sequences of the whitespace 2134characters 'space', 'tab', and 'newline' are ignored at the beginning 2135and end of the word, as long as the whitespace character is in the value 2136of 'IFS' (an 'IFS' whitespace character). Any character in 'IFS' that 2137is not 'IFS' whitespace, along with any adjacent 'IFS' whitespace 2138characters, delimits a field. A sequence of 'IFS' whitespace characters 2139is also treated as a delimiter. If the value of 'IFS' is null, no word 2140splitting occurs. 2141 2142 Explicit null arguments ('""' or '''') are retained and passed to 2143commands as empty strings. Unquoted implicit null arguments, resulting 2144from the expansion of parameters that have no values, are removed. If a 2145parameter with no value is expanded within double quotes, a null 2146argument results and is retained and passed to a command as an empty 2147string. When a quoted null argument appears as part of a word whose 2148expansion is non-null, the null argument is removed. That is, the word 2149'-d''' becomes '-d' after word splitting and null argument removal. 2150 2151 Note that if no expansion occurs, no splitting is performed. 2152 2153 2154File: bash.info, Node: Filename Expansion, Next: Quote Removal, Prev: Word Splitting, Up: Shell Expansions 2155 21563.5.8 Filename Expansion 2157------------------------ 2158 2159* Menu: 2160 2161* Pattern Matching:: How the shell matches patterns. 2162 2163After word splitting, unless the '-f' option has been set (*note The Set 2164Builtin::), Bash scans each word for the characters '*', '?', and '['. 2165If one of these characters appears, and is not quoted, then the word is 2166regarded as a PATTERN, and replaced with an alphabetically sorted list 2167of filenames matching the pattern (*note Pattern Matching::). If no 2168matching filenames are found, and the shell option 'nullglob' is 2169disabled, the word is left unchanged. If the 'nullglob' option is set, 2170and no matches are found, the word is removed. If the 'failglob' shell 2171option is set, and no matches are found, an error message is printed and 2172the command is not executed. If the shell option 'nocaseglob' is 2173enabled, the match is performed without regard to the case of alphabetic 2174characters. 2175 2176 When a pattern is used for filename expansion, the character '.' at 2177the start of a filename or immediately following a slash must be matched 2178explicitly, unless the shell option 'dotglob' is set. The filenames '.' 2179and '..' must always be matched explicitly, even if 'dotglob' is set. 2180In other cases, the '.' character is not treated specially. 2181 2182 When matching a filename, the slash character must always be matched 2183explicitly by a slash in the pattern, but in other matching contexts it 2184can be matched by a special pattern character as described below (*note 2185Pattern Matching::). 2186 2187 See the description of 'shopt' in *note The Shopt Builtin::, for a 2188description of the 'nocaseglob', 'nullglob', 'failglob', and 'dotglob' 2189options. 2190 2191 The 'GLOBIGNORE' shell variable may be used to restrict the set of 2192file names matching a pattern. If 'GLOBIGNORE' is set, each matching 2193file name that also matches one of the patterns in 'GLOBIGNORE' is 2194removed from the list of matches. If the 'nocaseglob' option is set, 2195the matching against the patterns in 'GLOBIGNORE' is performed without 2196regard to case. The filenames '.' and '..' are always ignored when 2197'GLOBIGNORE' is set and not null. However, setting 'GLOBIGNORE' to a 2198non-null value has the effect of enabling the 'dotglob' shell option, so 2199all other filenames beginning with a '.' will match. To get the old 2200behavior of ignoring filenames beginning with a '.', make '.*' one of 2201the patterns in 'GLOBIGNORE'. The 'dotglob' option is disabled when 2202'GLOBIGNORE' is unset. 2203 2204 2205File: bash.info, Node: Pattern Matching, Up: Filename Expansion 2206 22073.5.8.1 Pattern Matching 2208........................ 2209 2210Any character that appears in a pattern, other than the special pattern 2211characters described below, matches itself. The NUL character may not 2212occur in a pattern. A backslash escapes the following character; the 2213escaping backslash is discarded when matching. The special pattern 2214characters must be quoted if they are to be matched literally. 2215 2216 The special pattern characters have the following meanings: 2217'*' 2218 Matches any string, including the null string. When the 'globstar' 2219 shell option is enabled, and '*' is used in a filename expansion 2220 context, two adjacent '*'s used as a single pattern will match all 2221 files and zero or more directories and subdirectories. If followed 2222 by a '/', two adjacent '*'s will match only directories and 2223 subdirectories. 2224'?' 2225 Matches any single character. 2226'[...]' 2227 Matches any one of the enclosed characters. A pair of characters 2228 separated by a hyphen denotes a RANGE EXPRESSION; any character 2229 that falls between those two characters, inclusive, using the 2230 current locale's collating sequence and character set, is matched. 2231 If the first character following the '[' is a '!' or a '^' then any 2232 character not enclosed is matched. A '-' may be matched by 2233 including it as the first or last character in the set. A ']' may 2234 be matched by including it as the first character in the set. The 2235 sorting order of characters in range expressions is determined by 2236 the current locale and the values of the 'LC_COLLATE' and 'LC_ALL' 2237 shell variables, if set. 2238 2239 For example, in the default C locale, '[a-dx-z]' is equivalent to 2240 '[abcdxyz]'. Many locales sort characters in dictionary order, and 2241 in these locales '[a-dx-z]' is typically not equivalent to 2242 '[abcdxyz]'; it might be equivalent to '[aBbCcDdxXyYz]', for 2243 example. To obtain the traditional interpretation of ranges in 2244 bracket expressions, you can force the use of the C locale by 2245 setting the 'LC_COLLATE' or 'LC_ALL' environment variable to the 2246 value 'C', or enable the 'globasciiranges' shell option. 2247 2248 Within '[' and ']', CHARACTER CLASSES can be specified using the 2249 syntax '[:'CLASS':]', where CLASS is one of the following classes 2250 defined in the POSIX standard: 2251 alnum alpha ascii blank cntrl digit graph lower 2252 print punct space upper word xdigit 2253 A character class matches any character belonging to that class. 2254 The 'word' character class matches letters, digits, and the 2255 character '_'. 2256 2257 Within '[' and ']', an EQUIVALENCE CLASS can be specified using the 2258 syntax '[='C'=]', which matches all characters with the same 2259 collation weight (as defined by the current locale) as the 2260 character C. 2261 2262 Within '[' and ']', the syntax '[.'SYMBOL'.]' matches the collating 2263 symbol SYMBOL. 2264 2265 If the 'extglob' shell option is enabled using the 'shopt' builtin, 2266several extended pattern matching operators are recognized. In the 2267following description, a PATTERN-LIST is a list of one or more patterns 2268separated by a '|'. Composite patterns may be formed using one or more 2269of the following sub-patterns: 2270 2271'?(PATTERN-LIST)' 2272 Matches zero or one occurrence of the given patterns. 2273 2274'*(PATTERN-LIST)' 2275 Matches zero or more occurrences of the given patterns. 2276 2277'+(PATTERN-LIST)' 2278 Matches one or more occurrences of the given patterns. 2279 2280'@(PATTERN-LIST)' 2281 Matches one of the given patterns. 2282 2283'!(PATTERN-LIST)' 2284 Matches anything except one of the given patterns. 2285 2286 Complicated extended pattern matching against long strings is slow, 2287especially when the patterns contain alternations and the strings 2288contain multiple matches. Using separate matches against shorter 2289strings, or using arrays of strings instead of a single long string, may 2290be faster. 2291 2292 2293File: bash.info, Node: Quote Removal, Prev: Filename Expansion, Up: Shell Expansions 2294 22953.5.9 Quote Removal 2296------------------- 2297 2298After the preceding expansions, all unquoted occurrences of the 2299characters '\', ''', and '"' that did not result from one of the above 2300expansions are removed. 2301 2302 2303File: bash.info, Node: Redirections, Next: Executing Commands, Prev: Shell Expansions, Up: Basic Shell Features 2304 23053.6 Redirections 2306================ 2307 2308Before a command is executed, its input and output may be REDIRECTED 2309using a special notation interpreted by the shell. Redirection allows 2310commands' file handles to be duplicated, opened, closed, made to refer 2311to different files, and can change the files the command reads from and 2312writes to. Redirection may also be used to modify file handles in the 2313current shell execution environment. The following redirection 2314operators may precede or appear anywhere within a simple command or may 2315follow a command. Redirections are processed in the order they appear, 2316from left to right. 2317 2318 Each redirection that may be preceded by a file descriptor number may 2319instead be preceded by a word of the form {VARNAME}. In this case, for 2320each redirection operator except >&- and <&-, the shell will allocate a 2321file descriptor greater than 10 and assign it to {VARNAME}. If >&- or 2322<&- is preceded by {VARNAME}, the value of VARNAME defines the file 2323descriptor to close. If {VARNAME} is supplied, the redirection persists 2324beyond the scope of the command, allowing the shell programmer to manage 2325the file descriptor's lifetime manually. 2326 2327 In the following descriptions, if the file descriptor number is 2328omitted, and the first character of the redirection operator is '<', the 2329redirection refers to the standard input (file descriptor 0). If the 2330first character of the redirection operator is '>', the redirection 2331refers to the standard output (file descriptor 1). 2332 2333 The word following the redirection operator in the following 2334descriptions, unless otherwise noted, is subjected to brace expansion, 2335tilde expansion, parameter expansion, command substitution, arithmetic 2336expansion, quote removal, filename expansion, and word splitting. If it 2337expands to more than one word, Bash reports an error. 2338 2339 Note that the order of redirections is significant. For example, the 2340command 2341 ls > DIRLIST 2>&1 2342directs both standard output (file descriptor 1) and standard error 2343(file descriptor 2) to the file DIRLIST, while the command 2344 ls 2>&1 > DIRLIST 2345directs only the standard output to file DIRLIST, because the standard 2346error was made a copy of the standard output before the standard output 2347was redirected to DIRLIST. 2348 2349 Bash handles several filenames specially when they are used in 2350redirections, as described in the following table. If the operating 2351system on which Bash is running provides these special files, bash will 2352use them; otherwise it will emulate them internally with the behavior 2353described below. 2354 2355'/dev/fd/FD' 2356 If FD is a valid integer, file descriptor FD is duplicated. 2357 2358'/dev/stdin' 2359 File descriptor 0 is duplicated. 2360 2361'/dev/stdout' 2362 File descriptor 1 is duplicated. 2363 2364'/dev/stderr' 2365 File descriptor 2 is duplicated. 2366 2367'/dev/tcp/HOST/PORT' 2368 If HOST is a valid hostname or Internet address, and PORT is an 2369 integer port number or service name, Bash attempts to open the 2370 corresponding TCP socket. 2371 2372'/dev/udp/HOST/PORT' 2373 If HOST is a valid hostname or Internet address, and PORT is an 2374 integer port number or service name, Bash attempts to open the 2375 corresponding UDP socket. 2376 2377 A failure to open or create a file causes the redirection to fail. 2378 2379 Redirections using file descriptors greater than 9 should be used 2380with care, as they may conflict with file descriptors the shell uses 2381internally. 2382 23833.6.1 Redirecting Input 2384----------------------- 2385 2386Redirection of input causes the file whose name results from the 2387expansion of WORD to be opened for reading on file descriptor 'n', or 2388the standard input (file descriptor 0) if 'n' is not specified. 2389 2390 The general format for redirecting input is: 2391 [N]<WORD 2392 23933.6.2 Redirecting Output 2394------------------------ 2395 2396Redirection of output causes the file whose name results from the 2397expansion of WORD to be opened for writing on file descriptor N, or the 2398standard output (file descriptor 1) if N is not specified. If the file 2399does not exist it is created; if it does exist it is truncated to zero 2400size. 2401 2402 The general format for redirecting output is: 2403 [N]>[|]WORD 2404 2405 If the redirection operator is '>', and the 'noclobber' option to the 2406'set' builtin has been enabled, the redirection will fail if the file 2407whose name results from the expansion of WORD exists and is a regular 2408file. If the redirection operator is '>|', or the redirection operator 2409is '>' and the 'noclobber' option is not enabled, the redirection is 2410attempted even if the file named by WORD exists. 2411 24123.6.3 Appending Redirected Output 2413--------------------------------- 2414 2415Redirection of output in this fashion causes the file whose name results 2416from the expansion of WORD to be opened for appending on file descriptor 2417N, or the standard output (file descriptor 1) if N is not specified. If 2418the file does not exist it is created. 2419 2420 The general format for appending output is: 2421 [N]>>WORD 2422 24233.6.4 Redirecting Standard Output and Standard Error 2424---------------------------------------------------- 2425 2426This construct allows both the standard output (file descriptor 1) and 2427the standard error output (file descriptor 2) to be redirected to the 2428file whose name is the expansion of WORD. 2429 2430 There are two formats for redirecting standard output and standard 2431error: 2432 &>WORD 2433and 2434 >&WORD 2435Of the two forms, the first is preferred. This is semantically 2436equivalent to 2437 >WORD 2>&1 2438 When using the second form, WORD may not expand to a number or '-'. 2439If it does, other redirection operators apply (see Duplicating File 2440Descriptors below) for compatibility reasons. 2441 24423.6.5 Appending Standard Output and Standard Error 2443-------------------------------------------------- 2444 2445This construct allows both the standard output (file descriptor 1) and 2446the standard error output (file descriptor 2) to be appended to the file 2447whose name is the expansion of WORD. 2448 2449 The format for appending standard output and standard error is: 2450 &>>WORD 2451This is semantically equivalent to 2452 >>WORD 2>&1 2453 (see Duplicating File Descriptors below). 2454 24553.6.6 Here Documents 2456-------------------- 2457 2458This type of redirection instructs the shell to read input from the 2459current source until a line containing only WORD (with no trailing 2460blanks) is seen. All of the lines read up to that point are then used 2461as the standard input (or file descriptor N if N is specified) for a 2462command. 2463 2464 The format of here-documents is: 2465 [N]<<[-]WORD 2466 HERE-DOCUMENT 2467 DELIMITER 2468 2469 No parameter and variable expansion, command substitution, arithmetic 2470expansion, or filename expansion is performed on WORD. If any part of 2471WORD is quoted, the DELIMITER is the result of quote removal on WORD, 2472and the lines in the here-document are not expanded. If WORD is 2473unquoted, all lines of the here-document are subjected to parameter 2474expansion, command substitution, and arithmetic expansion, the character 2475sequence '\newline' is ignored, and '\' must be used to quote the 2476characters '\', '$', and '`'. 2477 2478 If the redirection operator is '<<-', then all leading tab characters 2479are stripped from input lines and the line containing DELIMITER. This 2480allows here-documents within shell scripts to be indented in a natural 2481fashion. 2482 24833.6.7 Here Strings 2484------------------ 2485 2486A variant of here documents, the format is: 2487 [N]<<< WORD 2488 2489 The WORD undergoes tilde expansion, parameter and variable expansion, 2490command substitution, arithmetic expansion, and quote removal. Filename 2491expansion and word splitting are not performed. The result is supplied 2492as a single string, with a newline appended, to the command on its 2493standard input (or file descriptor N if N is specified). 2494 24953.6.8 Duplicating File Descriptors 2496---------------------------------- 2497 2498The redirection operator 2499 [N]<&WORD 2500is used to duplicate input file descriptors. If WORD expands to one or 2501more digits, the file descriptor denoted by N is made to be a copy of 2502that file descriptor. If the digits in WORD do not specify a file 2503descriptor open for input, a redirection error occurs. If WORD 2504evaluates to '-', file descriptor N is closed. If N is not specified, 2505the standard input (file descriptor 0) is used. 2506 2507 The operator 2508 [N]>&WORD 2509is used similarly to duplicate output file descriptors. If N is not 2510specified, the standard output (file descriptor 1) is used. If the 2511digits in WORD do not specify a file descriptor open for output, a 2512redirection error occurs. If WORD evaluates to '-', file descriptor N 2513is closed. As a special case, if N is omitted, and WORD does not expand 2514to one or more digits or '-', the standard output and standard error are 2515redirected as described previously. 2516 25173.6.9 Moving File Descriptors 2518----------------------------- 2519 2520The redirection operator 2521 [N]<&DIGIT- 2522moves the file descriptor DIGIT to file descriptor N, or the standard 2523input (file descriptor 0) if N is not specified. DIGIT is closed after 2524being duplicated to N. 2525 2526 Similarly, the redirection operator 2527 [N]>&DIGIT- 2528moves the file descriptor DIGIT to file descriptor N, or the standard 2529output (file descriptor 1) if N is not specified. 2530 25313.6.10 Opening File Descriptors for Reading and Writing 2532------------------------------------------------------- 2533 2534The redirection operator 2535 [N]<>WORD 2536causes the file whose name is the expansion of WORD to be opened for 2537both reading and writing on file descriptor N, or on file descriptor 0 2538if N is not specified. If the file does not exist, it is created. 2539 2540 2541File: bash.info, Node: Executing Commands, Next: Shell Scripts, Prev: Redirections, Up: Basic Shell Features 2542 25433.7 Executing Commands 2544====================== 2545 2546* Menu: 2547 2548* Simple Command Expansion:: How Bash expands simple commands before 2549 executing them. 2550* Command Search and Execution:: How Bash finds commands and runs them. 2551* Command Execution Environment:: The environment in which Bash 2552 executes commands that are not 2553 shell builtins. 2554* Environment:: The environment given to a command. 2555* Exit Status:: The status returned by commands and how Bash 2556 interprets it. 2557* Signals:: What happens when Bash or a command it runs 2558 receives a signal. 2559 2560 2561File: bash.info, Node: Simple Command Expansion, Next: Command Search and Execution, Up: Executing Commands 2562 25633.7.1 Simple Command Expansion 2564------------------------------ 2565 2566When a simple command is executed, the shell performs the following 2567expansions, assignments, and redirections, from left to right, in the 2568following order. 2569 2570 1. The words that the parser has marked as variable assignments (those 2571 preceding the command name) and redirections are saved for later 2572 processing. 2573 2574 2. The words that are not variable assignments or redirections are 2575 expanded (*note Shell Expansions::). If any words remain after 2576 expansion, the first word is taken to be the name of the command 2577 and the remaining words are the arguments. 2578 2579 3. Redirections are performed as described above (*note 2580 Redirections::). 2581 2582 4. The text after the '=' in each variable assignment undergoes tilde 2583 expansion, parameter expansion, command substitution, arithmetic 2584 expansion, and quote removal before being assigned to the variable. 2585 2586 If no command name results, the variable assignments affect the 2587current shell environment. Otherwise, the variables are added to the 2588environment of the executed command and do not affect the current shell 2589environment. If any of the assignments attempts to assign a value to a 2590readonly variable, an error occurs, and the command exits with a 2591non-zero status. 2592 2593 If no command name results, redirections are performed, but do not 2594affect the current shell environment. A redirection error causes the 2595command to exit with a non-zero status. 2596 2597 If there is a command name left after expansion, execution proceeds 2598as described below. Otherwise, the command exits. If one of the 2599expansions contained a command substitution, the exit status of the 2600command is the exit status of the last command substitution performed. 2601If there were no command substitutions, the command exits with a status 2602of zero. 2603 2604 2605File: bash.info, Node: Command Search and Execution, Next: Command Execution Environment, Prev: Simple Command Expansion, Up: Executing Commands 2606 26073.7.2 Command Search and Execution 2608---------------------------------- 2609 2610After a command has been split into words, if it results in a simple 2611command and an optional list of arguments, the following actions are 2612taken. 2613 2614 1. If the command name contains no slashes, the shell attempts to 2615 locate it. If there exists a shell function by that name, that 2616 function is invoked as described in *note Shell Functions::. 2617 2618 2. If the name does not match a function, the shell searches for it in 2619 the list of shell builtins. If a match is found, that builtin is 2620 invoked. 2621 2622 3. If the name is neither a shell function nor a builtin, and contains 2623 no slashes, Bash searches each element of '$PATH' for a directory 2624 containing an executable file by that name. Bash uses a hash table 2625 to remember the full pathnames of executable files to avoid 2626 multiple 'PATH' searches (see the description of 'hash' in *note 2627 Bourne Shell Builtins::). A full search of the directories in 2628 '$PATH' is performed only if the command is not found in the hash 2629 table. If the search is unsuccessful, the shell searches for a 2630 defined shell function named 'command_not_found_handle'. If that 2631 function exists, it is invoked in a separate execution environment 2632 with the original command and the original command's arguments as 2633 its arguments, and the function's exit status becomes the exit 2634 status of that subshell. If that function is not defined, the 2635 shell prints an error message and returns an exit status of 127. 2636 2637 4. If the search is successful, or if the command name contains one or 2638 more slashes, the shell executes the named program in a separate 2639 execution environment. Argument 0 is set to the name given, and 2640 the remaining arguments to the command are set to the arguments 2641 supplied, if any. 2642 2643 5. If this execution fails because the file is not in executable 2644 format, and the file is not a directory, it is assumed to be a 2645 SHELL SCRIPT and the shell executes it as described in *note Shell 2646 Scripts::. 2647 2648 6. If the command was not begun asynchronously, the shell waits for 2649 the command to complete and collects its exit status. 2650 2651 2652File: bash.info, Node: Command Execution Environment, Next: Environment, Prev: Command Search and Execution, Up: Executing Commands 2653 26543.7.3 Command Execution Environment 2655----------------------------------- 2656 2657The shell has an EXECUTION ENVIRONMENT, which consists of the following: 2658 2659 * open files inherited by the shell at invocation, as modified by 2660 redirections supplied to the 'exec' builtin 2661 2662 * the current working directory as set by 'cd', 'pushd', or 'popd', 2663 or inherited by the shell at invocation 2664 2665 * the file creation mode mask as set by 'umask' or inherited from the 2666 shell's parent 2667 2668 * current traps set by 'trap' 2669 2670 * shell parameters that are set by variable assignment or with 'set' 2671 or inherited from the shell's parent in the environment 2672 2673 * shell functions defined during execution or inherited from the 2674 shell's parent in the environment 2675 2676 * options enabled at invocation (either by default or with 2677 command-line arguments) or by 'set' 2678 2679 * options enabled by 'shopt' (*note The Shopt Builtin::) 2680 2681 * shell aliases defined with 'alias' (*note Aliases::) 2682 2683 * various process IDs, including those of background jobs (*note 2684 Lists::), the value of '$$', and the value of '$PPID' 2685 2686 When a simple command other than a builtin or shell function is to be 2687executed, it is invoked in a separate execution environment that 2688consists of the following. Unless otherwise noted, the values are 2689inherited from the shell. 2690 2691 * the shell's open files, plus any modifications and additions 2692 specified by redirections to the command 2693 2694 * the current working directory 2695 2696 * the file creation mode mask 2697 2698 * shell variables and functions marked for export, along with 2699 variables exported for the command, passed in the environment 2700 (*note Environment::) 2701 2702 * traps caught by the shell are reset to the values inherited from 2703 the shell's parent, and traps ignored by the shell are ignored 2704 2705 A command invoked in this separate environment cannot affect the 2706shell's execution environment. 2707 2708 Command substitution, commands grouped with parentheses, and 2709asynchronous commands are invoked in a subshell environment that is a 2710duplicate of the shell environment, except that traps caught by the 2711shell are reset to the values that the shell inherited from its parent 2712at invocation. Builtin commands that are invoked as part of a pipeline 2713are also executed in a subshell environment. Changes made to the 2714subshell environment cannot affect the shell's execution environment. 2715 2716 Subshells spawned to execute command substitutions inherit the value 2717of the '-e' option from the parent shell. When not in POSIX mode, Bash 2718clears the '-e' option in such subshells. 2719 2720 If a command is followed by a '&' and job control is not active, the 2721default standard input for the command is the empty file '/dev/null'. 2722Otherwise, the invoked command inherits the file descriptors of the 2723calling shell as modified by redirections. 2724 2725 2726File: bash.info, Node: Environment, Next: Exit Status, Prev: Command Execution Environment, Up: Executing Commands 2727 27283.7.4 Environment 2729----------------- 2730 2731When a program is invoked it is given an array of strings called the 2732ENVIRONMENT. This is a list of name-value pairs, of the form 2733'name=value'. 2734 2735 Bash provides several ways to manipulate the environment. On 2736invocation, the shell scans its own environment and creates a parameter 2737for each name found, automatically marking it for EXPORT to child 2738processes. Executed commands inherit the environment. The 'export' and 2739'declare -x' commands allow parameters and functions to be added to and 2740deleted from the environment. If the value of a parameter in the 2741environment is modified, the new value becomes part of the environment, 2742replacing the old. The environment inherited by any executed command 2743consists of the shell's initial environment, whose values may be 2744modified in the shell, less any pairs removed by the 'unset' and 'export 2745-n' commands, plus any additions via the 'export' and 'declare -x' 2746commands. 2747 2748 The environment for any simple command or function may be augmented 2749temporarily by prefixing it with parameter assignments, as described in 2750*note Shell Parameters::. These assignment statements affect only the 2751environment seen by that command. 2752 2753 If the '-k' option is set (*note The Set Builtin::), then all 2754parameter assignments are placed in the environment for a command, not 2755just those that precede the command name. 2756 2757 When Bash invokes an external command, the variable '$_' is set to 2758the full pathname of the command and passed to that command in its 2759environment. 2760 2761 2762File: bash.info, Node: Exit Status, Next: Signals, Prev: Environment, Up: Executing Commands 2763 27643.7.5 Exit Status 2765----------------- 2766 2767The exit status of an executed command is the value returned by the 2768WAITPID system call or equivalent function. Exit statuses fall between 27690 and 255, though, as explained below, the shell may use values above 2770125 specially. Exit statuses from shell builtins and compound commands 2771are also limited to this range. Under certain circumstances, the shell 2772will use special values to indicate specific failure modes. 2773 2774 For the shell's purposes, a command which exits with a zero exit 2775status has succeeded. A non-zero exit status indicates failure. This 2776seemingly counter-intuitive scheme is used so there is one well-defined 2777way to indicate success and a variety of ways to indicate various 2778failure modes. When a command terminates on a fatal signal whose number 2779is N, Bash uses the value 128+N as the exit status. 2780 2781 If a command is not found, the child process created to execute it 2782returns a status of 127. If a command is found but is not executable, 2783the return status is 126. 2784 2785 If a command fails because of an error during expansion or 2786redirection, the exit status is greater than zero. 2787 2788 The exit status is used by the Bash conditional commands (*note 2789Conditional Constructs::) and some of the list constructs (*note 2790Lists::). 2791 2792 All of the Bash builtins return an exit status of zero if they 2793succeed and a non-zero status on failure, so they may be used by the 2794conditional and list constructs. All builtins return an exit status of 27952 to indicate incorrect usage, generally invalid options or missing 2796arguments. 2797 2798 2799File: bash.info, Node: Signals, Prev: Exit Status, Up: Executing Commands 2800 28013.7.6 Signals 2802------------- 2803 2804When Bash is interactive, in the absence of any traps, it ignores 2805'SIGTERM' (so that 'kill 0' does not kill an interactive shell), and 2806'SIGINT' is caught and handled (so that the 'wait' builtin is 2807interruptible). When Bash receives a 'SIGINT', it breaks out of any 2808executing loops. In all cases, Bash ignores 'SIGQUIT'. If job control 2809is in effect (*note Job Control::), Bash ignores 'SIGTTIN', 'SIGTTOU', 2810and 'SIGTSTP'. 2811 2812 Non-builtin commands started by Bash have signal handlers set to the 2813values inherited by the shell from its parent. When job control is not 2814in effect, asynchronous commands ignore 'SIGINT' and 'SIGQUIT' in 2815addition to these inherited handlers. Commands run as a result of 2816command substitution ignore the keyboard-generated job control signals 2817'SIGTTIN', 'SIGTTOU', and 'SIGTSTP'. 2818 2819 The shell exits by default upon receipt of a 'SIGHUP'. Before 2820exiting, an interactive shell resends the 'SIGHUP' to all jobs, running 2821or stopped. Stopped jobs are sent 'SIGCONT' to ensure that they receive 2822the 'SIGHUP'. To prevent the shell from sending the 'SIGHUP' signal to 2823a particular job, it should be removed from the jobs table with the 2824'disown' builtin (*note Job Control Builtins::) or marked to not receive 2825'SIGHUP' using 'disown -h'. 2826 2827 If the 'huponexit' shell option has been set with 'shopt' (*note The 2828Shopt Builtin::), Bash sends a 'SIGHUP' to all jobs when an interactive 2829login shell exits. 2830 2831 If Bash is waiting for a command to complete and receives a signal 2832for which a trap has been set, the trap will not be executed until the 2833command completes. When Bash is waiting for an asynchronous command via 2834the 'wait' builtin, the reception of a signal for which a trap has been 2835set will cause the 'wait' builtin to return immediately with an exit 2836status greater than 128, immediately after which the trap is executed. 2837 2838 2839File: bash.info, Node: Shell Scripts, Prev: Executing Commands, Up: Basic Shell Features 2840 28413.8 Shell Scripts 2842================= 2843 2844A shell script is a text file containing shell commands. When such a 2845file is used as the first non-option argument when invoking Bash, and 2846neither the '-c' nor '-s' option is supplied (*note Invoking Bash::), 2847Bash reads and executes commands from the file, then exits. This mode 2848of operation creates a non-interactive shell. The shell first searches 2849for the file in the current directory, and looks in the directories in 2850'$PATH' if not found there. 2851 2852 When Bash runs a shell script, it sets the special parameter '0' to 2853the name of the file, rather than the name of the shell, and the 2854positional parameters are set to the remaining arguments, if any are 2855given. If no additional arguments are supplied, the positional 2856parameters are unset. 2857 2858 A shell script may be made executable by using the 'chmod' command to 2859turn on the execute bit. When Bash finds such a file while searching 2860the '$PATH' for a command, it spawns a subshell to execute it. In other 2861words, executing 2862 filename ARGUMENTS 2863is equivalent to executing 2864 bash filename ARGUMENTS 2865 2866if 'filename' is an executable shell script. This subshell 2867reinitializes itself, so that the effect is as if a new shell had been 2868invoked to interpret the script, with the exception that the locations 2869of commands remembered by the parent (see the description of 'hash' in 2870*note Bourne Shell Builtins::) are retained by the child. 2871 2872 Most versions of Unix make this a part of the operating system's 2873command execution mechanism. If the first line of a script begins with 2874the two characters '#!', the remainder of the line specifies an 2875interpreter for the program and, depending on the operating system, one 2876or more optional arguments for that interpreter. Thus, you can specify 2877Bash, 'awk', Perl, or some other interpreter and write the rest of the 2878script file in that language. 2879 2880 The arguments to the interpreter consist of one or more optional 2881arguments following the interpreter name on the first line of the script 2882file, followed by the name of the script file, followed by the rest of 2883the arguments supplied to the script. The details of how the 2884interpreter line is split into an interpreter name and a set of 2885arguments vary across systems. Bash will perform this action on 2886operating systems that do not handle it themselves. Note that some 2887older versions of Unix limit the interpreter name and a single argument 2888to a maximum of 32 characters, so it's not portable to assume that using 2889more than one argument will work. 2890 2891 Bash scripts often begin with '#! /bin/bash' (assuming that Bash has 2892been installed in '/bin'), since this ensures that Bash will be used to 2893interpret the script, even if it is executed under another shell. It's 2894a common idiom to use 'env' to find 'bash' even if it's been installed 2895in another directory: '#!/usr/bin/env bash' will find the first 2896occurrence of 'bash' in '$PATH'. 2897 2898 2899File: bash.info, Node: Shell Builtin Commands, Next: Shell Variables, Prev: Basic Shell Features, Up: Top 2900 29014 Shell Builtin Commands 2902************************ 2903 2904* Menu: 2905 2906* Bourne Shell Builtins:: Builtin commands inherited from the Bourne 2907 Shell. 2908* Bash Builtins:: Table of builtins specific to Bash. 2909* Modifying Shell Behavior:: Builtins to modify shell attributes and 2910 optional behavior. 2911* Special Builtins:: Builtin commands classified specially by 2912 POSIX. 2913 2914Builtin commands are contained within the shell itself. When the name 2915of a builtin command is used as the first word of a simple command 2916(*note Simple Commands::), the shell executes the command directly, 2917without invoking another program. Builtin commands are necessary to 2918implement functionality impossible or inconvenient to obtain with 2919separate utilities. 2920 2921 This section briefly describes the builtins which Bash inherits from 2922the Bourne Shell, as well as the builtin commands which are unique to or 2923have been extended in Bash. 2924 2925 Several builtin commands are described in other chapters: builtin 2926commands which provide the Bash interface to the job control facilities 2927(*note Job Control Builtins::), the directory stack (*note Directory 2928Stack Builtins::), the command history (*note Bash History Builtins::), 2929and the programmable completion facilities (*note Programmable 2930Completion Builtins::). 2931 2932 Many of the builtins have been extended by POSIX or Bash. 2933 2934 Unless otherwise noted, each builtin command documented as accepting 2935options preceded by '-' accepts '--' to signify the end of the options. 2936The ':', 'true', 'false', and 'test'/'[' builtins do not accept options 2937and do not treat '--' specially. The 'exit', 'logout', 'return', 2938'break', 'continue', 'let', and 'shift' builtins accept and process 2939arguments beginning with '-' without requiring '--'. Other builtins 2940that accept arguments but are not specified as accepting options 2941interpret arguments beginning with '-' as invalid options and require 2942'--' to prevent this interpretation. 2943 2944 2945File: bash.info, Node: Bourne Shell Builtins, Next: Bash Builtins, Up: Shell Builtin Commands 2946 29474.1 Bourne Shell Builtins 2948========================= 2949 2950The following shell builtin commands are inherited from the Bourne 2951Shell. These commands are implemented as specified by the POSIX 2952standard. 2953 2954': (a colon)' 2955 : [ARGUMENTS] 2956 2957 Do nothing beyond expanding ARGUMENTS and performing redirections. 2958 The return status is zero. 2959 2960'. (a period)' 2961 . FILENAME [ARGUMENTS] 2962 2963 Read and execute commands from the FILENAME argument in the current 2964 shell context. If FILENAME does not contain a slash, the 'PATH' 2965 variable is used to find FILENAME. When Bash is not in POSIX mode, 2966 the current directory is searched if FILENAME is not found in 2967 '$PATH'. If any ARGUMENTS are supplied, they become the positional 2968 parameters when FILENAME is executed. Otherwise the positional 2969 parameters are unchanged. If the '-T' option is enabled, 'source' 2970 inherits any trap on 'DEBUG'; if it is not, any 'DEBUG' trap string 2971 is saved and restored around the call to 'source', and 'source' 2972 unsets the 'DEBUG' trap while it executes. If '-T' is not set, and 2973 the sourced file changes the 'DEBUG' trap, the new value is 2974 retained when 'source' completes. The return status is the exit 2975 status of the last command executed, or zero if no commands are 2976 executed. If FILENAME is not found, or cannot be read, the return 2977 status is non-zero. This builtin is equivalent to 'source'. 2978 2979'break' 2980 break [N] 2981 2982 Exit from a 'for', 'while', 'until', or 'select' loop. If N is 2983 supplied, the Nth enclosing loop is exited. N must be greater than 2984 or equal to 1. The return status is zero unless N is not greater 2985 than or equal to 1. 2986 2987'cd' 2988 cd [-L|[-P [-e]] [-@] [DIRECTORY] 2989 2990 Change the current working directory to DIRECTORY. If DIRECTORY is 2991 not supplied, the value of the 'HOME' shell variable is used. Any 2992 additional arguments following DIRECTORY are ignored. If the shell 2993 variable 'CDPATH' exists, it is used as a search path: each 2994 directory name in 'CDPATH' is searched for DIRECTORY, with 2995 alternative directory names in 'CDPATH' separated by a colon (':'). 2996 If DIRECTORY begins with a slash, 'CDPATH' is not used. 2997 2998 The '-P' option means to not follow symbolic links: symbolic links 2999 are resolved while 'cd' is traversing DIRECTORY and before 3000 processing an instance of '..' in DIRECTORY. 3001 3002 By default, or when the '-L' option is supplied, symbolic links in 3003 DIRECTORY are resolved after 'cd' processes an instance of '..' in 3004 DIRECTORY. 3005 3006 If '..' appears in DIRECTORY, it is processed by removing the 3007 immediately preceding pathname component, back to a slash or the 3008 beginning of DIRECTORY. 3009 3010 If the '-e' option is supplied with '-P' and the current working 3011 directory cannot be successfully determined after a successful 3012 directory change, 'cd' will return an unsuccessful status. 3013 3014 On systems that support it, the '-@' option presents the extended 3015 attributes associated with a file as a directory. 3016 3017 If DIRECTORY is '-', it is converted to '$OLDPWD' before the 3018 directory change is attempted. 3019 3020 If a non-empty directory name from 'CDPATH' is used, or if '-' is 3021 the first argument, and the directory change is successful, the 3022 absolute pathname of the new working directory is written to the 3023 standard output. 3024 3025 The return status is zero if the directory is successfully changed, 3026 non-zero otherwise. 3027 3028'continue' 3029 continue [N] 3030 3031 Resume the next iteration of an enclosing 'for', 'while', 'until', 3032 or 'select' loop. If N is supplied, the execution of the Nth 3033 enclosing loop is resumed. N must be greater than or equal to 1. 3034 The return status is zero unless N is not greater than or equal to 3035 1. 3036 3037'eval' 3038 eval [ARGUMENTS] 3039 3040 The arguments are concatenated together into a single command, 3041 which is then read and executed, and its exit status returned as 3042 the exit status of 'eval'. If there are no arguments or only empty 3043 arguments, the return status is zero. 3044 3045'exec' 3046 exec [-cl] [-a NAME] [COMMAND [ARGUMENTS]] 3047 3048 If COMMAND is supplied, it replaces the shell without creating a 3049 new process. If the '-l' option is supplied, the shell places a 3050 dash at the beginning of the zeroth argument passed to COMMAND. 3051 This is what the 'login' program does. The '-c' option causes 3052 COMMAND to be executed with an empty environment. If '-a' is 3053 supplied, the shell passes NAME as the zeroth argument to COMMAND. 3054 If COMMAND cannot be executed for some reason, a non-interactive 3055 shell exits, unless the 'execfail' shell option is enabled. In 3056 that case, it returns failure. An interactive shell returns 3057 failure if the file cannot be executed. A subshell exits 3058 unconditionally if 'exec' fails. If no COMMAND is specified, 3059 redirections may be used to affect the current shell environment. 3060 If there are no redirection errors, the return status is zero; 3061 otherwise the return status is non-zero. 3062 3063'exit' 3064 exit [N] 3065 3066 Exit the shell, returning a status of N to the shell's parent. If 3067 N is omitted, the exit status is that of the last command executed. 3068 Any trap on 'EXIT' is executed before the shell terminates. 3069 3070'export' 3071 export [-fn] [-p] [NAME[=VALUE]] 3072 3073 Mark each NAME to be passed to child processes in the environment. 3074 If the '-f' option is supplied, the NAMEs refer to shell functions; 3075 otherwise the names refer to shell variables. The '-n' option 3076 means to no longer mark each NAME for export. If no NAMES are 3077 supplied, or if the '-p' option is given, a list of names of all 3078 exported variables is displayed. The '-p' option displays output 3079 in a form that may be reused as input. If a variable name is 3080 followed by =VALUE, the value of the variable is set to VALUE. 3081 3082 The return status is zero unless an invalid option is supplied, one 3083 of the names is not a valid shell variable name, or '-f' is 3084 supplied with a name that is not a shell function. 3085 3086'getopts' 3087 getopts OPTSTRING NAME [ARG ...] 3088 3089 'getopts' is used by shell scripts to parse positional parameters. 3090 OPTSTRING contains the option characters to be recognized; if a 3091 character is followed by a colon, the option is expected to have an 3092 argument, which should be separated from it by whitespace. The 3093 colon (':') and question mark ('?') may not be used as option 3094 characters. Each time it is invoked, 'getopts' places the next 3095 option in the shell variable NAME, initializing NAME if it does not 3096 exist, and the index of the next argument to be processed into the 3097 variable 'OPTIND'. 'OPTIND' is initialized to 1 each time the 3098 shell or a shell script is invoked. When an option requires an 3099 argument, 'getopts' places that argument into the variable 3100 'OPTARG'. The shell does not reset 'OPTIND' automatically; it must 3101 be manually reset between multiple calls to 'getopts' within the 3102 same shell invocation if a new set of parameters is to be used. 3103 3104 When the end of options is encountered, 'getopts' exits with a 3105 return value greater than zero. 'OPTIND' is set to the index of 3106 the first non-option argument, and NAME is set to '?'. 3107 3108 'getopts' normally parses the positional parameters, but if more 3109 arguments are supplied as ARG values, 'getopts' parses those 3110 instead. 3111 3112 'getopts' can report errors in two ways. If the first character of 3113 OPTSTRING is a colon, SILENT error reporting is used. In normal 3114 operation, diagnostic messages are printed when invalid options or 3115 missing option arguments are encountered. If the variable 'OPTERR' 3116 is set to 0, no error messages will be displayed, even if the first 3117 character of 'optstring' is not a colon. 3118 3119 If an invalid option is seen, 'getopts' places '?' into NAME and, 3120 if not silent, prints an error message and unsets 'OPTARG'. If 3121 'getopts' is silent, the option character found is placed in 3122 'OPTARG' and no diagnostic message is printed. 3123 3124 If a required argument is not found, and 'getopts' is not silent, a 3125 question mark ('?') is placed in NAME, 'OPTARG' is unset, and a 3126 diagnostic message is printed. If 'getopts' is silent, then a 3127 colon (':') is placed in NAME and 'OPTARG' is set to the option 3128 character found. 3129 3130'hash' 3131 hash [-r] [-p FILENAME] [-dt] [NAME] 3132 3133 Each time 'hash' is invoked, it remembers the full pathnames of the 3134 commands specified as NAME arguments, so they need not be searched 3135 for on subsequent invocations. The commands are found by searching 3136 through the directories listed in '$PATH'. Any 3137 previously-remembered pathname is discarded. The '-p' option 3138 inhibits the path search, and FILENAME is used as the location of 3139 NAME. The '-r' option causes the shell to forget all remembered 3140 locations. The '-d' option causes the shell to forget the 3141 remembered location of each NAME. If the '-t' option is supplied, 3142 the full pathname to which each NAME corresponds is printed. If 3143 multiple NAME arguments are supplied with '-t', the NAME is printed 3144 before the hashed full pathname. The '-l' option causes output to 3145 be displayed in a format that may be reused as input. If no 3146 arguments are given, or if only '-l' is supplied, information about 3147 remembered commands is printed. The return status is zero unless a 3148 NAME is not found or an invalid option is supplied. 3149 3150'pwd' 3151 pwd [-LP] 3152 3153 Print the absolute pathname of the current working directory. If 3154 the '-P' option is supplied, the pathname printed will not contain 3155 symbolic links. If the '-L' option is supplied, the pathname 3156 printed may contain symbolic links. The return status is zero 3157 unless an error is encountered while determining the name of the 3158 current directory or an invalid option is supplied. 3159 3160'readonly' 3161 readonly [-aAf] [-p] [NAME[=VALUE]] ... 3162 3163 Mark each NAME as readonly. The values of these names may not be 3164 changed by subsequent assignment. If the '-f' option is supplied, 3165 each NAME refers to a shell function. The '-a' option means each 3166 NAME refers to an indexed array variable; the '-A' option means 3167 each NAME refers to an associative array variable. If both options 3168 are supplied, '-A' takes precedence. If no NAME arguments are 3169 given, or if the '-p' option is supplied, a list of all readonly 3170 names is printed. The other options may be used to restrict the 3171 output to a subset of the set of readonly names. The '-p' option 3172 causes output to be displayed in a format that may be reused as 3173 input. If a variable name is followed by =VALUE, the value of the 3174 variable is set to VALUE. The return status is zero unless an 3175 invalid option is supplied, one of the NAME arguments is not a 3176 valid shell variable or function name, or the '-f' option is 3177 supplied with a name that is not a shell function. 3178 3179'return' 3180 return [N] 3181 3182 Cause a shell function to stop executing and return the value N to 3183 its caller. If N is not supplied, the return value is the exit 3184 status of the last command executed in the function. If 'return' 3185 is executed by a trap handler, the last command used to determine 3186 the status is the last command executed before the trap handler. 3187 If 'return' is executed during a 'DEBUG' trap, the last command 3188 used to determine the status is the last command executed by the 3189 trap handler before 'return' was invoked. 'return' may also be 3190 used to terminate execution of a script being executed with the '.' 3191 ('source') builtin, returning either N or the exit status of the 3192 last command executed within the script as the exit status of the 3193 script. If N is supplied, the return value is its least 3194 significant 8 bits. Any command associated with the 'RETURN' trap 3195 is executed before execution resumes after the function or script. 3196 The return status is non-zero if 'return' is supplied a non-numeric 3197 argument or is used outside a function and not during the execution 3198 of a script by '.' or 'source'. 3199 3200'shift' 3201 shift [N] 3202 3203 Shift the positional parameters to the left by N. The positional 3204 parameters from N+1 ... '$#' are renamed to '$1' ... '$#'-N. 3205 Parameters represented by the numbers '$#' down to '$#'-N+1 are 3206 unset. N must be a non-negative number less than or equal to '$#'. 3207 If N is zero or greater than '$#', the positional parameters are 3208 not changed. If N is not supplied, it is assumed to be 1. The 3209 return status is zero unless N is greater than '$#' or less than 3210 zero, non-zero otherwise. 3211 3212'test' 3213'[' 3214 test EXPR 3215 3216 Evaluate a conditional expression EXPR and return a status of 0 3217 (true) or 1 (false). Each operator and operand must be a separate 3218 argument. Expressions are composed of the primaries described 3219 below in *note Bash Conditional Expressions::. 'test' does not 3220 accept any options, nor does it accept and ignore an argument of 3221 '--' as signifying the end of options. 3222 3223 When the '[' form is used, the last argument to the command must be 3224 a ']'. 3225 3226 Expressions may be combined using the following operators, listed 3227 in decreasing order of precedence. The evaluation depends on the 3228 number of arguments; see below. Operator precedence is used when 3229 there are five or more arguments. 3230 3231 '! EXPR' 3232 True if EXPR is false. 3233 3234 '( EXPR )' 3235 Returns the value of EXPR. This may be used to override the 3236 normal precedence of operators. 3237 3238 'EXPR1 -a EXPR2' 3239 True if both EXPR1 and EXPR2 are true. 3240 3241 'EXPR1 -o EXPR2' 3242 True if either EXPR1 or EXPR2 is true. 3243 3244 The 'test' and '[' builtins evaluate conditional expressions using 3245 a set of rules based on the number of arguments. 3246 3247 0 arguments 3248 The expression is false. 3249 3250 1 argument 3251 The expression is true if, and only if, the argument is not 3252 null. 3253 3254 2 arguments 3255 If the first argument is '!', the expression is true if and 3256 only if the second argument is null. If the first argument is 3257 one of the unary conditional operators (*note Bash Conditional 3258 Expressions::), the expression is true if the unary test is 3259 true. If the first argument is not a valid unary operator, 3260 the expression is false. 3261 3262 3 arguments 3263 The following conditions are applied in the order listed. 3264 3265 1. If the second argument is one of the binary conditional 3266 operators (*note Bash Conditional Expressions::), the 3267 result of the expression is the result of the binary test 3268 using the first and third arguments as operands. The 3269 '-a' and '-o' operators are considered binary operators 3270 when there are three arguments. 3271 2. If the first argument is '!', the value is the negation 3272 of the two-argument test using the second and third 3273 arguments. 3274 3. If the first argument is exactly '(' and the third 3275 argument is exactly ')', the result is the one-argument 3276 test of the second argument. 3277 4. Otherwise, the expression is false. 3278 3279 4 arguments 3280 If the first argument is '!', the result is the negation of 3281 the three-argument expression composed of the remaining 3282 arguments. Otherwise, the expression is parsed and evaluated 3283 according to precedence using the rules listed above. 3284 3285 5 or more arguments 3286 The expression is parsed and evaluated according to precedence 3287 using the rules listed above. 3288 3289 When used with 'test' or '[', the '<' and '>' operators sort 3290 lexicographically using ASCII ordering. 3291 3292'times' 3293 times 3294 3295 Print out the user and system times used by the shell and its 3296 children. The return status is zero. 3297 3298'trap' 3299 trap [-lp] [ARG] [SIGSPEC ...] 3300 3301 The commands in ARG are to be read and executed when the shell 3302 receives signal SIGSPEC. If ARG is absent (and there is a single 3303 SIGSPEC) or equal to '-', each specified signal's disposition is 3304 reset to the value it had when the shell was started. If ARG is 3305 the null string, then the signal specified by each SIGSPEC is 3306 ignored by the shell and commands it invokes. If ARG is not 3307 present and '-p' has been supplied, the shell displays the trap 3308 commands associated with each SIGSPEC. If no arguments are 3309 supplied, or only '-p' is given, 'trap' prints the list of commands 3310 associated with each signal number in a form that may be reused as 3311 shell input. The '-l' option causes the shell to print a list of 3312 signal names and their corresponding numbers. Each SIGSPEC is 3313 either a signal name or a signal number. Signal names are case 3314 insensitive and the 'SIG' prefix is optional. 3315 3316 If a SIGSPEC is '0' or 'EXIT', ARG is executed when the shell 3317 exits. If a SIGSPEC is 'DEBUG', the command ARG is executed before 3318 every simple command, 'for' command, 'case' command, 'select' 3319 command, every arithmetic 'for' command, and before the first 3320 command executes in a shell function. Refer to the description of 3321 the 'extdebug' option to the 'shopt' builtin (*note The Shopt 3322 Builtin::) for details of its effect on the 'DEBUG' trap. If a 3323 SIGSPEC is 'RETURN', the command ARG is executed each time a shell 3324 function or a script executed with the '.' or 'source' builtins 3325 finishes executing. 3326 3327 If a SIGSPEC is 'ERR', the command ARG is executed whenever a 3328 pipeline (which may consist of a single simple command), a list, or 3329 a compound command returns a non-zero exit status, subject to the 3330 following conditions. The 'ERR' trap is not executed if the failed 3331 command is part of the command list immediately following an 3332 'until' or 'while' keyword, part of the test following the 'if' or 3333 'elif' reserved words, part of a command executed in a '&&' or '||' 3334 list except the command following the final '&&' or '||', any 3335 command in a pipeline but the last, or if the command's return 3336 status is being inverted using '!'. These are the same conditions 3337 obeyed by the 'errexit' ('-e') option. 3338 3339 Signals ignored upon entry to the shell cannot be trapped or reset. 3340 Trapped signals that are not being ignored are reset to their 3341 original values in a subshell or subshell environment when one is 3342 created. 3343 3344 The return status is zero unless a SIGSPEC does not specify a valid 3345 signal. 3346 3347'umask' 3348 umask [-p] [-S] [MODE] 3349 3350 Set the shell process's file creation mask to MODE. If MODE begins 3351 with a digit, it is interpreted as an octal number; if not, it is 3352 interpreted as a symbolic mode mask similar to that accepted by the 3353 'chmod' command. If MODE is omitted, the current value of the mask 3354 is printed. If the '-S' option is supplied without a MODE 3355 argument, the mask is printed in a symbolic format. If the '-p' 3356 option is supplied, and MODE is omitted, the output is in a form 3357 that may be reused as input. The return status is zero if the mode 3358 is successfully changed or if no MODE argument is supplied, and 3359 non-zero otherwise. 3360 3361 Note that when the mode is interpreted as an octal number, each 3362 number of the umask is subtracted from '7'. Thus, a umask of '022' 3363 results in permissions of '755'. 3364 3365'unset' 3366 unset [-fnv] [NAME] 3367 3368 Remove each variable or function NAME. If the '-v' option is 3369 given, each NAME refers to a shell variable and that variable is 3370 removed. If the '-f' option is given, the NAMEs refer to shell 3371 functions, and the function definition is removed. If the '-n' 3372 option is supplied, and NAME is a variable with the NAMEREF 3373 attribute, NAME will be unset rather than the variable it 3374 references. '-n' has no effect if the '-f' option is supplied. If 3375 no options are supplied, each NAME refers to a variable; if there 3376 is no variable by that name, a function with that name, if any, is 3377 unset. Readonly variables and functions may not be unset. Some 3378 shell variables lose their special behavior if they are unset; such 3379 behavior is noted in the description of the individual variables. 3380 The return status is zero unless a NAME is readonly. 3381 3382 3383File: bash.info, Node: Bash Builtins, Next: Modifying Shell Behavior, Prev: Bourne Shell Builtins, Up: Shell Builtin Commands 3384 33854.2 Bash Builtin Commands 3386========================= 3387 3388This section describes builtin commands which are unique to or have been 3389extended in Bash. Some of these commands are specified in the POSIX 3390standard. 3391 3392'alias' 3393 alias [-p] [NAME[=VALUE] ...] 3394 3395 Without arguments or with the '-p' option, 'alias' prints the list 3396 of aliases on the standard output in a form that allows them to be 3397 reused as input. If arguments are supplied, an alias is defined 3398 for each NAME whose VALUE is given. If no VALUE is given, the name 3399 and value of the alias is printed. Aliases are described in *note 3400 Aliases::. 3401 3402'bind' 3403 bind [-m KEYMAP] [-lpsvPSVX] 3404 bind [-m KEYMAP] [-q FUNCTION] [-u FUNCTION] [-r KEYSEQ] 3405 bind [-m KEYMAP] -f FILENAME 3406 bind [-m KEYMAP] -x KEYSEQ:SHELL-COMMAND 3407 bind [-m KEYMAP] KEYSEQ:FUNCTION-NAME 3408 bind [-m KEYMAP] KEYSEQ:READLINE-COMMAND 3409 3410 Display current Readline (*note Command Line Editing::) key and 3411 function bindings, bind a key sequence to a Readline function or 3412 macro, or set a Readline variable. Each non-option argument is a 3413 command as it would appear in a Readline initialization file (*note 3414 Readline Init File::), but each binding or command must be passed 3415 as a separate argument; e.g., '"\C-x\C-r":re-read-init-file'. 3416 3417 Options, if supplied, have the following meanings: 3418 3419 '-m KEYMAP' 3420 Use KEYMAP as the keymap to be affected by the subsequent 3421 bindings. Acceptable KEYMAP names are 'emacs', 3422 'emacs-standard', 'emacs-meta', 'emacs-ctlx', 'vi', 'vi-move', 3423 'vi-command', and 'vi-insert'. 'vi' is equivalent to 3424 'vi-command' ('vi-move' is also a synonym); 'emacs' is 3425 equivalent to 'emacs-standard'. 3426 3427 '-l' 3428 List the names of all Readline functions. 3429 3430 '-p' 3431 Display Readline function names and bindings in such a way 3432 that they can be used as input or in a Readline initialization 3433 file. 3434 3435 '-P' 3436 List current Readline function names and bindings. 3437 3438 '-v' 3439 Display Readline variable names and values in such a way that 3440 they can be used as input or in a Readline initialization 3441 file. 3442 3443 '-V' 3444 List current Readline variable names and values. 3445 3446 '-s' 3447 Display Readline key sequences bound to macros and the strings 3448 they output in such a way that they can be used as input or in 3449 a Readline initialization file. 3450 3451 '-S' 3452 Display Readline key sequences bound to macros and the strings 3453 they output. 3454 3455 '-f FILENAME' 3456 Read key bindings from FILENAME. 3457 3458 '-q FUNCTION' 3459 Query about which keys invoke the named FUNCTION. 3460 3461 '-u FUNCTION' 3462 Unbind all keys bound to the named FUNCTION. 3463 3464 '-r KEYSEQ' 3465 Remove any current binding for KEYSEQ. 3466 3467 '-x KEYSEQ:SHELL-COMMAND' 3468 Cause SHELL-COMMAND to be executed whenever KEYSEQ is entered. 3469 When SHELL-COMMAND is executed, the shell sets the 3470 'READLINE_LINE' variable to the contents of the Readline line 3471 buffer and the 'READLINE_POINT' and 'READLINE_MARK' variables 3472 to the current location of the insertion point and the saved 3473 insertion point (the MARK), respectively. If the executed 3474 command changes the value of any of 'READLINE_LINE', 3475 'READLINE_POINT', or 'READLINE_MARK', those new values will be 3476 reflected in the editing state. 3477 3478 '-X' 3479 List all key sequences bound to shell commands and the 3480 associated commands in a format that can be reused as input. 3481 3482 The return status is zero unless an invalid option is supplied or 3483 an error occurs. 3484 3485'builtin' 3486 builtin [SHELL-BUILTIN [ARGS]] 3487 3488 Run a shell builtin, passing it ARGS, and return its exit status. 3489 This is useful when defining a shell function with the same name as 3490 a shell builtin, retaining the functionality of the builtin within 3491 the function. The return status is non-zero if SHELL-BUILTIN is 3492 not a shell builtin command. 3493 3494'caller' 3495 caller [EXPR] 3496 3497 Returns the context of any active subroutine call (a shell function 3498 or a script executed with the '.' or 'source' builtins). 3499 3500 Without EXPR, 'caller' displays the line number and source filename 3501 of the current subroutine call. If a non-negative integer is 3502 supplied as EXPR, 'caller' displays the line number, subroutine 3503 name, and source file corresponding to that position in the current 3504 execution call stack. This extra information may be used, for 3505 example, to print a stack trace. The current frame is frame 0. 3506 3507 The return value is 0 unless the shell is not executing a 3508 subroutine call or EXPR does not correspond to a valid position in 3509 the call stack. 3510 3511'command' 3512 command [-pVv] COMMAND [ARGUMENTS ...] 3513 3514 Runs COMMAND with ARGUMENTS ignoring any shell function named 3515 COMMAND. Only shell builtin commands or commands found by 3516 searching the 'PATH' are executed. If there is a shell function 3517 named 'ls', running 'command ls' within the function will execute 3518 the external command 'ls' instead of calling the function 3519 recursively. The '-p' option means to use a default value for 3520 'PATH' that is guaranteed to find all of the standard utilities. 3521 The return status in this case is 127 if COMMAND cannot be found or 3522 an error occurred, and the exit status of COMMAND otherwise. 3523 3524 If either the '-V' or '-v' option is supplied, a description of 3525 COMMAND is printed. The '-v' option causes a single word 3526 indicating the command or file name used to invoke COMMAND to be 3527 displayed; the '-V' option produces a more verbose description. In 3528 this case, the return status is zero if COMMAND is found, and 3529 non-zero if not. 3530 3531'declare' 3532 declare [-aAfFgiIlnrtux] [-p] [NAME[=VALUE] ...] 3533 3534 Declare variables and give them attributes. If no NAMEs are given, 3535 then display the values of variables instead. 3536 3537 The '-p' option will display the attributes and values of each 3538 NAME. When '-p' is used with NAME arguments, additional options, 3539 other than '-f' and '-F', are ignored. 3540 3541 When '-p' is supplied without NAME arguments, 'declare' will 3542 display the attributes and values of all variables having the 3543 attributes specified by the additional options. If no other 3544 options are supplied with '-p', 'declare' will display the 3545 attributes and values of all shell variables. The '-f' option will 3546 restrict the display to shell functions. 3547 3548 The '-F' option inhibits the display of function definitions; only 3549 the function name and attributes are printed. If the 'extdebug' 3550 shell option is enabled using 'shopt' (*note The Shopt Builtin::), 3551 the source file name and line number where each NAME is defined are 3552 displayed as well. '-F' implies '-f'. 3553 3554 The '-g' option forces variables to be created or modified at the 3555 global scope, even when 'declare' is executed in a shell function. 3556 It is ignored in all other cases. 3557 3558 The '-I' option causes local variables to inherit the attributes 3559 (except the NAMEREF attribute) and value of any existing variable 3560 with the same NAME at a surrounding scope. If there is no existing 3561 variable, the local variable is initially unset. 3562 3563 The following options can be used to restrict output to variables 3564 with the specified attributes or to give variables attributes: 3565 3566 '-a' 3567 Each NAME is an indexed array variable (*note Arrays::). 3568 3569 '-A' 3570 Each NAME is an associative array variable (*note Arrays::). 3571 3572 '-f' 3573 Use function names only. 3574 3575 '-i' 3576 The variable is to be treated as an integer; arithmetic 3577 evaluation (*note Shell Arithmetic::) is performed when the 3578 variable is assigned a value. 3579 3580 '-l' 3581 When the variable is assigned a value, all upper-case 3582 characters are converted to lower-case. The upper-case 3583 attribute is disabled. 3584 3585 '-n' 3586 Give each NAME the NAMEREF attribute, making it a name 3587 reference to another variable. That other variable is defined 3588 by the value of NAME. All references, assignments, and 3589 attribute modifications to NAME, except for those using or 3590 changing the '-n' attribute itself, are performed on the 3591 variable referenced by NAME's value. The nameref attribute 3592 cannot be applied to array variables. 3593 3594 '-r' 3595 Make NAMEs readonly. These names cannot then be assigned 3596 values by subsequent assignment statements or unset. 3597 3598 '-t' 3599 Give each NAME the 'trace' attribute. Traced functions 3600 inherit the 'DEBUG' and 'RETURN' traps from the calling shell. 3601 The trace attribute has no special meaning for variables. 3602 3603 '-u' 3604 When the variable is assigned a value, all lower-case 3605 characters are converted to upper-case. The lower-case 3606 attribute is disabled. 3607 3608 '-x' 3609 Mark each NAME for export to subsequent commands via the 3610 environment. 3611 3612 Using '+' instead of '-' turns off the attribute instead, with the 3613 exceptions that '+a' and '+A' may not be used to destroy array 3614 variables and '+r' will not remove the readonly attribute. When 3615 used in a function, 'declare' makes each NAME local, as with the 3616 'local' command, unless the '-g' option is used. If a variable 3617 name is followed by =VALUE, the value of the variable is set to 3618 VALUE. 3619 3620 When using '-a' or '-A' and the compound assignment syntax to 3621 create array variables, additional attributes do not take effect 3622 until subsequent assignments. 3623 3624 The return status is zero unless an invalid option is encountered, 3625 an attempt is made to define a function using '-f foo=bar', an 3626 attempt is made to assign a value to a readonly variable, an 3627 attempt is made to assign a value to an array variable without 3628 using the compound assignment syntax (*note Arrays::), one of the 3629 NAMES is not a valid shell variable name, an attempt is made to 3630 turn off readonly status for a readonly variable, an attempt is 3631 made to turn off array status for an array variable, or an attempt 3632 is made to display a non-existent function with '-f'. 3633 3634'echo' 3635 echo [-neE] [ARG ...] 3636 3637 Output the ARGs, separated by spaces, terminated with a newline. 3638 The return status is 0 unless a write error occurs. If '-n' is 3639 specified, the trailing newline is suppressed. If the '-e' option 3640 is given, interpretation of the following backslash-escaped 3641 characters is enabled. The '-E' option disables the interpretation 3642 of these escape characters, even on systems where they are 3643 interpreted by default. The 'xpg_echo' shell option may be used to 3644 dynamically determine whether or not 'echo' expands these escape 3645 characters by default. 'echo' does not interpret '--' to mean the 3646 end of options. 3647 3648 'echo' interprets the following escape sequences: 3649 '\a' 3650 alert (bell) 3651 '\b' 3652 backspace 3653 '\c' 3654 suppress further output 3655 '\e' 3656 '\E' 3657 escape 3658 '\f' 3659 form feed 3660 '\n' 3661 new line 3662 '\r' 3663 carriage return 3664 '\t' 3665 horizontal tab 3666 '\v' 3667 vertical tab 3668 '\\' 3669 backslash 3670 '\0NNN' 3671 the eight-bit character whose value is the octal value NNN 3672 (zero to three octal digits) 3673 '\xHH' 3674 the eight-bit character whose value is the hexadecimal value 3675 HH (one or two hex digits) 3676 '\uHHHH' 3677 the Unicode (ISO/IEC 10646) character whose value is the 3678 hexadecimal value HHHH (one to four hex digits) 3679 '\UHHHHHHHH' 3680 the Unicode (ISO/IEC 10646) character whose value is the 3681 hexadecimal value HHHHHHHH (one to eight hex digits) 3682 3683'enable' 3684 enable [-a] [-dnps] [-f FILENAME] [NAME ...] 3685 3686 Enable and disable builtin shell commands. Disabling a builtin 3687 allows a disk command which has the same name as a shell builtin to 3688 be executed without specifying a full pathname, even though the 3689 shell normally searches for builtins before disk commands. If '-n' 3690 is used, the NAMEs become disabled. Otherwise NAMEs are enabled. 3691 For example, to use the 'test' binary found via '$PATH' instead of 3692 the shell builtin version, type 'enable -n test'. 3693 3694 If the '-p' option is supplied, or no NAME arguments appear, a list 3695 of shell builtins is printed. With no other arguments, the list 3696 consists of all enabled shell builtins. The '-a' option means to 3697 list each builtin with an indication of whether or not it is 3698 enabled. 3699 3700 The '-f' option means to load the new builtin command NAME from 3701 shared object FILENAME, on systems that support dynamic loading. 3702 The '-d' option will delete a builtin loaded with '-f'. 3703 3704 If there are no options, a list of the shell builtins is displayed. 3705 The '-s' option restricts 'enable' to the POSIX special builtins. 3706 If '-s' is used with '-f', the new builtin becomes a special 3707 builtin (*note Special Builtins::). 3708 3709 The return status is zero unless a NAME is not a shell builtin or 3710 there is an error loading a new builtin from a shared object. 3711 3712'help' 3713 help [-dms] [PATTERN] 3714 3715 Display helpful information about builtin commands. If PATTERN is 3716 specified, 'help' gives detailed help on all commands matching 3717 PATTERN, otherwise a list of the builtins is printed. 3718 3719 Options, if supplied, have the following meanings: 3720 3721 '-d' 3722 Display a short description of each PATTERN 3723 '-m' 3724 Display the description of each PATTERN in a manpage-like 3725 format 3726 '-s' 3727 Display only a short usage synopsis for each PATTERN 3728 3729 The return status is zero unless no command matches PATTERN. 3730 3731'let' 3732 let EXPRESSION [EXPRESSION ...] 3733 3734 The 'let' builtin allows arithmetic to be performed on shell 3735 variables. Each EXPRESSION is evaluated according to the rules 3736 given below in *note Shell Arithmetic::. If the last EXPRESSION 3737 evaluates to 0, 'let' returns 1; otherwise 0 is returned. 3738 3739'local' 3740 local [OPTION] NAME[=VALUE] ... 3741 3742 For each argument, a local variable named NAME is created, and 3743 assigned VALUE. The OPTION can be any of the options accepted by 3744 'declare'. 'local' can only be used within a function; it makes 3745 the variable NAME have a visible scope restricted to that function 3746 and its children. If NAME is '-', the set of shell options is made 3747 local to the function in which 'local' is invoked: shell options 3748 changed using the 'set' builtin inside the function are restored to 3749 their original values when the function returns. The restore is 3750 effected as if a series of 'set' commands were executed to restore 3751 the values that were in place before the function. The return 3752 status is zero unless 'local' is used outside a function, an 3753 invalid NAME is supplied, or NAME is a readonly variable. 3754 3755'logout' 3756 logout [N] 3757 3758 Exit a login shell, returning a status of N to the shell's parent. 3759 3760'mapfile' 3761 mapfile [-d DELIM] [-n COUNT] [-O ORIGIN] [-s COUNT] 3762 [-t] [-u FD] [-C CALLBACK] [-c QUANTUM] [ARRAY] 3763 3764 Read lines from the standard input into the indexed array variable 3765 ARRAY, or from file descriptor FD if the '-u' option is supplied. 3766 The variable 'MAPFILE' is the default ARRAY. Options, if supplied, 3767 have the following meanings: 3768 3769 '-d' 3770 The first character of DELIM is used to terminate each input 3771 line, rather than newline. If DELIM is the empty string, 3772 'mapfile' will terminate a line when it reads a NUL character. 3773 '-n' 3774 Copy at most COUNT lines. If COUNT is 0, all lines are 3775 copied. 3776 '-O' 3777 Begin assigning to ARRAY at index ORIGIN. The default index 3778 is 0. 3779 '-s' 3780 Discard the first COUNT lines read. 3781 '-t' 3782 Remove a trailing DELIM (default newline) from each line read. 3783 '-u' 3784 Read lines from file descriptor FD instead of the standard 3785 input. 3786 '-C' 3787 Evaluate CALLBACK each time QUANTUM lines are read. The '-c' 3788 option specifies QUANTUM. 3789 '-c' 3790 Specify the number of lines read between each call to 3791 CALLBACK. 3792 3793 If '-C' is specified without '-c', the default quantum is 5000. 3794 When CALLBACK is evaluated, it is supplied the index of the next 3795 array element to be assigned and the line to be assigned to that 3796 element as additional arguments. CALLBACK is evaluated after the 3797 line is read but before the array element is assigned. 3798 3799 If not supplied with an explicit origin, 'mapfile' will clear ARRAY 3800 before assigning to it. 3801 3802 'mapfile' returns successfully unless an invalid option or option 3803 argument is supplied, ARRAY is invalid or unassignable, or ARRAY is 3804 not an indexed array. 3805 3806'printf' 3807 printf [-v VAR] FORMAT [ARGUMENTS] 3808 3809 Write the formatted ARGUMENTS to the standard output under the 3810 control of the FORMAT. The '-v' option causes the output to be 3811 assigned to the variable VAR rather than being printed to the 3812 standard output. 3813 3814 The FORMAT is a character string which contains three types of 3815 objects: plain characters, which are simply copied to standard 3816 output, character escape sequences, which are converted and copied 3817 to the standard output, and format specifications, each of which 3818 causes printing of the next successive ARGUMENT. In addition to 3819 the standard 'printf(1)' formats, 'printf' interprets the following 3820 extensions: 3821 3822 '%b' 3823 Causes 'printf' to expand backslash escape sequences in the 3824 corresponding ARGUMENT in the same way as 'echo -e' (*note 3825 Bash Builtins::). 3826 '%q' 3827 Causes 'printf' to output the corresponding ARGUMENT in a 3828 format that can be reused as shell input. 3829 '%(DATEFMT)T' 3830 Causes 'printf' to output the date-time string resulting from 3831 using DATEFMT as a format string for 'strftime'(3). The 3832 corresponding ARGUMENT is an integer representing the number 3833 of seconds since the epoch. Two special argument values may 3834 be used: -1 represents the current time, and -2 represents the 3835 time the shell was invoked. If no argument is specified, 3836 conversion behaves as if -1 had been given. This is an 3837 exception to the usual 'printf' behavior. 3838 3839 The %b, %q, and %T directives all use the field width and precision 3840 arguments from the format specification and write that many bytes 3841 from (or use that wide a field for) the expanded argument, which 3842 usually contains more characters than the original. 3843 3844 Arguments to non-string format specifiers are treated as C language 3845 constants, except that a leading plus or minus sign is allowed, and 3846 if the leading character is a single or double quote, the value is 3847 the ASCII value of the following character. 3848 3849 The FORMAT is reused as necessary to consume all of the ARGUMENTS. 3850 If the FORMAT requires more ARGUMENTS than are supplied, the extra 3851 format specifications behave as if a zero value or null string, as 3852 appropriate, had been supplied. The return value is zero on 3853 success, non-zero on failure. 3854 3855'read' 3856 read [-ers] [-a ANAME] [-d DELIM] [-i TEXT] [-n NCHARS] 3857 [-N NCHARS] [-p PROMPT] [-t TIMEOUT] [-u FD] [NAME ...] 3858 3859 One line is read from the standard input, or from the file 3860 descriptor FD supplied as an argument to the '-u' option, split 3861 into words as described above in *note Word Splitting::, and the 3862 first word is assigned to the first NAME, the second word to the 3863 second NAME, and so on. If there are more words than names, the 3864 remaining words and their intervening delimiters are assigned to 3865 the last NAME. If there are fewer words read from the input stream 3866 than names, the remaining names are assigned empty values. The 3867 characters in the value of the 'IFS' variable are used to split the 3868 line into words using the same rules the shell uses for expansion 3869 (described above in *note Word Splitting::). The backslash 3870 character '\' may be used to remove any special meaning for the 3871 next character read and for line continuation. 3872 3873 Options, if supplied, have the following meanings: 3874 3875 '-a ANAME' 3876 The words are assigned to sequential indices of the array 3877 variable ANAME, starting at 0. All elements are removed from 3878 ANAME before the assignment. Other NAME arguments are 3879 ignored. 3880 3881 '-d DELIM' 3882 The first character of DELIM is used to terminate the input 3883 line, rather than newline. If DELIM is the empty string, 3884 'read' will terminate a line when it reads a NUL character. 3885 3886 '-e' 3887 Readline (*note Command Line Editing::) is used to obtain the 3888 line. Readline uses the current (or default, if line editing 3889 was not previously active) editing settings, but uses 3890 Readline's default filename completion. 3891 3892 '-i TEXT' 3893 If Readline is being used to read the line, TEXT is placed 3894 into the editing buffer before editing begins. 3895 3896 '-n NCHARS' 3897 'read' returns after reading NCHARS characters rather than 3898 waiting for a complete line of input, but honors a delimiter 3899 if fewer than NCHARS characters are read before the delimiter. 3900 3901 '-N NCHARS' 3902 'read' returns after reading exactly NCHARS characters rather 3903 than waiting for a complete line of input, unless EOF is 3904 encountered or 'read' times out. Delimiter characters 3905 encountered in the input are not treated specially and do not 3906 cause 'read' to return until NCHARS characters are read. The 3907 result is not split on the characters in 'IFS'; the intent is 3908 that the variable is assigned exactly the characters read 3909 (with the exception of backslash; see the '-r' option below). 3910 3911 '-p PROMPT' 3912 Display PROMPT, without a trailing newline, before attempting 3913 to read any input. The prompt is displayed only if input is 3914 coming from a terminal. 3915 3916 '-r' 3917 If this option is given, backslash does not act as an escape 3918 character. The backslash is considered to be part of the 3919 line. In particular, a backslash-newline pair may not then be 3920 used as a line continuation. 3921 3922 '-s' 3923 Silent mode. If input is coming from a terminal, characters 3924 are not echoed. 3925 3926 '-t TIMEOUT' 3927 Cause 'read' to time out and return failure if a complete line 3928 of input (or a specified number of characters) is not read 3929 within TIMEOUT seconds. TIMEOUT may be a decimal number with 3930 a fractional portion following the decimal point. This option 3931 is only effective if 'read' is reading input from a terminal, 3932 pipe, or other special file; it has no effect when reading 3933 from regular files. If 'read' times out, 'read' saves any 3934 partial input read into the specified variable NAME. If 3935 TIMEOUT is 0, 'read' returns immediately, without trying to 3936 read any data. The exit status is 0 if input is available on 3937 the specified file descriptor, non-zero otherwise. The exit 3938 status is greater than 128 if the timeout is exceeded. 3939 3940 '-u FD' 3941 Read input from file descriptor FD. 3942 3943 If no NAMEs are supplied, the line read, without the ending 3944 delimiter but otherwise unmodified, is assigned to the variable 3945 'REPLY'. The exit status is zero, unless end-of-file is 3946 encountered, 'read' times out (in which case the status is greater 3947 than 128), a variable assignment error (such as assigning to a 3948 readonly variable) occurs, or an invalid file descriptor is 3949 supplied as the argument to '-u'. 3950 3951'readarray' 3952 readarray [-d DELIM] [-n COUNT] [-O ORIGIN] [-s COUNT] 3953 [-t] [-u FD] [-C CALLBACK] [-c QUANTUM] [ARRAY] 3954 3955 Read lines from the standard input into the indexed array variable 3956 ARRAY, or from file descriptor FD if the '-u' option is supplied. 3957 3958 A synonym for 'mapfile'. 3959 3960'source' 3961 source FILENAME 3962 3963 A synonym for '.' (*note Bourne Shell Builtins::). 3964 3965'type' 3966 type [-afptP] [NAME ...] 3967 3968 For each NAME, indicate how it would be interpreted if used as a 3969 command name. 3970 3971 If the '-t' option is used, 'type' prints a single word which is 3972 one of 'alias', 'function', 'builtin', 'file' or 'keyword', if NAME 3973 is an alias, shell function, shell builtin, disk file, or shell 3974 reserved word, respectively. If the NAME is not found, then 3975 nothing is printed, and 'type' returns a failure status. 3976 3977 If the '-p' option is used, 'type' either returns the name of the 3978 disk file that would be executed, or nothing if '-t' would not 3979 return 'file'. 3980 3981 The '-P' option forces a path search for each NAME, even if '-t' 3982 would not return 'file'. 3983 3984 If a command is hashed, '-p' and '-P' print the hashed value, which 3985 is not necessarily the file that appears first in '$PATH'. 3986 3987 If the '-a' option is used, 'type' returns all of the places that 3988 contain an executable named FILE. This includes aliases and 3989 functions, if and only if the '-p' option is not also used. 3990 3991 If the '-f' option is used, 'type' does not attempt to find shell 3992 functions, as with the 'command' builtin. 3993 3994 The return status is zero if all of the NAMES are found, non-zero 3995 if any are not found. 3996 3997'typeset' 3998 typeset [-afFgrxilnrtux] [-p] [NAME[=VALUE] ...] 3999 4000 The 'typeset' command is supplied for compatibility with the Korn 4001 shell. It is a synonym for the 'declare' builtin command. 4002 4003'ulimit' 4004 ulimit [-HS] -a 4005 ulimit [-HS] [-bcdefiklmnpqrstuvxPRT] [LIMIT] 4006 4007 'ulimit' provides control over the resources available to processes 4008 started by the shell, on systems that allow such control. If an 4009 option is given, it is interpreted as follows: 4010 4011 '-S' 4012 Change and report the soft limit associated with a resource. 4013 4014 '-H' 4015 Change and report the hard limit associated with a resource. 4016 4017 '-a' 4018 All current limits are reported; no limits are set. 4019 4020 '-b' 4021 The maximum socket buffer size. 4022 4023 '-c' 4024 The maximum size of core files created. 4025 4026 '-d' 4027 The maximum size of a process's data segment. 4028 4029 '-e' 4030 The maximum scheduling priority ("nice"). 4031 4032 '-f' 4033 The maximum size of files written by the shell and its 4034 children. 4035 4036 '-i' 4037 The maximum number of pending signals. 4038 4039 '-k' 4040 The maximum number of kqueues that may be allocated. 4041 4042 '-l' 4043 The maximum size that may be locked into memory. 4044 4045 '-m' 4046 The maximum resident set size (many systems do not honor this 4047 limit). 4048 4049 '-n' 4050 The maximum number of open file descriptors (most systems do 4051 not allow this value to be set). 4052 4053 '-p' 4054 The pipe buffer size. 4055 4056 '-q' 4057 The maximum number of bytes in POSIX message queues. 4058 4059 '-r' 4060 The maximum real-time scheduling priority. 4061 4062 '-s' 4063 The maximum stack size. 4064 4065 '-t' 4066 The maximum amount of cpu time in seconds. 4067 4068 '-u' 4069 The maximum number of processes available to a single user. 4070 4071 '-v' 4072 The maximum amount of virtual memory available to the shell, 4073 and, on some systems, to its children. 4074 4075 '-x' 4076 The maximum number of file locks. 4077 4078 '-P' 4079 The maximum number of pseudoterminals. 4080 4081 '-R' 4082 The maximum time a real-time process can run before blocking, 4083 in microseconds. 4084 4085 '-T' 4086 The maximum number of threads. 4087 4088 If LIMIT is given, and the '-a' option is not used, LIMIT is the 4089 new value of the specified resource. The special LIMIT values 4090 'hard', 'soft', and 'unlimited' stand for the current hard limit, 4091 the current soft limit, and no limit, respectively. A hard limit 4092 cannot be increased by a non-root user once it is set; a soft limit 4093 may be increased up to the value of the hard limit. Otherwise, the 4094 current value of the soft limit for the specified resource is 4095 printed, unless the '-H' option is supplied. When more than one 4096 resource is specified, the limit name and unit, if appropriate, are 4097 printed before the value. When setting new limits, if neither '-H' 4098 nor '-S' is supplied, both the hard and soft limits are set. If no 4099 option is given, then '-f' is assumed. Values are in 1024-byte 4100 increments, except for '-t', which is in seconds; '-R', which is in 4101 microseconds; '-p', which is in units of 512-byte blocks; '-P', 4102 '-T', '-b', '-k', '-n' and '-u', which are unscaled values; and, 4103 when in POSIX Mode (*note Bash POSIX Mode::), '-c' and '-f', which 4104 are in 512-byte increments. 4105 4106 The return status is zero unless an invalid option or argument is 4107 supplied, or an error occurs while setting a new limit. 4108 4109'unalias' 4110 unalias [-a] [NAME ... ] 4111 4112 Remove each NAME from the list of aliases. If '-a' is supplied, 4113 all aliases are removed. Aliases are described in *note Aliases::. 4114 4115 4116File: bash.info, Node: Modifying Shell Behavior, Next: Special Builtins, Prev: Bash Builtins, Up: Shell Builtin Commands 4117 41184.3 Modifying Shell Behavior 4119============================ 4120 4121* Menu: 4122 4123* The Set Builtin:: Change the values of shell attributes and 4124 positional parameters. 4125* The Shopt Builtin:: Modify shell optional behavior. 4126 4127 4128File: bash.info, Node: The Set Builtin, Next: The Shopt Builtin, Up: Modifying Shell Behavior 4129 41304.3.1 The Set Builtin 4131--------------------- 4132 4133This builtin is so complicated that it deserves its own section. 'set' 4134allows you to change the values of shell options and set the positional 4135parameters, or to display the names and values of shell variables. 4136 4137'set' 4138 set [--abefhkmnptuvxBCEHPT] [-o OPTION-NAME] [ARGUMENT ...] 4139 set [+abefhkmnptuvxBCEHPT] [+o OPTION-NAME] [ARGUMENT ...] 4140 4141 If no options or arguments are supplied, 'set' displays the names 4142 and values of all shell variables and functions, sorted according 4143 to the current locale, in a format that may be reused as input for 4144 setting or resetting the currently-set variables. Read-only 4145 variables cannot be reset. In POSIX mode, only shell variables are 4146 listed. 4147 4148 When options are supplied, they set or unset shell attributes. 4149 Options, if specified, have the following meanings: 4150 4151 '-a' 4152 Each variable or function that is created or modified is given 4153 the export attribute and marked for export to the environment 4154 of subsequent commands. 4155 4156 '-b' 4157 Cause the status of terminated background jobs to be reported 4158 immediately, rather than before printing the next primary 4159 prompt. 4160 4161 '-e' 4162 Exit immediately if a pipeline (*note Pipelines::), which may 4163 consist of a single simple command (*note Simple Commands::), 4164 a list (*note Lists::), or a compound command (*note Compound 4165 Commands::) returns a non-zero status. The shell does not 4166 exit if the command that fails is part of the command list 4167 immediately following a 'while' or 'until' keyword, part of 4168 the test in an 'if' statement, part of any command executed in 4169 a '&&' or '||' list except the command following the final 4170 '&&' or '||', any command in a pipeline but the last, or if 4171 the command's return status is being inverted with '!'. If a 4172 compound command other than a subshell returns a non-zero 4173 status because a command failed while '-e' was being ignored, 4174 the shell does not exit. A trap on 'ERR', if set, is executed 4175 before the shell exits. 4176 4177 This option applies to the shell environment and each subshell 4178 environment separately (*note Command Execution 4179 Environment::), and may cause subshells to exit before 4180 executing all the commands in the subshell. 4181 4182 If a compound command or shell function executes in a context 4183 where '-e' is being ignored, none of the commands executed 4184 within the compound command or function body will be affected 4185 by the '-e' setting, even if '-e' is set and a command returns 4186 a failure status. If a compound command or shell function 4187 sets '-e' while executing in a context where '-e' is ignored, 4188 that setting will not have any effect until the compound 4189 command or the command containing the function call completes. 4190 4191 '-f' 4192 Disable filename expansion (globbing). 4193 4194 '-h' 4195 Locate and remember (hash) commands as they are looked up for 4196 execution. This option is enabled by default. 4197 4198 '-k' 4199 All arguments in the form of assignment statements are placed 4200 in the environment for a command, not just those that precede 4201 the command name. 4202 4203 '-m' 4204 Job control is enabled (*note Job Control::). All processes 4205 run in a separate process group. When a background job 4206 completes, the shell prints a line containing its exit status. 4207 4208 '-n' 4209 Read commands but do not execute them. This may be used to 4210 check a script for syntax errors. This option is ignored by 4211 interactive shells. 4212 4213 '-o OPTION-NAME' 4214 4215 Set the option corresponding to OPTION-NAME: 4216 4217 'allexport' 4218 Same as '-a'. 4219 4220 'braceexpand' 4221 Same as '-B'. 4222 4223 'emacs' 4224 Use an 'emacs'-style line editing interface (*note 4225 Command Line Editing::). This also affects the editing 4226 interface used for 'read -e'. 4227 4228 'errexit' 4229 Same as '-e'. 4230 4231 'errtrace' 4232 Same as '-E'. 4233 4234 'functrace' 4235 Same as '-T'. 4236 4237 'hashall' 4238 Same as '-h'. 4239 4240 'histexpand' 4241 Same as '-H'. 4242 4243 'history' 4244 Enable command history, as described in *note Bash 4245 History Facilities::. This option is on by default in 4246 interactive shells. 4247 4248 'ignoreeof' 4249 An interactive shell will not exit upon reading EOF. 4250 4251 'keyword' 4252 Same as '-k'. 4253 4254 'monitor' 4255 Same as '-m'. 4256 4257 'noclobber' 4258 Same as '-C'. 4259 4260 'noexec' 4261 Same as '-n'. 4262 4263 'noglob' 4264 Same as '-f'. 4265 4266 'nolog' 4267 Currently ignored. 4268 4269 'notify' 4270 Same as '-b'. 4271 4272 'nounset' 4273 Same as '-u'. 4274 4275 'onecmd' 4276 Same as '-t'. 4277 4278 'physical' 4279 Same as '-P'. 4280 4281 'pipefail' 4282 If set, the return value of a pipeline is the value of 4283 the last (rightmost) command to exit with a non-zero 4284 status, or zero if all commands in the pipeline exit 4285 successfully. This option is disabled by default. 4286 4287 'posix' 4288 Change the behavior of Bash where the default operation 4289 differs from the POSIX standard to match the standard 4290 (*note Bash POSIX Mode::). This is intended to make Bash 4291 behave as a strict superset of that standard. 4292 4293 'privileged' 4294 Same as '-p'. 4295 4296 'verbose' 4297 Same as '-v'. 4298 4299 'vi' 4300 Use a 'vi'-style line editing interface. This also 4301 affects the editing interface used for 'read -e'. 4302 4303 'xtrace' 4304 Same as '-x'. 4305 4306 '-p' 4307 Turn on privileged mode. In this mode, the '$BASH_ENV' and 4308 '$ENV' files are not processed, shell functions are not 4309 inherited from the environment, and the 'SHELLOPTS', 4310 'BASHOPTS', 'CDPATH' and 'GLOBIGNORE' variables, if they 4311 appear in the environment, are ignored. If the shell is 4312 started with the effective user (group) id not equal to the 4313 real user (group) id, and the '-p' option is not supplied, 4314 these actions are taken and the effective user id is set to 4315 the real user id. If the '-p' option is supplied at startup, 4316 the effective user id is not reset. Turning this option off 4317 causes the effective user and group ids to be set to the real 4318 user and group ids. 4319 4320 '-t' 4321 Exit after reading and executing one command. 4322 4323 '-u' 4324 Treat unset variables and parameters other than the special 4325 parameters '@' or '*' as an error when performing parameter 4326 expansion. An error message will be written to the standard 4327 error, and a non-interactive shell will exit. 4328 4329 '-v' 4330 Print shell input lines as they are read. 4331 4332 '-x' 4333 Print a trace of simple commands, 'for' commands, 'case' 4334 commands, 'select' commands, and arithmetic 'for' commands and 4335 their arguments or associated word lists after they are 4336 expanded and before they are executed. The value of the 'PS4' 4337 variable is expanded and the resultant value is printed before 4338 the command and its expanded arguments. 4339 4340 '-B' 4341 The shell will perform brace expansion (*note Brace 4342 Expansion::). This option is on by default. 4343 4344 '-C' 4345 Prevent output redirection using '>', '>&', and '<>' from 4346 overwriting existing files. 4347 4348 '-E' 4349 If set, any trap on 'ERR' is inherited by shell functions, 4350 command substitutions, and commands executed in a subshell 4351 environment. The 'ERR' trap is normally not inherited in such 4352 cases. 4353 4354 '-H' 4355 Enable '!' style history substitution (*note History 4356 Interaction::). This option is on by default for interactive 4357 shells. 4358 4359 '-P' 4360 If set, do not resolve symbolic links when performing commands 4361 such as 'cd' which change the current directory. The physical 4362 directory is used instead. By default, Bash follows the 4363 logical chain of directories when performing commands which 4364 change the current directory. 4365 4366 For example, if '/usr/sys' is a symbolic link to 4367 '/usr/local/sys' then: 4368 $ cd /usr/sys; echo $PWD 4369 /usr/sys 4370 $ cd ..; pwd 4371 /usr 4372 4373 If 'set -P' is on, then: 4374 $ cd /usr/sys; echo $PWD 4375 /usr/local/sys 4376 $ cd ..; pwd 4377 /usr/local 4378 4379 '-T' 4380 If set, any trap on 'DEBUG' and 'RETURN' are inherited by 4381 shell functions, command substitutions, and commands executed 4382 in a subshell environment. The 'DEBUG' and 'RETURN' traps are 4383 normally not inherited in such cases. 4384 4385 '--' 4386 If no arguments follow this option, then the positional 4387 parameters are unset. Otherwise, the positional parameters 4388 are set to the ARGUMENTS, even if some of them begin with a 4389 '-'. 4390 4391 '-' 4392 Signal the end of options, cause all remaining ARGUMENTS to be 4393 assigned to the positional parameters. The '-x' and '-v' 4394 options are turned off. If there are no arguments, the 4395 positional parameters remain unchanged. 4396 4397 Using '+' rather than '-' causes these options to be turned off. 4398 The options can also be used upon invocation of the shell. The 4399 current set of options may be found in '$-'. 4400 4401 The remaining N ARGUMENTS are positional parameters and are 4402 assigned, in order, to '$1', '$2', ... '$N'. The special parameter 4403 '#' is set to N. 4404 4405 The return status is always zero unless an invalid option is 4406 supplied. 4407 4408 4409File: bash.info, Node: The Shopt Builtin, Prev: The Set Builtin, Up: Modifying Shell Behavior 4410 44114.3.2 The Shopt Builtin 4412----------------------- 4413 4414This builtin allows you to change additional shell optional behavior. 4415 4416'shopt' 4417 shopt [-pqsu] [-o] [OPTNAME ...] 4418 4419 Toggle the values of settings controlling optional shell behavior. 4420 The settings can be either those listed below, or, if the '-o' 4421 option is used, those available with the '-o' option to the 'set' 4422 builtin command (*note The Set Builtin::). With no options, or 4423 with the '-p' option, a list of all settable options is displayed, 4424 with an indication of whether or not each is set; if OPTNAMES are 4425 supplied, the output is restricted to those options. The '-p' 4426 option causes output to be displayed in a form that may be reused 4427 as input. Other options have the following meanings: 4428 4429 '-s' 4430 Enable (set) each OPTNAME. 4431 4432 '-u' 4433 Disable (unset) each OPTNAME. 4434 4435 '-q' 4436 Suppresses normal output; the return status indicates whether 4437 the OPTNAME is set or unset. If multiple OPTNAME arguments 4438 are given with '-q', the return status is zero if all OPTNAMES 4439 are enabled; non-zero otherwise. 4440 4441 '-o' 4442 Restricts the values of OPTNAME to be those defined for the 4443 '-o' option to the 'set' builtin (*note The Set Builtin::). 4444 4445 If either '-s' or '-u' is used with no OPTNAME arguments, 'shopt' 4446 shows only those options which are set or unset, respectively. 4447 4448 Unless otherwise noted, the 'shopt' options are disabled (off) by 4449 default. 4450 4451 The return status when listing options is zero if all OPTNAMES are 4452 enabled, non-zero otherwise. When setting or unsetting options, 4453 the return status is zero unless an OPTNAME is not a valid shell 4454 option. 4455 4456 The list of 'shopt' options is: 4457 4458 'assoc_expand_once' 4459 If set, the shell suppresses multiple evaluation of 4460 associative array subscripts during arithmetic expression 4461 evaluation, while executing builtins that can perform variable 4462 assignments, and while executing builtins that perform array 4463 dereferencing. 4464 4465 'autocd' 4466 If set, a command name that is the name of a directory is 4467 executed as if it were the argument to the 'cd' command. This 4468 option is only used by interactive shells. 4469 4470 'cdable_vars' 4471 If this is set, an argument to the 'cd' builtin command that 4472 is not a directory is assumed to be the name of a variable 4473 whose value is the directory to change to. 4474 4475 'cdspell' 4476 If set, minor errors in the spelling of a directory component 4477 in a 'cd' command will be corrected. The errors checked for 4478 are transposed characters, a missing character, and a 4479 character too many. If a correction is found, the corrected 4480 path is printed, and the command proceeds. This option is 4481 only used by interactive shells. 4482 4483 'checkhash' 4484 If this is set, Bash checks that a command found in the hash 4485 table exists before trying to execute it. If a hashed command 4486 no longer exists, a normal path search is performed. 4487 4488 'checkjobs' 4489 If set, Bash lists the status of any stopped and running jobs 4490 before exiting an interactive shell. If any jobs are running, 4491 this causes the exit to be deferred until a second exit is 4492 attempted without an intervening command (*note Job 4493 Control::). The shell always postpones exiting if any jobs 4494 are stopped. 4495 4496 'checkwinsize' 4497 If set, Bash checks the window size after each external 4498 (non-builtin) command and, if necessary, updates the values of 4499 'LINES' and 'COLUMNS'. This option is enabled by default. 4500 4501 'cmdhist' 4502 If set, Bash attempts to save all lines of a multiple-line 4503 command in the same history entry. This allows easy 4504 re-editing of multi-line commands. This option is enabled by 4505 default, but only has an effect if command history is enabled 4506 (*note Bash History Facilities::). 4507 4508 'compat31' 4509 'compat32' 4510 'compat40' 4511 'compat41' 4512 'compat42' 4513 'compat43' 4514 'compat44' 4515 These control aspects of the shell's compatibility mode (*note 4516 Shell Compatibility Mode::). 4517 4518 'complete_fullquote' 4519 If set, Bash quotes all shell metacharacters in filenames and 4520 directory names when performing completion. If not set, Bash 4521 removes metacharacters such as the dollar sign from the set of 4522 characters that will be quoted in completed filenames when 4523 these metacharacters appear in shell variable references in 4524 words to be completed. This means that dollar signs in 4525 variable names that expand to directories will not be quoted; 4526 however, any dollar signs appearing in filenames will not be 4527 quoted, either. This is active only when bash is using 4528 backslashes to quote completed filenames. This variable is 4529 set by default, which is the default Bash behavior in versions 4530 through 4.2. 4531 4532 'direxpand' 4533 If set, Bash replaces directory names with the results of word 4534 expansion when performing filename completion. This changes 4535 the contents of the readline editing buffer. If not set, Bash 4536 attempts to preserve what the user typed. 4537 4538 'dirspell' 4539 If set, Bash attempts spelling correction on directory names 4540 during word completion if the directory name initially 4541 supplied does not exist. 4542 4543 'dotglob' 4544 If set, Bash includes filenames beginning with a '.' in the 4545 results of filename expansion. The filenames '.' and '..' 4546 must always be matched explicitly, even if 'dotglob' is set. 4547 4548 'execfail' 4549 If this is set, a non-interactive shell will not exit if it 4550 cannot execute the file specified as an argument to the 'exec' 4551 builtin command. An interactive shell does not exit if 'exec' 4552 fails. 4553 4554 'expand_aliases' 4555 If set, aliases are expanded as described below under Aliases, 4556 *note Aliases::. This option is enabled by default for 4557 interactive shells. 4558 4559 'extdebug' 4560 If set at shell invocation, or in a shell startup file, 4561 arrange to execute the debugger profile before the shell 4562 starts, identical to the '--debugger' option. If set after 4563 invocation, behavior intended for use by debuggers is enabled: 4564 4565 1. The '-F' option to the 'declare' builtin (*note Bash 4566 Builtins::) displays the source file name and line number 4567 corresponding to each function name supplied as an 4568 argument. 4569 4570 2. If the command run by the 'DEBUG' trap returns a non-zero 4571 value, the next command is skipped and not executed. 4572 4573 3. If the command run by the 'DEBUG' trap returns a value of 4574 2, and the shell is executing in a subroutine (a shell 4575 function or a shell script executed by the '.' or 4576 'source' builtins), the shell simulates a call to 4577 'return'. 4578 4579 4. 'BASH_ARGC' and 'BASH_ARGV' are updated as described in 4580 their descriptions (*note Bash Variables::). 4581 4582 5. Function tracing is enabled: command substitution, shell 4583 functions, and subshells invoked with '( COMMAND )' 4584 inherit the 'DEBUG' and 'RETURN' traps. 4585 4586 6. Error tracing is enabled: command substitution, shell 4587 functions, and subshells invoked with '( COMMAND )' 4588 inherit the 'ERR' trap. 4589 4590 'extglob' 4591 If set, the extended pattern matching features described above 4592 (*note Pattern Matching::) are enabled. 4593 4594 'extquote' 4595 If set, '$'STRING'' and '$"STRING"' quoting is performed 4596 within '${PARAMETER}' expansions enclosed in double quotes. 4597 This option is enabled by default. 4598 4599 'failglob' 4600 If set, patterns which fail to match filenames during filename 4601 expansion result in an expansion error. 4602 4603 'force_fignore' 4604 If set, the suffixes specified by the 'FIGNORE' shell variable 4605 cause words to be ignored when performing word completion even 4606 if the ignored words are the only possible completions. *Note 4607 Bash Variables::, for a description of 'FIGNORE'. This option 4608 is enabled by default. 4609 4610 'globasciiranges' 4611 If set, range expressions used in pattern matching bracket 4612 expressions (*note Pattern Matching::) behave as if in the 4613 traditional C locale when performing comparisons. That is, 4614 the current locale's collating sequence is not taken into 4615 account, so 'b' will not collate between 'A' and 'B', and 4616 upper-case and lower-case ASCII characters will collate 4617 together. 4618 4619 'globstar' 4620 If set, the pattern '**' used in a filename expansion context 4621 will match all files and zero or more directories and 4622 subdirectories. If the pattern is followed by a '/', only 4623 directories and subdirectories match. 4624 4625 'gnu_errfmt' 4626 If set, shell error messages are written in the standard GNU 4627 error message format. 4628 4629 'histappend' 4630 If set, the history list is appended to the file named by the 4631 value of the 'HISTFILE' variable when the shell exits, rather 4632 than overwriting the file. 4633 4634 'histreedit' 4635 If set, and Readline is being used, a user is given the 4636 opportunity to re-edit a failed history substitution. 4637 4638 'histverify' 4639 If set, and Readline is being used, the results of history 4640 substitution are not immediately passed to the shell parser. 4641 Instead, the resulting line is loaded into the Readline 4642 editing buffer, allowing further modification. 4643 4644 'hostcomplete' 4645 If set, and Readline is being used, Bash will attempt to 4646 perform hostname completion when a word containing a '@' is 4647 being completed (*note Commands For Completion::). This 4648 option is enabled by default. 4649 4650 'huponexit' 4651 If set, Bash will send 'SIGHUP' to all jobs when an 4652 interactive login shell exits (*note Signals::). 4653 4654 'inherit_errexit' 4655 If set, command substitution inherits the value of the 4656 'errexit' option, instead of unsetting it in the subshell 4657 environment. This option is enabled when POSIX mode is 4658 enabled. 4659 4660 'interactive_comments' 4661 Allow a word beginning with '#' to cause that word and all 4662 remaining characters on that line to be ignored in an 4663 interactive shell. This option is enabled by default. 4664 4665 'lastpipe' 4666 If set, and job control is not active, the shell runs the last 4667 command of a pipeline not executed in the background in the 4668 current shell environment. 4669 4670 'lithist' 4671 If enabled, and the 'cmdhist' option is enabled, multi-line 4672 commands are saved to the history with embedded newlines 4673 rather than using semicolon separators where possible. 4674 4675 'localvar_inherit' 4676 If set, local variables inherit the value and attributes of a 4677 variable of the same name that exists at a previous scope 4678 before any new value is assigned. The NAMEREF attribute is 4679 not inherited. 4680 4681 'localvar_unset' 4682 If set, calling 'unset' on local variables in previous 4683 function scopes marks them so subsequent lookups find them 4684 unset until that function returns. This is identical to the 4685 behavior of unsetting local variables at the current function 4686 scope. 4687 4688 'login_shell' 4689 The shell sets this option if it is started as a login shell 4690 (*note Invoking Bash::). The value may not be changed. 4691 4692 'mailwarn' 4693 If set, and a file that Bash is checking for mail has been 4694 accessed since the last time it was checked, the message '"The 4695 mail in MAILFILE has been read"' is displayed. 4696 4697 'no_empty_cmd_completion' 4698 If set, and Readline is being used, Bash will not attempt to 4699 search the 'PATH' for possible completions when completion is 4700 attempted on an empty line. 4701 4702 'nocaseglob' 4703 If set, Bash matches filenames in a case-insensitive fashion 4704 when performing filename expansion. 4705 4706 'nocasematch' 4707 If set, Bash matches patterns in a case-insensitive fashion 4708 when performing matching while executing 'case' or '[[' 4709 conditional commands, when performing pattern substitution 4710 word expansions, or when filtering possible completions as 4711 part of programmable completion. 4712 4713 'nullglob' 4714 If set, Bash allows filename patterns which match no files to 4715 expand to a null string, rather than themselves. 4716 4717 'progcomp' 4718 If set, the programmable completion facilities (*note 4719 Programmable Completion::) are enabled. This option is 4720 enabled by default. 4721 4722 'progcomp_alias' 4723 If set, and programmable completion is enabled, Bash treats a 4724 command name that doesn't have any completions as a possible 4725 alias and attempts alias expansion. If it has an alias, Bash 4726 attempts programmable completion using the command word 4727 resulting from the expanded alias. 4728 4729 'promptvars' 4730 If set, prompt strings undergo parameter expansion, command 4731 substitution, arithmetic expansion, and quote removal after 4732 being expanded as described below (*note Controlling the 4733 Prompt::). This option is enabled by default. 4734 4735 'restricted_shell' 4736 The shell sets this option if it is started in restricted mode 4737 (*note The Restricted Shell::). The value may not be changed. 4738 This is not reset when the startup files are executed, 4739 allowing the startup files to discover whether or not a shell 4740 is restricted. 4741 4742 'shift_verbose' 4743 If this is set, the 'shift' builtin prints an error message 4744 when the shift count exceeds the number of positional 4745 parameters. 4746 4747 'sourcepath' 4748 If set, the 'source' builtin uses the value of 'PATH' to find 4749 the directory containing the file supplied as an argument. 4750 This option is enabled by default. 4751 4752 'xpg_echo' 4753 If set, the 'echo' builtin expands backslash-escape sequences 4754 by default. 4755 4756 4757File: bash.info, Node: Special Builtins, Prev: Modifying Shell Behavior, Up: Shell Builtin Commands 4758 47594.4 Special Builtins 4760==================== 4761 4762For historical reasons, the POSIX standard has classified several 4763builtin commands as _special_. When Bash is executing in POSIX mode, 4764the special builtins differ from other builtin commands in three 4765respects: 4766 4767 1. Special builtins are found before shell functions during command 4768 lookup. 4769 4770 2. If a special builtin returns an error status, a non-interactive 4771 shell exits. 4772 4773 3. Assignment statements preceding the command stay in effect in the 4774 shell environment after the command completes. 4775 4776 When Bash is not executing in POSIX mode, these builtins behave no 4777differently than the rest of the Bash builtin commands. The Bash POSIX 4778mode is described in *note Bash POSIX Mode::. 4779 4780 These are the POSIX special builtins: 4781 break : . continue eval exec exit export readonly return set 4782 shift trap unset 4783 4784 4785File: bash.info, Node: Shell Variables, Next: Bash Features, Prev: Shell Builtin Commands, Up: Top 4786 47875 Shell Variables 4788***************** 4789 4790* Menu: 4791 4792* Bourne Shell Variables:: Variables which Bash uses in the same way 4793 as the Bourne Shell. 4794* Bash Variables:: List of variables that exist in Bash. 4795 4796This chapter describes the shell variables that Bash uses. Bash 4797automatically assigns default values to a number of variables. 4798 4799 4800File: bash.info, Node: Bourne Shell Variables, Next: Bash Variables, Up: Shell Variables 4801 48025.1 Bourne Shell Variables 4803========================== 4804 4805Bash uses certain shell variables in the same way as the Bourne shell. 4806In some cases, Bash assigns a default value to the variable. 4807 4808'CDPATH' 4809 A colon-separated list of directories used as a search path for the 4810 'cd' builtin command. 4811 4812'HOME' 4813 The current user's home directory; the default for the 'cd' builtin 4814 command. The value of this variable is also used by tilde 4815 expansion (*note Tilde Expansion::). 4816 4817'IFS' 4818 A list of characters that separate fields; used when the shell 4819 splits words as part of expansion. 4820 4821'MAIL' 4822 If this parameter is set to a filename or directory name and the 4823 'MAILPATH' variable is not set, Bash informs the user of the 4824 arrival of mail in the specified file or Maildir-format directory. 4825 4826'MAILPATH' 4827 A colon-separated list of filenames which the shell periodically 4828 checks for new mail. Each list entry can specify the message that 4829 is printed when new mail arrives in the mail file by separating the 4830 filename from the message with a '?'. When used in the text of the 4831 message, '$_' expands to the name of the current mail file. 4832 4833'OPTARG' 4834 The value of the last option argument processed by the 'getopts' 4835 builtin. 4836 4837'OPTIND' 4838 The index of the last option argument processed by the 'getopts' 4839 builtin. 4840 4841'PATH' 4842 A colon-separated list of directories in which the shell looks for 4843 commands. A zero-length (null) directory name in the value of 4844 'PATH' indicates the current directory. A null directory name may 4845 appear as two adjacent colons, or as an initial or trailing colon. 4846 4847'PS1' 4848 The primary prompt string. The default value is '\s-\v\$ '. *Note 4849 Controlling the Prompt::, for the complete list of escape sequences 4850 that are expanded before 'PS1' is displayed. 4851 4852'PS2' 4853 The secondary prompt string. The default value is '> '. 'PS2' is 4854 expanded in the same way as 'PS1' before being displayed. 4855 4856 4857File: bash.info, Node: Bash Variables, Prev: Bourne Shell Variables, Up: Shell Variables 4858 48595.2 Bash Variables 4860================== 4861 4862These variables are set or used by Bash, but other shells do not 4863normally treat them specially. 4864 4865 A few variables used by Bash are described in different chapters: 4866variables for controlling the job control facilities (*note Job Control 4867Variables::). 4868 4869'_' 4870 ($_, an underscore.) At shell startup, set to the pathname used to 4871 invoke the shell or shell script being executed as passed in the 4872 environment or argument list. Subsequently, expands to the last 4873 argument to the previous simple command executed in the foreground, 4874 after expansion. Also set to the full pathname used to invoke each 4875 command executed and placed in the environment exported to that 4876 command. When checking mail, this parameter holds the name of the 4877 mail file. 4878 4879'BASH' 4880 The full pathname used to execute the current instance of Bash. 4881 4882'BASHOPTS' 4883 A colon-separated list of enabled shell options. Each word in the 4884 list is a valid argument for the '-s' option to the 'shopt' builtin 4885 command (*note The Shopt Builtin::). The options appearing in 4886 'BASHOPTS' are those reported as 'on' by 'shopt'. If this variable 4887 is in the environment when Bash starts up, each shell option in the 4888 list will be enabled before reading any startup files. This 4889 variable is readonly. 4890 4891'BASHPID' 4892 Expands to the process ID of the current Bash process. This 4893 differs from '$$' under certain circumstances, such as subshells 4894 that do not require Bash to be re-initialized. Assignments to 4895 'BASHPID' have no effect. If 'BASHPID' is unset, it loses its 4896 special properties, even if it is subsequently reset. 4897 4898'BASH_ALIASES' 4899 An associative array variable whose members correspond to the 4900 internal list of aliases as maintained by the 'alias' builtin. 4901 (*note Bourne Shell Builtins::). Elements added to this array 4902 appear in the alias list; however, unsetting array elements 4903 currently does not cause aliases to be removed from the alias list. 4904 If 'BASH_ALIASES' is unset, it loses its special properties, even 4905 if it is subsequently reset. 4906 4907'BASH_ARGC' 4908 An array variable whose values are the number of parameters in each 4909 frame of the current bash execution call stack. The number of 4910 parameters to the current subroutine (shell function or script 4911 executed with '.' or 'source') is at the top of the stack. When a 4912 subroutine is executed, the number of parameters passed is pushed 4913 onto 'BASH_ARGC'. The shell sets 'BASH_ARGC' only when in extended 4914 debugging mode (see *note The Shopt Builtin:: for a description of 4915 the 'extdebug' option to the 'shopt' builtin). Setting 'extdebug' 4916 after the shell has started to execute a script, or referencing 4917 this variable when 'extdebug' is not set, may result in 4918 inconsistent values. 4919 4920'BASH_ARGV' 4921 An array variable containing all of the parameters in the current 4922 bash execution call stack. The final parameter of the last 4923 subroutine call is at the top of the stack; the first parameter of 4924 the initial call is at the bottom. When a subroutine is executed, 4925 the parameters supplied are pushed onto 'BASH_ARGV'. The shell 4926 sets 'BASH_ARGV' only when in extended debugging mode (see *note 4927 The Shopt Builtin:: for a description of the 'extdebug' option to 4928 the 'shopt' builtin). Setting 'extdebug' after the shell has 4929 started to execute a script, or referencing this variable when 4930 'extdebug' is not set, may result in inconsistent values. 4931 4932'BASH_ARGV0' 4933 When referenced, this variable expands to the name of the shell or 4934 shell script (identical to '$0'; *Note Special Parameters::, for 4935 the description of special parameter 0). Assignment to 4936 'BASH_ARGV0' causes the value assigned to also be assigned to '$0'. 4937 If 'BASH_ARGV0' is unset, it loses its special properties, even if 4938 it is subsequently reset. 4939 4940'BASH_CMDS' 4941 An associative array variable whose members correspond to the 4942 internal hash table of commands as maintained by the 'hash' builtin 4943 (*note Bourne Shell Builtins::). Elements added to this array 4944 appear in the hash table; however, unsetting array elements 4945 currently does not cause command names to be removed from the hash 4946 table. If 'BASH_CMDS' is unset, it loses its special properties, 4947 even if it is subsequently reset. 4948 4949'BASH_COMMAND' 4950 The command currently being executed or about to be executed, 4951 unless the shell is executing a command as the result of a trap, in 4952 which case it is the command executing at the time of the trap. If 4953 'BASH_COMMAND' is unset, it loses its special properties, even if 4954 it is subsequently reset. 4955 4956'BASH_COMPAT' 4957 The value is used to set the shell's compatibility level. *Note 4958 Shell Compatibility Mode::, for a description of the various 4959 compatibility levels and their effects. The value may be a decimal 4960 number (e.g., 4.2) or an integer (e.g., 42) corresponding to the 4961 desired compatibility level. If 'BASH_COMPAT' is unset or set to 4962 the empty string, the compatibility level is set to the default for 4963 the current version. If 'BASH_COMPAT' is set to a value that is 4964 not one of the valid compatibility levels, the shell prints an 4965 error message and sets the compatibility level to the default for 4966 the current version. The valid values correspond to the 4967 compatibility levels described below (*note Shell Compatibility 4968 Mode::). For example, 4.2 and 42 are valid values that correspond 4969 to the 'compat42' 'shopt' option and set the compatibility level to 4970 42. The current version is also a valid value. 4971 4972'BASH_ENV' 4973 If this variable is set when Bash is invoked to execute a shell 4974 script, its value is expanded and used as the name of a startup 4975 file to read before executing the script. *Note Bash Startup 4976 Files::. 4977 4978'BASH_EXECUTION_STRING' 4979 The command argument to the '-c' invocation option. 4980 4981'BASH_LINENO' 4982 An array variable whose members are the line numbers in source 4983 files where each corresponding member of FUNCNAME was invoked. 4984 '${BASH_LINENO[$i]}' is the line number in the source file 4985 ('${BASH_SOURCE[$i+1]}') where '${FUNCNAME[$i]}' was called (or 4986 '${BASH_LINENO[$i-1]}' if referenced within another shell 4987 function). Use 'LINENO' to obtain the current line number. 4988 4989'BASH_LOADABLES_PATH' 4990 A colon-separated list of directories in which the shell looks for 4991 dynamically loadable builtins specified by the 'enable' command. 4992 4993'BASH_REMATCH' 4994 An array variable whose members are assigned by the '=~' binary 4995 operator to the '[[' conditional command (*note Conditional 4996 Constructs::). The element with index 0 is the portion of the 4997 string matching the entire regular expression. The element with 4998 index N is the portion of the string matching the Nth parenthesized 4999 subexpression. 5000 5001'BASH_SOURCE' 5002 An array variable whose members are the source filenames where the 5003 corresponding shell function names in the 'FUNCNAME' array variable 5004 are defined. The shell function '${FUNCNAME[$i]}' is defined in 5005 the file '${BASH_SOURCE[$i]}' and called from 5006 '${BASH_SOURCE[$i+1]}' 5007 5008'BASH_SUBSHELL' 5009 Incremented by one within each subshell or subshell environment 5010 when the shell begins executing in that environment. The initial 5011 value is 0. If 'BASH_SUBSHELL' is unset, it loses its special 5012 properties, even if it is subsequently reset. 5013 5014'BASH_VERSINFO' 5015 A readonly array variable (*note Arrays::) whose members hold 5016 version information for this instance of Bash. The values assigned 5017 to the array members are as follows: 5018 5019 'BASH_VERSINFO[0]' 5020 The major version number (the RELEASE). 5021 5022 'BASH_VERSINFO[1]' 5023 The minor version number (the VERSION). 5024 5025 'BASH_VERSINFO[2]' 5026 The patch level. 5027 5028 'BASH_VERSINFO[3]' 5029 The build version. 5030 5031 'BASH_VERSINFO[4]' 5032 The release status (e.g., BETA1). 5033 5034 'BASH_VERSINFO[5]' 5035 The value of 'MACHTYPE'. 5036 5037'BASH_VERSION' 5038 The version number of the current instance of Bash. 5039 5040'BASH_XTRACEFD' 5041 If set to an integer corresponding to a valid file descriptor, Bash 5042 will write the trace output generated when 'set -x' is enabled to 5043 that file descriptor. This allows tracing output to be separated 5044 from diagnostic and error messages. The file descriptor is closed 5045 when 'BASH_XTRACEFD' is unset or assigned a new value. Unsetting 5046 'BASH_XTRACEFD' or assigning it the empty string causes the trace 5047 output to be sent to the standard error. Note that setting 5048 'BASH_XTRACEFD' to 2 (the standard error file descriptor) and then 5049 unsetting it will result in the standard error being closed. 5050 5051'CHILD_MAX' 5052 Set the number of exited child status values for the shell to 5053 remember. Bash will not allow this value to be decreased below a 5054 POSIX-mandated minimum, and there is a maximum value (currently 5055 8192) that this may not exceed. The minimum value is 5056 system-dependent. 5057 5058'COLUMNS' 5059 Used by the 'select' command to determine the terminal width when 5060 printing selection lists. Automatically set if the 'checkwinsize' 5061 option is enabled (*note The Shopt Builtin::), or in an interactive 5062 shell upon receipt of a 'SIGWINCH'. 5063 5064'COMP_CWORD' 5065 An index into '${COMP_WORDS}' of the word containing the current 5066 cursor position. This variable is available only in shell 5067 functions invoked by the programmable completion facilities (*note 5068 Programmable Completion::). 5069 5070'COMP_LINE' 5071 The current command line. This variable is available only in shell 5072 functions and external commands invoked by the programmable 5073 completion facilities (*note Programmable Completion::). 5074 5075'COMP_POINT' 5076 The index of the current cursor position relative to the beginning 5077 of the current command. If the current cursor position is at the 5078 end of the current command, the value of this variable is equal to 5079 '${#COMP_LINE}'. This variable is available only in shell 5080 functions and external commands invoked by the programmable 5081 completion facilities (*note Programmable Completion::). 5082 5083'COMP_TYPE' 5084 Set to an integer value corresponding to the type of completion 5085 attempted that caused a completion function to be called: TAB, for 5086 normal completion, '?', for listing completions after successive 5087 tabs, '!', for listing alternatives on partial word completion, 5088 '@', to list completions if the word is not unmodified, or '%', for 5089 menu completion. This variable is available only in shell 5090 functions and external commands invoked by the programmable 5091 completion facilities (*note Programmable Completion::). 5092 5093'COMP_KEY' 5094 The key (or final key of a key sequence) used to invoke the current 5095 completion function. 5096 5097'COMP_WORDBREAKS' 5098 The set of characters that the Readline library treats as word 5099 separators when performing word completion. If 'COMP_WORDBREAKS' 5100 is unset, it loses its special properties, even if it is 5101 subsequently reset. 5102 5103'COMP_WORDS' 5104 An array variable consisting of the individual words in the current 5105 command line. The line is split into words as Readline would split 5106 it, using 'COMP_WORDBREAKS' as described above. This variable is 5107 available only in shell functions invoked by the programmable 5108 completion facilities (*note Programmable Completion::). 5109 5110'COMPREPLY' 5111 An array variable from which Bash reads the possible completions 5112 generated by a shell function invoked by the programmable 5113 completion facility (*note Programmable Completion::). Each array 5114 element contains one possible completion. 5115 5116'COPROC' 5117 An array variable created to hold the file descriptors for output 5118 from and input to an unnamed coprocess (*note Coprocesses::). 5119 5120'DIRSTACK' 5121 An array variable containing the current contents of the directory 5122 stack. Directories appear in the stack in the order they are 5123 displayed by the 'dirs' builtin. Assigning to members of this 5124 array variable may be used to modify directories already in the 5125 stack, but the 'pushd' and 'popd' builtins must be used to add and 5126 remove directories. Assignment to this variable will not change 5127 the current directory. If 'DIRSTACK' is unset, it loses its 5128 special properties, even if it is subsequently reset. 5129 5130'EMACS' 5131 If Bash finds this variable in the environment when the shell 5132 starts with value 't', it assumes that the shell is running in an 5133 Emacs shell buffer and disables line editing. 5134 5135'ENV' 5136 Expanded and executed similarlty to 'BASH_ENV' (*note Bash Startup 5137 Files::) when an interactive shell is invoked in POSIX Mode (*note 5138 Bash POSIX Mode::). 5139 5140'EPOCHREALTIME' 5141 Each time this parameter is referenced, it expands to the number of 5142 seconds since the Unix Epoch as a floating point value with 5143 micro-second granularity (see the documentation for the C library 5144 function TIME for the definition of Epoch). Assignments to 5145 'EPOCHREALTIME' are ignored. If 'EPOCHREALTIME' is unset, it loses 5146 its special properties, even if it is subsequently reset. 5147 5148'EPOCHSECONDS' 5149 Each time this parameter is referenced, it expands to the number of 5150 seconds since the Unix Epoch (see the documentation for the C 5151 library function TIME for the definition of Epoch). Assignments to 5152 'EPOCHSECONDS' are ignored. If 'EPOCHSECONDS' is unset, it loses 5153 its special properties, even if it is subsequently reset. 5154 5155'EUID' 5156 The numeric effective user id of the current user. This variable 5157 is readonly. 5158 5159'EXECIGNORE' 5160 A colon-separated list of shell patterns (*note Pattern Matching::) 5161 defining the list of filenames to be ignored by command search 5162 using 'PATH'. Files whose full pathnames match one of these 5163 patterns are not considered executable files for the purposes of 5164 completion and command execution via 'PATH' lookup. This does not 5165 affect the behavior of the '[', 'test', and '[[' commands. Full 5166 pathnames in the command hash table are not subject to 5167 'EXECIGNORE'. Use this variable to ignore shared library files 5168 that have the executable bit set, but are not executable files. 5169 The pattern matching honors the setting of the 'extglob' shell 5170 option. 5171 5172'FCEDIT' 5173 The editor used as a default by the '-e' option to the 'fc' builtin 5174 command. 5175 5176'FIGNORE' 5177 A colon-separated list of suffixes to ignore when performing 5178 filename completion. A filename whose suffix matches one of the 5179 entries in 'FIGNORE' is excluded from the list of matched 5180 filenames. A sample value is '.o:~' 5181 5182'FUNCNAME' 5183 An array variable containing the names of all shell functions 5184 currently in the execution call stack. The element with index 0 is 5185 the name of any currently-executing shell function. The 5186 bottom-most element (the one with the highest index) is '"main"'. 5187 This variable exists only when a shell function is executing. 5188 Assignments to 'FUNCNAME' have no effect. If 'FUNCNAME' is unset, 5189 it loses its special properties, even if it is subsequently reset. 5190 5191 This variable can be used with 'BASH_LINENO' and 'BASH_SOURCE'. 5192 Each element of 'FUNCNAME' has corresponding elements in 5193 'BASH_LINENO' and 'BASH_SOURCE' to describe the call stack. For 5194 instance, '${FUNCNAME[$i]}' was called from the file 5195 '${BASH_SOURCE[$i+1]}' at line number '${BASH_LINENO[$i]}'. The 5196 'caller' builtin displays the current call stack using this 5197 information. 5198 5199'FUNCNEST' 5200 If set to a numeric value greater than 0, defines a maximum 5201 function nesting level. Function invocations that exceed this 5202 nesting level will cause the current command to abort. 5203 5204'GLOBIGNORE' 5205 A colon-separated list of patterns defining the set of file names 5206 to be ignored by filename expansion. If a file name matched by a 5207 filename expansion pattern also matches one of the patterns in 5208 'GLOBIGNORE', it is removed from the list of matches. The pattern 5209 matching honors the setting of the 'extglob' shell option. 5210 5211'GROUPS' 5212 An array variable containing the list of groups of which the 5213 current user is a member. Assignments to 'GROUPS' have no effect. 5214 If 'GROUPS' is unset, it loses its special properties, even if it 5215 is subsequently reset. 5216 5217'histchars' 5218 Up to three characters which control history expansion, quick 5219 substitution, and tokenization (*note History Interaction::). The 5220 first character is the HISTORY EXPANSION character, that is, the 5221 character which signifies the start of a history expansion, 5222 normally '!'. The second character is the character which 5223 signifies 'quick substitution' when seen as the first character on 5224 a line, normally '^'. The optional third character is the 5225 character which indicates that the remainder of the line is a 5226 comment when found as the first character of a word, usually '#'. 5227 The history comment character causes history substitution to be 5228 skipped for the remaining words on the line. It does not 5229 necessarily cause the shell parser to treat the rest of the line as 5230 a comment. 5231 5232'HISTCMD' 5233 The history number, or index in the history list, of the current 5234 command. Assignments to 'HISTCMD' are ignored. If 'HISTCMD' is 5235 unset, it loses its special properties, even if it is subsequently 5236 reset. 5237 5238'HISTCONTROL' 5239 A colon-separated list of values controlling how commands are saved 5240 on the history list. If the list of values includes 'ignorespace', 5241 lines which begin with a space character are not saved in the 5242 history list. A value of 'ignoredups' causes lines which match the 5243 previous history entry to not be saved. A value of 'ignoreboth' is 5244 shorthand for 'ignorespace' and 'ignoredups'. A value of 5245 'erasedups' causes all previous lines matching the current line to 5246 be removed from the history list before that line is saved. Any 5247 value not in the above list is ignored. If 'HISTCONTROL' is unset, 5248 or does not include a valid value, all lines read by the shell 5249 parser are saved on the history list, subject to the value of 5250 'HISTIGNORE'. The second and subsequent lines of a multi-line 5251 compound command are not tested, and are added to the history 5252 regardless of the value of 'HISTCONTROL'. 5253 5254'HISTFILE' 5255 The name of the file to which the command history is saved. The 5256 default value is '~/.bash_history'. 5257 5258'HISTFILESIZE' 5259 The maximum number of lines contained in the history file. When 5260 this variable is assigned a value, the history file is truncated, 5261 if necessary, to contain no more than that number of lines by 5262 removing the oldest entries. The history file is also truncated to 5263 this size after writing it when a shell exits. If the value is 0, 5264 the history file is truncated to zero size. Non-numeric values and 5265 numeric values less than zero inhibit truncation. The shell sets 5266 the default value to the value of 'HISTSIZE' after reading any 5267 startup files. 5268 5269'HISTIGNORE' 5270 A colon-separated list of patterns used to decide which command 5271 lines should be saved on the history list. Each pattern is 5272 anchored at the beginning of the line and must match the complete 5273 line (no implicit '*' is appended). Each pattern is tested against 5274 the line after the checks specified by 'HISTCONTROL' are applied. 5275 In addition to the normal shell pattern matching characters, '&' 5276 matches the previous history line. '&' may be escaped using a 5277 backslash; the backslash is removed before attempting a match. The 5278 second and subsequent lines of a multi-line compound command are 5279 not tested, and are added to the history regardless of the value of 5280 'HISTIGNORE'. The pattern matching honors the setting of the 5281 'extglob' shell option. 5282 5283 'HISTIGNORE' subsumes the function of 'HISTCONTROL'. A pattern of 5284 '&' is identical to 'ignoredups', and a pattern of '[ ]*' is 5285 identical to 'ignorespace'. Combining these two patterns, 5286 separating them with a colon, provides the functionality of 5287 'ignoreboth'. 5288 5289'HISTSIZE' 5290 The maximum number of commands to remember on the history list. If 5291 the value is 0, commands are not saved in the history list. 5292 Numeric values less than zero result in every command being saved 5293 on the history list (there is no limit). The shell sets the 5294 default value to 500 after reading any startup files. 5295 5296'HISTTIMEFORMAT' 5297 If this variable is set and not null, its value is used as a format 5298 string for STRFTIME to print the time stamp associated with each 5299 history entry displayed by the 'history' builtin. If this variable 5300 is set, time stamps are written to the history file so they may be 5301 preserved across shell sessions. This uses the history comment 5302 character to distinguish timestamps from other history lines. 5303 5304'HOSTFILE' 5305 Contains the name of a file in the same format as '/etc/hosts' that 5306 should be read when the shell needs to complete a hostname. The 5307 list of possible hostname completions may be changed while the 5308 shell is running; the next time hostname completion is attempted 5309 after the value is changed, Bash adds the contents of the new file 5310 to the existing list. If 'HOSTFILE' is set, but has no value, or 5311 does not name a readable file, Bash attempts to read '/etc/hosts' 5312 to obtain the list of possible hostname completions. When 5313 'HOSTFILE' is unset, the hostname list is cleared. 5314 5315'HOSTNAME' 5316 The name of the current host. 5317 5318'HOSTTYPE' 5319 A string describing the machine Bash is running on. 5320 5321'IGNOREEOF' 5322 Controls the action of the shell on receipt of an 'EOF' character 5323 as the sole input. If set, the value denotes the number of 5324 consecutive 'EOF' characters that can be read as the first 5325 character on an input line before the shell will exit. If the 5326 variable exists but does not have a numeric value, or has no value, 5327 then the default is 10. If the variable does not exist, then 'EOF' 5328 signifies the end of input to the shell. This is only in effect 5329 for interactive shells. 5330 5331'INPUTRC' 5332 The name of the Readline initialization file, overriding the 5333 default of '~/.inputrc'. 5334 5335'INSIDE_EMACS' 5336 If Bash finds this variable in the environment when the shell 5337 starts, it assumes that the shell is running in an Emacs shell 5338 buffer and may disable line editing depending on the value of 5339 'TERM'. 5340 5341'LANG' 5342 Used to determine the locale category for any category not 5343 specifically selected with a variable starting with 'LC_'. 5344 5345'LC_ALL' 5346 This variable overrides the value of 'LANG' and any other 'LC_' 5347 variable specifying a locale category. 5348 5349'LC_COLLATE' 5350 This variable determines the collation order used when sorting the 5351 results of filename expansion, and determines the behavior of range 5352 expressions, equivalence classes, and collating sequences within 5353 filename expansion and pattern matching (*note Filename 5354 Expansion::). 5355 5356'LC_CTYPE' 5357 This variable determines the interpretation of characters and the 5358 behavior of character classes within filename expansion and pattern 5359 matching (*note Filename Expansion::). 5360 5361'LC_MESSAGES' 5362 This variable determines the locale used to translate double-quoted 5363 strings preceded by a '$' (*note Locale Translation::). 5364 5365'LC_NUMERIC' 5366 This variable determines the locale category used for number 5367 formatting. 5368 5369'LC_TIME' 5370 This variable determines the locale category used for data and time 5371 formatting. 5372 5373'LINENO' 5374 The line number in the script or shell function currently 5375 executing. If 'LINENO' is unset, it loses its special properties, 5376 even if it is subsequently reset. 5377 5378'LINES' 5379 Used by the 'select' command to determine the column length for 5380 printing selection lists. Automatically set if the 'checkwinsize' 5381 option is enabled (*note The Shopt Builtin::), or in an interactive 5382 shell upon receipt of a 'SIGWINCH'. 5383 5384'MACHTYPE' 5385 A string that fully describes the system type on which Bash is 5386 executing, in the standard GNU CPU-COMPANY-SYSTEM format. 5387 5388'MAILCHECK' 5389 How often (in seconds) that the shell should check for mail in the 5390 files specified in the 'MAILPATH' or 'MAIL' variables. The default 5391 is 60 seconds. When it is time to check for mail, the shell does 5392 so before displaying the primary prompt. If this variable is 5393 unset, or set to a value that is not a number greater than or equal 5394 to zero, the shell disables mail checking. 5395 5396'MAPFILE' 5397 An array variable created to hold the text read by the 'mapfile' 5398 builtin when no variable name is supplied. 5399 5400'OLDPWD' 5401 The previous working directory as set by the 'cd' builtin. 5402 5403'OPTERR' 5404 If set to the value 1, Bash displays error messages generated by 5405 the 'getopts' builtin command. 5406 5407'OSTYPE' 5408 A string describing the operating system Bash is running on. 5409 5410'PIPESTATUS' 5411 An array variable (*note Arrays::) containing a list of exit status 5412 values from the processes in the most-recently-executed foreground 5413 pipeline (which may contain only a single command). 5414 5415'POSIXLY_CORRECT' 5416 If this variable is in the environment when Bash starts, the shell 5417 enters POSIX mode (*note Bash POSIX Mode::) before reading the 5418 startup files, as if the '--posix' invocation option had been 5419 supplied. If it is set while the shell is running, Bash enables 5420 POSIX mode, as if the command 5421 set -o posix 5422 had been executed. When the shell enters POSIX mode, it sets this 5423 variable if it was not already set. 5424 5425'PPID' 5426 The process ID of the shell's parent process. This variable is 5427 readonly. 5428 5429'PROMPT_COMMAND' 5430 If this variable is set, and is an array, the value of each set 5431 element is interpreted as a command to execute before printing the 5432 primary prompt ('$PS1'). If this is set but not an array variable, 5433 its value is used as a command to execute instead. 5434 5435'PROMPT_DIRTRIM' 5436 If set to a number greater than zero, the value is used as the 5437 number of trailing directory components to retain when expanding 5438 the '\w' and '\W' prompt string escapes (*note Controlling the 5439 Prompt::). Characters removed are replaced with an ellipsis. 5440 5441'PS0' 5442 The value of this parameter is expanded like 'PS1' and displayed by 5443 interactive shells after reading a command and before the command 5444 is executed. 5445 5446'PS3' 5447 The value of this variable is used as the prompt for the 'select' 5448 command. If this variable is not set, the 'select' command prompts 5449 with '#? ' 5450 5451'PS4' 5452 The value of this parameter is expanded like PS1 and the expanded 5453 value is the prompt printed before the command line is echoed when 5454 the '-x' option is set (*note The Set Builtin::). The first 5455 character of the expanded value is replicated multiple times, as 5456 necessary, to indicate multiple levels of indirection. The default 5457 is '+ '. 5458 5459'PWD' 5460 The current working directory as set by the 'cd' builtin. 5461 5462'RANDOM' 5463 Each time this parameter is referenced, it expands to a random 5464 integer between 0 and 32767. Assigning a value to this variable 5465 seeds the random number generator. If 'RANDOM' is unset, it loses 5466 its special properties, even if it is subsequently reset. 5467 5468'READLINE_LINE' 5469 The contents of the Readline line buffer, for use with 'bind -x' 5470 (*note Bash Builtins::). 5471 5472'READLINE_MARK' 5473 The position of the MARK (saved insertion point) in the Readline 5474 line buffer, for use with 'bind -x' (*note Bash Builtins::). The 5475 characters between the insertion point and the mark are often 5476 called the REGION. 5477 5478'READLINE_POINT' 5479 The position of the insertion point in the Readline line buffer, 5480 for use with 'bind -x' (*note Bash Builtins::). 5481 5482'REPLY' 5483 The default variable for the 'read' builtin. 5484 5485'SECONDS' 5486 This variable expands to the number of seconds since the shell was 5487 started. Assignment to this variable resets the count to the value 5488 assigned, and the expanded value becomes the value assigned plus 5489 the number of seconds since the assignment. The number of seconds 5490 at shell invocation and the current time is always determined by 5491 querying the system clock. If 'SECONDS' is unset, it loses its 5492 special properties, even if it is subsequently reset. 5493 5494'SHELL' 5495 This environment variable expands to the full pathname to the 5496 shell. If it is not set when the shell starts, Bash assigns to it 5497 the full pathname of the current user's login shell. 5498 5499'SHELLOPTS' 5500 A colon-separated list of enabled shell options. Each word in the 5501 list is a valid argument for the '-o' option to the 'set' builtin 5502 command (*note The Set Builtin::). The options appearing in 5503 'SHELLOPTS' are those reported as 'on' by 'set -o'. If this 5504 variable is in the environment when Bash starts up, each shell 5505 option in the list will be enabled before reading any startup 5506 files. This variable is readonly. 5507 5508'SHLVL' 5509 Incremented by one each time a new instance of Bash is started. 5510 This is intended to be a count of how deeply your Bash shells are 5511 nested. 5512 5513'SRANDOM' 5514 This variable expands to a 32-bit pseudo-random number each time it 5515 is referenced. The random number generator is not linear on 5516 systems that support '/dev/urandom' or 'arc4random', so each 5517 returned number has no relationship to the numbers preceding it. 5518 The random number generator cannot be seeded, so assignments to 5519 this variable have no effect. If 'SRANDOM' is unset, it loses its 5520 special properties, even if it is subsequently reset. 5521 5522'TIMEFORMAT' 5523 The value of this parameter is used as a format string specifying 5524 how the timing information for pipelines prefixed with the 'time' 5525 reserved word should be displayed. The '%' character introduces an 5526 escape sequence that is expanded to a time value or other 5527 information. The escape sequences and their meanings are as 5528 follows; the braces denote optional portions. 5529 5530 '%%' 5531 A literal '%'. 5532 5533 '%[P][l]R' 5534 The elapsed time in seconds. 5535 5536 '%[P][l]U' 5537 The number of CPU seconds spent in user mode. 5538 5539 '%[P][l]S' 5540 The number of CPU seconds spent in system mode. 5541 5542 '%P' 5543 The CPU percentage, computed as (%U + %S) / %R. 5544 5545 The optional P is a digit specifying the precision, the number of 5546 fractional digits after a decimal point. A value of 0 causes no 5547 decimal point or fraction to be output. At most three places after 5548 the decimal point may be specified; values of P greater than 3 are 5549 changed to 3. If P is not specified, the value 3 is used. 5550 5551 The optional 'l' specifies a longer format, including minutes, of 5552 the form MMmSS.FFs. The value of P determines whether or not the 5553 fraction is included. 5554 5555 If this variable is not set, Bash acts as if it had the value 5556 $'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS' 5557 If the value is null, no timing information is displayed. A 5558 trailing newline is added when the format string is displayed. 5559 5560'TMOUT' 5561 If set to a value greater than zero, 'TMOUT' is treated as the 5562 default timeout for the 'read' builtin (*note Bash Builtins::). 5563 The 'select' command (*note Conditional Constructs::) terminates if 5564 input does not arrive after 'TMOUT' seconds when input is coming 5565 from a terminal. 5566 5567 In an interactive shell, the value is interpreted as the number of 5568 seconds to wait for a line of input after issuing the primary 5569 prompt. Bash terminates after waiting for that number of seconds 5570 if a complete line of input does not arrive. 5571 5572'TMPDIR' 5573 If set, Bash uses its value as the name of a directory in which 5574 Bash creates temporary files for the shell's use. 5575 5576'UID' 5577 The numeric real user id of the current user. This variable is 5578 readonly. 5579 5580 5581File: bash.info, Node: Bash Features, Next: Job Control, Prev: Shell Variables, Up: Top 5582 55836 Bash Features 5584*************** 5585 5586This chapter describes features unique to Bash. 5587 5588* Menu: 5589 5590* Invoking Bash:: Command line options that you can give 5591 to Bash. 5592* Bash Startup Files:: When and how Bash executes scripts. 5593* Interactive Shells:: What an interactive shell is. 5594* Bash Conditional Expressions:: Primitives used in composing expressions for 5595 the 'test' builtin. 5596* Shell Arithmetic:: Arithmetic on shell variables. 5597* Aliases:: Substituting one command for another. 5598* Arrays:: Array Variables. 5599* The Directory Stack:: History of visited directories. 5600* Controlling the Prompt:: Customizing the various prompt strings. 5601* The Restricted Shell:: A more controlled mode of shell execution. 5602* Bash POSIX Mode:: Making Bash behave more closely to what 5603 the POSIX standard specifies. 5604* Shell Compatibility Mode:: How Bash supports behavior that was present 5605 in earlier versions and has changed. 5606 5607 5608File: bash.info, Node: Invoking Bash, Next: Bash Startup Files, Up: Bash Features 5609 56106.1 Invoking Bash 5611================= 5612 5613 bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o OPTION] 5614 [-O SHOPT_OPTION] [ARGUMENT ...] 5615 bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o OPTION] 5616 [-O SHOPT_OPTION] -c STRING [ARGUMENT ...] 5617 bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o OPTION] 5618 [-O SHOPT_OPTION] [ARGUMENT ...] 5619 5620 All of the single-character options used with the 'set' builtin 5621(*note The Set Builtin::) can be used as options when the shell is 5622invoked. In addition, there are several multi-character options that 5623you can use. These options must appear on the command line before the 5624single-character options to be recognized. 5625 5626'--debugger' 5627 Arrange for the debugger profile to be executed before the shell 5628 starts. Turns on extended debugging mode (see *note The Shopt 5629 Builtin:: for a description of the 'extdebug' option to the 'shopt' 5630 builtin). 5631 5632'--dump-po-strings' 5633 A list of all double-quoted strings preceded by '$' is printed on 5634 the standard output in the GNU 'gettext' PO (portable object) file 5635 format. Equivalent to '-D' except for the output format. 5636 5637'--dump-strings' 5638 Equivalent to '-D'. 5639 5640'--help' 5641 Display a usage message on standard output and exit successfully. 5642 5643'--init-file FILENAME' 5644'--rcfile FILENAME' 5645 Execute commands from FILENAME (instead of '~/.bashrc') in an 5646 interactive shell. 5647 5648'--login' 5649 Equivalent to '-l'. 5650 5651'--noediting' 5652 Do not use the GNU Readline library (*note Command Line Editing::) 5653 to read command lines when the shell is interactive. 5654 5655'--noprofile' 5656 Don't load the system-wide startup file '/etc/profile' or any of 5657 the personal initialization files '~/.bash_profile', 5658 '~/.bash_login', or '~/.profile' when Bash is invoked as a login 5659 shell. 5660 5661'--norc' 5662 Don't read the '~/.bashrc' initialization file in an interactive 5663 shell. This is on by default if the shell is invoked as 'sh'. 5664 5665'--posix' 5666 Change the behavior of Bash where the default operation differs 5667 from the POSIX standard to match the standard. This is intended to 5668 make Bash behave as a strict superset of that standard. *Note Bash 5669 POSIX Mode::, for a description of the Bash POSIX mode. 5670 5671'--restricted' 5672 Make the shell a restricted shell (*note The Restricted Shell::). 5673 5674'--verbose' 5675 Equivalent to '-v'. Print shell input lines as they're read. 5676 5677'--version' 5678 Show version information for this instance of Bash on the standard 5679 output and exit successfully. 5680 5681 There are several single-character options that may be supplied at 5682invocation which are not available with the 'set' builtin. 5683 5684'-c' 5685 Read and execute commands from the first non-option argument 5686 COMMAND_STRING, then exit. If there are arguments after the 5687 COMMAND_STRING, the first argument is assigned to '$0' and any 5688 remaining arguments are assigned to the positional parameters. The 5689 assignment to '$0' sets the name of the shell, which is used in 5690 warning and error messages. 5691 5692'-i' 5693 Force the shell to run interactively. Interactive shells are 5694 described in *note Interactive Shells::. 5695 5696'-l' 5697 Make this shell act as if it had been directly invoked by login. 5698 When the shell is interactive, this is equivalent to starting a 5699 login shell with 'exec -l bash'. When the shell is not 5700 interactive, the login shell startup files will be executed. 'exec 5701 bash -l' or 'exec bash --login' will replace the current shell with 5702 a Bash login shell. *Note Bash Startup Files::, for a description 5703 of the special behavior of a login shell. 5704 5705'-r' 5706 Make the shell a restricted shell (*note The Restricted Shell::). 5707 5708'-s' 5709 If this option is present, or if no arguments remain after option 5710 processing, then commands are read from the standard input. This 5711 option allows the positional parameters to be set when invoking an 5712 interactive shell or when reading input through a pipe. 5713 5714'-D' 5715 A list of all double-quoted strings preceded by '$' is printed on 5716 the standard output. These are the strings that are subject to 5717 language translation when the current locale is not 'C' or 'POSIX' 5718 (*note Locale Translation::). This implies the '-n' option; no 5719 commands will be executed. 5720 5721'[-+]O [SHOPT_OPTION]' 5722 SHOPT_OPTION is one of the shell options accepted by the 'shopt' 5723 builtin (*note The Shopt Builtin::). If SHOPT_OPTION is present, 5724 '-O' sets the value of that option; '+O' unsets it. If 5725 SHOPT_OPTION is not supplied, the names and values of the shell 5726 options accepted by 'shopt' are printed on the standard output. If 5727 the invocation option is '+O', the output is displayed in a format 5728 that may be reused as input. 5729 5730'--' 5731 A '--' signals the end of options and disables further option 5732 processing. Any arguments after the '--' are treated as filenames 5733 and arguments. 5734 5735 A _login_ shell is one whose first character of argument zero is '-', 5736or one invoked with the '--login' option. 5737 5738 An _interactive_ shell is one started without non-option arguments, 5739unless '-s' is specified, without specifying the '-c' option, and whose 5740input and output are both connected to terminals (as determined by 5741'isatty(3)'), or one started with the '-i' option. *Note Interactive 5742Shells::, for more information. 5743 5744 If arguments remain after option processing, and neither the '-c' nor 5745the '-s' option has been supplied, the first argument is assumed to be 5746the name of a file containing shell commands (*note Shell Scripts::). 5747When Bash is invoked in this fashion, '$0' is set to the name of the 5748file, and the positional parameters are set to the remaining arguments. 5749Bash reads and executes commands from this file, then exits. Bash's 5750exit status is the exit status of the last command executed in the 5751script. If no commands are executed, the exit status is 0. 5752 5753 5754File: bash.info, Node: Bash Startup Files, Next: Interactive Shells, Prev: Invoking Bash, Up: Bash Features 5755 57566.2 Bash Startup Files 5757====================== 5758 5759This section describes how Bash executes its startup files. If any of 5760the files exist but cannot be read, Bash reports an error. Tildes are 5761expanded in filenames as described above under Tilde Expansion (*note 5762Tilde Expansion::). 5763 5764 Interactive shells are described in *note Interactive Shells::. 5765 5766Invoked as an interactive login shell, or with '--login' 5767........................................................ 5768 5769When Bash is invoked as an interactive login shell, or as a 5770non-interactive shell with the '--login' option, it first reads and 5771executes commands from the file '/etc/profile', if that file exists. 5772After reading that file, it looks for '~/.bash_profile', 5773'~/.bash_login', and '~/.profile', in that order, and reads and executes 5774commands from the first one that exists and is readable. The 5775'--noprofile' option may be used when the shell is started to inhibit 5776this behavior. 5777 5778 When an interactive login shell exits, or a non-interactive login 5779shell executes the 'exit' builtin command, Bash reads and executes 5780commands from the file '~/.bash_logout', if it exists. 5781 5782Invoked as an interactive non-login shell 5783......................................... 5784 5785When an interactive shell that is not a login shell is started, Bash 5786reads and executes commands from '~/.bashrc', if that file exists. This 5787may be inhibited by using the '--norc' option. The '--rcfile FILE' 5788option will force Bash to read and execute commands from FILE instead of 5789'~/.bashrc'. 5790 5791 So, typically, your '~/.bash_profile' contains the line 5792 if [ -f ~/.bashrc ]; then . ~/.bashrc; fi 5793after (or before) any login-specific initializations. 5794 5795Invoked non-interactively 5796......................... 5797 5798When Bash is started non-interactively, to run a shell script, for 5799example, it looks for the variable 'BASH_ENV' in the environment, 5800expands its value if it appears there, and uses the expanded value as 5801the name of a file to read and execute. Bash behaves as if the 5802following command were executed: 5803 if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi 5804but the value of the 'PATH' variable is not used to search for the 5805filename. 5806 5807 As noted above, if a non-interactive shell is invoked with the 5808'--login' option, Bash attempts to read and execute commands from the 5809login shell startup files. 5810 5811Invoked with name 'sh' 5812...................... 5813 5814If Bash is invoked with the name 'sh', it tries to mimic the startup 5815behavior of historical versions of 'sh' as closely as possible, while 5816conforming to the POSIX standard as well. 5817 5818 When invoked as an interactive login shell, or as a non-interactive 5819shell with the '--login' option, it first attempts to read and execute 5820commands from '/etc/profile' and '~/.profile', in that order. The 5821'--noprofile' option may be used to inhibit this behavior. When invoked 5822as an interactive shell with the name 'sh', Bash looks for the variable 5823'ENV', expands its value if it is defined, and uses the expanded value 5824as the name of a file to read and execute. Since a shell invoked as 5825'sh' does not attempt to read and execute commands from any other 5826startup files, the '--rcfile' option has no effect. A non-interactive 5827shell invoked with the name 'sh' does not attempt to read any other 5828startup files. 5829 5830 When invoked as 'sh', Bash enters POSIX mode after the startup files 5831are read. 5832 5833Invoked in POSIX mode 5834..................... 5835 5836When Bash is started in POSIX mode, as with the '--posix' command line 5837option, it follows the POSIX standard for startup files. In this mode, 5838interactive shells expand the 'ENV' variable and commands are read and 5839executed from the file whose name is the expanded value. No other 5840startup files are read. 5841 5842Invoked by remote shell daemon 5843.............................. 5844 5845Bash attempts to determine when it is being run with its standard input 5846connected to a network connection, as when executed by the remote shell 5847daemon, usually 'rshd', or the secure shell daemon 'sshd'. If Bash 5848determines it is being run in this fashion, it reads and executes 5849commands from '~/.bashrc', if that file exists and is readable. It will 5850not do this if invoked as 'sh'. The '--norc' option may be used to 5851inhibit this behavior, and the '--rcfile' option may be used to force 5852another file to be read, but neither 'rshd' nor 'sshd' generally invoke 5853the shell with those options or allow them to be specified. 5854 5855Invoked with unequal effective and real UID/GIDs 5856................................................ 5857 5858If Bash is started with the effective user (group) id not equal to the 5859real user (group) id, and the '-p' option is not supplied, no startup 5860files are read, shell functions are not inherited from the environment, 5861the 'SHELLOPTS', 'BASHOPTS', 'CDPATH', and 'GLOBIGNORE' variables, if 5862they appear in the environment, are ignored, and the effective user id 5863is set to the real user id. If the '-p' option is supplied at 5864invocation, the startup behavior is the same, but the effective user id 5865is not reset. 5866 5867 5868File: bash.info, Node: Interactive Shells, Next: Bash Conditional Expressions, Prev: Bash Startup Files, Up: Bash Features 5869 58706.3 Interactive Shells 5871====================== 5872 5873* Menu: 5874 5875* What is an Interactive Shell?:: What determines whether a shell is Interactive. 5876* Is this Shell Interactive?:: How to tell if a shell is interactive. 5877* Interactive Shell Behavior:: What changes in a interactive shell? 5878 5879 5880File: bash.info, Node: What is an Interactive Shell?, Next: Is this Shell Interactive?, Up: Interactive Shells 5881 58826.3.1 What is an Interactive Shell? 5883----------------------------------- 5884 5885An interactive shell is one started without non-option arguments, unless 5886'-s' is specified, without specifying the '-c' option, and whose input 5887and error output are both connected to terminals (as determined by 5888'isatty(3)'), or one started with the '-i' option. 5889 5890 An interactive shell generally reads from and writes to a user's 5891terminal. 5892 5893 The '-s' invocation option may be used to set the positional 5894parameters when an interactive shell is started. 5895 5896 5897File: bash.info, Node: Is this Shell Interactive?, Next: Interactive Shell Behavior, Prev: What is an Interactive Shell?, Up: Interactive Shells 5898 58996.3.2 Is this Shell Interactive? 5900-------------------------------- 5901 5902To determine within a startup script whether or not Bash is running 5903interactively, test the value of the '-' special parameter. It contains 5904'i' when the shell is interactive. For example: 5905 5906 case "$-" in 5907 *i*) echo This shell is interactive ;; 5908 *) echo This shell is not interactive ;; 5909 esac 5910 5911 Alternatively, startup scripts may examine the variable 'PS1'; it is 5912unset in non-interactive shells, and set in interactive shells. Thus: 5913 5914 if [ -z "$PS1" ]; then 5915 echo This shell is not interactive 5916 else 5917 echo This shell is interactive 5918 fi 5919 5920 5921File: bash.info, Node: Interactive Shell Behavior, Prev: Is this Shell Interactive?, Up: Interactive Shells 5922 59236.3.3 Interactive Shell Behavior 5924-------------------------------- 5925 5926When the shell is running interactively, it changes its behavior in 5927several ways. 5928 5929 1. Startup files are read and executed as described in *note Bash 5930 Startup Files::. 5931 5932 2. Job Control (*note Job Control::) is enabled by default. When job 5933 control is in effect, Bash ignores the keyboard-generated job 5934 control signals 'SIGTTIN', 'SIGTTOU', and 'SIGTSTP'. 5935 5936 3. Bash expands and displays 'PS1' before reading the first line of a 5937 command, and expands and displays 'PS2' before reading the second 5938 and subsequent lines of a multi-line command. Bash expands and 5939 displays 'PS0' after it reads a command but before executing it. 5940 See *note Controlling the Prompt::, for a complete list of prompt 5941 string escape sequences. 5942 5943 4. Bash executes the values of the set elements of the 5944 'PROMPT_COMMANDS' array variable as commands before printing the 5945 primary prompt, '$PS1' (*note Bash Variables::). 5946 5947 5. Readline (*note Command Line Editing::) is used to read commands 5948 from the user's terminal. 5949 5950 6. Bash inspects the value of the 'ignoreeof' option to 'set -o' 5951 instead of exiting immediately when it receives an 'EOF' on its 5952 standard input when reading a command (*note The Set Builtin::). 5953 5954 7. Command history (*note Bash History Facilities::) and history 5955 expansion (*note History Interaction::) are enabled by default. 5956 Bash will save the command history to the file named by '$HISTFILE' 5957 when a shell with history enabled exits. 5958 5959 8. Alias expansion (*note Aliases::) is performed by default. 5960 5961 9. In the absence of any traps, Bash ignores 'SIGTERM' (*note 5962 Signals::). 5963 5964 10. In the absence of any traps, 'SIGINT' is caught and handled (*note 5965 Signals::). 'SIGINT' will interrupt some shell builtins. 5966 5967 11. An interactive login shell sends a 'SIGHUP' to all jobs on exit if 5968 the 'huponexit' shell option has been enabled (*note Signals::). 5969 5970 12. The '-n' invocation option is ignored, and 'set -n' has no effect 5971 (*note The Set Builtin::). 5972 5973 13. Bash will check for mail periodically, depending on the values of 5974 the 'MAIL', 'MAILPATH', and 'MAILCHECK' shell variables (*note Bash 5975 Variables::). 5976 5977 14. Expansion errors due to references to unbound shell variables 5978 after 'set -u' has been enabled will not cause the shell to exit 5979 (*note The Set Builtin::). 5980 5981 15. The shell will not exit on expansion errors caused by VAR being 5982 unset or null in '${VAR:?WORD}' expansions (*note Shell Parameter 5983 Expansion::). 5984 5985 16. Redirection errors encountered by shell builtins will not cause 5986 the shell to exit. 5987 5988 17. When running in POSIX mode, a special builtin returning an error 5989 status will not cause the shell to exit (*note Bash POSIX Mode::). 5990 5991 18. A failed 'exec' will not cause the shell to exit (*note Bourne 5992 Shell Builtins::). 5993 5994 19. Parser syntax errors will not cause the shell to exit. 5995 5996 20. Simple spelling correction for directory arguments to the 'cd' 5997 builtin is enabled by default (see the description of the 'cdspell' 5998 option to the 'shopt' builtin in *note The Shopt Builtin::). 5999 6000 21. The shell will check the value of the 'TMOUT' variable and exit if 6001 a command is not read within the specified number of seconds after 6002 printing '$PS1' (*note Bash Variables::). 6003 6004 6005File: bash.info, Node: Bash Conditional Expressions, Next: Shell Arithmetic, Prev: Interactive Shells, Up: Bash Features 6006 60076.4 Bash Conditional Expressions 6008================================ 6009 6010Conditional expressions are used by the '[[' compound command and the 6011'test' and '[' builtin commands. The 'test' and '[' commands determine 6012their behavior based on the number of arguments; see the descriptions of 6013those commands for any other command-specific actions. 6014 6015 Expressions may be unary or binary, and are formed from the following 6016primaries. Unary expressions are often used to examine the status of a 6017file. There are string operators and numeric comparison operators as 6018well. Bash handles several filenames specially when they are used in 6019expressions. If the operating system on which Bash is running provides 6020these special files, Bash will use them; otherwise it will emulate them 6021internally with this behavior: If the FILE argument to one of the 6022primaries is of the form '/dev/fd/N', then file descriptor N is checked. 6023If the FILE argument to one of the primaries is one of '/dev/stdin', 6024'/dev/stdout', or '/dev/stderr', file descriptor 0, 1, or 2, 6025respectively, is checked. 6026 6027 When used with '[[', the '<' and '>' operators sort lexicographically 6028using the current locale. The 'test' command uses ASCII ordering. 6029 6030 Unless otherwise specified, primaries that operate on files follow 6031symbolic links and operate on the target of the link, rather than the 6032link itself. 6033 6034'-a FILE' 6035 True if FILE exists. 6036 6037'-b FILE' 6038 True if FILE exists and is a block special file. 6039 6040'-c FILE' 6041 True if FILE exists and is a character special file. 6042 6043'-d FILE' 6044 True if FILE exists and is a directory. 6045 6046'-e FILE' 6047 True if FILE exists. 6048 6049'-f FILE' 6050 True if FILE exists and is a regular file. 6051 6052'-g FILE' 6053 True if FILE exists and its set-group-id bit is set. 6054 6055'-h FILE' 6056 True if FILE exists and is a symbolic link. 6057 6058'-k FILE' 6059 True if FILE exists and its "sticky" bit is set. 6060 6061'-p FILE' 6062 True if FILE exists and is a named pipe (FIFO). 6063 6064'-r FILE' 6065 True if FILE exists and is readable. 6066 6067'-s FILE' 6068 True if FILE exists and has a size greater than zero. 6069 6070'-t FD' 6071 True if file descriptor FD is open and refers to a terminal. 6072 6073'-u FILE' 6074 True if FILE exists and its set-user-id bit is set. 6075 6076'-w FILE' 6077 True if FILE exists and is writable. 6078 6079'-x FILE' 6080 True if FILE exists and is executable. 6081 6082'-G FILE' 6083 True if FILE exists and is owned by the effective group id. 6084 6085'-L FILE' 6086 True if FILE exists and is a symbolic link. 6087 6088'-N FILE' 6089 True if FILE exists and has been modified since it was last read. 6090 6091'-O FILE' 6092 True if FILE exists and is owned by the effective user id. 6093 6094'-S FILE' 6095 True if FILE exists and is a socket. 6096 6097'FILE1 -ef FILE2' 6098 True if FILE1 and FILE2 refer to the same device and inode numbers. 6099 6100'FILE1 -nt FILE2' 6101 True if FILE1 is newer (according to modification date) than FILE2, 6102 or if FILE1 exists and FILE2 does not. 6103 6104'FILE1 -ot FILE2' 6105 True if FILE1 is older than FILE2, or if FILE2 exists and FILE1 6106 does not. 6107 6108'-o OPTNAME' 6109 True if the shell option OPTNAME is enabled. The list of options 6110 appears in the description of the '-o' option to the 'set' builtin 6111 (*note The Set Builtin::). 6112 6113'-v VARNAME' 6114 True if the shell variable VARNAME is set (has been assigned a 6115 value). 6116 6117'-R VARNAME' 6118 True if the shell variable VARNAME is set and is a name reference. 6119 6120'-z STRING' 6121 True if the length of STRING is zero. 6122 6123'-n STRING' 6124'STRING' 6125 True if the length of STRING is non-zero. 6126 6127'STRING1 == STRING2' 6128'STRING1 = STRING2' 6129 True if the strings are equal. When used with the '[[' command, 6130 this performs pattern matching as described above (*note 6131 Conditional Constructs::). 6132 6133 '=' should be used with the 'test' command for POSIX conformance. 6134 6135'STRING1 != STRING2' 6136 True if the strings are not equal. 6137 6138'STRING1 < STRING2' 6139 True if STRING1 sorts before STRING2 lexicographically. 6140 6141'STRING1 > STRING2' 6142 True if STRING1 sorts after STRING2 lexicographically. 6143 6144'ARG1 OP ARG2' 6145 'OP' is one of '-eq', '-ne', '-lt', '-le', '-gt', or '-ge'. These 6146 arithmetic binary operators return true if ARG1 is equal to, not 6147 equal to, less than, less than or equal to, greater than, or 6148 greater than or equal to ARG2, respectively. ARG1 and ARG2 may be 6149 positive or negative integers. When used with the '[[' command, 6150 ARG1 and ARG2 are evaluated as arithmetic expressions (*note Shell 6151 Arithmetic::). 6152 6153 6154File: bash.info, Node: Shell Arithmetic, Next: Aliases, Prev: Bash Conditional Expressions, Up: Bash Features 6155 61566.5 Shell Arithmetic 6157==================== 6158 6159The shell allows arithmetic expressions to be evaluated, as one of the 6160shell expansions or by using the '((' compound command, the 'let' 6161builtin, or the '-i' option to the 'declare' builtin. 6162 6163 Evaluation is done in fixed-width integers with no check for 6164overflow, though division by 0 is trapped and flagged as an error. The 6165operators and their precedence, associativity, and values are the same 6166as in the C language. The following list of operators is grouped into 6167levels of equal-precedence operators. The levels are listed in order of 6168decreasing precedence. 6169 6170'ID++ ID--' 6171 variable post-increment and post-decrement 6172 6173'++ID --ID' 6174 variable pre-increment and pre-decrement 6175 6176'- +' 6177 unary minus and plus 6178 6179'! ~' 6180 logical and bitwise negation 6181 6182'**' 6183 exponentiation 6184 6185'* / %' 6186 multiplication, division, remainder 6187 6188'+ -' 6189 addition, subtraction 6190 6191'<< >>' 6192 left and right bitwise shifts 6193 6194'<= >= < >' 6195 comparison 6196 6197'== !=' 6198 equality and inequality 6199 6200'&' 6201 bitwise AND 6202 6203'^' 6204 bitwise exclusive OR 6205 6206'|' 6207 bitwise OR 6208 6209'&&' 6210 logical AND 6211 6212'||' 6213 logical OR 6214 6215'expr ? expr : expr' 6216 conditional operator 6217 6218'= *= /= %= += -= <<= >>= &= ^= |=' 6219 assignment 6220 6221'expr1 , expr2' 6222 comma 6223 6224 Shell variables are allowed as operands; parameter expansion is 6225performed before the expression is evaluated. Within an expression, 6226shell variables may also be referenced by name without using the 6227parameter expansion syntax. A shell variable that is null or unset 6228evaluates to 0 when referenced by name without using the parameter 6229expansion syntax. The value of a variable is evaluated as an arithmetic 6230expression when it is referenced, or when a variable which has been 6231given the INTEGER attribute using 'declare -i' is assigned a value. A 6232null value evaluates to 0. A shell variable need not have its INTEGER 6233attribute turned on to be used in an expression. 6234 6235 Integer constants follow the C language definition, without suffixes 6236or character constants. Constants with a leading 0 are interpreted as 6237octal numbers. A leading '0x' or '0X' denotes hexadecimal. Otherwise, 6238numbers take the form [BASE'#']N, where the optional BASE is a decimal 6239number between 2 and 64 representing the arithmetic base, and N is a 6240number in that base. If BASE'#' is omitted, then base 10 is used. When 6241specifying N, if a non-digit is required, the digits greater than 9 are 6242represented by the lowercase letters, the uppercase letters, '@', and 6243'_', in that order. If BASE is less than or equal to 36, lowercase and 6244uppercase letters may be used interchangeably to represent numbers 6245between 10 and 35. 6246 6247 Operators are evaluated in order of precedence. Sub-expressions in 6248parentheses are evaluated first and may override the precedence rules 6249above. 6250 6251 6252File: bash.info, Node: Aliases, Next: Arrays, Prev: Shell Arithmetic, Up: Bash Features 6253 62546.6 Aliases 6255=========== 6256 6257ALIASES allow a string to be substituted for a word when it is used as 6258the first word of a simple command. The shell maintains a list of 6259aliases that may be set and unset with the 'alias' and 'unalias' builtin 6260commands. 6261 6262 The first word of each simple command, if unquoted, is checked to see 6263if it has an alias. If so, that word is replaced by the text of the 6264alias. The characters '/', '$', '`', '=' and any of the shell 6265metacharacters or quoting characters listed above may not appear in an 6266alias name. The replacement text may contain any valid shell input, 6267including shell metacharacters. The first word of the replacement text 6268is tested for aliases, but a word that is identical to an alias being 6269expanded is not expanded a second time. This means that one may alias 6270'ls' to '"ls -F"', for instance, and Bash does not try to recursively 6271expand the replacement text. If the last character of the alias value 6272is a BLANK, then the next command word following the alias is also 6273checked for alias expansion. 6274 6275 Aliases are created and listed with the 'alias' command, and removed 6276with the 'unalias' command. 6277 6278 There is no mechanism for using arguments in the replacement text, as 6279in 'csh'. If arguments are needed, a shell function should be used 6280(*note Shell Functions::). 6281 6282 Aliases are not expanded when the shell is not interactive, unless 6283the 'expand_aliases' shell option is set using 'shopt' (*note The Shopt 6284Builtin::). 6285 6286 The rules concerning the definition and use of aliases are somewhat 6287confusing. Bash always reads at least one complete line of input, and 6288all lines that make up a compound command, before executing any of the 6289commands on that line or the compound command. Aliases are expanded 6290when a command is read, not when it is executed. Therefore, an alias 6291definition appearing on the same line as another command does not take 6292effect until the next line of input is read. The commands following the 6293alias definition on that line are not affected by the new alias. This 6294behavior is also an issue when functions are executed. Aliases are 6295expanded when a function definition is read, not when the function is 6296executed, because a function definition is itself a command. As a 6297consequence, aliases defined in a function are not available until after 6298that function is executed. To be safe, always put alias definitions on 6299a separate line, and do not use 'alias' in compound commands. 6300 6301 For almost every purpose, shell functions are preferred over aliases. 6302 6303 6304File: bash.info, Node: Arrays, Next: The Directory Stack, Prev: Aliases, Up: Bash Features 6305 63066.7 Arrays 6307========== 6308 6309Bash provides one-dimensional indexed and associative array variables. 6310Any variable may be used as an indexed array; the 'declare' builtin will 6311explicitly declare an array. There is no maximum limit on the size of 6312an array, nor any requirement that members be indexed or assigned 6313contiguously. Indexed arrays are referenced using integers (including 6314arithmetic expressions (*note Shell Arithmetic::)) and are zero-based; 6315associative arrays use arbitrary strings. Unless otherwise noted, 6316indexed array indices must be non-negative integers. 6317 6318 An indexed array is created automatically if any variable is assigned 6319to using the syntax 6320 NAME[SUBSCRIPT]=VALUE 6321 6322The SUBSCRIPT is treated as an arithmetic expression that must evaluate 6323to a number. To explicitly declare an array, use 6324 declare -a NAME 6325The syntax 6326 declare -a NAME[SUBSCRIPT] 6327is also accepted; the SUBSCRIPT is ignored. 6328 6329Associative arrays are created using 6330 declare -A NAME 6331 6332 Attributes may be specified for an array variable using the 'declare' 6333and 'readonly' builtins. Each attribute applies to all members of an 6334array. 6335 6336 Arrays are assigned to using compound assignments of the form 6337 NAME=(VALUE1 VALUE2 ... ) 6338where each VALUE may be of the form '[SUBSCRIPT]='STRING. Indexed array 6339assignments do not require anything but STRING. When assigning to 6340indexed arrays, if the optional subscript is supplied, that index is 6341assigned to; otherwise the index of the element assigned is the last 6342index assigned to by the statement plus one. Indexing starts at zero. 6343 6344 Each VALUE in the list undergoes all the shell expansions described 6345above (*note Shell Expansions::). 6346 6347 When assigning to an associative array, the words in a compound 6348assignment may be either assignment statements, for which the subscript 6349is required, or a list of words that is interpreted as a sequence of 6350alternating keys and values: NAME=(KEY1 VALUE1 KEY2 VALUE2 ... ). These 6351are treated identically to NAME=( [KEY1]=VALUE1 [KEY2]=VALUE2 ... ). 6352The first word in the list determines how the remaining words are 6353interpreted; all assignments in a list must be of the same type. When 6354using key/value pairs, the keys may not be missing or empty; a final 6355missing value is treated like the empty string. 6356 6357 This syntax is also accepted by the 'declare' builtin. Individual 6358array elements may be assigned to using the 'NAME[SUBSCRIPT]=VALUE' 6359syntax introduced above. 6360 6361 When assigning to an indexed array, if NAME is subscripted by a 6362negative number, that number is interpreted as relative to one greater 6363than the maximum index of NAME, so negative indices count back from the 6364end of the array, and an index of -1 references the last element. 6365 6366 Any element of an array may be referenced using '${NAME[SUBSCRIPT]}'. 6367The braces are required to avoid conflicts with the shell's filename 6368expansion operators. If the SUBSCRIPT is '@' or '*', the word expands 6369to all members of the array NAME. These subscripts differ only when the 6370word appears within double quotes. If the word is double-quoted, 6371'${NAME[*]}' expands to a single word with the value of each array 6372member separated by the first character of the 'IFS' variable, and 6373'${NAME[@]}' expands each element of NAME to a separate word. When 6374there are no array members, '${NAME[@]}' expands to nothing. If the 6375double-quoted expansion occurs within a word, the expansion of the first 6376parameter is joined with the beginning part of the original word, and 6377the expansion of the last parameter is joined with the last part of the 6378original word. This is analogous to the expansion of the special 6379parameters '@' and '*'. '${#NAME[SUBSCRIPT]}' expands to the length of 6380'${NAME[SUBSCRIPT]}'. If SUBSCRIPT is '@' or '*', the expansion is the 6381number of elements in the array. If the SUBSCRIPT used to reference an 6382element of an indexed array evaluates to a number less than zero, it is 6383interpreted as relative to one greater than the maximum index of the 6384array, so negative indices count back from the end of the array, and an 6385index of -1 refers to the last element. 6386 6387 Referencing an array variable without a subscript is equivalent to 6388referencing with a subscript of 0. Any reference to a variable using a 6389valid subscript is legal, and 'bash' will create an array if necessary. 6390 6391 An array variable is considered set if a subscript has been assigned 6392a value. The null string is a valid value. 6393 6394 It is possible to obtain the keys (indices) of an array as well as 6395the values. ${!NAME[@]} and ${!NAME[*]} expand to the indices assigned 6396in array variable NAME. The treatment when in double quotes is similar 6397to the expansion of the special parameters '@' and '*' within double 6398quotes. 6399 6400 The 'unset' builtin is used to destroy arrays. 'unset 6401NAME[SUBSCRIPT]' destroys the array element at index SUBSCRIPT. 6402Negative subscripts to indexed arrays are interpreted as described 6403above. Unsetting the last element of an array variable does not unset 6404the variable. 'unset NAME', where NAME is an array, removes the entire 6405array. A subscript of '*' or '@' also removes the entire array. 6406 6407 When using a variable name with a subscript as an argument to a 6408command, such as with 'unset', without using the word expansion syntax 6409described above, the argument is subject to the shell's filename 6410expansion. If filename expansion is not desired, the argument should be 6411quoted. 6412 6413 The 'declare', 'local', and 'readonly' builtins each accept a '-a' 6414option to specify an indexed array and a '-A' option to specify an 6415associative array. If both options are supplied, '-A' takes precedence. 6416The 'read' builtin accepts a '-a' option to assign a list of words read 6417from the standard input to an array, and can read values from the 6418standard input into individual array elements. The 'set' and 'declare' 6419builtins display array values in a way that allows them to be reused as 6420input. 6421 6422 6423File: bash.info, Node: The Directory Stack, Next: Controlling the Prompt, Prev: Arrays, Up: Bash Features 6424 64256.8 The Directory Stack 6426======================= 6427 6428* Menu: 6429 6430* Directory Stack Builtins:: Bash builtin commands to manipulate 6431 the directory stack. 6432 6433The directory stack is a list of recently-visited directories. The 6434'pushd' builtin adds directories to the stack as it changes the current 6435directory, and the 'popd' builtin removes specified directories from the 6436stack and changes the current directory to the directory removed. The 6437'dirs' builtin displays the contents of the directory stack. The 6438current directory is always the "top" of the directory stack. 6439 6440 The contents of the directory stack are also visible as the value of 6441the 'DIRSTACK' shell variable. 6442 6443 6444File: bash.info, Node: Directory Stack Builtins, Up: The Directory Stack 6445 64466.8.1 Directory Stack Builtins 6447------------------------------ 6448 6449'dirs' 6450 dirs [-clpv] [+N | -N] 6451 6452 Display the list of currently remembered directories. Directories 6453 are added to the list with the 'pushd' command; the 'popd' command 6454 removes directories from the list. The current directory is always 6455 the first directory in the stack. 6456 6457 '-c' 6458 Clears the directory stack by deleting all of the elements. 6459 '-l' 6460 Produces a listing using full pathnames; the default listing 6461 format uses a tilde to denote the home directory. 6462 '-p' 6463 Causes 'dirs' to print the directory stack with one entry per 6464 line. 6465 '-v' 6466 Causes 'dirs' to print the directory stack with one entry per 6467 line, prefixing each entry with its index in the stack. 6468 '+N' 6469 Displays the Nth directory (counting from the left of the list 6470 printed by 'dirs' when invoked without options), starting with 6471 zero. 6472 '-N' 6473 Displays the Nth directory (counting from the right of the 6474 list printed by 'dirs' when invoked without options), starting 6475 with zero. 6476 6477'popd' 6478 popd [-n] [+N | -N] 6479 6480 When no arguments are given, 'popd' removes the top directory from 6481 the stack and performs a 'cd' to the new top directory. The 6482 elements are numbered from 0 starting at the first directory listed 6483 with 'dirs'; that is, 'popd' is equivalent to 'popd +0'. 6484 6485 '-n' 6486 Suppresses the normal change of directory when removing 6487 directories from the stack, so that only the stack is 6488 manipulated. 6489 '+N' 6490 Removes the Nth directory (counting from the left of the list 6491 printed by 'dirs'), starting with zero. 6492 '-N' 6493 Removes the Nth directory (counting from the right of the list 6494 printed by 'dirs'), starting with zero. 6495 6496'pushd' 6497 pushd [-n] [+N | -N | DIR] 6498 6499 Save the current directory on the top of the directory stack and 6500 then 'cd' to DIR. With no arguments, 'pushd' exchanges the top two 6501 directories and makes the new top the current directory. 6502 6503 '-n' 6504 Suppresses the normal change of directory when rotating or 6505 adding directories to the stack, so that only the stack is 6506 manipulated. 6507 '+N' 6508 Brings the Nth directory (counting from the left of the list 6509 printed by 'dirs', starting with zero) to the top of the list 6510 by rotating the stack. 6511 '-N' 6512 Brings the Nth directory (counting from the right of the list 6513 printed by 'dirs', starting with zero) to the top of the list 6514 by rotating the stack. 6515 'DIR' 6516 Makes DIR be the top of the stack, making it the new current 6517 directory as if it had been supplied as an argument to the 6518 'cd' builtin. 6519 6520 6521File: bash.info, Node: Controlling the Prompt, Next: The Restricted Shell, Prev: The Directory Stack, Up: Bash Features 6522 65236.9 Controlling the Prompt 6524========================== 6525 6526Bash examines the value of the array variable 'PROMPT_COMMANDS' just 6527before printing each primary prompt. If any elements in 6528'PROMPT_COMMANDS' are set and non-null, Bash executes each value, in 6529numeric order, just as if it had been typed on the command line. 6530 6531 In addition, the following table describes the special characters 6532which can appear in the prompt variables 'PS0', 'PS1', 'PS2', and 'PS4': 6533 6534'\a' 6535 A bell character. 6536'\d' 6537 The date, in "Weekday Month Date" format (e.g., "Tue May 26"). 6538'\D{FORMAT}' 6539 The FORMAT is passed to 'strftime'(3) and the result is inserted 6540 into the prompt string; an empty FORMAT results in a 6541 locale-specific time representation. The braces are required. 6542'\e' 6543 An escape character. 6544'\h' 6545 The hostname, up to the first '.'. 6546'\H' 6547 The hostname. 6548'\j' 6549 The number of jobs currently managed by the shell. 6550'\l' 6551 The basename of the shell's terminal device name. 6552'\n' 6553 A newline. 6554'\r' 6555 A carriage return. 6556'\s' 6557 The name of the shell, the basename of '$0' (the portion following 6558 the final slash). 6559'\t' 6560 The time, in 24-hour HH:MM:SS format. 6561'\T' 6562 The time, in 12-hour HH:MM:SS format. 6563'\@' 6564 The time, in 12-hour am/pm format. 6565'\A' 6566 The time, in 24-hour HH:MM format. 6567'\u' 6568 The username of the current user. 6569'\v' 6570 The version of Bash (e.g., 2.00) 6571'\V' 6572 The release of Bash, version + patchlevel (e.g., 2.00.0) 6573'\w' 6574 The current working directory, with '$HOME' abbreviated with a 6575 tilde (uses the '$PROMPT_DIRTRIM' variable). 6576'\W' 6577 The basename of '$PWD', with '$HOME' abbreviated with a tilde. 6578'\!' 6579 The history number of this command. 6580'\#' 6581 The command number of this command. 6582'\$' 6583 If the effective uid is 0, '#', otherwise '$'. 6584'\NNN' 6585 The character whose ASCII code is the octal value NNN. 6586'\\' 6587 A backslash. 6588'\[' 6589 Begin a sequence of non-printing characters. This could be used to 6590 embed a terminal control sequence into the prompt. 6591'\]' 6592 End a sequence of non-printing characters. 6593 6594 The command number and the history number are usually different: the 6595history number of a command is its position in the history list, which 6596may include commands restored from the history file (*note Bash History 6597Facilities::), while the command number is the position in the sequence 6598of commands executed during the current shell session. 6599 6600 After the string is decoded, it is expanded via parameter expansion, 6601command substitution, arithmetic expansion, and quote removal, subject 6602to the value of the 'promptvars' shell option (*note The Shopt 6603Builtin::). This can have unwanted side effects if escaped portions of 6604the string appear within command substitution or contain characters 6605special to word expansion. 6606 6607 6608File: bash.info, Node: The Restricted Shell, Next: Bash POSIX Mode, Prev: Controlling the Prompt, Up: Bash Features 6609 66106.10 The Restricted Shell 6611========================= 6612 6613If Bash is started with the name 'rbash', or the '--restricted' or '-r' 6614option is supplied at invocation, the shell becomes restricted. A 6615restricted shell is used to set up an environment more controlled than 6616the standard shell. A restricted shell behaves identically to 'bash' 6617with the exception that the following are disallowed or not performed: 6618 6619 * Changing directories with the 'cd' builtin. 6620 * Setting or unsetting the values of the 'SHELL', 'PATH', 'HISTFILE', 6621 'ENV', or 'BASH_ENV' variables. 6622 * Specifying command names containing slashes. 6623 * Specifying a filename containing a slash as an argument to the '.' 6624 builtin command. 6625 * Specifying a filename containing a slash as an argument to the 6626 'history' builtin command. 6627 * Specifying a filename containing a slash as an argument to the '-p' 6628 option to the 'hash' builtin command. 6629 * Importing function definitions from the shell environment at 6630 startup. 6631 * Parsing the value of 'SHELLOPTS' from the shell environment at 6632 startup. 6633 * Redirecting output using the '>', '>|', '<>', '>&', '&>', and '>>' 6634 redirection operators. 6635 * Using the 'exec' builtin to replace the shell with another command. 6636 * Adding or deleting builtin commands with the '-f' and '-d' options 6637 to the 'enable' builtin. 6638 * Using the 'enable' builtin command to enable disabled shell 6639 builtins. 6640 * Specifying the '-p' option to the 'command' builtin. 6641 * Turning off restricted mode with 'set +r' or 'set +o restricted'. 6642 6643 These restrictions are enforced after any startup files are read. 6644 6645 When a command that is found to be a shell script is executed (*note 6646Shell Scripts::), 'rbash' turns off any restrictions in the shell 6647spawned to execute the script. 6648 6649 The restricted shell mode is only one component of a useful 6650restricted environment. It should be accompanied by setting 'PATH' to a 6651value that allows execution of only a few verified commands (commands 6652that allow shell escapes are particularly vulnerable), leaving the user 6653in a non-writable directory other than his home directory after login, 6654not allowing the restricted shell to execute shell scripts, and cleaning 6655the environment of variables that cause some commands to modify their 6656behavior (e.g., 'VISUAL' or 'PAGER'). 6657 6658 Modern systems provide more secure ways to implement a restricted 6659environment, such as 'jails', 'zones', or 'containers'. 6660 6661 6662File: bash.info, Node: Bash POSIX Mode, Next: Shell Compatibility Mode, Prev: The Restricted Shell, Up: Bash Features 6663 66646.11 Bash POSIX Mode 6665==================== 6666 6667Starting Bash with the '--posix' command-line option or executing 'set 6668-o posix' while Bash is running will cause Bash to conform more closely 6669to the POSIX standard by changing the behavior to match that specified 6670by POSIX in areas where the Bash default differs. 6671 6672 When invoked as 'sh', Bash enters POSIX mode after reading the 6673startup files. 6674 6675 The following list is what's changed when 'POSIX mode' is in effect: 6676 6677 1. Bash ensures that the 'POSIXLY_CORRECT' variable is set. 6678 6679 2. When a command in the hash table no longer exists, Bash will 6680 re-search '$PATH' to find the new location. This is also available 6681 with 'shopt -s checkhash'. 6682 6683 3. Bash will not insert a command without the execute bit set into the 6684 command hash table, even if it returns it as a (last-ditch) result 6685 from a '$PATH' search. 6686 6687 4. The message printed by the job control code and builtins when a job 6688 exits with a non-zero status is 'Done(status)'. 6689 6690 5. The message printed by the job control code and builtins when a job 6691 is stopped is 'Stopped(SIGNAME)', where SIGNAME is, for example, 6692 'SIGTSTP'. 6693 6694 6. Alias expansion is always enabled, even in non-interactive shells. 6695 6696 7. Reserved words appearing in a context where reserved words are 6697 recognized do not undergo alias expansion. 6698 6699 8. The POSIX 'PS1' and 'PS2' expansions of '!' to the history number 6700 and '!!' to '!' are enabled, and parameter expansion is performed 6701 on the values of 'PS1' and 'PS2' regardless of the setting of the 6702 'promptvars' option. 6703 6704 9. The POSIX startup files are executed ('$ENV') rather than the 6705 normal Bash files. 6706 6707 10. Tilde expansion is only performed on assignments preceding a 6708 command name, rather than on all assignment statements on the line. 6709 6710 11. The default history file is '~/.sh_history' (this is the default 6711 value of '$HISTFILE'). 6712 6713 12. Redirection operators do not perform filename expansion on the 6714 word in the redirection unless the shell is interactive. 6715 6716 13. Redirection operators do not perform word splitting on the word in 6717 the redirection. 6718 6719 14. Function names must be valid shell 'name's. That is, they may not 6720 contain characters other than letters, digits, and underscores, and 6721 may not start with a digit. Declaring a function with an invalid 6722 name causes a fatal syntax error in non-interactive shells. 6723 6724 15. Function names may not be the same as one of the POSIX special 6725 builtins. 6726 6727 16. POSIX special builtins are found before shell functions during 6728 command lookup. 6729 6730 17. When printing shell function definitions (e.g., by 'type'), Bash 6731 does not print the 'function' keyword. 6732 6733 18. Literal tildes that appear as the first character in elements of 6734 the 'PATH' variable are not expanded as described above under *note 6735 Tilde Expansion::. 6736 6737 19. The 'time' reserved word may be used by itself as a command. When 6738 used in this way, it displays timing statistics for the shell and 6739 its completed children. The 'TIMEFORMAT' variable controls the 6740 format of the timing information. 6741 6742 20. When parsing and expanding a ${...} expansion that appears within 6743 double quotes, single quotes are no longer special and cannot be 6744 used to quote a closing brace or other special character, unless 6745 the operator is one of those defined to perform pattern removal. 6746 In this case, they do not have to appear as matched pairs. 6747 6748 21. The parser does not recognize 'time' as a reserved word if the 6749 next token begins with a '-'. 6750 6751 22. The '!' character does not introduce history expansion within a 6752 double-quoted string, even if the 'histexpand' option is enabled. 6753 6754 23. If a POSIX special builtin returns an error status, a 6755 non-interactive shell exits. The fatal errors are those listed in 6756 the POSIX standard, and include things like passing incorrect 6757 options, redirection errors, variable assignment errors for 6758 assignments preceding the command name, and so on. 6759 6760 24. A non-interactive shell exits with an error status if a variable 6761 assignment error occurs when no command name follows the assignment 6762 statements. A variable assignment error occurs, for example, when 6763 trying to assign a value to a readonly variable. 6764 6765 25. A non-interactive shell exits with an error status if a variable 6766 assignment error occurs in an assignment statement preceding a 6767 special builtin, but not with any other simple command. 6768 6769 26. A non-interactive shell exits with an error status if the 6770 iteration variable in a 'for' statement or the selection variable 6771 in a 'select' statement is a readonly variable. 6772 6773 27. Non-interactive shells exit if FILENAME in '.' FILENAME is not 6774 found. 6775 6776 28. Non-interactive shells exit if a syntax error in an arithmetic 6777 expansion results in an invalid expression. 6778 6779 29. Non-interactive shells exit if a parameter expansion error occurs. 6780 6781 30. Non-interactive shells exit if there is a syntax error in a script 6782 read with the '.' or 'source' builtins, or in a string processed by 6783 the 'eval' builtin. 6784 6785 31. While variable indirection is available, it may not be applied to 6786 the '#' and '?' special parameters. 6787 6788 32. When expanding the '*' special parameter in a pattern context 6789 where the expansion is double-quoted does not treat the '$*' as if 6790 it were double-quoted. 6791 6792 33. Assignment statements preceding POSIX special builtins persist in 6793 the shell environment after the builtin completes. 6794 6795 34. The 'command' builtin does not prevent builtins that take 6796 assignment statements as arguments from expanding them as 6797 assignment statements; when not in POSIX mode, assignment builtins 6798 lose their assignment statement expansion properties when preceded 6799 by 'command'. 6800 6801 35. The 'bg' builtin uses the required format to describe each job 6802 placed in the background, which does not include an indication of 6803 whether the job is the current or previous job. 6804 6805 36. The output of 'kill -l' prints all the signal names on a single 6806 line, separated by spaces, without the 'SIG' prefix. 6807 6808 37. The 'kill' builtin does not accept signal names with a 'SIG' 6809 prefix. 6810 6811 38. The 'export' and 'readonly' builtin commands display their output 6812 in the format required by POSIX. 6813 6814 39. The 'trap' builtin displays signal names without the leading 6815 'SIG'. 6816 6817 40. The 'trap' builtin doesn't check the first argument for a possible 6818 signal specification and revert the signal handling to the original 6819 disposition if it is, unless that argument consists solely of 6820 digits and is a valid signal number. If users want to reset the 6821 handler for a given signal to the original disposition, they should 6822 use '-' as the first argument. 6823 6824 41. 'trap -p' displays signals whose dispositions are set to SIG_DFL 6825 and those that were ignored when the shell started. 6826 6827 42. The '.' and 'source' builtins do not search the current directory 6828 for the filename argument if it is not found by searching 'PATH'. 6829 6830 43. Enabling POSIX mode has the effect of setting the 6831 'inherit_errexit' option, so subshells spawned to execute command 6832 substitutions inherit the value of the '-e' option from the parent 6833 shell. When the 'inherit_errexit' option is not enabled, Bash 6834 clears the '-e' option in such subshells. 6835 6836 44. Enabling POSIX mode has the effect of setting the 'shift_verbose' 6837 option, so numeric arguments to 'shift' that exceed the number of 6838 positional parameters will result in an error message. 6839 6840 45. When the 'alias' builtin displays alias definitions, it does not 6841 display them with a leading 'alias ' unless the '-p' option is 6842 supplied. 6843 6844 46. When the 'set' builtin is invoked without options, it does not 6845 display shell function names and definitions. 6846 6847 47. When the 'set' builtin is invoked without options, it displays 6848 variable values without quotes, unless they contain shell 6849 metacharacters, even if the result contains nonprinting characters. 6850 6851 48. When the 'cd' builtin is invoked in LOGICAL mode, and the pathname 6852 constructed from '$PWD' and the directory name supplied as an 6853 argument does not refer to an existing directory, 'cd' will fail 6854 instead of falling back to PHYSICAL mode. 6855 6856 49. When the 'cd' builtin cannot change a directory because the length 6857 of the pathname constructed from '$PWD' and the directory name 6858 supplied as an argument exceeds PATH_MAX when all symbolic links 6859 are expanded, 'cd' will fail instead of attempting to use only the 6860 supplied directory name. 6861 6862 50. The 'pwd' builtin verifies that the value it prints is the same as 6863 the current directory, even if it is not asked to check the file 6864 system with the '-P' option. 6865 6866 51. When listing the history, the 'fc' builtin does not include an 6867 indication of whether or not a history entry has been modified. 6868 6869 52. The default editor used by 'fc' is 'ed'. 6870 6871 53. The 'type' and 'command' builtins will not report a non-executable 6872 file as having been found, though the shell will attempt to execute 6873 such a file if it is the only so-named file found in '$PATH'. 6874 6875 54. The 'vi' editing mode will invoke the 'vi' editor directly when 6876 the 'v' command is run, instead of checking '$VISUAL' and 6877 '$EDITOR'. 6878 6879 55. When the 'xpg_echo' option is enabled, Bash does not attempt to 6880 interpret any arguments to 'echo' as options. Each argument is 6881 displayed, after escape characters are converted. 6882 6883 56. The 'ulimit' builtin uses a block size of 512 bytes for the '-c' 6884 and '-f' options. 6885 6886 57. The arrival of 'SIGCHLD' when a trap is set on 'SIGCHLD' does not 6887 interrupt the 'wait' builtin and cause it to return immediately. 6888 The trap command is run once for each child that exits. 6889 6890 58. The 'read' builtin may be interrupted by a signal for which a trap 6891 has been set. If Bash receives a trapped signal while executing 6892 'read', the trap handler executes and 'read' returns an exit status 6893 greater than 128. 6894 6895 59. Bash removes an exited background process's status from the list 6896 of such statuses after the 'wait' builtin is used to obtain it. 6897 6898 There is other POSIX behavior that Bash does not implement by default 6899even when in POSIX mode. Specifically: 6900 6901 1. The 'fc' builtin checks '$EDITOR' as a program to edit history 6902 entries if 'FCEDIT' is unset, rather than defaulting directly to 6903 'ed'. 'fc' uses 'ed' if 'EDITOR' is unset. 6904 6905 2. As noted above, Bash requires the 'xpg_echo' option to be enabled 6906 for the 'echo' builtin to be fully conformant. 6907 6908 Bash can be configured to be POSIX-conformant by default, by 6909specifying the '--enable-strict-posix-default' to 'configure' when 6910building (*note Optional Features::). 6911 6912 6913File: bash.info, Node: Shell Compatibility Mode, Prev: Bash POSIX Mode, Up: Bash Features 6914 69156.12 Shell Compatibility Mode 6916============================= 6917 6918Bash-4.0 introduced the concept of a 'shell compatibility level', 6919specified as a set of options to the shopt builtin ('compat31', 6920'compat32', 'compat40', 'compat41', and so on). There is only one 6921current compatibility level - each option is mutually exclusive. The 6922compatibility level is intended to allow users to select behavior from 6923previous versions that is incompatible with newer versions while they 6924migrate scripts to use current features and behavior. It's intended to 6925be a temporary solution. 6926 6927 This section does not mention behavior that is standard for a 6928particular version (e.g., setting 'compat32' means that quoting the rhs 6929of the regexp matching operator quotes special regexp characters in the 6930word, which is default behavior in bash-3.2 and above). 6931 6932 If a user enables, say, 'compat32', it may affect the behavior of 6933other compatibility levels up to and including the current compatibility 6934level. The idea is that each compatibility level controls behavior that 6935changed in that version of Bash, but that behavior may have been present 6936in earlier versions. For instance, the change to use locale-based 6937comparisons with the '[[' command came in bash-4.1, and earlier versions 6938used ASCII-based comparisons, so enabling 'compat32' will enable 6939ASCII-based comparisons as well. That granularity may not be sufficient 6940for all uses, and as a result users should employ compatibility levels 6941carefully. Read the documentation for a particular feature to find out 6942the current behavior. 6943 6944 Bash-4.3 introduced a new shell variable: 'BASH_COMPAT'. The value 6945assigned to this variable (a decimal version number like 4.2, or an 6946integer corresponding to the 'compat'NN option, like 42) determines the 6947compatibility level. 6948 6949 Starting with bash-4.4, Bash has begun deprecating older 6950compatibility levels. Eventually, the options will be removed in favor 6951of 'BASH_COMPAT'. 6952 6953 Bash-5.0 is the final version for which there will be an individual 6954shopt option for the previous version. Users should use 'BASH_COMPAT' 6955on bash-5.0 and later versions. 6956 6957 The following table describes the behavior changes controlled by each 6958compatibility level setting. The 'compat'NN tag is used as shorthand 6959for setting the compatibility level to NN using one of the following 6960mechanisms. For versions prior to bash-5.0, the compatibility level may 6961be set using the corresponding 'compat'NN shopt option. For bash-4.3 6962and later versions, the 'BASH_COMPAT' variable is preferred, and it is 6963required for bash-5.1 and later versions. 6964 6965'compat31' 6966 * quoting the rhs of the '[[' command's regexp matching operator 6967 (=~) has no special effect 6968 6969'compat32' 6970 * interrupting a command list such as "a ; b ; c" causes the 6971 execution of the next command in the list (in bash-4.0 and 6972 later versions, the shell acts as if it received the 6973 interrupt, so interrupting one command in a list aborts the 6974 execution of the entire list) 6975 6976'compat40' 6977 * the '<' and '>' operators to the '[[' command do not consider 6978 the current locale when comparing strings; they use ASCII 6979 ordering. Bash versions prior to bash-4.1 use ASCII collation 6980 and strcmp(3); bash-4.1 and later use the current locale's 6981 collation sequence and strcoll(3). 6982 6983'compat41' 6984 * in posix mode, 'time' may be followed by options and still be 6985 recognized as a reserved word (this is POSIX interpretation 6986 267) 6987 * in posix mode, the parser requires that an even number of 6988 single quotes occur in the WORD portion of a double-quoted 6989 ${...} parameter expansion and treats them specially, so that 6990 characters within the single quotes are considered quoted 6991 (this is POSIX interpretation 221) 6992 6993'compat42' 6994 * the replacement string in double-quoted pattern substitution 6995 does not undergo quote removal, as it does in versions after 6996 bash-4.2 6997 * in posix mode, single quotes are considered special when 6998 expanding the WORD portion of a double-quoted ${...} parameter 6999 expansion and can be used to quote a closing brace or other 7000 special character (this is part of POSIX interpretation 221); 7001 in later versions, single quotes are not special within 7002 double-quoted word expansions 7003 7004'compat43' 7005 * the shell does not print a warning message if an attempt is 7006 made to use a quoted compound assignment as an argument to 7007 declare (declare -a foo='(1 2)'). Later versions warn that 7008 this usage is deprecated 7009 * word expansion errors are considered non-fatal errors that 7010 cause the current command to fail, even in posix mode (the 7011 default behavior is to make them fatal errors that cause the 7012 shell to exit) 7013 * when executing a shell function, the loop state 7014 (while/until/etc.) is not reset, so 'break' or 'continue' in 7015 that function will break or continue loops in the calling 7016 context. Bash-4.4 and later reset the loop state to prevent 7017 this 7018 7019'compat44' 7020 * the shell sets up the values used by 'BASH_ARGV' and 7021 'BASH_ARGC' so they can expand to the shell's positional 7022 parameters even if extended debugging mode is not enabled 7023 * a subshell inherits loops from its parent context, so 'break' 7024 or 'continue' will cause the subshell to exit. Bash-5.0 and 7025 later reset the loop state to prevent the exit 7026 * variable assignments preceding builtins like 'export' and 7027 'readonly' that set attributes continue to affect variables 7028 with the same name in the calling environment even if the 7029 shell is not in posix mode 7030 7031'compat50 (set using BASH_COMPAT)' 7032 * Bash-5.1 changed the way '$RANDOM' is generated to introduce 7033 slightly more randomness. If the shell compatibility level is 7034 set to 50 or lower, it reverts to the method from bash-5.0 and 7035 previous versions, so seeding the random number generator by 7036 assigning a value to 'RANDOM' will produce the same sequence 7037 as in bash-5.0 7038 * If the command hash table is empty, Bash versions prior to 7039 bash-5.1 printed an informational message to that effect, even 7040 when producing output that can be reused as input. Bash-5.1 7041 suppresses that message when the '-l' option is supplied. 7042 7043 7044File: bash.info, Node: Job Control, Next: Command Line Editing, Prev: Bash Features, Up: Top 7045 70467 Job Control 7047************* 7048 7049This chapter discusses what job control is, how it works, and how Bash 7050allows you to access its facilities. 7051 7052* Menu: 7053 7054* Job Control Basics:: How job control works. 7055* Job Control Builtins:: Bash builtin commands used to interact 7056 with job control. 7057* Job Control Variables:: Variables Bash uses to customize job 7058 control. 7059 7060 7061File: bash.info, Node: Job Control Basics, Next: Job Control Builtins, Up: Job Control 7062 70637.1 Job Control Basics 7064====================== 7065 7066Job control refers to the ability to selectively stop (suspend) the 7067execution of processes and continue (resume) their execution at a later 7068point. A user typically employs this facility via an interactive 7069interface supplied jointly by the operating system kernel's terminal 7070driver and Bash. 7071 7072 The shell associates a JOB with each pipeline. It keeps a table of 7073currently executing jobs, which may be listed with the 'jobs' command. 7074When Bash starts a job asynchronously, it prints a line that looks like: 7075 [1] 25647 7076indicating that this job is job number 1 and that the process ID of the 7077last process in the pipeline associated with this job is 25647. All of 7078the processes in a single pipeline are members of the same job. Bash 7079uses the JOB abstraction as the basis for job control. 7080 7081 To facilitate the implementation of the user interface to job 7082control, the operating system maintains the notion of a current terminal 7083process group ID. Members of this process group (processes whose 7084process group ID is equal to the current terminal process group ID) 7085receive keyboard-generated signals such as 'SIGINT'. These processes 7086are said to be in the foreground. Background processes are those whose 7087process group ID differs from the terminal's; such processes are immune 7088to keyboard-generated signals. Only foreground processes are allowed to 7089read from or, if the user so specifies with 'stty tostop', write to the 7090terminal. Background processes which attempt to read from (write to 7091when 'stty tostop' is in effect) the terminal are sent a 'SIGTTIN' 7092('SIGTTOU') signal by the kernel's terminal driver, which, unless 7093caught, suspends the process. 7094 7095 If the operating system on which Bash is running supports job 7096control, Bash contains facilities to use it. Typing the SUSPEND 7097character (typically '^Z', Control-Z) while a process is running causes 7098that process to be stopped and returns control to Bash. Typing the 7099DELAYED SUSPEND character (typically '^Y', Control-Y) causes the process 7100to be stopped when it attempts to read input from the terminal, and 7101control to be returned to Bash. The user then manipulates the state of 7102this job, using the 'bg' command to continue it in the background, the 7103'fg' command to continue it in the foreground, or the 'kill' command to 7104kill it. A '^Z' takes effect immediately, and has the additional side 7105effect of causing pending output and typeahead to be discarded. 7106 7107 There are a number of ways to refer to a job in the shell. The 7108character '%' introduces a job specification (JOBSPEC). 7109 7110 Job number 'n' may be referred to as '%n'. The symbols '%%' and '%+' 7111refer to the shell's notion of the current job, which is the last job 7112stopped while it was in the foreground or started in the background. A 7113single '%' (with no accompanying job specification) also refers to the 7114current job. The previous job may be referenced using '%-'. If there 7115is only a single job, '%+' and '%-' can both be used to refer to that 7116job. In output pertaining to jobs (e.g., the output of the 'jobs' 7117command), the current job is always flagged with a '+', and the previous 7118job with a '-'. 7119 7120 A job may also be referred to using a prefix of the name used to 7121start it, or using a substring that appears in its command line. For 7122example, '%ce' refers to a stopped job whose command name begins with 7123'ce'. Using '%?ce', on the other hand, refers to any job containing the 7124string 'ce' in its command line. If the prefix or substring matches 7125more than one job, Bash reports an error. 7126 7127 Simply naming a job can be used to bring it into the foreground: '%1' 7128is a synonym for 'fg %1', bringing job 1 from the background into the 7129foreground. Similarly, '%1 &' resumes job 1 in the background, 7130equivalent to 'bg %1' 7131 7132 The shell learns immediately whenever a job changes state. Normally, 7133Bash waits until it is about to print a prompt before reporting changes 7134in a job's status so as to not interrupt any other output. If the '-b' 7135option to the 'set' builtin is enabled, Bash reports such changes 7136immediately (*note The Set Builtin::). Any trap on 'SIGCHLD' is 7137executed for each child process that exits. 7138 7139 If an attempt to exit Bash is made while jobs are stopped, (or 7140running, if the 'checkjobs' option is enabled - see *note The Shopt 7141Builtin::), the shell prints a warning message, and if the 'checkjobs' 7142option is enabled, lists the jobs and their statuses. The 'jobs' 7143command may then be used to inspect their status. If a second attempt 7144to exit is made without an intervening command, Bash does not print 7145another warning, and any stopped jobs are terminated. 7146 7147 When the shell is waiting for a job or process using the 'wait' 7148builtin, and job control is enabled, 'wait' will return when the job 7149changes state. The '-f' option causes 'wait' to wait until the job or 7150process terminates before returning. 7151 7152 7153File: bash.info, Node: Job Control Builtins, Next: Job Control Variables, Prev: Job Control Basics, Up: Job Control 7154 71557.2 Job Control Builtins 7156======================== 7157 7158'bg' 7159 bg [JOBSPEC ...] 7160 7161 Resume each suspended job JOBSPEC in the background, as if it had 7162 been started with '&'. If JOBSPEC is not supplied, the current job 7163 is used. The return status is zero unless it is run when job 7164 control is not enabled, or, when run with job control enabled, any 7165 JOBSPEC was not found or specifies a job that was started without 7166 job control. 7167 7168'fg' 7169 fg [JOBSPEC] 7170 7171 Resume the job JOBSPEC in the foreground and make it the current 7172 job. If JOBSPEC is not supplied, the current job is used. The 7173 return status is that of the command placed into the foreground, or 7174 non-zero if run when job control is disabled or, when run with job 7175 control enabled, JOBSPEC does not specify a valid job or JOBSPEC 7176 specifies a job that was started without job control. 7177 7178'jobs' 7179 jobs [-lnprs] [JOBSPEC] 7180 jobs -x COMMAND [ARGUMENTS] 7181 7182 The first form lists the active jobs. The options have the 7183 following meanings: 7184 7185 '-l' 7186 List process IDs in addition to the normal information. 7187 7188 '-n' 7189 Display information only about jobs that have changed status 7190 since the user was last notified of their status. 7191 7192 '-p' 7193 List only the process ID of the job's process group leader. 7194 7195 '-r' 7196 Display only running jobs. 7197 7198 '-s' 7199 Display only stopped jobs. 7200 7201 If JOBSPEC is given, output is restricted to information about that 7202 job. If JOBSPEC is not supplied, the status of all jobs is listed. 7203 7204 If the '-x' option is supplied, 'jobs' replaces any JOBSPEC found 7205 in COMMAND or ARGUMENTS with the corresponding process group ID, 7206 and executes COMMAND, passing it ARGUMENTs, returning its exit 7207 status. 7208 7209'kill' 7210 kill [-s SIGSPEC] [-n SIGNUM] [-SIGSPEC] JOBSPEC or PID 7211 kill -l|-L [EXIT_STATUS] 7212 7213 Send a signal specified by SIGSPEC or SIGNUM to the process named 7214 by job specification JOBSPEC or process ID PID. SIGSPEC is either 7215 a case-insensitive signal name such as 'SIGINT' (with or without 7216 the 'SIG' prefix) or a signal number; SIGNUM is a signal number. 7217 If SIGSPEC and SIGNUM are not present, 'SIGTERM' is used. The '-l' 7218 option lists the signal names. If any arguments are supplied when 7219 '-l' is given, the names of the signals corresponding to the 7220 arguments are listed, and the return status is zero. EXIT_STATUS 7221 is a number specifying a signal number or the exit status of a 7222 process terminated by a signal. The '-L' option is equivalent to 7223 '-l'. The return status is zero if at least one signal was 7224 successfully sent, or non-zero if an error occurs or an invalid 7225 option is encountered. 7226 7227'wait' 7228 wait [-fn] [-p VARNAME] [JOBSPEC or PID ...] 7229 7230 Wait until the child process specified by each process ID PID or 7231 job specification JOBSPEC exits and return the exit status of the 7232 last command waited for. If a job spec is given, all processes in 7233 the job are waited for. If no arguments are given, 'wait' waits 7234 for all running background jobs and the last-executed process 7235 substitution, if its process id is the same as $!, and the return 7236 status is zero. If the '-n' option is supplied, 'wait' waits for a 7237 single job from the list of PIDS or JOBSPECS or, if no arguments 7238 are supplied, any job, to complete and returns its exit status. If 7239 none of the supplied arguments is a child of the shell, or if no 7240 arguments are supplied and the shell has no unwaited-for children, 7241 the exit status is 127. If the '-p' option is supplied, the 7242 process or job identifier of the job for which the exit status is 7243 returned is assigned to the variable VARNAME named by the option 7244 argument. The variable will be unset initially, before any 7245 assignment. This is useful only when the '-n' option is supplied. 7246 Supplying the '-f' option, when job control is enabled, forces 7247 'wait' to wait for each PID or JOBSPEC to terminate before 7248 returning its status, intead of returning when it changes status. 7249 If neither JOBSPEC nor PID specifies an active child process of the 7250 shell, the return status is 127. 7251 7252'disown' 7253 disown [-ar] [-h] [JOBSPEC ... | PID ... ] 7254 7255 Without options, remove each JOBSPEC from the table of active jobs. 7256 If the '-h' option is given, the job is not removed from the table, 7257 but is marked so that 'SIGHUP' is not sent to the job if the shell 7258 receives a 'SIGHUP'. If JOBSPEC is not present, and neither the 7259 '-a' nor the '-r' option is supplied, the current job is used. If 7260 no JOBSPEC is supplied, the '-a' option means to remove or mark all 7261 jobs; the '-r' option without a JOBSPEC argument restricts 7262 operation to running jobs. 7263 7264'suspend' 7265 suspend [-f] 7266 7267 Suspend the execution of this shell until it receives a 'SIGCONT' 7268 signal. A login shell cannot be suspended; the '-f' option can be 7269 used to override this and force the suspension. 7270 7271 When job control is not active, the 'kill' and 'wait' builtins do not 7272accept JOBSPEC arguments. They must be supplied process IDs. 7273 7274 7275File: bash.info, Node: Job Control Variables, Prev: Job Control Builtins, Up: Job Control 7276 72777.3 Job Control Variables 7278========================= 7279 7280'auto_resume' 7281 This variable controls how the shell interacts with the user and 7282 job control. If this variable exists then single word simple 7283 commands without redirections are treated as candidates for 7284 resumption of an existing job. There is no ambiguity allowed; if 7285 there is more than one job beginning with the string typed, then 7286 the most recently accessed job will be selected. The name of a 7287 stopped job, in this context, is the command line used to start it. 7288 If this variable is set to the value 'exact', the string supplied 7289 must match the name of a stopped job exactly; if set to 7290 'substring', the string supplied needs to match a substring of the 7291 name of a stopped job. The 'substring' value provides 7292 functionality analogous to the '%?' job ID (*note Job Control 7293 Basics::). If set to any other value, the supplied string must be 7294 a prefix of a stopped job's name; this provides functionality 7295 analogous to the '%' job ID. 7296 7297 7298File: bash.info, Node: Command Line Editing, Next: Using History Interactively, Prev: Job Control, Up: Top 7299 73008 Command Line Editing 7301********************** 7302 7303This chapter describes the basic features of the GNU command line 7304editing interface. Command line editing is provided by the Readline 7305library, which is used by several different programs, including Bash. 7306Command line editing is enabled by default when using an interactive 7307shell, unless the '--noediting' option is supplied at shell invocation. 7308Line editing is also used when using the '-e' option to the 'read' 7309builtin command (*note Bash Builtins::). By default, the line editing 7310commands are similar to those of Emacs. A vi-style line editing 7311interface is also available. Line editing can be enabled at any time 7312using the '-o emacs' or '-o vi' options to the 'set' builtin command 7313(*note The Set Builtin::), or disabled using the '+o emacs' or '+o vi' 7314options to 'set'. 7315 7316* Menu: 7317 7318* Introduction and Notation:: Notation used in this text. 7319* Readline Interaction:: The minimum set of commands for editing a line. 7320* Readline Init File:: Customizing Readline from a user's view. 7321* Bindable Readline Commands:: A description of most of the Readline commands 7322 available for binding 7323* Readline vi Mode:: A short description of how to make Readline 7324 behave like the vi editor. 7325* Programmable Completion:: How to specify the possible completions for 7326 a specific command. 7327* Programmable Completion Builtins:: Builtin commands to specify how to 7328 complete arguments for a particular command. 7329* A Programmable Completion Example:: An example shell function for 7330 generating possible completions. 7331 7332 7333File: bash.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing 7334 73358.1 Introduction to Line Editing 7336================================ 7337 7338The following paragraphs describe the notation used to represent 7339keystrokes. 7340 7341 The text 'C-k' is read as 'Control-K' and describes the character 7342produced when the <k> key is pressed while the Control key is depressed. 7343 7344 The text 'M-k' is read as 'Meta-K' and describes the character 7345produced when the Meta key (if you have one) is depressed, and the <k> 7346key is pressed. The Meta key is labeled <ALT> on many keyboards. On 7347keyboards with two keys labeled <ALT> (usually to either side of the 7348space bar), the <ALT> on the left side is generally set to work as a 7349Meta key. The <ALT> key on the right may also be configured to work as 7350a Meta key or may be configured as some other modifier, such as a 7351Compose key for typing accented characters. 7352 7353 If you do not have a Meta or <ALT> key, or another key working as a 7354Meta key, the identical keystroke can be generated by typing <ESC> 7355_first_, and then typing <k>. Either process is known as "metafying" 7356the <k> key. 7357 7358 The text 'M-C-k' is read as 'Meta-Control-k' and describes the 7359character produced by "metafying" 'C-k'. 7360 7361 In addition, several keys have their own names. Specifically, <DEL>, 7362<ESC>, <LFD>, <SPC>, <RET>, and <TAB> all stand for themselves when seen 7363in this text, or in an init file (*note Readline Init File::). If your 7364keyboard lacks a <LFD> key, typing <C-j> will produce the desired 7365character. The <RET> key may be labeled <Return> or <Enter> on some 7366keyboards. 7367 7368 7369File: bash.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing 7370 73718.2 Readline Interaction 7372======================== 7373 7374Often during an interactive session you type in a long line of text, 7375only to notice that the first word on the line is misspelled. The 7376Readline library gives you a set of commands for manipulating the text 7377as you type it in, allowing you to just fix your typo, and not forcing 7378you to retype the majority of the line. Using these editing commands, 7379you move the cursor to the place that needs correction, and delete or 7380insert the text of the corrections. Then, when you are satisfied with 7381the line, you simply press <RET>. You do not have to be at the end of 7382the line to press <RET>; the entire line is accepted regardless of the 7383location of the cursor within the line. 7384 7385* Menu: 7386 7387* Readline Bare Essentials:: The least you need to know about Readline. 7388* Readline Movement Commands:: Moving about the input line. 7389* Readline Killing Commands:: How to delete text, and how to get it back! 7390* Readline Arguments:: Giving numeric arguments to commands. 7391* Searching:: Searching through previous lines. 7392 7393 7394File: bash.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction 7395 73968.2.1 Readline Bare Essentials 7397------------------------------ 7398 7399In order to enter characters into the line, simply type them. The typed 7400character appears where the cursor was, and then the cursor moves one 7401space to the right. If you mistype a character, you can use your erase 7402character to back up and delete the mistyped character. 7403 7404 Sometimes you may mistype a character, and not notice the error until 7405you have typed several other characters. In that case, you can type 7406'C-b' to move the cursor to the left, and then correct your mistake. 7407Afterwards, you can move the cursor to the right with 'C-f'. 7408 7409 When you add text in the middle of a line, you will notice that 7410characters to the right of the cursor are 'pushed over' to make room for 7411the text that you have inserted. Likewise, when you delete text behind 7412the cursor, characters to the right of the cursor are 'pulled back' to 7413fill in the blank space created by the removal of the text. A list of 7414the bare essentials for editing the text of an input line follows. 7415 7416'C-b' 7417 Move back one character. 7418'C-f' 7419 Move forward one character. 7420<DEL> or <Backspace> 7421 Delete the character to the left of the cursor. 7422'C-d' 7423 Delete the character underneath the cursor. 7424Printing characters 7425 Insert the character into the line at the cursor. 7426'C-_' or 'C-x C-u' 7427 Undo the last editing command. You can undo all the way back to an 7428 empty line. 7429 7430(Depending on your configuration, the <Backspace> key be set to delete 7431the character to the left of the cursor and the <DEL> key set to delete 7432the character underneath the cursor, like 'C-d', rather than the 7433character to the left of the cursor.) 7434 7435 7436File: bash.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction 7437 74388.2.2 Readline Movement Commands 7439-------------------------------- 7440 7441The above table describes the most basic keystrokes that you need in 7442order to do editing of the input line. For your convenience, many other 7443commands have been added in addition to 'C-b', 'C-f', 'C-d', and <DEL>. 7444Here are some commands for moving more rapidly about the line. 7445 7446'C-a' 7447 Move to the start of the line. 7448'C-e' 7449 Move to the end of the line. 7450'M-f' 7451 Move forward a word, where a word is composed of letters and 7452 digits. 7453'M-b' 7454 Move backward a word. 7455'C-l' 7456 Clear the screen, reprinting the current line at the top. 7457 7458 Notice how 'C-f' moves forward a character, while 'M-f' moves forward 7459a word. It is a loose convention that control keystrokes operate on 7460characters while meta keystrokes operate on words. 7461 7462 7463File: bash.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction 7464 74658.2.3 Readline Killing Commands 7466------------------------------- 7467 7468"Killing" text means to delete the text from the line, but to save it 7469away for later use, usually by "yanking" (re-inserting) it back into the 7470line. ('Cut' and 'paste' are more recent jargon for 'kill' and 'yank'.) 7471 7472 If the description for a command says that it 'kills' text, then you 7473can be sure that you can get the text back in a different (or the same) 7474place later. 7475 7476 When you use a kill command, the text is saved in a "kill-ring". Any 7477number of consecutive kills save all of the killed text together, so 7478that when you yank it back, you get it all. The kill ring is not line 7479specific; the text that you killed on a previously typed line is 7480available to be yanked back later, when you are typing another line. 7481 7482 Here is the list of commands for killing text. 7483 7484'C-k' 7485 Kill the text from the current cursor position to the end of the 7486 line. 7487 7488'M-d' 7489 Kill from the cursor to the end of the current word, or, if between 7490 words, to the end of the next word. Word boundaries are the same 7491 as those used by 'M-f'. 7492 7493'M-<DEL>' 7494 Kill from the cursor the start of the current word, or, if between 7495 words, to the start of the previous word. Word boundaries are the 7496 same as those used by 'M-b'. 7497 7498'C-w' 7499 Kill from the cursor to the previous whitespace. This is different 7500 than 'M-<DEL>' because the word boundaries differ. 7501 7502 Here is how to "yank" the text back into the line. Yanking means to 7503copy the most-recently-killed text from the kill buffer. 7504 7505'C-y' 7506 Yank the most recently killed text back into the buffer at the 7507 cursor. 7508 7509'M-y' 7510 Rotate the kill-ring, and yank the new top. You can only do this 7511 if the prior command is 'C-y' or 'M-y'. 7512 7513 7514File: bash.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction 7515 75168.2.4 Readline Arguments 7517------------------------ 7518 7519You can pass numeric arguments to Readline commands. Sometimes the 7520argument acts as a repeat count, other times it is the sign of the 7521argument that is significant. If you pass a negative argument to a 7522command which normally acts in a forward direction, that command will 7523act in a backward direction. For example, to kill text back to the 7524start of the line, you might type 'M-- C-k'. 7525 7526 The general way to pass numeric arguments to a command is to type 7527meta digits before the command. If the first 'digit' typed is a minus 7528sign ('-'), then the sign of the argument will be negative. Once you 7529have typed one meta digit to get the argument started, you can type the 7530remainder of the digits, and then the command. For example, to give the 7531'C-d' command an argument of 10, you could type 'M-1 0 C-d', which will 7532delete the next ten characters on the input line. 7533 7534 7535File: bash.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction 7536 75378.2.5 Searching for Commands in the History 7538------------------------------------------- 7539 7540Readline provides commands for searching through the command history 7541(*note Bash History Facilities::) for lines containing a specified 7542string. There are two search modes: "incremental" and 7543"non-incremental". 7544 7545 Incremental searches begin before the user has finished typing the 7546search string. As each character of the search string is typed, 7547Readline displays the next entry from the history matching the string 7548typed so far. An incremental search requires only as many characters as 7549needed to find the desired history entry. To search backward in the 7550history for a particular string, type 'C-r'. Typing 'C-s' searches 7551forward through the history. The characters present in the value of the 7552'isearch-terminators' variable are used to terminate an incremental 7553search. If that variable has not been assigned a value, the <ESC> and 7554'C-J' characters will terminate an incremental search. 'C-g' will abort 7555an incremental search and restore the original line. When the search is 7556terminated, the history entry containing the search string becomes the 7557current line. 7558 7559 To find other matching entries in the history list, type 'C-r' or 7560'C-s' as appropriate. This will search backward or forward in the 7561history for the next entry matching the search string typed so far. Any 7562other key sequence bound to a Readline command will terminate the search 7563and execute that command. For instance, a <RET> will terminate the 7564search and accept the line, thereby executing the command from the 7565history list. A movement command will terminate the search, make the 7566last line found the current line, and begin editing. 7567 7568 Readline remembers the last incremental search string. If two 'C-r's 7569are typed without any intervening characters defining a new search 7570string, any remembered search string is used. 7571 7572 Non-incremental searches read the entire search string before 7573starting to search for matching history lines. The search string may be 7574typed by the user or be part of the contents of the current line. 7575 7576 7577File: bash.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing 7578 75798.3 Readline Init File 7580====================== 7581 7582Although the Readline library comes with a set of Emacs-like keybindings 7583installed by default, it is possible to use a different set of 7584keybindings. Any user can customize programs that use Readline by 7585putting commands in an "inputrc" file, conventionally in his home 7586directory. The name of this file is taken from the value of the shell 7587variable 'INPUTRC'. If that variable is unset, the default is 7588'~/.inputrc'. If that file does not exist or cannot be read, the 7589ultimate default is '/usr/local/etc/inputrc'. The 'bind' builtin command can also 7590be used to set Readline keybindings and variables. *Note Bash 7591Builtins::. 7592 7593 When a program which uses the Readline library starts up, the init 7594file is read, and the key bindings are set. 7595 7596 In addition, the 'C-x C-r' command re-reads this init file, thus 7597incorporating any changes that you might have made to it. 7598 7599* Menu: 7600 7601* Readline Init File Syntax:: Syntax for the commands in the inputrc file. 7602 7603* Conditional Init Constructs:: Conditional key bindings in the inputrc file. 7604 7605* Sample Init File:: An example inputrc file. 7606 7607 7608File: bash.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File 7609 76108.3.1 Readline Init File Syntax 7611------------------------------- 7612 7613There are only a few basic constructs allowed in the Readline init file. 7614Blank lines are ignored. Lines beginning with a '#' are comments. 7615Lines beginning with a '$' indicate conditional constructs (*note 7616Conditional Init Constructs::). Other lines denote variable settings 7617and key bindings. 7618 7619Variable Settings 7620 You can modify the run-time behavior of Readline by altering the 7621 values of variables in Readline using the 'set' command within the 7622 init file. The syntax is simple: 7623 7624 set VARIABLE VALUE 7625 7626 Here, for example, is how to change from the default Emacs-like key 7627 binding to use 'vi' line editing commands: 7628 7629 set editing-mode vi 7630 7631 Variable names and values, where appropriate, are recognized 7632 without regard to case. Unrecognized variable names are ignored. 7633 7634 Boolean variables (those that can be set to on or off) are set to 7635 on if the value is null or empty, ON (case-insensitive), or 1. Any 7636 other value results in the variable being set to off. 7637 7638 The 'bind -V' command lists the current Readline variable names and 7639 values. *Note Bash Builtins::. 7640 7641 A great deal of run-time behavior is changeable with the following 7642 variables. 7643 7644 'bell-style' 7645 Controls what happens when Readline wants to ring the terminal 7646 bell. If set to 'none', Readline never rings the bell. If 7647 set to 'visible', Readline uses a visible bell if one is 7648 available. If set to 'audible' (the default), Readline 7649 attempts to ring the terminal's bell. 7650 7651 'bind-tty-special-chars' 7652 If set to 'on' (the default), Readline attempts to bind the 7653 control characters treated specially by the kernel's terminal 7654 driver to their Readline equivalents. 7655 7656 'blink-matching-paren' 7657 If set to 'on', Readline attempts to briefly move the cursor 7658 to an opening parenthesis when a closing parenthesis is 7659 inserted. The default is 'off'. 7660 7661 'colored-completion-prefix' 7662 If set to 'on', when listing completions, Readline displays 7663 the common prefix of the set of possible completions using a 7664 different color. The color definitions are taken from the 7665 value of the 'LS_COLORS' environment variable. The default is 7666 'off'. 7667 7668 'colored-stats' 7669 If set to 'on', Readline displays possible completions using 7670 different colors to indicate their file type. The color 7671 definitions are taken from the value of the 'LS_COLORS' 7672 environment variable. The default is 'off'. 7673 7674 'comment-begin' 7675 The string to insert at the beginning of the line when the 7676 'insert-comment' command is executed. The default value is 7677 '"#"'. 7678 7679 'completion-display-width' 7680 The number of screen columns used to display possible matches 7681 when performing completion. The value is ignored if it is 7682 less than 0 or greater than the terminal screen width. A 7683 value of 0 will cause matches to be displayed one per line. 7684 The default value is -1. 7685 7686 'completion-ignore-case' 7687 If set to 'on', Readline performs filename matching and 7688 completion in a case-insensitive fashion. The default value 7689 is 'off'. 7690 7691 'completion-map-case' 7692 If set to 'on', and COMPLETION-IGNORE-CASE is enabled, 7693 Readline treats hyphens ('-') and underscores ('_') as 7694 equivalent when performing case-insensitive filename matching 7695 and completion. The default value is 'off'. 7696 7697 'completion-prefix-display-length' 7698 The length in characters of the common prefix of a list of 7699 possible completions that is displayed without modification. 7700 When set to a value greater than zero, common prefixes longer 7701 than this value are replaced with an ellipsis when displaying 7702 possible completions. 7703 7704 'completion-query-items' 7705 The number of possible completions that determines when the 7706 user is asked whether the list of possibilities should be 7707 displayed. If the number of possible completions is greater 7708 than or equal to this value, Readline will ask whether or not 7709 the user wishes to view them; otherwise, they are simply 7710 listed. This variable must be set to an integer value greater 7711 than or equal to 0. A negative value means Readline should 7712 never ask. The default limit is '100'. 7713 7714 'convert-meta' 7715 If set to 'on', Readline will convert characters with the 7716 eighth bit set to an ASCII key sequence by stripping the 7717 eighth bit and prefixing an <ESC> character, converting them 7718 to a meta-prefixed key sequence. The default value is 'on', 7719 but will be set to 'off' if the locale is one that contains 7720 eight-bit characters. 7721 7722 'disable-completion' 7723 If set to 'On', Readline will inhibit word completion. 7724 Completion characters will be inserted into the line as if 7725 they had been mapped to 'self-insert'. The default is 'off'. 7726 7727 'echo-control-characters' 7728 When set to 'on', on operating systems that indicate they 7729 support it, readline echoes a character corresponding to a 7730 signal generated from the keyboard. The default is 'on'. 7731 7732 'editing-mode' 7733 The 'editing-mode' variable controls which default set of key 7734 bindings is used. By default, Readline starts up in Emacs 7735 editing mode, where the keystrokes are most similar to Emacs. 7736 This variable can be set to either 'emacs' or 'vi'. 7737 7738 'emacs-mode-string' 7739 If the SHOW-MODE-IN-PROMPT variable is enabled, this string is 7740 displayed immediately before the last line of the primary 7741 prompt when emacs editing mode is active. The value is 7742 expanded like a key binding, so the standard set of meta- and 7743 control prefixes and backslash escape sequences is available. 7744 Use the '\1' and '\2' escapes to begin and end sequences of 7745 non-printing characters, which can be used to embed a terminal 7746 control sequence into the mode string. The default is '@'. 7747 7748 'enable-bracketed-paste' 7749 When set to 'On', Readline will configure the terminal in a 7750 way that will enable it to insert each paste into the editing 7751 buffer as a single string of characters, instead of treating 7752 each character as if it had been read from the keyboard. This 7753 can prevent pasted characters from being interpreted as 7754 editing commands. The default is 'On'. 7755 7756 'enable-keypad' 7757 When set to 'on', Readline will try to enable the application 7758 keypad when it is called. Some systems need this to enable 7759 the arrow keys. The default is 'off'. 7760 7761 'enable-meta-key' 7762 When set to 'on', Readline will try to enable any meta 7763 modifier key the terminal claims to support when it is called. 7764 On many terminals, the meta key is used to send eight-bit 7765 characters. The default is 'on'. 7766 7767 'expand-tilde' 7768 If set to 'on', tilde expansion is performed when Readline 7769 attempts word completion. The default is 'off'. 7770 7771 'history-preserve-point' 7772 If set to 'on', the history code attempts to place the point 7773 (the current cursor position) at the same location on each 7774 history line retrieved with 'previous-history' or 7775 'next-history'. The default is 'off'. 7776 7777 'history-size' 7778 Set the maximum number of history entries saved in the history 7779 list. If set to zero, any existing history entries are 7780 deleted and no new entries are saved. If set to a value less 7781 than zero, the number of history entries is not limited. By 7782 default, the number of history entries is not limited. If an 7783 attempt is made to set HISTORY-SIZE to a non-numeric value, 7784 the maximum number of history entries will be set to 500. 7785 7786 'horizontal-scroll-mode' 7787 This variable can be set to either 'on' or 'off'. Setting it 7788 to 'on' means that the text of the lines being edited will 7789 scroll horizontally on a single screen line when they are 7790 longer than the width of the screen, instead of wrapping onto 7791 a new screen line. This variable is automatically set to 'on' 7792 for terminals of height 1. By default, this variable is set 7793 to 'off'. 7794 7795 'input-meta' 7796 If set to 'on', Readline will enable eight-bit input (it will 7797 not clear the eighth bit in the characters it reads), 7798 regardless of what the terminal claims it can support. The 7799 default value is 'off', but Readline will set it to 'on' if 7800 the locale contains eight-bit characters. The name 7801 'meta-flag' is a synonym for this variable. 7802 7803 'isearch-terminators' 7804 The string of characters that should terminate an incremental 7805 search without subsequently executing the character as a 7806 command (*note Searching::). If this variable has not been 7807 given a value, the characters <ESC> and 'C-J' will terminate 7808 an incremental search. 7809 7810 'keymap' 7811 Sets Readline's idea of the current keymap for key binding 7812 commands. Built-in 'keymap' names are 'emacs', 7813 'emacs-standard', 'emacs-meta', 'emacs-ctlx', 'vi', 'vi-move', 7814 'vi-command', and 'vi-insert'. 'vi' is equivalent to 7815 'vi-command' ('vi-move' is also a synonym); 'emacs' is 7816 equivalent to 'emacs-standard'. Applications may add 7817 additional names. The default value is 'emacs'. The value of 7818 the 'editing-mode' variable also affects the default keymap. 7819 7820 'keyseq-timeout' 7821 Specifies the duration Readline will wait for a character when 7822 reading an ambiguous key sequence (one that can form a 7823 complete key sequence using the input read so far, or can take 7824 additional input to complete a longer key sequence). If no 7825 input is received within the timeout, Readline will use the 7826 shorter but complete key sequence. Readline uses this value 7827 to determine whether or not input is available on the current 7828 input source ('rl_instream' by default). The value is 7829 specified in milliseconds, so a value of 1000 means that 7830 Readline will wait one second for additional input. If this 7831 variable is set to a value less than or equal to zero, or to a 7832 non-numeric value, Readline will wait until another key is 7833 pressed to decide which key sequence to complete. The default 7834 value is '500'. 7835 7836 'mark-directories' 7837 If set to 'on', completed directory names have a slash 7838 appended. The default is 'on'. 7839 7840 'mark-modified-lines' 7841 This variable, when set to 'on', causes Readline to display an 7842 asterisk ('*') at the start of history lines which have been 7843 modified. This variable is 'off' by default. 7844 7845 'mark-symlinked-directories' 7846 If set to 'on', completed names which are symbolic links to 7847 directories have a slash appended (subject to the value of 7848 'mark-directories'). The default is 'off'. 7849 7850 'match-hidden-files' 7851 This variable, when set to 'on', causes Readline to match 7852 files whose names begin with a '.' (hidden files) when 7853 performing filename completion. If set to 'off', the leading 7854 '.' must be supplied by the user in the filename to be 7855 completed. This variable is 'on' by default. 7856 7857 'menu-complete-display-prefix' 7858 If set to 'on', menu completion displays the common prefix of 7859 the list of possible completions (which may be empty) before 7860 cycling through the list. The default is 'off'. 7861 7862 'output-meta' 7863 If set to 'on', Readline will display characters with the 7864 eighth bit set directly rather than as a meta-prefixed escape 7865 sequence. The default is 'off', but Readline will set it to 7866 'on' if the locale contains eight-bit characters. 7867 7868 'page-completions' 7869 If set to 'on', Readline uses an internal 'more'-like pager to 7870 display a screenful of possible completions at a time. This 7871 variable is 'on' by default. 7872 7873 'print-completions-horizontally' 7874 If set to 'on', Readline will display completions with matches 7875 sorted horizontally in alphabetical order, rather than down 7876 the screen. The default is 'off'. 7877 7878 'revert-all-at-newline' 7879 If set to 'on', Readline will undo all changes to history 7880 lines before returning when 'accept-line' is executed. By 7881 default, history lines may be modified and retain individual 7882 undo lists across calls to 'readline'. The default is 'off'. 7883 7884 'show-all-if-ambiguous' 7885 This alters the default behavior of the completion functions. 7886 If set to 'on', words which have more than one possible 7887 completion cause the matches to be listed immediately instead 7888 of ringing the bell. The default value is 'off'. 7889 7890 'show-all-if-unmodified' 7891 This alters the default behavior of the completion functions 7892 in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to 7893 'on', words which have more than one possible completion 7894 without any possible partial completion (the possible 7895 completions don't share a common prefix) cause the matches to 7896 be listed immediately instead of ringing the bell. The 7897 default value is 'off'. 7898 7899 'show-mode-in-prompt' 7900 If set to 'on', add a string to the beginning of the prompt 7901 indicating the editing mode: emacs, vi command, or vi 7902 insertion. The mode strings are user-settable (e.g., 7903 EMACS-MODE-STRING). The default value is 'off'. 7904 7905 'skip-completed-text' 7906 If set to 'on', this alters the default completion behavior 7907 when inserting a single match into the line. It's only active 7908 when performing completion in the middle of a word. If 7909 enabled, readline does not insert characters from the 7910 completion that match characters after point in the word being 7911 completed, so portions of the word following the cursor are 7912 not duplicated. For instance, if this is enabled, attempting 7913 completion when the cursor is after the 'e' in 'Makefile' will 7914 result in 'Makefile' rather than 'Makefilefile', assuming 7915 there is a single possible completion. The default value is 7916 'off'. 7917 7918 'vi-cmd-mode-string' 7919 If the SHOW-MODE-IN-PROMPT variable is enabled, this string is 7920 displayed immediately before the last line of the primary 7921 prompt when vi editing mode is active and in command mode. 7922 The value is expanded like a key binding, so the standard set 7923 of meta- and control prefixes and backslash escape sequences 7924 is available. Use the '\1' and '\2' escapes to begin and end 7925 sequences of non-printing characters, which can be used to 7926 embed a terminal control sequence into the mode string. The 7927 default is '(cmd)'. 7928 7929 'vi-ins-mode-string' 7930 If the SHOW-MODE-IN-PROMPT variable is enabled, this string is 7931 displayed immediately before the last line of the primary 7932 prompt when vi editing mode is active and in insertion mode. 7933 The value is expanded like a key binding, so the standard set 7934 of meta- and control prefixes and backslash escape sequences 7935 is available. Use the '\1' and '\2' escapes to begin and end 7936 sequences of non-printing characters, which can be used to 7937 embed a terminal control sequence into the mode string. The 7938 default is '(ins)'. 7939 7940 'visible-stats' 7941 If set to 'on', a character denoting a file's type is appended 7942 to the filename when listing possible completions. The 7943 default is 'off'. 7944 7945Key Bindings 7946 The syntax for controlling key bindings in the init file is simple. 7947 First you need to find the name of the command that you want to 7948 change. The following sections contain tables of the command name, 7949 the default keybinding, if any, and a short description of what the 7950 command does. 7951 7952 Once you know the name of the command, simply place on a line in 7953 the init file the name of the key you wish to bind the command to, 7954 a colon, and then the name of the command. There can be no space 7955 between the key name and the colon - that will be interpreted as 7956 part of the key name. The name of the key can be expressed in 7957 different ways, depending on what you find most comfortable. 7958 7959 In addition to command names, readline allows keys to be bound to a 7960 string that is inserted when the key is pressed (a MACRO). 7961 7962 The 'bind -p' command displays Readline function names and bindings 7963 in a format that can put directly into an initialization file. 7964 *Note Bash Builtins::. 7965 7966 KEYNAME: FUNCTION-NAME or MACRO 7967 KEYNAME is the name of a key spelled out in English. For 7968 example: 7969 Control-u: universal-argument 7970 Meta-Rubout: backward-kill-word 7971 Control-o: "> output" 7972 7973 In the example above, 'C-u' is bound to the function 7974 'universal-argument', 'M-DEL' is bound to the function 7975 'backward-kill-word', and 'C-o' is bound to run the macro 7976 expressed on the right hand side (that is, to insert the text 7977 '> output' into the line). 7978 7979 A number of symbolic character names are recognized while 7980 processing this key binding syntax: DEL, ESC, ESCAPE, LFD, 7981 NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB. 7982 7983 "KEYSEQ": FUNCTION-NAME or MACRO 7984 KEYSEQ differs from KEYNAME above in that strings denoting an 7985 entire key sequence can be specified, by placing the key 7986 sequence in double quotes. Some GNU Emacs style key escapes 7987 can be used, as in the following example, but the special 7988 character names are not recognized. 7989 7990 "\C-u": universal-argument 7991 "\C-x\C-r": re-read-init-file 7992 "\e[11~": "Function Key 1" 7993 7994 In the above example, 'C-u' is again bound to the function 7995 'universal-argument' (just as it was in the first example), 7996 ''C-x' 'C-r'' is bound to the function 're-read-init-file', 7997 and '<ESC> <[> <1> <1> <~>' is bound to insert the text 7998 'Function Key 1'. 7999 8000 The following GNU Emacs style escape sequences are available when 8001 specifying key sequences: 8002 8003 '\C-' 8004 control prefix 8005 '\M-' 8006 meta prefix 8007 '\e' 8008 an escape character 8009 '\\' 8010 backslash 8011 '\"' 8012 <">, a double quotation mark 8013 '\'' 8014 <'>, a single quote or apostrophe 8015 8016 In addition to the GNU Emacs style escape sequences, a second set 8017 of backslash escapes is available: 8018 8019 '\a' 8020 alert (bell) 8021 '\b' 8022 backspace 8023 '\d' 8024 delete 8025 '\f' 8026 form feed 8027 '\n' 8028 newline 8029 '\r' 8030 carriage return 8031 '\t' 8032 horizontal tab 8033 '\v' 8034 vertical tab 8035 '\NNN' 8036 the eight-bit character whose value is the octal value NNN 8037 (one to three digits) 8038 '\xHH' 8039 the eight-bit character whose value is the hexadecimal value 8040 HH (one or two hex digits) 8041 8042 When entering the text of a macro, single or double quotes must be 8043 used to indicate a macro definition. Unquoted text is assumed to 8044 be a function name. In the macro body, the backslash escapes 8045 described above are expanded. Backslash will quote any other 8046 character in the macro text, including '"' and '''. For example, 8047 the following binding will make ''C-x' \' insert a single '\' into 8048 the line: 8049 "\C-x\\": "\\" 8050 8051 8052File: bash.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File 8053 80548.3.2 Conditional Init Constructs 8055--------------------------------- 8056 8057Readline implements a facility similar in spirit to the conditional 8058compilation features of the C preprocessor which allows key bindings and 8059variable settings to be performed as the result of tests. There are 8060four parser directives used. 8061 8062'$if' 8063 The '$if' construct allows bindings to be made based on the editing 8064 mode, the terminal being used, or the application using Readline. 8065 The text of the test, after any comparison operator, extends to the 8066 end of the line; unless otherwise noted, no characters are required 8067 to isolate it. 8068 8069 'mode' 8070 The 'mode=' form of the '$if' directive is used to test 8071 whether Readline is in 'emacs' or 'vi' mode. This may be used 8072 in conjunction with the 'set keymap' command, for instance, to 8073 set bindings in the 'emacs-standard' and 'emacs-ctlx' keymaps 8074 only if Readline is starting out in 'emacs' mode. 8075 8076 'term' 8077 The 'term=' form may be used to include terminal-specific key 8078 bindings, perhaps to bind the key sequences output by the 8079 terminal's function keys. The word on the right side of the 8080 '=' is tested against both the full name of the terminal and 8081 the portion of the terminal name before the first '-'. This 8082 allows 'sun' to match both 'sun' and 'sun-cmd', for instance. 8083 8084 'version' 8085 The 'version' test may be used to perform comparisons against 8086 specific Readline versions. The 'version' expands to the 8087 current Readline version. The set of comparison operators 8088 includes '=' (and '=='), '!=', '<=', '>=', '<', and '>'. The 8089 version number supplied on the right side of the operator 8090 consists of a major version number, an optional decimal point, 8091 and an optional minor version (e.g., '7.1'). If the minor 8092 version is omitted, it is assumed to be '0'. The operator may 8093 be separated from the string 'version' and from the version 8094 number argument by whitespace. The following example sets a 8095 variable if the Readline version being used is 7.0 or newer: 8096 $if version >= 7.0 8097 set show-mode-in-prompt on 8098 $endif 8099 8100 'application' 8101 The APPLICATION construct is used to include 8102 application-specific settings. Each program using the 8103 Readline library sets the APPLICATION NAME, and you can test 8104 for a particular value. This could be used to bind key 8105 sequences to functions useful for a specific program. For 8106 instance, the following command adds a key sequence that 8107 quotes the current or previous word in Bash: 8108 $if Bash 8109 # Quote the current or previous word 8110 "\C-xq": "\eb\"\ef\"" 8111 $endif 8112 8113 'variable' 8114 The VARIABLE construct provides simple equality tests for 8115 Readline variables and values. The permitted comparison 8116 operators are '=', '==', and '!='. The variable name must be 8117 separated from the comparison operator by whitespace; the 8118 operator may be separated from the value on the right hand 8119 side by whitespace. Both string and boolean variables may be 8120 tested. Boolean variables must be tested against the values 8121 ON and OFF. The following example is equivalent to the 8122 'mode=emacs' test described above: 8123 $if editing-mode == emacs 8124 set show-mode-in-prompt on 8125 $endif 8126 8127'$endif' 8128 This command, as seen in the previous example, terminates an '$if' 8129 command. 8130 8131'$else' 8132 Commands in this branch of the '$if' directive are executed if the 8133 test fails. 8134 8135'$include' 8136 This directive takes a single filename as an argument and reads 8137 commands and bindings from that file. For example, the following 8138 directive reads from '/usr/local/etc/inputrc': 8139 $include /usr/local/etc/inputrc 8140 8141 8142File: bash.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File 8143 81448.3.3 Sample Init File 8145---------------------- 8146 8147Here is an example of an INPUTRC file. This illustrates key binding, 8148variable assignment, and conditional syntax. 8149 8150 # This file controls the behaviour of line input editing for 8151 # programs that use the GNU Readline library. Existing 8152 # programs include FTP, Bash, and GDB. 8153 # 8154 # You can re-read the inputrc file with C-x C-r. 8155 # Lines beginning with '#' are comments. 8156 # 8157 # First, include any system-wide bindings and variable 8158 # assignments from /usr/local/etc/inputrc 8159 $include /usr/local/etc/inputrc 8160 8161 # 8162 # Set various bindings for emacs mode. 8163 8164 set editing-mode emacs 8165 8166 $if mode=emacs 8167 8168 Meta-Control-h: backward-kill-word Text after the function name is ignored 8169 8170 # 8171 # Arrow keys in keypad mode 8172 # 8173 #"\M-OD": backward-char 8174 #"\M-OC": forward-char 8175 #"\M-OA": previous-history 8176 #"\M-OB": next-history 8177 # 8178 # Arrow keys in ANSI mode 8179 # 8180 "\M-[D": backward-char 8181 "\M-[C": forward-char 8182 "\M-[A": previous-history 8183 "\M-[B": next-history 8184 # 8185 # Arrow keys in 8 bit keypad mode 8186 # 8187 #"\M-\C-OD": backward-char 8188 #"\M-\C-OC": forward-char 8189 #"\M-\C-OA": previous-history 8190 #"\M-\C-OB": next-history 8191 # 8192 # Arrow keys in 8 bit ANSI mode 8193 # 8194 #"\M-\C-[D": backward-char 8195 #"\M-\C-[C": forward-char 8196 #"\M-\C-[A": previous-history 8197 #"\M-\C-[B": next-history 8198 8199 C-q: quoted-insert 8200 8201 $endif 8202 8203 # An old-style binding. This happens to be the default. 8204 TAB: complete 8205 8206 # Macros that are convenient for shell interaction 8207 $if Bash 8208 # edit the path 8209 "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" 8210 # prepare to type a quoted word -- 8211 # insert open and close double quotes 8212 # and move to just after the open quote 8213 "\C-x\"": "\"\"\C-b" 8214 # insert a backslash (testing backslash escapes 8215 # in sequences and macros) 8216 "\C-x\\": "\\" 8217 # Quote the current or previous word 8218 "\C-xq": "\eb\"\ef\"" 8219 # Add a binding to refresh the line, which is unbound 8220 "\C-xr": redraw-current-line 8221 # Edit variable on current line. 8222 "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" 8223 $endif 8224 8225 # use a visible bell if one is available 8226 set bell-style visible 8227 8228 # don't strip characters to 7 bits when reading 8229 set input-meta on 8230 8231 # allow iso-latin1 characters to be inserted rather 8232 # than converted to prefix-meta sequences 8233 set convert-meta off 8234 8235 # display characters with the eighth bit set directly 8236 # rather than as meta-prefixed characters 8237 set output-meta on 8238 8239 # if there are 150 or more possible completions for a word, 8240 # ask whether or not the user wants to see all of them 8241 set completion-query-items 150 8242 8243 # For FTP 8244 $if Ftp 8245 "\C-xg": "get \M-?" 8246 "\C-xt": "put \M-?" 8247 "\M-.": yank-last-arg 8248 $endif 8249 8250 8251File: bash.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing 8252 82538.4 Bindable Readline Commands 8254============================== 8255 8256* Menu: 8257 8258* Commands For Moving:: Moving about the line. 8259* Commands For History:: Getting at previous lines. 8260* Commands For Text:: Commands for changing text. 8261* Commands For Killing:: Commands for killing and yanking. 8262* Numeric Arguments:: Specifying numeric arguments, repeat counts. 8263* Commands For Completion:: Getting Readline to do the typing for you. 8264* Keyboard Macros:: Saving and re-executing typed characters 8265* Miscellaneous Commands:: Other miscellaneous commands. 8266 8267This section describes Readline commands that may be bound to key 8268sequences. You can list your key bindings by executing 'bind -P' or, 8269for a more terse format, suitable for an INPUTRC file, 'bind -p'. 8270(*Note Bash Builtins::.) Command names without an accompanying key 8271sequence are unbound by default. 8272 8273 In the following descriptions, "point" refers to the current cursor 8274position, and "mark" refers to a cursor position saved by the 'set-mark' 8275command. The text between the point and mark is referred to as the 8276"region". 8277 8278 8279File: bash.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands 8280 82818.4.1 Commands For Moving 8282------------------------- 8283 8284'beginning-of-line (C-a)' 8285 Move to the start of the current line. 8286 8287'end-of-line (C-e)' 8288 Move to the end of the line. 8289 8290'forward-char (C-f)' 8291 Move forward a character. 8292 8293'backward-char (C-b)' 8294 Move back a character. 8295 8296'forward-word (M-f)' 8297 Move forward to the end of the next word. Words are composed of 8298 letters and digits. 8299 8300'backward-word (M-b)' 8301 Move back to the start of the current or previous word. Words are 8302 composed of letters and digits. 8303 8304'shell-forward-word (M-C-f)' 8305 Move forward to the end of the next word. Words are delimited by 8306 non-quoted shell metacharacters. 8307 8308'shell-backward-word (M-C-b)' 8309 Move back to the start of the current or previous word. Words are 8310 delimited by non-quoted shell metacharacters. 8311 8312'previous-screen-line ()' 8313 Attempt to move point to the same physical screen column on the 8314 previous physical screen line. This will not have the desired 8315 effect if the current Readline line does not take up more than one 8316 physical line or if point is not greater than the length of the 8317 prompt plus the screen width. 8318 8319'next-screen-line ()' 8320 Attempt to move point to the same physical screen column on the 8321 next physical screen line. This will not have the desired effect 8322 if the current Readline line does not take up more than one 8323 physical line or if the length of the current Readline line is not 8324 greater than the length of the prompt plus the screen width. 8325 8326'clear-display (M-C-l)' 8327 Clear the screen and, if possible, the terminal's scrollback 8328 buffer, then redraw the current line, leaving the current line at 8329 the top of the screen. 8330 8331'clear-screen (C-l)' 8332 Clear the screen, then redraw the current line, leaving the current 8333 line at the top of the screen. 8334 8335'redraw-current-line ()' 8336 Refresh the current line. By default, this is unbound. 8337 8338 8339File: bash.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands 8340 83418.4.2 Commands For Manipulating The History 8342------------------------------------------- 8343 8344'accept-line (Newline or Return)' 8345 Accept the line regardless of where the cursor is. If this line is 8346 non-empty, add it to the history list according to the setting of 8347 the 'HISTCONTROL' and 'HISTIGNORE' variables. If this line is a 8348 modified history line, then restore the history line to its 8349 original state. 8350 8351'previous-history (C-p)' 8352 Move 'back' through the history list, fetching the previous 8353 command. 8354 8355'next-history (C-n)' 8356 Move 'forward' through the history list, fetching the next command. 8357 8358'beginning-of-history (M-<)' 8359 Move to the first line in the history. 8360 8361'end-of-history (M->)' 8362 Move to the end of the input history, i.e., the line currently 8363 being entered. 8364 8365'reverse-search-history (C-r)' 8366 Search backward starting at the current line and moving 'up' 8367 through the history as necessary. This is an incremental search. 8368 This command sets the region to the matched text and activates the 8369 mark. 8370 8371'forward-search-history (C-s)' 8372 Search forward starting at the current line and moving 'down' 8373 through the history as necessary. This is an incremental search. 8374 This command sets the region to the matched text and activates the 8375 mark. 8376 8377'non-incremental-reverse-search-history (M-p)' 8378 Search backward starting at the current line and moving 'up' 8379 through the history as necessary using a non-incremental search for 8380 a string supplied by the user. The search string may match 8381 anywhere in a history line. 8382 8383'non-incremental-forward-search-history (M-n)' 8384 Search forward starting at the current line and moving 'down' 8385 through the history as necessary using a non-incremental search for 8386 a string supplied by the user. The search string may match 8387 anywhere in a history line. 8388 8389'history-search-forward ()' 8390 Search forward through the history for the string of characters 8391 between the start of the current line and the point. The search 8392 string must match at the beginning of a history line. This is a 8393 non-incremental search. By default, this command is unbound. 8394 8395'history-search-backward ()' 8396 Search backward through the history for the string of characters 8397 between the start of the current line and the point. The search 8398 string must match at the beginning of a history line. This is a 8399 non-incremental search. By default, this command is unbound. 8400 8401'history-substring-search-forward ()' 8402 Search forward through the history for the string of characters 8403 between the start of the current line and the point. The search 8404 string may match anywhere in a history line. This is a 8405 non-incremental search. By default, this command is unbound. 8406 8407'history-substring-search-backward ()' 8408 Search backward through the history for the string of characters 8409 between the start of the current line and the point. The search 8410 string may match anywhere in a history line. This is a 8411 non-incremental search. By default, this command is unbound. 8412 8413'yank-nth-arg (M-C-y)' 8414 Insert the first argument to the previous command (usually the 8415 second word on the previous line) at point. With an argument N, 8416 insert the Nth word from the previous command (the words in the 8417 previous command begin with word 0). A negative argument inserts 8418 the Nth word from the end of the previous command. Once the 8419 argument N is computed, the argument is extracted as if the '!N' 8420 history expansion had been specified. 8421 8422'yank-last-arg (M-. or M-_)' 8423 Insert last argument to the previous command (the last word of the 8424 previous history entry). With a numeric argument, behave exactly 8425 like 'yank-nth-arg'. Successive calls to 'yank-last-arg' move back 8426 through the history list, inserting the last word (or the word 8427 specified by the argument to the first call) of each line in turn. 8428 Any numeric argument supplied to these successive calls determines 8429 the direction to move through the history. A negative argument 8430 switches the direction through the history (back or forward). The 8431 history expansion facilities are used to extract the last argument, 8432 as if the '!$' history expansion had been specified. 8433 8434'operate-and-get-next (C-o)' 8435 Accept the current line for return to the calling application as if 8436 a newline had been entered, and fetch the next line relative to the 8437 current line from the history for editing. A numeric argument, if 8438 supplied, specifies the history entry to use instead of the current 8439 line. 8440 8441 8442File: bash.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands 8443 84448.4.3 Commands For Changing Text 8445-------------------------------- 8446 8447'end-of-file (usually C-d)' 8448 The character indicating end-of-file as set, for example, by 8449 'stty'. If this character is read when there are no characters on 8450 the line, and point is at the beginning of the line, Readline 8451 interprets it as the end of input and returns EOF. 8452 8453'delete-char (C-d)' 8454 Delete the character at point. If this function is bound to the 8455 same character as the tty EOF character, as 'C-d' commonly is, see 8456 above for the effects. 8457 8458'backward-delete-char (Rubout)' 8459 Delete the character behind the cursor. A numeric argument means 8460 to kill the characters instead of deleting them. 8461 8462'forward-backward-delete-char ()' 8463 Delete the character under the cursor, unless the cursor is at the 8464 end of the line, in which case the character behind the cursor is 8465 deleted. By default, this is not bound to a key. 8466 8467'quoted-insert (C-q or C-v)' 8468 Add the next character typed to the line verbatim. This is how to 8469 insert key sequences like 'C-q', for example. 8470 8471'self-insert (a, b, A, 1, !, ...)' 8472 Insert yourself. 8473 8474'bracketed-paste-begin ()' 8475 This function is intended to be bound to the "bracketed paste" 8476 escape sequence sent by some terminals, and such a binding is 8477 assigned by default. It allows Readline to insert the pasted text 8478 as a single unit without treating each character as if it had been 8479 read from the keyboard. The characters are inserted as if each one 8480 was bound to 'self-insert' instead of executing any editing 8481 commands. 8482 8483 Bracketed paste sets the region (the characters between point and 8484 the mark) to the inserted text. It uses the concept of an _active 8485 mark_: when the mark is active, Readline redisplay uses the 8486 terminal's standout mode to denote the region. 8487 8488'transpose-chars (C-t)' 8489 Drag the character before the cursor forward over the character at 8490 the cursor, moving the cursor forward as well. If the insertion 8491 point is at the end of the line, then this transposes the last two 8492 characters of the line. Negative arguments have no effect. 8493 8494'transpose-words (M-t)' 8495 Drag the word before point past the word after point, moving point 8496 past that word as well. If the insertion point is at the end of 8497 the line, this transposes the last two words on the line. 8498 8499'upcase-word (M-u)' 8500 Uppercase the current (or following) word. With a negative 8501 argument, uppercase the previous word, but do not move the cursor. 8502 8503'downcase-word (M-l)' 8504 Lowercase the current (or following) word. With a negative 8505 argument, lowercase the previous word, but do not move the cursor. 8506 8507'capitalize-word (M-c)' 8508 Capitalize the current (or following) word. With a negative 8509 argument, capitalize the previous word, but do not move the cursor. 8510 8511'overwrite-mode ()' 8512 Toggle overwrite mode. With an explicit positive numeric argument, 8513 switches to overwrite mode. With an explicit non-positive numeric 8514 argument, switches to insert mode. This command affects only 8515 'emacs' mode; 'vi' mode does overwrite differently. Each call to 8516 'readline()' starts in insert mode. 8517 8518 In overwrite mode, characters bound to 'self-insert' replace the 8519 text at point rather than pushing the text to the right. 8520 Characters bound to 'backward-delete-char' replace the character 8521 before point with a space. 8522 8523 By default, this command is unbound. 8524 8525 8526File: bash.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands 8527 85288.4.4 Killing And Yanking 8529------------------------- 8530 8531'kill-line (C-k)' 8532 Kill the text from point to the end of the line. With a negative 8533 numeric argument, kill backward from the cursor to the beginning of 8534 the current line. 8535 8536'backward-kill-line (C-x Rubout)' 8537 Kill backward from the cursor to the beginning of the current line. 8538 With a negative numeric argument, kill forward from the cursor to 8539 the end of the current line. 8540 8541'unix-line-discard (C-u)' 8542 Kill backward from the cursor to the beginning of the current line. 8543 8544'kill-whole-line ()' 8545 Kill all characters on the current line, no matter where point is. 8546 By default, this is unbound. 8547 8548'kill-word (M-d)' 8549 Kill from point to the end of the current word, or if between 8550 words, to the end of the next word. Word boundaries are the same 8551 as 'forward-word'. 8552 8553'backward-kill-word (M-<DEL>)' 8554 Kill the word behind point. Word boundaries are the same as 8555 'backward-word'. 8556 8557'shell-kill-word (M-C-d)' 8558 Kill from point to the end of the current word, or if between 8559 words, to the end of the next word. Word boundaries are the same 8560 as 'shell-forward-word'. 8561 8562'shell-backward-kill-word ()' 8563 Kill the word behind point. Word boundaries are the same as 8564 'shell-backward-word'. 8565 8566'shell-transpose-words (M-C-t)' 8567 Drag the word before point past the word after point, moving point 8568 past that word as well. If the insertion point is at the end of 8569 the line, this transposes the last two words on the line. Word 8570 boundaries are the same as 'shell-forward-word' and 8571 'shell-backward-word'. 8572 8573'unix-word-rubout (C-w)' 8574 Kill the word behind point, using white space as a word boundary. 8575 The killed text is saved on the kill-ring. 8576 8577'unix-filename-rubout ()' 8578 Kill the word behind point, using white space and the slash 8579 character as the word boundaries. The killed text is saved on the 8580 kill-ring. 8581 8582'delete-horizontal-space ()' 8583 Delete all spaces and tabs around point. By default, this is 8584 unbound. 8585 8586'kill-region ()' 8587 Kill the text in the current region. By default, this command is 8588 unbound. 8589 8590'copy-region-as-kill ()' 8591 Copy the text in the region to the kill buffer, so it can be yanked 8592 right away. By default, this command is unbound. 8593 8594'copy-backward-word ()' 8595 Copy the word before point to the kill buffer. The word boundaries 8596 are the same as 'backward-word'. By default, this command is 8597 unbound. 8598 8599'copy-forward-word ()' 8600 Copy the word following point to the kill buffer. The word 8601 boundaries are the same as 'forward-word'. By default, this 8602 command is unbound. 8603 8604'yank (C-y)' 8605 Yank the top of the kill ring into the buffer at point. 8606 8607'yank-pop (M-y)' 8608 Rotate the kill-ring, and yank the new top. You can only do this 8609 if the prior command is 'yank' or 'yank-pop'. 8610 8611 8612File: bash.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands 8613 86148.4.5 Specifying Numeric Arguments 8615---------------------------------- 8616 8617'digit-argument (M-0, M-1, ... M--)' 8618 Add this digit to the argument already accumulating, or start a new 8619 argument. 'M--' starts a negative argument. 8620 8621'universal-argument ()' 8622 This is another way to specify an argument. If this command is 8623 followed by one or more digits, optionally with a leading minus 8624 sign, those digits define the argument. If the command is followed 8625 by digits, executing 'universal-argument' again ends the numeric 8626 argument, but is otherwise ignored. As a special case, if this 8627 command is immediately followed by a character that is neither a 8628 digit nor minus sign, the argument count for the next command is 8629 multiplied by four. The argument count is initially one, so 8630 executing this function the first time makes the argument count 8631 four, a second time makes the argument count sixteen, and so on. 8632 By default, this is not bound to a key. 8633 8634 8635File: bash.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands 8636 86378.4.6 Letting Readline Type For You 8638----------------------------------- 8639 8640'complete (<TAB>)' 8641 Attempt to perform completion on the text before point. The actual 8642 completion performed is application-specific. Bash attempts 8643 completion treating the text as a variable (if the text begins with 8644 '$'), username (if the text begins with '~'), hostname (if the text 8645 begins with '@'), or command (including aliases and functions) in 8646 turn. If none of these produces a match, filename completion is 8647 attempted. 8648 8649'possible-completions (M-?)' 8650 List the possible completions of the text before point. When 8651 displaying completions, Readline sets the number of columns used 8652 for display to the value of 'completion-display-width', the value 8653 of the environment variable 'COLUMNS', or the screen width, in that 8654 order. 8655 8656'insert-completions (M-*)' 8657 Insert all completions of the text before point that would have 8658 been generated by 'possible-completions'. 8659 8660'menu-complete ()' 8661 Similar to 'complete', but replaces the word to be completed with a 8662 single match from the list of possible completions. Repeated 8663 execution of 'menu-complete' steps through the list of possible 8664 completions, inserting each match in turn. At the end of the list 8665 of completions, the bell is rung (subject to the setting of 8666 'bell-style') and the original text is restored. An argument of N 8667 moves N positions forward in the list of matches; a negative 8668 argument may be used to move backward through the list. This 8669 command is intended to be bound to <TAB>, but is unbound by 8670 default. 8671 8672'menu-complete-backward ()' 8673 Identical to 'menu-complete', but moves backward through the list 8674 of possible completions, as if 'menu-complete' had been given a 8675 negative argument. 8676 8677'delete-char-or-list ()' 8678 Deletes the character under the cursor if not at the beginning or 8679 end of the line (like 'delete-char'). If at the end of the line, 8680 behaves identically to 'possible-completions'. This command is 8681 unbound by default. 8682 8683'complete-filename (M-/)' 8684 Attempt filename completion on the text before point. 8685 8686'possible-filename-completions (C-x /)' 8687 List the possible completions of the text before point, treating it 8688 as a filename. 8689 8690'complete-username (M-~)' 8691 Attempt completion on the text before point, treating it as a 8692 username. 8693 8694'possible-username-completions (C-x ~)' 8695 List the possible completions of the text before point, treating it 8696 as a username. 8697 8698'complete-variable (M-$)' 8699 Attempt completion on the text before point, treating it as a shell 8700 variable. 8701 8702'possible-variable-completions (C-x $)' 8703 List the possible completions of the text before point, treating it 8704 as a shell variable. 8705 8706'complete-hostname (M-@)' 8707 Attempt completion on the text before point, treating it as a 8708 hostname. 8709 8710'possible-hostname-completions (C-x @)' 8711 List the possible completions of the text before point, treating it 8712 as a hostname. 8713 8714'complete-command (M-!)' 8715 Attempt completion on the text before point, treating it as a 8716 command name. Command completion attempts to match the text 8717 against aliases, reserved words, shell functions, shell builtins, 8718 and finally executable filenames, in that order. 8719 8720'possible-command-completions (C-x !)' 8721 List the possible completions of the text before point, treating it 8722 as a command name. 8723 8724'dynamic-complete-history (M-<TAB>)' 8725 Attempt completion on the text before point, comparing the text 8726 against lines from the history list for possible completion 8727 matches. 8728 8729'dabbrev-expand ()' 8730 Attempt menu completion on the text before point, comparing the 8731 text against lines from the history list for possible completion 8732 matches. 8733 8734'complete-into-braces (M-{)' 8735 Perform filename completion and insert the list of possible 8736 completions enclosed within braces so the list is available to the 8737 shell (*note Brace Expansion::). 8738 8739 8740File: bash.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands 8741 87428.4.7 Keyboard Macros 8743--------------------- 8744 8745'start-kbd-macro (C-x ()' 8746 Begin saving the characters typed into the current keyboard macro. 8747 8748'end-kbd-macro (C-x ))' 8749 Stop saving the characters typed into the current keyboard macro 8750 and save the definition. 8751 8752'call-last-kbd-macro (C-x e)' 8753 Re-execute the last keyboard macro defined, by making the 8754 characters in the macro appear as if typed at the keyboard. 8755 8756'print-last-kbd-macro ()' 8757 Print the last keboard macro defined in a format suitable for the 8758 INPUTRC file. 8759 8760 8761File: bash.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands 8762 87638.4.8 Some Miscellaneous Commands 8764--------------------------------- 8765 8766're-read-init-file (C-x C-r)' 8767 Read in the contents of the INPUTRC file, and incorporate any 8768 bindings or variable assignments found there. 8769 8770'abort (C-g)' 8771 Abort the current editing command and ring the terminal's bell 8772 (subject to the setting of 'bell-style'). 8773 8774'do-lowercase-version (M-A, M-B, M-X, ...)' 8775 If the metafied character X is upper case, run the command that is 8776 bound to the corresponding metafied lower case character. The 8777 behavior is undefined if X is already lower case. 8778 8779'prefix-meta (<ESC>)' 8780 Metafy the next character typed. This is for keyboards without a 8781 meta key. Typing '<ESC> f' is equivalent to typing 'M-f'. 8782 8783'undo (C-_ or C-x C-u)' 8784 Incremental undo, separately remembered for each line. 8785 8786'revert-line (M-r)' 8787 Undo all changes made to this line. This is like executing the 8788 'undo' command enough times to get back to the beginning. 8789 8790'tilde-expand (M-&)' 8791 Perform tilde expansion on the current word. 8792 8793'set-mark (C-@)' 8794 Set the mark to the point. If a numeric argument is supplied, the 8795 mark is set to that position. 8796 8797'exchange-point-and-mark (C-x C-x)' 8798 Swap the point with the mark. The current cursor position is set 8799 to the saved position, and the old cursor position is saved as the 8800 mark. 8801 8802'character-search (C-])' 8803 A character is read and point is moved to the next occurrence of 8804 that character. A negative count searches for previous 8805 occurrences. 8806 8807'character-search-backward (M-C-])' 8808 A character is read and point is moved to the previous occurrence 8809 of that character. A negative count searches for subsequent 8810 occurrences. 8811 8812'skip-csi-sequence ()' 8813 Read enough characters to consume a multi-key sequence such as 8814 those defined for keys like Home and End. Such sequences begin 8815 with a Control Sequence Indicator (CSI), usually ESC-[. If this 8816 sequence is bound to "\e[", keys producing such sequences will have 8817 no effect unless explicitly bound to a readline command, instead of 8818 inserting stray characters into the editing buffer. This is 8819 unbound by default, but usually bound to ESC-[. 8820 8821'insert-comment (M-#)' 8822 Without a numeric argument, the value of the 'comment-begin' 8823 variable is inserted at the beginning of the current line. If a 8824 numeric argument is supplied, this command acts as a toggle: if the 8825 characters at the beginning of the line do not match the value of 8826 'comment-begin', the value is inserted, otherwise the characters in 8827 'comment-begin' are deleted from the beginning of the line. In 8828 either case, the line is accepted as if a newline had been typed. 8829 The default value of 'comment-begin' causes this command to make 8830 the current line a shell comment. If a numeric argument causes the 8831 comment character to be removed, the line will be executed by the 8832 shell. 8833 8834'dump-functions ()' 8835 Print all of the functions and their key bindings to the Readline 8836 output stream. If a numeric argument is supplied, the output is 8837 formatted in such a way that it can be made part of an INPUTRC 8838 file. This command is unbound by default. 8839 8840'dump-variables ()' 8841 Print all of the settable variables and their values to the 8842 Readline output stream. If a numeric argument is supplied, the 8843 output is formatted in such a way that it can be made part of an 8844 INPUTRC file. This command is unbound by default. 8845 8846'dump-macros ()' 8847 Print all of the Readline key sequences bound to macros and the 8848 strings they output. If a numeric argument is supplied, the output 8849 is formatted in such a way that it can be made part of an INPUTRC 8850 file. This command is unbound by default. 8851 8852'glob-complete-word (M-g)' 8853 The word before point is treated as a pattern for pathname 8854 expansion, with an asterisk implicitly appended. This pattern is 8855 used to generate a list of matching file names for possible 8856 completions. 8857 8858'glob-expand-word (C-x *)' 8859 The word before point is treated as a pattern for pathname 8860 expansion, and the list of matching file names is inserted, 8861 replacing the word. If a numeric argument is supplied, a '*' is 8862 appended before pathname expansion. 8863 8864'glob-list-expansions (C-x g)' 8865 The list of expansions that would have been generated by 8866 'glob-expand-word' is displayed, and the line is redrawn. If a 8867 numeric argument is supplied, a '*' is appended before pathname 8868 expansion. 8869 8870'display-shell-version (C-x C-v)' 8871 Display version information about the current instance of Bash. 8872 8873'shell-expand-line (M-C-e)' 8874 Expand the line as the shell does. This performs alias and history 8875 expansion as well as all of the shell word expansions (*note Shell 8876 Expansions::). 8877 8878'history-expand-line (M-^)' 8879 Perform history expansion on the current line. 8880 8881'magic-space ()' 8882 Perform history expansion on the current line and insert a space 8883 (*note History Interaction::). 8884 8885'alias-expand-line ()' 8886 Perform alias expansion on the current line (*note Aliases::). 8887 8888'history-and-alias-expand-line ()' 8889 Perform history and alias expansion on the current line. 8890 8891'insert-last-argument (M-. or M-_)' 8892 A synonym for 'yank-last-arg'. 8893 8894'edit-and-execute-command (C-x C-e)' 8895 Invoke an editor on the current command line, and execute the 8896 result as shell commands. Bash attempts to invoke '$VISUAL', 8897 '$EDITOR', and 'emacs' as the editor, in that order. 8898 8899 8900File: bash.info, Node: Readline vi Mode, Next: Programmable Completion, Prev: Bindable Readline Commands, Up: Command Line Editing 8901 89028.5 Readline vi Mode 8903==================== 8904 8905While the Readline library does not have a full set of 'vi' editing 8906functions, it does contain enough to allow simple editing of the line. 8907The Readline 'vi' mode behaves as specified in the POSIX standard. 8908 8909 In order to switch interactively between 'emacs' and 'vi' editing 8910modes, use the 'set -o emacs' and 'set -o vi' commands (*note The Set 8911Builtin::). The Readline default is 'emacs' mode. 8912 8913 When you enter a line in 'vi' mode, you are already placed in 8914'insertion' mode, as if you had typed an 'i'. Pressing <ESC> switches 8915you into 'command' mode, where you can edit the text of the line with 8916the standard 'vi' movement keys, move to previous history lines with 'k' 8917and subsequent lines with 'j', and so forth. 8918 8919 8920File: bash.info, Node: Programmable Completion, Next: Programmable Completion Builtins, Prev: Readline vi Mode, Up: Command Line Editing 8921 89228.6 Programmable Completion 8923=========================== 8924 8925When word completion is attempted for an argument to a command for which 8926a completion specification (a COMPSPEC) has been defined using the 8927'complete' builtin (*note Programmable Completion Builtins::), the 8928programmable completion facilities are invoked. 8929 8930 First, the command name is identified. If a compspec has been 8931defined for that command, the compspec is used to generate the list of 8932possible completions for the word. If the command word is the empty 8933string (completion attempted at the beginning of an empty line), any 8934compspec defined with the '-E' option to 'complete' is used. If the 8935command word is a full pathname, a compspec for the full pathname is 8936searched for first. If no compspec is found for the full pathname, an 8937attempt is made to find a compspec for the portion following the final 8938slash. If those searches do not result in a compspec, any compspec 8939defined with the '-D' option to 'complete' is used as the default. If 8940there is no default compspec, Bash attempts alias expansion on the 8941command word as a final resort, and attempts to find a compspec for the 8942command word from any successful expansion 8943 8944 Once a compspec has been found, it is used to generate the list of 8945matching words. If a compspec is not found, the default Bash completion 8946described above (*note Commands For Completion::) is performed. 8947 8948 First, the actions specified by the compspec are used. Only matches 8949which are prefixed by the word being completed are returned. When the 8950'-f' or '-d' option is used for filename or directory name completion, 8951the shell variable 'FIGNORE' is used to filter the matches. *Note Bash 8952Variables::, for a description of 'FIGNORE'. 8953 8954 Any completions specified by a filename expansion pattern to the '-G' 8955option are generated next. The words generated by the pattern need not 8956match the word being completed. The 'GLOBIGNORE' shell variable is not 8957used to filter the matches, but the 'FIGNORE' shell variable is used. 8958 8959 Next, the string specified as the argument to the '-W' option is 8960considered. The string is first split using the characters in the 'IFS' 8961special variable as delimiters. Shell quoting is honored within the 8962string, in order to provide a mechanism for the words to contain shell 8963metacharacters or characters in the value of 'IFS'. Each word is then 8964expanded using brace expansion, tilde expansion, parameter and variable 8965expansion, command substitution, and arithmetic expansion, as described 8966above (*note Shell Expansions::). The results are split using the rules 8967described above (*note Word Splitting::). The results of the expansion 8968are prefix-matched against the word being completed, and the matching 8969words become the possible completions. 8970 8971 After these matches have been generated, any shell function or 8972command specified with the '-F' and '-C' options is invoked. When the 8973command or function is invoked, the 'COMP_LINE', 'COMP_POINT', 8974'COMP_KEY', and 'COMP_TYPE' variables are assigned values as described 8975above (*note Bash Variables::). If a shell function is being invoked, 8976the 'COMP_WORDS' and 'COMP_CWORD' variables are also set. When the 8977function or command is invoked, the first argument ($1) is the name of 8978the command whose arguments are being completed, the second argument 8979($2) is the word being completed, and the third argument ($3) is the 8980word preceding the word being completed on the current command line. No 8981filtering of the generated completions against the word being completed 8982is performed; the function or command has complete freedom in generating 8983the matches. 8984 8985 Any function specified with '-F' is invoked first. The function may 8986use any of the shell facilities, including the 'compgen' and 'compopt' 8987builtins described below (*note Programmable Completion Builtins::), to 8988generate the matches. It must put the possible completions in the 8989'COMPREPLY' array variable, one per array element. 8990 8991 Next, any command specified with the '-C' option is invoked in an 8992environment equivalent to command substitution. It should print a list 8993of completions, one per line, to the standard output. Backslash may be 8994used to escape a newline, if necessary. 8995 8996 After all of the possible completions are generated, any filter 8997specified with the '-X' option is applied to the list. The filter is a 8998pattern as used for pathname expansion; a '&' in the pattern is replaced 8999with the text of the word being completed. A literal '&' may be escaped 9000with a backslash; the backslash is removed before attempting a match. 9001Any completion that matches the pattern will be removed from the list. 9002A leading '!' negates the pattern; in this case any completion not 9003matching the pattern will be removed. If the 'nocasematch' shell option 9004(see the description of 'shopt' in *note The Shopt Builtin::) is 9005enabled, the match is performed without regard to the case of alphabetic 9006characters. 9007 9008 Finally, any prefix and suffix specified with the '-P' and '-S' 9009options are added to each member of the completion list, and the result 9010is returned to the Readline completion code as the list of possible 9011completions. 9012 9013 If the previously-applied actions do not generate any matches, and 9014the '-o dirnames' option was supplied to 'complete' when the compspec 9015was defined, directory name completion is attempted. 9016 9017 If the '-o plusdirs' option was supplied to 'complete' when the 9018compspec was defined, directory name completion is attempted and any 9019matches are added to the results of the other actions. 9020 9021 By default, if a compspec is found, whatever it generates is returned 9022to the completion code as the full set of possible completions. The 9023default Bash completions are not attempted, and the Readline default of 9024filename completion is disabled. If the '-o bashdefault' option was 9025supplied to 'complete' when the compspec was defined, the default Bash 9026completions are attempted if the compspec generates no matches. If the 9027'-o default' option was supplied to 'complete' when the compspec was 9028defined, Readline's default completion will be performed if the compspec 9029(and, if attempted, the default Bash completions) generate no matches. 9030 9031 When a compspec indicates that directory name completion is desired, 9032the programmable completion functions force Readline to append a slash 9033to completed names which are symbolic links to directories, subject to 9034the value of the MARK-DIRECTORIES Readline variable, regardless of the 9035setting of the MARK-SYMLINKED-DIRECTORIES Readline variable. 9036 9037 There is some support for dynamically modifying completions. This is 9038most useful when used in combination with a default completion specified 9039with '-D'. It's possible for shell functions executed as completion 9040handlers to indicate that completion should be retried by returning an 9041exit status of 124. If a shell function returns 124, and changes the 9042compspec associated with the command on which completion is being 9043attempted (supplied as the first argument when the function is 9044executed), programmable completion restarts from the beginning, with an 9045attempt to find a new compspec for that command. This allows a set of 9046completions to be built dynamically as completion is attempted, rather 9047than being loaded all at once. 9048 9049 For instance, assuming that there is a library of compspecs, each 9050kept in a file corresponding to the name of the command, the following 9051default completion function would load completions dynamically: 9052 9053 _completion_loader() 9054 { 9055 . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124 9056 } 9057 complete -D -F _completion_loader -o bashdefault -o default 9058 9059 9060File: bash.info, Node: Programmable Completion Builtins, Next: A Programmable Completion Example, Prev: Programmable Completion, Up: Command Line Editing 9061 90628.7 Programmable Completion Builtins 9063==================================== 9064 9065Three builtin commands are available to manipulate the programmable 9066completion facilities: one to specify how the arguments to a particular 9067command are to be completed, and two to modify the completion as it is 9068happening. 9069 9070'compgen' 9071 compgen [OPTION] [WORD] 9072 9073 Generate possible completion matches for WORD according to the 9074 OPTIONs, which may be any option accepted by the 'complete' builtin 9075 with the exception of '-p' and '-r', and write the matches to the 9076 standard output. When using the '-F' or '-C' options, the various 9077 shell variables set by the programmable completion facilities, 9078 while available, will not have useful values. 9079 9080 The matches will be generated in the same way as if the 9081 programmable completion code had generated them directly from a 9082 completion specification with the same flags. If WORD is 9083 specified, only those completions matching WORD will be displayed. 9084 9085 The return value is true unless an invalid option is supplied, or 9086 no matches were generated. 9087 9088'complete' 9089 complete [-abcdefgjksuv] [-o COMP-OPTION] [-DEI] [-A ACTION] [-G GLOBPAT] 9090 [-W WORDLIST] [-F FUNCTION] [-C COMMAND] [-X FILTERPAT] 9091 [-P PREFIX] [-S SUFFIX] NAME [NAME ...] 9092 complete -pr [-DEI] [NAME ...] 9093 9094 Specify how arguments to each NAME should be completed. If the 9095 '-p' option is supplied, or if no options are supplied, existing 9096 completion specifications are printed in a way that allows them to 9097 be reused as input. The '-r' option removes a completion 9098 specification for each NAME, or, if no NAMEs are supplied, all 9099 completion specifications. The '-D' option indicates that other 9100 supplied options and actions should apply to the "default" command 9101 completion; that is, completion attempted on a command for which no 9102 completion has previously been defined. The '-E' option indicates 9103 that other supplied options and actions should apply to "empty" 9104 command completion; that is, completion attempted on a blank line. 9105 The '-I' option indicates that other supplied options and actions 9106 should apply to completion on the initial non-assignment word on 9107 the line, or after a command delimiter such as ';' or '|', which is 9108 usually command name completion. If multiple options are supplied, 9109 the '-D' option takes precedence over '-E', and both take 9110 precedence over '-I'. If any of '-D', '-E', or '-I' are supplied, 9111 any other NAME arguments are ignored; these completions only apply 9112 to the case specified by the option. 9113 9114 The process of applying these completion specifications when word 9115 completion is attempted is described above (*note Programmable 9116 Completion::). 9117 9118 Other options, if specified, have the following meanings. The 9119 arguments to the '-G', '-W', and '-X' options (and, if necessary, 9120 the '-P' and '-S' options) should be quoted to protect them from 9121 expansion before the 'complete' builtin is invoked. 9122 9123 '-o COMP-OPTION' 9124 The COMP-OPTION controls several aspects of the compspec's 9125 behavior beyond the simple generation of completions. 9126 COMP-OPTION may be one of: 9127 9128 'bashdefault' 9129 Perform the rest of the default Bash completions if the 9130 compspec generates no matches. 9131 9132 'default' 9133 Use Readline's default filename completion if the 9134 compspec generates no matches. 9135 9136 'dirnames' 9137 Perform directory name completion if the compspec 9138 generates no matches. 9139 9140 'filenames' 9141 Tell Readline that the compspec generates filenames, so 9142 it can perform any filename-specific processing (like 9143 adding a slash to directory names, quoting special 9144 characters, or suppressing trailing spaces). This option 9145 is intended to be used with shell functions specified 9146 with '-F'. 9147 9148 'noquote' 9149 Tell Readline not to quote the completed words if they 9150 are filenames (quoting filenames is the default). 9151 9152 'nosort' 9153 Tell Readline not to sort the list of possible 9154 completions alphabetically. 9155 9156 'nospace' 9157 Tell Readline not to append a space (the default) to 9158 words completed at the end of the line. 9159 9160 'plusdirs' 9161 After any matches defined by the compspec are generated, 9162 directory name completion is attempted and any matches 9163 are added to the results of the other actions. 9164 9165 '-A ACTION' 9166 The ACTION may be one of the following to generate a list of 9167 possible completions: 9168 9169 'alias' 9170 Alias names. May also be specified as '-a'. 9171 9172 'arrayvar' 9173 Array variable names. 9174 9175 'binding' 9176 Readline key binding names (*note Bindable Readline 9177 Commands::). 9178 9179 'builtin' 9180 Names of shell builtin commands. May also be specified 9181 as '-b'. 9182 9183 'command' 9184 Command names. May also be specified as '-c'. 9185 9186 'directory' 9187 Directory names. May also be specified as '-d'. 9188 9189 'disabled' 9190 Names of disabled shell builtins. 9191 9192 'enabled' 9193 Names of enabled shell builtins. 9194 9195 'export' 9196 Names of exported shell variables. May also be specified 9197 as '-e'. 9198 9199 'file' 9200 File names. May also be specified as '-f'. 9201 9202 'function' 9203 Names of shell functions. 9204 9205 'group' 9206 Group names. May also be specified as '-g'. 9207 9208 'helptopic' 9209 Help topics as accepted by the 'help' builtin (*note Bash 9210 Builtins::). 9211 9212 'hostname' 9213 Hostnames, as taken from the file specified by the 9214 'HOSTFILE' shell variable (*note Bash Variables::). 9215 9216 'job' 9217 Job names, if job control is active. May also be 9218 specified as '-j'. 9219 9220 'keyword' 9221 Shell reserved words. May also be specified as '-k'. 9222 9223 'running' 9224 Names of running jobs, if job control is active. 9225 9226 'service' 9227 Service names. May also be specified as '-s'. 9228 9229 'setopt' 9230 Valid arguments for the '-o' option to the 'set' builtin 9231 (*note The Set Builtin::). 9232 9233 'shopt' 9234 Shell option names as accepted by the 'shopt' builtin 9235 (*note Bash Builtins::). 9236 9237 'signal' 9238 Signal names. 9239 9240 'stopped' 9241 Names of stopped jobs, if job control is active. 9242 9243 'user' 9244 User names. May also be specified as '-u'. 9245 9246 'variable' 9247 Names of all shell variables. May also be specified as 9248 '-v'. 9249 9250 '-C COMMAND' 9251 COMMAND is executed in a subshell environment, and its output 9252 is used as the possible completions. 9253 9254 '-F FUNCTION' 9255 The shell function FUNCTION is executed in the current shell 9256 environment. When it is executed, $1 is the name of the 9257 command whose arguments are being completed, $2 is the word 9258 being completed, and $3 is the word preceding the word being 9259 completed, as described above (*note Programmable 9260 Completion::). When it finishes, the possible completions are 9261 retrieved from the value of the 'COMPREPLY' array variable. 9262 9263 '-G GLOBPAT' 9264 The filename expansion pattern GLOBPAT is expanded to generate 9265 the possible completions. 9266 9267 '-P PREFIX' 9268 PREFIX is added at the beginning of each possible completion 9269 after all other options have been applied. 9270 9271 '-S SUFFIX' 9272 SUFFIX is appended to each possible completion after all other 9273 options have been applied. 9274 9275 '-W WORDLIST' 9276 The WORDLIST is split using the characters in the 'IFS' 9277 special variable as delimiters, and each resultant word is 9278 expanded. The possible completions are the members of the 9279 resultant list which match the word being completed. 9280 9281 '-X FILTERPAT' 9282 FILTERPAT is a pattern as used for filename expansion. It is 9283 applied to the list of possible completions generated by the 9284 preceding options and arguments, and each completion matching 9285 FILTERPAT is removed from the list. A leading '!' in 9286 FILTERPAT negates the pattern; in this case, any completion 9287 not matching FILTERPAT is removed. 9288 9289 The return value is true unless an invalid option is supplied, an 9290 option other than '-p' or '-r' is supplied without a NAME argument, 9291 an attempt is made to remove a completion specification for a NAME 9292 for which no specification exists, or an error occurs adding a 9293 completion specification. 9294 9295'compopt' 9296 compopt [-o OPTION] [-DEI] [+o OPTION] [NAME] 9297 Modify completion options for each NAME according to the OPTIONs, 9298 or for the currently-executing completion if no NAMEs are supplied. 9299 If no OPTIONs are given, display the completion options for each 9300 NAME or the current completion. The possible values of OPTION are 9301 those valid for the 'complete' builtin described above. The '-D' 9302 option indicates that other supplied options should apply to the 9303 "default" command completion; that is, completion attempted on a 9304 command for which no completion has previously been defined. The 9305 '-E' option indicates that other supplied options should apply to 9306 "empty" command completion; that is, completion attempted on a 9307 blank line. The '-I' option indicates that other supplied options 9308 should apply to completion on the initial non-assignment word on 9309 the line, or after a command delimiter such as ';' or '|', which is 9310 usually command name completion. 9311 9312 If multiple options are supplied, the '-D' option takes precedence 9313 over '-E', and both take precedence over '-I' 9314 9315 The return value is true unless an invalid option is supplied, an 9316 attempt is made to modify the options for a NAME for which no 9317 completion specification exists, or an output error occurs. 9318 9319 9320File: bash.info, Node: A Programmable Completion Example, Prev: Programmable Completion Builtins, Up: Command Line Editing 9321 93228.8 A Programmable Completion Example 9323===================================== 9324 9325The most common way to obtain additional completion functionality beyond 9326the default actions 'complete' and 'compgen' provide is to use a shell 9327function and bind it to a particular command using 'complete -F'. 9328 9329 The following function provides completions for the 'cd' builtin. It 9330is a reasonably good example of what shell functions must do when used 9331for completion. This function uses the word passed as '$2' to determine 9332the directory name to complete. You can also use the 'COMP_WORDS' array 9333variable; the current word is indexed by the 'COMP_CWORD' variable. 9334 9335 The function relies on the 'complete' and 'compgen' builtins to do 9336much of the work, adding only the things that the Bash 'cd' does beyond 9337accepting basic directory names: tilde expansion (*note Tilde 9338Expansion::), searching directories in $CDPATH, which is described above 9339(*note Bourne Shell Builtins::), and basic support for the 'cdable_vars' 9340shell option (*note The Shopt Builtin::). '_comp_cd' modifies the value 9341of IFS so that it contains only a newline to accommodate file names 9342containing spaces and tabs - 'compgen' prints the possible completions 9343it generates one per line. 9344 9345 Possible completions go into the COMPREPLY array variable, one 9346completion per array element. The programmable completion system 9347retrieves the completions from there when the function returns. 9348 9349 # A completion function for the cd builtin 9350 # based on the cd completion function from the bash_completion package 9351 _comp_cd() 9352 { 9353 local IFS=$' \t\n' # normalize IFS 9354 local cur _skipdot _cdpath 9355 local i j k 9356 9357 # Tilde expansion, which also expands tilde to full pathname 9358 case "$2" in 9359 \~*) eval cur="$2" ;; 9360 *) cur=$2 ;; 9361 esac 9362 9363 # no cdpath or absolute pathname -- straight directory completion 9364 if [[ -z "${CDPATH:-}" ]] || [[ "$cur" == @(./*|../*|/*) ]]; then 9365 # compgen prints paths one per line; could also use while loop 9366 IFS=$'\n' 9367 COMPREPLY=( $(compgen -d -- "$cur") ) 9368 IFS=$' \t\n' 9369 # CDPATH+directories in the current directory if not in CDPATH 9370 else 9371 IFS=$'\n' 9372 _skipdot=false 9373 # preprocess CDPATH to convert null directory names to . 9374 _cdpath=${CDPATH/#:/.:} 9375 _cdpath=${_cdpath//::/:.:} 9376 _cdpath=${_cdpath/%:/:.} 9377 for i in ${_cdpath//:/$'\n'}; do 9378 if [[ $i -ef . ]]; then _skipdot=true; fi 9379 k="${#COMPREPLY[@]}" 9380 for j in $( compgen -d -- "$i/$cur" ); do 9381 COMPREPLY[k++]=${j#$i/} # cut off directory 9382 done 9383 done 9384 $_skipdot || COMPREPLY+=( $(compgen -d -- "$cur") ) 9385 IFS=$' \t\n' 9386 fi 9387 9388 # variable names if appropriate shell option set and no completions 9389 if shopt -q cdable_vars && [[ ${#COMPREPLY[@]} -eq 0 ]]; then 9390 COMPREPLY=( $(compgen -v -- "$cur") ) 9391 fi 9392 9393 return 0 9394 } 9395 9396 We install the completion function using the '-F' option to 9397'complete': 9398 9399 # Tell readline to quote appropriate and append slashes to directories; 9400 # use the bash default completion for other arguments 9401 complete -o filenames -o nospace -o bashdefault -F _comp_cd cd 9402 9403Since we'd like Bash and Readline to take care of some of the other 9404details for us, we use several other options to tell Bash and Readline 9405what to do. The '-o filenames' option tells Readline that the possible 9406completions should be treated as filenames, and quoted appropriately. 9407That option will also cause Readline to append a slash to filenames it 9408can determine are directories (which is why we might want to extend 9409'_comp_cd' to append a slash if we're using directories found via 9410CDPATH: Readline can't tell those completions are directories). The '-o 9411nospace' option tells Readline to not append a space character to the 9412directory name, in case we want to append to it. The '-o bashdefault' 9413option brings in the rest of the "Bash default" completions - possible 9414completion that Bash adds to the default Readline set. These include 9415things like command name completion, variable completion for words 9416beginning with '$' or '${', completions containing pathname expansion 9417patterns (*note Filename Expansion::), and so on. 9418 9419 Once installed using 'complete', '_comp_cd' will be called every time 9420we attempt word completion for a 'cd' command. 9421 9422 Many more examples - an extensive collection of completions for most 9423of the common GNU, Unix, and Linux commands - are available as part of 9424the bash_completion project. This is installed by default on many 9425GNU/Linux distributions. Originally written by Ian Macdonald, the 9426project now lives at <https://github.com/scop/bash-completion/>. There 9427are ports for other systems such as Solaris and Mac OS X. 9428 9429 An older version of the bash_completion package is distributed with 9430bash in the 'examples/complete' subdirectory. 9431 9432 9433File: bash.info, Node: Using History Interactively, Next: Installing Bash, Prev: Command Line Editing, Up: Top 9434 94359 Using History Interactively 9436***************************** 9437 9438This chapter describes how to use the GNU History Library interactively, 9439from a user's standpoint. It should be considered a user's guide. For 9440information on using the GNU History Library in other programs, see the 9441GNU Readline Library Manual. 9442 9443* Menu: 9444 9445* Bash History Facilities:: How Bash lets you manipulate your command 9446 history. 9447* Bash History Builtins:: The Bash builtin commands that manipulate 9448 the command history. 9449* History Interaction:: What it feels like using History as a user. 9450 9451 9452File: bash.info, Node: Bash History Facilities, Next: Bash History Builtins, Up: Using History Interactively 9453 94549.1 Bash History Facilities 9455=========================== 9456 9457When the '-o history' option to the 'set' builtin is enabled (*note The 9458Set Builtin::), the shell provides access to the "command history", the 9459list of commands previously typed. The value of the 'HISTSIZE' shell 9460variable is used as the number of commands to save in a history list. 9461The text of the last '$HISTSIZE' commands (default 500) is saved. The 9462shell stores each command in the history list prior to parameter and 9463variable expansion but after history expansion is performed, subject to 9464the values of the shell variables 'HISTIGNORE' and 'HISTCONTROL'. 9465 9466 When the shell starts up, the history is initialized from the file 9467named by the 'HISTFILE' variable (default '~/.bash_history'). The file 9468named by the value of 'HISTFILE' is truncated, if necessary, to contain 9469no more than the number of lines specified by the value of the 9470'HISTFILESIZE' variable. When a shell with history enabled exits, the 9471last '$HISTSIZE' lines are copied from the history list to the file 9472named by '$HISTFILE'. If the 'histappend' shell option is set (*note 9473Bash Builtins::), the lines are appended to the history file, otherwise 9474the history file is overwritten. If 'HISTFILE' is unset, or if the 9475history file is unwritable, the history is not saved. After saving the 9476history, the history file is truncated to contain no more than 9477'$HISTFILESIZE' lines. If 'HISTFILESIZE' is unset, or set to null, a 9478non-numeric value, or a numeric value less than zero, the history file 9479is not truncated. 9480 9481 If the 'HISTTIMEFORMAT' is set, the time stamp information associated 9482with each history entry is written to the history file, marked with the 9483history comment character. When the history file is read, lines 9484beginning with the history comment character followed immediately by a 9485digit are interpreted as timestamps for the following history entry. 9486 9487 The builtin command 'fc' may be used to list or edit and re-execute a 9488portion of the history list. The 'history' builtin may be used to 9489display or modify the history list and manipulate the history file. 9490When using command-line editing, search commands are available in each 9491editing mode that provide access to the history list (*note Commands For 9492History::). 9493 9494 The shell allows control over which commands are saved on the history 9495list. The 'HISTCONTROL' and 'HISTIGNORE' variables may be set to cause 9496the shell to save only a subset of the commands entered. The 'cmdhist' 9497shell option, if enabled, causes the shell to attempt to save each line 9498of a multi-line command in the same history entry, adding semicolons 9499where necessary to preserve syntactic correctness. The 'lithist' shell 9500option causes the shell to save the command with embedded newlines 9501instead of semicolons. The 'shopt' builtin is used to set these 9502options. *Note The Shopt Builtin::, for a description of 'shopt'. 9503 9504 9505File: bash.info, Node: Bash History Builtins, Next: History Interaction, Prev: Bash History Facilities, Up: Using History Interactively 9506 95079.2 Bash History Builtins 9508========================= 9509 9510Bash provides two builtin commands which manipulate the history list and 9511history file. 9512 9513'fc' 9514 fc [-e ENAME] [-lnr] [FIRST] [LAST] 9515 fc -s [PAT=REP] [COMMAND] 9516 9517 The first form selects a range of commands from FIRST to LAST from 9518 the history list and displays or edits and re-executes them. Both 9519 FIRST and LAST may be specified as a string (to locate the most 9520 recent command beginning with that string) or as a number (an index 9521 into the history list, where a negative number is used as an offset 9522 from the current command number). 9523 9524 When listing, a FIRST or LAST of 0 is equivalent to -1 and -0 is 9525 equivalent to the current command (usually the 'fc' command); 9526 otherwise 0 is equivalent to -1 and -0 is invalid. 9527 9528 If LAST is not specified, it is set to FIRST. If FIRST is not 9529 specified, it is set to the previous command for editing and -16 9530 for listing. If the '-l' flag is given, the commands are listed on 9531 standard output. The '-n' flag suppresses the command numbers when 9532 listing. The '-r' flag reverses the order of the listing. 9533 Otherwise, the editor given by ENAME is invoked on a file 9534 containing those commands. If ENAME is not given, the value of the 9535 following variable expansion is used: '${FCEDIT:-${EDITOR:-vi}}'. 9536 This says to use the value of the 'FCEDIT' variable if set, or the 9537 value of the 'EDITOR' variable if that is set, or 'vi' if neither 9538 is set. When editing is complete, the edited commands are echoed 9539 and executed. 9540 9541 In the second form, COMMAND is re-executed after each instance of 9542 PAT in the selected command is replaced by REP. COMMAND is 9543 interpreted the same as FIRST above. 9544 9545 A useful alias to use with the 'fc' command is 'r='fc -s'', so that 9546 typing 'r cc' runs the last command beginning with 'cc' and typing 9547 'r' re-executes the last command (*note Aliases::). 9548 9549'history' 9550 history [N] 9551 history -c 9552 history -d OFFSET 9553 history -d START-END 9554 history [-anrw] [FILENAME] 9555 history -ps ARG 9556 9557 With no options, display the history list with line numbers. Lines 9558 prefixed with a '*' have been modified. An argument of N lists 9559 only the last N lines. If the shell variable 'HISTTIMEFORMAT' is 9560 set and not null, it is used as a format string for STRFTIME to 9561 display the time stamp associated with each displayed history 9562 entry. No intervening blank is printed between the formatted time 9563 stamp and the history line. 9564 9565 Options, if supplied, have the following meanings: 9566 9567 '-c' 9568 Clear the history list. This may be combined with the other 9569 options to replace the history list completely. 9570 9571 '-d OFFSET' 9572 Delete the history entry at position OFFSET. If OFFSET is 9573 positive, it should be specified as it appears when the 9574 history is displayed. If OFFSET is negative, it is 9575 interpreted as relative to one greater than the last history 9576 position, so negative indices count back from the end of the 9577 history, and an index of '-1' refers to the current 'history 9578 -d' command. 9579 9580 '-d START-END' 9581 Delete the history entries between positions START and END, 9582 inclusive. Positive and negative values for START and END are 9583 interpreted as described above. 9584 9585 '-a' 9586 Append the new history lines to the history file. These are 9587 history lines entered since the beginning of the current Bash 9588 session, but not already appended to the history file. 9589 9590 '-n' 9591 Append the history lines not already read from the history 9592 file to the current history list. These are lines appended to 9593 the history file since the beginning of the current Bash 9594 session. 9595 9596 '-r' 9597 Read the history file and append its contents to the history 9598 list. 9599 9600 '-w' 9601 Write out the current history list to the history file. 9602 9603 '-p' 9604 Perform history substitution on the ARGs and display the 9605 result on the standard output, without storing the results in 9606 the history list. 9607 9608 '-s' 9609 The ARGs are added to the end of the history list as a single 9610 entry. 9611 9612 When any of the '-w', '-r', '-a', or '-n' options is used, if 9613 FILENAME is given, then it is used as the history file. If not, 9614 then the value of the 'HISTFILE' variable is used. 9615 9616 9617File: bash.info, Node: History Interaction, Prev: Bash History Builtins, Up: Using History Interactively 9618 96199.3 History Expansion 9620===================== 9621 9622The History library provides a history expansion feature that is similar 9623to the history expansion provided by 'csh'. This section describes the 9624syntax used to manipulate the history information. 9625 9626 History expansions introduce words from the history list into the 9627input stream, making it easy to repeat commands, insert the arguments to 9628a previous command into the current input line, or fix errors in 9629previous commands quickly. 9630 9631 History expansion is performed immediately after a complete line is 9632read, before the shell breaks it into words, and is performed on each 9633line individually. Bash attempts to inform the history expansion 9634functions about quoting still in effect from previous lines. 9635 9636 History expansion takes place in two parts. The first is to 9637determine which line from the history list should be used during 9638substitution. The second is to select portions of that line for 9639inclusion into the current one. The line selected from the history is 9640called the "event", and the portions of that line that are acted upon 9641are called "words". Various "modifiers" are available to manipulate the 9642selected words. The line is broken into words in the same fashion that 9643Bash does, so that several words surrounded by quotes are considered one 9644word. History expansions are introduced by the appearance of the 9645history expansion character, which is '!' by default. 9646 9647 History expansion implements shell-like quoting conventions: a 9648backslash can be used to remove the special handling for the next 9649character; single quotes enclose verbatim sequences of characters, and 9650can be used to inhibit history expansion; and characters enclosed within 9651double quotes may be subject to history expansion, since backslash can 9652escape the history expansion character, but single quotes may not, since 9653they are not treated specially within double quotes. 9654 9655 When using the shell, only '\' and ''' may be used to escape the 9656history expansion character, but the history expansion character is also 9657treated as quoted if it immediately precedes the closing double quote in 9658a double-quoted string. 9659 9660 Several shell options settable with the 'shopt' builtin (*note The 9661Shopt Builtin::) may be used to tailor the behavior of history 9662expansion. If the 'histverify' shell option is enabled, and Readline is 9663being used, history substitutions are not immediately passed to the 9664shell parser. Instead, the expanded line is reloaded into the Readline 9665editing buffer for further modification. If Readline is being used, and 9666the 'histreedit' shell option is enabled, a failed history expansion 9667will be reloaded into the Readline editing buffer for correction. The 9668'-p' option to the 'history' builtin command may be used to see what a 9669history expansion will do before using it. The '-s' option to the 9670'history' builtin may be used to add commands to the end of the history 9671list without actually executing them, so that they are available for 9672subsequent recall. This is most useful in conjunction with Readline. 9673 9674 The shell allows control of the various characters used by the 9675history expansion mechanism with the 'histchars' variable, as explained 9676above (*note Bash Variables::). The shell uses the history comment 9677character to mark history timestamps when writing the history file. 9678 9679* Menu: 9680 9681* Event Designators:: How to specify which history line to use. 9682* Word Designators:: Specifying which words are of interest. 9683* Modifiers:: Modifying the results of substitution. 9684 9685 9686File: bash.info, Node: Event Designators, Next: Word Designators, Up: History Interaction 9687 96889.3.1 Event Designators 9689----------------------- 9690 9691An event designator is a reference to a command line entry in the 9692history list. Unless the reference is absolute, events are relative to 9693the current position in the history list. 9694 9695'!' 9696 Start a history substitution, except when followed by a space, tab, 9697 the end of the line, '=' or '(' (when the 'extglob' shell option is 9698 enabled using the 'shopt' builtin). 9699 9700'!N' 9701 Refer to command line N. 9702 9703'!-N' 9704 Refer to the command N lines back. 9705 9706'!!' 9707 Refer to the previous command. This is a synonym for '!-1'. 9708 9709'!STRING' 9710 Refer to the most recent command preceding the current position in 9711 the history list starting with STRING. 9712 9713'!?STRING[?]' 9714 Refer to the most recent command preceding the current position in 9715 the history list containing STRING. The trailing '?' may be 9716 omitted if the STRING is followed immediately by a newline. If 9717 STRING is missing, the string from the most recent search is used; 9718 it is an error if there is no previous search string. 9719 9720'^STRING1^STRING2^' 9721 Quick Substitution. Repeat the last command, replacing STRING1 9722 with STRING2. Equivalent to '!!:s^STRING1^STRING2^'. 9723 9724'!#' 9725 The entire command line typed so far. 9726 9727 9728File: bash.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction 9729 97309.3.2 Word Designators 9731---------------------- 9732 9733Word designators are used to select desired words from the event. A ':' 9734separates the event specification from the word designator. It may be 9735omitted if the word designator begins with a '^', '$', '*', '-', or '%'. 9736Words are numbered from the beginning of the line, with the first word 9737being denoted by 0 (zero). Words are inserted into the current line 9738separated by single spaces. 9739 9740 For example, 9741 9742'!!' 9743 designates the preceding command. When you type this, the 9744 preceding command is repeated in toto. 9745 9746'!!:$' 9747 designates the last argument of the preceding command. This may be 9748 shortened to '!$'. 9749 9750'!fi:2' 9751 designates the second argument of the most recent command starting 9752 with the letters 'fi'. 9753 9754 Here are the word designators: 9755 9756'0 (zero)' 9757 The '0'th word. For many applications, this is the command word. 9758 9759'N' 9760 The Nth word. 9761 9762'^' 9763 The first argument; that is, word 1. 9764 9765'$' 9766 The last argument. 9767 9768'%' 9769 The first word matched by the most recent '?STRING?' search, if the 9770 search string begins with a character that is part of a word. 9771 9772'X-Y' 9773 A range of words; '-Y' abbreviates '0-Y'. 9774 9775'*' 9776 All of the words, except the '0'th. This is a synonym for '1-$'. 9777 It is not an error to use '*' if there is just one word in the 9778 event; the empty string is returned in that case. 9779 9780'X*' 9781 Abbreviates 'X-$' 9782 9783'X-' 9784 Abbreviates 'X-$' like 'X*', but omits the last word. If 'x' is 9785 missing, it defaults to 0. 9786 9787 If a word designator is supplied without an event specification, the 9788previous command is used as the event. 9789 9790 9791File: bash.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction 9792 97939.3.3 Modifiers 9794--------------- 9795 9796After the optional word designator, you can add a sequence of one or 9797more of the following modifiers, each preceded by a ':'. These modify, 9798or edit, the word or words selected from the history event. 9799 9800'h' 9801 Remove a trailing pathname component, leaving only the head. 9802 9803't' 9804 Remove all leading pathname components, leaving the tail. 9805 9806'r' 9807 Remove a trailing suffix of the form '.SUFFIX', leaving the 9808 basename. 9809 9810'e' 9811 Remove all but the trailing suffix. 9812 9813'p' 9814 Print the new command but do not execute it. 9815 9816'q' 9817 Quote the substituted words, escaping further substitutions. 9818 9819'x' 9820 Quote the substituted words as with 'q', but break into words at 9821 spaces, tabs, and newlines. The 'q' and 'x' modifiers are mutually 9822 exclusive; the last one supplied is used. 9823 9824's/OLD/NEW/' 9825 Substitute NEW for the first occurrence of OLD in the event line. 9826 Any character may be used as the delimiter in place of '/'. The 9827 delimiter may be quoted in OLD and NEW with a single backslash. If 9828 '&' appears in NEW, it is replaced by OLD. A single backslash will 9829 quote the '&'. If OLD is null, it is set to the last OLD 9830 substituted, or, if no previous history substitutions took place, 9831 the last STRING in a !?STRING'[?]' search. If NEW is is null, each 9832 matching OLD is deleted. The final delimiter is optional if it is 9833 the last character on the input line. 9834 9835'&' 9836 Repeat the previous substitution. 9837 9838'g' 9839'a' 9840 Cause changes to be applied over the entire event line. Used in 9841 conjunction with 's', as in 'gs/OLD/NEW/', or with '&'. 9842 9843'G' 9844 Apply the following 's' or '&' modifier once to each word in the 9845 event. 9846 9847 9848File: bash.info, Node: Installing Bash, Next: Reporting Bugs, Prev: Using History Interactively, Up: Top 9849 985010 Installing Bash 9851****************** 9852 9853This chapter provides basic instructions for installing Bash on the 9854various supported platforms. The distribution supports the GNU 9855operating systems, nearly every version of Unix, and several non-Unix 9856systems such as BeOS and Interix. Other independent ports exist for 9857MS-DOS, OS/2, and Windows platforms. 9858 9859* Menu: 9860 9861* Basic Installation:: Installation instructions. 9862* Compilers and Options:: How to set special options for various 9863 systems. 9864* Compiling For Multiple Architectures:: How to compile Bash for more 9865 than one kind of system from 9866 the same source tree. 9867* Installation Names:: How to set the various paths used by the installation. 9868* Specifying the System Type:: How to configure Bash for a particular system. 9869* Sharing Defaults:: How to share default configuration values among GNU 9870 programs. 9871* Operation Controls:: Options recognized by the configuration program. 9872* Optional Features:: How to enable and disable optional features when 9873 building Bash. 9874 9875 9876File: bash.info, Node: Basic Installation, Next: Compilers and Options, Up: Installing Bash 9877 987810.1 Basic Installation 9879======================= 9880 9881These are installation instructions for Bash. 9882 9883 The simplest way to compile Bash is: 9884 9885 1. 'cd' to the directory containing the source code and type 9886 './configure' to configure Bash for your system. If you're using 9887 'csh' on an old version of System V, you might need to type 'sh 9888 ./configure' instead to prevent 'csh' from trying to execute 9889 'configure' itself. 9890 9891 Running 'configure' takes some time. While running, it prints 9892 messages telling which features it is checking for. 9893 9894 2. Type 'make' to compile Bash and build the 'bashbug' bug reporting 9895 script. 9896 9897 3. Optionally, type 'make tests' to run the Bash test suite. 9898 9899 4. Type 'make install' to install 'bash' and 'bashbug'. This will 9900 also install the manual pages and Info file. 9901 9902 The 'configure' shell script attempts to guess correct values for 9903various system-dependent variables used during compilation. It uses 9904those values to create a 'Makefile' in each directory of the package 9905(the top directory, the 'builtins', 'doc', and 'support' directories, 9906each directory under 'lib', and several others). It also creates a 9907'config.h' file containing system-dependent definitions. Finally, it 9908creates a shell script named 'config.status' that you can run in the 9909future to recreate the current configuration, a file 'config.cache' that 9910saves the results of its tests to speed up reconfiguring, and a file 9911'config.log' containing compiler output (useful mainly for debugging 9912'configure'). If at some point 'config.cache' contains results you 9913don't want to keep, you may remove or edit it. 9914 9915 To find out more about the options and arguments that the 'configure' 9916script understands, type 9917 9918 bash-4.2$ ./configure --help 9919 9920at the Bash prompt in your Bash source directory. 9921 9922 If you want to build Bash in a directory separate from the source 9923directory - to build for multiple architectures, for example - just use 9924the full path to the configure script. The following commands will 9925build bash in a directory under '/usr/local/build' from the source code 9926in '/usr/local/src/bash-4.4': 9927 9928 mkdir /usr/local/build/bash-4.4 9929 cd /usr/local/build/bash-4.4 9930 bash /usr/local/src/bash-4.4/configure 9931 make 9932 9933 See *note Compiling For Multiple Architectures:: for more information 9934about building in a directory separate from the source. 9935 9936 If you need to do unusual things to compile Bash, please try to 9937figure out how 'configure' could check whether or not to do them, and 9938mail diffs or instructions to <bash-maintainers@gnu.org> so they can be 9939considered for the next release. 9940 9941 The file 'configure.ac' is used to create 'configure' by a program 9942called Autoconf. You only need 'configure.ac' if you want to change it 9943or regenerate 'configure' using a newer version of Autoconf. If you do 9944this, make sure you are using Autoconf version 2.50 or newer. 9945 9946 You can remove the program binaries and object files from the source 9947code directory by typing 'make clean'. To also remove the files that 9948'configure' created (so you can compile Bash for a different kind of 9949computer), type 'make distclean'. 9950 9951 9952File: bash.info, Node: Compilers and Options, Next: Compiling For Multiple Architectures, Prev: Basic Installation, Up: Installing Bash 9953 995410.2 Compilers and Options 9955========================== 9956 9957Some systems require unusual options for compilation or linking that the 9958'configure' script does not know about. You can give 'configure' 9959initial values for variables by setting them in the environment. Using 9960a Bourne-compatible shell, you can do that on the command line like 9961this: 9962 9963 CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure 9964 9965 On systems that have the 'env' program, you can do it like this: 9966 9967 env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure 9968 9969 The configuration process uses GCC to build Bash if it is available. 9970 9971 9972File: bash.info, Node: Compiling For Multiple Architectures, Next: Installation Names, Prev: Compilers and Options, Up: Installing Bash 9973 997410.3 Compiling For Multiple Architectures 9975========================================= 9976 9977You can compile Bash for more than one kind of computer at the same 9978time, by placing the object files for each architecture in their own 9979directory. To do this, you must use a version of 'make' that supports 9980the 'VPATH' variable, such as GNU 'make'. 'cd' to the directory where 9981you want the object files and executables to go and run the 'configure' 9982script from the source directory (*note Basic Installation::). You may 9983need to supply the '--srcdir=PATH' argument to tell 'configure' where 9984the source files are. 'configure' automatically checks for the source 9985code in the directory that 'configure' is in and in '..'. 9986 9987 If you have to use a 'make' that does not supports the 'VPATH' 9988variable, you can compile Bash for one architecture at a time in the 9989source code directory. After you have installed Bash for one 9990architecture, use 'make distclean' before reconfiguring for another 9991architecture. 9992 9993 Alternatively, if your system supports symbolic links, you can use 9994the 'support/mkclone' script to create a build tree which has symbolic 9995links back to each file in the source directory. Here's an example that 9996creates a build directory in the current directory from a source 9997directory '/usr/gnu/src/bash-2.0': 9998 9999 bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 . 10000 10001The 'mkclone' script requires Bash, so you must have already built Bash 10002for at least one architecture before you can create build directories 10003for other architectures. 10004 10005 10006File: bash.info, Node: Installation Names, Next: Specifying the System Type, Prev: Compiling For Multiple Architectures, Up: Installing Bash 10007 1000810.4 Installation Names 10009======================= 10010 10011By default, 'make install' will install into '/usr/local/bin', 10012'/usr/local/man', etc. You can specify an installation prefix other 10013than '/usr/local' by giving 'configure' the option '--prefix=PATH', or 10014by specifying a value for the 'DESTDIR' 'make' variable when running 10015'make install'. 10016 10017 You can specify separate installation prefixes for 10018architecture-specific files and architecture-independent files. If you 10019give 'configure' the option '--exec-prefix=PATH', 'make install' will 10020use PATH as the prefix for installing programs and libraries. 10021Documentation and other data files will still use the regular prefix. 10022 10023 10024File: bash.info, Node: Specifying the System Type, Next: Sharing Defaults, Prev: Installation Names, Up: Installing Bash 10025 1002610.5 Specifying the System Type 10027=============================== 10028 10029There may be some features 'configure' can not figure out automatically, 10030but need to determine by the type of host Bash will run on. Usually 10031'configure' can figure that out, but if it prints a message saying it 10032can not guess the host type, give it the '--host=TYPE' option. 'TYPE' 10033can either be a short name for the system type, such as 'sun4', or a 10034canonical name with three fields: 'CPU-COMPANY-SYSTEM' (e.g., 10035'i386-unknown-freebsd4.2'). 10036 10037 See the file 'support/config.sub' for the possible values of each 10038field. 10039 10040 10041File: bash.info, Node: Sharing Defaults, Next: Operation Controls, Prev: Specifying the System Type, Up: Installing Bash 10042 1004310.6 Sharing Defaults 10044===================== 10045 10046If you want to set default values for 'configure' scripts to share, you 10047can create a site shell script called 'config.site' that gives default 10048values for variables like 'CC', 'cache_file', and 'prefix'. 'configure' 10049looks for 'PREFIX/share/config.site' if it exists, then 10050'PREFIX/etc/config.site' if it exists. Or, you can set the 10051'CONFIG_SITE' environment variable to the location of the site script. 10052A warning: the Bash 'configure' looks for a site script, but not all 10053'configure' scripts do. 10054 10055 10056File: bash.info, Node: Operation Controls, Next: Optional Features, Prev: Sharing Defaults, Up: Installing Bash 10057 1005810.7 Operation Controls 10059======================= 10060 10061'configure' recognizes the following options to control how it operates. 10062 10063'--cache-file=FILE' 10064 Use and save the results of the tests in FILE instead of 10065 './config.cache'. Set FILE to '/dev/null' to disable caching, for 10066 debugging 'configure'. 10067 10068'--help' 10069 Print a summary of the options to 'configure', and exit. 10070 10071'--quiet' 10072'--silent' 10073'-q' 10074 Do not print messages saying which checks are being made. 10075 10076'--srcdir=DIR' 10077 Look for the Bash source code in directory DIR. Usually 10078 'configure' can determine that directory automatically. 10079 10080'--version' 10081 Print the version of Autoconf used to generate the 'configure' 10082 script, and exit. 10083 10084 'configure' also accepts some other, not widely used, boilerplate 10085options. 'configure --help' prints the complete list. 10086 10087 10088File: bash.info, Node: Optional Features, Prev: Operation Controls, Up: Installing Bash 10089 1009010.8 Optional Features 10091====================== 10092 10093The Bash 'configure' has a number of '--enable-FEATURE' options, where 10094FEATURE indicates an optional part of Bash. There are also several 10095'--with-PACKAGE' options, where PACKAGE is something like 'bash-malloc' 10096or 'purify'. To turn off the default use of a package, use 10097'--without-PACKAGE'. To configure Bash without a feature that is 10098enabled by default, use '--disable-FEATURE'. 10099 10100 Here is a complete list of the '--enable-' and '--with-' options that 10101the Bash 'configure' recognizes. 10102 10103'--with-afs' 10104 Define if you are using the Andrew File System from Transarc. 10105 10106'--with-bash-malloc' 10107 Use the Bash version of 'malloc' in the directory 'lib/malloc'. 10108 This is not the same 'malloc' that appears in GNU libc, but an 10109 older version originally derived from the 4.2 BSD 'malloc'. This 10110 'malloc' is very fast, but wastes some space on each allocation. 10111 This option is enabled by default. The 'NOTES' file contains a 10112 list of systems for which this should be turned off, and 10113 'configure' disables this option automatically for a number of 10114 systems. 10115 10116'--with-curses' 10117 Use the curses library instead of the termcap library. This should 10118 be supplied if your system has an inadequate or incomplete termcap 10119 database. 10120 10121'--with-gnu-malloc' 10122 A synonym for '--with-bash-malloc'. 10123 10124'--with-installed-readline[=PREFIX]' 10125 Define this to make Bash link with a locally-installed version of 10126 Readline rather than the version in 'lib/readline'. This works 10127 only with Readline 5.0 and later versions. If PREFIX is 'yes' or 10128 not supplied, 'configure' uses the values of the make variables 10129 'includedir' and 'libdir', which are subdirectories of 'prefix' by 10130 default, to find the installed version of Readline if it is not in 10131 the standard system include and library directories. If PREFIX is 10132 'no', Bash links with the version in 'lib/readline'. If PREFIX is 10133 set to any other value, 'configure' treats it as a directory 10134 pathname and looks for the installed version of Readline in 10135 subdirectories of that directory (include files in PREFIX/'include' 10136 and the library in PREFIX/'lib'). 10137 10138'--with-purify' 10139 Define this to use the Purify memory allocation checker from 10140 Rational Software. 10141 10142'--enable-minimal-config' 10143 This produces a shell with minimal features, close to the 10144 historical Bourne shell. 10145 10146 There are several '--enable-' options that alter how Bash is compiled 10147and linked, rather than changing run-time features. 10148 10149'--enable-largefile' 10150 Enable support for large files 10151 (http://www.unix.org/version2/whatsnew/lfs20mar.html) if the 10152 operating system requires special compiler options to build 10153 programs which can access large files. This is enabled by default, 10154 if the operating system provides large file support. 10155 10156'--enable-profiling' 10157 This builds a Bash binary that produces profiling information to be 10158 processed by 'gprof' each time it is executed. 10159 10160'--enable-static-link' 10161 This causes Bash to be linked statically, if 'gcc' is being used. 10162 This could be used to build a version to use as root's shell. 10163 10164 The 'minimal-config' option can be used to disable all of the 10165following options, but it is processed first, so individual options may 10166be enabled using 'enable-FEATURE'. 10167 10168 All of the following options except for 'disabled-builtins', 10169'direxpand-default', and 'xpg-echo-default' are enabled by default, 10170unless the operating system does not provide the necessary support. 10171 10172'--enable-alias' 10173 Allow alias expansion and include the 'alias' and 'unalias' 10174 builtins (*note Aliases::). 10175 10176'--enable-arith-for-command' 10177 Include support for the alternate form of the 'for' command that 10178 behaves like the C language 'for' statement (*note Looping 10179 Constructs::). 10180 10181'--enable-array-variables' 10182 Include support for one-dimensional array shell variables (*note 10183 Arrays::). 10184 10185'--enable-bang-history' 10186 Include support for 'csh'-like history substitution (*note History 10187 Interaction::). 10188 10189'--enable-brace-expansion' 10190 Include 'csh'-like brace expansion ( 'b{a,b}c' ==> 'bac bbc' ). 10191 See *note Brace Expansion::, for a complete description. 10192 10193'--enable-casemod-attributes' 10194 Include support for case-modifying attributes in the 'declare' 10195 builtin and assignment statements. Variables with the UPPERCASE 10196 attribute, for example, will have their values converted to 10197 uppercase upon assignment. 10198 10199'--enable-casemod-expansion' 10200 Include support for case-modifying word expansions. 10201 10202'--enable-command-timing' 10203 Include support for recognizing 'time' as a reserved word and for 10204 displaying timing statistics for the pipeline following 'time' 10205 (*note Pipelines::). This allows pipelines as well as shell 10206 builtins and functions to be timed. 10207 10208'--enable-cond-command' 10209 Include support for the '[[' conditional command. (*note 10210 Conditional Constructs::). 10211 10212'--enable-cond-regexp' 10213 Include support for matching POSIX regular expressions using the 10214 '=~' binary operator in the '[[' conditional command. (*note 10215 Conditional Constructs::). 10216 10217'--enable-coprocesses' 10218 Include support for coprocesses and the 'coproc' reserved word 10219 (*note Pipelines::). 10220 10221'--enable-debugger' 10222 Include support for the bash debugger (distributed separately). 10223 10224'--enable-dev-fd-stat-broken' 10225 If calling 'stat' on /dev/fd/N returns different results than 10226 calling 'fstat' on file descriptor N, supply this option to enable 10227 a workaround. This has implications for conditional commands that 10228 test file attributes. 10229 10230'--enable-direxpand-default' 10231 Cause the 'direxpand' shell option (*note The Shopt Builtin::) to 10232 be enabled by default when the shell starts. It is normally 10233 disabled by default. 10234 10235'--enable-directory-stack' 10236 Include support for a 'csh'-like directory stack and the 'pushd', 10237 'popd', and 'dirs' builtins (*note The Directory Stack::). 10238 10239'--enable-disabled-builtins' 10240 Allow builtin commands to be invoked via 'builtin xxx' even after 10241 'xxx' has been disabled using 'enable -n xxx'. See *note Bash 10242 Builtins::, for details of the 'builtin' and 'enable' builtin 10243 commands. 10244 10245'--enable-dparen-arithmetic' 10246 Include support for the '((...))' command (*note Conditional 10247 Constructs::). 10248 10249'--enable-extended-glob' 10250 Include support for the extended pattern matching features 10251 described above under *note Pattern Matching::. 10252 10253'--enable-extended-glob-default' 10254 Set the default value of the EXTGLOB shell option described above 10255 under *note The Shopt Builtin:: to be enabled. 10256 10257'--enable-function-import' 10258 Include support for importing function definitions exported by 10259 another instance of the shell from the environment. This option is 10260 enabled by default. 10261 10262'--enable-glob-asciirange-default' 10263 Set the default value of the GLOBASCIIRANGES shell option described 10264 above under *note The Shopt Builtin:: to be enabled. This controls 10265 the behavior of character ranges when used in pattern matching 10266 bracket expressions. 10267 10268'--enable-help-builtin' 10269 Include the 'help' builtin, which displays help on shell builtins 10270 and variables (*note Bash Builtins::). 10271 10272'--enable-history' 10273 Include command history and the 'fc' and 'history' builtin commands 10274 (*note Bash History Facilities::). 10275 10276'--enable-job-control' 10277 This enables the job control features (*note Job Control::), if the 10278 operating system supports them. 10279 10280'--enable-multibyte' 10281 This enables support for multibyte characters if the operating 10282 system provides the necessary support. 10283 10284'--enable-net-redirections' 10285 This enables the special handling of filenames of the form 10286 '/dev/tcp/HOST/PORT' and '/dev/udp/HOST/PORT' when used in 10287 redirections (*note Redirections::). 10288 10289'--enable-process-substitution' 10290 This enables process substitution (*note Process Substitution::) if 10291 the operating system provides the necessary support. 10292 10293'--enable-progcomp' 10294 Enable the programmable completion facilities (*note Programmable 10295 Completion::). If Readline is not enabled, this option has no 10296 effect. 10297 10298'--enable-prompt-string-decoding' 10299 Turn on the interpretation of a number of backslash-escaped 10300 characters in the '$PS0', '$PS1', '$PS2', and '$PS4' prompt 10301 strings. See *note Controlling the Prompt::, for a complete list 10302 of prompt string escape sequences. 10303 10304'--enable-readline' 10305 Include support for command-line editing and history with the Bash 10306 version of the Readline library (*note Command Line Editing::). 10307 10308'--enable-restricted' 10309 Include support for a "restricted shell". If this is enabled, 10310 Bash, when called as 'rbash', enters a restricted mode. See *note 10311 The Restricted Shell::, for a description of restricted mode. 10312 10313'--enable-select' 10314 Include the 'select' compound command, which allows the generation 10315 of simple menus (*note Conditional Constructs::). 10316 10317'--enable-separate-helpfiles' 10318 Use external files for the documentation displayed by the 'help' 10319 builtin instead of storing the text internally. 10320 10321'--enable-single-help-strings' 10322 Store the text displayed by the 'help' builtin as a single string 10323 for each help topic. This aids in translating the text to 10324 different languages. You may need to disable this if your compiler 10325 cannot handle very long string literals. 10326 10327'--enable-strict-posix-default' 10328 Make Bash POSIX-conformant by default (*note Bash POSIX Mode::). 10329 10330'--enable-usg-echo-default' 10331 A synonym for '--enable-xpg-echo-default'. 10332 10333'--enable-xpg-echo-default' 10334 Make the 'echo' builtin expand backslash-escaped characters by 10335 default, without requiring the '-e' option. This sets the default 10336 value of the 'xpg_echo' shell option to 'on', which makes the Bash 10337 'echo' behave more like the version specified in the Single Unix 10338 Specification, version 3. *Note Bash Builtins::, for a description 10339 of the escape sequences that 'echo' recognizes. 10340 10341 The file 'config-top.h' contains C Preprocessor '#define' statements 10342for options which are not settable from 'configure'. Some of these are 10343not meant to be changed; beware of the consequences if you do. Read the 10344comments associated with each definition for more information about its 10345effect. 10346 10347 10348File: bash.info, Node: Reporting Bugs, Next: Major Differences From The Bourne Shell, Prev: Installing Bash, Up: Top 10349 10350Appendix A Reporting Bugs 10351************************* 10352 10353Please report all bugs you find in Bash. But first, you should make 10354sure that it really is a bug, and that it appears in the latest version 10355of Bash. The latest version of Bash is always available for FTP from 10356<ftp://ftp.gnu.org/pub/gnu/bash/>. 10357 10358 Once you have determined that a bug actually exists, use the 10359'bashbug' command to submit a bug report. If you have a fix, you are 10360encouraged to mail that as well! Suggestions and 'philosophical' bug 10361reports may be mailed to <bug-bash@gnu.org> or posted to the Usenet 10362newsgroup 'gnu.bash.bug'. 10363 10364 All bug reports should include: 10365 * The version number of Bash. 10366 * The hardware and operating system. 10367 * The compiler used to compile Bash. 10368 * A description of the bug behaviour. 10369 * A short script or 'recipe' which exercises the bug and may be used 10370 to reproduce it. 10371 10372'bashbug' inserts the first three items automatically into the template 10373it provides for filing a bug report. 10374 10375 Please send all reports concerning this manual to <bug-bash@gnu.org>. 10376 10377 10378File: bash.info, Node: Major Differences From The Bourne Shell, Next: GNU Free Documentation License, Prev: Reporting Bugs, Up: Top 10379 10380Appendix B Major Differences From The Bourne Shell 10381************************************************** 10382 10383Bash implements essentially the same grammar, parameter and variable 10384expansion, redirection, and quoting as the Bourne Shell. Bash uses the 10385POSIX standard as the specification of how these features are to be 10386implemented. There are some differences between the traditional Bourne 10387shell and Bash; this section quickly details the differences of 10388significance. A number of these differences are explained in greater 10389depth in previous sections. This section uses the version of 'sh' 10390included in SVR4.2 (the last version of the historical Bourne shell) as 10391the baseline reference. 10392 10393 * Bash is POSIX-conformant, even where the POSIX specification 10394 differs from traditional 'sh' behavior (*note Bash POSIX Mode::). 10395 10396 * Bash has multi-character invocation options (*note Invoking 10397 Bash::). 10398 10399 * Bash has command-line editing (*note Command Line Editing::) and 10400 the 'bind' builtin. 10401 10402 * Bash provides a programmable word completion mechanism (*note 10403 Programmable Completion::), and builtin commands 'complete', 10404 'compgen', and 'compopt', to manipulate it. 10405 10406 * Bash has command history (*note Bash History Facilities::) and the 10407 'history' and 'fc' builtins to manipulate it. The Bash history 10408 list maintains timestamp information and uses the value of the 10409 'HISTTIMEFORMAT' variable to display it. 10410 10411 * Bash implements 'csh'-like history expansion (*note History 10412 Interaction::). 10413 10414 * Bash has one-dimensional array variables (*note Arrays::), and the 10415 appropriate variable expansions and assignment syntax to use them. 10416 Several of the Bash builtins take options to act on arrays. Bash 10417 provides a number of built-in array variables. 10418 10419 * The '$'...'' quoting syntax, which expands ANSI-C backslash-escaped 10420 characters in the text between the single quotes, is supported 10421 (*note ANSI-C Quoting::). 10422 10423 * Bash supports the '$"..."' quoting syntax to do locale-specific 10424 translation of the characters between the double quotes. The '-D', 10425 '--dump-strings', and '--dump-po-strings' invocation options list 10426 the translatable strings found in a script (*note Locale 10427 Translation::). 10428 10429 * Bash implements the '!' keyword to negate the return value of a 10430 pipeline (*note Pipelines::). Very useful when an 'if' statement 10431 needs to act only if a test fails. The Bash '-o pipefail' option 10432 to 'set' will cause a pipeline to return a failure status if any 10433 command fails. 10434 10435 * Bash has the 'time' reserved word and command timing (*note 10436 Pipelines::). The display of the timing statistics may be 10437 controlled with the 'TIMEFORMAT' variable. 10438 10439 * Bash implements the 'for (( EXPR1 ; EXPR2 ; EXPR3 ))' arithmetic 10440 for command, similar to the C language (*note Looping 10441 Constructs::). 10442 10443 * Bash includes the 'select' compound command, which allows the 10444 generation of simple menus (*note Conditional Constructs::). 10445 10446 * Bash includes the '[[' compound command, which makes conditional 10447 testing part of the shell grammar (*note Conditional Constructs::), 10448 including optional regular expression matching. 10449 10450 * Bash provides optional case-insensitive matching for the 'case' and 10451 '[[' constructs. 10452 10453 * Bash includes brace expansion (*note Brace Expansion::) and tilde 10454 expansion (*note Tilde Expansion::). 10455 10456 * Bash implements command aliases and the 'alias' and 'unalias' 10457 builtins (*note Aliases::). 10458 10459 * Bash provides shell arithmetic, the '((' compound command (*note 10460 Conditional Constructs::), and arithmetic expansion (*note Shell 10461 Arithmetic::). 10462 10463 * Variables present in the shell's initial environment are 10464 automatically exported to child processes. The Bourne shell does 10465 not normally do this unless the variables are explicitly marked 10466 using the 'export' command. 10467 10468 * Bash supports the '+=' assignment operator, which appends to the 10469 value of the variable named on the left hand side. 10470 10471 * Bash includes the POSIX pattern removal '%', '#', '%%' and '##' 10472 expansions to remove leading or trailing substrings from variable 10473 values (*note Shell Parameter Expansion::). 10474 10475 * The expansion '${#xx}', which returns the length of '${xx}', is 10476 supported (*note Shell Parameter Expansion::). 10477 10478 * The expansion '${var:'OFFSET'[:'LENGTH']}', which expands to the 10479 substring of 'var''s value of length LENGTH, beginning at OFFSET, 10480 is present (*note Shell Parameter Expansion::). 10481 10482 * The expansion '${var/[/]'PATTERN'[/'REPLACEMENT']}', which matches 10483 PATTERN and replaces it with REPLACEMENT in the value of 'var', is 10484 available (*note Shell Parameter Expansion::). 10485 10486 * The expansion '${!PREFIX*}' expansion, which expands to the names 10487 of all shell variables whose names begin with PREFIX, is available 10488 (*note Shell Parameter Expansion::). 10489 10490 * Bash has INDIRECT variable expansion using '${!word}' (*note Shell 10491 Parameter Expansion::). 10492 10493 * Bash can expand positional parameters beyond '$9' using '${NUM}'. 10494 10495 * The POSIX '$()' form of command substitution is implemented (*note 10496 Command Substitution::), and preferred to the Bourne shell's '``' 10497 (which is also implemented for backwards compatibility). 10498 10499 * Bash has process substitution (*note Process Substitution::). 10500 10501 * Bash automatically assigns variables that provide information about 10502 the current user ('UID', 'EUID', and 'GROUPS'), the current host 10503 ('HOSTTYPE', 'OSTYPE', 'MACHTYPE', and 'HOSTNAME'), and the 10504 instance of Bash that is running ('BASH', 'BASH_VERSION', and 10505 'BASH_VERSINFO'). *Note Bash Variables::, for details. 10506 10507 * The 'IFS' variable is used to split only the results of expansion, 10508 not all words (*note Word Splitting::). This closes a longstanding 10509 shell security hole. 10510 10511 * The filename expansion bracket expression code uses '!' and '^' to 10512 negate the set of characters between the brackets. The Bourne 10513 shell uses only '!'. 10514 10515 * Bash implements the full set of POSIX filename expansion operators, 10516 including CHARACTER CLASSES, EQUIVALENCE CLASSES, and COLLATING 10517 SYMBOLS (*note Filename Expansion::). 10518 10519 * Bash implements extended pattern matching features when the 10520 'extglob' shell option is enabled (*note Pattern Matching::). 10521 10522 * It is possible to have a variable and a function with the same 10523 name; 'sh' does not separate the two name spaces. 10524 10525 * Bash functions are permitted to have local variables using the 10526 'local' builtin, and thus useful recursive functions may be written 10527 (*note Bash Builtins::). 10528 10529 * Variable assignments preceding commands affect only that command, 10530 even builtins and functions (*note Environment::). In 'sh', all 10531 variable assignments preceding commands are global unless the 10532 command is executed from the file system. 10533 10534 * Bash performs filename expansion on filenames specified as operands 10535 to input and output redirection operators (*note Redirections::). 10536 10537 * Bash contains the '<>' redirection operator, allowing a file to be 10538 opened for both reading and writing, and the '&>' redirection 10539 operator, for directing standard output and standard error to the 10540 same file (*note Redirections::). 10541 10542 * Bash includes the '<<<' redirection operator, allowing a string to 10543 be used as the standard input to a command. 10544 10545 * Bash implements the '[n]<&WORD' and '[n]>&WORD' redirection 10546 operators, which move one file descriptor to another. 10547 10548 * Bash treats a number of filenames specially when they are used in 10549 redirection operators (*note Redirections::). 10550 10551 * Bash can open network connections to arbitrary machines and 10552 services with the redirection operators (*note Redirections::). 10553 10554 * The 'noclobber' option is available to avoid overwriting existing 10555 files with output redirection (*note The Set Builtin::). The '>|' 10556 redirection operator may be used to override 'noclobber'. 10557 10558 * The Bash 'cd' and 'pwd' builtins (*note Bourne Shell Builtins::) 10559 each take '-L' and '-P' options to switch between logical and 10560 physical modes. 10561 10562 * Bash allows a function to override a builtin with the same name, 10563 and provides access to that builtin's functionality within the 10564 function via the 'builtin' and 'command' builtins (*note Bash 10565 Builtins::). 10566 10567 * The 'command' builtin allows selective disabling of functions when 10568 command lookup is performed (*note Bash Builtins::). 10569 10570 * Individual builtins may be enabled or disabled using the 'enable' 10571 builtin (*note Bash Builtins::). 10572 10573 * The Bash 'exec' builtin takes additional options that allow users 10574 to control the contents of the environment passed to the executed 10575 command, and what the zeroth argument to the command is to be 10576 (*note Bourne Shell Builtins::). 10577 10578 * Shell functions may be exported to children via the environment 10579 using 'export -f' (*note Shell Functions::). 10580 10581 * The Bash 'export', 'readonly', and 'declare' builtins can take a 10582 '-f' option to act on shell functions, a '-p' option to display 10583 variables with various attributes set in a format that can be used 10584 as shell input, a '-n' option to remove various variable 10585 attributes, and 'name=value' arguments to set variable attributes 10586 and values simultaneously. 10587 10588 * The Bash 'hash' builtin allows a name to be associated with an 10589 arbitrary filename, even when that filename cannot be found by 10590 searching the '$PATH', using 'hash -p' (*note Bourne Shell 10591 Builtins::). 10592 10593 * Bash includes a 'help' builtin for quick reference to shell 10594 facilities (*note Bash Builtins::). 10595 10596 * The 'printf' builtin is available to display formatted output 10597 (*note Bash Builtins::). 10598 10599 * The Bash 'read' builtin (*note Bash Builtins::) will read a line 10600 ending in '\' with the '-r' option, and will use the 'REPLY' 10601 variable as a default if no non-option arguments are supplied. The 10602 Bash 'read' builtin also accepts a prompt string with the '-p' 10603 option and will use Readline to obtain the line when given the '-e' 10604 option. The 'read' builtin also has additional options to control 10605 input: the '-s' option will turn off echoing of input characters as 10606 they are read, the '-t' option will allow 'read' to time out if 10607 input does not arrive within a specified number of seconds, the 10608 '-n' option will allow reading only a specified number of 10609 characters rather than a full line, and the '-d' option will read 10610 until a particular character rather than newline. 10611 10612 * The 'return' builtin may be used to abort execution of scripts 10613 executed with the '.' or 'source' builtins (*note Bourne Shell 10614 Builtins::). 10615 10616 * Bash includes the 'shopt' builtin, for finer control of shell 10617 optional capabilities (*note The Shopt Builtin::), and allows these 10618 options to be set and unset at shell invocation (*note Invoking 10619 Bash::). 10620 10621 * Bash has much more optional behavior controllable with the 'set' 10622 builtin (*note The Set Builtin::). 10623 10624 * The '-x' ('xtrace') option displays commands other than simple 10625 commands when performing an execution trace (*note The Set 10626 Builtin::). 10627 10628 * The 'test' builtin (*note Bourne Shell Builtins::) is slightly 10629 different, as it implements the POSIX algorithm, which specifies 10630 the behavior based on the number of arguments. 10631 10632 * Bash includes the 'caller' builtin, which displays the context of 10633 any active subroutine call (a shell function or a script executed 10634 with the '.' or 'source' builtins). This supports the bash 10635 debugger. 10636 10637 * The 'trap' builtin (*note Bourne Shell Builtins::) allows a 'DEBUG' 10638 pseudo-signal specification, similar to 'EXIT'. Commands specified 10639 with a 'DEBUG' trap are executed before every simple command, 'for' 10640 command, 'case' command, 'select' command, every arithmetic 'for' 10641 command, and before the first command executes in a shell function. 10642 The 'DEBUG' trap is not inherited by shell functions unless the 10643 function has been given the 'trace' attribute or the 'functrace' 10644 option has been enabled using the 'shopt' builtin. The 'extdebug' 10645 shell option has additional effects on the 'DEBUG' trap. 10646 10647 The 'trap' builtin (*note Bourne Shell Builtins::) allows an 'ERR' 10648 pseudo-signal specification, similar to 'EXIT' and 'DEBUG'. 10649 Commands specified with an 'ERR' trap are executed after a simple 10650 command fails, with a few exceptions. The 'ERR' trap is not 10651 inherited by shell functions unless the '-o errtrace' option to the 10652 'set' builtin is enabled. 10653 10654 The 'trap' builtin (*note Bourne Shell Builtins::) allows a 10655 'RETURN' pseudo-signal specification, similar to 'EXIT' and 10656 'DEBUG'. Commands specified with an 'RETURN' trap are executed 10657 before execution resumes after a shell function or a shell script 10658 executed with '.' or 'source' returns. The 'RETURN' trap is not 10659 inherited by shell functions unless the function has been given the 10660 'trace' attribute or the 'functrace' option has been enabled using 10661 the 'shopt' builtin. 10662 10663 * The Bash 'type' builtin is more extensive and gives more 10664 information about the names it finds (*note Bash Builtins::). 10665 10666 * The Bash 'umask' builtin permits a '-p' option to cause the output 10667 to be displayed in the form of a 'umask' command that may be reused 10668 as input (*note Bourne Shell Builtins::). 10669 10670 * Bash implements a 'csh'-like directory stack, and provides the 10671 'pushd', 'popd', and 'dirs' builtins to manipulate it (*note The 10672 Directory Stack::). Bash also makes the directory stack visible as 10673 the value of the 'DIRSTACK' shell variable. 10674 10675 * Bash interprets special backslash-escaped characters in the prompt 10676 strings when interactive (*note Controlling the Prompt::). 10677 10678 * The Bash restricted mode is more useful (*note The Restricted 10679 Shell::); the SVR4.2 shell restricted mode is too limited. 10680 10681 * The 'disown' builtin can remove a job from the internal shell job 10682 table (*note Job Control Builtins::) or suppress the sending of 10683 'SIGHUP' to a job when the shell exits as the result of a 'SIGHUP'. 10684 10685 * Bash includes a number of features to support a separate debugger 10686 for shell scripts. 10687 10688 * The SVR4.2 shell has two privilege-related builtins ('mldmode' and 10689 'priv') not present in Bash. 10690 10691 * Bash does not have the 'stop' or 'newgrp' builtins. 10692 10693 * Bash does not use the 'SHACCT' variable or perform shell 10694 accounting. 10695 10696 * The SVR4.2 'sh' uses a 'TIMEOUT' variable like Bash uses 'TMOUT'. 10697 10698More features unique to Bash may be found in *note Bash Features::. 10699 10700B.1 Implementation Differences From The SVR4.2 Shell 10701==================================================== 10702 10703Since Bash is a completely new implementation, it does not suffer from 10704many of the limitations of the SVR4.2 shell. For instance: 10705 10706 * Bash does not fork a subshell when redirecting into or out of a 10707 shell control structure such as an 'if' or 'while' statement. 10708 10709 * Bash does not allow unbalanced quotes. The SVR4.2 shell will 10710 silently insert a needed closing quote at 'EOF' under certain 10711 circumstances. This can be the cause of some hard-to-find errors. 10712 10713 * The SVR4.2 shell uses a baroque memory management scheme based on 10714 trapping 'SIGSEGV'. If the shell is started from a process with 10715 'SIGSEGV' blocked (e.g., by using the 'system()' C library function 10716 call), it misbehaves badly. 10717 10718 * In a questionable attempt at security, the SVR4.2 shell, when 10719 invoked without the '-p' option, will alter its real and effective 10720 UID and GID if they are less than some magic threshold value, 10721 commonly 100. This can lead to unexpected results. 10722 10723 * The SVR4.2 shell does not allow users to trap 'SIGSEGV', 'SIGALRM', 10724 or 'SIGCHLD'. 10725 10726 * The SVR4.2 shell does not allow the 'IFS', 'MAILCHECK', 'PATH', 10727 'PS1', or 'PS2' variables to be unset. 10728 10729 * The SVR4.2 shell treats '^' as the undocumented equivalent of '|'. 10730 10731 * Bash allows multiple option arguments when it is invoked ('-x -v'); 10732 the SVR4.2 shell allows only one option argument ('-xv'). In fact, 10733 some versions of the shell dump core if the second argument begins 10734 with a '-'. 10735 10736 * The SVR4.2 shell exits a script if any builtin fails; Bash exits a 10737 script only if one of the POSIX special builtins fails, and only 10738 for certain failures, as enumerated in the POSIX standard. 10739 10740 * The SVR4.2 shell behaves differently when invoked as 'jsh' (it 10741 turns on job control). 10742 10743 10744File: bash.info, Node: GNU Free Documentation License, Next: Indexes, Prev: Major Differences From The Bourne Shell, Up: Top 10745 10746Appendix C GNU Free Documentation License 10747***************************************** 10748 10749 Version 1.3, 3 November 2008 10750 10751 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. 10752 <http://fsf.org/> 10753 10754 Everyone is permitted to copy and distribute verbatim copies 10755 of this license document, but changing it is not allowed. 10756 10757 0. PREAMBLE 10758 10759 The purpose of this License is to make a manual, textbook, or other 10760 functional and useful document "free" in the sense of freedom: to 10761 assure everyone the effective freedom to copy and redistribute it, 10762 with or without modifying it, either commercially or 10763 noncommercially. Secondarily, this License preserves for the 10764 author and publisher a way to get credit for their work, while not 10765 being considered responsible for modifications made by others. 10766 10767 This License is a kind of "copyleft", which means that derivative 10768 works of the document must themselves be free in the same sense. 10769 It complements the GNU General Public License, which is a copyleft 10770 license designed for free software. 10771 10772 We have designed this License in order to use it for manuals for 10773 free software, because free software needs free documentation: a 10774 free program should come with manuals providing the same freedoms 10775 that the software does. But this License is not limited to 10776 software manuals; it can be used for any textual work, regardless 10777 of subject matter or whether it is published as a printed book. We 10778 recommend this License principally for works whose purpose is 10779 instruction or reference. 10780 10781 1. APPLICABILITY AND DEFINITIONS 10782 10783 This License applies to any manual or other work, in any medium, 10784 that contains a notice placed by the copyright holder saying it can 10785 be distributed under the terms of this License. Such a notice 10786 grants a world-wide, royalty-free license, unlimited in duration, 10787 to use that work under the conditions stated herein. The 10788 "Document", below, refers to any such manual or work. Any member 10789 of the public is a licensee, and is addressed as "you". You accept 10790 the license if you copy, modify or distribute the work in a way 10791 requiring permission under copyright law. 10792 10793 A "Modified Version" of the Document means any work containing the 10794 Document or a portion of it, either copied verbatim, or with 10795 modifications and/or translated into another language. 10796 10797 A "Secondary Section" is a named appendix or a front-matter section 10798 of the Document that deals exclusively with the relationship of the 10799 publishers or authors of the Document to the Document's overall 10800 subject (or to related matters) and contains nothing that could 10801 fall directly within that overall subject. (Thus, if the Document 10802 is in part a textbook of mathematics, a Secondary Section may not 10803 explain any mathematics.) The relationship could be a matter of 10804 historical connection with the subject or with related matters, or 10805 of legal, commercial, philosophical, ethical or political position 10806 regarding them. 10807 10808 The "Invariant Sections" are certain Secondary Sections whose 10809 titles are designated, as being those of Invariant Sections, in the 10810 notice that says that the Document is released under this License. 10811 If a section does not fit the above definition of Secondary then it 10812 is not allowed to be designated as Invariant. The Document may 10813 contain zero Invariant Sections. If the Document does not identify 10814 any Invariant Sections then there are none. 10815 10816 The "Cover Texts" are certain short passages of text that are 10817 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 10818 that says that the Document is released under this License. A 10819 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 10820 be at most 25 words. 10821 10822 A "Transparent" copy of the Document means a machine-readable copy, 10823 represented in a format whose specification is available to the 10824 general public, that is suitable for revising the document 10825 straightforwardly with generic text editors or (for images composed 10826 of pixels) generic paint programs or (for drawings) some widely 10827 available drawing editor, and that is suitable for input to text 10828 formatters or for automatic translation to a variety of formats 10829 suitable for input to text formatters. A copy made in an otherwise 10830 Transparent file format whose markup, or absence of markup, has 10831 been arranged to thwart or discourage subsequent modification by 10832 readers is not Transparent. An image format is not Transparent if 10833 used for any substantial amount of text. A copy that is not 10834 "Transparent" is called "Opaque". 10835 10836 Examples of suitable formats for Transparent copies include plain 10837 ASCII without markup, Texinfo input format, LaTeX input format, 10838 SGML or XML using a publicly available DTD, and standard-conforming 10839 simple HTML, PostScript or PDF designed for human modification. 10840 Examples of transparent image formats include PNG, XCF and JPG. 10841 Opaque formats include proprietary formats that can be read and 10842 edited only by proprietary word processors, SGML or XML for which 10843 the DTD and/or processing tools are not generally available, and 10844 the machine-generated HTML, PostScript or PDF produced by some word 10845 processors for output purposes only. 10846 10847 The "Title Page" means, for a printed book, the title page itself, 10848 plus such following pages as are needed to hold, legibly, the 10849 material this License requires to appear in the title page. For 10850 works in formats which do not have any title page as such, "Title 10851 Page" means the text near the most prominent appearance of the 10852 work's title, preceding the beginning of the body of the text. 10853 10854 The "publisher" means any person or entity that distributes copies 10855 of the Document to the public. 10856 10857 A section "Entitled XYZ" means a named subunit of the Document 10858 whose title either is precisely XYZ or contains XYZ in parentheses 10859 following text that translates XYZ in another language. (Here XYZ 10860 stands for a specific section name mentioned below, such as 10861 "Acknowledgements", "Dedications", "Endorsements", or "History".) 10862 To "Preserve the Title" of such a section when you modify the 10863 Document means that it remains a section "Entitled XYZ" according 10864 to this definition. 10865 10866 The Document may include Warranty Disclaimers next to the notice 10867 which states that this License applies to the Document. These 10868 Warranty Disclaimers are considered to be included by reference in 10869 this License, but only as regards disclaiming warranties: any other 10870 implication that these Warranty Disclaimers may have is void and 10871 has no effect on the meaning of this License. 10872 10873 2. VERBATIM COPYING 10874 10875 You may copy and distribute the Document in any medium, either 10876 commercially or noncommercially, provided that this License, the 10877 copyright notices, and the license notice saying this License 10878 applies to the Document are reproduced in all copies, and that you 10879 add no other conditions whatsoever to those of this License. You 10880 may not use technical measures to obstruct or control the reading 10881 or further copying of the copies you make or distribute. However, 10882 you may accept compensation in exchange for copies. If you 10883 distribute a large enough number of copies you must also follow the 10884 conditions in section 3. 10885 10886 You may also lend copies, under the same conditions stated above, 10887 and you may publicly display copies. 10888 10889 3. COPYING IN QUANTITY 10890 10891 If you publish printed copies (or copies in media that commonly 10892 have printed covers) of the Document, numbering more than 100, and 10893 the Document's license notice requires Cover Texts, you must 10894 enclose the copies in covers that carry, clearly and legibly, all 10895 these Cover Texts: Front-Cover Texts on the front cover, and 10896 Back-Cover Texts on the back cover. Both covers must also clearly 10897 and legibly identify you as the publisher of these copies. The 10898 front cover must present the full title with all words of the title 10899 equally prominent and visible. You may add other material on the 10900 covers in addition. Copying with changes limited to the covers, as 10901 long as they preserve the title of the Document and satisfy these 10902 conditions, can be treated as verbatim copying in other respects. 10903 10904 If the required texts for either cover are too voluminous to fit 10905 legibly, you should put the first ones listed (as many as fit 10906 reasonably) on the actual cover, and continue the rest onto 10907 adjacent pages. 10908 10909 If you publish or distribute Opaque copies of the Document 10910 numbering more than 100, you must either include a machine-readable 10911 Transparent copy along with each Opaque copy, or state in or with 10912 each Opaque copy a computer-network location from which the general 10913 network-using public has access to download using public-standard 10914 network protocols a complete Transparent copy of the Document, free 10915 of added material. If you use the latter option, you must take 10916 reasonably prudent steps, when you begin distribution of Opaque 10917 copies in quantity, to ensure that this Transparent copy will 10918 remain thus accessible at the stated location until at least one 10919 year after the last time you distribute an Opaque copy (directly or 10920 through your agents or retailers) of that edition to the public. 10921 10922 It is requested, but not required, that you contact the authors of 10923 the Document well before redistributing any large number of copies, 10924 to give them a chance to provide you with an updated version of the 10925 Document. 10926 10927 4. MODIFICATIONS 10928 10929 You may copy and distribute a Modified Version of the Document 10930 under the conditions of sections 2 and 3 above, provided that you 10931 release the Modified Version under precisely this License, with the 10932 Modified Version filling the role of the Document, thus licensing 10933 distribution and modification of the Modified Version to whoever 10934 possesses a copy of it. In addition, you must do these things in 10935 the Modified Version: 10936 10937 A. Use in the Title Page (and on the covers, if any) a title 10938 distinct from that of the Document, and from those of previous 10939 versions (which should, if there were any, be listed in the 10940 History section of the Document). You may use the same title 10941 as a previous version if the original publisher of that 10942 version gives permission. 10943 10944 B. List on the Title Page, as authors, one or more persons or 10945 entities responsible for authorship of the modifications in 10946 the Modified Version, together with at least five of the 10947 principal authors of the Document (all of its principal 10948 authors, if it has fewer than five), unless they release you 10949 from this requirement. 10950 10951 C. State on the Title page the name of the publisher of the 10952 Modified Version, as the publisher. 10953 10954 D. Preserve all the copyright notices of the Document. 10955 10956 E. Add an appropriate copyright notice for your modifications 10957 adjacent to the other copyright notices. 10958 10959 F. Include, immediately after the copyright notices, a license 10960 notice giving the public permission to use the Modified 10961 Version under the terms of this License, in the form shown in 10962 the Addendum below. 10963 10964 G. Preserve in that license notice the full lists of Invariant 10965 Sections and required Cover Texts given in the Document's 10966 license notice. 10967 10968 H. Include an unaltered copy of this License. 10969 10970 I. Preserve the section Entitled "History", Preserve its Title, 10971 and add to it an item stating at least the title, year, new 10972 authors, and publisher of the Modified Version as given on the 10973 Title Page. If there is no section Entitled "History" in the 10974 Document, create one stating the title, year, authors, and 10975 publisher of the Document as given on its Title Page, then add 10976 an item describing the Modified Version as stated in the 10977 previous sentence. 10978 10979 J. Preserve the network location, if any, given in the Document 10980 for public access to a Transparent copy of the Document, and 10981 likewise the network locations given in the Document for 10982 previous versions it was based on. These may be placed in the 10983 "History" section. You may omit a network location for a work 10984 that was published at least four years before the Document 10985 itself, or if the original publisher of the version it refers 10986 to gives permission. 10987 10988 K. For any section Entitled "Acknowledgements" or "Dedications", 10989 Preserve the Title of the section, and preserve in the section 10990 all the substance and tone of each of the contributor 10991 acknowledgements and/or dedications given therein. 10992 10993 L. Preserve all the Invariant Sections of the Document, unaltered 10994 in their text and in their titles. Section numbers or the 10995 equivalent are not considered part of the section titles. 10996 10997 M. Delete any section Entitled "Endorsements". Such a section 10998 may not be included in the Modified Version. 10999 11000 N. Do not retitle any existing section to be Entitled 11001 "Endorsements" or to conflict in title with any Invariant 11002 Section. 11003 11004 O. Preserve any Warranty Disclaimers. 11005 11006 If the Modified Version includes new front-matter sections or 11007 appendices that qualify as Secondary Sections and contain no 11008 material copied from the Document, you may at your option designate 11009 some or all of these sections as invariant. To do this, add their 11010 titles to the list of Invariant Sections in the Modified Version's 11011 license notice. These titles must be distinct from any other 11012 section titles. 11013 11014 You may add a section Entitled "Endorsements", provided it contains 11015 nothing but endorsements of your Modified Version by various 11016 parties--for example, statements of peer review or that the text 11017 has been approved by an organization as the authoritative 11018 definition of a standard. 11019 11020 You may add a passage of up to five words as a Front-Cover Text, 11021 and a passage of up to 25 words as a Back-Cover Text, to the end of 11022 the list of Cover Texts in the Modified Version. Only one passage 11023 of Front-Cover Text and one of Back-Cover Text may be added by (or 11024 through arrangements made by) any one entity. If the Document 11025 already includes a cover text for the same cover, previously added 11026 by you or by arrangement made by the same entity you are acting on 11027 behalf of, you may not add another; but you may replace the old 11028 one, on explicit permission from the previous publisher that added 11029 the old one. 11030 11031 The author(s) and publisher(s) of the Document do not by this 11032 License give permission to use their names for publicity for or to 11033 assert or imply endorsement of any Modified Version. 11034 11035 5. COMBINING DOCUMENTS 11036 11037 You may combine the Document with other documents released under 11038 this License, under the terms defined in section 4 above for 11039 modified versions, provided that you include in the combination all 11040 of the Invariant Sections of all of the original documents, 11041 unmodified, and list them all as Invariant Sections of your 11042 combined work in its license notice, and that you preserve all 11043 their Warranty Disclaimers. 11044 11045 The combined work need only contain one copy of this License, and 11046 multiple identical Invariant Sections may be replaced with a single 11047 copy. If there are multiple Invariant Sections with the same name 11048 but different contents, make the title of each such section unique 11049 by adding at the end of it, in parentheses, the name of the 11050 original author or publisher of that section if known, or else a 11051 unique number. Make the same adjustment to the section titles in 11052 the list of Invariant Sections in the license notice of the 11053 combined work. 11054 11055 In the combination, you must combine any sections Entitled 11056 "History" in the various original documents, forming one section 11057 Entitled "History"; likewise combine any sections Entitled 11058 "Acknowledgements", and any sections Entitled "Dedications". You 11059 must delete all sections Entitled "Endorsements." 11060 11061 6. COLLECTIONS OF DOCUMENTS 11062 11063 You may make a collection consisting of the Document and other 11064 documents released under this License, and replace the individual 11065 copies of this License in the various documents with a single copy 11066 that is included in the collection, provided that you follow the 11067 rules of this License for verbatim copying of each of the documents 11068 in all other respects. 11069 11070 You may extract a single document from such a collection, and 11071 distribute it individually under this License, provided you insert 11072 a copy of this License into the extracted document, and follow this 11073 License in all other respects regarding verbatim copying of that 11074 document. 11075 11076 7. AGGREGATION WITH INDEPENDENT WORKS 11077 11078 A compilation of the Document or its derivatives with other 11079 separate and independent documents or works, in or on a volume of a 11080 storage or distribution medium, is called an "aggregate" if the 11081 copyright resulting from the compilation is not used to limit the 11082 legal rights of the compilation's users beyond what the individual 11083 works permit. When the Document is included in an aggregate, this 11084 License does not apply to the other works in the aggregate which 11085 are not themselves derivative works of the Document. 11086 11087 If the Cover Text requirement of section 3 is applicable to these 11088 copies of the Document, then if the Document is less than one half 11089 of the entire aggregate, the Document's Cover Texts may be placed 11090 on covers that bracket the Document within the aggregate, or the 11091 electronic equivalent of covers if the Document is in electronic 11092 form. Otherwise they must appear on printed covers that bracket 11093 the whole aggregate. 11094 11095 8. TRANSLATION 11096 11097 Translation is considered a kind of modification, so you may 11098 distribute translations of the Document under the terms of section 11099 4. Replacing Invariant Sections with translations requires special 11100 permission from their copyright holders, but you may include 11101 translations of some or all Invariant Sections in addition to the 11102 original versions of these Invariant Sections. You may include a 11103 translation of this License, and all the license notices in the 11104 Document, and any Warranty Disclaimers, provided that you also 11105 include the original English version of this License and the 11106 original versions of those notices and disclaimers. In case of a 11107 disagreement between the translation and the original version of 11108 this License or a notice or disclaimer, the original version will 11109 prevail. 11110 11111 If a section in the Document is Entitled "Acknowledgements", 11112 "Dedications", or "History", the requirement (section 4) to 11113 Preserve its Title (section 1) will typically require changing the 11114 actual title. 11115 11116 9. TERMINATION 11117 11118 You may not copy, modify, sublicense, or distribute the Document 11119 except as expressly provided under this License. Any attempt 11120 otherwise to copy, modify, sublicense, or distribute it is void, 11121 and will automatically terminate your rights under this License. 11122 11123 However, if you cease all violation of this License, then your 11124 license from a particular copyright holder is reinstated (a) 11125 provisionally, unless and until the copyright holder explicitly and 11126 finally terminates your license, and (b) permanently, if the 11127 copyright holder fails to notify you of the violation by some 11128 reasonable means prior to 60 days after the cessation. 11129 11130 Moreover, your license from a particular copyright holder is 11131 reinstated permanently if the copyright holder notifies you of the 11132 violation by some reasonable means, this is the first time you have 11133 received notice of violation of this License (for any work) from 11134 that copyright holder, and you cure the violation prior to 30 days 11135 after your receipt of the notice. 11136 11137 Termination of your rights under this section does not terminate 11138 the licenses of parties who have received copies or rights from you 11139 under this License. If your rights have been terminated and not 11140 permanently reinstated, receipt of a copy of some or all of the 11141 same material does not give you any rights to use it. 11142 11143 10. FUTURE REVISIONS OF THIS LICENSE 11144 11145 The Free Software Foundation may publish new, revised versions of 11146 the GNU Free Documentation License from time to time. Such new 11147 versions will be similar in spirit to the present version, but may 11148 differ in detail to address new problems or concerns. See 11149 <http://www.gnu.org/copyleft/>. 11150 11151 Each version of the License is given a distinguishing version 11152 number. If the Document specifies that a particular numbered 11153 version of this License "or any later version" applies to it, you 11154 have the option of following the terms and conditions either of 11155 that specified version or of any later version that has been 11156 published (not as a draft) by the Free Software Foundation. If the 11157 Document does not specify a version number of this License, you may 11158 choose any version ever published (not as a draft) by the Free 11159 Software Foundation. If the Document specifies that a proxy can 11160 decide which future versions of this License can be used, that 11161 proxy's public statement of acceptance of a version permanently 11162 authorizes you to choose that version for the Document. 11163 11164 11. RELICENSING 11165 11166 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any 11167 World Wide Web server that publishes copyrightable works and also 11168 provides prominent facilities for anybody to edit those works. A 11169 public wiki that anybody can edit is an example of such a server. 11170 A "Massive Multiauthor Collaboration" (or "MMC") contained in the 11171 site means any set of copyrightable works thus published on the MMC 11172 site. 11173 11174 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 11175 license published by Creative Commons Corporation, a not-for-profit 11176 corporation with a principal place of business in San Francisco, 11177 California, as well as future copyleft versions of that license 11178 published by that same organization. 11179 11180 "Incorporate" means to publish or republish a Document, in whole or 11181 in part, as part of another Document. 11182 11183 An MMC is "eligible for relicensing" if it is licensed under this 11184 License, and if all works that were first published under this 11185 License somewhere other than this MMC, and subsequently 11186 incorporated in whole or in part into the MMC, (1) had no cover 11187 texts or invariant sections, and (2) were thus incorporated prior 11188 to November 1, 2008. 11189 11190 The operator of an MMC Site may republish an MMC contained in the 11191 site under CC-BY-SA on the same site at any time before August 1, 11192 2009, provided the MMC is eligible for relicensing. 11193 11194ADDENDUM: How to use this License for your documents 11195==================================================== 11196 11197To use this License in a document you have written, include a copy of 11198the License in the document and put the following copyright and license 11199notices just after the title page: 11200 11201 Copyright (C) YEAR YOUR NAME. 11202 Permission is granted to copy, distribute and/or modify this document 11203 under the terms of the GNU Free Documentation License, Version 1.3 11204 or any later version published by the Free Software Foundation; 11205 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 11206 Texts. A copy of the license is included in the section entitled ``GNU 11207 Free Documentation License''. 11208 11209 If you have Invariant Sections, Front-Cover Texts and Back-Cover 11210Texts, replace the "with...Texts." line with this: 11211 11212 with the Invariant Sections being LIST THEIR TITLES, with 11213 the Front-Cover Texts being LIST, and with the Back-Cover Texts 11214 being LIST. 11215 11216 If you have Invariant Sections without Cover Texts, or some other 11217combination of the three, merge those two alternatives to suit the 11218situation. 11219 11220 If your document contains nontrivial examples of program code, we 11221recommend releasing these examples in parallel under your choice of free 11222software license, such as the GNU General Public License, to permit 11223their use in free software. 11224 11225 11226File: bash.info, Node: Indexes, Prev: GNU Free Documentation License, Up: Top 11227 11228Appendix D Indexes 11229****************** 11230 11231* Menu: 11232 11233* Builtin Index:: Index of Bash builtin commands. 11234* Reserved Word Index:: Index of Bash reserved words. 11235* Variable Index:: Quick reference helps you find the 11236 variable you want. 11237* Function Index:: Index of bindable Readline functions. 11238* Concept Index:: General index for concepts described in 11239 this manual. 11240 11241 11242File: bash.info, Node: Builtin Index, Next: Reserved Word Index, Up: Indexes 11243 11244D.1 Index of Shell Builtin Commands 11245=================================== 11246 11247�[index�] 11248* Menu: 11249 11250* .: Bourne Shell Builtins. 11251 (line 17) 11252* :: Bourne Shell Builtins. 11253 (line 11) 11254* [: Bourne Shell Builtins. 11255 (line 270) 11256* alias: Bash Builtins. (line 11) 11257* bg: Job Control Builtins. 11258 (line 7) 11259* bind: Bash Builtins. (line 21) 11260* break: Bourne Shell Builtins. 11261 (line 36) 11262* builtin: Bash Builtins. (line 104) 11263* caller: Bash Builtins. (line 113) 11264* cd: Bourne Shell Builtins. 11265 (line 44) 11266* command: Bash Builtins. (line 130) 11267* compgen: Programmable Completion Builtins. 11268 (line 12) 11269* complete: Programmable Completion Builtins. 11270 (line 30) 11271* compopt: Programmable Completion Builtins. 11272 (line 237) 11273* continue: Bourne Shell Builtins. 11274 (line 85) 11275* declare: Bash Builtins. (line 150) 11276* dirs: Directory Stack Builtins. 11277 (line 7) 11278* disown: Job Control Builtins. 11279 (line 101) 11280* echo: Bash Builtins. (line 253) 11281* enable: Bash Builtins. (line 302) 11282* eval: Bourne Shell Builtins. 11283 (line 94) 11284* exec: Bourne Shell Builtins. 11285 (line 102) 11286* exit: Bourne Shell Builtins. 11287 (line 120) 11288* export: Bourne Shell Builtins. 11289 (line 127) 11290* fc: Bash History Builtins. 11291 (line 10) 11292* fg: Job Control Builtins. 11293 (line 17) 11294* getopts: Bourne Shell Builtins. 11295 (line 143) 11296* hash: Bourne Shell Builtins. 11297 (line 187) 11298* help: Bash Builtins. (line 331) 11299* history: Bash History Builtins. 11300 (line 46) 11301* jobs: Job Control Builtins. 11302 (line 27) 11303* kill: Job Control Builtins. 11304 (line 58) 11305* let: Bash Builtins. (line 350) 11306* local: Bash Builtins. (line 358) 11307* logout: Bash Builtins. (line 374) 11308* mapfile: Bash Builtins. (line 379) 11309* popd: Directory Stack Builtins. 11310 (line 35) 11311* printf: Bash Builtins. (line 425) 11312* pushd: Directory Stack Builtins. 11313 (line 53) 11314* pwd: Bourne Shell Builtins. 11315 (line 207) 11316* read: Bash Builtins. (line 474) 11317* readarray: Bash Builtins. (line 570) 11318* readonly: Bourne Shell Builtins. 11319 (line 217) 11320* return: Bourne Shell Builtins. 11321 (line 236) 11322* set: The Set Builtin. (line 11) 11323* shift: Bourne Shell Builtins. 11324 (line 257) 11325* shopt: The Shopt Builtin. (line 9) 11326* source: Bash Builtins. (line 579) 11327* suspend: Job Control Builtins. 11328 (line 113) 11329* test: Bourne Shell Builtins. 11330 (line 270) 11331* times: Bourne Shell Builtins. 11332 (line 349) 11333* trap: Bourne Shell Builtins. 11334 (line 355) 11335* type: Bash Builtins. (line 584) 11336* typeset: Bash Builtins. (line 616) 11337* ulimit: Bash Builtins. (line 622) 11338* umask: Bourne Shell Builtins. 11339 (line 404) 11340* unalias: Bash Builtins. (line 728) 11341* unset: Bourne Shell Builtins. 11342 (line 422) 11343* wait: Job Control Builtins. 11344 (line 76) 11345 11346 11347File: bash.info, Node: Reserved Word Index, Next: Variable Index, Prev: Builtin Index, Up: Indexes 11348 11349D.2 Index of Shell Reserved Words 11350================================= 11351 11352�[index�] 11353* Menu: 11354 11355* !: Pipelines. (line 9) 11356* [[: Conditional Constructs. 11357 (line 125) 11358* ]]: Conditional Constructs. 11359 (line 125) 11360* {: Command Grouping. (line 21) 11361* }: Command Grouping. (line 21) 11362* case: Conditional Constructs. 11363 (line 28) 11364* do: Looping Constructs. (line 12) 11365* done: Looping Constructs. (line 12) 11366* elif: Conditional Constructs. 11367 (line 7) 11368* else: Conditional Constructs. 11369 (line 7) 11370* esac: Conditional Constructs. 11371 (line 28) 11372* fi: Conditional Constructs. 11373 (line 7) 11374* for: Looping Constructs. (line 32) 11375* function: Shell Functions. (line 13) 11376* if: Conditional Constructs. 11377 (line 7) 11378* in: Conditional Constructs. 11379 (line 28) 11380* select: Conditional Constructs. 11381 (line 83) 11382* then: Conditional Constructs. 11383 (line 7) 11384* time: Pipelines. (line 9) 11385* until: Looping Constructs. (line 12) 11386* while: Looping Constructs. (line 22) 11387 11388 11389File: bash.info, Node: Variable Index, Next: Function Index, Prev: Reserved Word Index, Up: Indexes 11390 11391D.3 Parameter and Variable Index 11392================================ 11393 11394�[index�] 11395* Menu: 11396 11397* !: Special Parameters. (line 56) 11398* #: Special Parameters. (line 39) 11399* $: Special Parameters. (line 51) 11400* $!: Special Parameters. (line 57) 11401* $#: Special Parameters. (line 40) 11402* $$: Special Parameters. (line 52) 11403* $*: Special Parameters. (line 10) 11404* $-: Special Parameters. (line 47) 11405* $0: Special Parameters. (line 62) 11406* $?: Special Parameters. (line 43) 11407* $@: Special Parameters. (line 23) 11408* $_: Bash Variables. (line 14) 11409* *: Special Parameters. (line 9) 11410* -: Special Parameters. (line 46) 11411* 0: Special Parameters. (line 61) 11412* ?: Special Parameters. (line 42) 11413* @: Special Parameters. (line 22) 11414* _: Bash Variables. (line 13) 11415* auto_resume: Job Control Variables. 11416 (line 6) 11417* BASH: Bash Variables. (line 23) 11418* BASHOPTS: Bash Variables. (line 26) 11419* BASHPID: Bash Variables. (line 35) 11420* BASH_ALIASES: Bash Variables. (line 42) 11421* BASH_ARGC: Bash Variables. (line 51) 11422* BASH_ARGV: Bash Variables. (line 64) 11423* BASH_ARGV0: Bash Variables. (line 76) 11424* BASH_CMDS: Bash Variables. (line 84) 11425* BASH_COMMAND: Bash Variables. (line 93) 11426* BASH_COMPAT: Bash Variables. (line 100) 11427* BASH_ENV: Bash Variables. (line 116) 11428* BASH_EXECUTION_STRING: Bash Variables. (line 122) 11429* BASH_LINENO: Bash Variables. (line 125) 11430* BASH_LOADABLES_PATH: Bash Variables. (line 133) 11431* BASH_REMATCH: Bash Variables. (line 137) 11432* BASH_SOURCE: Bash Variables. (line 145) 11433* BASH_SUBSHELL: Bash Variables. (line 152) 11434* BASH_VERSINFO: Bash Variables. (line 158) 11435* BASH_VERSION: Bash Variables. (line 181) 11436* BASH_XTRACEFD: Bash Variables. (line 184) 11437* bell-style: Readline Init File Syntax. 11438 (line 38) 11439* bind-tty-special-chars: Readline Init File Syntax. 11440 (line 45) 11441* blink-matching-paren: Readline Init File Syntax. 11442 (line 50) 11443* CDPATH: Bourne Shell Variables. 11444 (line 9) 11445* CHILD_MAX: Bash Variables. (line 195) 11446* colored-completion-prefix: Readline Init File Syntax. 11447 (line 55) 11448* colored-stats: Readline Init File Syntax. 11449 (line 62) 11450* COLUMNS: Bash Variables. (line 202) 11451* comment-begin: Readline Init File Syntax. 11452 (line 68) 11453* completion-display-width: Readline Init File Syntax. 11454 (line 73) 11455* completion-ignore-case: Readline Init File Syntax. 11456 (line 80) 11457* completion-map-case: Readline Init File Syntax. 11458 (line 85) 11459* completion-prefix-display-length: Readline Init File Syntax. 11460 (line 91) 11461* completion-query-items: Readline Init File Syntax. 11462 (line 98) 11463* COMPREPLY: Bash Variables. (line 254) 11464* COMP_CWORD: Bash Variables. (line 208) 11465* COMP_KEY: Bash Variables. (line 237) 11466* COMP_LINE: Bash Variables. (line 214) 11467* COMP_POINT: Bash Variables. (line 219) 11468* COMP_TYPE: Bash Variables. (line 227) 11469* COMP_WORDBREAKS: Bash Variables. (line 241) 11470* COMP_WORDS: Bash Variables. (line 247) 11471* convert-meta: Readline Init File Syntax. 11472 (line 108) 11473* COPROC: Bash Variables. (line 260) 11474* DIRSTACK: Bash Variables. (line 264) 11475* disable-completion: Readline Init File Syntax. 11476 (line 116) 11477* echo-control-characters: Readline Init File Syntax. 11478 (line 121) 11479* editing-mode: Readline Init File Syntax. 11480 (line 126) 11481* EMACS: Bash Variables. (line 274) 11482* emacs-mode-string: Readline Init File Syntax. 11483 (line 132) 11484* enable-bracketed-paste: Readline Init File Syntax. 11485 (line 142) 11486* enable-keypad: Readline Init File Syntax. 11487 (line 150) 11488* ENV: Bash Variables. (line 279) 11489* EPOCHREALTIME: Bash Variables. (line 284) 11490* EPOCHSECONDS: Bash Variables. (line 292) 11491* EUID: Bash Variables. (line 299) 11492* EXECIGNORE: Bash Variables. (line 303) 11493* expand-tilde: Readline Init File Syntax. 11494 (line 161) 11495* FCEDIT: Bash Variables. (line 316) 11496* FIGNORE: Bash Variables. (line 320) 11497* FUNCNAME: Bash Variables. (line 326) 11498* FUNCNEST: Bash Variables. (line 343) 11499* GLOBIGNORE: Bash Variables. (line 348) 11500* GROUPS: Bash Variables. (line 355) 11501* histchars: Bash Variables. (line 361) 11502* HISTCMD: Bash Variables. (line 376) 11503* HISTCONTROL: Bash Variables. (line 382) 11504* HISTFILE: Bash Variables. (line 398) 11505* HISTFILESIZE: Bash Variables. (line 402) 11506* HISTIGNORE: Bash Variables. (line 413) 11507* history-preserve-point: Readline Init File Syntax. 11508 (line 165) 11509* history-size: Readline Init File Syntax. 11510 (line 171) 11511* HISTSIZE: Bash Variables. (line 433) 11512* HISTTIMEFORMAT: Bash Variables. (line 440) 11513* HOME: Bourne Shell Variables. 11514 (line 13) 11515* horizontal-scroll-mode: Readline Init File Syntax. 11516 (line 180) 11517* HOSTFILE: Bash Variables. (line 448) 11518* HOSTNAME: Bash Variables. (line 459) 11519* HOSTTYPE: Bash Variables. (line 462) 11520* IFS: Bourne Shell Variables. 11521 (line 18) 11522* IGNOREEOF: Bash Variables. (line 465) 11523* input-meta: Readline Init File Syntax. 11524 (line 189) 11525* INPUTRC: Bash Variables. (line 475) 11526* INSIDE_EMACS: Bash Variables. (line 479) 11527* isearch-terminators: Readline Init File Syntax. 11528 (line 197) 11529* keymap: Readline Init File Syntax. 11530 (line 204) 11531* LANG: Bash Variables. (line 485) 11532* LC_ALL: Bash Variables. (line 489) 11533* LC_COLLATE: Bash Variables. (line 493) 11534* LC_CTYPE: Bash Variables. (line 500) 11535* LC_MESSAGES: Locale Translation. (line 15) 11536* LC_MESSAGES <1>: Bash Variables. (line 505) 11537* LC_NUMERIC: Bash Variables. (line 509) 11538* LC_TIME: Bash Variables. (line 513) 11539* LINENO: Bash Variables. (line 517) 11540* LINES: Bash Variables. (line 522) 11541* MACHTYPE: Bash Variables. (line 528) 11542* MAIL: Bourne Shell Variables. 11543 (line 22) 11544* MAILCHECK: Bash Variables. (line 532) 11545* MAILPATH: Bourne Shell Variables. 11546 (line 27) 11547* MAPFILE: Bash Variables. (line 540) 11548* mark-modified-lines: Readline Init File Syntax. 11549 (line 234) 11550* mark-symlinked-directories: Readline Init File Syntax. 11551 (line 239) 11552* match-hidden-files: Readline Init File Syntax. 11553 (line 244) 11554* menu-complete-display-prefix: Readline Init File Syntax. 11555 (line 251) 11556* meta-flag: Readline Init File Syntax. 11557 (line 189) 11558* OLDPWD: Bash Variables. (line 544) 11559* OPTARG: Bourne Shell Variables. 11560 (line 34) 11561* OPTERR: Bash Variables. (line 547) 11562* OPTIND: Bourne Shell Variables. 11563 (line 38) 11564* OSTYPE: Bash Variables. (line 551) 11565* output-meta: Readline Init File Syntax. 11566 (line 256) 11567* page-completions: Readline Init File Syntax. 11568 (line 262) 11569* PATH: Bourne Shell Variables. 11570 (line 42) 11571* PIPESTATUS: Bash Variables. (line 554) 11572* POSIXLY_CORRECT: Bash Variables. (line 559) 11573* PPID: Bash Variables. (line 569) 11574* PROMPT_COMMAND: Bash Variables. (line 573) 11575* PROMPT_DIRTRIM: Bash Variables. (line 579) 11576* PS0: Bash Variables. (line 585) 11577* PS1: Bourne Shell Variables. 11578 (line 48) 11579* PS2: Bourne Shell Variables. 11580 (line 53) 11581* PS3: Bash Variables. (line 590) 11582* PS4: Bash Variables. (line 595) 11583* PWD: Bash Variables. (line 603) 11584* RANDOM: Bash Variables. (line 606) 11585* READLINE_LINE: Bash Variables. (line 612) 11586* READLINE_MARK: Bash Variables. (line 616) 11587* READLINE_POINT: Bash Variables. (line 622) 11588* REPLY: Bash Variables. (line 626) 11589* revert-all-at-newline: Readline Init File Syntax. 11590 (line 272) 11591* SECONDS: Bash Variables. (line 629) 11592* SHELL: Bash Variables. (line 638) 11593* SHELLOPTS: Bash Variables. (line 643) 11594* SHLVL: Bash Variables. (line 652) 11595* show-all-if-ambiguous: Readline Init File Syntax. 11596 (line 278) 11597* show-all-if-unmodified: Readline Init File Syntax. 11598 (line 284) 11599* show-mode-in-prompt: Readline Init File Syntax. 11600 (line 293) 11601* skip-completed-text: Readline Init File Syntax. 11602 (line 299) 11603* SRANDOM: Bash Variables. (line 657) 11604* TEXTDOMAIN: Locale Translation. (line 15) 11605* TEXTDOMAINDIR: Locale Translation. (line 15) 11606* TIMEFORMAT: Bash Variables. (line 666) 11607* TMOUT: Bash Variables. (line 704) 11608* TMPDIR: Bash Variables. (line 716) 11609* UID: Bash Variables. (line 720) 11610* vi-cmd-mode-string: Readline Init File Syntax. 11611 (line 312) 11612* vi-ins-mode-string: Readline Init File Syntax. 11613 (line 323) 11614* visible-stats: Readline Init File Syntax. 11615 (line 334) 11616 11617 11618File: bash.info, Node: Function Index, Next: Concept Index, Prev: Variable Index, Up: Indexes 11619 11620D.4 Function Index 11621================== 11622 11623�[index�] 11624* Menu: 11625 11626* abort (C-g): Miscellaneous Commands. 11627 (line 10) 11628* accept-line (Newline or Return): Commands For History. 11629 (line 6) 11630* alias-expand-line (): Miscellaneous Commands. 11631 (line 125) 11632* backward-char (C-b): Commands For Moving. (line 15) 11633* backward-delete-char (Rubout): Commands For Text. (line 17) 11634* backward-kill-line (C-x Rubout): Commands For Killing. 11635 (line 11) 11636* backward-kill-word (M-<DEL>): Commands For Killing. 11637 (line 28) 11638* backward-word (M-b): Commands For Moving. (line 22) 11639* beginning-of-history (M-<): Commands For History. 11640 (line 20) 11641* beginning-of-line (C-a): Commands For Moving. (line 6) 11642* bracketed-paste-begin (): Commands For Text. (line 33) 11643* call-last-kbd-macro (C-x e): Keyboard Macros. (line 13) 11644* capitalize-word (M-c): Commands For Text. (line 66) 11645* character-search (C-]): Miscellaneous Commands. 11646 (line 42) 11647* character-search-backward (M-C-]): Miscellaneous Commands. 11648 (line 47) 11649* clear-display (M-C-l): Commands For Moving. (line 48) 11650* clear-screen (C-l): Commands For Moving. (line 53) 11651* complete (<TAB>): Commands For Completion. 11652 (line 6) 11653* complete-command (M-!): Commands For Completion. 11654 (line 80) 11655* complete-filename (M-/): Commands For Completion. 11656 (line 49) 11657* complete-hostname (M-@): Commands For Completion. 11658 (line 72) 11659* complete-into-braces (M-{): Commands For Completion. 11660 (line 100) 11661* complete-username (M-~): Commands For Completion. 11662 (line 56) 11663* complete-variable (M-$): Commands For Completion. 11664 (line 64) 11665* copy-backward-word (): Commands For Killing. 11666 (line 69) 11667* copy-forward-word (): Commands For Killing. 11668 (line 74) 11669* copy-region-as-kill (): Commands For Killing. 11670 (line 65) 11671* dabbrev-expand (): Commands For Completion. 11672 (line 95) 11673* delete-char (C-d): Commands For Text. (line 12) 11674* delete-char-or-list (): Commands For Completion. 11675 (line 43) 11676* delete-horizontal-space (): Commands For Killing. 11677 (line 57) 11678* digit-argument (M-0, M-1, ... M--): Numeric Arguments. (line 6) 11679* display-shell-version (C-x C-v): Miscellaneous Commands. 11680 (line 110) 11681* do-lowercase-version (M-A, M-B, M-X, ...): Miscellaneous Commands. 11682 (line 14) 11683* downcase-word (M-l): Commands For Text. (line 62) 11684* dump-functions (): Miscellaneous Commands. 11685 (line 74) 11686* dump-macros (): Miscellaneous Commands. 11687 (line 86) 11688* dump-variables (): Miscellaneous Commands. 11689 (line 80) 11690* dynamic-complete-history (M-<TAB>): Commands For Completion. 11691 (line 90) 11692* edit-and-execute-command (C-x C-e): Miscellaneous Commands. 11693 (line 134) 11694* end-kbd-macro (C-x )): Keyboard Macros. (line 9) 11695* end-of-file (usually C-d): Commands For Text. (line 6) 11696* end-of-history (M->): Commands For History. 11697 (line 23) 11698* end-of-line (C-e): Commands For Moving. (line 9) 11699* exchange-point-and-mark (C-x C-x): Miscellaneous Commands. 11700 (line 37) 11701* forward-backward-delete-char (): Commands For Text. (line 21) 11702* forward-char (C-f): Commands For Moving. (line 12) 11703* forward-search-history (C-s): Commands For History. 11704 (line 33) 11705* forward-word (M-f): Commands For Moving. (line 18) 11706* glob-complete-word (M-g): Miscellaneous Commands. 11707 (line 92) 11708* glob-expand-word (C-x *): Miscellaneous Commands. 11709 (line 98) 11710* glob-list-expansions (C-x g): Miscellaneous Commands. 11711 (line 104) 11712* history-and-alias-expand-line (): Miscellaneous Commands. 11713 (line 128) 11714* history-expand-line (M-^): Miscellaneous Commands. 11715 (line 118) 11716* history-search-backward (): Commands For History. 11717 (line 57) 11718* history-search-forward (): Commands For History. 11719 (line 51) 11720* history-substring-search-backward (): Commands For History. 11721 (line 69) 11722* history-substring-search-forward (): Commands For History. 11723 (line 63) 11724* insert-comment (M-#): Miscellaneous Commands. 11725 (line 61) 11726* insert-completions (M-*): Commands For Completion. 11727 (line 22) 11728* insert-last-argument (M-. or M-_): Miscellaneous Commands. 11729 (line 131) 11730* kill-line (C-k): Commands For Killing. 11731 (line 6) 11732* kill-region (): Commands For Killing. 11733 (line 61) 11734* kill-whole-line (): Commands For Killing. 11735 (line 19) 11736* kill-word (M-d): Commands For Killing. 11737 (line 23) 11738* magic-space (): Miscellaneous Commands. 11739 (line 121) 11740* menu-complete (): Commands For Completion. 11741 (line 26) 11742* menu-complete-backward (): Commands For Completion. 11743 (line 38) 11744* next-history (C-n): Commands For History. 11745 (line 17) 11746* next-screen-line (): Commands For Moving. (line 41) 11747* non-incremental-forward-search-history (M-n): Commands For History. 11748 (line 45) 11749* non-incremental-reverse-search-history (M-p): Commands For History. 11750 (line 39) 11751* operate-and-get-next (C-o): Commands For History. 11752 (line 96) 11753* overwrite-mode (): Commands For Text. (line 70) 11754* possible-command-completions (C-x !): Commands For Completion. 11755 (line 86) 11756* possible-completions (M-?): Commands For Completion. 11757 (line 15) 11758* possible-filename-completions (C-x /): Commands For Completion. 11759 (line 52) 11760* possible-hostname-completions (C-x @): Commands For Completion. 11761 (line 76) 11762* possible-username-completions (C-x ~): Commands For Completion. 11763 (line 60) 11764* possible-variable-completions (C-x $): Commands For Completion. 11765 (line 68) 11766* prefix-meta (<ESC>): Miscellaneous Commands. 11767 (line 19) 11768* previous-history (C-p): Commands For History. 11769 (line 13) 11770* previous-screen-line (): Commands For Moving. (line 34) 11771* print-last-kbd-macro (): Keyboard Macros. (line 17) 11772* quoted-insert (C-q or C-v): Commands For Text. (line 26) 11773* re-read-init-file (C-x C-r): Miscellaneous Commands. 11774 (line 6) 11775* redraw-current-line (): Commands For Moving. (line 57) 11776* reverse-search-history (C-r): Commands For History. 11777 (line 27) 11778* revert-line (M-r): Miscellaneous Commands. 11779 (line 26) 11780* self-insert (a, b, A, 1, !, ...): Commands For Text. (line 30) 11781* set-mark (C-@): Miscellaneous Commands. 11782 (line 33) 11783* shell-backward-kill-word (): Commands For Killing. 11784 (line 37) 11785* shell-backward-word (M-C-b): Commands For Moving. (line 30) 11786* shell-expand-line (M-C-e): Miscellaneous Commands. 11787 (line 113) 11788* shell-forward-word (M-C-f): Commands For Moving. (line 26) 11789* shell-kill-word (M-C-d): Commands For Killing. 11790 (line 32) 11791* shell-transpose-words (M-C-t): Commands For Killing. 11792 (line 41) 11793* skip-csi-sequence (): Miscellaneous Commands. 11794 (line 52) 11795* start-kbd-macro (C-x (): Keyboard Macros. (line 6) 11796* tilde-expand (M-&): Miscellaneous Commands. 11797 (line 30) 11798* transpose-chars (C-t): Commands For Text. (line 47) 11799* transpose-words (M-t): Commands For Text. (line 53) 11800* undo (C-_ or C-x C-u): Miscellaneous Commands. 11801 (line 23) 11802* universal-argument (): Numeric Arguments. (line 10) 11803* unix-filename-rubout (): Commands For Killing. 11804 (line 52) 11805* unix-line-discard (C-u): Commands For Killing. 11806 (line 16) 11807* unix-word-rubout (C-w): Commands For Killing. 11808 (line 48) 11809* upcase-word (M-u): Commands For Text. (line 58) 11810* yank (C-y): Commands For Killing. 11811 (line 79) 11812* yank-last-arg (M-. or M-_): Commands For History. 11813 (line 84) 11814* yank-nth-arg (M-C-y): Commands For History. 11815 (line 75) 11816* yank-pop (M-y): Commands For Killing. 11817 (line 82) 11818 11819 11820File: bash.info, Node: Concept Index, Prev: Function Index, Up: Indexes 11821 11822D.5 Concept Index 11823================= 11824 11825�[index�] 11826* Menu: 11827 11828* alias expansion: Aliases. (line 6) 11829* arithmetic evaluation: Shell Arithmetic. (line 6) 11830* arithmetic expansion: Arithmetic Expansion. 11831 (line 6) 11832* arithmetic, shell: Shell Arithmetic. (line 6) 11833* arrays: Arrays. (line 6) 11834* background: Job Control Basics. (line 6) 11835* Bash configuration: Basic Installation. (line 6) 11836* Bash installation: Basic Installation. (line 6) 11837* Bourne shell: Basic Shell Features. 11838 (line 6) 11839* brace expansion: Brace Expansion. (line 6) 11840* builtin: Definitions. (line 17) 11841* command editing: Readline Bare Essentials. 11842 (line 6) 11843* command execution: Command Search and Execution. 11844 (line 6) 11845* command expansion: Simple Command Expansion. 11846 (line 6) 11847* command history: Bash History Facilities. 11848 (line 6) 11849* command search: Command Search and Execution. 11850 (line 6) 11851* command substitution: Command Substitution. 11852 (line 6) 11853* command timing: Pipelines. (line 9) 11854* commands, compound: Compound Commands. (line 6) 11855* commands, conditional: Conditional Constructs. 11856 (line 6) 11857* commands, grouping: Command Grouping. (line 6) 11858* commands, lists: Lists. (line 6) 11859* commands, looping: Looping Constructs. (line 6) 11860* commands, pipelines: Pipelines. (line 6) 11861* commands, shell: Shell Commands. (line 6) 11862* commands, simple: Simple Commands. (line 6) 11863* comments, shell: Comments. (line 6) 11864* Compatibility Level: Shell Compatibility Mode. 11865 (line 6) 11866* Compatibility Mode: Shell Compatibility Mode. 11867 (line 6) 11868* completion builtins: Programmable Completion Builtins. 11869 (line 6) 11870* configuration: Basic Installation. (line 6) 11871* control operator: Definitions. (line 21) 11872* coprocess: Coprocesses. (line 6) 11873* directory stack: The Directory Stack. (line 6) 11874* editing command lines: Readline Bare Essentials. 11875 (line 6) 11876* environment: Environment. (line 6) 11877* evaluation, arithmetic: Shell Arithmetic. (line 6) 11878* event designators: Event Designators. (line 6) 11879* execution environment: Command Execution Environment. 11880 (line 6) 11881* exit status: Definitions. (line 26) 11882* exit status <1>: Exit Status. (line 6) 11883* expansion: Shell Expansions. (line 6) 11884* expansion, arithmetic: Arithmetic Expansion. 11885 (line 6) 11886* expansion, brace: Brace Expansion. (line 6) 11887* expansion, filename: Filename Expansion. (line 9) 11888* expansion, parameter: Shell Parameter Expansion. 11889 (line 6) 11890* expansion, pathname: Filename Expansion. (line 9) 11891* expansion, tilde: Tilde Expansion. (line 6) 11892* expressions, arithmetic: Shell Arithmetic. (line 6) 11893* expressions, conditional: Bash Conditional Expressions. 11894 (line 6) 11895* field: Definitions. (line 30) 11896* filename: Definitions. (line 35) 11897* filename expansion: Filename Expansion. (line 9) 11898* foreground: Job Control Basics. (line 6) 11899* functions, shell: Shell Functions. (line 6) 11900* history builtins: Bash History Builtins. 11901 (line 6) 11902* history events: Event Designators. (line 8) 11903* history expansion: History Interaction. (line 6) 11904* history list: Bash History Facilities. 11905 (line 6) 11906* History, how to use: A Programmable Completion Example. 11907 (line 113) 11908* identifier: Definitions. (line 51) 11909* initialization file, readline: Readline Init File. (line 6) 11910* installation: Basic Installation. (line 6) 11911* interaction, readline: Readline Interaction. 11912 (line 6) 11913* interactive shell: Invoking Bash. (line 131) 11914* interactive shell <1>: Interactive Shells. (line 6) 11915* internationalization: Locale Translation. (line 6) 11916* job: Definitions. (line 38) 11917* job control: Definitions. (line 42) 11918* job control <1>: Job Control Basics. (line 6) 11919* kill ring: Readline Killing Commands. 11920 (line 18) 11921* killing text: Readline Killing Commands. 11922 (line 6) 11923* localization: Locale Translation. (line 6) 11924* login shell: Invoking Bash. (line 128) 11925* matching, pattern: Pattern Matching. (line 6) 11926* metacharacter: Definitions. (line 46) 11927* name: Definitions. (line 51) 11928* native languages: Locale Translation. (line 6) 11929* notation, readline: Readline Bare Essentials. 11930 (line 6) 11931* operator, shell: Definitions. (line 57) 11932* parameter expansion: Shell Parameter Expansion. 11933 (line 6) 11934* parameters: Shell Parameters. (line 6) 11935* parameters, positional: Positional Parameters. 11936 (line 6) 11937* parameters, special: Special Parameters. (line 6) 11938* pathname expansion: Filename Expansion. (line 9) 11939* pattern matching: Pattern Matching. (line 6) 11940* pipeline: Pipelines. (line 6) 11941* POSIX: Definitions. (line 9) 11942* POSIX Mode: Bash POSIX Mode. (line 6) 11943* process group: Definitions. (line 62) 11944* process group ID: Definitions. (line 66) 11945* process substitution: Process Substitution. 11946 (line 6) 11947* programmable completion: Programmable Completion. 11948 (line 6) 11949* prompting: Controlling the Prompt. 11950 (line 6) 11951* quoting: Quoting. (line 6) 11952* quoting, ANSI: ANSI-C Quoting. (line 6) 11953* Readline, how to use: Job Control Variables. 11954 (line 23) 11955* redirection: Redirections. (line 6) 11956* reserved word: Definitions. (line 70) 11957* reserved words: Reserved Words. (line 6) 11958* restricted shell: The Restricted Shell. 11959 (line 6) 11960* return status: Definitions. (line 75) 11961* shell arithmetic: Shell Arithmetic. (line 6) 11962* shell function: Shell Functions. (line 6) 11963* shell script: Shell Scripts. (line 6) 11964* shell variable: Shell Parameters. (line 6) 11965* shell, interactive: Interactive Shells. (line 6) 11966* signal: Definitions. (line 78) 11967* signal handling: Signals. (line 6) 11968* special builtin: Definitions. (line 82) 11969* special builtin <1>: Special Builtins. (line 6) 11970* startup files: Bash Startup Files. (line 6) 11971* suspending jobs: Job Control Basics. (line 6) 11972* tilde expansion: Tilde Expansion. (line 6) 11973* token: Definitions. (line 86) 11974* translation, native languages: Locale Translation. (line 6) 11975* variable, shell: Shell Parameters. (line 6) 11976* variables, readline: Readline Init File Syntax. 11977 (line 37) 11978* word: Definitions. (line 90) 11979* word splitting: Word Splitting. (line 6) 11980* yanking text: Readline Killing Commands. 11981 (line 6) 11982 11983 11984 11985Tag Table: 11986Node: Top895 11987Node: Introduction2813 11988Node: What is Bash?3029 11989Node: What is a shell?4143 11990Node: Definitions6681 11991Node: Basic Shell Features9632 11992Node: Shell Syntax10851 11993Node: Shell Operation11877 11994Node: Quoting13170 11995Node: Escape Character14470 11996Node: Single Quotes14955 11997Node: Double Quotes15303 11998Node: ANSI-C Quoting16581 11999Node: Locale Translation17840 12000Node: Comments18993 12001Node: Shell Commands19611 12002Node: Reserved Words20549 12003Node: Simple Commands21305 12004Node: Pipelines21959 12005Node: Lists24891 12006Node: Compound Commands26682 12007Node: Looping Constructs27694 12008Node: Conditional Constructs30189 12009Node: Command Grouping41760 12010Node: Coprocesses43239 12011Node: GNU Parallel45142 12012Node: Shell Functions49443 12013Node: Shell Parameters56650 12014Node: Positional Parameters61063 12015Node: Special Parameters61963 12016Node: Shell Expansions65187 12017Node: Brace Expansion67310 12018Node: Tilde Expansion70033 12019Node: Shell Parameter Expansion72650 12020Node: Command Substitution87779 12021Node: Arithmetic Expansion89134 12022Node: Process Substitution90066 12023Node: Word Splitting91186 12024Node: Filename Expansion93130 12025Node: Pattern Matching95679 12026Node: Quote Removal99665 12027Node: Redirections99960 12028Node: Executing Commands109530 12029Node: Simple Command Expansion110200 12030Node: Command Search and Execution112154 12031Node: Command Execution Environment114530 12032Node: Environment117514 12033Node: Exit Status119173 12034Node: Signals120843 12035Node: Shell Scripts122810 12036Node: Shell Builtin Commands125822 12037Node: Bourne Shell Builtins127860 12038Node: Bash Builtins148789 12039Node: Modifying Shell Behavior178898 12040Node: The Set Builtin179243 12041Node: The Shopt Builtin189656 12042Node: Special Builtins204566 12043Node: Shell Variables205545 12044Node: Bourne Shell Variables205982 12045Node: Bash Variables208086 12046Node: Bash Features240720 12047Node: Invoking Bash241733 12048Node: Bash Startup Files247746 12049Node: Interactive Shells252849 12050Node: What is an Interactive Shell?253259 12051Node: Is this Shell Interactive?253908 12052Node: Interactive Shell Behavior254723 12053Node: Bash Conditional Expressions258237 12054Node: Shell Arithmetic262814 12055Node: Aliases265754 12056Node: Arrays268374 12057Node: The Directory Stack274383 12058Node: Directory Stack Builtins275167 12059Node: Controlling the Prompt278135 12060Node: The Restricted Shell281085 12061Node: Bash POSIX Mode283679 12062Node: Shell Compatibility Mode294715 12063Node: Job Control301371 12064Node: Job Control Basics301831 12065Node: Job Control Builtins306827 12066Node: Job Control Variables312227 12067Node: Command Line Editing313383 12068Node: Introduction and Notation315054 12069Node: Readline Interaction316677 12070Node: Readline Bare Essentials317868 12071Node: Readline Movement Commands319651 12072Node: Readline Killing Commands320611 12073Node: Readline Arguments322529 12074Node: Searching323573 12075Node: Readline Init File325759 12076Node: Readline Init File Syntax327018 12077Node: Conditional Init Constructs347556 12078Node: Sample Init File351752 12079Node: Bindable Readline Commands354876 12080Node: Commands For Moving356080 12081Node: Commands For History358131 12082Node: Commands For Text362924 12083Node: Commands For Killing366573 12084Node: Numeric Arguments369606 12085Node: Commands For Completion370745 12086Node: Keyboard Macros374936 12087Node: Miscellaneous Commands375623 12088Node: Readline vi Mode381307 12089Node: Programmable Completion382214 12090Node: Programmable Completion Builtins389994 12091Node: A Programmable Completion Example400689 12092Node: Using History Interactively405936 12093Node: Bash History Facilities406620 12094Node: Bash History Builtins409625 12095Node: History Interaction414354 12096Node: Event Designators417974 12097Node: Word Designators419328 12098Node: Modifiers421088 12099Node: Installing Bash422899 12100Node: Basic Installation424036 12101Node: Compilers and Options427294 12102Node: Compiling For Multiple Architectures428035 12103Node: Installation Names429728 12104Node: Specifying the System Type430546 12105Node: Sharing Defaults431262 12106Node: Operation Controls431935 12107Node: Optional Features432893 12108Node: Reporting Bugs443411 12109Node: Major Differences From The Bourne Shell444605 12110Node: GNU Free Documentation License461457 12111Node: Indexes486634 12112Node: Builtin Index487088 12113Node: Reserved Word Index493915 12114Node: Variable Index496363 12115Node: Function Index512260 12116Node: Concept Index525770 12117 12118End Tag Table 12119 12120 12121Local Variables: 12122coding: utf-8 12123End: 12124