diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/bashref.html | 16033 |
1 files changed, 16033 insertions, 0 deletions
diff --git a/doc/bashref.html b/doc/bashref.html new file mode 100644 index 0000000..928b3ff --- /dev/null +++ b/doc/bashref.html @@ -0,0 +1,16033 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- This text is a brief description of the features that are present in +the Bash shell (version 5.2, 19 September 2022). + +This is Edition 5.2, last updated 19 September 2022, +of The GNU Bash Reference Manual, +for Bash, Version 5.2. + +Copyright (C) 1988-2022 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +A copy of the license is included in the section entitled +"GNU Free Documentation License". --> +<title>Bash Reference Manual</title> + +<meta name="description" content="Bash Reference Manual"> +<meta name="keywords" content="Bash Reference Manual"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +<link href="#Top" rel="start" title="Top"> +<link href="#Indexes" rel="index" title="Indexes"> +<link href="#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="dir.html#Top" rel="up" title="(dir)"> +<link href="#Introduction" rel="next" title="Introduction"> +<link href="dir.html#Top" rel="prev" title="(dir)"> +<style type="text/css"> +<!-- +a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em} +a.summary-letter {text-decoration: none} +blockquote.indentedblock {margin-right: 0em} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +kbd {font-style: oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +span.nolinebreak {white-space: nowrap} +span.roman {font-family: initial; font-weight: normal} +span.sansserif {font-family: sans-serif; font-weight: normal} +span:hover a.copiable-anchor {visibility: visible} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en"> +<h1 class="settitle" align="center">Bash Reference Manual</h1> + + + + + + + + + + + +<div class="top" id="Top"> +<div class="header"> +<p> +Next: <a href="#Introduction" accesskey="n" rel="next">Introduction</a>, Previous: <a href="dir.html#Top" accesskey="p" rel="prev">(dir)</a>, Up: <a href="dir.html#Top" accesskey="u" rel="up">(dir)</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Bash-Features-1"></span><h1 class="top">Bash Features</h1> + +<p>This text is a brief description of the features that are present in +the Bash shell (version 5.2, 19 September 2022). +The Bash home page is <a href="http://www.gnu.org/software/bash/">http://www.gnu.org/software/bash/</a>. +</p> +<p>This is Edition 5.2, last updated 19 September 2022, +of <cite>The GNU Bash Reference Manual</cite>, +for <code>Bash</code>, Version 5.2. +</p> +<p>Bash contains features that appear in other popular shells, and some +features that only appear in Bash. Some of the shells that Bash has +borrowed concepts from are the Bourne Shell (<samp>sh</samp>), the Korn Shell +(<samp>ksh</samp>), and the C-shell (<samp>csh</samp> and its successor, +<samp>tcsh</samp>). The following menu breaks the features up into +categories, noting which features were inspired by other shells and +which are specific to Bash. +</p> +<p>This manual is meant as a brief introduction to features found in +Bash. The Bash manual page should be used as the definitive +reference on shell behavior. +</p> + +<div class="Contents_element" id="SEC_Contents"> +<h2 class="contents-heading">Table of Contents</h2> + +<div class="contents"> + +<ul class="no-bullet"> + <li><a id="toc-Introduction-1" href="#Introduction">1 Introduction</a> + <ul class="no-bullet"> + <li><a id="toc-What-is-Bash_003f-1" href="#What-is-Bash_003f">1.1 What is Bash?</a></li> + <li><a id="toc-What-is-a-shell_003f-1" href="#What-is-a-shell_003f">1.2 What is a shell?</a></li> + </ul></li> + <li><a id="toc-Definitions-1" href="#Definitions">2 Definitions</a></li> + <li><a id="toc-Basic-Shell-Features-1" href="#Basic-Shell-Features">3 Basic Shell Features</a> + <ul class="no-bullet"> + <li><a id="toc-Shell-Syntax-1" href="#Shell-Syntax">3.1 Shell Syntax</a> + <ul class="no-bullet"> + <li><a id="toc-Shell-Operation-1" href="#Shell-Operation">3.1.1 Shell Operation</a></li> + <li><a id="toc-Quoting-1" href="#Quoting">3.1.2 Quoting</a> + <ul class="no-bullet"> + <li><a id="toc-Escape-Character-1" href="#Escape-Character">3.1.2.1 Escape Character</a></li> + <li><a id="toc-Single-Quotes-1" href="#Single-Quotes">3.1.2.2 Single Quotes</a></li> + <li><a id="toc-Double-Quotes-1" href="#Double-Quotes">3.1.2.3 Double Quotes</a></li> + <li><a id="toc-ANSI_002dC-Quoting-1" href="#ANSI_002dC-Quoting">3.1.2.4 ANSI-C Quoting</a></li> + <li><a id="toc-Locale_002dSpecific-Translation" href="#Locale-Translation">3.1.2.5 Locale-Specific Translation</a></li> + </ul></li> + <li><a id="toc-Comments-1" href="#Comments">3.1.3 Comments</a></li> + </ul></li> + <li><a id="toc-Shell-Commands-1" href="#Shell-Commands">3.2 Shell Commands</a> + <ul class="no-bullet"> + <li><a id="toc-Reserved-Words-1" href="#Reserved-Words">3.2.1 Reserved Words</a></li> + <li><a id="toc-Simple-Commands-1" href="#Simple-Commands">3.2.2 Simple Commands</a></li> + <li><a id="toc-Pipelines-1" href="#Pipelines">3.2.3 Pipelines</a></li> + <li><a id="toc-Lists-of-Commands" href="#Lists">3.2.4 Lists of Commands</a></li> + <li><a id="toc-Compound-Commands-1" href="#Compound-Commands">3.2.5 Compound Commands</a> + <ul class="no-bullet"> + <li><a id="toc-Looping-Constructs-1" href="#Looping-Constructs">3.2.5.1 Looping Constructs</a></li> + <li><a id="toc-Conditional-Constructs-1" href="#Conditional-Constructs">3.2.5.2 Conditional Constructs</a></li> + <li><a id="toc-Grouping-Commands" href="#Command-Grouping">3.2.5.3 Grouping Commands</a></li> + </ul></li> + <li><a id="toc-Coprocesses-1" href="#Coprocesses">3.2.6 Coprocesses</a></li> + <li><a id="toc-GNU-Parallel-1" href="#GNU-Parallel">3.2.7 GNU Parallel</a></li> + </ul></li> + <li><a id="toc-Shell-Functions-1" href="#Shell-Functions">3.3 Shell Functions</a></li> + <li><a id="toc-Shell-Parameters-1" href="#Shell-Parameters">3.4 Shell Parameters</a> + <ul class="no-bullet"> + <li><a id="toc-Positional-Parameters-1" href="#Positional-Parameters">3.4.1 Positional Parameters</a></li> + <li><a id="toc-Special-Parameters-1" href="#Special-Parameters">3.4.2 Special Parameters</a></li> + </ul></li> + <li><a id="toc-Shell-Expansions-1" href="#Shell-Expansions">3.5 Shell Expansions</a> + <ul class="no-bullet"> + <li><a id="toc-Brace-Expansion-1" href="#Brace-Expansion">3.5.1 Brace Expansion</a></li> + <li><a id="toc-Tilde-Expansion-1" href="#Tilde-Expansion">3.5.2 Tilde Expansion</a></li> + <li><a id="toc-Shell-Parameter-Expansion-1" href="#Shell-Parameter-Expansion">3.5.3 Shell Parameter Expansion</a></li> + <li><a id="toc-Command-Substitution-1" href="#Command-Substitution">3.5.4 Command Substitution</a></li> + <li><a id="toc-Arithmetic-Expansion-1" href="#Arithmetic-Expansion">3.5.5 Arithmetic Expansion</a></li> + <li><a id="toc-Process-Substitution-1" href="#Process-Substitution">3.5.6 Process Substitution</a></li> + <li><a id="toc-Word-Splitting-1" href="#Word-Splitting">3.5.7 Word Splitting</a></li> + <li><a id="toc-Filename-Expansion-1" href="#Filename-Expansion">3.5.8 Filename Expansion</a> + <ul class="no-bullet"> + <li><a id="toc-Pattern-Matching-1" href="#Pattern-Matching">3.5.8.1 Pattern Matching</a></li> + </ul></li> + <li><a id="toc-Quote-Removal-1" href="#Quote-Removal">3.5.9 Quote Removal</a></li> + </ul></li> + <li><a id="toc-Redirections-1" href="#Redirections">3.6 Redirections</a> + <ul class="no-bullet"> + <li><a id="toc-Redirecting-Input" href="#Redirecting-Input">3.6.1 Redirecting Input</a></li> + <li><a id="toc-Redirecting-Output" href="#Redirecting-Output">3.6.2 Redirecting Output</a></li> + <li><a id="toc-Appending-Redirected-Output" href="#Appending-Redirected-Output">3.6.3 Appending Redirected Output</a></li> + <li><a id="toc-Redirecting-Standard-Output-and-Standard-Error" href="#Redirecting-Standard-Output-and-Standard-Error">3.6.4 Redirecting Standard Output and Standard Error</a></li> + <li><a id="toc-Appending-Standard-Output-and-Standard-Error" href="#Appending-Standard-Output-and-Standard-Error">3.6.5 Appending Standard Output and Standard Error</a></li> + <li><a id="toc-Here-Documents" href="#Here-Documents">3.6.6 Here Documents</a></li> + <li><a id="toc-Here-Strings" href="#Here-Strings">3.6.7 Here Strings</a></li> + <li><a id="toc-Duplicating-File-Descriptors" href="#Duplicating-File-Descriptors">3.6.8 Duplicating File Descriptors</a></li> + <li><a id="toc-Moving-File-Descriptors" href="#Moving-File-Descriptors">3.6.9 Moving File Descriptors</a></li> + <li><a id="toc-Opening-File-Descriptors-for-Reading-and-Writing" href="#Opening-File-Descriptors-for-Reading-and-Writing">3.6.10 Opening File Descriptors for Reading and Writing</a></li> + </ul></li> + <li><a id="toc-Executing-Commands-1" href="#Executing-Commands">3.7 Executing Commands</a> + <ul class="no-bullet"> + <li><a id="toc-Simple-Command-Expansion-1" href="#Simple-Command-Expansion">3.7.1 Simple Command Expansion</a></li> + <li><a id="toc-Command-Search-and-Execution-1" href="#Command-Search-and-Execution">3.7.2 Command Search and Execution</a></li> + <li><a id="toc-Command-Execution-Environment-1" href="#Command-Execution-Environment">3.7.3 Command Execution Environment</a></li> + <li><a id="toc-Environment-1" href="#Environment">3.7.4 Environment</a></li> + <li><a id="toc-Exit-Status-1" href="#Exit-Status">3.7.5 Exit Status</a></li> + <li><a id="toc-Signals-1" href="#Signals">3.7.6 Signals</a></li> + </ul></li> + <li><a id="toc-Shell-Scripts-1" href="#Shell-Scripts">3.8 Shell Scripts</a></li> + </ul></li> + <li><a id="toc-Shell-Builtin-Commands-1" href="#Shell-Builtin-Commands">4 Shell Builtin Commands</a> + <ul class="no-bullet"> + <li><a id="toc-Bourne-Shell-Builtins-1" href="#Bourne-Shell-Builtins">4.1 Bourne Shell Builtins</a></li> + <li><a id="toc-Bash-Builtin-Commands" href="#Bash-Builtins">4.2 Bash Builtin Commands</a></li> + <li><a id="toc-Modifying-Shell-Behavior-1" href="#Modifying-Shell-Behavior">4.3 Modifying Shell Behavior</a> + <ul class="no-bullet"> + <li><a id="toc-The-Set-Builtin-1" href="#The-Set-Builtin">4.3.1 The Set Builtin</a></li> + <li><a id="toc-The-Shopt-Builtin-1" href="#The-Shopt-Builtin">4.3.2 The Shopt Builtin</a></li> + </ul></li> + <li><a id="toc-Special-Builtins-1" href="#Special-Builtins">4.4 Special Builtins</a></li> + </ul></li> + <li><a id="toc-Shell-Variables-1" href="#Shell-Variables">5 Shell Variables</a> + <ul class="no-bullet"> + <li><a id="toc-Bourne-Shell-Variables-1" href="#Bourne-Shell-Variables">5.1 Bourne Shell Variables</a></li> + <li><a id="toc-Bash-Variables-1" href="#Bash-Variables">5.2 Bash Variables</a></li> + </ul></li> + <li><a id="toc-Bash-Features-2" href="#Bash-Features">6 Bash Features</a> + <ul class="no-bullet"> + <li><a id="toc-Invoking-Bash-1" href="#Invoking-Bash">6.1 Invoking Bash</a></li> + <li><a id="toc-Bash-Startup-Files-1" href="#Bash-Startup-Files">6.2 Bash Startup Files</a></li> + <li><a id="toc-Interactive-Shells-1" href="#Interactive-Shells">6.3 Interactive Shells</a> + <ul class="no-bullet"> + <li><a id="toc-What-is-an-Interactive-Shell_003f-1" href="#What-is-an-Interactive-Shell_003f">6.3.1 What is an Interactive Shell?</a></li> + <li><a id="toc-Is-this-Shell-Interactive_003f-1" href="#Is-this-Shell-Interactive_003f">6.3.2 Is this Shell Interactive?</a></li> + <li><a id="toc-Interactive-Shell-Behavior-1" href="#Interactive-Shell-Behavior">6.3.3 Interactive Shell Behavior</a></li> + </ul></li> + <li><a id="toc-Bash-Conditional-Expressions-1" href="#Bash-Conditional-Expressions">6.4 Bash Conditional Expressions</a></li> + <li><a id="toc-Shell-Arithmetic-1" href="#Shell-Arithmetic">6.5 Shell Arithmetic</a></li> + <li><a id="toc-Aliases-1" href="#Aliases">6.6 Aliases</a></li> + <li><a id="toc-Arrays-1" href="#Arrays">6.7 Arrays</a></li> + <li><a id="toc-The-Directory-Stack-1" href="#The-Directory-Stack">6.8 The Directory Stack</a> + <ul class="no-bullet"> + <li><a id="toc-Directory-Stack-Builtins-1" href="#Directory-Stack-Builtins">6.8.1 Directory Stack Builtins</a></li> + </ul></li> + <li><a id="toc-Controlling-the-Prompt-1" href="#Controlling-the-Prompt">6.9 Controlling the Prompt</a></li> + <li><a id="toc-The-Restricted-Shell-1" href="#The-Restricted-Shell">6.10 The Restricted Shell</a></li> + <li><a id="toc-Bash-POSIX-Mode-1" href="#Bash-POSIX-Mode">6.11 Bash POSIX Mode</a></li> + <li><a id="toc-Shell-Compatibility-Mode-1" href="#Shell-Compatibility-Mode">6.12 Shell Compatibility Mode</a></li> + </ul></li> + <li><a id="toc-Job-Control-1" href="#Job-Control">7 Job Control</a> + <ul class="no-bullet"> + <li><a id="toc-Job-Control-Basics-1" href="#Job-Control-Basics">7.1 Job Control Basics</a></li> + <li><a id="toc-Job-Control-Builtins-1" href="#Job-Control-Builtins">7.2 Job Control Builtins</a></li> + <li><a id="toc-Job-Control-Variables-1" href="#Job-Control-Variables">7.3 Job Control Variables</a></li> + </ul></li> + <li><a id="toc-Command-Line-Editing-1" href="#Command-Line-Editing">8 Command Line Editing</a> + <ul class="no-bullet"> + <li><a id="toc-Introduction-to-Line-Editing" href="#Introduction-and-Notation">8.1 Introduction to Line Editing</a></li> + <li><a id="toc-Readline-Interaction-1" href="#Readline-Interaction">8.2 Readline Interaction</a> + <ul class="no-bullet"> + <li><a id="toc-Readline-Bare-Essentials-1" href="#Readline-Bare-Essentials">8.2.1 Readline Bare Essentials</a></li> + <li><a id="toc-Readline-Movement-Commands-1" href="#Readline-Movement-Commands">8.2.2 Readline Movement Commands</a></li> + <li><a id="toc-Readline-Killing-Commands-1" href="#Readline-Killing-Commands">8.2.3 Readline Killing Commands</a></li> + <li><a id="toc-Readline-Arguments-1" href="#Readline-Arguments">8.2.4 Readline Arguments</a></li> + <li><a id="toc-Searching-for-Commands-in-the-History" href="#Searching">8.2.5 Searching for Commands in the History</a></li> + </ul></li> + <li><a id="toc-Readline-Init-File-1" href="#Readline-Init-File">8.3 Readline Init File</a> + <ul class="no-bullet"> + <li><a id="toc-Readline-Init-File-Syntax-1" href="#Readline-Init-File-Syntax">8.3.1 Readline Init File Syntax</a></li> + <li><a id="toc-Conditional-Init-Constructs-1" href="#Conditional-Init-Constructs">8.3.2 Conditional Init Constructs</a></li> + <li><a id="toc-Sample-Init-File-1" href="#Sample-Init-File">8.3.3 Sample Init File</a></li> + </ul></li> + <li><a id="toc-Bindable-Readline-Commands-1" href="#Bindable-Readline-Commands">8.4 Bindable Readline Commands</a> + <ul class="no-bullet"> + <li><a id="toc-Commands-For-Moving-1" href="#Commands-For-Moving">8.4.1 Commands For Moving</a></li> + <li><a id="toc-Commands-For-Manipulating-The-History" href="#Commands-For-History">8.4.2 Commands For Manipulating The History</a></li> + <li><a id="toc-Commands-For-Changing-Text" href="#Commands-For-Text">8.4.3 Commands For Changing Text</a></li> + <li><a id="toc-Killing-And-Yanking" href="#Commands-For-Killing">8.4.4 Killing And Yanking</a></li> + <li><a id="toc-Specifying-Numeric-Arguments" href="#Numeric-Arguments">8.4.5 Specifying Numeric Arguments</a></li> + <li><a id="toc-Letting-Readline-Type-For-You" href="#Commands-For-Completion">8.4.6 Letting Readline Type For You</a></li> + <li><a id="toc-Keyboard-Macros-1" href="#Keyboard-Macros">8.4.7 Keyboard Macros</a></li> + <li><a id="toc-Some-Miscellaneous-Commands" href="#Miscellaneous-Commands">8.4.8 Some Miscellaneous Commands</a></li> + </ul></li> + <li><a id="toc-Readline-vi-Mode-1" href="#Readline-vi-Mode">8.5 Readline vi Mode</a></li> + <li><a id="toc-Programmable-Completion-1" href="#Programmable-Completion">8.6 Programmable Completion</a></li> + <li><a id="toc-Programmable-Completion-Builtins-1" href="#Programmable-Completion-Builtins">8.7 Programmable Completion Builtins</a></li> + <li><a id="toc-A-Programmable-Completion-Example-1" href="#A-Programmable-Completion-Example">8.8 A Programmable Completion Example</a></li> + </ul></li> + <li><a id="toc-Using-History-Interactively-1" href="#Using-History-Interactively">9 Using History Interactively</a> + <ul class="no-bullet"> + <li><a id="toc-Bash-History-Facilities-1" href="#Bash-History-Facilities">9.1 Bash History Facilities</a></li> + <li><a id="toc-Bash-History-Builtins-1" href="#Bash-History-Builtins">9.2 Bash History Builtins</a></li> + <li><a id="toc-History-Expansion" href="#History-Interaction">9.3 History Expansion</a> + <ul class="no-bullet"> + <li><a id="toc-Event-Designators-1" href="#Event-Designators">9.3.1 Event Designators</a></li> + <li><a id="toc-Word-Designators-1" href="#Word-Designators">9.3.2 Word Designators</a></li> + <li><a id="toc-Modifiers-1" href="#Modifiers">9.3.3 Modifiers</a></li> + </ul></li> + </ul></li> + <li><a id="toc-Installing-Bash-1" href="#Installing-Bash">10 Installing Bash</a> + <ul class="no-bullet"> + <li><a id="toc-Basic-Installation-1" href="#Basic-Installation">10.1 Basic Installation</a></li> + <li><a id="toc-Compilers-and-Options-1" href="#Compilers-and-Options">10.2 Compilers and Options</a></li> + <li><a id="toc-Compiling-For-Multiple-Architectures-1" href="#Compiling-For-Multiple-Architectures">10.3 Compiling For Multiple Architectures</a></li> + <li><a id="toc-Installation-Names-1" href="#Installation-Names">10.4 Installation Names</a></li> + <li><a id="toc-Specifying-the-System-Type-1" href="#Specifying-the-System-Type">10.5 Specifying the System Type</a></li> + <li><a id="toc-Sharing-Defaults-1" href="#Sharing-Defaults">10.6 Sharing Defaults</a></li> + <li><a id="toc-Operation-Controls-1" href="#Operation-Controls">10.7 Operation Controls</a></li> + <li><a id="toc-Optional-Features-1" href="#Optional-Features">10.8 Optional Features</a></li> + </ul></li> + <li><a id="toc-Reporting-Bugs-1" href="#Reporting-Bugs">Appendix A Reporting Bugs</a></li> + <li><a id="toc-Major-Differences-From-The-Bourne-Shell-1" href="#Major-Differences-From-The-Bourne-Shell">Appendix B Major Differences From The Bourne Shell</a> + <ul class="no-bullet"> + <li><a id="toc-Implementation-Differences-From-The-SVR4_002e2-Shell" href="#Implementation-Differences-From-The-SVR4_002e2-Shell">B.1 Implementation Differences From The SVR4.2 Shell</a></li> + </ul></li> + <li><a id="toc-GNU-Free-Documentation-License-1" href="#GNU-Free-Documentation-License">Appendix C GNU Free Documentation License</a></li> + <li><a id="toc-Indexes-1" href="#Indexes">Appendix D Indexes</a> + <ul class="no-bullet"> + <li><a id="toc-Index-of-Shell-Builtin-Commands" href="#Builtin-Index" rel="index">D.1 Index of Shell Builtin Commands</a></li> + <li><a id="toc-Index-of-Shell-Reserved-Words" href="#Reserved-Word-Index" rel="index">D.2 Index of Shell Reserved Words</a></li> + <li><a id="toc-Parameter-and-Variable-Index" href="#Variable-Index" rel="index">D.3 Parameter and Variable Index</a></li> + <li><a id="toc-Function-Index-1" href="#Function-Index" rel="index">D.4 Function Index</a></li> + <li><a id="toc-Concept-Index-1" href="#Concept-Index" rel="index">D.5 Concept Index</a></li> + </ul></li> +</ul> +</div> +</div> +<hr> +<div class="chapter" id="Introduction"> +<div class="header"> +<p> +Next: <a href="#Definitions" accesskey="n" rel="next">Definitions</a>, Up: <a href="#Top" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Introduction-1"></span><h2 class="chapter">1 Introduction</h2> + +<ul class="section-toc"> +<li><a href="#What-is-Bash_003f" accesskey="1">What is Bash?</a></li> +<li><a href="#What-is-a-shell_003f" accesskey="2">What is a shell?</a></li> +</ul> +<hr> +<div class="section" id="What-is-Bash_003f"> +<div class="header"> +<p> +Next: <a href="#What-is-a-shell_003f" accesskey="n" rel="next">What is a shell?</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="What-is-Bash_003f-1"></span><h3 class="section">1.1 What is Bash?</h3> + +<p>Bash is the shell, or command language interpreter, +for the <small>GNU</small> operating system. +The name is an acronym for the ‘<samp>Bourne-Again SHell</samp>’, +a pun on Stephen Bourne, the author of the direct ancestor of +the current Unix shell <code>sh</code>, +which appeared in the Seventh Edition Bell Labs Research version +of Unix. +</p> +<p>Bash is largely compatible with <code>sh</code> and incorporates useful +features from the Korn shell <code>ksh</code> and the C shell <code>csh</code>. +It is intended to be a conformant implementation of the <small>IEEE</small> +<small>POSIX</small> Shell and Tools portion of the <small>IEEE</small> <small>POSIX</small> +specification (<small>IEEE</small> Standard 1003.1). +It offers functional improvements over <code>sh</code> for both interactive and +programming use. +</p> +<p>While the <small>GNU</small> operating system provides other shells, including +a version of <code>csh</code>, Bash is the default shell. +Like other <small>GNU</small> software, Bash is quite portable. It currently runs +on nearly every version of Unix and a few other operating systems - +independently-supported ports exist for <small>MS-DOS</small>, <small>OS/2</small>, +and Windows platforms. +</p> +<hr> +</div> +<div class="section" id="What-is-a-shell_003f"> +<div class="header"> +<p> +Previous: <a href="#What-is-Bash_003f" accesskey="p" rel="prev">What is Bash?</a>, Up: <a href="#Introduction" accesskey="u" rel="up">Introduction</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="What-is-a-shell_003f-1"></span><h3 class="section">1.2 What is a shell?</h3> + +<p>At its base, a shell is simply a macro processor that executes +commands. The term macro processor means functionality where text +and symbols are expanded to create larger expressions. +</p> +<p>A Unix shell is both a command interpreter and a programming +language. As a command interpreter, the shell provides the user +interface to the rich set of <small>GNU</small> utilities. The programming +language features allow these utilities to be combined. +Files containing commands can be created, and become +commands themselves. These new commands have the same status as +system commands in directories such as <samp>/bin</samp>, allowing users +or groups to establish custom environments to automate their common +tasks. +</p> +<p>Shells may be used interactively or non-interactively. In +interactive mode, they accept input typed from the keyboard. +When executing non-interactively, shells execute commands read +from a file. +</p> +<p>A shell allows execution of <small>GNU</small> commands, both synchronously and +asynchronously. +The shell waits for synchronous commands to complete before accepting +more input; asynchronous commands continue to execute in parallel +with the shell while it reads and executes additional commands. +The <em>redirection</em> constructs permit +fine-grained control of the input and output of those commands. +Moreover, the shell allows control over the contents of commands’ +environments. +</p> +<p>Shells also provide a small set of built-in +commands (<em>builtins</em>) implementing functionality impossible +or inconvenient to obtain via separate utilities. +For example, <code>cd</code>, <code>break</code>, <code>continue</code>, and +<code>exec</code> cannot be implemented outside of the shell because +they directly manipulate the shell itself. +The <code>history</code>, <code>getopts</code>, <code>kill</code>, or <code>pwd</code> +builtins, among others, could be implemented in separate utilities, +but they are more convenient to use as builtin commands. +All of the shell builtins are described in +subsequent sections. +</p> +<p>While executing commands is essential, most of the power (and +complexity) of shells is due to their embedded programming +languages. Like any high-level language, the shell provides +variables, flow control constructs, quoting, and functions. +</p> +<p>Shells offer features geared specifically for +interactive use rather than to augment the programming language. +These interactive features include job control, command line +editing, command history and aliases. Each of these features is +described in this manual. +</p> +<hr> +</div> +</div> +<div class="chapter" id="Definitions"> +<div class="header"> +<p> +Next: <a href="#Basic-Shell-Features" accesskey="n" rel="next">Basic Shell Features</a>, Previous: <a href="#Introduction" accesskey="p" rel="prev">Introduction</a>, Up: <a href="#Top" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Definitions-1"></span><h2 class="chapter">2 Definitions</h2> +<p>These definitions are used throughout the remainder of this manual. +</p> +<dl compact="compact"> +<dt id='index-POSIX'><span><code>POSIX</code><a href='#index-POSIX' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A family of open system standards based on Unix. Bash +is primarily concerned with the Shell and Utilities portion of the +<small>POSIX</small> 1003.1 standard. +</p> +</dd> +<dt><span><code>blank</code></span></dt> +<dd><p>A space or tab character. +</p> +</dd> +<dt id='index-builtin-1'><span><code>builtin</code><a href='#index-builtin-1' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A command that is implemented internally by the shell itself, rather +than by an executable program somewhere in the file system. +</p> +</dd> +<dt id='index-control-operator'><span><code>control operator</code><a href='#index-control-operator' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A <code>token</code> that performs a control function. It is a <code>newline</code> +or one of the following: +‘<samp>||</samp>’, ‘<samp>&&</samp>’, ‘<samp>&</samp>’, ‘<samp>;</samp>’, ‘<samp>;;</samp>’, ‘<samp>;&</samp>’, ‘<samp>;;&</samp>’, +‘<samp>|</samp>’, ‘<samp>|&</samp>’, ‘<samp>(</samp>’, or ‘<samp>)</samp>’. +</p> +</dd> +<dt id='index-exit-status'><span><code>exit status</code><a href='#index-exit-status' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The value returned by a command to its caller. The value is restricted +to eight bits, so the maximum value is 255. +</p> +</dd> +<dt id='index-field'><span><code>field</code><a href='#index-field' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A unit of text that is the result of one of the shell expansions. After +expansion, when executing a command, the resulting fields are used as +the command name and arguments. +</p> +</dd> +<dt id='index-filename'><span><code>filename</code><a href='#index-filename' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A string of characters used to identify a file. +</p> +</dd> +<dt id='index-job'><span><code>job</code><a href='#index-job' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A set of processes comprising a pipeline, and any processes descended +from it, that are all in the same process group. +</p> +</dd> +<dt id='index-job-control'><span><code>job control</code><a href='#index-job-control' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A mechanism by which users can selectively stop (suspend) and restart +(resume) execution of processes. +</p> +</dd> +<dt id='index-metacharacter'><span><code>metacharacter</code><a href='#index-metacharacter' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A character that, when unquoted, separates words. A metacharacter is +a <code>space</code>, <code>tab</code>, <code>newline</code>, or one of the following characters: +‘<samp>|</samp>’, ‘<samp>&</samp>’, ‘<samp>;</samp>’, ‘<samp>(</samp>’, ‘<samp>)</samp>’, ‘<samp><</samp>’, or +‘<samp>></samp>’. +</p> +</dd> +<dt id='index-name'><span><code>name</code><a href='#index-name' class='copiable-anchor'> ¶</a></span></dt> +<dd><span id="index-identifier"></span> +<p>A <code>word</code> consisting solely of letters, numbers, and underscores, +and beginning with a letter or underscore. <code>Name</code>s are used as +shell variable and function names. +Also referred to as an <code>identifier</code>. +</p> +</dd> +<dt id='index-operator_002c-shell'><span><code>operator</code><a href='#index-operator_002c-shell' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A <code>control operator</code> or a <code>redirection operator</code>. +See <a href="#Redirections">Redirections</a>, for a list of redirection operators. +Operators contain at least one unquoted <code>metacharacter</code>. +</p> +</dd> +<dt id='index-process-group'><span><code>process group</code><a href='#index-process-group' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A collection of related processes each having the same process +group <small>ID</small>. +</p> +</dd> +<dt id='index-process-group-ID'><span><code>process group ID</code><a href='#index-process-group-ID' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A unique identifier that represents a <code>process group</code> +during its lifetime. +</p> +</dd> +<dt id='index-reserved-word'><span><code>reserved word</code><a href='#index-reserved-word' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A <code>word</code> that has a special meaning to the shell. Most reserved +words introduce shell flow control constructs, such as <code>for</code> and +<code>while</code>. +</p> +</dd> +<dt id='index-return-status'><span><code>return status</code><a href='#index-return-status' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A synonym for <code>exit status</code>. +</p> +</dd> +<dt id='index-signal'><span><code>signal</code><a href='#index-signal' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A mechanism by which a process may be notified by the kernel +of an event occurring in the system. +</p> +</dd> +<dt id='index-special-builtin'><span><code>special builtin</code><a href='#index-special-builtin' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A shell builtin command that has been classified as special by the +<small>POSIX</small> standard. +</p> +</dd> +<dt id='index-token'><span><code>token</code><a href='#index-token' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A sequence of characters considered a single unit by the shell. +It is either a <code>word</code> or an <code>operator</code>. +</p> +</dd> +<dt id='index-word'><span><code>word</code><a href='#index-word' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A sequence of characters treated as a unit by the shell. +Words may not include unquoted <code>metacharacters</code>. +</p></dd> +</dl> + +<hr> +</div> +<div class="chapter" id="Basic-Shell-Features"> +<div class="header"> +<p> +Next: <a href="#Shell-Builtin-Commands" accesskey="n" rel="next">Shell Builtin Commands</a>, Previous: <a href="#Definitions" accesskey="p" rel="prev">Definitions</a>, Up: <a href="#Top" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Basic-Shell-Features-1"></span><h2 class="chapter">3 Basic Shell Features</h2> +<span id="index-Bourne-shell"></span> + +<p>Bash is an acronym for ‘<samp>Bourne-Again SHell</samp>’. +The Bourne shell is +the traditional Unix shell originally written by Stephen Bourne. +All of the Bourne shell builtin commands are available in Bash, +The rules for evaluation and quoting are taken from the <small>POSIX</small> +specification for the ‘standard’ Unix shell. +</p> +<p>This chapter briefly summarizes the shell’s ‘building blocks’: +commands, control structures, shell functions, shell <i>parameters</i>, +shell expansions, +<i>redirections</i>, which are a way to direct input and output from +and to named files, and how the shell executes commands. +</p> + +<ul class="section-toc"> +<li><a href="#Shell-Syntax" accesskey="1">Shell Syntax</a></li> +<li><a href="#Shell-Commands" accesskey="2">Shell Commands</a></li> +<li><a href="#Shell-Functions" accesskey="3">Shell Functions</a></li> +<li><a href="#Shell-Parameters" accesskey="4">Shell Parameters</a></li> +<li><a href="#Shell-Expansions" accesskey="5">Shell Expansions</a></li> +<li><a href="#Redirections" accesskey="6">Redirections</a></li> +<li><a href="#Executing-Commands" accesskey="7">Executing Commands</a></li> +<li><a href="#Shell-Scripts" accesskey="8">Shell Scripts</a></li> +</ul> +<hr> +<div class="section" id="Shell-Syntax"> +<div class="header"> +<p> +Next: <a href="#Shell-Commands" accesskey="n" rel="next">Shell Commands</a>, Up: <a href="#Basic-Shell-Features" accesskey="u" rel="up">Basic Shell Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Shell-Syntax-1"></span><h3 class="section">3.1 Shell Syntax</h3> + +<p>When the shell reads input, it proceeds through a +sequence of operations. If the input indicates the beginning of a +comment, the shell ignores the comment symbol (‘<samp>#</samp>’), and the rest +of that line. +</p> +<p>Otherwise, roughly speaking, the shell reads its input and +divides the input into words and operators, employing the quoting rules +to select which meanings to assign various words and characters. +</p> +<p>The shell then parses these tokens into commands and other constructs, +removes the special meaning of certain words or characters, expands +others, redirects input and output as needed, executes the specified +command, waits for the command’s exit status, and makes that exit status +available for further inspection or processing. +</p> +<ul class="section-toc"> +<li><a href="#Shell-Operation" accesskey="1">Shell Operation</a></li> +<li><a href="#Quoting" accesskey="2">Quoting</a></li> +<li><a href="#Comments" accesskey="3">Comments</a></li> +</ul> +<hr> +<div class="subsection" id="Shell-Operation"> +<div class="header"> +<p> +Next: <a href="#Quoting" accesskey="n" rel="next">Quoting</a>, Up: <a href="#Shell-Syntax" accesskey="u" rel="up">Shell Syntax</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Shell-Operation-1"></span><h4 class="subsection">3.1.1 Shell Operation</h4> + +<p>The following is a brief description of the shell’s operation when it +reads and executes a command. Basically, the shell does the +following: +</p> +<ol> +<li> Reads its input from a file (see <a href="#Shell-Scripts">Shell Scripts</a>), from a string +supplied as an argument to the <samp>-c</samp> invocation option +(see <a href="#Invoking-Bash">Invoking Bash</a>), or from the user’s terminal. + +</li><li> Breaks the input into words and operators, obeying the quoting rules +described in <a href="#Quoting">Quoting</a>. These tokens are separated by +<code>metacharacters</code>. Alias expansion is performed by this step +(see <a href="#Aliases">Aliases</a>). + +</li><li> Parses the tokens into simple and compound commands +(see <a href="#Shell-Commands">Shell Commands</a>). + +</li><li> Performs the various shell expansions (see <a href="#Shell-Expansions">Shell Expansions</a>), breaking +the expanded tokens into lists of filenames (see <a href="#Filename-Expansion">Filename Expansion</a>) +and commands and arguments. + +</li><li> Performs any necessary redirections (see <a href="#Redirections">Redirections</a>) and removes +the redirection operators and their operands from the argument list. + +</li><li> Executes the command (see <a href="#Executing-Commands">Executing Commands</a>). + +</li><li> Optionally waits for the command to complete and collects its exit +status (see <a href="#Exit-Status">Exit Status</a>). + +</li></ol> + +<hr> +</div> +<div class="subsection" id="Quoting"> +<div class="header"> +<p> +Next: <a href="#Comments" accesskey="n" rel="next">Comments</a>, Previous: <a href="#Shell-Operation" accesskey="p" rel="prev">Shell Operation</a>, Up: <a href="#Shell-Syntax" accesskey="u" rel="up">Shell Syntax</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Quoting-1"></span><h4 class="subsection">3.1.2 Quoting</h4> +<span id="index-quoting"></span> + +<p>Quoting is used to remove the special meaning of certain +characters or words to the shell. Quoting can be used to +disable special treatment for special characters, to prevent +reserved words from being recognized as such, and to prevent +parameter expansion. +</p> +<p>Each of the shell metacharacters (see <a href="#Definitions">Definitions</a>) +has special meaning to the shell and must be quoted if it is to +represent itself. +When the command history expansion facilities are being used +(see <a href="#History-Interaction">History Expansion</a>), the +<em>history expansion</em> character, usually ‘<samp>!</samp>’, must be quoted +to prevent history expansion. See <a href="#Bash-History-Facilities">Bash History Facilities</a>, for +more details concerning history expansion. +</p> +<p>There are three quoting mechanisms: the +<em>escape character</em>, single quotes, and double quotes. +</p> +<ul class="section-toc"> +<li><a href="#Escape-Character" accesskey="1">Escape Character</a></li> +<li><a href="#Single-Quotes" accesskey="2">Single Quotes</a></li> +<li><a href="#Double-Quotes" accesskey="3">Double Quotes</a></li> +<li><a href="#ANSI_002dC-Quoting" accesskey="4">ANSI-C Quoting</a></li> +<li><a href="#Locale-Translation" accesskey="5">Locale-Specific Translation</a></li> +</ul> +<hr> +<div class="subsubsection" id="Escape-Character"> +<div class="header"> +<p> +Next: <a href="#Single-Quotes" accesskey="n" rel="next">Single Quotes</a>, Up: <a href="#Quoting" accesskey="u" rel="up">Quoting</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Escape-Character-1"></span><h4 class="subsubsection">3.1.2.1 Escape Character</h4> +<p>A non-quoted backslash ‘<samp>\</samp>’ is the Bash escape character. +It preserves the literal value of the next character that follows, +with the exception of <code>newline</code>. If a <code>\newline</code> pair +appears, and the backslash itself is not quoted, the <code>\newline</code> +is treated as a line continuation (that is, it is removed from +the input stream and effectively ignored). +</p> +<hr> +</div> +<div class="subsubsection" id="Single-Quotes"> +<div class="header"> +<p> +Next: <a href="#Double-Quotes" accesskey="n" rel="next">Double Quotes</a>, Previous: <a href="#Escape-Character" accesskey="p" rel="prev">Escape Character</a>, Up: <a href="#Quoting" accesskey="u" rel="up">Quoting</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Single-Quotes-1"></span><h4 class="subsubsection">3.1.2.2 Single Quotes</h4> + +<p>Enclosing characters in single quotes (‘<samp>'</samp>’) preserves the literal value +of each character within the quotes. A single quote may not occur +between single quotes, even when preceded by a backslash. +</p> +<hr> +</div> +<div class="subsubsection" id="Double-Quotes"> +<div class="header"> +<p> +Next: <a href="#ANSI_002dC-Quoting" accesskey="n" rel="next">ANSI-C Quoting</a>, Previous: <a href="#Single-Quotes" accesskey="p" rel="prev">Single Quotes</a>, Up: <a href="#Quoting" accesskey="u" rel="up">Quoting</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Double-Quotes-1"></span><h4 class="subsubsection">3.1.2.3 Double Quotes</h4> + +<p>Enclosing characters in double quotes (‘<samp>"</samp>’) preserves the literal value +of all characters within the quotes, with the exception of +‘<samp>$</samp>’, ‘<samp>`</samp>’, ‘<samp>\</samp>’, +and, when history expansion is enabled, ‘<samp>!</samp>’. +When the shell is in +<small>POSIX</small> mode (see <a href="#Bash-POSIX-Mode">Bash POSIX Mode</a>), +the ‘<samp>!</samp>’ has no special meaning +within double quotes, even when history expansion is enabled. +The characters ‘<samp>$</samp>’ and ‘<samp>`</samp>’ +retain their special meaning within double quotes (see <a href="#Shell-Expansions">Shell Expansions</a>). +The backslash retains its special meaning only when followed by one of +the following characters: +‘<samp>$</samp>’, ‘<samp>`</samp>’, ‘<samp>"</samp>’, ‘<samp>\</samp>’, or <code>newline</code>. +Within double quotes, backslashes that are followed by one of these +characters are removed. Backslashes preceding characters without a +special meaning are left unmodified. +A double quote may be quoted within double quotes by preceding it with +a backslash. +If enabled, history expansion will be performed unless an ‘<samp>!</samp>’ +appearing in double quotes is escaped using a backslash. +The backslash preceding the ‘<samp>!</samp>’ is not removed. +</p> +<p>The special parameters ‘<samp>*</samp>’ and ‘<samp>@</samp>’ have special meaning +when in double quotes (see <a href="#Shell-Parameter-Expansion">Shell Parameter Expansion</a>). +</p> +<hr> +</div> +<div class="subsubsection" id="ANSI_002dC-Quoting"> +<div class="header"> +<p> +Next: <a href="#Locale-Translation" accesskey="n" rel="next">Locale-Specific Translation</a>, Previous: <a href="#Double-Quotes" accesskey="p" rel="prev">Double Quotes</a>, Up: <a href="#Quoting" accesskey="u" rel="up">Quoting</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="ANSI_002dC-Quoting-1"></span><h4 class="subsubsection">3.1.2.4 ANSI-C Quoting</h4> +<span id="index-quoting_002c-ANSI"></span> + +<p>Character sequences of the form $’<var>string</var>’ are treated as a special +kind of single quotes. +The sequence expands to <var>string</var>, with backslash-escaped characters +in <var>string</var> replaced as specified by the ANSI C standard. +Backslash escape sequences, if present, are decoded as follows: +</p> +<dl compact="compact"> +<dt><span><code>\a</code></span></dt> +<dd><p>alert (bell) +</p></dd> +<dt><span><code>\b</code></span></dt> +<dd><p>backspace +</p></dd> +<dt><span><code>\e</code></span></dt> +<dt><span><code>\E</code></span></dt> +<dd><p>an escape character (not ANSI C) +</p></dd> +<dt><span><code>\f</code></span></dt> +<dd><p>form feed +</p></dd> +<dt><span><code>\n</code></span></dt> +<dd><p>newline +</p></dd> +<dt><span><code>\r</code></span></dt> +<dd><p>carriage return +</p></dd> +<dt><span><code>\t</code></span></dt> +<dd><p>horizontal tab +</p></dd> +<dt><span><code>\v</code></span></dt> +<dd><p>vertical tab +</p></dd> +<dt><span><code>\\</code></span></dt> +<dd><p>backslash +</p></dd> +<dt><span><code>\'</code></span></dt> +<dd><p>single quote +</p></dd> +<dt><span><code>\"</code></span></dt> +<dd><p>double quote +</p></dd> +<dt><span><code>\?</code></span></dt> +<dd><p>question mark +</p></dd> +<dt><span><code>\<var>nnn</var></code></span></dt> +<dd><p>the eight-bit character whose value is the octal value <var>nnn</var> +(one to three octal digits) +</p></dd> +<dt><span><code>\x<var>HH</var></code></span></dt> +<dd><p>the eight-bit character whose value is the hexadecimal value <var>HH</var> +(one or two hex digits) +</p></dd> +<dt><span><code>\u<var>HHHH</var></code></span></dt> +<dd><p>the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +<var>HHHH</var> (one to four hex digits) +</p></dd> +<dt><span><code>\U<var>HHHHHHHH</var></code></span></dt> +<dd><p>the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +<var>HHHHHHHH</var> (one to eight hex digits) +</p></dd> +<dt><span><code>\c<var>x</var></code></span></dt> +<dd><p>a control-<var>x</var> character +</p></dd> +</dl> + +<p>The expanded result is single-quoted, as if the dollar sign had not +been present. +</p> +<hr> +</div> +<div class="subsubsection" id="Locale-Translation"> +<div class="header"> +<p> +Previous: <a href="#ANSI_002dC-Quoting" accesskey="p" rel="prev">ANSI-C Quoting</a>, Up: <a href="#Quoting" accesskey="u" rel="up">Quoting</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Locale_002dSpecific-Translation"></span><h4 class="subsubsection">3.1.2.5 Locale-Specific Translation</h4> +<span id="index-localization"></span> +<span id="index-internationalization"></span> +<span id="index-native-languages"></span> +<span id="index-translation_002c-native-languages"></span> + +<p>Prefixing a double-quoted string with a dollar sign (‘<samp>$</samp>’), such +as <tt>$"hello, world"</tt>, +will cause the string to be translated according to the current locale. +The <code>gettext</code> infrastructure performs the lookup and +translation, using the <code>LC_MESSAGES</code>, <code>TEXTDOMAINDIR</code>, +and <code>TEXTDOMAIN</code> shell variables, as explained below. +See the gettext documentation for additional details not covered here. +If the current locale is <code>C</code> or <code>POSIX</code>, +if there are no translations available, +of if the string is not translated, +the dollar sign is ignored. +Since this is a form of double quoting, the string remains double-quoted +by default, whether or not it is translated and replaced. +If the <code>noexpand_translation</code> option is enabled +using the <code>shopt</code> builtin (see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>), +translated strings are single-quoted instead of double-quoted. +</p> +<p>The rest of this section is a brief overview of how you use gettext to +create translations for strings in a shell script named <var>scriptname</var>. +There are more details in the gettext documentation. +</p> +<hr> +<span id="Creating-Internationalized-Scripts"></span><div class="header"> +<p> + [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<h4 class="node-heading">Creating Internationalized Scripts</h4> +<span id="index-internationalized-scripts"></span> +<span id="index-string-translations"></span> +<p>Once you’ve marked the strings in your script +that you want to translate using $"...", +you create a gettext "template" file using the command +</p> +<div class="example"> +<pre class="example">bash --dump-po-strings <var>scriptname</var> > <var>domain</var>.pot +</pre></div> + +<p>The <var>domain</var> is your <em>message domain</em>. +It’s just an arbitrary string that’s used to identify the files gettext +needs, like a package or script name. +It needs to be unique among all +the message domains on systems where you install the translations, so +gettext knows which translations correspond to your script. +You’ll use the template file to create translations for each target language. +The template file conventionally has the suffix ‘<samp>.pot</samp>’. +</p> +<p>You copy this template file to a separate file for each target language +you want to support (called "PO" files, which use the suffix ‘<samp>.po</samp>’). +PO files use various naming conventions, but +when you are working to translate a template file into a particular +language, you first copy the template file to a file whose name is the +language you want to target, with the ‘<samp>.po</samp>’ suffix. +For instance, the Spanish translations of your strings would be +in a file named ‘<samp>es.po</samp>’, and to get started using a message +domain named "example," you would run +</p> +<div class="example"> +<pre class="example">cp example.pot es.po +</pre></div> + +<p>Ultimately, PO files are often named <var>domain</var>.po and installed in +directories that contain multiple translation files for a particular language. +</p> +<p>Whichever naming convention you choose, you will need to translate the +strings in the PO files into the appropriate languages. +This has to be done manually. +</p> +<p>When you have the translations and PO files complete, you’ll use the +gettext tools to produce what are called "MO" files, which are compiled +versions of the PO files the gettext tools use to look up translations +efficiently. +MO files are also called "message catalog" files. +You use the <code>msgfmt</code> program to do this. +For instance, if you had a file with Spanish translations, you could run +</p> +<div class="example"> +<pre class="example">msgfmt -o es.mo es.po +</pre></div> + +<p>to produce the corresponding MO file. +</p> +<p>Once you have the MO files, you decide where to install them and use the +<code>TEXTDOMAINDIR</code> shell variable to tell the gettext tools where they are. +Make sure to use the same message domain to name the MO files +as you did for the PO files when you install them. +</p> +<span id="index-LANG"></span> +<span id="index-LC_005fMESSAGES"></span> +<span id="index-TEXTDOMAIN"></span> +<span id="index-TEXTDOMAINDIR"></span> +<p>Your users will use the <code>LANG</code> or <code>LC_MESSAGES</code> shell variables to +select the desired language. +</p> +<p>You set the <code>TEXTDOMAIN</code> variable to the script’s message domain. +As above, you use the message domain to name your translation files. +</p> +<p>You, or possibly your users, set the <code>TEXTDOMAINDIR</code> variable to the +name of a directory where the message catalog files are stored. +If you install the message files into the system’s standard message catalog +directory, you don’t need to worry about this variable. +</p> +<p>The directory where the message catalog files are stored varies between +systems. +Some use the message catalog selected by the <code>LC_MESSAGES</code> +shell variable. +Others create the name of the message catalog from the value of the +<code>TEXTDOMAIN</code> shell variable, possibly adding the ‘<samp>.mo</samp>’ suffix. +If you use the <code>TEXTDOMAIN</code> variable, you may need to set the +<code>TEXTDOMAINDIR</code> variable to the location of the message catalog files, +as above. +It’s common to use both variables in this fashion: +<code>$TEXTDOMAINDIR</code>/<code>$LC_MESSAGES</code>/LC_MESSAGES/<code>$TEXTDOMAIN</code>.mo. +</p> +<p>If you used that last convention, and you wanted to store the message +catalog files with Spanish (es) and Esperanto (eo) translations into a +local directory you use for custom translation files, you could run +</p> +<div class="example"> +<pre class="example">TEXTDOMAIN=example +TEXTDOMAINDIR=/usr/local/share/locale + +cp es.mo ${TEXTDOMAINDIR}/es/LC_MESSAGES/${TEXTDOMAIN}.mo +cp eo.mo ${TEXTDOMAINDIR}/eo/LC_MESSAGES/${TEXTDOMAIN}.mo +</pre></div> + +<p>When all of this is done, and the message catalog files containing the +compiled translations are installed in the correct location, +your users will be able to see translated strings +in any of the supported languages by setting the <code>LANG</code> or +<code>LC_MESSAGES</code> environment variables before running your script. +</p> +<hr> +</div> +</div> +<div class="subsection" id="Comments"> +<div class="header"> +<p> +Previous: <a href="#Quoting" accesskey="p" rel="prev">Quoting</a>, Up: <a href="#Shell-Syntax" accesskey="u" rel="up">Shell Syntax</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Comments-1"></span><h4 class="subsection">3.1.3 Comments</h4> +<span id="index-comments_002c-shell"></span> + +<p>In a non-interactive shell, or an interactive shell in which the +<code>interactive_comments</code> option to the <code>shopt</code> +builtin is enabled (see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>), +a word beginning with ‘<samp>#</samp>’ +causes that word and all remaining characters on that line to +be ignored. An interactive shell without the <code>interactive_comments</code> +option enabled does not allow comments. The <code>interactive_comments</code> +option is on by default in interactive shells. +See <a href="#Interactive-Shells">Interactive Shells</a>, for a description of what makes +a shell interactive. +</p> +<hr> +</div> +</div> +<div class="section" id="Shell-Commands"> +<div class="header"> +<p> +Next: <a href="#Shell-Functions" accesskey="n" rel="next">Shell Functions</a>, Previous: <a href="#Shell-Syntax" accesskey="p" rel="prev">Shell Syntax</a>, Up: <a href="#Basic-Shell-Features" accesskey="u" rel="up">Basic Shell Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Shell-Commands-1"></span><h3 class="section">3.2 Shell Commands</h3> +<span id="index-commands_002c-shell"></span> + +<p>A simple shell command such as <code>echo a b c</code> consists of the command +itself followed by arguments, separated by spaces. +</p> +<p>More complex shell commands are composed of simple commands arranged together +in a variety of ways: in a pipeline in which the output of one command +becomes the input of a second, in a loop or conditional construct, or in +some other grouping. +</p> + +<ul class="section-toc"> +<li><a href="#Reserved-Words" accesskey="1">Reserved Words</a></li> +<li><a href="#Simple-Commands" accesskey="2">Simple Commands</a></li> +<li><a href="#Pipelines" accesskey="3">Pipelines</a></li> +<li><a href="#Lists" accesskey="4">Lists of Commands</a></li> +<li><a href="#Compound-Commands" accesskey="5">Compound Commands</a></li> +<li><a href="#Coprocesses" accesskey="6">Coprocesses</a></li> +<li><a href="#GNU-Parallel" accesskey="7">GNU Parallel</a></li> +</ul> +<hr> +<div class="subsection" id="Reserved-Words"> +<div class="header"> +<p> +Next: <a href="#Simple-Commands" accesskey="n" rel="next">Simple Commands</a>, Up: <a href="#Shell-Commands" accesskey="u" rel="up">Shell Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Reserved-Words-1"></span><h4 class="subsection">3.2.1 Reserved Words</h4> +<span id="index-reserved-words"></span> + +<p>Reserved words are words that have special meaning to the shell. +They are used to begin and end the shell’s compound commands. +</p> +<p>The following words are recognized as reserved when unquoted and +the first word of a command (see below for exceptions): +</p> +<table> +<tr><td width="10%"><code>if</code></td><td width="10%"><code>then</code></td><td width="10%"><code>elif</code></td><td width="10%"><code>else</code></td><td width="12%"><code>fi</code></td><td width="10%"><code>time</code></td></tr> +<tr><td width="10%"><code>for</code></td><td width="10%"><code>in</code></td><td width="10%"><code>until</code></td><td width="10%"><code>while</code></td><td width="12%"><code>do</code></td><td width="10%"><code>done</code></td></tr> +<tr><td width="10%"><code>case</code></td><td width="10%"><code>esac</code></td><td width="10%"><code>coproc</code></td><td width="10%"><code>select</code></td><td width="12%"><code>function</code></td></tr> +<tr><td width="10%"><code>{</code></td><td width="10%"><code>}</code></td><td width="10%"><code>[[</code></td><td width="10%"><code>]]</code></td><td width="12%"><code>!</code></td></tr> +</table> + +<p><code>in</code> is recognized as a reserved word if it is the third word of a +<code>case</code> or <code>select</code> command. +<code>in</code> and <code>do</code> are recognized as reserved +words if they are the third word in a <code>for</code> command. +</p> +<hr> +</div> +<div class="subsection" id="Simple-Commands"> +<div class="header"> +<p> +Next: <a href="#Pipelines" accesskey="n" rel="next">Pipelines</a>, Previous: <a href="#Reserved-Words" accesskey="p" rel="prev">Reserved Words</a>, Up: <a href="#Shell-Commands" accesskey="u" rel="up">Shell Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Simple-Commands-1"></span><h4 class="subsection">3.2.2 Simple Commands</h4> +<span id="index-commands_002c-simple"></span> + +<p>A simple command is the kind of command encountered most often. +It’s just a sequence of words separated by <code>blank</code>s, terminated +by one of the shell’s control operators (see <a href="#Definitions">Definitions</a>). The +first word generally specifies a command to be executed, with the +rest of the words being that command’s arguments. +</p> +<p>The return status (see <a href="#Exit-Status">Exit Status</a>) of a simple command is +its exit status as provided +by the <small>POSIX</small> 1003.1 <code>waitpid</code> function, or 128+<var>n</var> if +the command was terminated by signal <var>n</var>. +</p> +<hr> +</div> +<div class="subsection" id="Pipelines"> +<div class="header"> +<p> +Next: <a href="#Lists" accesskey="n" rel="next">Lists of Commands</a>, Previous: <a href="#Simple-Commands" accesskey="p" rel="prev">Simple Commands</a>, Up: <a href="#Shell-Commands" accesskey="u" rel="up">Shell Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Pipelines-1"></span><h4 class="subsection">3.2.3 Pipelines</h4> +<span id="index-pipeline"></span> +<span id="index-commands_002c-pipelines"></span> + +<p>A <code>pipeline</code> is a sequence of one or more commands separated by +one of the control operators ‘<samp>|</samp>’ or ‘<samp>|&</samp>’. +</p> +<span id="index-time"></span> +<span id="index-_0021"></span> +<span id="index-command-timing"></span> +<p>The format for a pipeline is +</p><div class="example"> +<pre class="example">[time [-p]] [!] <var>command1</var> [ | or |& <var>command2</var> ] … +</pre></div> + +<p>The output of each command in the pipeline is connected via a pipe +to the input of the next command. +That is, each command reads the previous command’s output. This +connection is performed before any redirections specified by +<var>command1</var>. +</p> +<p>If ‘<samp>|&</samp>’ is used, <var>command1</var>’s standard error, in addition to +its standard output, is connected to +<var>command2</var>’s standard input through the pipe; +it is shorthand for <code>2>&1 |</code>. +This implicit redirection of the standard error to the standard output is +performed after any redirections specified by <var>command1</var>. +</p> +<p>The reserved word <code>time</code> causes timing statistics +to be printed for the pipeline once it finishes. +The statistics currently consist of elapsed (wall-clock) time and +user and system time consumed by the command’s execution. +The <samp>-p</samp> option changes the output format to that specified +by <small>POSIX</small>. +When the shell is in <small>POSIX</small> mode (see <a href="#Bash-POSIX-Mode">Bash POSIX Mode</a>), +it does not recognize <code>time</code> as a reserved word if the next +token begins with a ‘<samp>-</samp>’. +The <code>TIMEFORMAT</code> variable may be set to a format string that +specifies how the timing information should be displayed. +See <a href="#Bash-Variables">Bash Variables</a>, for a description of the available formats. +The use of <code>time</code> as a reserved word permits the timing of +shell builtins, shell functions, and pipelines. An external +<code>time</code> command cannot time these easily. +</p> +<p>When the shell is in <small>POSIX</small> mode (see <a href="#Bash-POSIX-Mode">Bash POSIX Mode</a>), <code>time</code> +may be followed by a newline. In this case, the shell displays the +total user and system time consumed by the shell and its children. +The <code>TIMEFORMAT</code> variable may be used to specify the format of +the time information. +</p> +<p>If the pipeline is not executed asynchronously (see <a href="#Lists">Lists of Commands</a>), the +shell waits for all commands in the pipeline to complete. +</p> +<p>Each command in a multi-command pipeline, +where pipes are created, +is executed in its own <em>subshell</em>, which is a +separate process (see <a href="#Command-Execution-Environment">Command Execution Environment</a>). +If the <code>lastpipe</code> option is enabled using the <code>shopt</code> builtin +(see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>), +the last element of a pipeline may be run by the shell process +when job control is not active. +</p> +<p>The exit +status of a pipeline is the exit status of the last command in the +pipeline, unless the <code>pipefail</code> option is enabled +(see <a href="#The-Set-Builtin">The Set Builtin</a>). +If <code>pipefail</code> is enabled, the pipeline’s return status is the +value of the last (rightmost) command to exit with a non-zero status, +or zero if all commands exit successfully. +If the reserved word ‘<samp>!</samp>’ precedes the pipeline, the +exit status is the logical negation of the exit status as described +above. +The shell waits for all commands in the pipeline to terminate before +returning a value. +</p> +<hr> +</div> +<div class="subsection" id="Lists"> +<div class="header"> +<p> +Next: <a href="#Compound-Commands" accesskey="n" rel="next">Compound Commands</a>, Previous: <a href="#Pipelines" accesskey="p" rel="prev">Pipelines</a>, Up: <a href="#Shell-Commands" accesskey="u" rel="up">Shell Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Lists-of-Commands"></span><h4 class="subsection">3.2.4 Lists of Commands</h4> +<span id="index-commands_002c-lists"></span> + +<p>A <code>list</code> is a sequence of one or more pipelines separated by one +of the operators ‘<samp>;</samp>’, ‘<samp>&</samp>’, ‘<samp>&&</samp>’, or ‘<samp>||</samp>’, +and optionally terminated by one of ‘<samp>;</samp>’, ‘<samp>&</samp>’, or a +<code>newline</code>. +</p> +<p>Of these list operators, ‘<samp>&&</samp>’ and ‘<samp>||</samp>’ +have equal precedence, followed by ‘<samp>;</samp>’ and ‘<samp>&</samp>’, +which have equal precedence. +</p> +<p>A sequence of one or more newlines may appear in a <code>list</code> +to delimit commands, equivalent to a semicolon. +</p> +<p>If a command is terminated by the control operator ‘<samp>&</samp>’, +the shell executes the command asynchronously in a subshell. +This is known as executing the command in the <em>background</em>, +and these are referred to as <em>asynchronous</em> commands. +The shell does not wait for the command to finish, and the return +status is 0 (true). +When job control is not active (see <a href="#Job-Control">Job Control</a>), +the standard input for asynchronous commands, in the absence of any +explicit redirections, is redirected from <code>/dev/null</code>. +</p> +<p>Commands separated by a ‘<samp>;</samp>’ are executed sequentially; the shell +waits for each command to terminate in turn. The return status is the +exit status of the last command executed. +</p> +<p><small>AND</small> and <small>OR</small> lists are sequences of one or more pipelines +separated by the control operators ‘<samp>&&</samp>’ and ‘<samp>||</samp>’, +respectively. <small>AND</small> and <small>OR</small> lists are executed with left +associativity. +</p> +<p>An <small>AND</small> list has the form +</p><div class="example"> +<pre class="example"><var>command1</var> && <var>command2</var> +</pre></div> + +<p><var>command2</var> is executed if, and only if, <var>command1</var> +returns an exit status of zero (success). +</p> +<p>An <small>OR</small> list has the form +</p><div class="example"> +<pre class="example"><var>command1</var> || <var>command2</var> +</pre></div> + +<p><var>command2</var> is executed if, and only if, <var>command1</var> +returns a non-zero exit status. +</p> +<p>The return status of +<small>AND</small> and <small>OR</small> lists is the exit status of the last command +executed in the list. +</p> +<hr> +</div> +<div class="subsection" id="Compound-Commands"> +<div class="header"> +<p> +Next: <a href="#Coprocesses" accesskey="n" rel="next">Coprocesses</a>, Previous: <a href="#Lists" accesskey="p" rel="prev">Lists of Commands</a>, Up: <a href="#Shell-Commands" accesskey="u" rel="up">Shell Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Compound-Commands-1"></span><h4 class="subsection">3.2.5 Compound Commands</h4> +<span id="index-commands_002c-compound"></span> + + +<p>Compound commands are the shell programming language constructs. +Each construct begins with a reserved word or control operator and is +terminated by a corresponding reserved word or operator. +Any redirections (see <a href="#Redirections">Redirections</a>) associated with a compound command +apply to all commands within that compound command unless explicitly overridden. +</p> +<p>In most cases a list of commands in a compound command’s description may be +separated from the rest of the command by one or more newlines, and may be +followed by a newline in place of a semicolon. +</p> +<p>Bash provides looping constructs, conditional commands, and mechanisms +to group commands and execute them as a unit. +</p> +<ul class="section-toc"> +<li><a href="#Looping-Constructs" accesskey="1">Looping Constructs</a></li> +<li><a href="#Conditional-Constructs" accesskey="2">Conditional Constructs</a></li> +<li><a href="#Command-Grouping" accesskey="3">Grouping Commands</a></li> +</ul> +<hr> +<div class="subsubsection" id="Looping-Constructs"> +<div class="header"> +<p> +Next: <a href="#Conditional-Constructs" accesskey="n" rel="next">Conditional Constructs</a>, Up: <a href="#Compound-Commands" accesskey="u" rel="up">Compound Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Looping-Constructs-1"></span><h4 class="subsubsection">3.2.5.1 Looping Constructs</h4> +<span id="index-commands_002c-looping"></span> + +<p>Bash supports the following looping constructs. +</p> +<p>Note that wherever a ‘<samp>;</samp>’ appears in the description of a +command’s syntax, it may be replaced with one or more newlines. +</p> +<dl compact="compact"> +<dt id='index-until'><span><code>until</code><a href='#index-until' class='copiable-anchor'> ¶</a></span></dt> +<dd><span id="index-do"></span> +<span id="index-done"></span> +<p>The syntax of the <code>until</code> command is: +</p> +<div class="example"> +<pre class="example">until <var>test-commands</var>; do <var>consequent-commands</var>; done +</pre></div> + +<p>Execute <var>consequent-commands</var> as long as +<var>test-commands</var> has an exit status which is not zero. +The return status is the exit status of the last command executed +in <var>consequent-commands</var>, or zero if none was executed. +</p> +</dd> +<dt id='index-while'><span><code>while</code><a href='#index-while' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The syntax of the <code>while</code> command is: +</p> +<div class="example"> +<pre class="example">while <var>test-commands</var>; do <var>consequent-commands</var>; done +</pre></div> + +<p>Execute <var>consequent-commands</var> as long as +<var>test-commands</var> has an exit status of zero. +The return status is the exit status of the last command executed +in <var>consequent-commands</var>, or zero if none was executed. +</p> +</dd> +<dt id='index-for'><span><code>for</code><a href='#index-for' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The syntax of the <code>for</code> command is: +</p> +<div class="example"> +<pre class="example">for <var>name</var> [ [in [<var>words</var> …] ] ; ] do <var>commands</var>; done +</pre></div> + +<p>Expand <var>words</var> (see <a href="#Shell-Expansions">Shell Expansions</a>), and execute <var>commands</var> +once for each member +in the resultant list, with <var>name</var> bound to the current member. +If ‘<samp>in <var>words</var></samp>’ is not present, the <code>for</code> command +executes the <var>commands</var> once for each positional parameter that is +set, as if ‘<samp>in "$@"</samp>’ had been specified +(see <a href="#Special-Parameters">Special Parameters</a>). +</p> +<p>The return status is the exit status of the last command that executes. +If there are no items in the expansion of <var>words</var>, no commands are +executed, and the return status is zero. +</p> +<p>An alternate form of the <code>for</code> command is also supported: +</p> +<div class="example"> +<pre class="example">for (( <var>expr1</var> ; <var>expr2</var> ; <var>expr3</var> )) ; do <var>commands</var> ; done +</pre></div> + +<p>First, the arithmetic expression <var>expr1</var> is evaluated according +to the rules described below (see <a href="#Shell-Arithmetic">Shell Arithmetic</a>). +The arithmetic expression <var>expr2</var> is then evaluated repeatedly +until it evaluates to zero. +Each time <var>expr2</var> evaluates to a non-zero value, <var>commands</var> are +executed and the arithmetic expression <var>expr3</var> is evaluated. +If any expression is omitted, it behaves as if it evaluates to 1. +The return value is the exit status of the last command in <var>commands</var> +that is executed, or false if any of the expressions is invalid. +</p></dd> +</dl> + +<p>The <code>break</code> and <code>continue</code> builtins (see <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>) +may be used to control loop execution. +</p> +<hr> +</div> +<div class="subsubsection" id="Conditional-Constructs"> +<div class="header"> +<p> +Next: <a href="#Command-Grouping" accesskey="n" rel="next">Grouping Commands</a>, Previous: <a href="#Looping-Constructs" accesskey="p" rel="prev">Looping Constructs</a>, Up: <a href="#Compound-Commands" accesskey="u" rel="up">Compound Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Conditional-Constructs-1"></span><h4 class="subsubsection">3.2.5.2 Conditional Constructs</h4> +<span id="index-commands_002c-conditional"></span> + +<dl compact="compact"> +<dt id='index-if'><span><code>if</code><a href='#index-if' class='copiable-anchor'> ¶</a></span></dt> +<dd><span id="index-then"></span> +<span id="index-else"></span> +<span id="index-elif"></span> +<span id="index-fi"></span> +<p>The syntax of the <code>if</code> command is: +</p> +<div class="example"> +<pre class="example">if <var>test-commands</var>; then + <var>consequent-commands</var>; +[elif <var>more-test-commands</var>; then + <var>more-consequents</var>;] +[else <var>alternate-consequents</var>;] +fi +</pre></div> + +<p>The <var>test-commands</var> list is executed, and if its return status is zero, +the <var>consequent-commands</var> list is executed. +If <var>test-commands</var> returns a non-zero status, each <code>elif</code> list +is executed in turn, and if its exit status is zero, +the corresponding <var>more-consequents</var> is executed and the +command completes. +If ‘<samp>else <var>alternate-consequents</var></samp>’ is present, and +the final command in the final <code>if</code> or <code>elif</code> clause +has a non-zero exit status, then <var>alternate-consequents</var> is executed. +The return status is the exit status of the last command executed, or +zero if no condition tested true. +</p> +</dd> +<dt id='index-case'><span><code>case</code><a href='#index-case' class='copiable-anchor'> ¶</a></span></dt> +<dd><span id="index-in"></span> +<span id="index-esac"></span> +<p>The syntax of the <code>case</code> command is: +</p> +<div class="example"> +<pre class="example">case <var>word</var> in + [ [(] <var>pattern</var> [| <var>pattern</var>]…) <var>command-list</var> ;;]… +esac +</pre></div> + +<p><code>case</code> will selectively execute the <var>command-list</var> corresponding to +the first <var>pattern</var> that matches <var>word</var>. +The match is performed according +to the rules described below in <a href="#Pattern-Matching">Pattern Matching</a>. +If the <code>nocasematch</code> shell option +(see the description of <code>shopt</code> in <a href="#The-Shopt-Builtin">The Shopt Builtin</a>) +is enabled, the match is performed without regard to the case +of alphabetic characters. +The ‘<samp>|</samp>’ is used to separate multiple patterns, and the ‘<samp>)</samp>’ +operator terminates a pattern list. +A list of patterns and an associated command-list is known +as a <var>clause</var>. +</p> +<p>Each clause must be terminated with ‘<samp>;;</samp>’, ‘<samp>;&</samp>’, or ‘<samp>;;&</samp>’. +The <var>word</var> undergoes tilde expansion, parameter expansion, command +substitution, arithmetic expansion, and quote removal +(see <a href="#Shell-Parameter-Expansion">Shell Parameter Expansion</a>) +before matching is attempted. +Each <var>pattern</var> undergoes tilde expansion, parameter expansion, +command substitution, arithmetic expansion, process substitution, and +quote removal. +</p> +<p>There may be an arbitrary number of <code>case</code> clauses, each terminated +by a ‘<samp>;;</samp>’, ‘<samp>;&</samp>’, or ‘<samp>;;&</samp>’. +The first pattern that matches determines the +command-list that is executed. +It’s a common idiom to use ‘<samp>*</samp>’ as the final pattern to define the +default case, since that pattern will always match. +</p> +<p>Here is an example using <code>case</code> in a script that could be used to +describe one interesting feature of an animal: +</p> +<div class="example"> +<pre class="example">echo -n "Enter the name of an animal: " +read ANIMAL +echo -n "The $ANIMAL has " +case $ANIMAL in + horse | dog | cat) echo -n "four";; + man | kangaroo ) echo -n "two";; + *) echo -n "an unknown number of";; +esac +echo " legs." +</pre></div> + + +<p>If the ‘<samp>;;</samp>’ operator is used, no subsequent matches are attempted after +the first pattern match. +Using ‘<samp>;&</samp>’ in place of ‘<samp>;;</samp>’ causes execution to continue with +the <var>command-list</var> associated with the next clause, if any. +Using ‘<samp>;;&</samp>’ in place of ‘<samp>;;</samp>’ causes the shell to test the patterns +in the next clause, if any, and execute any associated <var>command-list</var> +on a successful match, +continuing the case statement execution as if the pattern list had not matched. +</p> +<p>The return status is zero if no <var>pattern</var> is matched. Otherwise, the +return status is the exit status of the <var>command-list</var> executed. +</p> +</dd> +<dt id='index-select'><span><code>select</code><a href='#index-select' class='copiable-anchor'> ¶</a></span></dt> +<dd> +<p>The <code>select</code> construct allows the easy generation of menus. +It has almost the same syntax as the <code>for</code> command: +</p> +<div class="example"> +<pre class="example">select <var>name</var> [in <var>words</var> …]; do <var>commands</var>; done +</pre></div> + +<p>The list of words following <code>in</code> is expanded, generating a list +of items, and the set of expanded words is printed on the standard +error output stream, each preceded by a number. If the +‘<samp>in <var>words</var></samp>’ is omitted, the positional parameters are printed, +as if ‘<samp>in "$@"</samp>’ had been specified. +<code>select</code> then displays the <code>PS3</code> +prompt and reads a line from the standard input. +If the line consists of a number corresponding to one of the displayed +words, then the value of <var>name</var> is set to that word. +If the line is empty, the words and prompt are displayed again. +If <code>EOF</code> is read, the <code>select</code> command completes and returns 1. +Any other value read causes <var>name</var> to be set to null. +The line read is saved in the variable <code>REPLY</code>. +</p> +<p>The <var>commands</var> are executed after each selection until a +<code>break</code> command is executed, at which +point the <code>select</code> command completes. +</p> +<p>Here is an example that allows the user to pick a filename from the +current directory, and displays the name and index of the file +selected. +</p> +<div class="example"> +<pre class="example">select fname in *; +do + echo you picked $fname \($REPLY\) + break; +done +</pre></div> + +</dd> +<dt><span><code>((…))</code></span></dt> +<dd><div class="example"> +<pre class="example">(( <var>expression</var> )) +</pre></div> + +<p>The arithmetic <var>expression</var> is evaluated according to the rules +described below (see <a href="#Shell-Arithmetic">Shell Arithmetic</a>). +The <var>expression</var> undergoes the same expansions +as if it were within double quotes, +but double quote characters in <var>expression</var> are not treated specially +are removed. +If the value of the expression is non-zero, the return status is 0; +otherwise the return status is 1. +</p> + +</dd> +<dt id='index-_005b_005b'><span><code>[[…]]</code><a href='#index-_005b_005b' class='copiable-anchor'> ¶</a></span></dt> +<dd><span id="index-_005d_005d"></span> +<div class="example"> +<pre class="example">[[ <var>expression</var> ]] +</pre></div> + +<p>Return a status of 0 or 1 depending on the evaluation of +the conditional expression <var>expression</var>. +Expressions are composed of the primaries described below in +<a href="#Bash-Conditional-Expressions">Bash Conditional Expressions</a>. +The words between the <code>[[</code> and <code>]]</code> do not undergo word splitting +and filename expansion. +The shell performs tilde expansion, parameter and +variable expansion, arithmetic expansion, command substitution, process +substitution, and quote removal on those words +(the expansions that would occur if the words were enclosed in double quotes). +Conditional operators such as ‘<samp>-f</samp>’ must be unquoted to be recognized +as primaries. +</p> +<p>When used with <code>[[</code>, the ‘<samp><</samp>’ and ‘<samp>></samp>’ operators sort +lexicographically using the current locale. +</p> +<p>When the ‘<samp>==</samp>’ and ‘<samp>!=</samp>’ operators are used, the string to the +right of the operator is considered a pattern and matched according +to the rules described below in <a href="#Pattern-Matching">Pattern Matching</a>, +as if the <code>extglob</code> shell option were enabled. +The ‘<samp>=</samp>’ operator is identical to ‘<samp>==</samp>’. +If the <code>nocasematch</code> shell option +(see the description of <code>shopt</code> in <a href="#The-Shopt-Builtin">The Shopt Builtin</a>) +is enabled, the match is performed without regard to the case +of alphabetic characters. +The return value is 0 if the string matches (‘<samp>==</samp>’) or does not +match (‘<samp>!=</samp>’) the pattern, and 1 otherwise. +</p> +<p>If you quote any part of the pattern, +using any of the shell’s quoting mechanisms, +the quoted portion is matched literally. +This means every character in the quoted portion matches itself, +instead of having any special pattern matching meaning. +</p> +<p>An additional binary operator, ‘<samp>=~</samp>’, is available, with the same +precedence as ‘<samp>==</samp>’ and ‘<samp>!=</samp>’. +When you use ‘<samp>=~</samp>’, the string to the right of the operator is considered +a <small>POSIX</small> extended regular expression pattern and matched accordingly +(using the <small>POSIX</small> <code>regcomp</code> and <code>regexec</code> interfaces +usually described in <i>regex</i>(3)). +The return value is 0 if the string matches the pattern, and 1 if it does not. +If the regular expression is syntactically incorrect, the conditional +expression returns 2. +If the <code>nocasematch</code> shell option +(see the description of <code>shopt</code> in <a href="#The-Shopt-Builtin">The Shopt Builtin</a>) +is enabled, the match is performed without regard to the case +of alphabetic characters. +</p> +<p>You can quote any part of the pattern +to force the quoted portion to be matched literally +instead of as a regular expression (see above). +If the pattern is stored in a shell variable, quoting the variable +expansion forces the entire pattern to be matched literally. +</p> +<p>The pattern will match if it matches any part of the string. +If you want to force the pattern to match the entire string, +anchor the pattern using the ‘<samp>^</samp>’ and ‘<samp>$</samp>’ regular expression +operators. +</p> +<p>For example, the following will match a line +(stored in the shell variable <code>line</code>) +if there is a sequence of characters anywhere in the value consisting of +any number, including zero, of +characters in the <code>space</code> character class, +immediately followed by zero or one instances of ‘<samp>a</samp>’, +then a ‘<samp>b</samp>’: +</p> +<div class="example"> +<pre class="example">[[ $line =~ [[:space:]]*(a)?b ]] +</pre></div> + +<p>That means values for <code>line</code> like +‘<samp>aab</samp>’, ‘<samp> aaaaaab</samp>’, ‘<samp>xaby</samp>’, and ‘<samp> ab</samp>’ +will all match, +as will a line containing a ‘<samp>b</samp>’ anywhere in its value. +</p> +<p>If you want to match a character that’s special to the regular expression +grammar (‘<samp>^$|[]()\.*+?</samp>’), it has to be quoted to remove its special +meaning. +This means that in the pattern ‘<samp>xxx.txt</samp>’, the ‘<samp>.</samp>’ matches any +character in the string (its usual regular expression meaning), but in the +pattern ‘<samp>"xxx.txt"</samp>’, it can only match a literal ‘<samp>.</samp>’. +</p> +<p>Likewise, if you want to include a character in your pattern that has a +special meaning to the regular expression grammar, you must make sure it’s +not quoted. +If you want to anchor a pattern at the beginning or end of the string, +for instance, you cannot quote the ‘<samp>^</samp>’ or ‘<samp>$</samp>’ +characters using any form of shell quoting. +</p> +<p>If you want to match ‘<samp>initial string</samp>’ at the start of a line, +the following will work: +</p><div class="example"> +<pre class="example">[[ $line =~ ^"initial string" ]] +</pre></div> +<p>but this will not: +</p><div class="example"> +<pre class="example">[[ $line =~ "^initial string" ]] +</pre></div> +<p>because in the second example the ‘<samp>^</samp>’ is quoted and doesn’t have its +usual special meaning. +</p> +<p>It is sometimes difficult to specify a regular expression properly +without using quotes, or to keep track of the quoting used by regular +expressions while paying attention to +shell quoting and the shell’s quote removal. +Storing the regular expression in a shell variable is often a useful +way to avoid problems with quoting characters that are special to the +shell. +For example, the following is equivalent to the pattern used above: +</p> +<div class="example"> +<pre class="example">pattern='[[:space:]]*(a)?b' +[[ $line =~ $pattern ]] +</pre></div> + +<p>Shell programmers should take special care with backslashes, since +backslashes are used by both the shell and regular expressions to remove +the special meaning from the following character. +This means that after the shell’s word expansions complete +(see <a href="#Shell-Expansions">Shell Expansions</a>), +any backslashes remaining in parts of the pattern +that were originally not quoted can remove the +special meaning of pattern characters. +If any part of the pattern is quoted, the shell does its best to ensure that +the regular expression treats those remaining backslashes as literal, +if they appeared in a quoted portion. +</p> +<p>The following two sets of commands are <em>not</em> equivalent: +</p> +<div class="example"> +<pre class="example">pattern='\.' + +[[ . =~ $pattern ]] +[[ . =~ \. ]] + +[[ . =~ "$pattern" ]] +[[ . =~ '\.' ]] +</pre></div> + +<p>The first two matches will succeed, but the second two will not, because +in the second two the backslash will be part of the pattern to be matched. +In the first two examples, the pattern passed to the regular expression +parser is ‘<samp>\.</samp>’. The backslash removes the special meaning from +‘<samp>.</samp>’, so the literal ‘<samp>.</samp>’ matches. +In the second two examples, the pattern passed to the regular expression +parser has the backslash quoted (e.g., ‘<samp>\\\.</samp>’), which will not match +the string, since it does not contain a backslash. +If the string in the first examples were anything other than ‘<samp>.</samp>’, say +‘<samp>a</samp>’, the pattern would not match, because the quoted ‘<samp>.</samp>’ in the +pattern loses its special meaning of matching any single character. +</p> +<p>Bracket expressions in regular expressions can be sources of errors as well, +since characters that are normally special in regular expressions +lose their special meanings between brackets. +However, you can use bracket expressions to match special pattern characters +without quoting them, so they are sometimes useful for this purpose. +</p> +<p>Though it might seem like a strange way to write it, the following pattern +will match a ‘<samp>.</samp>’ in the string: +</p> +<div class="example"> +<pre class="example">[[ . =~ [.] ]] +</pre></div> + +<p>The shell performs any word expansions before passing the pattern +to the regular expression functions, +so you can assume that the shell’s quoting takes precedence. +As noted above, the regular expression parser will interpret any +unquoted backslashes remaining in the pattern after shell expansion +according to its own rules. +The intention is to avoid making shell programmers quote things twice +as much as possible, so shell quoting should be sufficient to quote +special pattern characters where that’s necessary. +</p> +<p>The array variable <code>BASH_REMATCH</code> records which parts of the string +matched the pattern. +The element of <code>BASH_REMATCH</code> with index 0 contains the portion of +the string matching the entire regular expression. +Substrings matched by parenthesized subexpressions within the regular +expression are saved in the remaining <code>BASH_REMATCH</code> indices. +The element of <code>BASH_REMATCH</code> with index <var>n</var> is the portion of the +string matching the <var>n</var>th parenthesized subexpression. +</p> +<p>Bash sets +<code>BASH_REMATCH</code> +in the global scope; declaring it as a local variable will lead to +unexpected results. +</p> +<p>Expressions may be combined using the following operators, listed +in decreasing order of precedence: +</p> +<dl compact="compact"> +<dt><span><code>( <var>expression</var> )</code></span></dt> +<dd><p>Returns the value of <var>expression</var>. +This may be used to override the normal precedence of operators. +</p> +</dd> +<dt><span><code>! <var>expression</var></code></span></dt> +<dd><p>True if <var>expression</var> is false. +</p> +</dd> +<dt><span><code><var>expression1</var> && <var>expression2</var></code></span></dt> +<dd><p>True if both <var>expression1</var> and <var>expression2</var> are true. +</p> +</dd> +<dt><span><code><var>expression1</var> || <var>expression2</var></code></span></dt> +<dd><p>True if either <var>expression1</var> or <var>expression2</var> is true. +</p></dd> +</dl> + +<p>The <code>&&</code> and <code>||</code> operators do not evaluate <var>expression2</var> if the +value of <var>expression1</var> is sufficient to determine the return +value of the entire conditional expression. +</p></dd> +</dl> + +<hr> +</div> +<div class="subsubsection" id="Command-Grouping"> +<div class="header"> +<p> +Previous: <a href="#Conditional-Constructs" accesskey="p" rel="prev">Conditional Constructs</a>, Up: <a href="#Compound-Commands" accesskey="u" rel="up">Compound Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Grouping-Commands"></span><h4 class="subsubsection">3.2.5.3 Grouping Commands</h4> +<span id="index-commands_002c-grouping"></span> + +<p>Bash provides two ways to group a list of commands to be executed +as a unit. When commands are grouped, redirections may be applied +to the entire command list. For example, the output of all the +commands in the list may be redirected to a single stream. +</p> +<dl compact="compact"> +<dt><span><code>()</code></span></dt> +<dd><div class="example"> +<pre class="example">( <var>list</var> ) +</pre></div> + +<p>Placing a list of commands between parentheses forces the shell to create +a subshell (see <a href="#Command-Execution-Environment">Command Execution Environment</a>), and each +of the commands in <var>list</var> is executed in that subshell environment. +Since the <var>list</var> is executed in a subshell, variable assignments do not +remain in effect after the subshell completes. +</p> +</dd> +<dt id='index-_007b'><span><code>{}</code><a href='#index-_007b' class='copiable-anchor'> ¶</a></span></dt> +<dd><span id="index-_007d"></span> +<div class="example"> +<pre class="example">{ <var>list</var>; } +</pre></div> + +<p>Placing a list of commands between curly braces causes the list to +be executed in the current shell context. No subshell is created. +The semicolon (or newline) following <var>list</var> is required. +</p></dd> +</dl> + +<p>In addition to the creation of a subshell, there is a subtle difference +between these two constructs due to historical reasons. The braces +are reserved words, so they must be separated from the <var>list</var> +by <code>blank</code>s or other shell metacharacters. +The parentheses are operators, and are +recognized as separate tokens by the shell even if they are not separated +from the <var>list</var> by whitespace. +</p> +<p>The exit status of both of these constructs is the exit status of +<var>list</var>. +</p> +<hr> +</div> +</div> +<div class="subsection" id="Coprocesses"> +<div class="header"> +<p> +Next: <a href="#GNU-Parallel" accesskey="n" rel="next">GNU Parallel</a>, Previous: <a href="#Compound-Commands" accesskey="p" rel="prev">Compound Commands</a>, Up: <a href="#Shell-Commands" accesskey="u" rel="up">Shell Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Coprocesses-1"></span><h4 class="subsection">3.2.6 Coprocesses</h4> +<span id="index-coprocess"></span> + +<p>A <code>coprocess</code> is a shell command preceded by the <code>coproc</code> +reserved word. +A coprocess is executed asynchronously in a subshell, as if the command +had been terminated with the ‘<samp>&</samp>’ control operator, with a two-way pipe +established between the executing shell and the coprocess. +</p> +<p>The syntax for a coprocess is: +</p> +<div class="example"> +<pre class="example">coproc [<var>NAME</var>] <var>command</var> [<var>redirections</var>] +</pre></div> + +<p>This creates a coprocess named <var>NAME</var>. +<var>command</var> may be either a simple command (see <a href="#Simple-Commands">Simple Commands</a>) +or a compound command (see <a href="#Compound-Commands">Compound Commands</a>). +<var>NAME</var> is a shell variable name. +If <var>NAME</var> is not supplied, the default name is <code>COPROC</code>. +</p> +<p>The recommended form to use for a coprocess is +</p> +<div class="example"> +<pre class="example">coproc <var>NAME</var> { <var>command</var>; } +</pre></div> + +<p>This form is recommended because simple commands result in the coprocess +always being named <code>COPROC</code>, and it is simpler to use and more complete +than the other compound commands. +</p> +<p>There are other forms of coprocesses: +</p> +<div class="example"> +<pre class="example">coproc <var>NAME</var> <var>compound-command</var> +coproc <var>compound-command</var> +coproc <var>simple-command</var> +</pre></div> + +<p>If <var>command</var> is a compound command, <var>NAME</var> is optional. The +word following <code>coproc</code> determines whether that word is interpreted +as a variable name: it is interpreted as <var>NAME</var> if it is not a +reserved word that introduces a compound command. +If <var>command</var> is a simple command, <var>NAME</var> is not allowed; this +is to avoid confusion between <var>NAME</var> and the first word of the simple +command. +</p> +<p>When the coprocess is executed, the shell creates an array variable +(see <a href="#Arrays">Arrays</a>) +named <var>NAME</var> in the context of the executing shell. +The standard output of <var>command</var> +is connected via a pipe to a file descriptor in the executing shell, +and that file descriptor is assigned to <var>NAME</var>[0]. +The standard input of <var>command</var> +is connected via a pipe to a file descriptor in the executing shell, +and that file descriptor is assigned to <var>NAME</var>[1]. +This pipe is established before any redirections specified by the +command (see <a href="#Redirections">Redirections</a>). +The file descriptors can be utilized as arguments to shell commands +and redirections using standard word expansions. +Other than those created to execute command and process substitutions, +the file descriptors are not available in subshells. +</p> +<p>The process ID of the shell spawned to execute the coprocess is +available as the value of the variable <code><var>NAME</var>_PID</code>. +The <code>wait</code> +builtin command may be used to wait for the coprocess to terminate. +</p> +<p>Since the coprocess is created as an asynchronous command, +the <code>coproc</code> command always returns success. +The return status of a coprocess is the exit status of <var>command</var>. +</p> +<hr> +</div> +<div class="subsection" id="GNU-Parallel"> +<div class="header"> +<p> +Previous: <a href="#Coprocesses" accesskey="p" rel="prev">Coprocesses</a>, Up: <a href="#Shell-Commands" accesskey="u" rel="up">Shell Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="GNU-Parallel-1"></span><h4 class="subsection">3.2.7 GNU Parallel</h4> + +<p>There are ways to run commands in parallel that are not built into Bash. +GNU Parallel is a tool to do just that. +</p> +<p>GNU Parallel, as its name suggests, can be used to build and run commands +in parallel. You may run the same command with different arguments, whether +they are filenames, usernames, hostnames, or lines read from files. GNU +Parallel provides shorthand references to many of the most common operations +(input lines, various portions of the input line, different ways to specify +the input source, and so on). Parallel can replace <code>xargs</code> or feed +commands from its input sources to several different instances of Bash. +</p> +<p>For a complete description, refer to the GNU Parallel documentation, which +is available at +<a href="https://www.gnu.org/software/parallel/parallel_tutorial.html">https://www.gnu.org/software/parallel/parallel_tutorial.html</a>. +</p> +<hr> +</div> +</div> +<div class="section" id="Shell-Functions"> +<div class="header"> +<p> +Next: <a href="#Shell-Parameters" accesskey="n" rel="next">Shell Parameters</a>, Previous: <a href="#Shell-Commands" accesskey="p" rel="prev">Shell Commands</a>, Up: <a href="#Basic-Shell-Features" accesskey="u" rel="up">Basic Shell Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Shell-Functions-1"></span><h3 class="section">3.3 Shell Functions</h3> +<span id="index-shell-function"></span> +<span id="index-functions_002c-shell"></span> + +<p>Shell functions are a way to group commands for later execution +using a single name for the group. They are executed just like +a "regular" command. +When the name of a shell function is used as a simple command name, +the list of commands associated with that function name is executed. +Shell functions are executed in the current +shell context; no new process is created to interpret them. +</p> +<p>Functions are declared using this syntax: +<span id="index-function"></span> +</p><div class="example"> +<pre class="example"><var>fname</var> () <var>compound-command</var> [ <var>redirections</var> ] +</pre></div> + +<p>or +</p> +<div class="example"> +<pre class="example">function <var>fname</var> [()] <var>compound-command</var> [ <var>redirections</var> ] +</pre></div> + +<p>This defines a shell function named <var>fname</var>. The reserved +word <code>function</code> is optional. +If the <code>function</code> reserved +word is supplied, the parentheses are optional. +The <em>body</em> of the function is the compound command +<var>compound-command</var> (see <a href="#Compound-Commands">Compound Commands</a>). +That command is usually a <var>list</var> enclosed between { and }, but +may be any compound command listed above. +If the <code>function</code> reserved word is used, but the +parentheses are not supplied, the braces are recommended. +<var>compound-command</var> is executed whenever <var>fname</var> is specified as the +name of a simple command. +When the shell is in <small>POSIX</small> mode (see <a href="#Bash-POSIX-Mode">Bash POSIX Mode</a>), +<var>fname</var> must be a valid shell name and +may not be the same as one of the special builtins +(see <a href="#Special-Builtins">Special Builtins</a>). +In default mode, a function name can be any unquoted shell word that does +not contain ‘<samp>$</samp>’. +Any redirections (see <a href="#Redirections">Redirections</a>) associated with the shell function +are performed when the function is executed. +A function definition may be deleted using the <samp>-f</samp> option to the +<code>unset</code> builtin (see <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>). +</p> +<p>The exit status of a function definition is zero unless a syntax error +occurs or a readonly function with the same name already exists. +When executed, the exit status of a function is the exit status of the +last command executed in the body. +</p> +<p>Note that for historical reasons, in the most common usage the curly braces +that surround the body of the function must be separated from the body by +<code>blank</code>s or newlines. +This is because the braces are reserved words and are only recognized +as such when they are separated from the command list +by whitespace or another shell metacharacter. +Also, when using the braces, the <var>list</var> must be terminated by a semicolon, +a ‘<samp>&</samp>’, or a newline. +</p> +<p>When a function is executed, the arguments to the +function become the positional parameters +during its execution (see <a href="#Positional-Parameters">Positional Parameters</a>). +The special parameter ‘<samp>#</samp>’ that expands to the number of +positional parameters is updated to reflect the change. +Special parameter <code>0</code> is unchanged. +The first element of the <code>FUNCNAME</code> variable is set to the +name of the function while the function is executing. +</p> +<p>All other aspects of the shell execution +environment are identical between a function and its caller +with these exceptions: +the <code>DEBUG</code> and <code>RETURN</code> traps +are not inherited unless the function has been given the +<code>trace</code> attribute using the <code>declare</code> builtin or +the <code>-o functrace</code> option has been enabled with +the <code>set</code> builtin, +(in which case all functions inherit the <code>DEBUG</code> and <code>RETURN</code> traps), +and the <code>ERR</code> trap is not inherited unless the <code>-o errtrace</code> +shell option has been enabled. +See <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>, for the description of the +<code>trap</code> builtin. +</p> +<p>The <code>FUNCNEST</code> variable, if set to a numeric value greater +than 0, defines a maximum function nesting level. Function +invocations that exceed the limit cause the entire command to +abort. +</p> +<p>If the builtin command <code>return</code> +is executed in a function, the function completes and +execution resumes with the next command after the function +call. +Any command associated with the <code>RETURN</code> trap is executed +before execution resumes. +When a function completes, the values of the +positional parameters and the special parameter ‘<samp>#</samp>’ +are restored to the values they had prior to the function’s +execution. If a numeric argument is given to <code>return</code>, +that is the function’s return status; otherwise the function’s +return status is the exit status of the last command executed +before the <code>return</code>. +</p> +<p>Variables local to the function may be declared with the +<code>local</code> builtin (<em>local variables</em>). +Ordinarily, variables and their values +are shared between a function and its caller. +These variables are visible only to +the function and the commands it invokes. This is particularly +important when a shell function calls other functions. +</p> +<p>In the following description, the <em>current scope</em> is a currently- +executing function. +Previous scopes consist of that function’s caller and so on, +back to the "global" scope, where the shell is not executing +any shell function. +Consequently, a local variable at the current local scope is a variable +declared using the <code>local</code> or <code>declare</code> builtins in the +function that is currently executing. +</p> +<p>Local variables "shadow" variables with the same name declared at +previous scopes. For instance, a local variable declared in a function +hides a global variable of the same name: references and assignments +refer to the local variable, leaving the global variable unmodified. +When the function returns, the global variable is once again visible. +</p> +<p>The shell uses <em>dynamic scoping</em> to control a variable’s visibility +within functions. +With dynamic scoping, visible variables and their values +are a result of the sequence of function calls that caused execution +to reach the current function. +The value of a variable that a function sees depends +on its value within its caller, if any, whether that caller is +the "global" scope or another shell function. +This is also the value that a local variable +declaration "shadows", and the value that is restored when the function +returns. +</p> +<p>For example, if a variable <code>var</code> is declared as local in function +<code>func1</code>, and <code>func1</code> calls another function <code>func2</code>, +references to <code>var</code> made from within <code>func2</code> will resolve to the +local variable <code>var</code> from <code>func1</code>, shadowing any global variable +named <code>var</code>. +</p> +<p>The following script demonstrates this behavior. +When executed, the script displays +</p> +<div class="example"> +<pre class="example">In func2, var = func1 local +</pre></div> + +<div class="example"> +<pre class="example">func1() +{ + local var='func1 local' + func2 +} + +func2() +{ + echo "In func2, var = $var" +} + +var=global +func1 +</pre></div> + +<p>The <code>unset</code> builtin also acts using the same dynamic scope: if a +variable is local to the current scope, <code>unset</code> will unset it; +otherwise the unset will refer to the variable found in any calling scope +as described above. +If a variable at the current local scope is unset, it will remain so +(appearing as unset) +until it is reset in that scope or until the function returns. +Once the function returns, any instance of the variable at a previous +scope will become visible. +If the unset acts on a variable at a previous scope, any instance of a +variable with that name that had been shadowed will become visible +(see below how <code>localvar_unset</code>shell option changes this behavior). +</p> +<p>Function names and definitions may be listed with the +<samp>-f</samp> option to the <code>declare</code> (<code>typeset</code>) +builtin command (see <a href="#Bash-Builtins">Bash Builtin Commands</a>). +The <samp>-F</samp> option to <code>declare</code> or <code>typeset</code> +will list the function names only +(and optionally the source file and line number, if the <code>extdebug</code> +shell option is enabled). +Functions may be exported so that child shell processes +(those created when executing a separate shell invocation) +automatically have them defined with the +<samp>-f</samp> option to the <code>export</code> builtin +(see <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>). +</p> +<p>Functions may be recursive. +The <code>FUNCNEST</code> variable may be used to limit the depth of the +function call stack and restrict the number of function invocations. +By default, no limit is placed on the number of recursive calls. +</p> +<hr> +</div> +<div class="section" id="Shell-Parameters"> +<div class="header"> +<p> +Next: <a href="#Shell-Expansions" accesskey="n" rel="next">Shell Expansions</a>, Previous: <a href="#Shell-Functions" accesskey="p" rel="prev">Shell Functions</a>, Up: <a href="#Basic-Shell-Features" accesskey="u" rel="up">Basic Shell Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Shell-Parameters-1"></span><h3 class="section">3.4 Shell Parameters</h3> +<span id="index-parameters"></span> +<span id="index-variable_002c-shell"></span> +<span id="index-shell-variable"></span> + + +<p>A <em>parameter</em> is an entity that stores values. +It can be a <code>name</code>, a number, or one of the special characters +listed below. +A <em>variable</em> is a parameter denoted by a <code>name</code>. +A variable has a <code>value</code> and zero or more <code>attributes</code>. +Attributes are assigned using the <code>declare</code> builtin command +(see the description of the <code>declare</code> builtin in <a href="#Bash-Builtins">Bash Builtin Commands</a>). +</p> +<p>A parameter is set if it has been assigned a value. The null string is +a valid value. Once a variable is set, it may be unset only by using +the <code>unset</code> builtin command. +</p> +<p>A variable may be assigned to by a statement of the form +</p><div class="example"> +<pre class="example"><var>name</var>=[<var>value</var>] +</pre></div> +<p>If <var>value</var> +is not given, the variable is assigned the null string. All +<var>value</var>s undergo tilde expansion, parameter and variable expansion, +command substitution, arithmetic expansion, and quote +removal (see <a href="#Shell-Parameter-Expansion">Shell Parameter Expansion</a>). +If the variable has its <code>integer</code> +attribute set, then <var>value</var> +is evaluated as an arithmetic expression even if the <code>$((…))</code> +expansion is not used (see <a href="#Arithmetic-Expansion">Arithmetic Expansion</a>). +Word splitting and filename expansion are not performed. +Assignment statements may also appear as arguments to the +<code>alias</code>, +<code>declare</code>, <code>typeset</code>, <code>export</code>, <code>readonly</code>, +and <code>local</code> builtin commands (<em>declaration</em> commands). +When in <small>POSIX</small> mode (see <a href="#Bash-POSIX-Mode">Bash POSIX Mode</a>), these builtins may appear +in a command after one or more instances of the <code>command</code> builtin +and retain these assignment statement properties. +</p> +<p>In the context where an assignment statement is assigning a value +to a shell variable or array index (see <a href="#Arrays">Arrays</a>), the ‘<samp>+=</samp>’ +operator can be used to +append to or add to the variable’s previous value. +This includes arguments to builtin commands such as <code>declare</code> that +accept assignment statements (declaration commands). +When ‘<samp>+=</samp>’ is applied to a variable for which the <code>integer</code> attribute +has been set, <var>value</var> is evaluated as an arithmetic expression and +added to the variable’s current value, which is also evaluated. +When ‘<samp>+=</samp>’ is applied to an array variable using compound assignment +(see <a href="#Arrays">Arrays</a>), the +variable’s value is not unset (as it is when using ‘<samp>=</samp>’), and new +values are appended to the array beginning at one greater than the array’s +maximum index (for indexed arrays), or added as additional key-value pairs +in an associative array. +When applied to a string-valued variable, <var>value</var> is expanded and +appended to the variable’s value. +</p> +<p>A variable can be assigned the <code>nameref</code> attribute using the +<samp>-n</samp> option to the <code>declare</code> or <code>local</code> builtin commands +(see <a href="#Bash-Builtins">Bash Builtin Commands</a>) +to create a <em>nameref</em>, or a reference to another variable. +This allows variables to be manipulated indirectly. +Whenever the nameref variable is referenced, assigned to, unset, or has +its attributes modified (other than using or changing the nameref +attribute itself), the +operation is actually performed on the variable specified by the nameref +variable’s value. +A nameref is commonly used within shell functions to refer to a variable +whose name is passed as an argument to the function. +For instance, if a variable name is passed to a shell function as its first +argument, running +</p><div class="example"> +<pre class="example">declare -n ref=$1 +</pre></div> +<p>inside the function creates a nameref variable <code>ref</code> whose value is +the variable name passed as the first argument. +References and assignments to <code>ref</code>, and changes to its attributes, +are treated as references, assignments, and attribute modifications +to the variable whose name was passed as <code>$1</code>. +</p> +<p>If the control variable in a <code>for</code> loop has the nameref attribute, +the list of words can be a list of shell variables, and a name reference +will be established for each word in the list, in turn, when the loop is +executed. +Array variables cannot be given the nameref attribute. +However, nameref variables can reference array variables and subscripted +array variables. +Namerefs can be unset using the <samp>-n</samp> option to the <code>unset</code> builtin +(see <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>). +Otherwise, if <code>unset</code> is executed with the name of a nameref variable +as an argument, the variable referenced by the nameref variable will be unset. +</p> +<ul class="section-toc"> +<li><a href="#Positional-Parameters" accesskey="1">Positional Parameters</a></li> +<li><a href="#Special-Parameters" accesskey="2">Special Parameters</a></li> +</ul> +<hr> +<div class="subsection" id="Positional-Parameters"> +<div class="header"> +<p> +Next: <a href="#Special-Parameters" accesskey="n" rel="next">Special Parameters</a>, Up: <a href="#Shell-Parameters" accesskey="u" rel="up">Shell Parameters</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Positional-Parameters-1"></span><h4 class="subsection">3.4.1 Positional Parameters</h4> +<span id="index-parameters_002c-positional"></span> + +<p>A <em>positional parameter</em> is a parameter denoted by one or more +digits, other than the single digit <code>0</code>. Positional parameters are +assigned from the shell’s arguments when it is invoked, +and may be reassigned using the <code>set</code> builtin command. +Positional parameter <code>N</code> may be referenced as <code>${N}</code>, or +as <code>$N</code> when <code>N</code> consists of a single digit. +Positional parameters may not be assigned to with assignment statements. +The <code>set</code> and <code>shift</code> builtins are used to set and +unset them (see <a href="#Shell-Builtin-Commands">Shell Builtin Commands</a>). +The positional parameters are +temporarily replaced when a shell function is executed +(see <a href="#Shell-Functions">Shell Functions</a>). +</p> +<p>When a positional parameter consisting of more than a single +digit is expanded, it must be enclosed in braces. +</p> +<hr> +</div> +<div class="subsection" id="Special-Parameters"> +<div class="header"> +<p> +Previous: <a href="#Positional-Parameters" accesskey="p" rel="prev">Positional Parameters</a>, Up: <a href="#Shell-Parameters" accesskey="u" rel="up">Shell Parameters</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Special-Parameters-1"></span><h4 class="subsection">3.4.2 Special Parameters</h4> +<span id="index-parameters_002c-special"></span> + +<p>The shell treats several parameters specially. These parameters may +only be referenced; assignment to them is not allowed. +</p> +<dl compact="compact"> +<dt id='index-_002a'><span><code>*</code><a href='#index-_002a' class='copiable-anchor'> ¶</a></span></dt> +<dd><span id="index-_0024_002a"></span> +<p>($*) Expands to the positional parameters, starting from one. +When the expansion is not within double quotes, each positional parameter +expands to a separate word. +In contexts where it is performed, those words +are subject to further word splitting and filename expansion. +When the expansion occurs within double quotes, it expands to a single word +with the value of each parameter separated by the first character of the +<code>IFS</code> special variable. That is, <code>"$*"</code> is equivalent +to <code>"$1<var>c</var>$2<var>c</var>…"</code>, where <var>c</var> +is the first character of the value of the <code>IFS</code> +variable. +If <code>IFS</code> is unset, the parameters are separated by spaces. +If <code>IFS</code> is null, the parameters are joined without intervening +separators. +</p> +</dd> +<dt id='index-_0040'><span><code>@</code><a href='#index-_0040' class='copiable-anchor'> ¶</a></span></dt> +<dd><span id="index-_0024_0040"></span> +<p>($@) Expands to the positional parameters, starting from one. +In contexts where word splitting is performed, this expands each +positional parameter to a separate word; if not within double +quotes, these words are subject to word splitting. +In contexts where word splitting is not performed, +this expands to a single word +with each positional parameter separated by a space. +When the +expansion occurs within double quotes, and word splitting is performed, +each parameter expands to a +separate word. That is, <code>"$@"</code> is equivalent to +<code>"$1" "$2" …</code>. +If the double-quoted expansion occurs within a word, the expansion of +the first parameter is joined with the beginning part of the original +word, and the expansion of the last parameter is joined with the last +part of the original word. +When there are no positional parameters, <code>"$@"</code> and +<code>$@</code> +expand to nothing (i.e., they are removed). +</p> +</dd> +<dt id='index-_0023'><span><code>#</code><a href='#index-_0023' class='copiable-anchor'> ¶</a></span></dt> +<dd><span id="index-_0024_0023"></span> +<p>($#) Expands to the number of positional parameters in decimal. +</p> +</dd> +<dt id='index-_003f'><span><code>?</code><a href='#index-_003f' class='copiable-anchor'> ¶</a></span></dt> +<dd><span id="index-_0024_003f"></span> +<p>($?) Expands to the exit status of the most recently executed foreground +pipeline. +</p> +</dd> +<dt id='index-_002d'><span><code>-</code><a href='#index-_002d' class='copiable-anchor'> ¶</a></span></dt> +<dd><span id="index-_0024_002d"></span> +<p>($-, a hyphen.) Expands to the current option flags as specified upon +invocation, by the <code>set</code> +builtin command, or those set by the shell itself +(such as the <samp>-i</samp> option). +</p> +</dd> +<dt id='index-_0024'><span><code>$</code><a href='#index-_0024' class='copiable-anchor'> ¶</a></span></dt> +<dd><span id="index-_0024_0024"></span> +<p>($$) Expands to the process <small>ID</small> of the shell. In a subshell, it +expands to the process <small>ID</small> of the invoking shell, not the subshell. +</p> +</dd> +<dt id='index-_0021-1'><span><code>!</code><a href='#index-_0021-1' class='copiable-anchor'> ¶</a></span></dt> +<dd><span id="index-_0024_0021"></span> +<p>($!) Expands to the process <small>ID</small> of the job most recently placed into the +background, whether executed as an asynchronous command or using +the <code>bg</code> builtin (see <a href="#Job-Control-Builtins">Job Control Builtins</a>). +</p> +</dd> +<dt id='index-0'><span><code>0</code><a href='#index-0' class='copiable-anchor'> ¶</a></span></dt> +<dd><span id="index-_00240"></span> +<p>($0) Expands to the name of the shell or shell script. This is set at +shell initialization. If Bash is invoked with a file of commands +(see <a href="#Shell-Scripts">Shell Scripts</a>), <code>$0</code> is set to the name of that file. +If Bash is started with the <samp>-c</samp> option (see <a href="#Invoking-Bash">Invoking Bash</a>), +then <code>$0</code> is set to the first argument after the string to be +executed, if one is present. Otherwise, it is set +to the filename used to invoke Bash, as given by argument zero. +</p></dd> +</dl> + +<hr> +</div> +</div> +<div class="section" id="Shell-Expansions"> +<div class="header"> +<p> +Next: <a href="#Redirections" accesskey="n" rel="next">Redirections</a>, Previous: <a href="#Shell-Parameters" accesskey="p" rel="prev">Shell Parameters</a>, Up: <a href="#Basic-Shell-Features" accesskey="u" rel="up">Basic Shell Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Shell-Expansions-1"></span><h3 class="section">3.5 Shell Expansions</h3> +<span id="index-expansion"></span> + +<p>Expansion is performed on the command line after it has been split into +<code>token</code>s. There are seven kinds of expansion performed: +</p> +<ul> +<li> brace expansion +</li><li> tilde expansion +</li><li> parameter and variable expansion +</li><li> command substitution +</li><li> arithmetic expansion +</li><li> word splitting +</li><li> filename expansion +</li></ul> + + +<p>The order of expansions is: +brace expansion; +tilde expansion, parameter and variable expansion, arithmetic expansion, +and command substitution (done in a left-to-right fashion); +word splitting; +and filename expansion. +</p> +<p>On systems that can support it, there is an additional expansion +available: <em>process substitution</em>. +This is performed at the +same time as tilde, parameter, variable, and arithmetic expansion and +command substitution. +</p> +<p>After these expansions are performed, quote characters present in the +original word are removed unless they have been quoted themselves +(<em>quote removal</em>). +</p> +<p>Only brace expansion, word splitting, and filename expansion +can increase the number of words of the expansion; other expansions +expand a single word to a single word. +The only exceptions to this are the expansions of +<code>"$@"</code> and <code>$*</code> (see <a href="#Special-Parameters">Special Parameters</a>), and +<code>"${<var>name</var>[@]}"</code> and <code>${<var>name</var>[*]}</code> +(see <a href="#Arrays">Arrays</a>). +</p> +<p>After all expansions, <code>quote removal</code> (see <a href="#Quote-Removal">Quote Removal</a>) +is performed. +</p> +<ul class="section-toc"> +<li><a href="#Brace-Expansion" accesskey="1">Brace Expansion</a></li> +<li><a href="#Tilde-Expansion" accesskey="2">Tilde Expansion</a></li> +<li><a href="#Shell-Parameter-Expansion" accesskey="3">Shell Parameter Expansion</a></li> +<li><a href="#Command-Substitution" accesskey="4">Command Substitution</a></li> +<li><a href="#Arithmetic-Expansion" accesskey="5">Arithmetic Expansion</a></li> +<li><a href="#Process-Substitution" accesskey="6">Process Substitution</a></li> +<li><a href="#Word-Splitting" accesskey="7">Word Splitting</a></li> +<li><a href="#Filename-Expansion" accesskey="8">Filename Expansion</a></li> +<li><a href="#Quote-Removal" accesskey="9">Quote Removal</a></li> +</ul> +<hr> +<div class="subsection" id="Brace-Expansion"> +<div class="header"> +<p> +Next: <a href="#Tilde-Expansion" accesskey="n" rel="next">Tilde Expansion</a>, Up: <a href="#Shell-Expansions" accesskey="u" rel="up">Shell Expansions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Brace-Expansion-1"></span><h4 class="subsection">3.5.1 Brace Expansion</h4> +<span id="index-brace-expansion"></span> +<span id="index-expansion_002c-brace"></span> + +<p>Brace expansion is a mechanism by which arbitrary strings may be generated. +This mechanism is similar to +<em>filename expansion</em> (see <a href="#Filename-Expansion">Filename Expansion</a>), +but the filenames generated need not exist. +Patterns to be brace expanded take the form of an optional <var>preamble</var>, +followed by either a series of comma-separated strings or a sequence expression +between a pair of braces, +followed by an optional <var>postscript</var>. +The preamble is prefixed to each string contained within the braces, and +the postscript is then appended to each resulting string, expanding left +to right. +</p> +<p>Brace expansions may be nested. +The results of each expanded string are not sorted; left to right order +is preserved. +For example, +</p><div class="example"> +<pre class="example">bash$ echo a{d,c,b}e +ade ace abe +</pre></div> + +<p>A sequence expression takes the form <code>{<var>x</var>..<var>y</var>[..<var>incr</var>]}</code>, +where <var>x</var> and <var>y</var> are either integers or letters, +and <var>incr</var>, an optional increment, is an integer. +When integers are supplied, the expression expands to each number between +<var>x</var> and <var>y</var>, inclusive. +Supplied integers may be prefixed with ‘<samp>0</samp>’ to force each term to have the +same width. +When either <var>x</var> or <var>y</var> begins with a zero, the shell +attempts to force all generated terms to contain the same number of digits, +zero-padding where necessary. +When letters are supplied, the expression expands to each character +lexicographically between <var>x</var> and <var>y</var>, inclusive, +using the default C locale. +Note that both <var>x</var> and <var>y</var> must be of the same type +(integer or letter). +When the increment is supplied, it is used as the difference between +each term. The default increment is 1 or -1 as appropriate. +</p> +<p>Brace expansion is performed before any other expansions, +and any characters special to other expansions are preserved +in the result. It is strictly textual. Bash +does not apply any syntactic interpretation to the context of the +expansion or the text between the braces. +</p> +<p>A correctly-formed brace expansion must contain unquoted opening +and closing braces, and at least one unquoted comma or a valid +sequence expression. +Any incorrectly formed brace expansion is left unchanged. +</p> +<p>A { or ‘<samp>,</samp>’ may be quoted with a backslash to prevent its +being considered part of a brace expression. +To avoid conflicts with parameter expansion, the string ‘<samp>${</samp>’ +is not considered eligible for brace expansion, +and inhibits brace expansion until the closing ‘<samp>}</samp>’. +</p> +<p>This construct is typically used as shorthand when the common +prefix of the strings to be generated is longer than in the +above example: +</p><div class="example"> +<pre class="example">mkdir /usr/local/src/bash/{old,new,dist,bugs} +</pre></div> +<p>or +</p><div class="example"> +<pre class="example">chown root /usr/{ucb/{ex,edit},lib/{ex?.?*,how_ex}} +</pre></div> + +<hr> +</div> +<div class="subsection" id="Tilde-Expansion"> +<div class="header"> +<p> +Next: <a href="#Shell-Parameter-Expansion" accesskey="n" rel="next">Shell Parameter Expansion</a>, Previous: <a href="#Brace-Expansion" accesskey="p" rel="prev">Brace Expansion</a>, Up: <a href="#Shell-Expansions" accesskey="u" rel="up">Shell Expansions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Tilde-Expansion-1"></span><h4 class="subsection">3.5.2 Tilde Expansion</h4> +<span id="index-tilde-expansion"></span> +<span id="index-expansion_002c-tilde"></span> + +<p>If a word begins with an unquoted tilde character (‘<samp>~</samp>’), all of the +characters up to the first unquoted slash (or all characters, +if there is no unquoted slash) are considered a <em>tilde-prefix</em>. +If none of the characters in the tilde-prefix are quoted, the +characters in the tilde-prefix following the tilde are treated as a +possible <em>login name</em>. +If this login name is the null string, the tilde is replaced with the +value of the <code>HOME</code> shell variable. +If <code>HOME</code> is unset, the home directory of the user executing the +shell is substituted instead. +Otherwise, the tilde-prefix is replaced with the home directory +associated with the specified login name. +</p> +<p>If the tilde-prefix is ‘<samp>~+</samp>’, the value of +the shell variable <code>PWD</code> replaces the tilde-prefix. +If the tilde-prefix is ‘<samp>~-</samp>’, the value of the shell variable +<code>OLDPWD</code>, if it is set, is substituted. +</p> +<p>If the characters following the tilde in the tilde-prefix consist of a +number <var>N</var>, optionally prefixed by a ‘<samp>+</samp>’ or a ‘<samp>-</samp>’, +the tilde-prefix is replaced with the +corresponding element from the directory stack, as it would be displayed +by the <code>dirs</code> builtin invoked with the characters following tilde +in the tilde-prefix as an argument (see <a href="#The-Directory-Stack">The Directory Stack</a>). +If the tilde-prefix, sans the tilde, consists of a number without a +leading ‘<samp>+</samp>’ or ‘<samp>-</samp>’, ‘<samp>+</samp>’ is assumed. +</p> +<p>If the login name is invalid, or the tilde expansion fails, the word is +left unchanged. +</p> +<p>Each variable assignment is checked for unquoted tilde-prefixes immediately +following a ‘<samp>:</samp>’ or the first ‘<samp>=</samp>’. +In these cases, tilde expansion is also performed. +Consequently, one may use filenames with tildes in assignments to +<code>PATH</code>, <code>MAILPATH</code>, and <code>CDPATH</code>, +and the shell assigns the expanded value. +</p> +<p>The following table shows how Bash treats unquoted tilde-prefixes: +</p> +<dl compact="compact"> +<dt><span><code>~</code></span></dt> +<dd><p>The value of <code>$HOME</code> +</p></dd> +<dt><span><code>~/foo</code></span></dt> +<dd><p><samp>$HOME/foo</samp> +</p> +</dd> +<dt><span><code>~fred/foo</code></span></dt> +<dd><p>The subdirectory <code>foo</code> of the home directory of the user +<code>fred</code> +</p> +</dd> +<dt><span><code>~+/foo</code></span></dt> +<dd><p><samp>$PWD/foo</samp> +</p> +</dd> +<dt><span><code>~-/foo</code></span></dt> +<dd><p><samp>${OLDPWD-'~-'}/foo</samp> +</p> +</dd> +<dt><span><code>~<var>N</var></code></span></dt> +<dd><p>The string that would be displayed by ‘<samp>dirs +<var>N</var></samp>’ +</p> +</dd> +<dt><span><code>~+<var>N</var></code></span></dt> +<dd><p>The string that would be displayed by ‘<samp>dirs +<var>N</var></samp>’ +</p> +</dd> +<dt><span><code>~-<var>N</var></code></span></dt> +<dd><p>The string that would be displayed by ‘<samp>dirs -<var>N</var></samp>’ +</p></dd> +</dl> + +<p>Bash also performs tilde expansion on words satisfying the conditions of +variable assignments (see <a href="#Shell-Parameters">Shell Parameters</a>) +when they appear as arguments to simple commands. +Bash does not do this, except for the declaration commands listed +above, when in <small>POSIX</small> mode. +</p> +<hr> +</div> +<div class="subsection" id="Shell-Parameter-Expansion"> +<div class="header"> +<p> +Next: <a href="#Command-Substitution" accesskey="n" rel="next">Command Substitution</a>, Previous: <a href="#Tilde-Expansion" accesskey="p" rel="prev">Tilde Expansion</a>, Up: <a href="#Shell-Expansions" accesskey="u" rel="up">Shell Expansions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Shell-Parameter-Expansion-1"></span><h4 class="subsection">3.5.3 Shell Parameter Expansion</h4> +<span id="index-parameter-expansion"></span> +<span id="index-expansion_002c-parameter"></span> + +<p>The ‘<samp>$</samp>’ character introduces parameter expansion, +command substitution, or arithmetic expansion. The parameter name +or symbol to be expanded may be enclosed in braces, which +are optional but serve to protect the variable to be expanded from +characters immediately following it which could be +interpreted as part of the name. +</p> +<p>When braces are used, the matching ending brace is the first ‘<samp>}</samp>’ +not escaped by a backslash or within a quoted string, and not within an +embedded arithmetic expansion, command substitution, or parameter +expansion. +</p> +<p>The basic form of parameter expansion is ${<var>parameter</var>}. +The value of <var>parameter</var> is substituted. +The <var>parameter</var> is a shell parameter as described above +(see <a href="#Shell-Parameters">Shell Parameters</a>) or an array reference (see <a href="#Arrays">Arrays</a>). +The braces are required when <var>parameter</var> +is a positional parameter with more than one digit, +or when <var>parameter</var> is followed by a character that is not to be +interpreted as part of its name. +</p> +<p>If the first character of <var>parameter</var> is an exclamation point (!), +and <var>parameter</var> is not a nameref, +it introduces a level of indirection. +Bash uses the value formed by expanding the rest of +<var>parameter</var> as the new <var>parameter</var>; this is then +expanded and that value is used in the rest of the expansion, rather +than the expansion of the original <var>parameter</var>. +This is known as <code>indirect expansion</code>. +The value is subject to tilde expansion, +parameter expansion, command substitution, and arithmetic expansion. +If <var>parameter</var> is a nameref, this expands to the name of the +variable referenced by <var>parameter</var> instead of performing the +complete indirect expansion. +The exceptions to this are the expansions of ${!<var>prefix</var>*} +and ${!<var>name</var>[@]} +described below. +The exclamation point must immediately follow the left brace in order to +introduce indirection. +</p> +<p>In each of the cases below, <var>word</var> is subject to tilde expansion, +parameter expansion, command substitution, and arithmetic expansion. +</p> +<p>When not performing substring expansion, using the form described +below (e.g., ‘<samp>:-</samp>’), Bash tests for a parameter that is unset or null. +Omitting the colon results in a test only for a parameter that is unset. +Put another way, if the colon is included, +the operator tests for both <var>parameter</var>’s existence and that its value +is not null; if the colon is omitted, the operator tests only for existence. +</p> +<dl compact="compact"> +<dt><span><code>${<var>parameter</var>:-<var>word</var>}</code></span></dt> +<dd><p>If <var>parameter</var> is unset or null, the expansion of +<var>word</var> is substituted. Otherwise, the value of +<var>parameter</var> is substituted. +</p> +<div class="example"> +<pre class="example">$ v=123 +$ echo ${v-unset} +123 +</pre></div> + +</dd> +<dt><span><code>${<var>parameter</var>:=<var>word</var>}</code></span></dt> +<dd><p>If <var>parameter</var> +is unset or null, the expansion of <var>word</var> +is assigned to <var>parameter</var>. +The value of <var>parameter</var> is then substituted. +Positional parameters and special parameters may not be assigned to +in this way. +</p> +<div class="example"> +<pre class="example">$ var= +$ : ${var:=DEFAULT} +$ echo $var +DEFAULT +</pre></div> + +</dd> +<dt><span><code>${<var>parameter</var>:?<var>word</var>}</code></span></dt> +<dd><p>If <var>parameter</var> +is null or unset, the expansion of <var>word</var> (or a message +to that effect if <var>word</var> +is not present) is written to the standard error and the shell, if it +is not interactive, exits. Otherwise, the value of <var>parameter</var> is +substituted. +</p> +<div class="example"> +<pre class="example">$ var= +$ : ${var:?var is unset or null} +bash: var: var is unset or null +</pre></div> + +</dd> +<dt><span><code>${<var>parameter</var>:+<var>word</var>}</code></span></dt> +<dd><p>If <var>parameter</var> +is null or unset, nothing is substituted, otherwise the expansion of +<var>word</var> is substituted. +</p> +<div class="example"> +<pre class="example">$ var=123 +$ echo ${var:+var is set and not null} +var is set and not null +</pre></div> + +</dd> +<dt><span><code>${<var>parameter</var>:<var>offset</var>}</code></span></dt> +<dt><span><code>${<var>parameter</var>:<var>offset</var>:<var>length</var>}</code></span></dt> +<dd><p>This is referred to as Substring Expansion. +It expands to up to <var>length</var> characters of the value of <var>parameter</var> +starting at the character specified by <var>offset</var>. +If <var>parameter</var> is ‘<samp>@</samp>’ or ‘<samp>*</samp>’, an indexed array subscripted by +‘<samp>@</samp>’ or ‘<samp>*</samp>’, or an associative array name, the results differ as +described below. +If <var>length</var> is omitted, it expands to the substring of the value of +<var>parameter</var> starting at the character specified by <var>offset</var> +and extending to the end of the value. +<var>length</var> and <var>offset</var> are arithmetic expressions +(see <a href="#Shell-Arithmetic">Shell Arithmetic</a>). +</p> +<p>If <var>offset</var> evaluates to a number less than zero, the value +is used as an offset in characters +from the end of the value of <var>parameter</var>. +If <var>length</var> evaluates to a number less than zero, +it is interpreted as an offset in characters +from the end of the value of <var>parameter</var> rather than +a number of characters, and the expansion is the characters between +<var>offset</var> and that result. +Note that a negative offset must be separated from the colon by at least +one space to avoid being confused with the ‘<samp>:-</samp>’ expansion. +</p> +<p>Here are some examples illustrating substring expansion on parameters and +subscripted arrays: +</p> +<pre class="verbatim">$ string=01234567890abcdefgh +$ echo ${string:7} +7890abcdefgh +$ echo ${string:7:0} + +$ echo ${string:7:2} +78 +$ echo ${string:7:-2} +7890abcdef +$ echo ${string: -7} +bcdefgh +$ echo ${string: -7:0} + +$ echo ${string: -7:2} +bc +$ echo ${string: -7:-2} +bcdef +$ set -- 01234567890abcdefgh +$ echo ${1:7} +7890abcdefgh +$ echo ${1:7:0} + +$ echo ${1:7:2} +78 +$ echo ${1:7:-2} +7890abcdef +$ echo ${1: -7} +bcdefgh +$ echo ${1: -7:0} + +$ echo ${1: -7:2} +bc +$ echo ${1: -7:-2} +bcdef +$ array[0]=01234567890abcdefgh +$ echo ${array[0]:7} +7890abcdefgh +$ echo ${array[0]:7:0} + +$ echo ${array[0]:7:2} +78 +$ echo ${array[0]:7:-2} +7890abcdef +$ echo ${array[0]: -7} +bcdefgh +$ echo ${array[0]: -7:0} + +$ echo ${array[0]: -7:2} +bc +$ echo ${array[0]: -7:-2} +bcdef +</pre> +<p>If <var>parameter</var> is ‘<samp>@</samp>’ or ‘<samp>*</samp>’, the result is <var>length</var> +positional parameters beginning at <var>offset</var>. +A negative <var>offset</var> is taken relative to one greater than the greatest +positional parameter, so an offset of -1 evaluates to the last positional +parameter. +It is an expansion error if <var>length</var> evaluates to a number less than zero. +</p> +<p>The following examples illustrate substring expansion using positional +parameters: +</p> +<pre class="verbatim">$ set -- 1 2 3 4 5 6 7 8 9 0 a b c d e f g h +$ echo ${@:7} +7 8 9 0 a b c d e f g h +$ echo ${@:7:0} + +$ echo ${@:7:2} +7 8 +$ echo ${@:7:-2} +bash: -2: substring expression < 0 +$ echo ${@: -7:2} +b c +$ echo ${@:0} +./bash 1 2 3 4 5 6 7 8 9 0 a b c d e f g h +$ echo ${@:0:2} +./bash 1 +$ echo ${@: -7:0} + +</pre> +<p>If <var>parameter</var> is an indexed array name subscripted +by ‘<samp>@</samp>’ or ‘<samp>*</samp>’, the result is the <var>length</var> +members of the array beginning with <code>${<var>parameter</var>[<var>offset</var>]}</code>. +A negative <var>offset</var> is taken relative to one greater than the maximum +index of the specified array. +It is an expansion error if <var>length</var> evaluates to a number less than zero. +</p> +<p>These examples show how you can use substring expansion with indexed +arrays: +</p> +<pre class="verbatim">$ array=(0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h) +$ echo ${array[@]:7} +7 8 9 0 a b c d e f g h +$ echo ${array[@]:7:2} +7 8 +$ echo ${array[@]: -7:2} +b c +$ echo ${array[@]: -7:-2} +bash: -2: substring expression < 0 +$ echo ${array[@]:0} +0 1 2 3 4 5 6 7 8 9 0 a b c d e f g h +$ echo ${array[@]:0:2} +0 1 +$ echo ${array[@]: -7:0} + +</pre> +<p>Substring expansion applied to an associative array produces undefined +results. +</p> +<p>Substring indexing is zero-based unless the positional parameters +are used, in which case the indexing starts at 1 by default. +If <var>offset</var> is 0, and the positional parameters are used, <code>$0</code> is +prefixed to the list. +</p> +</dd> +<dt><span><code>${!<var>prefix</var>*}</code></span></dt> +<dt><span><code>${!<var>prefix</var>@}</code></span></dt> +<dd><p>Expands to the names of variables whose names begin with <var>prefix</var>, +separated by the first character of the <code>IFS</code> special variable. +When ‘<samp>@</samp>’ is used and the expansion appears within double quotes, each +variable name expands to a separate word. +</p> +</dd> +<dt><span><code>${!<var>name</var>[@]}</code></span></dt> +<dt><span><code>${!<var>name</var>[*]}</code></span></dt> +<dd><p>If <var>name</var> is an array variable, expands to the list of array indices +(keys) assigned in <var>name</var>. +If <var>name</var> is not an array, expands to 0 if <var>name</var> is set and null +otherwise. +When ‘<samp>@</samp>’ is used and the expansion appears within double quotes, each +key expands to a separate word. +</p> +</dd> +<dt><span><code>${#<var>parameter</var>}</code></span></dt> +<dd><p>The length in characters of the expanded value of <var>parameter</var> is +substituted. +If <var>parameter</var> is ‘<samp>*</samp>’ or ‘<samp>@</samp>’, the value substituted +is the number of positional parameters. +If <var>parameter</var> is an array name subscripted by ‘<samp>*</samp>’ or ‘<samp>@</samp>’, +the value substituted is the number of elements in the array. +If <var>parameter</var> +is an indexed array name subscripted by a negative number, that number is +interpreted as relative to one greater than the maximum index of +<var>parameter</var>, so negative indices count back from the end of the +array, and an index of -1 references the last element. +</p> +</dd> +<dt><span><code>${<var>parameter</var>#<var>word</var>}</code></span></dt> +<dt><span><code>${<var>parameter</var>##<var>word</var>}</code></span></dt> +<dd><p>The <var>word</var> +is expanded to produce a pattern and matched according to the rules +described below (see <a href="#Pattern-Matching">Pattern Matching</a>). If the pattern matches +the beginning of the expanded value of <var>parameter</var>, +then the result of the expansion is the expanded value of <var>parameter</var> +with the shortest matching pattern (the ‘<samp>#</samp>’ case) or the +longest matching pattern (the ‘<samp>##</samp>’ case) deleted. +If <var>parameter</var> is ‘<samp>@</samp>’ or ‘<samp>*</samp>’, +the pattern removal operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If <var>parameter</var> is an array variable subscripted with +‘<samp>@</samp>’ or ‘<samp>*</samp>’, +the pattern removal operation is applied to each member of the +array in turn, and the expansion is the resultant list. +</p> +</dd> +<dt><span><code>${<var>parameter</var>%<var>word</var>}</code></span></dt> +<dt><span><code>${<var>parameter</var>%%<var>word</var>}</code></span></dt> +<dd><p>The <var>word</var> +is expanded to produce a pattern and matched according to the rules +described below (see <a href="#Pattern-Matching">Pattern Matching</a>). +If the pattern matches a trailing portion of the expanded value of +<var>parameter</var>, then the result of the expansion is the value of +<var>parameter</var> with the shortest matching pattern (the ‘<samp>%</samp>’ case) +or the longest matching pattern (the ‘<samp>%%</samp>’ case) deleted. +If <var>parameter</var> is ‘<samp>@</samp>’ or ‘<samp>*</samp>’, +the pattern removal operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If <var>parameter</var> +is an array variable subscripted with ‘<samp>@</samp>’ or ‘<samp>*</samp>’, +the pattern removal operation is applied to each member of the +array in turn, and the expansion is the resultant list. +</p> +</dd> +<dt><span><code>${<var>parameter</var>/<var>pattern</var>/<var>string</var>}</code></span></dt> +<dt><span><code>${<var>parameter</var>//<var>pattern</var>/<var>string</var>}</code></span></dt> +<dt><span><code>${<var>parameter</var>/#<var>pattern</var>/<var>string</var>}</code></span></dt> +<dt><span><code>${<var>parameter</var>/%<var>pattern</var>/<var>string</var>}</code></span></dt> +<dd><p>The <var>pattern</var> is expanded to produce a pattern just as in +filename expansion. +<var>Parameter</var> is expanded and the longest match of <var>pattern</var> +against its value is replaced with <var>string</var>. +<var>string</var> undergoes tilde expansion, parameter and variable expansion, +arithmetic expansion, command and process substitution, and quote removal. +The match is performed according to the rules described below +(see <a href="#Pattern-Matching">Pattern Matching</a>). +</p> +<p>In the first form above, only the first match is replaced. +If there are two slashes separating <var>parameter</var> and <var>pattern</var> +(the second form above), all matches of <var>pattern</var> are +replaced with <var>string</var>. +If <var>pattern</var> is preceded by ‘<samp>#</samp>’ (the third form above), +it must match at the beginning of the expanded value of <var>parameter</var>. +If <var>pattern</var> is preceded by ‘<samp>%</samp>’ (the fourth form above), +it must match at the end of the expanded value of <var>parameter</var>. +If the expansion of <var>string</var> is null, +matches of <var>pattern</var> are deleted. +If <var>string</var> is null, +matches of <var>pattern</var> are deleted +and the ‘<samp>/</samp>’ following <var>pattern</var> may be omitted. +</p> +<p>If the <code>patsub_replacement</code> shell option is enabled using <code>shopt</code>, +any unquoted instances of ‘<samp>&</samp>’ in <var>string</var> are replaced with the +matching portion of <var>pattern</var>. +This is intended to duplicate a common <code>sed</code> idiom. +</p> +<p>Quoting any part of <var>string</var> inhibits replacement in the +expansion of the quoted portion, including replacement strings stored +in shell variables. +Backslash will escape ‘<samp>&</samp>’ in <var>string</var>; the backslash is removed +in order to permit a literal ‘<samp>&</samp>’ in the replacement string. +Users should take care if <var>string</var> is double-quoted to avoid +unwanted interactions between the backslash and double-quoting, since +backslash has special meaning within double quotes. +Pattern substitution performs the check for unquoted ‘<samp>&</samp>’ after +expanding <var>string</var>, +so users should ensure to properly quote any occurrences of ‘<samp>&</samp>’ +they want to be taken literally in the replacement +and ensure any instances of ‘<samp>&</samp>’ they want to be replaced are unquoted. +</p> +<p>For instance, +</p> +<div class="example"> +<pre class="example">var=abcdef +rep='& ' +echo ${var/abc/& } +echo "${var/abc/& }" +echo ${var/abc/$rep} +echo "${var/abc/$rep}" +</pre></div> + +<p>will display four lines of "abc def", while +</p> +<div class="example"> +<pre class="example">var=abcdef +rep='& ' +echo ${var/abc/\& } +echo "${var/abc/\& }" +echo ${var/abc/"& "} +echo ${var/abc/"$rep"} +</pre></div> + +<p>will display four lines of "& def". +Like the pattern removal operators, double quotes surrounding the +replacement string quote the expanded characters, while double quotes +enclosing the entire parameter substitution do not, since +the expansion is performed in a +context that doesn’t take any enclosing double quotes into account. +</p> +<p>Since backslash can escape ‘<samp>&</samp>’, it can also escape a backslash in +the replacement string. +This means that ‘<samp>\\</samp>’ will insert a literal +backslash into the replacement, so these two <code>echo</code> commands +</p> +<div class="example"> +<pre class="example">var=abcdef +rep='\\&xyz' +echo ${var/abc/\\&xyz} +echo ${var/abc/$rep} +</pre></div> + +<p>will both output ‘<samp>\abcxyzdef</samp>’. +</p> +<p>It should rarely be necessary to enclose only <var>string</var> in double +quotes. +</p> +<p>If the <code>nocasematch</code> shell option +(see the description of <code>shopt</code> in <a href="#The-Shopt-Builtin">The Shopt Builtin</a>) +is enabled, the match is performed without regard to the case +of alphabetic characters. +If <var>parameter</var> is ‘<samp>@</samp>’ or ‘<samp>*</samp>’, +the substitution operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If <var>parameter</var> +is an array variable subscripted with ‘<samp>@</samp>’ or ‘<samp>*</samp>’, +the substitution operation is applied to each member of the +array in turn, and the expansion is the resultant list. +</p> +</dd> +<dt><span><code>${<var>parameter</var>^<var>pattern</var>}</code></span></dt> +<dt><span><code>${<var>parameter</var>^^<var>pattern</var>}</code></span></dt> +<dt><span><code>${<var>parameter</var>,<var>pattern</var>}</code></span></dt> +<dt><span><code>${<var>parameter</var>,,<var>pattern</var>}</code></span></dt> +<dd><p>This expansion modifies the case of alphabetic characters in <var>parameter</var>. +The <var>pattern</var> is expanded to produce a pattern just as in +filename expansion. +Each character in the expanded value of <var>parameter</var> is tested against +<var>pattern</var>, and, if it matches the pattern, its case is converted. +The pattern should not attempt to match more than one character. +</p> +<p>The ‘<samp>^</samp>’ operator converts lowercase letters matching <var>pattern</var> +to uppercase; the ‘<samp>,</samp>’ operator converts matching uppercase letters +to lowercase. +The ‘<samp>^^</samp>’ and ‘<samp>,,</samp>’ expansions convert each matched character in the +expanded value; the ‘<samp>^</samp>’ and ‘<samp>,</samp>’ expansions match and convert only +the first character in the expanded value. +If <var>pattern</var> is omitted, it is treated like a ‘<samp>?</samp>’, which matches +every character. +</p> +<p>If <var>parameter</var> is ‘<samp>@</samp>’ or ‘<samp>*</samp>’, +the case modification operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If <var>parameter</var> +is an array variable subscripted with ‘<samp>@</samp>’ or ‘<samp>*</samp>’, +the case modification operation is applied to each member of the +array in turn, and the expansion is the resultant list. +</p> +</dd> +<dt><span><code>${<var>parameter</var>@<var>operator</var>}</code></span></dt> +<dd><p>The expansion is either a transformation of the value of <var>parameter</var> +or information about <var>parameter</var> itself, depending on the value of +<var>operator</var>. Each <var>operator</var> is a single letter: +</p> +<dl compact="compact"> +<dt><span><code>U</code></span></dt> +<dd><p>The expansion is a string that is the value of <var>parameter</var> with lowercase +alphabetic characters converted to uppercase. +</p></dd> +<dt><span><code>u</code></span></dt> +<dd><p>The expansion is a string that is the value of <var>parameter</var> with the first +character converted to uppercase, if it is alphabetic. +</p></dd> +<dt><span><code>L</code></span></dt> +<dd><p>The expansion is a string that is the value of <var>parameter</var> with uppercase +alphabetic characters converted to lowercase. +</p></dd> +<dt><span><code>Q</code></span></dt> +<dd><p>The expansion is a string that is the value of <var>parameter</var> quoted in a +format that can be reused as input. +</p></dd> +<dt><span><code>E</code></span></dt> +<dd><p>The expansion is a string that is the value of <var>parameter</var> with backslash +escape sequences expanded as with the <code>$'…'</code> quoting mechanism. +</p></dd> +<dt><span><code>P</code></span></dt> +<dd><p>The expansion is a string that is the result of expanding the value of +<var>parameter</var> as if it were a prompt string (see <a href="#Controlling-the-Prompt">Controlling the Prompt</a>). +</p></dd> +<dt><span><code>A</code></span></dt> +<dd><p>The expansion is a string in the form of +an assignment statement or <code>declare</code> command that, if +evaluated, will recreate <var>parameter</var> with its attributes and value. +</p></dd> +<dt><span><code>K</code></span></dt> +<dd><p>Produces a possibly-quoted version of the value of <var>parameter</var>, +except that it prints the values of +indexed and associative arrays as a sequence of quoted key-value pairs +(see <a href="#Arrays">Arrays</a>). +</p></dd> +<dt><span><code>a</code></span></dt> +<dd><p>The expansion is a string consisting of flag values representing +<var>parameter</var>’s attributes. +</p></dd> +<dt><span><code>k</code></span></dt> +<dd><p>Like the ‘<samp>K</samp>’ transformation, but expands the keys and values of +indexed and associative arrays to separate words after word splitting. +</p></dd> +</dl> + +<p>If <var>parameter</var> is ‘<samp>@</samp>’ or ‘<samp>*</samp>’, +the operation is applied to each positional +parameter in turn, and the expansion is the resultant list. +If <var>parameter</var> +is an array variable subscripted with ‘<samp>@</samp>’ or ‘<samp>*</samp>’, +the operation is applied to each member of the +array in turn, and the expansion is the resultant list. +</p> +<p>The result of the expansion is subject to word splitting and filename +expansion as described below. +</p></dd> +</dl> + +<hr> +</div> +<div class="subsection" id="Command-Substitution"> +<div class="header"> +<p> +Next: <a href="#Arithmetic-Expansion" accesskey="n" rel="next">Arithmetic Expansion</a>, Previous: <a href="#Shell-Parameter-Expansion" accesskey="p" rel="prev">Shell Parameter Expansion</a>, Up: <a href="#Shell-Expansions" accesskey="u" rel="up">Shell Expansions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Command-Substitution-1"></span><h4 class="subsection">3.5.4 Command Substitution</h4> +<span id="index-command-substitution"></span> + +<p>Command substitution allows the output of a command to replace +the command itself. +Command substitution occurs when a command is enclosed as follows: +</p><div class="example"> +<pre class="example">$(<var>command</var>) +</pre></div> +<p>or +</p><div class="example"> +<pre class="example">`<var>command</var>` +</pre></div> + +<p>Bash performs the expansion by executing <var>command</var> in a subshell environment +and replacing the command substitution with the standard output of the +command, with any trailing newlines deleted. +Embedded newlines are not deleted, but they may be removed during +word splitting. +The command substitution <code>$(cat <var>file</var>)</code> can be +replaced by the equivalent but faster <code>$(< <var>file</var>)</code>. +</p> +<p>When the old-style backquote form of substitution is used, +backslash retains its literal meaning except when followed by +‘<samp>$</samp>’, ‘<samp>`</samp>’, or ‘<samp>\</samp>’. +The first backquote not preceded by a backslash terminates the +command substitution. +When using the <code>$(<var>command</var>)</code> form, all characters between +the parentheses make up the command; none are treated specially. +</p> +<p>Command substitutions may be nested. To nest when using the backquoted +form, escape the inner backquotes with backslashes. +</p> +<p>If the substitution appears within double quotes, word splitting and +filename expansion are not performed on the results. +</p> +<hr> +</div> +<div class="subsection" id="Arithmetic-Expansion"> +<div class="header"> +<p> +Next: <a href="#Process-Substitution" accesskey="n" rel="next">Process Substitution</a>, Previous: <a href="#Command-Substitution" accesskey="p" rel="prev">Command Substitution</a>, Up: <a href="#Shell-Expansions" accesskey="u" rel="up">Shell Expansions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Arithmetic-Expansion-1"></span><h4 class="subsection">3.5.5 Arithmetic Expansion</h4> +<span id="index-expansion_002c-arithmetic"></span> +<span id="index-arithmetic-expansion"></span> + +<p>Arithmetic expansion allows the evaluation of an arithmetic expression +and the substitution of the result. The format for arithmetic expansion is: +</p> +<div class="example"> +<pre class="example">$(( <var>expression</var> )) +</pre></div> + +<p>The <var>expression</var> undergoes the same expansions +as if it were within double quotes, +but double quote characters in <var>expression</var> are not treated specially +and are removed. +All tokens in the expression undergo parameter and variable expansion, +command substitution, and quote removal. +The result is treated as the arithmetic expression to be evaluated. +Arithmetic expansions may be nested. +</p> +<p>The evaluation is performed according to the rules listed below +(see <a href="#Shell-Arithmetic">Shell Arithmetic</a>). +If the expression is invalid, Bash prints a message indicating +failure to the standard error and no substitution occurs. +</p> +<hr> +</div> +<div class="subsection" id="Process-Substitution"> +<div class="header"> +<p> +Next: <a href="#Word-Splitting" accesskey="n" rel="next">Word Splitting</a>, Previous: <a href="#Arithmetic-Expansion" accesskey="p" rel="prev">Arithmetic Expansion</a>, Up: <a href="#Shell-Expansions" accesskey="u" rel="up">Shell Expansions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Process-Substitution-1"></span><h4 class="subsection">3.5.6 Process Substitution</h4> +<span id="index-process-substitution"></span> + +<p>Process substitution allows a process’s input or output to be +referred to using a filename. +It takes the form of +</p><div class="example"> +<pre class="example"><(<var>list</var>) +</pre></div> +<p>or +</p><div class="example"> +<pre class="example">>(<var>list</var>) +</pre></div> +<p>The process <var>list</var> is run asynchronously, and its input or output +appears as a filename. +This filename is +passed as an argument to the current command as the result of the +expansion. +If the <code>>(<var>list</var>)</code> form is used, writing to +the file will provide input for <var>list</var>. If the +<code><(<var>list</var>)</code> form is used, the file passed as an +argument should be read to obtain the output of <var>list</var>. +Note that no space may appear between the <code><</code> or <code>></code> +and the left parenthesis, otherwise the construct would be interpreted +as a redirection. +Process substitution is supported on systems that support named +pipes (<small>FIFO</small>s) or the <samp>/dev/fd</samp> method of naming open files. +</p> +<p>When available, process substitution is performed simultaneously with +parameter and variable expansion, command substitution, and arithmetic +expansion. +</p> +<hr> +</div> +<div class="subsection" id="Word-Splitting"> +<div class="header"> +<p> +Next: <a href="#Filename-Expansion" accesskey="n" rel="next">Filename Expansion</a>, Previous: <a href="#Process-Substitution" accesskey="p" rel="prev">Process Substitution</a>, Up: <a href="#Shell-Expansions" accesskey="u" rel="up">Shell Expansions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Word-Splitting-1"></span><h4 class="subsection">3.5.7 Word Splitting</h4> +<span id="index-word-splitting"></span> + +<p>The shell scans the results of parameter expansion, command substitution, +and arithmetic expansion that did not occur within double quotes for +word splitting. +</p> +<p>The shell treats each character of <code>$IFS</code> as a delimiter, and splits +the results of the other expansions into words using these characters +as field terminators. +If <code>IFS</code> is unset, or its value is exactly <code><space><tab><newline></code>, +the default, then sequences of +<code> <space></code>, <code><tab></code>, and <code><newline></code> +at the beginning and end of the results of the previous +expansions are ignored, and any sequence of <code>IFS</code> +characters not at the beginning or end serves to delimit words. +If <code>IFS</code> has a value other than the default, then sequences of +the whitespace characters <code>space</code>, <code>tab</code>, and <code>newline</code> +are ignored at the beginning and end of the +word, as long as the whitespace character is in the +value of <code>IFS</code> (an <code>IFS</code> whitespace character). +Any character in <code>IFS</code> that is not <code>IFS</code> +whitespace, along with any adjacent <code>IFS</code> +whitespace characters, delimits a field. A sequence of <code>IFS</code> +whitespace characters is also treated as a delimiter. +If the value of <code>IFS</code> is null, no word splitting occurs. +</p> +<p>Explicit null arguments (<code>""</code> or <code>''</code>) are retained +and passed to commands as empty strings. +Unquoted implicit null arguments, resulting from the expansion of +parameters that have no values, are removed. +If a parameter with no value is expanded within double quotes, a +null argument results and is retained +and passed to a command as an empty string. +When a quoted null argument appears as part of a word whose expansion is +non-null, the null argument is removed. +That is, the word +<code>-d''</code> becomes <code>-d</code> after word splitting and +null argument removal. +</p> +<p>Note that if no expansion occurs, no splitting +is performed. +</p> +<hr> +</div> +<div class="subsection" id="Filename-Expansion"> +<div class="header"> +<p> +Next: <a href="#Quote-Removal" accesskey="n" rel="next">Quote Removal</a>, Previous: <a href="#Word-Splitting" accesskey="p" rel="prev">Word Splitting</a>, Up: <a href="#Shell-Expansions" accesskey="u" rel="up">Shell Expansions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Filename-Expansion-1"></span><h4 class="subsection">3.5.8 Filename Expansion</h4> +<span id="index-expansion_002c-filename"></span> +<span id="index-expansion_002c-pathname"></span> +<span id="index-filename-expansion"></span> +<span id="index-pathname-expansion"></span> + +<p>After word splitting, unless the <samp>-f</samp> option has been set +(see <a href="#The-Set-Builtin">The Set Builtin</a>), Bash scans each word for the characters +‘<samp>*</samp>’, ‘<samp>?</samp>’, and ‘<samp>[</samp>’. +If one of these characters appears, and is not quoted, then the word is +regarded as a <var>pattern</var>, +and replaced with an alphabetically sorted list of +filenames matching the pattern (see <a href="#Pattern-Matching">Pattern Matching</a>). +If no matching filenames are found, +and the shell option <code>nullglob</code> is disabled, the word is left +unchanged. +If the <code>nullglob</code> option is set, and no matches are found, the word +is removed. +If the <code>failglob</code> shell option is set, and no matches are found, +an error message is printed and the command is not executed. +If the shell option <code>nocaseglob</code> is enabled, the match is performed +without regard to the case of alphabetic characters. +</p> +<p>When a pattern is used for filename expansion, the character ‘<samp>.</samp>’ +at the start of a filename or immediately following a slash +must be matched explicitly, unless the shell option <code>dotglob</code> is set. +In order to match the filenames ‘<samp>.</samp>’ and ‘<samp>..</samp>’, +the pattern must begin with ‘<samp>.</samp>’ (for example, ‘<samp>.?</samp>’), +even if <code>dotglob</code> is set. +If the <code>globskipdots</code> shell option is enabled, the filenames +‘<samp>.</samp>’ and ‘<samp>..</samp>’ are never matched, even if the pattern begins +with a ‘<samp>.</samp>’. +When not matching filenames, the ‘<samp>.</samp>’ character is not treated specially. +</p> +<p>When matching a filename, the slash character must always be +matched explicitly by a slash in the pattern, but in other matching +contexts it can be matched by a special pattern character as described +below (see <a href="#Pattern-Matching">Pattern Matching</a>). +</p> +<p>See the description of <code>shopt</code> in <a href="#The-Shopt-Builtin">The Shopt Builtin</a>, +for a description of the <code>nocaseglob</code>, <code>nullglob</code>, +<code>globskipdots</code>, +<code>failglob</code>, and <code>dotglob</code> options. +</p> +<p>The <code>GLOBIGNORE</code> +shell variable may be used to restrict the set of file names matching a +pattern. If <code>GLOBIGNORE</code> +is set, each matching file name that also matches one of the patterns in +<code>GLOBIGNORE</code> is removed from the list of matches. +If the <code>nocaseglob</code> option is set, the matching against the patterns in +<code>GLOBIGNORE</code> is performed without regard to case. +The filenames +<samp>.</samp> and <samp>..</samp> +are always ignored when <code>GLOBIGNORE</code> +is set and not null. +However, setting <code>GLOBIGNORE</code> to a non-null value has the effect of +enabling the <code>dotglob</code> +shell option, so all other filenames beginning with a +‘<samp>.</samp>’ will match. +To get the old behavior of ignoring filenames beginning with a +‘<samp>.</samp>’, make ‘<samp>.*</samp>’ one of the patterns in <code>GLOBIGNORE</code>. +The <code>dotglob</code> option is disabled when <code>GLOBIGNORE</code> +is unset. +</p> +<ul class="section-toc"> +<li><a href="#Pattern-Matching" accesskey="1">Pattern Matching</a></li> +</ul> +<hr> +<div class="subsubsection" id="Pattern-Matching"> +<div class="header"> +<p> +Up: <a href="#Filename-Expansion" accesskey="u" rel="up">Filename Expansion</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Pattern-Matching-1"></span><h4 class="subsubsection">3.5.8.1 Pattern Matching</h4> +<span id="index-pattern-matching"></span> +<span id="index-matching_002c-pattern"></span> + +<p>Any character that appears in a pattern, other than the special pattern +characters described below, matches itself. +The <small>NUL</small> character may not occur in a pattern. +A backslash escapes the following character; the +escaping backslash is discarded when matching. +The special pattern characters must be quoted if they are to be matched +literally. +</p> +<p>The special pattern characters have the following meanings: +</p><dl compact="compact"> +<dt><span><code>*</code></span></dt> +<dd><p>Matches any string, including the null string. +When the <code>globstar</code> shell option is enabled, and ‘<samp>*</samp>’ is used in +a filename expansion context, two adjacent ‘<samp>*</samp>’s used as a single +pattern will match all files and zero or more directories and +subdirectories. +If followed by a ‘<samp>/</samp>’, two adjacent ‘<samp>*</samp>’s will match only +directories and subdirectories. +</p></dd> +<dt><span><code>?</code></span></dt> +<dd><p>Matches any single character. +</p></dd> +<dt><span><code>[…]</code></span></dt> +<dd><p>Matches any one of the enclosed characters. A pair of characters +separated by a hyphen denotes a <var>range expression</var>; +any character that falls between those two characters, inclusive, +using the current locale’s collating sequence and character set, +is matched. If the first character following the +‘<samp>[</samp>’ is a ‘<samp>!</samp>’ or a ‘<samp>^</samp>’ +then any character not enclosed is matched. A ‘<samp>-</samp>’ +may be matched by including it as the first or last character +in the set. A ‘<samp>]</samp>’ may be matched by including it as the first +character in the set. +The sorting order of characters in range expressions, +and the characters included in the range, +are determined by +the current locale and the values of the +<code>LC_COLLATE</code> and <code>LC_ALL</code> shell variables, if set. +</p> +<p>For example, in the default C locale, ‘<samp>[a-dx-z]</samp>’ is equivalent to +‘<samp>[abcdxyz]</samp>’. Many locales sort characters in dictionary order, and in +these locales ‘<samp>[a-dx-z]</samp>’ is typically not equivalent to ‘<samp>[abcdxyz]</samp>’; +it might be equivalent to ‘<samp>[aBbCcDdxYyZz]</samp>’, for example. To obtain +the traditional interpretation of ranges in bracket expressions, you can +force the use of the C locale by setting the <code>LC_COLLATE</code> or +<code>LC_ALL</code> environment variable to the value ‘<samp>C</samp>’, or enable the +<code>globasciiranges</code> shell option. +</p> +<p>Within ‘<samp>[</samp>’ and ‘<samp>]</samp>’, <em>character classes</em> can be specified +using the syntax +<code>[:</code><var>class</var><code>:]</code>, where <var>class</var> is one of the +following classes defined in the <small>POSIX</small> standard: +</p><div class="example"> +<pre class="example">alnum alpha ascii blank cntrl digit graph lower +print punct space upper word xdigit +</pre></div> +<p>A character class matches any character belonging to that class. +The <code>word</code> character class matches letters, digits, and the character +‘<samp>_</samp>’. +</p> +<p>Within ‘<samp>[</samp>’ and ‘<samp>]</samp>’, an <em>equivalence class</em> can be +specified using the syntax <code>[=</code><var>c</var><code>=]</code>, which +matches all characters with the same collation weight (as defined +by the current locale) as the character <var>c</var>. +</p> +<p>Within ‘<samp>[</samp>’ and ‘<samp>]</samp>’, the syntax <code>[.</code><var>symbol</var><code>.]</code> +matches the collating symbol <var>symbol</var>. +</p></dd> +</dl> + +<p>If the <code>extglob</code> shell option is enabled using the <code>shopt</code> +builtin, the shell recognizes several extended pattern matching operators. +In the following description, a <var>pattern-list</var> is a list of one +or more patterns separated by a ‘<samp>|</samp>’. +When matching filenames, the <code>dotglob</code> shell option determines +the set of filenames that are tested, as described above. +Composite patterns may be formed using one or more of the following +sub-patterns: +</p> +<dl compact="compact"> +<dt><span><code>?(<var>pattern-list</var>)</code></span></dt> +<dd><p>Matches zero or one occurrence of the given patterns. +</p> +</dd> +<dt><span><code>*(<var>pattern-list</var>)</code></span></dt> +<dd><p>Matches zero or more occurrences of the given patterns. +</p> +</dd> +<dt><span><code>+(<var>pattern-list</var>)</code></span></dt> +<dd><p>Matches one or more occurrences of the given patterns. +</p> +</dd> +<dt><span><code>@(<var>pattern-list</var>)</code></span></dt> +<dd><p>Matches one of the given patterns. +</p> +</dd> +<dt><span><code>!(<var>pattern-list</var>)</code></span></dt> +<dd><p>Matches anything except one of the given patterns. +</p></dd> +</dl> + +<p>The <code>extglob</code> option changes the behavior of the parser, since the +parentheses are normally treated as operators with syntactic meaning. +To ensure that extended matching patterns are parsed correctly, make sure +that <code>extglob</code> is enabled before parsing constructs containing the +patterns, including shell functions and command substitutions. +</p> +<p>When matching filenames, the <code>dotglob</code> shell option determines +the set of filenames that are tested: +when <code>dotglob</code> is enabled, the set of filenames includes all files +beginning with ‘<samp>.</samp>’, but the filenames +‘<samp>.</samp>’ and ‘<samp>..</samp>’ must be matched by a +pattern or sub-pattern that begins with a dot; +when it is disabled, the set does not +include any filenames beginning with “.” unless the pattern +or sub-pattern begins with a ‘<samp>.</samp>’. +As above, ‘<samp>.</samp>’ only has a special meaning when matching filenames. +</p> +<p>Complicated extended pattern matching against long strings is slow, +especially when the patterns contain alternations and the strings +contain multiple matches. +Using separate matches against shorter strings, or using arrays of +strings instead of a single long string, may be faster. +</p> +<hr> +</div> +</div> +<div class="subsection" id="Quote-Removal"> +<div class="header"> +<p> +Previous: <a href="#Filename-Expansion" accesskey="p" rel="prev">Filename Expansion</a>, Up: <a href="#Shell-Expansions" accesskey="u" rel="up">Shell Expansions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Quote-Removal-1"></span><h4 class="subsection">3.5.9 Quote Removal</h4> + +<p>After the preceding expansions, all unquoted occurrences of the +characters ‘<samp>\</samp>’, ‘<samp>'</samp>’, and ‘<samp>"</samp>’ that did not +result from one of the above expansions are removed. +</p> +<hr> +</div> +</div> +<div class="section" id="Redirections"> +<div class="header"> +<p> +Next: <a href="#Executing-Commands" accesskey="n" rel="next">Executing Commands</a>, Previous: <a href="#Shell-Expansions" accesskey="p" rel="prev">Shell Expansions</a>, Up: <a href="#Basic-Shell-Features" accesskey="u" rel="up">Basic Shell Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Redirections-1"></span><h3 class="section">3.6 Redirections</h3> +<span id="index-redirection"></span> + +<p>Before a command is executed, its input and output +may be <em>redirected</em> +using a special notation interpreted by the shell. +<em>Redirection</em> allows commands’ file handles to be +duplicated, opened, closed, +made to refer to different files, +and can change the files the command reads from and writes to. +Redirection may also be used to modify file handles in the +current shell execution environment. The following redirection +operators may precede or appear anywhere within a +simple command or may follow a command. +Redirections are processed in the order they appear, from +left to right. +</p> +<p>Each redirection that may be preceded by a file descriptor number +may instead be preceded by a word of the form {<var>varname</var>}. +In this case, for each redirection operator except +>&- and <&-, the shell will allocate a file descriptor greater +than 10 and assign it to {<var>varname</var>}. If >&- or <&- is preceded +by {<var>varname</var>}, the value of <var>varname</var> defines the file +descriptor to close. +If {<var>varname</var>} is supplied, the redirection persists beyond +the scope of the command, allowing the shell programmer to manage +the file descriptor’s lifetime manually. +The <code>varredir_close</code> shell option manages this behavior +(see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>). +</p> +<p>In the following descriptions, if the file descriptor number is +omitted, and the first character of the redirection operator is +‘<samp><</samp>’, the redirection refers to the standard input (file +descriptor 0). If the first character of the redirection operator +is ‘<samp>></samp>’, the redirection refers to the standard output (file +descriptor 1). +</p> +<p>The word following the redirection operator in the following +descriptions, unless otherwise noted, is subjected to brace expansion, +tilde expansion, parameter expansion, command substitution, arithmetic +expansion, quote removal, filename expansion, and word splitting. +If it expands to more than one word, Bash reports an error. +</p> +<p>Note that the order of redirections is significant. For example, +the command +</p><div class="example"> +<pre class="example">ls > <var>dirlist</var> 2>&1 +</pre></div> +<p>directs both standard output (file descriptor 1) and standard error +(file descriptor 2) to the file <var>dirlist</var>, while the command +</p><div class="example"> +<pre class="example">ls 2>&1 > <var>dirlist</var> +</pre></div> +<p>directs only the standard output to file <var>dirlist</var>, +because the standard error was made a copy of the standard output +before the standard output was redirected to <var>dirlist</var>. +</p> +<p>Bash handles several filenames specially when they are used in +redirections, as described in the following table. +If the operating system on which Bash is running provides these +special files, bash will use them; otherwise it will emulate them +internally with the behavior described below. +</p> +<dl compact="compact"> +<dt><span><code>/dev/fd/<var>fd</var></code></span></dt> +<dd><p>If <var>fd</var> is a valid integer, file descriptor <var>fd</var> is duplicated. +</p> +</dd> +<dt><span><code>/dev/stdin</code></span></dt> +<dd><p>File descriptor 0 is duplicated. +</p> +</dd> +<dt><span><code>/dev/stdout</code></span></dt> +<dd><p>File descriptor 1 is duplicated. +</p> +</dd> +<dt><span><code>/dev/stderr</code></span></dt> +<dd><p>File descriptor 2 is duplicated. +</p> +</dd> +<dt><span><code>/dev/tcp/<var>host</var>/<var>port</var></code></span></dt> +<dd><p>If <var>host</var> is a valid hostname or Internet address, and <var>port</var> +is an integer port number or service name, Bash attempts to open +the corresponding TCP socket. +</p> +</dd> +<dt><span><code>/dev/udp/<var>host</var>/<var>port</var></code></span></dt> +<dd><p>If <var>host</var> is a valid hostname or Internet address, and <var>port</var> +is an integer port number or service name, Bash attempts to open +the corresponding UDP socket. +</p></dd> +</dl> + +<p>A failure to open or create a file causes the redirection to fail. +</p> +<p>Redirections using file descriptors greater than 9 should be used with +care, as they may conflict with file descriptors the shell uses +internally. +</p> +<ul class="section-toc"> +<li><a href="#Redirecting-Input" accesskey="1">Redirecting Input</a></li> +<li><a href="#Redirecting-Output" accesskey="2">Redirecting Output</a></li> +<li><a href="#Appending-Redirected-Output" accesskey="3">Appending Redirected Output</a></li> +<li><a href="#Redirecting-Standard-Output-and-Standard-Error" accesskey="4">Redirecting Standard Output and Standard Error</a></li> +<li><a href="#Appending-Standard-Output-and-Standard-Error" accesskey="5">Appending Standard Output and Standard Error</a></li> +<li><a href="#Here-Documents" accesskey="6">Here Documents</a></li> +<li><a href="#Here-Strings" accesskey="7">Here Strings</a></li> +<li><a href="#Duplicating-File-Descriptors" accesskey="8">Duplicating File Descriptors</a></li> +<li><a href="#Moving-File-Descriptors" accesskey="9">Moving File Descriptors</a></li> +<li><a href="#Opening-File-Descriptors-for-Reading-and-Writing">Opening File Descriptors for Reading and Writing</a></li> +</ul> +<div class="subsection" id="Redirecting-Input"> +<h4 class="subsection">3.6.1 Redirecting Input</h4> +<p>Redirection of input causes the file whose name results from +the expansion of <var>word</var> +to be opened for reading on file descriptor <code>n</code>, +or the standard input (file descriptor 0) if <code>n</code> +is not specified. +</p> +<p>The general format for redirecting input is: +</p><div class="example"> +<pre class="example">[<var>n</var>]<<var>word</var> +</pre></div> + +</div> +<div class="subsection" id="Redirecting-Output"> +<h4 class="subsection">3.6.2 Redirecting Output</h4> +<p>Redirection of output causes the file whose name results from +the expansion of <var>word</var> +to be opened for writing on file descriptor <var>n</var>, +or the standard output (file descriptor 1) if <var>n</var> +is not specified. If the file does not exist it is created; +if it does exist it is truncated to zero size. +</p> +<p>The general format for redirecting output is: +</p><div class="example"> +<pre class="example">[<var>n</var>]>[|]<var>word</var> +</pre></div> + +<p>If the redirection operator is ‘<samp>></samp>’, and the <code>noclobber</code> +option to the <code>set</code> builtin has been enabled, the redirection +will fail if the file whose name results from the expansion of +<var>word</var> exists and is a regular file. +If the redirection operator is ‘<samp>>|</samp>’, or the redirection operator is +‘<samp>></samp>’ and the <code>noclobber</code> option is not enabled, the redirection +is attempted even if the file named by <var>word</var> exists. +</p> +</div> +<div class="subsection" id="Appending-Redirected-Output"> +<h4 class="subsection">3.6.3 Appending Redirected Output</h4> +<p>Redirection of output in this fashion +causes the file whose name results from +the expansion of <var>word</var> +to be opened for appending on file descriptor <var>n</var>, +or the standard output (file descriptor 1) if <var>n</var> +is not specified. If the file does not exist it is created. +</p> +<p>The general format for appending output is: +</p><div class="example"> +<pre class="example">[<var>n</var>]>><var>word</var> +</pre></div> + +</div> +<div class="subsection" id="Redirecting-Standard-Output-and-Standard-Error"> +<h4 class="subsection">3.6.4 Redirecting Standard Output and Standard Error</h4> +<p>This construct allows both the +standard output (file descriptor 1) and +the standard error output (file descriptor 2) +to be redirected to the file whose name is the +expansion of <var>word</var>. +</p> +<p>There are two formats for redirecting standard output and +standard error: +</p><div class="example"> +<pre class="example">&><var>word</var> +</pre></div> +<p>and +</p><div class="example"> +<pre class="example">>&<var>word</var> +</pre></div> +<p>Of the two forms, the first is preferred. +This is semantically equivalent to +</p><div class="example"> +<pre class="example">><var>word</var> 2>&1 +</pre></div> +<p>When using the second form, <var>word</var> may not expand to a number or +‘<samp>-</samp>’. If it does, other redirection operators apply +(see Duplicating File Descriptors below) for compatibility reasons. +</p> +</div> +<div class="subsection" id="Appending-Standard-Output-and-Standard-Error"> +<h4 class="subsection">3.6.5 Appending Standard Output and Standard Error</h4> +<p>This construct allows both the +standard output (file descriptor 1) and +the standard error output (file descriptor 2) +to be appended to the file whose name is the +expansion of <var>word</var>. +</p> +<p>The format for appending standard output and standard error is: +</p><div class="example"> +<pre class="example">&>><var>word</var> +</pre></div> +<p>This is semantically equivalent to +</p><div class="example"> +<pre class="example">>><var>word</var> 2>&1 +</pre></div> +<p>(see Duplicating File Descriptors below). +</p> +</div> +<div class="subsection" id="Here-Documents"> +<h4 class="subsection">3.6.6 Here Documents</h4> +<p>This type of redirection instructs the shell to read input from the +current source until a line containing only <var>word</var> +(with no trailing blanks) is seen. All of +the lines read up to that point are then used as the standard +input (or file descriptor <var>n</var> if <var>n</var> is specified) for a command. +</p> +<p>The format of here-documents is: +</p><div class="example"> +<pre class="example">[<var>n</var>]<<[-]<var>word</var> + <var>here-document</var> +<var>delimiter</var> +</pre></div> + +<p>No parameter and variable expansion, command substitution, +arithmetic expansion, or filename expansion is performed on +<var>word</var>. If any part of <var>word</var> is quoted, the +<var>delimiter</var> is the result of quote removal on <var>word</var>, +and the lines in the here-document are not expanded. +If <var>word</var> is unquoted, +all lines of the here-document are subjected to +parameter expansion, command substitution, and arithmetic expansion, +the character sequence <code>\newline</code> is ignored, and ‘<samp>\</samp>’ +must be used to quote the characters +‘<samp>\</samp>’, ‘<samp>$</samp>’, and ‘<samp>`</samp>’. +</p> +<p>If the redirection operator is ‘<samp><<-</samp>’, +then all leading tab characters are stripped from input lines and the +line containing <var>delimiter</var>. +This allows here-documents within shell scripts to be indented in a +natural fashion. +</p> +</div> +<div class="subsection" id="Here-Strings"> +<h4 class="subsection">3.6.7 Here Strings</h4> +<p>A variant of here documents, the format is: +</p><div class="example"> +<pre class="example">[<var>n</var>]<<< <var>word</var> +</pre></div> + +<p>The <var>word</var> undergoes +tilde expansion, parameter and variable expansion, +command substitution, arithmetic expansion, and quote removal. +Filename expansion and word splitting are not performed. +The result is supplied as a single string, +with a newline appended, +to the command on its +standard input (or file descriptor <var>n</var> if <var>n</var> is specified). +</p> +</div> +<div class="subsection" id="Duplicating-File-Descriptors"> +<h4 class="subsection">3.6.8 Duplicating File Descriptors</h4> +<p>The redirection operator +</p><div class="example"> +<pre class="example">[<var>n</var>]<&<var>word</var> +</pre></div> +<p>is used to duplicate input file descriptors. +If <var>word</var> +expands to one or more digits, the file descriptor denoted by <var>n</var> +is made to be a copy of that file descriptor. +If the digits in <var>word</var> do not specify a file descriptor open for +input, a redirection error occurs. +If <var>word</var> +evaluates to ‘<samp>-</samp>’, file descriptor <var>n</var> is closed. +If <var>n</var> is not specified, the standard input (file descriptor 0) is used. +</p> +<p>The operator +</p><div class="example"> +<pre class="example">[<var>n</var>]>&<var>word</var> +</pre></div> +<p>is used similarly to duplicate output file descriptors. If +<var>n</var> is not specified, the standard output (file descriptor 1) is used. +If the digits in <var>word</var> do not specify a file descriptor open for +output, a redirection error occurs. +If <var>word</var> +evaluates to ‘<samp>-</samp>’, file descriptor <var>n</var> is closed. +As a special case, if <var>n</var> is omitted, and <var>word</var> does not +expand to one or more digits or ‘<samp>-</samp>’, the standard output and standard +error are redirected as described previously. +</p> +</div> +<div class="subsection" id="Moving-File-Descriptors"> +<h4 class="subsection">3.6.9 Moving File Descriptors</h4> +<p>The redirection operator +</p><div class="example"> +<pre class="example">[<var>n</var>]<&<var>digit</var>- +</pre></div> +<p>moves the file descriptor <var>digit</var> to file descriptor <var>n</var>, +or the standard input (file descriptor 0) if <var>n</var> is not specified. +<var>digit</var> is closed after being duplicated to <var>n</var>. +</p> +<p>Similarly, the redirection operator +</p><div class="example"> +<pre class="example">[<var>n</var>]>&<var>digit</var>- +</pre></div> +<p>moves the file descriptor <var>digit</var> to file descriptor <var>n</var>, +or the standard output (file descriptor 1) if <var>n</var> is not specified. +</p> +</div> +<div class="subsection" id="Opening-File-Descriptors-for-Reading-and-Writing"> +<h4 class="subsection">3.6.10 Opening File Descriptors for Reading and Writing</h4> +<p>The redirection operator +</p><div class="example"> +<pre class="example">[<var>n</var>]<><var>word</var> +</pre></div> +<p>causes the file whose name is the expansion of <var>word</var> +to be opened for both reading and writing on file descriptor +<var>n</var>, or on file descriptor 0 if <var>n</var> +is not specified. If the file does not exist, it is created. +</p> +<hr> +</div> +</div> +<div class="section" id="Executing-Commands"> +<div class="header"> +<p> +Next: <a href="#Shell-Scripts" accesskey="n" rel="next">Shell Scripts</a>, Previous: <a href="#Redirections" accesskey="p" rel="prev">Redirections</a>, Up: <a href="#Basic-Shell-Features" accesskey="u" rel="up">Basic Shell Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Executing-Commands-1"></span><h3 class="section">3.7 Executing Commands</h3> + + +<ul class="section-toc"> +<li><a href="#Simple-Command-Expansion" accesskey="1">Simple Command Expansion</a></li> +<li><a href="#Command-Search-and-Execution" accesskey="2">Command Search and Execution</a></li> +<li><a href="#Command-Execution-Environment" accesskey="3">Command Execution Environment</a></li> +<li><a href="#Environment" accesskey="4">Environment</a></li> +<li><a href="#Exit-Status" accesskey="5">Exit Status</a></li> +<li><a href="#Signals" accesskey="6">Signals</a></li> +</ul> +<hr> +<div class="subsection" id="Simple-Command-Expansion"> +<div class="header"> +<p> +Next: <a href="#Command-Search-and-Execution" accesskey="n" rel="next">Command Search and Execution</a>, Up: <a href="#Executing-Commands" accesskey="u" rel="up">Executing Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Simple-Command-Expansion-1"></span><h4 class="subsection">3.7.1 Simple Command Expansion</h4> +<span id="index-command-expansion"></span> + +<p>When a simple command is executed, the shell performs the following +expansions, assignments, and redirections, from left to right, in +the following order. +</p> +<ol> +<li> The words that the parser has marked as variable assignments (those +preceding the command name) and redirections are saved for later +processing. + +</li><li> The words that are not variable assignments or redirections are +expanded (see <a href="#Shell-Expansions">Shell Expansions</a>). +If any words remain after expansion, the first word +is taken to be the name of the command and the remaining words are +the arguments. + +</li><li> Redirections are performed as described above (see <a href="#Redirections">Redirections</a>). + +</li><li> The text after the ‘<samp>=</samp>’ in each variable assignment undergoes tilde +expansion, parameter expansion, command substitution, arithmetic expansion, +and quote removal before being assigned to the variable. +</li></ol> + +<p>If no command name results, the variable assignments affect the current +shell environment. +In the case of such a command (one that consists only of assignment +statements and redirections), assignment statements are performed before +redirections. +Otherwise, the variables are added to the environment +of the executed command and do not affect the current shell environment. +If any of the assignments attempts to assign a value to a readonly variable, +an error occurs, and the command exits with a non-zero status. +</p> +<p>If no command name results, redirections are performed, but do not +affect the current shell environment. A redirection error causes the +command to exit with a non-zero status. +</p> +<p>If there is a command name left after expansion, execution proceeds as +described below. Otherwise, the command exits. If one of the expansions +contained a command substitution, the exit status of the command is +the exit status of the last command substitution performed. If there +were no command substitutions, the command exits with a status of zero. +</p> +<hr> +</div> +<div class="subsection" id="Command-Search-and-Execution"> +<div class="header"> +<p> +Next: <a href="#Command-Execution-Environment" accesskey="n" rel="next">Command Execution Environment</a>, Previous: <a href="#Simple-Command-Expansion" accesskey="p" rel="prev">Simple Command Expansion</a>, Up: <a href="#Executing-Commands" accesskey="u" rel="up">Executing Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Command-Search-and-Execution-1"></span><h4 class="subsection">3.7.2 Command Search and Execution</h4> +<span id="index-command-execution"></span> +<span id="index-command-search"></span> + +<p>After a command has been split into words, if it results in a +simple command and an optional list of arguments, the following +actions are taken. +</p> +<ol> +<li> If the command name contains no slashes, the shell attempts to +locate it. If there exists a shell function by that name, that +function is invoked as described in <a href="#Shell-Functions">Shell Functions</a>. + +</li><li> If the name does not match a function, the shell searches for +it in the list of shell builtins. If a match is found, that +builtin is invoked. + +</li><li> If the name is neither a shell function nor a builtin, +and contains no slashes, Bash searches each element of +<code>$PATH</code> for a directory containing an executable file +by that name. Bash uses a hash table to remember the full +pathnames of executable files to avoid multiple <code>PATH</code> searches +(see the description of <code>hash</code> in <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>). +A full search of the directories in <code>$PATH</code> +is performed only if the command is not found in the hash table. +If the search is unsuccessful, the shell searches for a defined shell +function named <code>command_not_found_handle</code>. +If that function exists, it is invoked in a separate execution environment +with the original command and +the original command’s arguments as its arguments, and the function’s +exit status becomes the exit status of that subshell. +If that function is not defined, the shell prints an error +message and returns an exit status of 127. + +</li><li> If the search is successful, or if the command name contains +one or more slashes, the shell executes the named program in +a separate execution environment. +Argument 0 is set to the name given, and the remaining arguments +to the command are set to the arguments supplied, if any. + +</li><li> If this execution fails because the file is not in executable +format, and the file is not a directory, it is assumed to be a +<em>shell script</em> and the shell executes it as described in +<a href="#Shell-Scripts">Shell Scripts</a>. + +</li><li> If the command was not begun asynchronously, the shell waits for +the command to complete and collects its exit status. + +</li></ol> + +<hr> +</div> +<div class="subsection" id="Command-Execution-Environment"> +<div class="header"> +<p> +Next: <a href="#Environment" accesskey="n" rel="next">Environment</a>, Previous: <a href="#Command-Search-and-Execution" accesskey="p" rel="prev">Command Search and Execution</a>, Up: <a href="#Executing-Commands" accesskey="u" rel="up">Executing Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Command-Execution-Environment-1"></span><h4 class="subsection">3.7.3 Command Execution Environment</h4> +<span id="index-execution-environment"></span> + +<p>The shell has an <em>execution environment</em>, which consists of the +following: +</p> +<ul> +<li> open files inherited by the shell at invocation, as modified by +redirections supplied to the <code>exec</code> builtin + +</li><li> the current working directory as set by <code>cd</code>, <code>pushd</code>, or +<code>popd</code>, or inherited by the shell at invocation + +</li><li> the file creation mode mask as set by <code>umask</code> or inherited from +the shell’s parent + +</li><li> current traps set by <code>trap</code> + +</li><li> shell parameters that are set by variable assignment or with <code>set</code> +or inherited from the shell’s parent in the environment + +</li><li> shell functions defined during execution or inherited from the shell’s +parent in the environment + +</li><li> options enabled at invocation (either by default or with command-line +arguments) or by <code>set</code> + +</li><li> options enabled by <code>shopt</code> (see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>) + +</li><li> shell aliases defined with <code>alias</code> (see <a href="#Aliases">Aliases</a>) + +</li><li> various process <small>ID</small>s, including those of background jobs +(see <a href="#Lists">Lists of Commands</a>), the value of <code>$$</code>, and the value of +<code>$PPID</code> + +</li></ul> + +<p>When a simple command other than a builtin or shell function +is to be executed, it +is invoked in a separate execution environment that consists of +the following. Unless otherwise noted, the values are inherited +from the shell. +</p> +<ul> +<li> the shell’s open files, plus any modifications and additions specified +by redirections to the command + +</li><li> the current working directory + +</li><li> the file creation mode mask + +</li><li> shell variables and functions marked for export, along with variables +exported for the command, passed in the environment (see <a href="#Environment">Environment</a>) + +</li><li> traps caught by the shell are reset to the values inherited from the +shell’s parent, and traps ignored by the shell are ignored + +</li></ul> + +<p>A command invoked in this separate environment cannot affect the +shell’s execution environment. +</p> +<p>A <em>subshell</em> is a copy of the shell process. +</p> +<p>Command substitution, commands grouped with parentheses, +and asynchronous commands are invoked in a +subshell environment that is a duplicate of the shell environment, +except that traps caught by the shell are reset to the values +that the shell inherited from its parent at invocation. Builtin +commands that are invoked as part of a pipeline are also executed +in a subshell environment. Changes made to the subshell environment +cannot affect the shell’s execution environment. +</p> +<p>Subshells spawned to execute command substitutions inherit the value of +the <samp>-e</samp> option from the parent shell. When not in <small>POSIX</small> mode, +Bash clears the <samp>-e</samp> option in such subshells. +</p> +<p>If a command is followed by a ‘<samp>&</samp>’ and job control is not active, the +default standard input for the command is the empty file <samp>/dev/null</samp>. +Otherwise, the invoked command inherits the file descriptors of the calling +shell as modified by redirections. +</p> +<hr> +</div> +<div class="subsection" id="Environment"> +<div class="header"> +<p> +Next: <a href="#Exit-Status" accesskey="n" rel="next">Exit Status</a>, Previous: <a href="#Command-Execution-Environment" accesskey="p" rel="prev">Command Execution Environment</a>, Up: <a href="#Executing-Commands" accesskey="u" rel="up">Executing Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Environment-1"></span><h4 class="subsection">3.7.4 Environment</h4> +<span id="index-environment"></span> + +<p>When a program is invoked it is given an array of strings +called the <em>environment</em>. +This is a list of name-value pairs, of the form <code>name=value</code>. +</p> +<p>Bash provides several ways to manipulate the environment. +On invocation, the shell scans its own environment and +creates a parameter for each name found, automatically marking +it for <code>export</code> +to child processes. Executed commands inherit the environment. +The <code>export</code> and ‘<samp>declare -x</samp>’ +commands allow parameters and functions to be added to and +deleted from the environment. If the value of a parameter +in the environment is modified, the new value becomes part +of the environment, replacing the old. The environment +inherited by any executed command consists of the shell’s +initial environment, whose values may be modified in the shell, +less any pairs removed by the <code>unset</code> and ‘<samp>export -n</samp>’ +commands, plus any additions via the <code>export</code> and +‘<samp>declare -x</samp>’ commands. +</p> +<p>The environment for any simple command +or function may be augmented temporarily by prefixing it with +parameter assignments, as described in <a href="#Shell-Parameters">Shell Parameters</a>. +These assignment statements affect only the environment seen +by that command. +</p> +<p>If the <samp>-k</samp> option is set (see <a href="#The-Set-Builtin">The Set Builtin</a>), then all +parameter assignments are placed in the environment for a command, +not just those that precede the command name. +</p> +<p>When Bash invokes an external command, the variable ‘<samp>$_</samp>’ +is set to the full pathname of the command and passed to that +command in its environment. +</p> +<hr> +</div> +<div class="subsection" id="Exit-Status"> +<div class="header"> +<p> +Next: <a href="#Signals" accesskey="n" rel="next">Signals</a>, Previous: <a href="#Environment" accesskey="p" rel="prev">Environment</a>, Up: <a href="#Executing-Commands" accesskey="u" rel="up">Executing Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Exit-Status-1"></span><h4 class="subsection">3.7.5 Exit Status</h4> +<span id="index-exit-status-1"></span> + +<p>The exit status of an executed command is the value returned by the +<code>waitpid</code> system call or equivalent function. Exit statuses +fall between 0 and 255, though, as explained below, the shell may +use values above 125 specially. Exit statuses from shell builtins and +compound commands are also limited to this range. Under certain +circumstances, the shell will use special values to indicate specific +failure modes. +</p> +<p>For the shell’s purposes, a command which exits with a +zero exit status has succeeded. +A non-zero exit status indicates failure. +This seemingly counter-intuitive scheme is used so there +is one well-defined way to indicate success and a variety of +ways to indicate various failure modes. +When a command terminates on a fatal signal whose number is <var>N</var>, +Bash uses the value 128+<var>N</var> as the exit status. +</p> +<p>If a command is not found, the child process created to +execute it returns a status of 127. If a command is found +but is not executable, the return status is 126. +</p> +<p>If a command fails because of an error during expansion or redirection, +the exit status is greater than zero. +</p> +<p>The exit status is used by the Bash conditional commands +(see <a href="#Conditional-Constructs">Conditional Constructs</a>) and some of the list +constructs (see <a href="#Lists">Lists of Commands</a>). +</p> +<p>All of the Bash builtins return an exit status of zero if they succeed +and a non-zero status on failure, so they may be used by the +conditional and list constructs. +All builtins return an exit status of 2 to indicate incorrect usage, +generally invalid options or missing arguments. +</p> +<p>The exit status of the last command is available in the special +parameter $? (see <a href="#Special-Parameters">Special Parameters</a>). +</p> +<hr> +</div> +<div class="subsection" id="Signals"> +<div class="header"> +<p> +Previous: <a href="#Exit-Status" accesskey="p" rel="prev">Exit Status</a>, Up: <a href="#Executing-Commands" accesskey="u" rel="up">Executing Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Signals-1"></span><h4 class="subsection">3.7.6 Signals</h4> +<span id="index-signal-handling"></span> + +<p>When Bash is interactive, in the absence of any traps, it ignores +<code>SIGTERM</code> (so that ‘<samp>kill 0</samp>’ does not kill an interactive shell), +and <code>SIGINT</code> +is caught and handled (so that the <code>wait</code> builtin is interruptible). +When Bash receives a <code>SIGINT</code>, it breaks out of any executing loops. +In all cases, Bash ignores <code>SIGQUIT</code>. +If job control is in effect (see <a href="#Job-Control">Job Control</a>), Bash +ignores <code>SIGTTIN</code>, <code>SIGTTOU</code>, and <code>SIGTSTP</code>. +</p> +<p>Non-builtin commands started by Bash have signal handlers set to the +values inherited by the shell from its parent. +When job control is not in effect, asynchronous commands +ignore <code>SIGINT</code> and <code>SIGQUIT</code> in addition to these inherited +handlers. +Commands run as a result of +command substitution ignore the keyboard-generated job control signals +<code>SIGTTIN</code>, <code>SIGTTOU</code>, and <code>SIGTSTP</code>. +</p> +<p>The shell exits by default upon receipt of a <code>SIGHUP</code>. +Before exiting, an interactive shell resends the <code>SIGHUP</code> to +all jobs, running or stopped. +Stopped jobs are sent <code>SIGCONT</code> to ensure that they receive +the <code>SIGHUP</code>. +To prevent the shell from sending the <code>SIGHUP</code> signal to a +particular job, it should be removed +from the jobs table with the <code>disown</code> +builtin (see <a href="#Job-Control-Builtins">Job Control Builtins</a>) or marked +to not receive <code>SIGHUP</code> using <code>disown -h</code>. +</p> +<p>If the <code>huponexit</code> shell option has been set with <code>shopt</code> +(see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>), Bash sends a <code>SIGHUP</code> to all jobs when +an interactive login shell exits. +</p> +<p>If Bash is waiting for a command to complete and receives a signal +for which a trap has been set, the trap will not be executed until +the command completes. +When Bash is waiting for an asynchronous +command via the <code>wait</code> builtin, the reception of a signal for +which a trap has been set will cause the <code>wait</code> builtin to return +immediately with an exit status greater than 128, immediately after +which the trap is executed. +</p> +<p>When job control is not enabled, and Bash is waiting for a foreground +command to complete, the shell receives keyboard-generated signals +such as <code>SIGINT</code> (usually generated by ‘<samp>^C</samp>’) that users +commonly intend to send to that command. +This happens because the shell and the command are in the same process +group as the terminal, and ‘<samp>^C</samp>’ sends <code>SIGINT</code> to all processes +in that process group. +See <a href="#Job-Control">Job Control</a>, for a more in-depth discussion of process groups. +</p> +<p>When Bash is running without job control enabled and receives <code>SIGINT</code> +while waiting for a foreground command, it waits until that foreground +command terminates and then decides what to do about the <code>SIGINT</code>: +</p> +<ol> +<li> If the command terminates due to the <code>SIGINT</code>, Bash concludes +that the user meant to end the entire script, and acts on the +<code>SIGINT</code> (e.g., by running a <code>SIGINT</code> trap or exiting itself); + +</li><li> If the pipeline does not terminate due to <code>SIGINT</code>, the program +handled the <code>SIGINT</code> itself and did not treat it as a fatal signal. +In that case, Bash does not treat <code>SIGINT</code> as a fatal signal, +either, instead assuming that the <code>SIGINT</code> was used as part of the +program’s normal operation (e.g., <code>emacs</code> uses it to abort editing +commands) or deliberately discarded. However, Bash will run any +trap set on <code>SIGINT</code>, as it does with any other trapped signal it +receives while it is waiting for the foreground command to +complete, for compatibility. +</li></ol> + +<hr> +</div> +</div> +<div class="section" id="Shell-Scripts"> +<div class="header"> +<p> +Previous: <a href="#Executing-Commands" accesskey="p" rel="prev">Executing Commands</a>, Up: <a href="#Basic-Shell-Features" accesskey="u" rel="up">Basic Shell Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Shell-Scripts-1"></span><h3 class="section">3.8 Shell Scripts</h3> +<span id="index-shell-script"></span> + +<p>A shell script is a text file containing shell commands. When such +a file is used as the first non-option argument when invoking Bash, +and neither the <samp>-c</samp> nor <samp>-s</samp> option is supplied +(see <a href="#Invoking-Bash">Invoking Bash</a>), +Bash reads and executes commands from the file, then exits. This +mode of operation creates a non-interactive shell. The shell first +searches for the file in the current directory, and looks in the +directories in <code>$PATH</code> if not found there. +</p> +<p>When Bash runs +a shell script, it sets the special parameter <code>0</code> to the name +of the file, rather than the name of the shell, and the positional +parameters are set to the remaining arguments, if any are given. +If no additional arguments are supplied, the positional parameters +are unset. +</p> +<p>A shell script may be made executable by using the <code>chmod</code> command +to turn on the execute bit. When Bash finds such a file while +searching the <code>$PATH</code> for a command, it creates a +new instance of itself +to execute it. +In other words, executing +</p><div class="example"> +<pre class="example">filename <var>arguments</var> +</pre></div> +<p>is equivalent to executing +</p><div class="example"> +<pre class="example">bash filename <var>arguments</var> +</pre></div> + +<p>if <code>filename</code> is an executable shell script. +This subshell reinitializes itself, so that the effect is as if a +new shell had been invoked to interpret the script, with the +exception that the locations of commands remembered by the parent +(see the description of <code>hash</code> in <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>) +are retained by the child. +</p> +<p>Most versions of Unix make this a part of the operating system’s command +execution mechanism. If the first line of a script begins with +the two characters ‘<samp>#!</samp>’, the remainder of the line specifies +an interpreter for the program and, depending on the operating system, one +or more optional arguments for that interpreter. +Thus, you can specify Bash, <code>awk</code>, Perl, or some other +interpreter and write the rest of the script file in that language. +</p> +<p>The arguments to the interpreter +consist of one or more optional arguments following the interpreter +name on the first line of the script file, followed by the name of +the script file, followed by the rest of the arguments supplied to the +script. +The details of how the interpreter line is split into an interpreter name +and a set of arguments vary across systems. +Bash will perform this action on operating systems that do not handle it +themselves. +Note that some older versions of Unix limit the interpreter +name and a single argument to a maximum of 32 characters, so it’s not +portable to assume that using more than one argument will work. +</p> +<p>Bash scripts often begin with <code>#! /bin/bash</code> (assuming that +Bash has been installed in <samp>/bin</samp>), since this ensures that +Bash will be used to interpret the script, even if it is executed +under another shell. It’s a common idiom to use <code>env</code> to find +<code>bash</code> even if it’s been installed in another directory: +<code>#!/usr/bin/env bash</code> will find the first occurrence of <code>bash</code> +in <code>$PATH</code>. +</p> +<hr> +</div> +</div> +<div class="chapter" id="Shell-Builtin-Commands"> +<div class="header"> +<p> +Next: <a href="#Shell-Variables" accesskey="n" rel="next">Shell Variables</a>, Previous: <a href="#Basic-Shell-Features" accesskey="p" rel="prev">Basic Shell Features</a>, Up: <a href="#Top" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Shell-Builtin-Commands-1"></span><h2 class="chapter">4 Shell Builtin Commands</h2> + + +<p>Builtin commands are contained within the shell itself. +When the name of a builtin command is used as the first word of +a simple command (see <a href="#Simple-Commands">Simple Commands</a>), the shell executes +the command directly, without invoking another program. +Builtin commands are necessary to implement functionality impossible +or inconvenient to obtain with separate utilities. +</p> +<p>This section briefly describes the builtins which Bash inherits from +the Bourne Shell, as well as the builtin commands which are unique +to or have been extended in Bash. +</p> +<p>Several builtin commands are described in other chapters: builtin +commands which provide the Bash interface to the job control +facilities (see <a href="#Job-Control-Builtins">Job Control Builtins</a>), the directory stack +(see <a href="#Directory-Stack-Builtins">Directory Stack Builtins</a>), the command history +(see <a href="#Bash-History-Builtins">Bash History Builtins</a>), and the programmable completion +facilities (see <a href="#Programmable-Completion-Builtins">Programmable Completion Builtins</a>). +</p> +<p>Many of the builtins have been extended by <small>POSIX</small> or Bash. +</p> +<p>Unless otherwise noted, each builtin command documented as accepting +options preceded by ‘<samp>-</samp>’ accepts ‘<samp>--</samp>’ +to signify the end of the options. +The <code>:</code>, <code>true</code>, <code>false</code>, and <code>test</code>/<code>[</code> +builtins do not accept options and do not treat ‘<samp>--</samp>’ specially. +The <code>exit</code>, <code>logout</code>, <code>return</code>, +<code>break</code>, <code>continue</code>, <code>let</code>, +and <code>shift</code> builtins accept and process arguments beginning +with ‘<samp>-</samp>’ without requiring ‘<samp>--</samp>’. +Other builtins that accept arguments but are not specified as accepting +options interpret arguments beginning with ‘<samp>-</samp>’ as invalid options and +require ‘<samp>--</samp>’ to prevent this interpretation. +</p> +<ul class="section-toc"> +<li><a href="#Bourne-Shell-Builtins" accesskey="1">Bourne Shell Builtins</a></li> +<li><a href="#Bash-Builtins" accesskey="2">Bash Builtin Commands</a></li> +<li><a href="#Modifying-Shell-Behavior" accesskey="3">Modifying Shell Behavior</a></li> +<li><a href="#Special-Builtins" accesskey="4">Special Builtins</a></li> +</ul> +<hr> +<div class="section" id="Bourne-Shell-Builtins"> +<div class="header"> +<p> +Next: <a href="#Bash-Builtins" accesskey="n" rel="next">Bash Builtin Commands</a>, Up: <a href="#Shell-Builtin-Commands" accesskey="u" rel="up">Shell Builtin Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Bourne-Shell-Builtins-1"></span><h3 class="section">4.1 Bourne Shell Builtins</h3> + +<p>The following shell builtin commands are inherited from the Bourne Shell. +These commands are implemented as specified by the <small>POSIX</small> standard. +</p> +<dl compact="compact"> +<dt id='index-_003a'><span><code>: <span class="roman">(a colon)</span></code><a href='#index-_003a' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">: [<var>arguments</var>] +</pre></div> + +<p>Do nothing beyond expanding <var>arguments</var> and performing redirections. +The return status is zero. +</p> +</dd> +<dt id='index-_002e'><span><code>. <span class="roman">(a period)</span></code><a href='#index-_002e' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">. <var>filename</var> [<var>arguments</var>] +</pre></div> + +<p>Read and execute commands from the <var>filename</var> argument in the +current shell context. If <var>filename</var> does not contain a slash, +the <code>PATH</code> variable is used to find <var>filename</var>, +but <var>filename</var> does not need to be executable. +When Bash is not in <small>POSIX</small> mode, it searches the current directory +if <var>filename</var> is not found in <code>$PATH</code>. +If any <var>arguments</var> are supplied, they become the positional +parameters when <var>filename</var> is executed. Otherwise the positional +parameters are unchanged. +If the <samp>-T</samp> option is enabled, <code>.</code> inherits any trap on +<code>DEBUG</code>; if it is not, any <code>DEBUG</code> trap string is saved and +restored around the call to <code>.</code>, and <code>.</code> unsets the +<code>DEBUG</code> trap while it executes. +If <samp>-T</samp> is not set, and the sourced file changes +the <code>DEBUG</code> trap, the new value is retained when <code>.</code> completes. +The return status is the exit status of the last command executed, or +zero if no commands are executed. If <var>filename</var> is not found, or +cannot be read, the return status is non-zero. +This builtin is equivalent to <code>source</code>. +</p> +</dd> +<dt id='index-break'><span><code>break</code><a href='#index-break' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">break [<var>n</var>] +</pre></div> + +<p>Exit from a <code>for</code>, <code>while</code>, <code>until</code>, or <code>select</code> loop. +If <var>n</var> is supplied, the <var>n</var>th enclosing loop is exited. +<var>n</var> must be greater than or equal to 1. +The return status is zero unless <var>n</var> is not greater than or equal to 1. +</p> +</dd> +<dt id='index-cd'><span><code>cd</code><a href='#index-cd' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">cd [-L|[-P [-e]] [-@] [<var>directory</var>] +</pre></div> + +<p>Change the current working directory to <var>directory</var>. +If <var>directory</var> is not supplied, the value of the <code>HOME</code> +shell variable is used. +If the shell variable +<code>CDPATH</code> exists, it is used as a search path: +each directory name in <code>CDPATH</code> is searched for +<var>directory</var>, with alternative directory names in <code>CDPATH</code> +separated by a colon (‘<samp>:</samp>’). +If <var>directory</var> begins with a slash, <code>CDPATH</code> is not used. +</p> +<p>The <samp>-P</samp> option means to not follow symbolic links: symbolic links +are resolved while <code>cd</code> is traversing <var>directory</var> and before +processing an instance of ‘<samp>..</samp>’ in <var>directory</var>. +</p> +<p>By default, or when the <samp>-L</samp> option is supplied, symbolic links +in <var>directory</var> are resolved after <code>cd</code> processes an instance +of ‘<samp>..</samp>’ in <var>directory</var>. +</p> +<p>If ‘<samp>..</samp>’ appears in <var>directory</var>, it is processed by removing the +immediately preceding pathname component, back to a slash or the beginning +of <var>directory</var>. +</p> +<p>If the <samp>-e</samp> option is supplied with <samp>-P</samp> +and the current working directory cannot be successfully determined +after a successful directory change, <code>cd</code> will return an unsuccessful +status. +</p> +<p>On systems that support it, the <samp>-@</samp> option presents the extended +attributes associated with a file as a directory. +</p> +<p>If <var>directory</var> is ‘<samp>-</samp>’, it is converted to <code>$OLDPWD</code> +before the directory change is attempted. +</p> +<p>If a non-empty directory name from <code>CDPATH</code> is used, or if +‘<samp>-</samp>’ is the first argument, and the directory change is +successful, the absolute pathname of the new working directory is +written to the standard output. +</p> +<p>If the directory change is successful, <code>cd</code> sets the value of the +<code>PWD</code> environment variable to the new directory name, and sets the +<code>OLDPWD</code> environment variable to the value of the current working +directory before the change. +</p> +<p>The return status is zero if the directory is successfully changed, +non-zero otherwise. +</p> +</dd> +<dt id='index-continue'><span><code>continue</code><a href='#index-continue' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">continue [<var>n</var>] +</pre></div> + +<p>Resume the next iteration of an enclosing <code>for</code>, <code>while</code>, +<code>until</code>, or <code>select</code> loop. +If <var>n</var> is supplied, the execution of the <var>n</var>th enclosing loop +is resumed. +<var>n</var> must be greater than or equal to 1. +The return status is zero unless <var>n</var> is not greater than or equal to 1. +</p> +</dd> +<dt id='index-eval'><span><code>eval</code><a href='#index-eval' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">eval [<var>arguments</var>] +</pre></div> + +<p>The arguments are concatenated together into a single command, which is +then read and executed, and its exit status returned as the exit status +of <code>eval</code>. +If there are no arguments or only empty arguments, the return status is +zero. +</p> +</dd> +<dt id='index-exec'><span><code>exec</code><a href='#index-exec' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">exec [-cl] [-a <var>name</var>] [<var>command</var> [<var>arguments</var>]] +</pre></div> + +<p>If <var>command</var> +is supplied, it replaces the shell without creating a new process. +If the <samp>-l</samp> option is supplied, the shell places a dash at the +beginning of the zeroth argument passed to <var>command</var>. +This is what the <code>login</code> program does. +The <samp>-c</samp> option causes <var>command</var> to be executed with an empty +environment. +If <samp>-a</samp> is supplied, the shell passes <var>name</var> as the zeroth +argument to <var>command</var>. +If <var>command</var> +cannot be executed for some reason, a non-interactive shell exits, +unless the <code>execfail</code> shell option +is enabled. In that case, it returns failure. +An interactive shell returns failure if the file cannot be executed. +A subshell exits unconditionally if <code>exec</code> fails. +If no <var>command</var> is specified, redirections may be used to affect +the current shell environment. If there are no redirection errors, the +return status is zero; otherwise the return status is non-zero. +</p> +</dd> +<dt id='index-exit'><span><code>exit</code><a href='#index-exit' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">exit [<var>n</var>] +</pre></div> + +<p>Exit the shell, returning a status of <var>n</var> to the shell’s parent. +If <var>n</var> is omitted, the exit status is that of the last command executed. +Any trap on <code>EXIT</code> is executed before the shell terminates. +</p> +</dd> +<dt id='index-export'><span><code>export</code><a href='#index-export' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">export [-fn] [-p] [<var>name</var>[=<var>value</var>]] +</pre></div> + +<p>Mark each <var>name</var> to be passed to child processes +in the environment. If the <samp>-f</samp> option is supplied, the <var>name</var>s +refer to shell functions; otherwise the names refer to shell variables. +The <samp>-n</samp> option means to no longer mark each <var>name</var> for export. +If no <var>name</var>s are supplied, or if the <samp>-p</samp> option is given, a +list of names of all exported variables is displayed. +The <samp>-p</samp> option displays output in a form that may be reused as input. +If a variable name is followed by =<var>value</var>, the value of +the variable is set to <var>value</var>. +</p> +<p>The return status is zero unless an invalid option is supplied, one of +the names is not a valid shell variable name, or <samp>-f</samp> is supplied +with a name that is not a shell function. +</p> +</dd> +<dt id='index-getopts'><span><code>getopts</code><a href='#index-getopts' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">getopts <var>optstring</var> <var>name</var> [<var>arg</var> …] +</pre></div> + +<p><code>getopts</code> is used by shell scripts to parse positional parameters. +<var>optstring</var> contains the option characters to be recognized; if a +character is followed by a colon, the option is expected to have an +argument, which should be separated from it by whitespace. +The colon (‘<samp>:</samp>’) and question mark (‘<samp>?</samp>’) may not be +used as option characters. +Each time it is invoked, <code>getopts</code> +places the next option in the shell variable <var>name</var>, initializing +<var>name</var> if it does not exist, +and the index of the next argument to be processed into the +variable <code>OPTIND</code>. +<code>OPTIND</code> is initialized to 1 each time the shell or a shell script +is invoked. +When an option requires an argument, +<code>getopts</code> places that argument into the variable <code>OPTARG</code>. +The shell does not reset <code>OPTIND</code> automatically; it must be manually +reset between multiple calls to <code>getopts</code> within the same shell +invocation if a new set of parameters is to be used. +</p> +<p>When the end of options is encountered, <code>getopts</code> exits with a +return value greater than zero. +<code>OPTIND</code> is set to the index of the first non-option argument, +and <var>name</var> is set to ‘<samp>?</samp>’. +</p> +<p><code>getopts</code> +normally parses the positional parameters, but if more arguments are +supplied as <var>arg</var> values, <code>getopts</code> parses those instead. +</p> +<p><code>getopts</code> can report errors in two ways. If the first character of +<var>optstring</var> is a colon, <var>silent</var> +error reporting is used. In normal operation, diagnostic messages +are printed when invalid options or missing option arguments are +encountered. +If the variable <code>OPTERR</code> +is set to 0, no error messages will be displayed, even if the first +character of <code>optstring</code> is not a colon. +</p> +<p>If an invalid option is seen, +<code>getopts</code> places ‘<samp>?</samp>’ into <var>name</var> and, if not silent, +prints an error message and unsets <code>OPTARG</code>. +If <code>getopts</code> is silent, the option character found is placed in +<code>OPTARG</code> and no diagnostic message is printed. +</p> +<p>If a required argument is not found, and <code>getopts</code> +is not silent, a question mark (‘<samp>?</samp>’) is placed in <var>name</var>, +<code>OPTARG</code> is unset, and a diagnostic message is printed. +If <code>getopts</code> is silent, then a colon (‘<samp>:</samp>’) is placed in +<var>name</var> and <code>OPTARG</code> is set to the option character found. +</p> +</dd> +<dt id='index-hash'><span><code>hash</code><a href='#index-hash' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">hash [-r] [-p <var>filename</var>] [-dt] [<var>name</var>] +</pre></div> + +<p>Each time <code>hash</code> is invoked, it remembers the full pathnames of the +commands specified as <var>name</var> arguments, +so they need not be searched for on subsequent invocations. +The commands are found by searching through the directories listed in +<code>$PATH</code>. +Any previously-remembered pathname is discarded. +The <samp>-p</samp> option inhibits the path search, and <var>filename</var> is +used as the location of <var>name</var>. +The <samp>-r</samp> option causes the shell to forget all remembered locations. +The <samp>-d</samp> option causes the shell to forget the remembered location +of each <var>name</var>. +If the <samp>-t</samp> option is supplied, the full pathname to which each +<var>name</var> corresponds is printed. If multiple <var>name</var> arguments are +supplied with <samp>-t</samp>, the <var>name</var> is printed before the hashed +full pathname. +The <samp>-l</samp> option causes output to be displayed in a format +that may be reused as input. +If no arguments are given, or if only <samp>-l</samp> is supplied, +information about remembered commands is printed. +The return status is zero unless a <var>name</var> is not found or an invalid +option is supplied. +</p> +</dd> +<dt id='index-pwd'><span><code>pwd</code><a href='#index-pwd' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">pwd [-LP] +</pre></div> + +<p>Print the absolute pathname of the current working directory. +If the <samp>-P</samp> option is supplied, the pathname printed will not +contain symbolic links. +If the <samp>-L</samp> option is supplied, the pathname printed may contain +symbolic links. +The return status is zero unless an error is encountered while +determining the name of the current directory or an invalid option +is supplied. +</p> +</dd> +<dt id='index-readonly'><span><code>readonly</code><a href='#index-readonly' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">readonly [-aAf] [-p] [<var>name</var>[=<var>value</var>]] … +</pre></div> + +<p>Mark each <var>name</var> as readonly. +The values of these names may not be changed by subsequent assignment. +If the <samp>-f</samp> option is supplied, each <var>name</var> refers to a shell +function. +The <samp>-a</samp> option means each <var>name</var> refers to an indexed +array variable; the <samp>-A</samp> option means each <var>name</var> refers +to an associative array variable. +If both options are supplied, <samp>-A</samp> takes precedence. +If no <var>name</var> arguments are given, or if the <samp>-p</samp> +option is supplied, a list of all readonly names is printed. +The other options may be used to restrict the output to a subset of +the set of readonly names. +The <samp>-p</samp> option causes output to be displayed in a format that +may be reused as input. +If a variable name is followed by =<var>value</var>, the value of +the variable is set to <var>value</var>. +The return status is zero unless an invalid option is supplied, one of +the <var>name</var> arguments is not a valid shell variable or function name, +or the <samp>-f</samp> option is supplied with a name that is not a shell function. +</p> +</dd> +<dt id='index-return'><span><code>return</code><a href='#index-return' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">return [<var>n</var>] +</pre></div> + +<p>Cause a shell function to stop executing and return the value <var>n</var> +to its caller. +If <var>n</var> is not supplied, the return value is the exit status of the +last command executed in the function. +If <code>return</code> is executed by a trap handler, the last command used to +determine the status is the last command executed before the trap handler. +If <code>return</code> is executed during a <code>DEBUG</code> trap, the last command +used to determine the status is the last command executed by the trap +handler before <code>return</code> was invoked. +<code>return</code> may also be used to terminate execution of a script +being executed with the <code>.</code> (<code>source</code>) builtin, +returning either <var>n</var> or +the exit status of the last command executed within the script as the exit +status of the script. +If <var>n</var> is supplied, the return value is its least significant +8 bits. +Any command associated with the <code>RETURN</code> trap is executed +before execution resumes after the function or script. +The return status is non-zero if <code>return</code> is supplied a non-numeric +argument or is used outside a function +and not during the execution of a script by <code>.</code> or <code>source</code>. +</p> +</dd> +<dt id='index-shift'><span><code>shift</code><a href='#index-shift' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">shift [<var>n</var>] +</pre></div> + +<p>Shift the positional parameters to the left by <var>n</var>. +The positional parameters from <var>n</var>+1 … <code>$#</code> are +renamed to <code>$1</code> … <code>$#</code>-<var>n</var>. +Parameters represented by the numbers <code>$#</code> down to <code>$#</code>-<var>n</var>+1 +are unset. +<var>n</var> must be a non-negative number less than or equal to <code>$#</code>. +If <var>n</var> is zero or greater than <code>$#</code>, the positional parameters +are not changed. +If <var>n</var> is not supplied, it is assumed to be 1. +The return status is zero unless <var>n</var> is greater than <code>$#</code> or +less than zero, non-zero otherwise. +</p> +</dd> +<dt id='index-test'><span><code>test</code><a href='#index-test' class='copiable-anchor'> ¶</a></span></dt> +<dt><span><code>[</code></span></dt> +<dd><span id="index-_005b"></span> +<div class="example"> +<pre class="example">test <var>expr</var> +</pre></div> + +<p>Evaluate a conditional expression <var>expr</var> and return a status of 0 +(true) or 1 (false). +Each operator and operand must be a separate argument. +Expressions are composed of the primaries described below in +<a href="#Bash-Conditional-Expressions">Bash Conditional Expressions</a>. +<code>test</code> does not accept any options, nor does it accept and ignore +an argument of <samp>--</samp> as signifying the end of options. +</p> +<p>When the <code>[</code> form is used, the last argument to the command must +be a <code>]</code>. +</p> +<p>Expressions may be combined using the following operators, listed in +decreasing order of precedence. +The evaluation depends on the number of arguments; see below. +Operator precedence is used when there are five or more arguments. +</p> +<dl compact="compact"> +<dt><span><code>! <var>expr</var></code></span></dt> +<dd><p>True if <var>expr</var> is false. +</p> +</dd> +<dt><span><code>( <var>expr</var> )</code></span></dt> +<dd><p>Returns the value of <var>expr</var>. +This may be used to override the normal precedence of operators. +</p> +</dd> +<dt><span><code><var>expr1</var> -a <var>expr2</var></code></span></dt> +<dd><p>True if both <var>expr1</var> and <var>expr2</var> are true. +</p> +</dd> +<dt><span><code><var>expr1</var> -o <var>expr2</var></code></span></dt> +<dd><p>True if either <var>expr1</var> or <var>expr2</var> is true. +</p></dd> +</dl> + +<p>The <code>test</code> and <code>[</code> builtins evaluate conditional +expressions using a set of rules based on the number of arguments. +</p> +<dl compact="compact"> +<dt><span>0 arguments</span></dt> +<dd><p>The expression is false. +</p> +</dd> +<dt><span>1 argument</span></dt> +<dd><p>The expression is true if, and only if, the argument is not null. +</p> +</dd> +<dt><span>2 arguments</span></dt> +<dd><p>If the first argument is ‘<samp>!</samp>’, the expression is true if and +only if the second argument is null. +If the first argument is one of the unary conditional operators +(see <a href="#Bash-Conditional-Expressions">Bash Conditional Expressions</a>), the expression +is true if the unary test is true. +If the first argument is not a valid unary operator, the expression is +false. +</p> +</dd> +<dt><span>3 arguments</span></dt> +<dd><p>The following conditions are applied in the order listed. +</p> +<ol> +<li> If the second argument is one of the binary conditional +operators (see <a href="#Bash-Conditional-Expressions">Bash Conditional Expressions</a>), the +result of the expression is the result of the binary test using the +first and third arguments as operands. +The ‘<samp>-a</samp>’ and ‘<samp>-o</samp>’ operators are considered binary operators +when there are three arguments. +</li><li> If the first argument is ‘<samp>!</samp>’, the value is the negation of +the two-argument test using the second and third arguments. +</li><li> If the first argument is exactly ‘<samp>(</samp>’ and the third argument is +exactly ‘<samp>)</samp>’, the result is the one-argument test of the second +argument. +</li><li> Otherwise, the expression is false. +</li></ol> + +</dd> +<dt><span>4 arguments</span></dt> +<dd><p>The following conditions are applied in the order listed. +</p> +<ol> +<li> If the first argument is ‘<samp>!</samp>’, the result is the negation of +the three-argument expression composed of the remaining arguments. +</li><li> If the first argument is exactly ‘<samp>(</samp>’ and the fourth argument is +exactly ‘<samp>)</samp>’, the result is the two-argument test of the second +and third arguments. +</li><li> Otherwise, the expression is parsed and evaluated according to +precedence using the rules listed above. +</li></ol> + +</dd> +<dt><span>5 or more arguments</span></dt> +<dd><p>The expression is parsed and evaluated according to precedence +using the rules listed above. +</p></dd> +</dl> + +<p>When used with <code>test</code> or ‘<samp>[</samp>’, the ‘<samp><</samp>’ and ‘<samp>></samp>’ +operators sort lexicographically using ASCII ordering. +</p> +</dd> +<dt id='index-times'><span><code>times</code><a href='#index-times' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">times +</pre></div> + +<p>Print out the user and system times used by the shell and its children. +The return status is zero. +</p> +</dd> +<dt id='index-trap'><span><code>trap</code><a href='#index-trap' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">trap [-lp] [<var>arg</var>] [<var>sigspec</var> …] +</pre></div> + +<p>The commands in <var>arg</var> are to be read and executed when the +shell receives signal <var>sigspec</var>. If <var>arg</var> is absent (and +there is a single <var>sigspec</var>) or +equal to ‘<samp>-</samp>’, each specified signal’s disposition is reset +to the value it had when the shell was started. +If <var>arg</var> is the null string, then the signal specified by +each <var>sigspec</var> is ignored by the shell and commands it invokes. +If <var>arg</var> is not present and <samp>-p</samp> has been supplied, +the shell displays the trap commands associated with each <var>sigspec</var>. +If no arguments are supplied, or +only <samp>-p</samp> is given, <code>trap</code> prints the list of commands +associated with each signal number in a form that may be reused as +shell input. +The <samp>-l</samp> option causes the shell to print a list of signal names +and their corresponding numbers. +Each <var>sigspec</var> is either a signal name or a signal number. +Signal names are case insensitive and the <code>SIG</code> prefix is optional. +</p> +<p>If a <var>sigspec</var> +is <code>0</code> or <code>EXIT</code>, <var>arg</var> is executed when the shell exits. +If a <var>sigspec</var> is <code>DEBUG</code>, the command <var>arg</var> is executed +before every simple command, <code>for</code> command, <code>case</code> command, +<code>select</code> command, every arithmetic <code>for</code> command, and before +the first command executes in a shell function. +Refer to the description of the <code>extdebug</code> option to the +<code>shopt</code> builtin (see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>) for details of its +effect on the <code>DEBUG</code> trap. +If a <var>sigspec</var> is <code>RETURN</code>, the command <var>arg</var> is executed +each time a shell function or a script executed with the <code>.</code> or +<code>source</code> builtins finishes executing. +</p> +<p>If a <var>sigspec</var> is <code>ERR</code>, the command <var>arg</var> +is executed whenever +a pipeline (which may consist of a single simple +command), a list, or a compound command returns a +non-zero exit status, +subject to the following conditions. +The <code>ERR</code> trap is not executed if the failed command is part of the +command list immediately following an <code>until</code> or <code>while</code> keyword, +part of the test following the <code>if</code> or <code>elif</code> reserved words, +part of a command executed in a <code>&&</code> or <code>||</code> list +except the command following the final <code>&&</code> or <code>||</code>, +any command in a pipeline but the last, +or if the command’s return +status is being inverted using <code>!</code>. +These are the same conditions obeyed by the <code>errexit</code> (<samp>-e</samp>) +option. +</p> +<p>Signals ignored upon entry to the shell cannot be trapped or reset. +Trapped signals that are not being ignored are reset to their original +values in a subshell or subshell environment when one is created. +</p> +<p>The return status is zero unless a <var>sigspec</var> does not specify a +valid signal. +</p> +</dd> +<dt id='index-umask'><span><code>umask</code><a href='#index-umask' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">umask [-p] [-S] [<var>mode</var>] +</pre></div> + +<p>Set the shell process’s file creation mask to <var>mode</var>. If +<var>mode</var> begins with a digit, it is interpreted as an octal number; +if not, it is interpreted as a symbolic mode mask similar +to that accepted by the <code>chmod</code> command. If <var>mode</var> is +omitted, the current value of the mask is printed. If the <samp>-S</samp> +option is supplied without a <var>mode</var> argument, the mask is printed +in a symbolic format. +If the <samp>-p</samp> option is supplied, and <var>mode</var> +is omitted, the output is in a form that may be reused as input. +The return status is zero if the mode is successfully changed or if +no <var>mode</var> argument is supplied, and non-zero otherwise. +</p> +<p>Note that when the mode is interpreted as an octal number, each number +of the umask is subtracted from <code>7</code>. Thus, a umask of <code>022</code> +results in permissions of <code>755</code>. +</p> +</dd> +<dt id='index-unset'><span><code>unset</code><a href='#index-unset' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">unset [-fnv] [<var>name</var>] +</pre></div> + +<p>Remove each variable or function <var>name</var>. +If the <samp>-v</samp> option is given, each +<var>name</var> refers to a shell variable and that variable is removed. +If the <samp>-f</samp> option is given, the <var>name</var>s refer to shell +functions, and the function definition is removed. +If the <samp>-n</samp> option is supplied, and <var>name</var> is a variable with +the <code>nameref</code> attribute, <var>name</var> will be unset rather than the +variable it references. +<samp>-n</samp> has no effect if the <samp>-f</samp> option is supplied. +If no options are supplied, each <var>name</var> refers to a variable; if +there is no variable by that name, a function with that name, if any, is +unset. +Readonly variables and functions may not be unset. +Some shell variables lose their special behavior if they are unset; such +behavior is noted in the description of the individual variables. +The return status is zero unless a <var>name</var> is readonly or may not be unset. +</p></dd> +</dl> + +<hr> +</div> +<div class="section" id="Bash-Builtins"> +<div class="header"> +<p> +Next: <a href="#Modifying-Shell-Behavior" accesskey="n" rel="next">Modifying Shell Behavior</a>, Previous: <a href="#Bourne-Shell-Builtins" accesskey="p" rel="prev">Bourne Shell Builtins</a>, Up: <a href="#Shell-Builtin-Commands" accesskey="u" rel="up">Shell Builtin Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Bash-Builtin-Commands"></span><h3 class="section">4.2 Bash Builtin Commands</h3> + +<p>This section describes builtin commands which are unique to +or have been extended in Bash. +Some of these commands are specified in the <small>POSIX</small> standard. +</p> +<dl compact="compact"> +<dt id='index-alias'><span><code>alias</code><a href='#index-alias' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">alias [-p] [<var>name</var>[=<var>value</var>] …] +</pre></div> + +<p>Without arguments or with the <samp>-p</samp> option, <code>alias</code> prints +the list of aliases on the standard output in a form that allows +them to be reused as input. +If arguments are supplied, an alias is defined for each <var>name</var> +whose <var>value</var> is given. If no <var>value</var> is given, the name +and value of the alias is printed. +Aliases are described in <a href="#Aliases">Aliases</a>. +</p> +</dd> +<dt id='index-bind'><span><code>bind</code><a href='#index-bind' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">bind [-m <var>keymap</var>] [-lpsvPSVX] +bind [-m <var>keymap</var>] [-q <var>function</var>] [-u <var>function</var>] [-r <var>keyseq</var>] +bind [-m <var>keymap</var>] -f <var>filename</var> +bind [-m <var>keymap</var>] -x <var>keyseq:shell-command</var> +bind [-m <var>keymap</var>] <var>keyseq:function-name</var> +bind [-m <var>keymap</var>] <var>keyseq:readline-command</var> +bind <var>readline-command-line</var> +</pre></div> + +<p>Display current Readline (see <a href="#Command-Line-Editing">Command Line Editing</a>) +key and function bindings, +bind a key sequence to a Readline function or macro, +or set a Readline variable. +Each non-option argument is a command as it would appear in a +Readline initialization file (see <a href="#Readline-Init-File">Readline Init File</a>), +but each binding or command must be passed as a separate argument; e.g., +‘<samp>"\C-x\C-r":re-read-init-file</samp>’. +</p> +<p>Options, if supplied, have the following meanings: +</p> +<dl compact="compact"> +<dt><span><code>-m <var>keymap</var></code></span></dt> +<dd><p>Use <var>keymap</var> as the keymap to be affected by +the subsequent bindings. Acceptable <var>keymap</var> +names are +<code>emacs</code>, +<code>emacs-standard</code>, +<code>emacs-meta</code>, +<code>emacs-ctlx</code>, +<code>vi</code>, +<code>vi-move</code>, +<code>vi-command</code>, and +<code>vi-insert</code>. +<code>vi</code> is equivalent to <code>vi-command</code> (<code>vi-move</code> is also a +synonym); <code>emacs</code> is equivalent to <code>emacs-standard</code>. +</p> +</dd> +<dt><span><code>-l</code></span></dt> +<dd><p>List the names of all Readline functions. +</p> +</dd> +<dt><span><code>-p</code></span></dt> +<dd><p>Display Readline function names and bindings in such a way that they +can be used as input or in a Readline initialization file. +</p> +</dd> +<dt><span><code>-P</code></span></dt> +<dd><p>List current Readline function names and bindings. +</p> +</dd> +<dt><span><code>-v</code></span></dt> +<dd><p>Display Readline variable names and values in such a way that they +can be used as input or in a Readline initialization file. +</p> +</dd> +<dt><span><code>-V</code></span></dt> +<dd><p>List current Readline variable names and values. +</p> +</dd> +<dt><span><code>-s</code></span></dt> +<dd><p>Display Readline key sequences bound to macros and the strings they output +in such a way that they can be used as input or in a Readline +initialization file. +</p> +</dd> +<dt><span><code>-S</code></span></dt> +<dd><p>Display Readline key sequences bound to macros and the strings they output. +</p> +</dd> +<dt><span><code>-f <var>filename</var></code></span></dt> +<dd><p>Read key bindings from <var>filename</var>. +</p> +</dd> +<dt><span><code>-q <var>function</var></code></span></dt> +<dd><p>Query about which keys invoke the named <var>function</var>. +</p> +</dd> +<dt><span><code>-u <var>function</var></code></span></dt> +<dd><p>Unbind all keys bound to the named <var>function</var>. +</p> +</dd> +<dt><span><code>-r <var>keyseq</var></code></span></dt> +<dd><p>Remove any current binding for <var>keyseq</var>. +</p> +</dd> +<dt><span><code>-x <var>keyseq:shell-command</var></code></span></dt> +<dd><p>Cause <var>shell-command</var> to be executed whenever <var>keyseq</var> is +entered. +When <var>shell-command</var> is executed, the shell sets the +<code>READLINE_LINE</code> variable to the contents of the Readline line +buffer and the <code>READLINE_POINT</code> and <code>READLINE_MARK</code> variables +to the current location of the insertion point and the saved insertion +point (the <var>mark</var>), respectively. +The shell assigns any numeric argument the user supplied to the +<code>READLINE_ARGUMENT</code> variable. +If there was no argument, that variable is not set. +If the executed command changes the value of any of <code>READLINE_LINE</code>, +<code>READLINE_POINT</code>, or <code>READLINE_MARK</code>, those new values will be +reflected in the editing state. +</p> +</dd> +<dt><span><code>-X</code></span></dt> +<dd><p>List all key sequences bound to shell commands and the associated commands +in a format that can be reused as input. +</p></dd> +</dl> + +<p>The return status is zero unless an invalid option is supplied or an +error occurs. +</p> +</dd> +<dt id='index-builtin'><span><code>builtin</code><a href='#index-builtin' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">builtin [<var>shell-builtin</var> [<var>args</var>]] +</pre></div> + +<p>Run a shell builtin, passing it <var>args</var>, and return its exit status. +This is useful when defining a shell function with the same +name as a shell builtin, retaining the functionality of the builtin within +the function. +The return status is non-zero if <var>shell-builtin</var> is not a shell +builtin command. +</p> +</dd> +<dt id='index-caller'><span><code>caller</code><a href='#index-caller' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">caller [<var>expr</var>] +</pre></div> + +<p>Returns the context of any active subroutine call (a shell function or +a script executed with the <code>.</code> or <code>source</code> builtins). +</p> +<p>Without <var>expr</var>, <code>caller</code> displays the line number and source +filename of the current subroutine call. +If a non-negative integer is supplied as <var>expr</var>, <code>caller</code> +displays the line number, subroutine name, and source file corresponding +to that position in the current execution call stack. This extra +information may be used, for example, to print a stack trace. The +current frame is frame 0. +</p> +<p>The return value is 0 unless the shell is not executing a subroutine +call or <var>expr</var> does not correspond to a valid position in the +call stack. +</p> +</dd> +<dt id='index-command'><span><code>command</code><a href='#index-command' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">command [-pVv] <var>command</var> [<var>arguments</var> …] +</pre></div> + +<p>Runs <var>command</var> with <var>arguments</var> ignoring any shell function +named <var>command</var>. +Only shell builtin commands or commands found by searching the +<code>PATH</code> are executed. +If there is a shell function named <code>ls</code>, running ‘<samp>command ls</samp>’ +within the function will execute the external command <code>ls</code> +instead of calling the function recursively. +The <samp>-p</samp> option means to use a default value for <code>PATH</code> +that is guaranteed to find all of the standard utilities. +The return status in this case is 127 if <var>command</var> cannot be +found or an error occurred, and the exit status of <var>command</var> +otherwise. +</p> +<p>If either the <samp>-V</samp> or <samp>-v</samp> option is supplied, a +description of <var>command</var> is printed. The <samp>-v</samp> option +causes a single word indicating the command or file name used to +invoke <var>command</var> to be displayed; the <samp>-V</samp> option produces +a more verbose description. In this case, the return status is +zero if <var>command</var> is found, and non-zero if not. +</p> +</dd> +<dt id='index-declare'><span><code>declare</code><a href='#index-declare' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">declare [-aAfFgiIlnrtux] [-p] [<var>name</var>[=<var>value</var>] …] +</pre></div> + +<p>Declare variables and give them attributes. If no <var>name</var>s +are given, then display the values of variables instead. +</p> +<p>The <samp>-p</samp> option will display the attributes and values of each +<var>name</var>. +When <samp>-p</samp> is used with <var>name</var> arguments, additional options, +other than <samp>-f</samp> and <samp>-F</samp>, are ignored. +</p> +<p>When <samp>-p</samp> is supplied without <var>name</var> arguments, <code>declare</code> +will display the attributes and values of all variables having the +attributes specified by the additional options. +If no other options are supplied with <samp>-p</samp>, <code>declare</code> will +display the attributes and values of all shell variables. The <samp>-f</samp> +option will restrict the display to shell functions. +</p> +<p>The <samp>-F</samp> option inhibits the display of function definitions; +only the function name and attributes are printed. +If the <code>extdebug</code> shell option is enabled using <code>shopt</code> +(see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>), the source file name and line number where +each <var>name</var> is defined are displayed as well. +<samp>-F</samp> implies <samp>-f</samp>. +</p> +<p>The <samp>-g</samp> option forces variables to be created or modified at +the global scope, even when <code>declare</code> is executed in a shell function. +It is ignored in all other cases. +</p> +<p>The <samp>-I</samp> option causes local variables to inherit the attributes +(except the <code>nameref</code> attribute) +and value of any existing variable with the same +<var>name</var> at a surrounding scope. +If there is no existing variable, the local variable is initially unset. +</p> +<p>The following options can be used to restrict output to variables with +the specified attributes or to give variables attributes: +</p> +<dl compact="compact"> +<dt><span><code>-a</code></span></dt> +<dd><p>Each <var>name</var> is an indexed array variable (see <a href="#Arrays">Arrays</a>). +</p> +</dd> +<dt><span><code>-A</code></span></dt> +<dd><p>Each <var>name</var> is an associative array variable (see <a href="#Arrays">Arrays</a>). +</p> +</dd> +<dt><span><code>-f</code></span></dt> +<dd><p>Use function names only. +</p> +</dd> +<dt><span><code>-i</code></span></dt> +<dd><p>The variable is to be treated as +an integer; arithmetic evaluation (see <a href="#Shell-Arithmetic">Shell Arithmetic</a>) is +performed when the variable is assigned a value. +</p> +</dd> +<dt><span><code>-l</code></span></dt> +<dd><p>When the variable is assigned a value, all upper-case characters are +converted to lower-case. +The upper-case attribute is disabled. +</p> +</dd> +<dt><span><code>-n</code></span></dt> +<dd><p>Give each <var>name</var> the <code>nameref</code> attribute, making +it a name reference to another variable. +That other variable is defined by the value of <var>name</var>. +All references, assignments, and attribute modifications +to <var>name</var>, except for those using or changing the +<samp>-n</samp> attribute itself, are performed on the variable referenced by +<var>name</var>’s value. +The nameref attribute cannot be applied to array variables. +</p> +</dd> +<dt><span><code>-r</code></span></dt> +<dd><p>Make <var>name</var>s readonly. These names cannot then be assigned values +by subsequent assignment statements or unset. +</p> +</dd> +<dt><span><code>-t</code></span></dt> +<dd><p>Give each <var>name</var> the <code>trace</code> attribute. +Traced functions inherit the <code>DEBUG</code> and <code>RETURN</code> traps from +the calling shell. +The trace attribute has no special meaning for variables. +</p> +</dd> +<dt><span><code>-u</code></span></dt> +<dd><p>When the variable is assigned a value, all lower-case characters are +converted to upper-case. +The lower-case attribute is disabled. +</p> +</dd> +<dt><span><code>-x</code></span></dt> +<dd><p>Mark each <var>name</var> for export to subsequent commands via +the environment. +</p></dd> +</dl> + +<p>Using ‘<samp>+</samp>’ instead of ‘<samp>-</samp>’ turns off the attribute instead, +with the exceptions that ‘<samp>+a</samp>’ and ‘<samp>+A</samp>’ +may not be used to destroy array variables and ‘<samp>+r</samp>’ will not +remove the readonly attribute. +When used in a function, <code>declare</code> makes each <var>name</var> local, +as with the <code>local</code> command, unless the <samp>-g</samp> option is used. +If a variable name is followed by =<var>value</var>, the value of the variable +is set to <var>value</var>. +</p> +<p>When using <samp>-a</samp> or <samp>-A</samp> and the compound assignment syntax to +create array variables, additional attributes do not take effect until +subsequent assignments. +</p> +<p>The return status is zero unless an invalid option is encountered, +an attempt is made to define a function using ‘<samp>-f foo=bar</samp>’, +an attempt is made to assign a value to a readonly variable, +an attempt is made to assign a value to an array variable without +using the compound assignment syntax (see <a href="#Arrays">Arrays</a>), +one of the <var>name</var>s is not a valid shell variable name, +an attempt is made to turn off readonly status for a readonly variable, +an attempt is made to turn off array status for an array variable, +or an attempt is made to display a non-existent function with <samp>-f</samp>. +</p> +</dd> +<dt id='index-echo'><span><code>echo</code><a href='#index-echo' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">echo [-neE] [<var>arg</var> …] +</pre></div> + +<p>Output the <var>arg</var>s, separated by spaces, terminated with a +newline. +The return status is 0 unless a write error occurs. +If <samp>-n</samp> is specified, the trailing newline is suppressed. +If the <samp>-e</samp> option is given, interpretation of the following +backslash-escaped characters is enabled. +The <samp>-E</samp> option disables the interpretation of these escape characters, +even on systems where they are interpreted by default. +The <code>xpg_echo</code> shell option may be used to +dynamically determine whether or not <code>echo</code> expands these +escape characters by default. +<code>echo</code> does not interpret <samp>--</samp> to mean the end of options. +</p> +<p><code>echo</code> interprets the following escape sequences: +</p><dl compact="compact"> +<dt><span><code>\a</code></span></dt> +<dd><p>alert (bell) +</p></dd> +<dt><span><code>\b</code></span></dt> +<dd><p>backspace +</p></dd> +<dt><span><code>\c</code></span></dt> +<dd><p>suppress further output +</p></dd> +<dt><span><code>\e</code></span></dt> +<dt><span><code>\E</code></span></dt> +<dd><p>escape +</p></dd> +<dt><span><code>\f</code></span></dt> +<dd><p>form feed +</p></dd> +<dt><span><code>\n</code></span></dt> +<dd><p>new line +</p></dd> +<dt><span><code>\r</code></span></dt> +<dd><p>carriage return +</p></dd> +<dt><span><code>\t</code></span></dt> +<dd><p>horizontal tab +</p></dd> +<dt><span><code>\v</code></span></dt> +<dd><p>vertical tab +</p></dd> +<dt><span><code>\\</code></span></dt> +<dd><p>backslash +</p></dd> +<dt><span><code>\0<var>nnn</var></code></span></dt> +<dd><p>the eight-bit character whose value is the octal value <var>nnn</var> +(zero to three octal digits) +</p></dd> +<dt><span><code>\x<var>HH</var></code></span></dt> +<dd><p>the eight-bit character whose value is the hexadecimal value <var>HH</var> +(one or two hex digits) +</p></dd> +<dt><span><code>\u<var>HHHH</var></code></span></dt> +<dd><p>the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +<var>HHHH</var> (one to four hex digits) +</p></dd> +<dt><span><code>\U<var>HHHHHHHH</var></code></span></dt> +<dd><p>the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +<var>HHHHHHHH</var> (one to eight hex digits) +</p></dd> +</dl> + +</dd> +<dt id='index-enable'><span><code>enable</code><a href='#index-enable' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">enable [-a] [-dnps] [-f <var>filename</var>] [<var>name</var> …] +</pre></div> + +<p>Enable and disable builtin shell commands. +Disabling a builtin allows a disk command which has the same name +as a shell builtin to be executed without specifying a full pathname, +even though the shell normally searches for builtins before disk commands. +If <samp>-n</samp> is used, the <var>name</var>s become disabled. Otherwise +<var>name</var>s are enabled. For example, to use the <code>test</code> binary +found via <code>$PATH</code> instead of the shell builtin version, type +‘<samp>enable -n test</samp>’. +</p> +<p>If the <samp>-p</samp> option is supplied, or no <var>name</var> arguments appear, +a list of shell builtins is printed. With no other arguments, the list +consists of all enabled shell builtins. +The <samp>-a</samp> option means to list +each builtin with an indication of whether or not it is enabled. +</p> +<p>The <samp>-f</samp> option means to load the new builtin command <var>name</var> +from shared object <var>filename</var>, on systems that support dynamic loading. +Bash will use the value of the <code>BASH_LOADABLES_PATH</code> variable as a +colon-separated list of directories in which to search for <var>filename</var>. +The default is system-dependent. +The <samp>-d</samp> option will delete a builtin loaded with <samp>-f</samp>. +</p> +<p>If there are no options, a list of the shell builtins is displayed. +The <samp>-s</samp> option restricts <code>enable</code> to the <small>POSIX</small> special +builtins. If <samp>-s</samp> is used with <samp>-f</samp>, the new builtin becomes +a special builtin (see <a href="#Special-Builtins">Special Builtins</a>). +</p> +<p>If no options are supplied and a <var>name</var> is not a shell builtin, +<code>enable</code> will attempt to load <var>name</var> from a shared object named +<var>name</var>, as if the command were +‘<samp>enable -f <var>name</var> <var>name</var></samp>’. +</p> +<p>The return status is zero unless a <var>name</var> is not a shell builtin +or there is an error loading a new builtin from a shared object. +</p> +</dd> +<dt id='index-help'><span><code>help</code><a href='#index-help' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">help [-dms] [<var>pattern</var>] +</pre></div> + +<p>Display helpful information about builtin commands. +If <var>pattern</var> is specified, <code>help</code> gives detailed help +on all commands matching <var>pattern</var>, otherwise a list of +the builtins is printed. +</p> +<p>Options, if supplied, have the following meanings: +</p> +<dl compact="compact"> +<dt><span><code>-d</code></span></dt> +<dd><p>Display a short description of each <var>pattern</var> +</p></dd> +<dt><span><code>-m</code></span></dt> +<dd><p>Display the description of each <var>pattern</var> in a manpage-like format +</p></dd> +<dt><span><code>-s</code></span></dt> +<dd><p>Display only a short usage synopsis for each <var>pattern</var> +</p></dd> +</dl> + +<p>The return status is zero unless no command matches <var>pattern</var>. +</p> +</dd> +<dt id='index-let'><span><code>let</code><a href='#index-let' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">let <var>expression</var> [<var>expression</var> …] +</pre></div> + +<p>The <code>let</code> builtin allows arithmetic to be performed on shell +variables. Each <var>expression</var> is evaluated according to the +rules given below in <a href="#Shell-Arithmetic">Shell Arithmetic</a>. If the +last <var>expression</var> evaluates to 0, <code>let</code> returns 1; +otherwise 0 is returned. +</p> +</dd> +<dt id='index-local'><span><code>local</code><a href='#index-local' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">local [<var>option</var>] <var>name</var>[=<var>value</var>] … +</pre></div> + +<p>For each argument, a local variable named <var>name</var> is created, +and assigned <var>value</var>. +The <var>option</var> can be any of the options accepted by <code>declare</code>. +<code>local</code> can only be used within a function; it makes the variable +<var>name</var> have a visible scope restricted to that function and its +children. +If <var>name</var> is ‘<samp>-</samp>’, the set of shell options is made local to the +function in which <code>local</code> is invoked: shell options changed using +the <code>set</code> builtin inside the function are restored to their original +values when the function returns. +The restore is effected as if a series of <code>set</code> commands were executed +to restore the values that were in place before the function. +The return status is zero unless <code>local</code> is used outside +a function, an invalid <var>name</var> is supplied, or <var>name</var> is a +readonly variable. +</p> +</dd> +<dt id='index-logout'><span><code>logout</code><a href='#index-logout' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">logout [<var>n</var>] +</pre></div> + +<p>Exit a login shell, returning a status of <var>n</var> to the shell’s +parent. +</p> +</dd> +<dt id='index-mapfile'><span><code>mapfile</code><a href='#index-mapfile' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">mapfile [-d <var>delim</var>] [-n <var>count</var>] [-O <var>origin</var>] [-s <var>count</var>] + [-t] [-u <var>fd</var>] [-C <var>callback</var>] [-c <var>quantum</var>] [<var>array</var>] +</pre></div> + +<p>Read lines from the standard input into the indexed array variable <var>array</var>, +or from file descriptor <var>fd</var> +if the <samp>-u</samp> option is supplied. +The variable <code>MAPFILE</code> is the default <var>array</var>. +Options, if supplied, have the following meanings: +</p> +<dl compact="compact"> +<dt><span><code>-d</code></span></dt> +<dd><p>The first character of <var>delim</var> is used to terminate each input line, +rather than newline. +If <var>delim</var> is the empty string, <code>mapfile</code> will terminate a line +when it reads a NUL character. +</p></dd> +<dt><span><code>-n</code></span></dt> +<dd><p>Copy at most <var>count</var> lines. If <var>count</var> is 0, all lines are copied. +</p></dd> +<dt><span><code>-O</code></span></dt> +<dd><p>Begin assigning to <var>array</var> at index <var>origin</var>. +The default index is 0. +</p></dd> +<dt><span><code>-s</code></span></dt> +<dd><p>Discard the first <var>count</var> lines read. +</p></dd> +<dt><span><code>-t</code></span></dt> +<dd><p>Remove a trailing <var>delim</var> (default newline) from each line read. +</p></dd> +<dt><span><code>-u</code></span></dt> +<dd><p>Read lines from file descriptor <var>fd</var> instead of the standard input. +</p></dd> +<dt><span><code>-C</code></span></dt> +<dd><p>Evaluate <var>callback</var> each time <var>quantum</var> lines are read. +The <samp>-c</samp> option specifies <var>quantum</var>. +</p></dd> +<dt><span><code>-c</code></span></dt> +<dd><p>Specify the number of lines read between each call to <var>callback</var>. +</p></dd> +</dl> + +<p>If <samp>-C</samp> is specified without <samp>-c</samp>, +the default quantum is 5000. +When <var>callback</var> is evaluated, it is supplied the index of the next +array element to be assigned and the line to be assigned to that element +as additional arguments. +<var>callback</var> is evaluated after the line is read but before the +array element is assigned. +</p> +<p>If not supplied with an explicit origin, <code>mapfile</code> will clear <var>array</var> +before assigning to it. +</p> +<p><code>mapfile</code> returns successfully unless an invalid option or option +argument is supplied, <var>array</var> is invalid or unassignable, or <var>array</var> +is not an indexed array. +</p> +</dd> +<dt id='index-printf'><span><code>printf</code><a href='#index-printf' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">printf [-v <var>var</var>] <var>format</var> [<var>arguments</var>] +</pre></div> + +<p>Write the formatted <var>arguments</var> to the standard output under the +control of the <var>format</var>. +The <samp>-v</samp> option causes the output to be assigned to the variable +<var>var</var> rather than being printed to the standard output. +</p> +<p>The <var>format</var> is a character string which contains three types of objects: +plain characters, which are simply copied to standard output, character +escape sequences, which are converted and copied to the standard output, and +format specifications, each of which causes printing of the next successive +<var>argument</var>. +In addition to the standard <code>printf(1)</code> formats, <code>printf</code> +interprets the following extensions: +</p> +<dl compact="compact"> +<dt><span><code>%b</code></span></dt> +<dd><p>Causes <code>printf</code> to expand backslash escape sequences in the +corresponding <var>argument</var> in the same way as <code>echo -e</code> +(see <a href="#Bash-Builtins">Bash Builtin Commands</a>). +</p></dd> +<dt><span><code>%q</code></span></dt> +<dd><p>Causes <code>printf</code> to output the +corresponding <var>argument</var> in a format that can be reused as shell input. +</p></dd> +<dt><span><code>%Q</code></span></dt> +<dd><p>like <code>%q</code>, but applies any supplied precision to the <var>argument</var> +before quoting it. +</p></dd> +<dt><span><code>%(<var>datefmt</var>)T</code></span></dt> +<dd><p>Causes <code>printf</code> to output the date-time string resulting from using +<var>datefmt</var> as a format string for <code>strftime</code>(3). +The corresponding <var>argument</var> is an integer representing the number of +seconds since the epoch. +Two special argument values may be used: -1 represents the current +time, and -2 represents the time the shell was invoked. +If no argument is specified, conversion behaves as if -1 had been given. +This is an exception to the usual <code>printf</code> behavior. +</p></dd> +</dl> + +<p>The %b, %q, and %T directives all use the field width and precision +arguments from the format specification and write that many bytes from +(or use that wide a field for) the expanded argument, which usually +contains more characters than the original. +</p> +<p>Arguments to non-string format specifiers are treated as C language constants, +except that a leading plus or minus sign is allowed, and if the leading +character is a single or double quote, the value is the ASCII value of +the following character. +</p> +<p>The <var>format</var> is reused as necessary to consume all of the <var>arguments</var>. +If the <var>format</var> requires more <var>arguments</var> than are supplied, the +extra format specifications behave as if a zero value or null string, as +appropriate, had been supplied. The return value is zero on success, +non-zero on failure. +</p> +</dd> +<dt id='index-read'><span><code>read</code><a href='#index-read' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">read [-ers] [-a <var>aname</var>] [-d <var>delim</var>] [-i <var>text</var>] [-n <var>nchars</var>] + [-N <var>nchars</var>] [-p <var>prompt</var>] [-t <var>timeout</var>] [-u <var>fd</var>] [<var>name</var> …] +</pre></div> + +<p>One line is read from the standard input, or from the file descriptor +<var>fd</var> supplied as an argument to the <samp>-u</samp> option, +split into words as described above in <a href="#Word-Splitting">Word Splitting</a>, +and the first word +is assigned to the first <var>name</var>, the second word to the second <var>name</var>, +and so on. +If there are more words than names, +the remaining words and their intervening delimiters are assigned +to the last <var>name</var>. +If there are fewer words read from the input stream than names, +the remaining names are assigned empty values. +The characters in the value of the <code>IFS</code> variable +are used to split the line into words using the same rules the shell +uses for expansion (described above in <a href="#Word-Splitting">Word Splitting</a>). +The backslash character ‘<samp>\</samp>’ may be used to remove any special +meaning for the next character read and for line continuation. +</p> +<p>Options, if supplied, have the following meanings: +</p> +<dl compact="compact"> +<dt><span><code>-a <var>aname</var></code></span></dt> +<dd><p>The words are assigned to sequential indices of the array variable +<var>aname</var>, starting at 0. +All elements are removed from <var>aname</var> before the assignment. +Other <var>name</var> arguments are ignored. +</p> +</dd> +<dt><span><code>-d <var>delim</var></code></span></dt> +<dd><p>The first character of <var>delim</var> is used to terminate the input line, +rather than newline. +If <var>delim</var> is the empty string, <code>read</code> will terminate a line +when it reads a NUL character. +</p> +</dd> +<dt><span><code>-e</code></span></dt> +<dd><p>Readline (see <a href="#Command-Line-Editing">Command Line Editing</a>) is used to obtain the line. +Readline uses the current (or default, if line editing was not previously +active) editing settings, but uses Readline’s default filename completion. +</p> +</dd> +<dt><span><code>-i <var>text</var></code></span></dt> +<dd><p>If Readline is being used to read the line, <var>text</var> is placed into +the editing buffer before editing begins. +</p> +</dd> +<dt><span><code>-n <var>nchars</var></code></span></dt> +<dd><p><code>read</code> returns after reading <var>nchars</var> characters rather than +waiting for a complete line of input, but honors a delimiter if fewer +than <var>nchars</var> characters are read before the delimiter. +</p> +</dd> +<dt><span><code>-N <var>nchars</var></code></span></dt> +<dd><p><code>read</code> returns after reading exactly <var>nchars</var> characters rather +than waiting for a complete line of input, unless EOF is encountered or +<code>read</code> times out. +Delimiter characters encountered in the input are +not treated specially and do not cause <code>read</code> to return until +<var>nchars</var> characters are read. +The result is not split on the characters in <code>IFS</code>; the intent is +that the variable is assigned exactly the characters read +(with the exception of backslash; see the <samp>-r</samp> option below). +</p> +</dd> +<dt><span><code>-p <var>prompt</var></code></span></dt> +<dd><p>Display <var>prompt</var>, without a trailing newline, before attempting +to read any input. +The prompt is displayed only if input is coming from a terminal. +</p> +</dd> +<dt><span><code>-r</code></span></dt> +<dd><p>If this option is given, backslash does not act as an escape character. +The backslash is considered to be part of the line. +In particular, a backslash-newline pair may not then be used as a line +continuation. +</p> +</dd> +<dt><span><code>-s</code></span></dt> +<dd><p>Silent mode. If input is coming from a terminal, characters are +not echoed. +</p> +</dd> +<dt><span><code>-t <var>timeout</var></code></span></dt> +<dd><p>Cause <code>read</code> to time out and return failure if a complete line of +input (or a specified number of characters) +is not read within <var>timeout</var> seconds. +<var>timeout</var> may be a decimal number with a fractional portion following +the decimal point. +This option is only effective if <code>read</code> is reading input from a +terminal, pipe, or other special file; it has no effect when reading +from regular files. +If <code>read</code> times out, <code>read</code> saves any partial input read into +the specified variable <var>name</var>. +If <var>timeout</var> is 0, <code>read</code> returns immediately, without trying to +read any data. +The exit status is 0 if input is available on the specified file descriptor, +or the read will return EOF, +non-zero otherwise. +The exit status is greater than 128 if the timeout is exceeded. +</p> +</dd> +<dt><span><code>-u <var>fd</var></code></span></dt> +<dd><p>Read input from file descriptor <var>fd</var>. +</p></dd> +</dl> + +<p>If no <var>name</var>s are supplied, the line read, +without the ending delimiter but otherwise unmodified, +is assigned to the +variable <code>REPLY</code>. +The exit status is zero, unless end-of-file is encountered, <code>read</code> +times out (in which case the status is greater than 128), +a variable assignment error (such as assigning to a readonly variable) occurs, +or an invalid file descriptor is supplied as the argument to <samp>-u</samp>. +</p> +</dd> +<dt id='index-readarray'><span><code>readarray</code><a href='#index-readarray' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">readarray [-d <var>delim</var>] [-n <var>count</var>] [-O <var>origin</var>] [-s <var>count</var>] + [-t] [-u <var>fd</var>] [-C <var>callback</var>] [-c <var>quantum</var>] [<var>array</var>] +</pre></div> + +<p>Read lines from the standard input into the indexed array variable <var>array</var>, +or from file descriptor <var>fd</var> +if the <samp>-u</samp> option is supplied. +</p> +<p>A synonym for <code>mapfile</code>. +</p> +</dd> +<dt id='index-source'><span><code>source</code><a href='#index-source' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">source <var>filename</var> +</pre></div> + +<p>A synonym for <code>.</code> (see <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>). +</p> +</dd> +<dt id='index-type'><span><code>type</code><a href='#index-type' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">type [-afptP] [<var>name</var> …] +</pre></div> + +<p>For each <var>name</var>, indicate how it would be interpreted if used as a +command name. +</p> +<p>If the <samp>-t</samp> option is used, <code>type</code> prints a single word +which is one of ‘<samp>alias</samp>’, ‘<samp>function</samp>’, ‘<samp>builtin</samp>’, +‘<samp>file</samp>’ or ‘<samp>keyword</samp>’, +if <var>name</var> is an alias, shell function, shell builtin, +disk file, or shell reserved word, respectively. +If the <var>name</var> is not found, then nothing is printed, and +<code>type</code> returns a failure status. +</p> +<p>If the <samp>-p</samp> option is used, <code>type</code> either returns the name +of the disk file that would be executed, or nothing if <samp>-t</samp> +would not return ‘<samp>file</samp>’. +</p> +<p>The <samp>-P</samp> option forces a path search for each <var>name</var>, even if +<samp>-t</samp> would not return ‘<samp>file</samp>’. +</p> +<p>If a command is hashed, <samp>-p</samp> and <samp>-P</samp> print the hashed value, +which is not necessarily the file that appears first in <code>$PATH</code>. +</p> +<p>If the <samp>-a</samp> option is used, <code>type</code> returns all of the places +that contain an executable named <var>file</var>. +This includes aliases and functions, if and only if the <samp>-p</samp> option +is not also used. +</p> +<p>If the <samp>-f</samp> option is used, <code>type</code> does not attempt to find +shell functions, as with the <code>command</code> builtin. +</p> +<p>The return status is zero if all of the <var>name</var>s are found, non-zero +if any are not found. +</p> +</dd> +<dt id='index-typeset'><span><code>typeset</code><a href='#index-typeset' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">typeset [-afFgrxilnrtux] [-p] [<var>name</var>[=<var>value</var>] …] +</pre></div> + +<p>The <code>typeset</code> command is supplied for compatibility with the Korn +shell. +It is a synonym for the <code>declare</code> builtin command. +</p> +</dd> +<dt id='index-ulimit'><span><code>ulimit</code><a href='#index-ulimit' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">ulimit [-HS] -a +ulimit [-HS] [-bcdefiklmnpqrstuvxPRT] [<var>limit</var>] +</pre></div> + +<p><code>ulimit</code> provides control over the resources available to processes +started by the shell, on systems that allow such control. If an +option is given, it is interpreted as follows: +</p> +<dl compact="compact"> +<dt><span><code>-S</code></span></dt> +<dd><p>Change and report the soft limit associated with a resource. +</p> +</dd> +<dt><span><code>-H</code></span></dt> +<dd><p>Change and report the hard limit associated with a resource. +</p> +</dd> +<dt><span><code>-a</code></span></dt> +<dd><p>All current limits are reported; no limits are set. +</p> +</dd> +<dt><span><code>-b</code></span></dt> +<dd><p>The maximum socket buffer size. +</p> +</dd> +<dt><span><code>-c</code></span></dt> +<dd><p>The maximum size of core files created. +</p> +</dd> +<dt><span><code>-d</code></span></dt> +<dd><p>The maximum size of a process’s data segment. +</p> +</dd> +<dt><span><code>-e</code></span></dt> +<dd><p>The maximum scheduling priority ("nice"). +</p> +</dd> +<dt><span><code>-f</code></span></dt> +<dd><p>The maximum size of files written by the shell and its children. +</p> +</dd> +<dt><span><code>-i</code></span></dt> +<dd><p>The maximum number of pending signals. +</p> +</dd> +<dt><span><code>-k</code></span></dt> +<dd><p>The maximum number of kqueues that may be allocated. +</p> +</dd> +<dt><span><code>-l</code></span></dt> +<dd><p>The maximum size that may be locked into memory. +</p> +</dd> +<dt><span><code>-m</code></span></dt> +<dd><p>The maximum resident set size (many systems do not honor this limit). +</p> +</dd> +<dt><span><code>-n</code></span></dt> +<dd><p>The maximum number of open file descriptors (most systems do not +allow this value to be set). +</p> +</dd> +<dt><span><code>-p</code></span></dt> +<dd><p>The pipe buffer size. +</p> +</dd> +<dt><span><code>-q</code></span></dt> +<dd><p>The maximum number of bytes in <small>POSIX</small> message queues. +</p> +</dd> +<dt><span><code>-r</code></span></dt> +<dd><p>The maximum real-time scheduling priority. +</p> +</dd> +<dt><span><code>-s</code></span></dt> +<dd><p>The maximum stack size. +</p> +</dd> +<dt><span><code>-t</code></span></dt> +<dd><p>The maximum amount of cpu time in seconds. +</p> +</dd> +<dt><span><code>-u</code></span></dt> +<dd><p>The maximum number of processes available to a single user. +</p> +</dd> +<dt><span><code>-v</code></span></dt> +<dd><p>The maximum amount of virtual memory available to the shell, and, on +some systems, to its children. +</p> +</dd> +<dt><span><code>-x</code></span></dt> +<dd><p>The maximum number of file locks. +</p> +</dd> +<dt><span><code>-P</code></span></dt> +<dd><p>The maximum number of pseudoterminals. +</p> +</dd> +<dt><span><code>-R</code></span></dt> +<dd><p>The maximum time a real-time process can run before blocking, in microseconds. +</p> +</dd> +<dt><span><code>-T</code></span></dt> +<dd><p>The maximum number of threads. +</p></dd> +</dl> + +<p>If <var>limit</var> is given, and the <samp>-a</samp> option is not used, +<var>limit</var> is the new value of the specified resource. +The special <var>limit</var> values <code>hard</code>, <code>soft</code>, and +<code>unlimited</code> stand for the current hard limit, the current soft limit, +and no limit, respectively. +A hard limit cannot be increased by a non-root user once it is set; +a soft limit may be increased up to the value of the hard limit. +Otherwise, the current value of the soft limit for the specified resource +is printed, unless the <samp>-H</samp> option is supplied. +When more than one +resource is specified, the limit name and unit, if appropriate, +are printed before the value. +When setting new limits, if neither <samp>-H</samp> nor <samp>-S</samp> is supplied, +both the hard and soft limits are set. +If no option is given, then <samp>-f</samp> is assumed. Values are in 1024-byte +increments, except for +<samp>-t</samp>, which is in seconds; +<samp>-R</samp>, which is in microseconds; +<samp>-p</samp>, which is in units of 512-byte blocks; +<samp>-P</samp>, +<samp>-T</samp>, +<samp>-b</samp>, +<samp>-k</samp>, +<samp>-n</samp> and <samp>-u</samp>, which are unscaled values; +and, when in <small>POSIX</small> Mode (see <a href="#Bash-POSIX-Mode">Bash POSIX Mode</a>), +<samp>-c</samp> and <samp>-f</samp>, which are in 512-byte increments. +</p> +<p>The return status is zero unless an invalid option or argument is supplied, +or an error occurs while setting a new limit. +</p> +</dd> +<dt id='index-unalias'><span><code>unalias</code><a href='#index-unalias' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">unalias [-a] [<var>name</var> … ] +</pre></div> + +<p>Remove each <var>name</var> from the list of aliases. If <samp>-a</samp> is +supplied, all aliases are removed. +Aliases are described in <a href="#Aliases">Aliases</a>. +</p></dd> +</dl> + +<hr> +</div> +<div class="section" id="Modifying-Shell-Behavior"> +<div class="header"> +<p> +Next: <a href="#Special-Builtins" accesskey="n" rel="next">Special Builtins</a>, Previous: <a href="#Bash-Builtins" accesskey="p" rel="prev">Bash Builtin Commands</a>, Up: <a href="#Shell-Builtin-Commands" accesskey="u" rel="up">Shell Builtin Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Modifying-Shell-Behavior-1"></span><h3 class="section">4.3 Modifying Shell Behavior</h3> + + +<ul class="section-toc"> +<li><a href="#The-Set-Builtin" accesskey="1">The Set Builtin</a></li> +<li><a href="#The-Shopt-Builtin" accesskey="2">The Shopt Builtin</a></li> +</ul> +<hr> +<div class="subsection" id="The-Set-Builtin"> +<div class="header"> +<p> +Next: <a href="#The-Shopt-Builtin" accesskey="n" rel="next">The Shopt Builtin</a>, Up: <a href="#Modifying-Shell-Behavior" accesskey="u" rel="up">Modifying Shell Behavior</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="The-Set-Builtin-1"></span><h4 class="subsection">4.3.1 The Set Builtin</h4> + +<p>This builtin is so complicated that it deserves its own section. <code>set</code> +allows you to change the values of shell options and set the positional +parameters, or to display the names and values of shell variables. +</p> +<dl compact="compact"> +<dt id='index-set'><span><code>set</code><a href='#index-set' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">set [-abefhkmnptuvxBCEHPT] [-o <var>option-name</var>] [--] [-] [<var>argument</var> …] +set [+abefhkmnptuvxBCEHPT] [+o <var>option-name</var>] [--] [-] [<var>argument</var> …] +</pre></div> + +<p>If no options or arguments are supplied, <code>set</code> displays the names +and values of all shell variables and functions, sorted according to the +current locale, in a format that may be reused as input +for setting or resetting the currently-set variables. +Read-only variables cannot be reset. +In <small>POSIX</small> mode, only shell variables are listed. +</p> +<p>When options are supplied, they set or unset shell attributes. +Options, if specified, have the following meanings: +</p> +<dl compact="compact"> +<dt><span><code>-a</code></span></dt> +<dd><p>Each variable or function that is created or modified is given the +export attribute and marked for export to the environment of +subsequent commands. +</p> +</dd> +<dt><span><code>-b</code></span></dt> +<dd><p>Cause the status of terminated background jobs to be reported +immediately, rather than before printing the next primary prompt. +</p> +</dd> +<dt><span><code>-e</code></span></dt> +<dd><p>Exit immediately if +a pipeline (see <a href="#Pipelines">Pipelines</a>), which may consist of a single simple command +(see <a href="#Simple-Commands">Simple Commands</a>), +a list (see <a href="#Lists">Lists of Commands</a>), +or a compound command (see <a href="#Compound-Commands">Compound Commands</a>) +returns a non-zero status. +The shell does not exit if the command that fails is part of the +command list immediately following a <code>while</code> or <code>until</code> keyword, +part of the test in an <code>if</code> statement, +part of any command executed in a <code>&&</code> or <code>||</code> list except +the command following the final <code>&&</code> or <code>||</code>, +any command in a pipeline but the last, +or if the command’s return status is being inverted with <code>!</code>. +If a compound command other than a subshell +returns a non-zero status because a command failed +while <samp>-e</samp> was being ignored, the shell does not exit. +A trap on <code>ERR</code>, if set, is executed before the shell exits. +</p> +<p>This option applies to the shell environment and each subshell environment +separately (see <a href="#Command-Execution-Environment">Command Execution Environment</a>), and may cause +subshells to exit before executing all the commands in the subshell. +</p> +<p>If a compound command or shell function executes in a context where +<samp>-e</samp> is being ignored, +none of the commands executed within the compound command or function body +will be affected by the <samp>-e</samp> setting, even if <samp>-e</samp> is set +and a command returns a failure status. +If a compound command or shell function sets <samp>-e</samp> while executing in +a context where <samp>-e</samp> is ignored, that setting will not have any +effect until the compound command or the command containing the function +call completes. +</p> +</dd> +<dt><span><code>-f</code></span></dt> +<dd><p>Disable filename expansion (globbing). +</p> +</dd> +<dt><span><code>-h</code></span></dt> +<dd><p>Locate and remember (hash) commands as they are looked up for execution. +This option is enabled by default. +</p> +</dd> +<dt><span><code>-k</code></span></dt> +<dd><p>All arguments in the form of assignment statements are placed +in the environment for a command, not just those that precede +the command name. +</p> +</dd> +<dt><span><code>-m</code></span></dt> +<dd><p>Job control is enabled (see <a href="#Job-Control">Job Control</a>). +All processes run in a separate process group. +When a background job completes, the shell prints a line +containing its exit status. +</p> +</dd> +<dt><span><code>-n</code></span></dt> +<dd><p>Read commands but do not execute them. +This may be used to check a script for syntax errors. +This option is ignored by interactive shells. +</p> +</dd> +<dt><span><code>-o <var>option-name</var></code></span></dt> +<dd> +<p>Set the option corresponding to <var>option-name</var>: +</p> +<dl compact="compact"> +<dt><span><code>allexport</code></span></dt> +<dd><p>Same as <code>-a</code>. +</p> +</dd> +<dt><span><code>braceexpand</code></span></dt> +<dd><p>Same as <code>-B</code>. +</p> +</dd> +<dt><span><code>emacs</code></span></dt> +<dd><p>Use an <code>emacs</code>-style line editing interface (see <a href="#Command-Line-Editing">Command Line Editing</a>). +This also affects the editing interface used for <code>read -e</code>. +</p> +</dd> +<dt><span><code>errexit</code></span></dt> +<dd><p>Same as <code>-e</code>. +</p> +</dd> +<dt><span><code>errtrace</code></span></dt> +<dd><p>Same as <code>-E</code>. +</p> +</dd> +<dt><span><code>functrace</code></span></dt> +<dd><p>Same as <code>-T</code>. +</p> +</dd> +<dt><span><code>hashall</code></span></dt> +<dd><p>Same as <code>-h</code>. +</p> +</dd> +<dt><span><code>histexpand</code></span></dt> +<dd><p>Same as <code>-H</code>. +</p> +</dd> +<dt><span><code>history</code></span></dt> +<dd><p>Enable command history, as described in <a href="#Bash-History-Facilities">Bash History Facilities</a>. +This option is on by default in interactive shells. +</p> +</dd> +<dt><span><code>ignoreeof</code></span></dt> +<dd><p>An interactive shell will not exit upon reading EOF. +</p> +</dd> +<dt><span><code>keyword</code></span></dt> +<dd><p>Same as <code>-k</code>. +</p> +</dd> +<dt><span><code>monitor</code></span></dt> +<dd><p>Same as <code>-m</code>. +</p> +</dd> +<dt><span><code>noclobber</code></span></dt> +<dd><p>Same as <code>-C</code>. +</p> +</dd> +<dt><span><code>noexec</code></span></dt> +<dd><p>Same as <code>-n</code>. +</p> +</dd> +<dt><span><code>noglob</code></span></dt> +<dd><p>Same as <code>-f</code>. +</p> +</dd> +<dt><span><code>nolog</code></span></dt> +<dd><p>Currently ignored. +</p> +</dd> +<dt><span><code>notify</code></span></dt> +<dd><p>Same as <code>-b</code>. +</p> +</dd> +<dt><span><code>nounset</code></span></dt> +<dd><p>Same as <code>-u</code>. +</p> +</dd> +<dt><span><code>onecmd</code></span></dt> +<dd><p>Same as <code>-t</code>. +</p> +</dd> +<dt><span><code>physical</code></span></dt> +<dd><p>Same as <code>-P</code>. +</p> +</dd> +<dt><span><code>pipefail</code></span></dt> +<dd><p>If set, the return value of a pipeline is the value of the last +(rightmost) command to exit with a non-zero status, or zero if all +commands in the pipeline exit successfully. +This option is disabled by default. +</p> +</dd> +<dt><span><code>posix</code></span></dt> +<dd><p>Change the behavior of Bash where the default operation differs +from the <small>POSIX</small> standard to match the standard +(see <a href="#Bash-POSIX-Mode">Bash POSIX Mode</a>). +This is intended to make Bash behave as a strict superset of that +standard. +</p> +</dd> +<dt><span><code>privileged</code></span></dt> +<dd><p>Same as <code>-p</code>. +</p> +</dd> +<dt><span><code>verbose</code></span></dt> +<dd><p>Same as <code>-v</code>. +</p> +</dd> +<dt><span><code>vi</code></span></dt> +<dd><p>Use a <code>vi</code>-style line editing interface. +This also affects the editing interface used for <code>read -e</code>. +</p> +</dd> +<dt><span><code>xtrace</code></span></dt> +<dd><p>Same as <code>-x</code>. +</p></dd> +</dl> + +</dd> +<dt><span><code>-p</code></span></dt> +<dd><p>Turn on privileged mode. +In this mode, the <code>$BASH_ENV</code> and <code>$ENV</code> files are not +processed, shell functions are not inherited from the environment, +and the <code>SHELLOPTS</code>, <code>BASHOPTS</code>, <code>CDPATH</code> and <code>GLOBIGNORE</code> +variables, if they appear in the environment, are ignored. +If the shell is started with the effective user (group) id not equal to the +real user (group) id, and the <samp>-p</samp> option is not supplied, these actions +are taken and the effective user id is set to the real user id. +If the <samp>-p</samp> option is supplied at startup, the effective user id is +not reset. +Turning this option off causes the effective user +and group ids to be set to the real user and group ids. +</p> +</dd> +<dt><span><code>-r</code></span></dt> +<dd><p>Enable restricted shell mode. +This option cannot be unset once it has been set. +</p> +</dd> +<dt><span><code>-t</code></span></dt> +<dd><p>Exit after reading and executing one command. +</p> +</dd> +<dt><span><code>-u</code></span></dt> +<dd><p>Treat unset variables and parameters other than the special parameters +‘<samp>@</samp>’ or ‘<samp>*</samp>’, +or array variables subscripted with ‘<samp>@</samp>’ or ‘<samp>*</samp>’, +as an error when performing parameter expansion. +An error message will be written to the standard error, and a non-interactive +shell will exit. +</p> +</dd> +<dt><span><code>-v</code></span></dt> +<dd><p>Print shell input lines as they are read. +</p> +</dd> +<dt><span><code>-x</code></span></dt> +<dd><p>Print a trace of simple commands, <code>for</code> commands, <code>case</code> +commands, <code>select</code> commands, and arithmetic <code>for</code> commands +and their arguments or associated word lists after they are +expanded and before they are executed. The value of the <code>PS4</code> +variable is expanded and the resultant value is printed before +the command and its expanded arguments. +</p> +</dd> +<dt><span><code>-B</code></span></dt> +<dd><p>The shell will perform brace expansion (see <a href="#Brace-Expansion">Brace Expansion</a>). +This option is on by default. +</p> +</dd> +<dt><span><code>-C</code></span></dt> +<dd><p>Prevent output redirection using ‘<samp>></samp>’, ‘<samp>>&</samp>’, and ‘<samp><></samp>’ +from overwriting existing files. +</p> +</dd> +<dt><span><code>-E</code></span></dt> +<dd><p>If set, any trap on <code>ERR</code> is inherited by shell functions, command +substitutions, and commands executed in a subshell environment. +The <code>ERR</code> trap is normally not inherited in such cases. +</p> +</dd> +<dt><span><code>-H</code></span></dt> +<dd><p>Enable ‘<samp>!</samp>’ style history substitution (see <a href="#History-Interaction">History Expansion</a>). +This option is on by default for interactive shells. +</p> +</dd> +<dt><span><code>-P</code></span></dt> +<dd><p>If set, do not resolve symbolic links when performing commands such as +<code>cd</code> which change the current directory. The physical directory +is used instead. By default, Bash follows +the logical chain of directories when performing commands +which change the current directory. +</p> +<p>For example, if <samp>/usr/sys</samp> is a symbolic link to <samp>/usr/local/sys</samp> +then: +</p><div class="example"> +<pre class="example">$ cd /usr/sys; echo $PWD +/usr/sys +$ cd ..; pwd +/usr +</pre></div> + +<p>If <code>set -P</code> is on, then: +</p><div class="example"> +<pre class="example">$ cd /usr/sys; echo $PWD +/usr/local/sys +$ cd ..; pwd +/usr/local +</pre></div> + +</dd> +<dt><span><code>-T</code></span></dt> +<dd><p>If set, any trap on <code>DEBUG</code> and <code>RETURN</code> are inherited by +shell functions, command substitutions, and commands executed +in a subshell environment. +The <code>DEBUG</code> and <code>RETURN</code> traps are normally not inherited +in such cases. +</p> +</dd> +<dt><span><code>--</code></span></dt> +<dd><p>If no arguments follow this option, then the positional parameters are +unset. Otherwise, the positional parameters are set to the +<var>arguments</var>, even if some of them begin with a ‘<samp>-</samp>’. +</p> +</dd> +<dt><span><code>-</code></span></dt> +<dd><p>Signal the end of options, cause all remaining <var>arguments</var> +to be assigned to the positional parameters. The <samp>-x</samp> +and <samp>-v</samp> options are turned off. +If there are no arguments, the positional parameters remain unchanged. +</p></dd> +</dl> + +<p>Using ‘<samp>+</samp>’ rather than ‘<samp>-</samp>’ causes these options to be +turned off. The options can also be used upon invocation of the +shell. The current set of options may be found in <code>$-</code>. +</p> +<p>The remaining N <var>arguments</var> are positional parameters and are +assigned, in order, to <code>$1</code>, <code>$2</code>, … <code>$N</code>. +The special parameter <code>#</code> is set to N. +</p> +<p>The return status is always zero unless an invalid option is supplied. +</p></dd> +</dl> + +<hr> +</div> +<div class="subsection" id="The-Shopt-Builtin"> +<div class="header"> +<p> +Previous: <a href="#The-Set-Builtin" accesskey="p" rel="prev">The Set Builtin</a>, Up: <a href="#Modifying-Shell-Behavior" accesskey="u" rel="up">Modifying Shell Behavior</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="The-Shopt-Builtin-1"></span><h4 class="subsection">4.3.2 The Shopt Builtin</h4> + +<p>This builtin allows you to change additional shell optional behavior. +</p> +<dl compact="compact"> +<dt id='index-shopt'><span><code>shopt</code><a href='#index-shopt' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">shopt [-pqsu] [-o] [<var>optname</var> …] +</pre></div> + +<p>Toggle the values of settings controlling optional shell behavior. +The settings can be either those listed below, or, if the +<samp>-o</samp> option is used, those available with the <samp>-o</samp> +option to the <code>set</code> builtin command (see <a href="#The-Set-Builtin">The Set Builtin</a>). +With no options, or with the <samp>-p</samp> option, a list of all settable +options is displayed, with an indication of whether or not each is set; +if <var>optname</var>s are supplied, the output is restricted to those options. +The <samp>-p</samp> option causes output to be displayed in a form that +may be reused as input. +Other options have the following meanings: +</p> +<dl compact="compact"> +<dt><span><code>-s</code></span></dt> +<dd><p>Enable (set) each <var>optname</var>. +</p> +</dd> +<dt><span><code>-u</code></span></dt> +<dd><p>Disable (unset) each <var>optname</var>. +</p> +</dd> +<dt><span><code>-q</code></span></dt> +<dd><p>Suppresses normal output; the return status +indicates whether the <var>optname</var> is set or unset. +If multiple <var>optname</var> arguments are given with <samp>-q</samp>, +the return status is zero if all <var>optname</var>s are enabled; +non-zero otherwise. +</p> +</dd> +<dt><span><code>-o</code></span></dt> +<dd><p>Restricts the values of +<var>optname</var> to be those defined for the <samp>-o</samp> option to the +<code>set</code> builtin (see <a href="#The-Set-Builtin">The Set Builtin</a>). +</p></dd> +</dl> + +<p>If either <samp>-s</samp> or <samp>-u</samp> +is used with no <var>optname</var> arguments, <code>shopt</code> shows only +those options which are set or unset, respectively. +</p> +<p>Unless otherwise noted, the <code>shopt</code> options are disabled (off) +by default. +</p> +<p>The return status when listing options is zero if all <var>optname</var>s +are enabled, non-zero otherwise. When setting or unsetting options, +the return status is zero unless an <var>optname</var> is not a valid shell +option. +</p> +<p>The list of <code>shopt</code> options is: +</p><dl compact="compact"> +<dt><span><code>assoc_expand_once</code></span></dt> +<dd><p>If set, the shell suppresses multiple evaluation of associative array +subscripts during arithmetic expression evaluation, while executing +builtins that can perform variable assignments, +and while executing builtins that perform array dereferencing. +</p> +</dd> +<dt><span><code>autocd</code></span></dt> +<dd><p>If set, a command name that is the name of a directory is executed as if +it were the argument to the <code>cd</code> command. +This option is only used by interactive shells. +</p> +</dd> +<dt><span><code>cdable_vars</code></span></dt> +<dd><p>If this is set, an argument to the <code>cd</code> builtin command that +is not a directory is assumed to be the name of a variable whose +value is the directory to change to. +</p> +</dd> +<dt><span><code>cdspell</code></span></dt> +<dd><p>If set, minor errors in the spelling of a directory component in a +<code>cd</code> command will be corrected. +The errors checked for are transposed characters, +a missing character, and a character too many. +If a correction is found, the corrected path is printed, +and the command proceeds. +This option is only used by interactive shells. +</p> +</dd> +<dt><span><code>checkhash</code></span></dt> +<dd><p>If this is set, Bash checks that a command found in the hash +table exists before trying to execute it. If a hashed command no +longer exists, a normal path search is performed. +</p> +</dd> +<dt><span><code>checkjobs</code></span></dt> +<dd><p>If set, Bash lists the status of any stopped and running jobs before +exiting an interactive shell. If any jobs are running, this causes +the exit to be deferred until a second exit is attempted without an +intervening command (see <a href="#Job-Control">Job Control</a>). +The shell always postpones exiting if any jobs are stopped. +</p> +</dd> +<dt><span><code>checkwinsize</code></span></dt> +<dd><p>If set, Bash checks the window size after each external (non-builtin) +command and, if necessary, updates the values of +<code>LINES</code> and <code>COLUMNS</code>. +This option is enabled by default. +</p> +</dd> +<dt><span><code>cmdhist</code></span></dt> +<dd><p>If set, Bash +attempts to save all lines of a multiple-line +command in the same history entry. This allows +easy re-editing of multi-line commands. +This option is enabled by default, but only has an effect if command +history is enabled (see <a href="#Bash-History-Facilities">Bash History Facilities</a>). +</p> +</dd> +<dt><span><code>compat31</code></span></dt> +<dt><span><code>compat32</code></span></dt> +<dt><span><code>compat40</code></span></dt> +<dt><span><code>compat41</code></span></dt> +<dt><span><code>compat42</code></span></dt> +<dt><span><code>compat43</code></span></dt> +<dt><span><code>compat44</code></span></dt> +<dd><p>These control aspects of the shell’s compatibility mode +(see <a href="#Shell-Compatibility-Mode">Shell Compatibility Mode</a>). +</p> +</dd> +<dt><span><code>complete_fullquote</code></span></dt> +<dd><p>If set, Bash +quotes all shell metacharacters in filenames and directory names when +performing completion. +If not set, Bash +removes metacharacters such as the dollar sign from the set of +characters that will be quoted in completed filenames +when these metacharacters appear in shell variable references in words to be +completed. +This means that dollar signs in variable names that expand to directories +will not be quoted; +however, any dollar signs appearing in filenames will not be quoted, either. +This is active only when bash is using backslashes to quote completed +filenames. +This variable is set by default, which is the default Bash behavior in +versions through 4.2. +</p> +</dd> +<dt><span><code>direxpand</code></span></dt> +<dd><p>If set, Bash +replaces directory names with the results of word expansion when performing +filename completion. This changes the contents of the Readline editing +buffer. +If not set, Bash attempts to preserve what the user typed. +</p> +</dd> +<dt><span><code>dirspell</code></span></dt> +<dd><p>If set, Bash +attempts spelling correction on directory names during word completion +if the directory name initially supplied does not exist. +</p> +</dd> +<dt><span><code>dotglob</code></span></dt> +<dd><p>If set, Bash includes filenames beginning with a ‘.’ in +the results of filename expansion. +The filenames ‘<samp>.</samp>’ and ‘<samp>..</samp>’ must always be matched explicitly, +even if <code>dotglob</code> is set. +</p> +</dd> +<dt><span><code>execfail</code></span></dt> +<dd><p>If this is set, a non-interactive shell will not exit if +it cannot execute the file specified as an argument to the <code>exec</code> +builtin command. An interactive shell does not exit if <code>exec</code> +fails. +</p> +</dd> +<dt><span><code>expand_aliases</code></span></dt> +<dd><p>If set, aliases are expanded as described below under Aliases, +<a href="#Aliases">Aliases</a>. +This option is enabled by default for interactive shells. +</p> +</dd> +<dt><span><code>extdebug</code></span></dt> +<dd><p>If set at shell invocation, +or in a shell startup file, +arrange to execute the debugger profile +before the shell starts, identical to the <samp>--debugger</samp> option. +If set after invocation, behavior intended for use by debuggers is enabled: +</p> +<ol> +<li> The <samp>-F</samp> option to the <code>declare</code> builtin (see <a href="#Bash-Builtins">Bash Builtin Commands</a>) +displays the source file name and line number corresponding to each function +name supplied as an argument. + +</li><li> If the command run by the <code>DEBUG</code> trap returns a non-zero value, the +next command is skipped and not executed. + +</li><li> If the command run by the <code>DEBUG</code> trap returns a value of 2, and the +shell is executing in a subroutine (a shell function or a shell script +executed by the <code>.</code> or <code>source</code> builtins), the shell simulates +a call to <code>return</code>. + +</li><li> <code>BASH_ARGC</code> and <code>BASH_ARGV</code> are updated as described in their +descriptions (see <a href="#Bash-Variables">Bash Variables</a>). + +</li><li> Function tracing is enabled: command substitution, shell functions, and +subshells invoked with <code>( <var>command</var> )</code> inherit the +<code>DEBUG</code> and <code>RETURN</code> traps. + +</li><li> Error tracing is enabled: command substitution, shell functions, and +subshells invoked with <code>( <var>command</var> )</code> inherit the +<code>ERR</code> trap. +</li></ol> + +</dd> +<dt><span><code>extglob</code></span></dt> +<dd><p>If set, the extended pattern matching features described above +(see <a href="#Pattern-Matching">Pattern Matching</a>) are enabled. +</p> +</dd> +<dt><span><code>extquote</code></span></dt> +<dd><p>If set, <code>$'<var>string</var>'</code> and <code>$"<var>string</var>"</code> quoting is +performed within <code>${<var>parameter</var>}</code> expansions +enclosed in double quotes. This option is enabled by default. +</p> +</dd> +<dt><span><code>failglob</code></span></dt> +<dd><p>If set, patterns which fail to match filenames during filename expansion +result in an expansion error. +</p> +</dd> +<dt><span><code>force_fignore</code></span></dt> +<dd><p>If set, the suffixes specified by the <code>FIGNORE</code> shell variable +cause words to be ignored when performing word completion even if +the ignored words are the only possible completions. +See <a href="#Bash-Variables">Bash Variables</a>, for a description of <code>FIGNORE</code>. +This option is enabled by default. +</p> +</dd> +<dt><span><code>globasciiranges</code></span></dt> +<dd><p>If set, range expressions used in pattern matching bracket expressions +(see <a href="#Pattern-Matching">Pattern Matching</a>) +behave as if in the traditional C locale when performing +comparisons. That is, the current locale’s collating sequence +is not taken into account, so +‘<samp>b</samp>’ will not collate between ‘<samp>A</samp>’ and ‘<samp>B</samp>’, +and upper-case and lower-case ASCII characters will collate together. +</p> +</dd> +<dt><span><code>globskipdots</code></span></dt> +<dd><p>If set, filename expansion will never match the filenames +‘<samp>.</samp>’ and ‘<samp>..</samp>’, +even if the pattern begins with a ‘<samp>.</samp>’. +This option is enabled by default. +</p> +</dd> +<dt><span><code>globstar</code></span></dt> +<dd><p>If set, the pattern ‘<samp>**</samp>’ used in a filename expansion context will +match all files and zero or more directories and subdirectories. +If the pattern is followed by a ‘<samp>/</samp>’, only directories and +subdirectories match. +</p> +</dd> +<dt><span><code>gnu_errfmt</code></span></dt> +<dd><p>If set, shell error messages are written in the standard <small>GNU</small> error +message format. +</p> +</dd> +<dt><span><code>histappend</code></span></dt> +<dd><p>If set, the history list is appended to the file named by the value +of the <code>HISTFILE</code> +variable when the shell exits, rather than overwriting the file. +</p> +</dd> +<dt><span><code>histreedit</code></span></dt> +<dd><p>If set, and Readline +is being used, a user is given the opportunity to re-edit a +failed history substitution. +</p> +</dd> +<dt><span><code>histverify</code></span></dt> +<dd><p>If set, and Readline +is being used, the results of history substitution are not immediately +passed to the shell parser. Instead, the resulting line is loaded into +the Readline editing buffer, allowing further modification. +</p> +</dd> +<dt><span><code>hostcomplete</code></span></dt> +<dd><p>If set, and Readline is being used, Bash will attempt to perform +hostname completion when a word containing a ‘<samp>@</samp>’ is being +completed (see <a href="#Commands-For-Completion">Letting Readline Type For You</a>). This option is enabled +by default. +</p> +</dd> +<dt><span><code>huponexit</code></span></dt> +<dd><p>If set, Bash will send <code>SIGHUP</code> to all jobs when an interactive +login shell exits (see <a href="#Signals">Signals</a>). +</p> +</dd> +<dt><span><code>inherit_errexit</code></span></dt> +<dd><p>If set, command substitution inherits the value of the <code>errexit</code> option, +instead of unsetting it in the subshell environment. +This option is enabled when <small>POSIX</small> mode is enabled. +</p> +</dd> +<dt><span><code>interactive_comments</code></span></dt> +<dd><p>Allow a word beginning with ‘<samp>#</samp>’ +to cause that word and all remaining characters on that +line to be ignored in an interactive shell. +This option is enabled by default. +</p> +</dd> +<dt><span><code>lastpipe</code></span></dt> +<dd><p>If set, and job control is not active, the shell runs the last command of +a pipeline not executed in the background in the current shell environment. +</p> +</dd> +<dt><span><code>lithist</code></span></dt> +<dd><p>If enabled, and the <code>cmdhist</code> +option is enabled, multi-line commands are saved to the history with +embedded newlines rather than using semicolon separators where possible. +</p> +</dd> +<dt><span><code>localvar_inherit</code></span></dt> +<dd><p>If set, local variables inherit the value and attributes of a variable of +the same name that exists at a previous scope before any new value is +assigned. The <code>nameref</code> attribute is not inherited. +</p> +</dd> +<dt><span><code>localvar_unset</code></span></dt> +<dd><p>If set, calling <code>unset</code> on local variables in previous function scopes +marks them so subsequent lookups find them unset until that function +returns. This is identical to the behavior of unsetting local variables +at the current function scope. +</p> +</dd> +<dt><span><code>login_shell</code></span></dt> +<dd><p>The shell sets this option if it is started as a login shell +(see <a href="#Invoking-Bash">Invoking Bash</a>). +The value may not be changed. +</p> +</dd> +<dt><span><code>mailwarn</code></span></dt> +<dd><p>If set, and a file that Bash is checking for mail has been +accessed since the last time it was checked, the message +<code>"The mail in <var>mailfile</var> has been read"</code> is displayed. +</p> +</dd> +<dt><span><code>no_empty_cmd_completion</code></span></dt> +<dd><p>If set, and Readline is being used, Bash will not attempt to search +the <code>PATH</code> for possible completions when completion is attempted +on an empty line. +</p> +</dd> +<dt><span><code>nocaseglob</code></span></dt> +<dd><p>If set, Bash matches filenames in a case-insensitive fashion when +performing filename expansion. +</p> +</dd> +<dt><span><code>nocasematch</code></span></dt> +<dd><p>If set, Bash matches patterns in a case-insensitive fashion when +performing matching while executing <code>case</code> or <code>[[</code> +conditional commands (see <a href="#Conditional-Constructs">Conditional Constructs</a>, +when performing pattern substitution word expansions, +or when filtering possible completions as part of programmable completion. +</p> +</dd> +<dt><span><code>noexpand_translation</code></span></dt> +<dd><p>If set, Bash +encloses the translated results of $"..." quoting in single quotes +instead of double quotes. +If the string is not translated, this has no effect. +</p> +</dd> +<dt><span><code>nullglob</code></span></dt> +<dd><p>If set, Bash allows filename patterns which match no +files to expand to a null string, rather than themselves. +</p> +</dd> +<dt><span><code>patsub_replacement</code></span></dt> +<dd><p>If set, Bash +expands occurrences of ‘<samp>&</samp>’ in the replacement string of pattern +substitution to the text matched by the pattern, as described +above (see <a href="#Shell-Parameter-Expansion">Shell Parameter Expansion</a>). +This option is enabled by default. +</p> +</dd> +<dt><span><code>progcomp</code></span></dt> +<dd><p>If set, the programmable completion facilities +(see <a href="#Programmable-Completion">Programmable Completion</a>) are enabled. +This option is enabled by default. +</p> +</dd> +<dt><span><code>progcomp_alias</code></span></dt> +<dd><p>If set, and programmable completion is enabled, Bash treats a command +name that doesn’t have any completions as a possible alias and attempts +alias expansion. If it has an alias, Bash attempts programmable +completion using the command word resulting from the expanded alias. +</p> +</dd> +<dt><span><code>promptvars</code></span></dt> +<dd><p>If set, prompt strings undergo +parameter expansion, command substitution, arithmetic +expansion, and quote removal after being expanded +as described below (see <a href="#Controlling-the-Prompt">Controlling the Prompt</a>). +This option is enabled by default. +</p> +</dd> +<dt><span><code>restricted_shell</code></span></dt> +<dd><p>The shell sets this option if it is started in restricted mode +(see <a href="#The-Restricted-Shell">The Restricted Shell</a>). +The value may not be changed. +This is not reset when the startup files are executed, allowing +the startup files to discover whether or not a shell is restricted. +</p> +</dd> +<dt><span><code>shift_verbose</code></span></dt> +<dd><p>If this is set, the <code>shift</code> +builtin prints an error message when the shift count exceeds the +number of positional parameters. +</p> +</dd> +<dt><span><code>sourcepath</code></span></dt> +<dd><p>If set, the <code>.</code> (<code>source</code>) builtin uses the value of <code>PATH</code> +to find the directory containing the file supplied as an argument. +This option is enabled by default. +</p> +</dd> +<dt><span><code>varredir_close</code></span></dt> +<dd><p>If set, the shell automatically closes file descriptors assigned using the +<code>{varname}</code> redirection syntax (see <a href="#Redirections">Redirections</a>) instead of +leaving them open when the command completes. +</p> +</dd> +<dt><span><code>xpg_echo</code></span></dt> +<dd><p>If set, the <code>echo</code> builtin expands backslash-escape sequences +by default. +</p> +</dd> +</dl> +</dd> +</dl> + +<hr> +</div> +</div> +<div class="section" id="Special-Builtins"> +<div class="header"> +<p> +Previous: <a href="#Modifying-Shell-Behavior" accesskey="p" rel="prev">Modifying Shell Behavior</a>, Up: <a href="#Shell-Builtin-Commands" accesskey="u" rel="up">Shell Builtin Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Special-Builtins-1"></span><h3 class="section">4.4 Special Builtins</h3> +<span id="index-special-builtin-1"></span> + +<p>For historical reasons, the <small>POSIX</small> standard has classified +several builtin commands as <em>special</em>. +When Bash is executing in <small>POSIX</small> mode, the special builtins +differ from other builtin commands in three respects: +</p> +<ol> +<li> Special builtins are found before shell functions during command lookup. + +</li><li> If a special builtin returns an error status, a non-interactive shell exits. + +</li><li> Assignment statements preceding the command stay in effect in the shell +environment after the command completes. +</li></ol> + +<p>When Bash is not executing in <small>POSIX</small> mode, these builtins behave no +differently than the rest of the Bash builtin commands. +The Bash <small>POSIX</small> mode is described in <a href="#Bash-POSIX-Mode">Bash POSIX Mode</a>. +</p> +<p>These are the <small>POSIX</small> special builtins: +</p><div class="example"> +<pre class="example">break : . continue eval exec exit export readonly return set<!-- /@w --> +shift trap unset<!-- /@w --> +</pre></div> + +<hr> +</div> +</div> +<div class="chapter" id="Shell-Variables"> +<div class="header"> +<p> +Next: <a href="#Bash-Features" accesskey="n" rel="next">Bash Features</a>, Previous: <a href="#Shell-Builtin-Commands" accesskey="p" rel="prev">Shell Builtin Commands</a>, Up: <a href="#Top" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Shell-Variables-1"></span><h2 class="chapter">5 Shell Variables</h2> + + +<p>This chapter describes the shell variables that Bash uses. +Bash automatically assigns default values to a number of variables. +</p> +<ul class="section-toc"> +<li><a href="#Bourne-Shell-Variables" accesskey="1">Bourne Shell Variables</a></li> +<li><a href="#Bash-Variables" accesskey="2">Bash Variables</a></li> +</ul> +<hr> +<div class="section" id="Bourne-Shell-Variables"> +<div class="header"> +<p> +Next: <a href="#Bash-Variables" accesskey="n" rel="next">Bash Variables</a>, Up: <a href="#Shell-Variables" accesskey="u" rel="up">Shell Variables</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Bourne-Shell-Variables-1"></span><h3 class="section">5.1 Bourne Shell Variables</h3> + +<p>Bash uses certain shell variables in the same way as the Bourne shell. +In some cases, Bash assigns a default value to the variable. +</p> +<dl compact="compact"> +<dt id='index-CDPATH'><span><code>CDPATH</code><a href='#index-CDPATH' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A colon-separated list of directories used as a search path for +the <code>cd</code> builtin command. +</p> +</dd> +<dt id='index-HOME'><span><code>HOME</code><a href='#index-HOME' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The current user’s home directory; the default for the <code>cd</code> builtin +command. +The value of this variable is also used by tilde expansion +(see <a href="#Tilde-Expansion">Tilde Expansion</a>). +</p> +</dd> +<dt id='index-IFS'><span><code>IFS</code><a href='#index-IFS' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A list of characters that separate fields; used when the shell splits +words as part of expansion. +</p> +</dd> +<dt id='index-MAIL'><span><code>MAIL</code><a href='#index-MAIL' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If this parameter is set to a filename or directory name +and the <code>MAILPATH</code> variable +is not set, Bash informs the user of the arrival of mail in +the specified file or Maildir-format directory. +</p> +</dd> +<dt id='index-MAILPATH'><span><code>MAILPATH</code><a href='#index-MAILPATH' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A colon-separated list of filenames which the shell periodically checks +for new mail. +Each list entry can specify the message that is printed when new mail +arrives in the mail file by separating the filename from the message with +a ‘<samp>?</samp>’. +When used in the text of the message, <code>$_</code> expands to the name of +the current mail file. +</p> +</dd> +<dt id='index-OPTARG'><span><code>OPTARG</code><a href='#index-OPTARG' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The value of the last option argument processed by the <code>getopts</code> builtin. +</p> +</dd> +<dt id='index-OPTIND'><span><code>OPTIND</code><a href='#index-OPTIND' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The index of the last option argument processed by the <code>getopts</code> builtin. +</p> +</dd> +<dt id='index-PATH'><span><code>PATH</code><a href='#index-PATH' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A colon-separated list of directories in which the shell looks for +commands. +A zero-length (null) directory name in the value of <code>PATH</code> indicates the +current directory. +A null directory name may appear as two adjacent colons, or as an initial +or trailing colon. +</p> +</dd> +<dt id='index-PS1'><span><code>PS1</code><a href='#index-PS1' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The primary prompt string. The default value is ‘<samp>\s-\v\$ </samp>’. +See <a href="#Controlling-the-Prompt">Controlling the Prompt</a>, for the complete list of escape +sequences that are expanded before <code>PS1</code> is displayed. +</p> +</dd> +<dt id='index-PS2'><span><code>PS2</code><a href='#index-PS2' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The secondary prompt string. The default value is ‘<samp>> </samp>’. +<code>PS2</code> is expanded in the same way as <code>PS1</code> before being +displayed. +</p> +</dd> +</dl> + +<hr> +</div> +<div class="section" id="Bash-Variables"> +<div class="header"> +<p> +Previous: <a href="#Bourne-Shell-Variables" accesskey="p" rel="prev">Bourne Shell Variables</a>, Up: <a href="#Shell-Variables" accesskey="u" rel="up">Shell Variables</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Bash-Variables-1"></span><h3 class="section">5.2 Bash Variables</h3> + +<p>These variables are set or used by Bash, but other shells +do not normally treat them specially. +</p> +<p>A few variables used by Bash are described in different chapters: +variables for controlling the job control facilities +(see <a href="#Job-Control-Variables">Job Control Variables</a>). +</p> +<dl compact="compact"> +<dt id='index-_005f'><span><code>_</code><a href='#index-_005f' class='copiable-anchor'> ¶</a></span></dt> +<dd><span id="index-_0024_005f"></span> +<p>($_, an underscore.) +At shell startup, set to the pathname used to invoke the +shell or shell script being executed as passed in the environment +or argument list. +Subsequently, expands to the last argument to the previous simple +command executed in the foreground, after expansion. +Also set to the full pathname used to invoke each command executed +and placed in the environment exported to that command. +When checking mail, this parameter holds the name of the mail file. +</p> +</dd> +<dt id='index-BASH'><span><code>BASH</code><a href='#index-BASH' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The full pathname used to execute the current instance of Bash. +</p> +</dd> +<dt id='index-BASHOPTS'><span><code>BASHOPTS</code><a href='#index-BASHOPTS' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A colon-separated list of enabled shell options. Each word in +the list is a valid argument for the <samp>-s</samp> option to the +<code>shopt</code> builtin command (see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>). +The options appearing in <code>BASHOPTS</code> are those reported +as ‘<samp>on</samp>’ by ‘<samp>shopt</samp>’. +If this variable is in the environment when Bash +starts up, each shell option in the list will be enabled before +reading any startup files. This variable is readonly. +</p> +</dd> +<dt id='index-BASHPID'><span><code>BASHPID</code><a href='#index-BASHPID' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Expands to the process ID of the current Bash process. +This differs from <code>$$</code> under certain circumstances, such as subshells +that do not require Bash to be re-initialized. +Assignments to <code>BASHPID</code> have no effect. +If <code>BASHPID</code> +is unset, it loses its special properties, even if it is +subsequently reset. +</p> +</dd> +<dt id='index-BASH_005fALIASES'><span><code>BASH_ALIASES</code><a href='#index-BASH_005fALIASES' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>An associative array variable whose members correspond to the internal +list of aliases as maintained by the <code>alias</code> builtin. +(see <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>). +Elements added to this array appear in the alias list; however, +unsetting array elements currently does not cause aliases to be removed +from the alias list. +If <code>BASH_ALIASES</code> +is unset, it loses its special properties, even if it is +subsequently reset. +</p> +</dd> +<dt id='index-BASH_005fARGC'><span><code>BASH_ARGC</code><a href='#index-BASH_005fARGC' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>An array variable whose values are the number of parameters in each +frame of the current bash execution call stack. The number of +parameters to the current subroutine (shell function or script executed +with <code>.</code> or <code>source</code>) is at the top of the stack. When a +subroutine is executed, the number of parameters passed is pushed onto +<code>BASH_ARGC</code>. +The shell sets <code>BASH_ARGC</code> only when in extended debugging mode +(see <a href="#The-Shopt-Builtin">The Shopt Builtin</a> +for a description of the <code>extdebug</code> option to the <code>shopt</code> +builtin). +Setting <code>extdebug</code> after the shell has started to execute a script, +or referencing this variable when <code>extdebug</code> is not set, +may result in inconsistent values. +</p> +</dd> +<dt id='index-BASH_005fARGV'><span><code>BASH_ARGV</code><a href='#index-BASH_005fARGV' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>An array variable containing all of the parameters in the current bash +execution call stack. The final parameter of the last subroutine call +is at the top of the stack; the first parameter of the initial call is +at the bottom. When a subroutine is executed, the parameters supplied +are pushed onto <code>BASH_ARGV</code>. +The shell sets <code>BASH_ARGV</code> only when in extended debugging mode +(see <a href="#The-Shopt-Builtin">The Shopt Builtin</a> +for a description of the <code>extdebug</code> option to the <code>shopt</code> +builtin). +Setting <code>extdebug</code> after the shell has started to execute a script, +or referencing this variable when <code>extdebug</code> is not set, +may result in inconsistent values. +</p> +</dd> +<dt id='index-BASH_005fARGV0'><span><code>BASH_ARGV0</code><a href='#index-BASH_005fARGV0' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>When referenced, this variable expands to the name of the shell or shell +script (identical to <code>$0</code>; See <a href="#Special-Parameters">Special Parameters</a>, +for the description of special parameter 0). +Assignment to <code>BASH_ARGV0</code> +causes the value assigned to also be assigned to <code>$0</code>. +If <code>BASH_ARGV0</code> +is unset, it loses its special properties, even if it is +subsequently reset. +</p> +</dd> +<dt id='index-BASH_005fCMDS'><span><code>BASH_CMDS</code><a href='#index-BASH_005fCMDS' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>An associative array variable whose members correspond to the internal +hash table of commands as maintained by the <code>hash</code> builtin +(see <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>). +Elements added to this array appear in the hash table; however, +unsetting array elements currently does not cause command names to be removed +from the hash table. +If <code>BASH_CMDS</code> +is unset, it loses its special properties, even if it is +subsequently reset. +</p> +</dd> +<dt id='index-BASH_005fCOMMAND'><span><code>BASH_COMMAND</code><a href='#index-BASH_005fCOMMAND' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The command currently being executed or about to be executed, unless the +shell is executing a command as the result of a trap, +in which case it is the command executing at the time of the trap. +If <code>BASH_COMMAND</code> +is unset, it loses its special properties, even if it is +subsequently reset. +</p> +</dd> +<dt id='index-BASH_005fCOMPAT'><span><code>BASH_COMPAT</code><a href='#index-BASH_005fCOMPAT' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The value is used to set the shell’s compatibility level. +See <a href="#Shell-Compatibility-Mode">Shell Compatibility Mode</a>, for a description of the various +compatibility levels and their effects. +The value may be a decimal number (e.g., 4.2) or an integer (e.g., 42) +corresponding to the desired compatibility level. +If <code>BASH_COMPAT</code> is unset or set to the empty string, the compatibility +level is set to the default for the current version. +If <code>BASH_COMPAT</code> is set to a value that is not one of the valid +compatibility levels, the shell prints an error message and sets the +compatibility level to the default for the current version. +The valid values correspond to the compatibility levels +described below (see <a href="#Shell-Compatibility-Mode">Shell Compatibility Mode</a>). +For example, 4.2 and 42 are valid values that correspond +to the <code>compat42</code> <code>shopt</code> option +and set the compatibility level to 42. +The current version is also a valid value. +</p> +</dd> +<dt id='index-BASH_005fENV'><span><code>BASH_ENV</code><a href='#index-BASH_005fENV' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If this variable is set when Bash is invoked to execute a shell +script, its value is expanded and used as the name of a startup file +to read before executing the script. See <a href="#Bash-Startup-Files">Bash Startup Files</a>. +</p> +</dd> +<dt id='index-BASH_005fEXECUTION_005fSTRING'><span><code>BASH_EXECUTION_STRING</code><a href='#index-BASH_005fEXECUTION_005fSTRING' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The command argument to the <samp>-c</samp> invocation option. +</p> +</dd> +<dt id='index-BASH_005fLINENO'><span><code>BASH_LINENO</code><a href='#index-BASH_005fLINENO' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>An array variable whose members are the line numbers in source files +where each corresponding member of <code>FUNCNAME</code> was invoked. +<code>${BASH_LINENO[$i]}</code> is the line number in the source file +(<code>${BASH_SOURCE[$i+1]}</code>) where +<code>${FUNCNAME[$i]}</code> was called (or <code>${BASH_LINENO[$i-1]}</code> if +referenced within another shell function). +Use <code>LINENO</code> to obtain the current line number. +</p> +</dd> +<dt id='index-BASH_005fLOADABLES_005fPATH'><span><code>BASH_LOADABLES_PATH</code><a href='#index-BASH_005fLOADABLES_005fPATH' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A colon-separated list of directories in which the shell looks for +dynamically loadable builtins specified by the +<code>enable</code> command. +</p> +</dd> +<dt id='index-BASH_005fREMATCH'><span><code>BASH_REMATCH</code><a href='#index-BASH_005fREMATCH' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>An array variable whose members are assigned by the ‘<samp>=~</samp>’ binary +operator to the <code>[[</code> conditional command +(see <a href="#Conditional-Constructs">Conditional Constructs</a>). +The element with index 0 is the portion of the string +matching the entire regular expression. +The element with index <var>n</var> is the portion of the +string matching the <var>n</var>th parenthesized subexpression. +</p> +</dd> +<dt id='index-BASH_005fSOURCE'><span><code>BASH_SOURCE</code><a href='#index-BASH_005fSOURCE' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>An array variable whose members are the source filenames where the +corresponding shell function names in the <code>FUNCNAME</code> array +variable are defined. +The shell function <code>${FUNCNAME[$i]}</code> is defined in the file +<code>${BASH_SOURCE[$i]}</code> and called from <code>${BASH_SOURCE[$i+1]}</code> +</p> +</dd> +<dt id='index-BASH_005fSUBSHELL'><span><code>BASH_SUBSHELL</code><a href='#index-BASH_005fSUBSHELL' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Incremented by one within each subshell or subshell environment when +the shell begins executing in that environment. +The initial value is 0. +If <code>BASH_SUBSHELL</code> +is unset, it loses its special properties, even if it is +subsequently reset. +</p> +</dd> +<dt id='index-BASH_005fVERSINFO'><span><code>BASH_VERSINFO</code><a href='#index-BASH_005fVERSINFO' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A readonly array variable (see <a href="#Arrays">Arrays</a>) +whose members hold version information for this instance of Bash. +The values assigned to the array members are as follows: +</p> +<dl compact="compact"> +<dt><span><code>BASH_VERSINFO[0]</code></span></dt> +<dd><p>The major version number (the <em>release</em>). +</p> +</dd> +<dt><span><code>BASH_VERSINFO[1]</code></span></dt> +<dd><p>The minor version number (the <em>version</em>). +</p> +</dd> +<dt><span><code>BASH_VERSINFO[2]</code></span></dt> +<dd><p>The patch level. +</p> +</dd> +<dt><span><code>BASH_VERSINFO[3]</code></span></dt> +<dd><p>The build version. +</p> +</dd> +<dt><span><code>BASH_VERSINFO[4]</code></span></dt> +<dd><p>The release status (e.g., <code>beta1</code>). +</p> +</dd> +<dt><span><code>BASH_VERSINFO[5]</code></span></dt> +<dd><p>The value of <code>MACHTYPE</code>. +</p></dd> +</dl> + +</dd> +<dt id='index-BASH_005fVERSION'><span><code>BASH_VERSION</code><a href='#index-BASH_005fVERSION' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The version number of the current instance of Bash. +</p> +</dd> +<dt id='index-BASH_005fXTRACEFD'><span><code>BASH_XTRACEFD</code><a href='#index-BASH_005fXTRACEFD' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to an integer corresponding to a valid file descriptor, Bash +will write the trace output generated when ‘<samp>set -x</samp>’ +is enabled to that file descriptor. +This allows tracing output to be separated from diagnostic and error +messages. +The file descriptor is closed when <code>BASH_XTRACEFD</code> is unset or assigned +a new value. +Unsetting <code>BASH_XTRACEFD</code> or assigning it the empty string causes the +trace output to be sent to the standard error. +Note that setting <code>BASH_XTRACEFD</code> to 2 (the standard error file +descriptor) and then unsetting it will result in the standard error +being closed. +</p> +</dd> +<dt id='index-CHILD_005fMAX'><span><code>CHILD_MAX</code><a href='#index-CHILD_005fMAX' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Set the number of exited child status values for the shell to remember. +Bash will not allow this value to be decreased below a <small>POSIX</small>-mandated +minimum, and there is a maximum value (currently 8192) that this may +not exceed. +The minimum value is system-dependent. +</p> +</dd> +<dt id='index-COLUMNS'><span><code>COLUMNS</code><a href='#index-COLUMNS' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Used by the <code>select</code> command to determine the terminal width +when printing selection lists. +Automatically set if the <code>checkwinsize</code> option is enabled +(see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>), or in an interactive shell upon receipt of a +<code>SIGWINCH</code>. +</p> +</dd> +<dt id='index-COMP_005fCWORD'><span><code>COMP_CWORD</code><a href='#index-COMP_005fCWORD' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>An index into <code>${COMP_WORDS}</code> of the word containing the current +cursor position. +This variable is available only in shell functions invoked by the +programmable completion facilities (see <a href="#Programmable-Completion">Programmable Completion</a>). +</p> +</dd> +<dt id='index-COMP_005fLINE'><span><code>COMP_LINE</code><a href='#index-COMP_005fLINE' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The current command line. +This variable is available only in shell functions and external +commands invoked by the +programmable completion facilities (see <a href="#Programmable-Completion">Programmable Completion</a>). +</p> +</dd> +<dt id='index-COMP_005fPOINT'><span><code>COMP_POINT</code><a href='#index-COMP_005fPOINT' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The index of the current cursor position relative to the beginning of +the current command. +If the current cursor position is at the end of the current command, +the value of this variable is equal to <code>${#COMP_LINE}</code>. +This variable is available only in shell functions and external +commands invoked by the +programmable completion facilities (see <a href="#Programmable-Completion">Programmable Completion</a>). +</p> +</dd> +<dt id='index-COMP_005fTYPE'><span><code>COMP_TYPE</code><a href='#index-COMP_005fTYPE' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Set to an integer value corresponding to the type of completion attempted +that caused a completion function to be called: +<tt class="key">TAB</tt>, for normal completion, +‘<samp>?</samp>’, for listing completions after successive tabs, +‘<samp>!</samp>’, for listing alternatives on partial word completion, +‘<samp>@</samp>’, to list completions if the word is not unmodified, +or +‘<samp>%</samp>’, for menu completion. +This variable is available only in shell functions and external +commands invoked by the +programmable completion facilities (see <a href="#Programmable-Completion">Programmable Completion</a>). +</p> +</dd> +<dt id='index-COMP_005fKEY'><span><code>COMP_KEY</code><a href='#index-COMP_005fKEY' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The key (or final key of a key sequence) used to invoke the current +completion function. +</p> +</dd> +<dt id='index-COMP_005fWORDBREAKS'><span><code>COMP_WORDBREAKS</code><a href='#index-COMP_005fWORDBREAKS' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The set of characters that the Readline library treats as word +separators when performing word completion. +If <code>COMP_WORDBREAKS</code> +is unset, it loses its special properties, +even if it is subsequently reset. +</p> +</dd> +<dt id='index-COMP_005fWORDS'><span><code>COMP_WORDS</code><a href='#index-COMP_005fWORDS' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>An array variable consisting of the individual +words in the current command line. +The line is split into words as Readline would split it, using +<code>COMP_WORDBREAKS</code> as described above. +This variable is available only in shell functions invoked by the +programmable completion facilities (see <a href="#Programmable-Completion">Programmable Completion</a>). +</p> +</dd> +<dt id='index-COMPREPLY'><span><code>COMPREPLY</code><a href='#index-COMPREPLY' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>An array variable from which Bash reads the possible completions +generated by a shell function invoked by the programmable completion +facility (see <a href="#Programmable-Completion">Programmable Completion</a>). +Each array element contains one possible completion. +</p> +</dd> +<dt id='index-COPROC'><span><code>COPROC</code><a href='#index-COPROC' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>An array variable created to hold the file descriptors +for output from and input to an unnamed coprocess (see <a href="#Coprocesses">Coprocesses</a>). +</p> +</dd> +<dt id='index-DIRSTACK'><span><code>DIRSTACK</code><a href='#index-DIRSTACK' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>An array variable containing the current contents of the directory stack. +Directories appear in the stack in the order they are displayed by the +<code>dirs</code> builtin. +Assigning to members of this array variable may be used to modify +directories already in the stack, but the <code>pushd</code> and <code>popd</code> +builtins must be used to add and remove directories. +Assignment to this variable will not change the current directory. +If <code>DIRSTACK</code> +is unset, it loses its special properties, even if +it is subsequently reset. +</p> +</dd> +<dt id='index-EMACS'><span><code>EMACS</code><a href='#index-EMACS' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If Bash finds this variable in the environment when the shell +starts with value ‘<samp>t</samp>’, it assumes that the shell is running in an +Emacs shell buffer and disables line editing. +</p> +</dd> +<dt id='index-ENV'><span><code>ENV</code><a href='#index-ENV' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Expanded and executed similarly to <code>BASH_ENV</code> +(see <a href="#Bash-Startup-Files">Bash Startup Files</a>) +when an interactive shell is invoked in +<small>POSIX</small> Mode (see <a href="#Bash-POSIX-Mode">Bash POSIX Mode</a>). +</p> +</dd> +<dt id='index-EPOCHREALTIME'><span><code>EPOCHREALTIME</code><a href='#index-EPOCHREALTIME' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Each time this parameter is referenced, it expands to the number of seconds +since the Unix Epoch as a floating point value with micro-second granularity +(see the documentation for the C library function <code>time</code> for the +definition of Epoch). +Assignments to <code>EPOCHREALTIME</code> are ignored. +If <code>EPOCHREALTIME</code> +is unset, it loses its special properties, even if +it is subsequently reset. +</p> +</dd> +<dt id='index-EPOCHSECONDS'><span><code>EPOCHSECONDS</code><a href='#index-EPOCHSECONDS' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Each time this parameter is referenced, it expands to the number of seconds +since the Unix Epoch (see the documentation for the C library function +<code>time</code> for the definition of Epoch). +Assignments to <code>EPOCHSECONDS</code> are ignored. +If <code>EPOCHSECONDS</code> +is unset, it loses its special properties, even if +it is subsequently reset. +</p> +</dd> +<dt id='index-EUID'><span><code>EUID</code><a href='#index-EUID' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The numeric effective user id of the current user. This variable +is readonly. +</p> +</dd> +<dt id='index-EXECIGNORE'><span><code>EXECIGNORE</code><a href='#index-EXECIGNORE' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A colon-separated list of shell patterns (see <a href="#Pattern-Matching">Pattern Matching</a>) +defining the list of filenames to be ignored by command search using +<code>PATH</code>. +Files whose full pathnames match one of these patterns are not considered +executable files for the purposes of completion and command execution +via <code>PATH</code> lookup. +This does not affect the behavior of the <code>[</code>, <code>test</code>, and <code>[[</code> +commands. +Full pathnames in the command hash table are not subject to <code>EXECIGNORE</code>. +Use this variable to ignore shared library files that have the executable +bit set, but are not executable files. +The pattern matching honors the setting of the <code>extglob</code> shell +option. +</p> +</dd> +<dt id='index-FCEDIT'><span><code>FCEDIT</code><a href='#index-FCEDIT' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The editor used as a default by the <samp>-e</samp> option to the <code>fc</code> +builtin command. +</p> +</dd> +<dt id='index-FIGNORE'><span><code>FIGNORE</code><a href='#index-FIGNORE' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A colon-separated list of suffixes to ignore when performing +filename completion. +A filename whose suffix matches one of the entries in +<code>FIGNORE</code> +is excluded from the list of matched filenames. A sample +value is ‘<samp>.o:~</samp>’ +</p> +</dd> +<dt id='index-FUNCNAME'><span><code>FUNCNAME</code><a href='#index-FUNCNAME' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>An array variable containing the names of all shell functions +currently in the execution call stack. +The element with index 0 is the name of any currently-executing +shell function. +The bottom-most element (the one with the highest index) +is <code>"main"</code>. +This variable exists only when a shell function is executing. +Assignments to <code>FUNCNAME</code> have no effect. +If <code>FUNCNAME</code> +is unset, it loses its special properties, even if +it is subsequently reset. +</p> +<p>This variable can be used with <code>BASH_LINENO</code> and <code>BASH_SOURCE</code>. +Each element of <code>FUNCNAME</code> has corresponding elements in +<code>BASH_LINENO</code> and <code>BASH_SOURCE</code> to describe the call stack. +For instance, <code>${FUNCNAME[$i]}</code> was called from the file +<code>${BASH_SOURCE[$i+1]}</code> at line number <code>${BASH_LINENO[$i]}</code>. +The <code>caller</code> builtin displays the current call stack using this +information. +</p> +</dd> +<dt id='index-FUNCNEST'><span><code>FUNCNEST</code><a href='#index-FUNCNEST' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to a numeric value greater than 0, defines a maximum function +nesting level. Function invocations that exceed this nesting level +will cause the current command to abort. +</p> +</dd> +<dt id='index-GLOBIGNORE'><span><code>GLOBIGNORE</code><a href='#index-GLOBIGNORE' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A colon-separated list of patterns defining the set of file names to +be ignored by filename expansion. +If a file name matched by a filename expansion pattern also matches one +of the patterns in <code>GLOBIGNORE</code>, it is removed from the list +of matches. +The pattern matching honors the setting of the <code>extglob</code> shell +option. +</p> +</dd> +<dt id='index-GROUPS'><span><code>GROUPS</code><a href='#index-GROUPS' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>An array variable containing the list of groups of which the current +user is a member. +Assignments to <code>GROUPS</code> have no effect. +If <code>GROUPS</code> +is unset, it loses its special properties, even if it is +subsequently reset. +</p> +</dd> +<dt id='index-histchars'><span><code>histchars</code><a href='#index-histchars' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Up to three characters which control history expansion, quick +substitution, and tokenization (see <a href="#History-Interaction">History Expansion</a>). +The first character is the +<em>history expansion</em> character, that is, the character which signifies the +start of a history expansion, normally ‘<samp>!</samp>’. The second character is the +character which signifies ‘quick substitution’ when seen as the first +character on a line, normally ‘<samp>^</samp>’. The optional third character is the +character which indicates that the remainder of the line is a comment when +found as the first character of a word, usually ‘<samp>#</samp>’. The history +comment character causes history substitution to be skipped for the +remaining words on the line. It does not necessarily cause the shell +parser to treat the rest of the line as a comment. +</p> +</dd> +<dt id='index-HISTCMD'><span><code>HISTCMD</code><a href='#index-HISTCMD' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The history number, or index in the history list, of the current +command. +Assignments to <code>HISTCMD</code> are ignored. +If <code>HISTCMD</code> +is unset, it loses its special properties, +even if it is subsequently reset. +</p> +</dd> +<dt id='index-HISTCONTROL'><span><code>HISTCONTROL</code><a href='#index-HISTCONTROL' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A colon-separated list of values controlling how commands are saved on +the history list. +If the list of values includes ‘<samp>ignorespace</samp>’, lines which begin +with a space character are not saved in the history list. +A value of ‘<samp>ignoredups</samp>’ causes lines which match the previous +history entry to not be saved. +A value of ‘<samp>ignoreboth</samp>’ is shorthand for +‘<samp>ignorespace</samp>’ and ‘<samp>ignoredups</samp>’. +A value of ‘<samp>erasedups</samp>’ causes all previous lines matching the +current line to be removed from the history list before that line +is saved. +Any value not in the above list is ignored. +If <code>HISTCONTROL</code> is unset, or does not include a valid value, +all lines read by the shell parser are saved on the history list, +subject to the value of <code>HISTIGNORE</code>. +The second and subsequent lines of a multi-line compound command are +not tested, and are added to the history regardless of the value of +<code>HISTCONTROL</code>. +</p> +</dd> +<dt id='index-HISTFILE'><span><code>HISTFILE</code><a href='#index-HISTFILE' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The name of the file to which the command history is saved. The +default value is <samp>~/.bash_history</samp>. +</p> +</dd> +<dt id='index-HISTFILESIZE'><span><code>HISTFILESIZE</code><a href='#index-HISTFILESIZE' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The maximum number of lines contained in the history file. +When this variable is assigned a value, the history file is truncated, +if necessary, to contain no more than that number of lines +by removing the oldest entries. +The history file is also truncated to this size after +writing it when a shell exits. +If the value is 0, the history file is truncated to zero size. +Non-numeric values and numeric values less than zero inhibit truncation. +The shell sets the default value to the value of <code>HISTSIZE</code> +after reading any startup files. +</p> +</dd> +<dt id='index-HISTIGNORE'><span><code>HISTIGNORE</code><a href='#index-HISTIGNORE' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A colon-separated list of patterns used to decide which command +lines should be saved on the history list. Each pattern is +anchored at the beginning of the line and must match the complete +line (no implicit ‘<samp>*</samp>’ is appended). Each pattern is tested +against the line after the checks specified by <code>HISTCONTROL</code> +are applied. In addition to the normal shell pattern matching +characters, ‘<samp>&</samp>’ matches the previous history line. ‘<samp>&</samp>’ +may be escaped using a backslash; the backslash is removed +before attempting a match. +The second and subsequent lines of a multi-line compound command are +not tested, and are added to the history regardless of the value of +<code>HISTIGNORE</code>. +The pattern matching honors the setting of the <code>extglob</code> shell +option. +</p> +<p><code>HISTIGNORE</code> subsumes the function of <code>HISTCONTROL</code>. A +pattern of ‘<samp>&</samp>’ is identical to <code>ignoredups</code>, and a +pattern of ‘<samp>[ ]*</samp>’ is identical to <code>ignorespace</code>. +Combining these two patterns, separating them with a colon, +provides the functionality of <code>ignoreboth</code>. +</p> +</dd> +<dt id='index-HISTSIZE'><span><code>HISTSIZE</code><a href='#index-HISTSIZE' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The maximum number of commands to remember on the history list. +If the value is 0, commands are not saved in the history list. +Numeric values less than zero result in every command being saved +on the history list (there is no limit). +The shell sets the default value to 500 after reading any startup files. +</p> +</dd> +<dt id='index-HISTTIMEFORMAT'><span><code>HISTTIMEFORMAT</code><a href='#index-HISTTIMEFORMAT' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If this variable is set and not null, its value is used as a format string +for <code>strftime</code> to print the time stamp associated with each history +entry displayed by the <code>history</code> builtin. +If this variable is set, time stamps are written to the history file so +they may be preserved across shell sessions. +This uses the history comment character to distinguish timestamps from +other history lines. +</p> +</dd> +<dt id='index-HOSTFILE'><span><code>HOSTFILE</code><a href='#index-HOSTFILE' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Contains the name of a file in the same format as <samp>/etc/hosts</samp> that +should be read when the shell needs to complete a hostname. +The list of possible hostname completions may be changed while the shell +is running; +the next time hostname completion is attempted after the +value is changed, Bash adds the contents of the new file to the +existing list. +If <code>HOSTFILE</code> is set, but has no value, or does not name a readable file, +Bash attempts to read +<samp>/etc/hosts</samp> to obtain the list of possible hostname completions. +When <code>HOSTFILE</code> is unset, the hostname list is cleared. +</p> +</dd> +<dt id='index-HOSTNAME'><span><code>HOSTNAME</code><a href='#index-HOSTNAME' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The name of the current host. +</p> +</dd> +<dt id='index-HOSTTYPE'><span><code>HOSTTYPE</code><a href='#index-HOSTTYPE' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A string describing the machine Bash is running on. +</p> +</dd> +<dt id='index-IGNOREEOF'><span><code>IGNOREEOF</code><a href='#index-IGNOREEOF' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Controls the action of the shell on receipt of an <code>EOF</code> character +as the sole input. If set, the value denotes the number +of consecutive <code>EOF</code> characters that can be read as the +first character on an input line +before the shell will exit. If the variable exists but does not +have a numeric value, or has no value, then the default is 10. +If the variable does not exist, then <code>EOF</code> signifies the end of +input to the shell. This is only in effect for interactive shells. +</p> +</dd> +<dt id='index-INPUTRC'><span><code>INPUTRC</code><a href='#index-INPUTRC' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The name of the Readline initialization file, overriding the default +of <samp>~/.inputrc</samp>. +</p> +</dd> +<dt id='index-INSIDE_005fEMACS'><span><code>INSIDE_EMACS</code><a href='#index-INSIDE_005fEMACS' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If Bash finds this variable in the environment when the shell +starts, it assumes that the shell is running in an Emacs shell buffer +and may disable line editing depending on the value of <code>TERM</code>. +</p> +</dd> +<dt id='index-LANG-1'><span><code>LANG</code><a href='#index-LANG-1' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Used to determine the locale category for any category not specifically +selected with a variable starting with <code>LC_</code>. +</p> +</dd> +<dt id='index-LC_005fALL'><span><code>LC_ALL</code><a href='#index-LC_005fALL' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This variable overrides the value of <code>LANG</code> and any other +<code>LC_</code> variable specifying a locale category. +</p> +</dd> +<dt id='index-LC_005fCOLLATE'><span><code>LC_COLLATE</code><a href='#index-LC_005fCOLLATE' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This variable determines the collation order used when sorting the +results of filename expansion, and +determines the behavior of range expressions, equivalence classes, +and collating sequences within filename expansion and pattern matching +(see <a href="#Filename-Expansion">Filename Expansion</a>). +</p> +</dd> +<dt id='index-LC_005fCTYPE'><span><code>LC_CTYPE</code><a href='#index-LC_005fCTYPE' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This variable determines the interpretation of characters and the +behavior of character classes within filename expansion and pattern +matching (see <a href="#Filename-Expansion">Filename Expansion</a>). +</p> +</dd> +<dt id='index-LC_005fMESSAGES-1'><span><code>LC_MESSAGES</code><a href='#index-LC_005fMESSAGES-1' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This variable determines the locale used to translate double-quoted +strings preceded by a ‘<samp>$</samp>’ (see <a href="#Locale-Translation">Locale-Specific Translation</a>). +</p> +</dd> +<dt id='index-LC_005fNUMERIC'><span><code>LC_NUMERIC</code><a href='#index-LC_005fNUMERIC' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This variable determines the locale category used for number formatting. +</p> +</dd> +<dt id='index-LC_005fTIME'><span><code>LC_TIME</code><a href='#index-LC_005fTIME' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This variable determines the locale category used for data and time +formatting. +</p> +</dd> +<dt id='index-LINENO'><span><code>LINENO</code><a href='#index-LINENO' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The line number in the script or shell function currently executing. +If <code>LINENO</code> +is unset, it loses its special properties, even if it is +subsequently reset. +</p> +</dd> +<dt id='index-LINES'><span><code>LINES</code><a href='#index-LINES' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Used by the <code>select</code> command to determine the column length +for printing selection lists. +Automatically set if the <code>checkwinsize</code> option is enabled +(see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>), or in an interactive shell upon receipt of a +<code>SIGWINCH</code>. +</p> +</dd> +<dt id='index-MACHTYPE'><span><code>MACHTYPE</code><a href='#index-MACHTYPE' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A string that fully describes the system type on which Bash +is executing, in the standard <small>GNU</small> <var>cpu-company-system</var> format. +</p> +</dd> +<dt id='index-MAILCHECK'><span><code>MAILCHECK</code><a href='#index-MAILCHECK' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>How often (in seconds) that the shell should check for mail in the +files specified in the <code>MAILPATH</code> or <code>MAIL</code> variables. +The default is 60 seconds. When it is time to check +for mail, the shell does so before displaying the primary prompt. +If this variable is unset, or set to a value that is not a number +greater than or equal to zero, the shell disables mail checking. +</p> +</dd> +<dt id='index-MAPFILE'><span><code>MAPFILE</code><a href='#index-MAPFILE' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>An array variable created to hold the text read by the +<code>mapfile</code> builtin when no variable name is supplied. +</p> +</dd> +<dt id='index-OLDPWD'><span><code>OLDPWD</code><a href='#index-OLDPWD' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The previous working directory as set by the <code>cd</code> builtin. +</p> +</dd> +<dt id='index-OPTERR'><span><code>OPTERR</code><a href='#index-OPTERR' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to the value 1, Bash displays error messages +generated by the <code>getopts</code> builtin command. +</p> +</dd> +<dt id='index-OSTYPE'><span><code>OSTYPE</code><a href='#index-OSTYPE' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A string describing the operating system Bash is running on. +</p> +</dd> +<dt id='index-PIPESTATUS'><span><code>PIPESTATUS</code><a href='#index-PIPESTATUS' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>An array variable (see <a href="#Arrays">Arrays</a>) +containing a list of exit status values from the processes +in the most-recently-executed foreground pipeline (which may +contain only a single command). +</p> +</dd> +<dt id='index-POSIXLY_005fCORRECT'><span><code>POSIXLY_CORRECT</code><a href='#index-POSIXLY_005fCORRECT' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If this variable is in the environment when Bash starts, the shell +enters <small>POSIX</small> mode (see <a href="#Bash-POSIX-Mode">Bash POSIX Mode</a>) before reading the +startup files, as if the <samp>--posix</samp> invocation option had been supplied. +If it is set while the shell is running, Bash enables <small>POSIX</small> mode, +as if the command +</p><div class="example"> +<pre class="example"><code>set -o posix</code> +</pre></div> +<p>had been executed. +When the shell enters <small>POSIX</small> mode, it sets this variable if it was +not already set. +</p> +</dd> +<dt id='index-PPID'><span><code>PPID</code><a href='#index-PPID' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The process <small>ID</small> of the shell’s parent process. This variable +is readonly. +</p> +</dd> +<dt id='index-PROMPT_005fCOMMAND'><span><code>PROMPT_COMMAND</code><a href='#index-PROMPT_005fCOMMAND' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If this variable is set, and is an array, +the value of each set element is interpreted as a command to execute +before printing the primary prompt (<code>$PS1</code>). +If this is set but not an array variable, +its value is used as a command to execute instead. +</p> +</dd> +<dt id='index-PROMPT_005fDIRTRIM'><span><code>PROMPT_DIRTRIM</code><a href='#index-PROMPT_005fDIRTRIM' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to a number greater than zero, the value is used as the number of +trailing directory components to retain when expanding the <code>\w</code> and +<code>\W</code> prompt string escapes (see <a href="#Controlling-the-Prompt">Controlling the Prompt</a>). +Characters removed are replaced with an ellipsis. +</p> +</dd> +<dt id='index-PS0'><span><code>PS0</code><a href='#index-PS0' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The value of this parameter is expanded like <code>PS1</code> +and displayed by interactive shells after reading a command +and before the command is executed. +</p> +</dd> +<dt id='index-PS3'><span><code>PS3</code><a href='#index-PS3' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The value of this variable is used as the prompt for the +<code>select</code> command. If this variable is not set, the +<code>select</code> command prompts with ‘<samp>#? </samp>’ +</p> +</dd> +<dt id='index-PS4'><span><code>PS4</code><a href='#index-PS4' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The value of this parameter is expanded like <code>PS1</code> +and the expanded value is the prompt printed before the command line +is echoed when the <samp>-x</samp> option is set (see <a href="#The-Set-Builtin">The Set Builtin</a>). +The first character of the expanded value is replicated multiple times, +as necessary, to indicate multiple levels of indirection. +The default is ‘<samp>+ </samp>’. +</p> +</dd> +<dt id='index-PWD'><span><code>PWD</code><a href='#index-PWD' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The current working directory as set by the <code>cd</code> builtin. +</p> +</dd> +<dt id='index-RANDOM'><span><code>RANDOM</code><a href='#index-RANDOM' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Each time this parameter is referenced, it expands to a random integer +between 0 and 32767. Assigning a value to this +variable seeds the random number generator. +If <code>RANDOM</code> +is unset, it loses its special properties, even if it is +subsequently reset. +</p> +</dd> +<dt id='index-READLINE_005fARGUMENT'><span><code>READLINE_ARGUMENT</code><a href='#index-READLINE_005fARGUMENT' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Any numeric argument given to a Readline command that was defined using +‘<samp>bind -x</samp>’ (see <a href="#Bash-Builtins">Bash Builtin Commands</a> +when it was invoked. +</p> +</dd> +<dt id='index-READLINE_005fLINE'><span><code>READLINE_LINE</code><a href='#index-READLINE_005fLINE' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The contents of the Readline line buffer, for use +with ‘<samp>bind -x</samp>’ (see <a href="#Bash-Builtins">Bash Builtin Commands</a>). +</p> +</dd> +<dt id='index-READLINE_005fMARK'><span><code>READLINE_MARK</code><a href='#index-READLINE_005fMARK' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The position of the <em>mark</em> (saved insertion point) in the +Readline line buffer, for use +with ‘<samp>bind -x</samp>’ (see <a href="#Bash-Builtins">Bash Builtin Commands</a>). +The characters between the insertion point and the mark are often +called the <em>region</em>. +</p> +</dd> +<dt id='index-READLINE_005fPOINT'><span><code>READLINE_POINT</code><a href='#index-READLINE_005fPOINT' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The position of the insertion point in the Readline line buffer, for use +with ‘<samp>bind -x</samp>’ (see <a href="#Bash-Builtins">Bash Builtin Commands</a>). +</p> +</dd> +<dt id='index-REPLY'><span><code>REPLY</code><a href='#index-REPLY' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The default variable for the <code>read</code> builtin. +</p> +</dd> +<dt id='index-SECONDS'><span><code>SECONDS</code><a href='#index-SECONDS' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This variable expands to the number of seconds since the shell was started. +Assignment to this variable resets the count to the value assigned, and the +expanded value becomes the value assigned plus the number of seconds +since the assignment. +The number of seconds at shell invocation and the current time are always +determined by querying the system clock. +If <code>SECONDS</code> +is unset, it loses its special properties, +even if it is subsequently reset. +</p> +</dd> +<dt id='index-SHELL'><span><code>SHELL</code><a href='#index-SHELL' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This environment variable expands to the full pathname to the shell. +If it is not set when the shell starts, +Bash assigns to it the full pathname of the current user’s login shell. +</p> +</dd> +<dt id='index-SHELLOPTS'><span><code>SHELLOPTS</code><a href='#index-SHELLOPTS' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A colon-separated list of enabled shell options. Each word in +the list is a valid argument for the <samp>-o</samp> option to the +<code>set</code> builtin command (see <a href="#The-Set-Builtin">The Set Builtin</a>). +The options appearing in <code>SHELLOPTS</code> are those reported +as ‘<samp>on</samp>’ by ‘<samp>set -o</samp>’. +If this variable is in the environment when Bash +starts up, each shell option in the list will be enabled before +reading any startup files. This variable is readonly. +</p> +</dd> +<dt id='index-SHLVL'><span><code>SHLVL</code><a href='#index-SHLVL' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Incremented by one each time a new instance of Bash is started. This is +intended to be a count of how deeply your Bash shells are nested. +</p> +</dd> +<dt id='index-SRANDOM'><span><code>SRANDOM</code><a href='#index-SRANDOM' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This variable expands to a 32-bit pseudo-random number each time it is +referenced. The random number generator is not linear on systems that +support <samp>/dev/urandom</samp> or <code>arc4random</code>, so each returned number +has no relationship to the numbers preceding it. +The random number generator cannot be seeded, so assignments to this +variable have no effect. +If <code>SRANDOM</code> +is unset, it loses its special properties, +even if it is subsequently reset. +</p> +</dd> +<dt id='index-TIMEFORMAT'><span><code>TIMEFORMAT</code><a href='#index-TIMEFORMAT' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The value of this parameter is used as a format string specifying +how the timing information for pipelines prefixed with the <code>time</code> +reserved word should be displayed. +The ‘<samp>%</samp>’ character introduces an +escape sequence that is expanded to a time value or other +information. +The escape sequences and their meanings are as +follows; the braces denote optional portions. +</p> +<dl compact="compact"> +<dt><span><code>%%</code></span></dt> +<dd><p>A literal ‘<samp>%</samp>’. +</p> +</dd> +<dt><span><code>%[<var>p</var>][l]R</code></span></dt> +<dd><p>The elapsed time in seconds. +</p> +</dd> +<dt><span><code>%[<var>p</var>][l]U</code></span></dt> +<dd><p>The number of CPU seconds spent in user mode. +</p> +</dd> +<dt><span><code>%[<var>p</var>][l]S</code></span></dt> +<dd><p>The number of CPU seconds spent in system mode. +</p> +</dd> +<dt><span><code>%P</code></span></dt> +<dd><p>The CPU percentage, computed as (%U + %S) / %R. +</p></dd> +</dl> + +<p>The optional <var>p</var> is a digit specifying the precision, the number of +fractional digits after a decimal point. +A value of 0 causes no decimal point or fraction to be output. +At most three places after the decimal point may be specified; values +of <var>p</var> greater than 3 are changed to 3. +If <var>p</var> is not specified, the value 3 is used. +</p> +<p>The optional <code>l</code> specifies a longer format, including minutes, of +the form <var>MM</var>m<var>SS</var>.<var>FF</var>s. +The value of <var>p</var> determines whether or not the fraction is included. +</p> +<p>If this variable is not set, Bash acts as if it had the value +</p><div class="example"> +<pre class="example"><code>$'\nreal\t%3lR\nuser\t%3lU\nsys\t%3lS'</code> +</pre></div> +<p>If the value is null, no timing information is displayed. +A trailing newline is added when the format string is displayed. +</p> +</dd> +<dt id='index-TMOUT'><span><code>TMOUT</code><a href='#index-TMOUT' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to a value greater than zero, <code>TMOUT</code> is treated as the +default timeout for the <code>read</code> builtin (see <a href="#Bash-Builtins">Bash Builtin Commands</a>). +The <code>select</code> command (see <a href="#Conditional-Constructs">Conditional Constructs</a>) terminates +if input does not arrive after <code>TMOUT</code> seconds when input is coming +from a terminal. +</p> +<p>In an interactive shell, the value is interpreted as +the number of seconds to wait for a line of input after issuing +the primary prompt. +Bash +terminates after waiting for that number of seconds if a complete +line of input does not arrive. +</p> +</dd> +<dt id='index-TMPDIR'><span><code>TMPDIR</code><a href='#index-TMPDIR' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set, Bash uses its value as the name of a directory in which +Bash creates temporary files for the shell’s use. +</p> +</dd> +<dt id='index-UID'><span><code>UID</code><a href='#index-UID' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The numeric real user id of the current user. This variable is readonly. +</p> +</dd> +</dl> + +<hr> +</div> +</div> +<div class="chapter" id="Bash-Features"> +<div class="header"> +<p> +Next: <a href="#Job-Control" accesskey="n" rel="next">Job Control</a>, Previous: <a href="#Shell-Variables" accesskey="p" rel="prev">Shell Variables</a>, Up: <a href="#Top" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Bash-Features-2"></span><h2 class="chapter">6 Bash Features</h2> + +<p>This chapter describes features unique to Bash. +</p> + +<ul class="section-toc"> +<li><a href="#Invoking-Bash" accesskey="1">Invoking Bash</a></li> +<li><a href="#Bash-Startup-Files" accesskey="2">Bash Startup Files</a></li> +<li><a href="#Interactive-Shells" accesskey="3">Interactive Shells</a></li> +<li><a href="#Bash-Conditional-Expressions" accesskey="4">Bash Conditional Expressions</a></li> +<li><a href="#Shell-Arithmetic" accesskey="5">Shell Arithmetic</a></li> +<li><a href="#Aliases" accesskey="6">Aliases</a></li> +<li><a href="#Arrays" accesskey="7">Arrays</a></li> +<li><a href="#The-Directory-Stack" accesskey="8">The Directory Stack</a></li> +<li><a href="#Controlling-the-Prompt" accesskey="9">Controlling the Prompt</a></li> +<li><a href="#The-Restricted-Shell">The Restricted Shell</a></li> +<li><a href="#Bash-POSIX-Mode">Bash POSIX Mode</a></li> +<li><a href="#Shell-Compatibility-Mode">Shell Compatibility Mode</a></li> +</ul> +<hr> +<div class="section" id="Invoking-Bash"> +<div class="header"> +<p> +Next: <a href="#Bash-Startup-Files" accesskey="n" rel="next">Bash Startup Files</a>, Up: <a href="#Bash-Features" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Invoking-Bash-1"></span><h3 class="section">6.1 Invoking Bash</h3> + +<div class="example"> +<pre class="example">bash [long-opt] [-ir] [-abefhkmnptuvxdBCDHP] [-o <var>option</var>] + [-O <var>shopt_option</var>] [<var>argument</var> …] +bash [long-opt] [-abefhkmnptuvxdBCDHP] [-o <var>option</var>] + [-O <var>shopt_option</var>] -c <var>string</var> [<var>argument</var> …] +bash [long-opt] -s [-abefhkmnptuvxdBCDHP] [-o <var>option</var>] + [-O <var>shopt_option</var>] [<var>argument</var> …] +</pre></div> + +<p>All of the single-character options used with the <code>set</code> builtin +(see <a href="#The-Set-Builtin">The Set Builtin</a>) can be used as options when the shell is invoked. +In addition, there are several multi-character +options that you can use. These options must appear on the command +line before the single-character options to be recognized. +</p> +<dl compact="compact"> +<dt><span><code>--debugger</code></span></dt> +<dd><p>Arrange for the debugger profile to be executed before the shell +starts. Turns on extended debugging mode (see <a href="#The-Shopt-Builtin">The Shopt Builtin</a> +for a description of the <code>extdebug</code> option to the <code>shopt</code> +builtin). +</p> +</dd> +<dt><span><code>--dump-po-strings</code></span></dt> +<dd><p>A list of all double-quoted strings preceded by ‘<samp>$</samp>’ +is printed on the standard output +in the <small>GNU</small> <code>gettext</code> PO (portable object) file format. +Equivalent to <samp>-D</samp> except for the output format. +</p> +</dd> +<dt><span><code>--dump-strings</code></span></dt> +<dd><p>Equivalent to <samp>-D</samp>. +</p> +</dd> +<dt><span><code>--help</code></span></dt> +<dd><p>Display a usage message on standard output and exit successfully. +</p> +</dd> +<dt><span><code>--init-file <var>filename</var></code></span></dt> +<dt><span><code>--rcfile <var>filename</var></code></span></dt> +<dd><p>Execute commands from <var>filename</var> (instead of <samp>~/.bashrc</samp>) +in an interactive shell. +</p> +</dd> +<dt><span><code>--login</code></span></dt> +<dd><p>Equivalent to <samp>-l</samp>. +</p> +</dd> +<dt><span><code>--noediting</code></span></dt> +<dd><p>Do not use the <small>GNU</small> Readline library (see <a href="#Command-Line-Editing">Command Line Editing</a>) +to read command lines when the shell is interactive. +</p> +</dd> +<dt><span><code>--noprofile</code></span></dt> +<dd><p>Don’t load the system-wide startup file <samp>/etc/profile</samp> +or any of the personal initialization files +<samp>~/.bash_profile</samp>, <samp>~/.bash_login</samp>, or <samp>~/.profile</samp> +when Bash is invoked as a login shell. +</p> +</dd> +<dt><span><code>--norc</code></span></dt> +<dd><p>Don’t read the <samp>~/.bashrc</samp> initialization file in an +interactive shell. This is on by default if the shell is +invoked as <code>sh</code>. +</p> +</dd> +<dt><span><code>--posix</code></span></dt> +<dd><p>Change the behavior of Bash where the default operation differs +from the <small>POSIX</small> standard to match the standard. This +is intended to make Bash behave as a strict superset of that +standard. See <a href="#Bash-POSIX-Mode">Bash POSIX Mode</a>, for a description of the Bash +<small>POSIX</small> mode. +</p> +</dd> +<dt><span><code>--restricted</code></span></dt> +<dd><p>Make the shell a restricted shell (see <a href="#The-Restricted-Shell">The Restricted Shell</a>). +</p> +</dd> +<dt><span><code>--verbose</code></span></dt> +<dd><p>Equivalent to <samp>-v</samp>. Print shell input lines as they’re read. +</p> +</dd> +<dt><span><code>--version</code></span></dt> +<dd><p>Show version information for this instance of +Bash on the standard output and exit successfully. +</p></dd> +</dl> + +<p>There are several single-character options that may be supplied at +invocation which are not available with the <code>set</code> builtin. +</p> +<dl compact="compact"> +<dt><span><code>-c</code></span></dt> +<dd><p>Read and execute commands from the first non-option argument +<var>command_string</var>, then exit. +If there are arguments after the <var>command_string</var>, +the first argument is assigned to <code>$0</code> +and any remaining arguments are assigned to the positional parameters. +The assignment to <code>$0</code> sets the name of the shell, which is used +in warning and error messages. +</p> +</dd> +<dt><span><code>-i</code></span></dt> +<dd><p>Force the shell to run interactively. Interactive shells are +described in <a href="#Interactive-Shells">Interactive Shells</a>. +</p> +</dd> +<dt><span><code>-l</code></span></dt> +<dd><p>Make this shell act as if it had been directly invoked by login. +When the shell is interactive, this is equivalent to starting a +login shell with ‘<samp>exec -l bash</samp>’. +When the shell is not interactive, the login shell startup files will +be executed. +‘<samp>exec bash -l</samp>’ or ‘<samp>exec bash --login</samp>’ +will replace the current shell with a Bash login shell. +See <a href="#Bash-Startup-Files">Bash Startup Files</a>, for a description of the special behavior +of a login shell. +</p> +</dd> +<dt><span><code>-r</code></span></dt> +<dd><p>Make the shell a restricted shell (see <a href="#The-Restricted-Shell">The Restricted Shell</a>). +</p> +</dd> +<dt><span><code>-s</code></span></dt> +<dd><p>If this option is present, or if no arguments remain after option +processing, then commands are read from the standard input. +This option allows the positional parameters to be set +when invoking an interactive shell or when reading input +through a pipe. +</p> +</dd> +<dt><span><code>-D</code></span></dt> +<dd><p>A list of all double-quoted strings preceded by ‘<samp>$</samp>’ +is printed on the standard output. +These are the strings that +are subject to language translation when the current locale +is not <code>C</code> or <code>POSIX</code> (see <a href="#Locale-Translation">Locale-Specific Translation</a>). +This implies the <samp>-n</samp> option; no commands will be executed. +</p> +</dd> +<dt><span><code>[-+]O [<var>shopt_option</var>]</code></span></dt> +<dd><p><var>shopt_option</var> is one of the shell options accepted by the +<code>shopt</code> builtin (see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>). +If <var>shopt_option</var> is present, <samp>-O</samp> sets the value of that option; +<samp>+O</samp> unsets it. +If <var>shopt_option</var> is not supplied, the names and values of the shell +options accepted by <code>shopt</code> are printed on the standard output. +If the invocation option is <samp>+O</samp>, the output is displayed in a format +that may be reused as input. +</p> +</dd> +<dt><span><code>--</code></span></dt> +<dd><p>A <code>--</code> signals the end of options and disables further option +processing. +Any arguments after the <code>--</code> are treated as filenames and arguments. +</p></dd> +</dl> + +<span id="index-login-shell"></span> +<p>A <em>login</em> shell is one whose first character of argument zero is +‘<samp>-</samp>’, or one invoked with the <samp>--login</samp> option. +</p> +<span id="index-interactive-shell"></span> +<p>An <em>interactive</em> shell is one started without non-option arguments, +unless <samp>-s</samp> is specified, +without specifying the <samp>-c</samp> option, and whose input and output are both +connected to terminals (as determined by <code>isatty(3)</code>), or one +started with the <samp>-i</samp> option. See <a href="#Interactive-Shells">Interactive Shells</a>, for more +information. +</p> +<p>If arguments remain after option processing, and neither the +<samp>-c</samp> nor the <samp>-s</samp> +option has been supplied, the first argument is assumed to +be the name of a file containing shell commands (see <a href="#Shell-Scripts">Shell Scripts</a>). +When Bash is invoked in this fashion, <code>$0</code> +is set to the name of the file, and the positional parameters +are set to the remaining arguments. +Bash reads and executes commands from this file, then exits. +Bash’s exit status is the exit status of the last command executed +in the script. If no commands are executed, the exit status is 0. +</p> +<hr> +</div> +<div class="section" id="Bash-Startup-Files"> +<div class="header"> +<p> +Next: <a href="#Interactive-Shells" accesskey="n" rel="next">Interactive Shells</a>, Previous: <a href="#Invoking-Bash" accesskey="p" rel="prev">Invoking Bash</a>, Up: <a href="#Bash-Features" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Bash-Startup-Files-1"></span><h3 class="section">6.2 Bash Startup Files</h3> +<span id="index-startup-files"></span> + +<p>This section describes how Bash executes its startup files. +If any of the files exist but cannot be read, Bash reports an error. +Tildes are expanded in filenames as described above under +Tilde Expansion (see <a href="#Tilde-Expansion">Tilde Expansion</a>). +</p> +<p>Interactive shells are described in <a href="#Interactive-Shells">Interactive Shells</a>. +</p> +<span id="Invoked-as-an-interactive-login-shell_002c-or-with-_002d_002dlogin"></span><h4 class="subsubheading">Invoked as an interactive login shell, or with <samp>--login</samp></h4> + +<p>When Bash is invoked as an interactive login shell, or as a +non-interactive shell with the <samp>--login</samp> option, it first reads and +executes commands from the file <samp>/etc/profile</samp>, if that file exists. +After reading that file, it looks for <samp>~/.bash_profile</samp>, +<samp>~/.bash_login</samp>, and <samp>~/.profile</samp>, in that order, and reads +and executes commands from the first one that exists and is readable. +The <samp>--noprofile</samp> option may be used when the shell is started to +inhibit this behavior. +</p> +<p>When an interactive login shell exits, +or a non-interactive login shell executes the <code>exit</code> builtin command, +Bash reads and executes commands from +the file <samp>~/.bash_logout</samp>, if it exists. +</p> +<span id="Invoked-as-an-interactive-non_002dlogin-shell"></span><h4 class="subsubheading">Invoked as an interactive non-login shell</h4> + +<p>When an interactive shell that is not a login shell is started, Bash +reads and executes commands from <samp>~/.bashrc</samp>, if that file exists. +This may be inhibited by using the <samp>--norc</samp> option. +The <samp>--rcfile <var>file</var></samp> option will force Bash to read and +execute commands from <var>file</var> instead of <samp>~/.bashrc</samp>. +</p> +<p>So, typically, your <samp>~/.bash_profile</samp> contains the line +</p><div class="example"> +<pre class="example"><code>if [ -f ~/.bashrc ]; then . ~/.bashrc; fi</code> +</pre></div> +<p>after (or before) any login-specific initializations. +</p> +<span id="Invoked-non_002dinteractively"></span><h4 class="subsubheading">Invoked non-interactively</h4> + +<p>When Bash is started non-interactively, to run a shell script, +for example, it looks for the variable <code>BASH_ENV</code> in the environment, +expands its value if it appears there, and uses the expanded value as +the name of a file to read and execute. Bash behaves as if the +following command were executed: +</p><div class="example"> +<pre class="example"><code>if [ -n "$BASH_ENV" ]; then . "$BASH_ENV"; fi</code> +</pre></div> +<p>but the value of the <code>PATH</code> variable is not used to search for the +filename. +</p> +<p>As noted above, if a non-interactive shell is invoked with the +<samp>--login</samp> option, Bash attempts to read and execute commands from the +login shell startup files. +</p> +<span id="Invoked-with-name-sh"></span><h4 class="subsubheading">Invoked with name <code>sh</code></h4> + +<p>If Bash is invoked with the name <code>sh</code>, it tries to mimic the +startup behavior of historical versions of <code>sh</code> as closely as +possible, while conforming to the <small>POSIX</small> standard as well. +</p> +<p>When invoked as an interactive login shell, or as a non-interactive +shell with the <samp>--login</samp> option, it first attempts to read +and execute commands from <samp>/etc/profile</samp> and <samp>~/.profile</samp>, in +that order. +The <samp>--noprofile</samp> option may be used to inhibit this behavior. +When invoked as an interactive shell with the name <code>sh</code>, Bash +looks for the variable <code>ENV</code>, expands its value if it is defined, +and uses the expanded value as the name of a file to read and execute. +Since a shell invoked as <code>sh</code> does not attempt to read and execute +commands from any other startup files, the <samp>--rcfile</samp> option has +no effect. +A non-interactive shell invoked with the name <code>sh</code> does not attempt +to read any other startup files. +</p> +<p>When invoked as <code>sh</code>, Bash enters <small>POSIX</small> mode after +the startup files are read. +</p> +<span id="Invoked-in-POSIX-mode"></span><h4 class="subsubheading">Invoked in <small>POSIX</small> mode</h4> + +<p>When Bash is started in <small>POSIX</small> mode, as with the +<samp>--posix</samp> command line option, it follows the <small>POSIX</small> standard +for startup files. +In this mode, interactive shells expand the <code>ENV</code> variable +and commands are read and executed from the file whose name is the +expanded value. +No other startup files are read. +</p> +<span id="Invoked-by-remote-shell-daemon"></span><h4 class="subsubheading">Invoked by remote shell daemon</h4> + +<p>Bash attempts to determine when it is being run with its standard input +connected to a network connection, as when executed by +the historical remote shell daemon, usually <code>rshd</code>, +or the secure shell daemon <code>sshd</code>. +If Bash +determines it is being run non-interactively in this fashion, +it reads and executes commands from <samp>~/.bashrc</samp>, if that +file exists and is readable. +It will not do this if invoked as <code>sh</code>. +The <samp>--norc</samp> option may be used to inhibit this behavior, and the +<samp>--rcfile</samp> option may be used to force another file to be read, but +neither <code>rshd</code> nor <code>sshd</code> generally invoke the shell with those +options or allow them to be specified. +</p> +<span id="Invoked-with-unequal-effective-and-real-UID_002fGIDs"></span><h4 class="subsubheading">Invoked with unequal effective and real <small>UID/GID</small>s</h4> + +<p>If Bash is started with the effective user (group) id not equal to the +real user (group) id, and the <samp>-p</samp> option is not supplied, no startup +files are read, shell functions are not inherited from the environment, +the <code>SHELLOPTS</code>, <code>BASHOPTS</code>, <code>CDPATH</code>, and <code>GLOBIGNORE</code> +variables, if they appear in the environment, are ignored, and the effective +user id is set to the real user id. +If the <samp>-p</samp> option is supplied at invocation, the startup behavior is +the same, but the effective user id is not reset. +</p> +<hr> +</div> +<div class="section" id="Interactive-Shells"> +<div class="header"> +<p> +Next: <a href="#Bash-Conditional-Expressions" accesskey="n" rel="next">Bash Conditional Expressions</a>, Previous: <a href="#Bash-Startup-Files" accesskey="p" rel="prev">Bash Startup Files</a>, Up: <a href="#Bash-Features" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Interactive-Shells-1"></span><h3 class="section">6.3 Interactive Shells</h3> +<span id="index-interactive-shell-1"></span> +<span id="index-shell_002c-interactive"></span> + + +<ul class="section-toc"> +<li><a href="#What-is-an-Interactive-Shell_003f" accesskey="1">What is an Interactive Shell?</a></li> +<li><a href="#Is-this-Shell-Interactive_003f" accesskey="2">Is this Shell Interactive?</a></li> +<li><a href="#Interactive-Shell-Behavior" accesskey="3">Interactive Shell Behavior</a></li> +</ul> +<hr> +<div class="subsection" id="What-is-an-Interactive-Shell_003f"> +<div class="header"> +<p> +Next: <a href="#Is-this-Shell-Interactive_003f" accesskey="n" rel="next">Is this Shell Interactive?</a>, Up: <a href="#Interactive-Shells" accesskey="u" rel="up">Interactive Shells</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="What-is-an-Interactive-Shell_003f-1"></span><h4 class="subsection">6.3.1 What is an Interactive Shell?</h4> + +<p>An interactive shell +is one started without non-option arguments +(unless <samp>-s</samp> is specified) +and without specifying the <samp>-c</samp> option, +whose input and error output are both +connected to terminals (as determined by <code>isatty(3)</code>), +or one started with the <samp>-i</samp> option. +</p> +<p>An interactive shell generally reads from and writes to a user’s +terminal. +</p> +<p>The <samp>-s</samp> invocation option may be used to set the positional parameters +when an interactive shell is started. +</p> +<hr> +</div> +<div class="subsection" id="Is-this-Shell-Interactive_003f"> +<div class="header"> +<p> +Next: <a href="#Interactive-Shell-Behavior" accesskey="n" rel="next">Interactive Shell Behavior</a>, Previous: <a href="#What-is-an-Interactive-Shell_003f" accesskey="p" rel="prev">What is an Interactive Shell?</a>, Up: <a href="#Interactive-Shells" accesskey="u" rel="up">Interactive Shells</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Is-this-Shell-Interactive_003f-1"></span><h4 class="subsection">6.3.2 Is this Shell Interactive?</h4> + +<p>To determine within a startup script whether or not Bash is +running interactively, +test the value of the ‘<samp>-</samp>’ special parameter. +It contains <code>i</code> when the shell is interactive. For example: +</p> +<div class="example"> +<pre class="example">case "$-" in +*i*) echo This shell is interactive ;; +*) echo This shell is not interactive ;; +esac +</pre></div> + +<p>Alternatively, startup scripts may examine the variable +<code>PS1</code>; it is unset in non-interactive shells, and set in +interactive shells. Thus: +</p> +<div class="example"> +<pre class="example">if [ -z "$PS1" ]; then + echo This shell is not interactive +else + echo This shell is interactive +fi +</pre></div> + +<hr> +</div> +<div class="subsection" id="Interactive-Shell-Behavior"> +<div class="header"> +<p> +Previous: <a href="#Is-this-Shell-Interactive_003f" accesskey="p" rel="prev">Is this Shell Interactive?</a>, Up: <a href="#Interactive-Shells" accesskey="u" rel="up">Interactive Shells</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Interactive-Shell-Behavior-1"></span><h4 class="subsection">6.3.3 Interactive Shell Behavior</h4> + +<p>When the shell is running interactively, it changes its behavior in +several ways. +</p> +<ol> +<li> Startup files are read and executed as described in <a href="#Bash-Startup-Files">Bash Startup Files</a>. + +</li><li> Job Control (see <a href="#Job-Control">Job Control</a>) is enabled by default. When job +control is in effect, Bash ignores the keyboard-generated job control +signals <code>SIGTTIN</code>, <code>SIGTTOU</code>, and <code>SIGTSTP</code>. + +</li><li> Bash expands and displays <code>PS1</code> before reading the first line +of a command, and expands and displays <code>PS2</code> before reading the +second and subsequent lines of a multi-line command. +Bash expands and displays <code>PS0</code> after it reads a command but before +executing it. +See <a href="#Controlling-the-Prompt">Controlling the Prompt</a>, for a complete list of prompt +string escape sequences. + +</li><li> Bash executes the values of the set elements of the <code>PROMPT_COMMAND</code> +array variable as commands before printing the primary prompt, <code>$PS1</code> +(see <a href="#Bash-Variables">Bash Variables</a>). + +</li><li> Readline (see <a href="#Command-Line-Editing">Command Line Editing</a>) is used to read commands from +the user’s terminal. + +</li><li> Bash inspects the value of the <code>ignoreeof</code> option to <code>set -o</code> +instead of exiting immediately when it receives an <code>EOF</code> on its +standard input when reading a command (see <a href="#The-Set-Builtin">The Set Builtin</a>). + +</li><li> Command history (see <a href="#Bash-History-Facilities">Bash History Facilities</a>) +and history expansion (see <a href="#History-Interaction">History Expansion</a>) +are enabled by default. +Bash will save the command history to the file named by <code>$HISTFILE</code> +when a shell with history enabled exits. + +</li><li> Alias expansion (see <a href="#Aliases">Aliases</a>) is performed by default. + +</li><li> In the absence of any traps, Bash ignores <code>SIGTERM</code> +(see <a href="#Signals">Signals</a>). + +</li><li> In the absence of any traps, <code>SIGINT</code> is caught and handled +(see <a href="#Signals">Signals</a>). +<code>SIGINT</code> will interrupt some shell builtins. + +</li><li> An interactive login shell sends a <code>SIGHUP</code> to all jobs on exit +if the <code>huponexit</code> shell option has been enabled (see <a href="#Signals">Signals</a>). + +</li><li> The <samp>-n</samp> invocation option is ignored, and ‘<samp>set -n</samp>’ has +no effect (see <a href="#The-Set-Builtin">The Set Builtin</a>). + +</li><li> Bash will check for mail periodically, depending on the values of the +<code>MAIL</code>, <code>MAILPATH</code>, and <code>MAILCHECK</code> shell variables +(see <a href="#Bash-Variables">Bash Variables</a>). + +</li><li> Expansion errors due to references to unbound shell variables after +‘<samp>set -u</samp>’ has been enabled will not cause the shell to exit +(see <a href="#The-Set-Builtin">The Set Builtin</a>). + +</li><li> The shell will not exit on expansion errors caused by <var>var</var> being unset +or null in <code>${<var>var</var>:?<var>word</var>}</code> expansions +(see <a href="#Shell-Parameter-Expansion">Shell Parameter Expansion</a>). + +</li><li> Redirection errors encountered by shell builtins will not cause the +shell to exit. + +</li><li> When running in <small>POSIX</small> mode, a special builtin returning an error +status will not cause the shell to exit (see <a href="#Bash-POSIX-Mode">Bash POSIX Mode</a>). + +</li><li> A failed <code>exec</code> will not cause the shell to exit +(see <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>). + +</li><li> Parser syntax errors will not cause the shell to exit. + +</li><li> If the <code>cdspell</code> shell option is enabled, the shell will attempt +simple spelling correction for directory arguments to the <code>cd</code> +builtin (see the description of the <code>cdspell</code> +option to the <code>shopt</code> builtin in <a href="#The-Shopt-Builtin">The Shopt Builtin</a>). +The <code>cdspell</code> option is only effective in interactive shells. + +</li><li> The shell will check the value of the <code>TMOUT</code> variable and exit +if a command is not read within the specified number of seconds after +printing <code>$PS1</code> (see <a href="#Bash-Variables">Bash Variables</a>). + +</li></ol> + +<hr> +</div> +</div> +<div class="section" id="Bash-Conditional-Expressions"> +<div class="header"> +<p> +Next: <a href="#Shell-Arithmetic" accesskey="n" rel="next">Shell Arithmetic</a>, Previous: <a href="#Interactive-Shells" accesskey="p" rel="prev">Interactive Shells</a>, Up: <a href="#Bash-Features" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Bash-Conditional-Expressions-1"></span><h3 class="section">6.4 Bash Conditional Expressions</h3> +<span id="index-expressions_002c-conditional"></span> + +<p>Conditional expressions are used by the <code>[[</code> compound command +(see <a href="#Conditional-Constructs">Conditional Constructs</a>) +and the <code>test</code> and <code>[</code> builtin commands +(see <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>). +The <code>test</code> +and <code>[</code> commands determine their behavior based on the number +of arguments; see the descriptions of those commands for any other +command-specific actions. +</p> +<p>Expressions may be unary or binary, +and are formed from the following primaries. +Unary expressions are often used to examine the status of a file. +There are string operators and numeric comparison operators as well. +Bash handles several filenames specially when they are used in +expressions. +If the operating system on which Bash is running provides these +special files, Bash will use them; otherwise it will emulate them +internally with this behavior: +If the <var>file</var> argument to one of the primaries is of the form +<samp>/dev/fd/<var>N</var></samp>, then file descriptor <var>N</var> is checked. +If the <var>file</var> argument to one of the primaries is one of +<samp>/dev/stdin</samp>, <samp>/dev/stdout</samp>, or <samp>/dev/stderr</samp>, file +descriptor 0, 1, or 2, respectively, is checked. +</p> +<p>When used with <code>[[</code>, the ‘<samp><</samp>’ and ‘<samp>></samp>’ operators sort +lexicographically using the current locale. +The <code>test</code> command uses ASCII ordering. +</p> +<p>Unless otherwise specified, primaries that operate on files follow symbolic +links and operate on the target of the link, rather than the link itself. +</p> +<dl compact="compact"> +<dt><span><code>-a <var>file</var></code></span></dt> +<dd><p>True if <var>file</var> exists. +</p> +</dd> +<dt><span><code>-b <var>file</var></code></span></dt> +<dd><p>True if <var>file</var> exists and is a block special file. +</p> +</dd> +<dt><span><code>-c <var>file</var></code></span></dt> +<dd><p>True if <var>file</var> exists and is a character special file. +</p> +</dd> +<dt><span><code>-d <var>file</var></code></span></dt> +<dd><p>True if <var>file</var> exists and is a directory. +</p> +</dd> +<dt><span><code>-e <var>file</var></code></span></dt> +<dd><p>True if <var>file</var> exists. +</p> +</dd> +<dt><span><code>-f <var>file</var></code></span></dt> +<dd><p>True if <var>file</var> exists and is a regular file. +</p> +</dd> +<dt><span><code>-g <var>file</var></code></span></dt> +<dd><p>True if <var>file</var> exists and its set-group-id bit is set. +</p> +</dd> +<dt><span><code>-h <var>file</var></code></span></dt> +<dd><p>True if <var>file</var> exists and is a symbolic link. +</p> +</dd> +<dt><span><code>-k <var>file</var></code></span></dt> +<dd><p>True if <var>file</var> exists and its "sticky" bit is set. +</p> +</dd> +<dt><span><code>-p <var>file</var></code></span></dt> +<dd><p>True if <var>file</var> exists and is a named pipe (FIFO). +</p> +</dd> +<dt><span><code>-r <var>file</var></code></span></dt> +<dd><p>True if <var>file</var> exists and is readable. +</p> +</dd> +<dt><span><code>-s <var>file</var></code></span></dt> +<dd><p>True if <var>file</var> exists and has a size greater than zero. +</p> +</dd> +<dt><span><code>-t <var>fd</var></code></span></dt> +<dd><p>True if file descriptor <var>fd</var> is open and refers to a terminal. +</p> +</dd> +<dt><span><code>-u <var>file</var></code></span></dt> +<dd><p>True if <var>file</var> exists and its set-user-id bit is set. +</p> +</dd> +<dt><span><code>-w <var>file</var></code></span></dt> +<dd><p>True if <var>file</var> exists and is writable. +</p> +</dd> +<dt><span><code>-x <var>file</var></code></span></dt> +<dd><p>True if <var>file</var> exists and is executable. +</p> +</dd> +<dt><span><code>-G <var>file</var></code></span></dt> +<dd><p>True if <var>file</var> exists and is owned by the effective group id. +</p> +</dd> +<dt><span><code>-L <var>file</var></code></span></dt> +<dd><p>True if <var>file</var> exists and is a symbolic link. +</p> +</dd> +<dt><span><code>-N <var>file</var></code></span></dt> +<dd><p>True if <var>file</var> exists and has been modified since it was last read. +</p> +</dd> +<dt><span><code>-O <var>file</var></code></span></dt> +<dd><p>True if <var>file</var> exists and is owned by the effective user id. +</p> +</dd> +<dt><span><code>-S <var>file</var></code></span></dt> +<dd><p>True if <var>file</var> exists and is a socket. +</p> +</dd> +<dt><span><code><var>file1</var> -ef <var>file2</var></code></span></dt> +<dd><p>True if <var>file1</var> and <var>file2</var> refer to the same device and +inode numbers. +</p> +</dd> +<dt><span><code><var>file1</var> -nt <var>file2</var></code></span></dt> +<dd><p>True if <var>file1</var> is newer (according to modification date) +than <var>file2</var>, or if <var>file1</var> exists and <var>file2</var> does not. +</p> +</dd> +<dt><span><code><var>file1</var> -ot <var>file2</var></code></span></dt> +<dd><p>True if <var>file1</var> is older than <var>file2</var>, +or if <var>file2</var> exists and <var>file1</var> does not. +</p> +</dd> +<dt><span><code>-o <var>optname</var></code></span></dt> +<dd><p>True if the shell option <var>optname</var> is enabled. +The list of options appears in the description of the <samp>-o</samp> +option to the <code>set</code> builtin (see <a href="#The-Set-Builtin">The Set Builtin</a>). +</p> +</dd> +<dt><span><code>-v <var>varname</var></code></span></dt> +<dd><p>True if the shell variable <var>varname</var> is set (has been assigned a value). +</p> +</dd> +<dt><span><code>-R <var>varname</var></code></span></dt> +<dd><p>True if the shell variable <var>varname</var> is set and is a name reference. +</p> +</dd> +<dt><span><code>-z <var>string</var></code></span></dt> +<dd><p>True if the length of <var>string</var> is zero. +</p> +</dd> +<dt><span><code>-n <var>string</var></code></span></dt> +<dt><span><code><var>string</var></code></span></dt> +<dd><p>True if the length of <var>string</var> is non-zero. +</p> +</dd> +<dt><span><code><var>string1</var> == <var>string2</var></code></span></dt> +<dt><span><code><var>string1</var> = <var>string2</var></code></span></dt> +<dd><p>True if the strings are equal. +When used with the <code>[[</code> command, this performs pattern matching as +described above (see <a href="#Conditional-Constructs">Conditional Constructs</a>). +</p> +<p>‘<samp>=</samp>’ should be used with the <code>test</code> command for <small>POSIX</small> conformance. +</p> +</dd> +<dt><span><code><var>string1</var> != <var>string2</var></code></span></dt> +<dd><p>True if the strings are not equal. +</p> +</dd> +<dt><span><code><var>string1</var> < <var>string2</var></code></span></dt> +<dd><p>True if <var>string1</var> sorts before <var>string2</var> lexicographically. +</p> +</dd> +<dt><span><code><var>string1</var> > <var>string2</var></code></span></dt> +<dd><p>True if <var>string1</var> sorts after <var>string2</var> lexicographically. +</p> +</dd> +<dt><span><code><var>arg1</var> OP <var>arg2</var></code></span></dt> +<dd><p><code>OP</code> is one of +‘<samp>-eq</samp>’, ‘<samp>-ne</samp>’, ‘<samp>-lt</samp>’, ‘<samp>-le</samp>’, ‘<samp>-gt</samp>’, or ‘<samp>-ge</samp>’. +These arithmetic binary operators return true if <var>arg1</var> +is equal to, not equal to, less than, less than or equal to, +greater than, or greater than or equal to <var>arg2</var>, +respectively. <var>Arg1</var> and <var>arg2</var> +may be positive or negative integers. +When used with the <code>[[</code> command, <var>Arg1</var> and <var>Arg2</var> +are evaluated as arithmetic expressions (see <a href="#Shell-Arithmetic">Shell Arithmetic</a>). +</p></dd> +</dl> + +<hr> +</div> +<div class="section" id="Shell-Arithmetic"> +<div class="header"> +<p> +Next: <a href="#Aliases" accesskey="n" rel="next">Aliases</a>, Previous: <a href="#Bash-Conditional-Expressions" accesskey="p" rel="prev">Bash Conditional Expressions</a>, Up: <a href="#Bash-Features" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Shell-Arithmetic-1"></span><h3 class="section">6.5 Shell Arithmetic</h3> +<span id="index-arithmetic_002c-shell"></span> +<span id="index-shell-arithmetic"></span> +<span id="index-expressions_002c-arithmetic"></span> +<span id="index-evaluation_002c-arithmetic"></span> +<span id="index-arithmetic-evaluation"></span> + +<p>The shell allows arithmetic expressions to be evaluated, as one of +the shell expansions or by using the <code>((</code> compound command, the +<code>let</code> builtin, or the <samp>-i</samp> option to the <code>declare</code> builtin. +</p> +<p>Evaluation is done in fixed-width integers with no check for overflow, +though division by 0 is trapped and flagged as an error. +The operators and their precedence, associativity, and values +are the same as in the C language. +The following list of operators is grouped into levels of +equal-precedence operators. +The levels are listed in order of decreasing precedence. +</p> +<dl compact="compact"> +<dt><span><code><var>id</var>++ <var>id</var>--</code></span></dt> +<dd><p>variable post-increment and post-decrement +</p> +</dd> +<dt><span><code>++<var>id</var> --<var>id</var></code></span></dt> +<dd><p>variable pre-increment and pre-decrement +</p> +</dd> +<dt><span><code>- +</code></span></dt> +<dd><p>unary minus and plus +</p> +</dd> +<dt><span><code>! ~</code></span></dt> +<dd><p>logical and bitwise negation +</p> +</dd> +<dt><span><code>**</code></span></dt> +<dd><p>exponentiation +</p> +</dd> +<dt><span><code>* / %</code></span></dt> +<dd><p>multiplication, division, remainder +</p> +</dd> +<dt><span><code>+ -</code></span></dt> +<dd><p>addition, subtraction +</p> +</dd> +<dt><span><code><< >></code></span></dt> +<dd><p>left and right bitwise shifts +</p> +</dd> +<dt><span><code><= >= < ></code></span></dt> +<dd><p>comparison +</p> +</dd> +<dt><span><code>== !=</code></span></dt> +<dd><p>equality and inequality +</p> +</dd> +<dt><span><code>&</code></span></dt> +<dd><p>bitwise AND +</p> +</dd> +<dt><span><code>^</code></span></dt> +<dd><p>bitwise exclusive OR +</p> +</dd> +<dt><span><code>|</code></span></dt> +<dd><p>bitwise OR +</p> +</dd> +<dt><span><code>&&</code></span></dt> +<dd><p>logical AND +</p> +</dd> +<dt><span><code>||</code></span></dt> +<dd><p>logical OR +</p> +</dd> +<dt><span><code>expr ? expr : expr</code></span></dt> +<dd><p>conditional operator +</p> +</dd> +<dt><span><code>= *= /= %= += -= <<= >>= &= ^= |=</code></span></dt> +<dd><p>assignment +</p> +</dd> +<dt><span><code>expr1 , expr2</code></span></dt> +<dd><p>comma +</p></dd> +</dl> + +<p>Shell variables are allowed as operands; parameter expansion is +performed before the expression is evaluated. +Within an expression, shell variables may also be referenced by name +without using the parameter expansion syntax. +A shell variable that is null or unset evaluates to 0 when referenced +by name without using the parameter expansion syntax. +The value of a variable is evaluated as an arithmetic expression +when it is referenced, or when a variable which has been given the +<code>integer</code> attribute using ‘<samp>declare -i</samp>’ is assigned a value. +A null value evaluates to 0. +A shell variable need not have its <code>integer</code> attribute turned on +to be used in an expression. +</p> +<p>Integer constants follow the C language definition, without suffixes or +character constants. +Constants with a leading 0 are interpreted as octal numbers. +A leading ‘<samp>0x</samp>’ or ‘<samp>0X</samp>’ denotes hexadecimal. Otherwise, +numbers take the form [<var>base</var><code>#</code>]<var>n</var>, where the optional <var>base</var> +is a decimal number between 2 and 64 representing the arithmetic +base, and <var>n</var> is a number in that base. +If <var>base</var><code>#</code> is omitted, then base 10 is used. +When specifying <var>n</var>, +if a non-digit is required, +the digits greater than 9 are represented by the lowercase letters, +the uppercase letters, ‘<samp>@</samp>’, and ‘<samp>_</samp>’, in that order. +If <var>base</var> is less than or equal to 36, lowercase and uppercase +letters may be used interchangeably to represent numbers between 10 +and 35. +</p> +<p>Operators are evaluated in order of precedence. Sub-expressions in +parentheses are evaluated first and may override the precedence +rules above. +</p> +<hr> +</div> +<div class="section" id="Aliases"> +<div class="header"> +<p> +Next: <a href="#Arrays" accesskey="n" rel="next">Arrays</a>, Previous: <a href="#Shell-Arithmetic" accesskey="p" rel="prev">Shell Arithmetic</a>, Up: <a href="#Bash-Features" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Aliases-1"></span><h3 class="section">6.6 Aliases</h3> +<span id="index-alias-expansion"></span> + +<p><em>Aliases</em> allow a string to be substituted for a word when it is used +as the first word of a simple command. +The shell maintains a list of aliases that may be set and unset with +the <code>alias</code> and <code>unalias</code> builtin commands. +</p> +<p>The first word of each simple command, if unquoted, is checked to see +if it has an alias. +If so, that word is replaced by the text of the alias. +The characters ‘<samp>/</samp>’, ‘<samp>$</samp>’, ‘<samp>`</samp>’, ‘<samp>=</samp>’ and any of the +shell metacharacters or quoting characters listed above may not appear +in an alias name. +The replacement text may contain any valid +shell input, including shell metacharacters. +The first word of the replacement text is tested for +aliases, but a word that is identical to an alias being expanded +is not expanded a second time. +This means that one may alias <code>ls</code> to <code>"ls -F"</code>, +for instance, and Bash does not try to recursively expand the +replacement text. +If the last character of the alias value is a +<code>blank</code>, then the next command word following the +alias is also checked for alias expansion. +</p> +<p>Aliases are created and listed with the <code>alias</code> +command, and removed with the <code>unalias</code> command. +</p> +<p>There is no mechanism for using arguments in the replacement text, +as in <code>csh</code>. +If arguments are needed, use a shell function +(see <a href="#Shell-Functions">Shell Functions</a>). +</p> +<p>Aliases are not expanded when the shell is not interactive, +unless the <code>expand_aliases</code> shell option is set using +<code>shopt</code> (see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>). +</p> +<p>The rules concerning the definition and use of aliases are +somewhat confusing. Bash +always reads at least one complete line of input, +and all lines that make up a compound command, +before executing any of the commands on that line or the compound command. +Aliases are expanded when a +command is read, not when it is executed. Therefore, an +alias definition appearing on the same line as another +command does not take effect until the next line of input is read. +The commands following the alias definition +on that line are not affected by the new alias. +This behavior is also an issue when functions are executed. +Aliases are expanded when a function definition is read, +not when the function is executed, because a function definition +is itself a command. As a consequence, aliases +defined in a function are not available until after that +function is executed. To be safe, always put +alias definitions on a separate line, and do not use <code>alias</code> +in compound commands. +</p> +<p>For almost every purpose, shell functions are preferred over aliases. +</p> +<hr> +</div> +<div class="section" id="Arrays"> +<div class="header"> +<p> +Next: <a href="#The-Directory-Stack" accesskey="n" rel="next">The Directory Stack</a>, Previous: <a href="#Aliases" accesskey="p" rel="prev">Aliases</a>, Up: <a href="#Bash-Features" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Arrays-1"></span><h3 class="section">6.7 Arrays</h3> +<span id="index-arrays"></span> + +<p>Bash provides one-dimensional indexed and associative array variables. +Any variable may be used as an indexed array; +the <code>declare</code> builtin will explicitly declare an array. +There is no maximum +limit on the size of an array, nor any requirement that members +be indexed or assigned contiguously. +Indexed arrays are referenced using integers (including arithmetic +expressions (see <a href="#Shell-Arithmetic">Shell Arithmetic</a>)) and are zero-based; +associative arrays use arbitrary strings. +Unless otherwise noted, indexed array indices must be non-negative integers. +</p> +<p>An indexed array is created automatically if any variable is assigned to +using the syntax +</p><div class="example"> +<pre class="example"><var>name</var>[<var>subscript</var>]=<var>value</var> +</pre></div> + +<p>The <var>subscript</var> +is treated as an arithmetic expression that must evaluate to a number. +To explicitly declare an array, use +</p><div class="example"> +<pre class="example">declare -a <var>name</var> +</pre></div> +<p>The syntax +</p><div class="example"> +<pre class="example">declare -a <var>name</var>[<var>subscript</var>] +</pre></div> +<p>is also accepted; the <var>subscript</var> is ignored. +</p> +<p>Associative arrays are created using +</p><div class="example"> +<pre class="example">declare -A <var>name</var> +</pre></div> + +<p>Attributes may be +specified for an array variable using the <code>declare</code> and +<code>readonly</code> builtins. Each attribute applies to all members of +an array. +</p> +<p>Arrays are assigned to using compound assignments of the form +</p><div class="example"> +<pre class="example"><var>name</var>=(<var>value1</var> <var>value2</var> … ) +</pre></div> +<p>where each +<var>value</var> may be of the form <code>[<var>subscript</var>]=</code><var>string</var>. +Indexed array assignments do not require anything but <var>string</var>. +When assigning to indexed arrays, if +the optional subscript is supplied, that index is assigned to; +otherwise the index of the element assigned is the last index assigned +to by the statement plus one. Indexing starts at zero. +</p> +<p>Each <var>value</var> in the list undergoes all the shell expansions +described above (see <a href="#Shell-Expansions">Shell Expansions</a>). +</p> +<p>When assigning to an associative array, the words in a compound assignment +may be either assignment statements, for which the subscript is required, +or a list of words that is interpreted as a sequence of alternating keys +and values: +<var>name</var>=(<var>key1</var> <var>value1</var> <var>key2</var> <var>value2</var> … ). +These are treated identically to +<var>name</var>=( [<var>key1</var>]=<var>value1</var> [<var>key2</var>]=<var>value2</var> … ). +The first word in the list determines how the remaining words +are interpreted; all assignments in a list must be of the same type. +When using key/value pairs, the keys may not be missing or empty; +a final missing value is treated like the empty string. +</p> +<p>This syntax is also accepted by the <code>declare</code> +builtin. Individual array elements may be assigned to using the +<code><var>name</var>[<var>subscript</var>]=<var>value</var></code> syntax introduced above. +</p> +<p>When assigning to an indexed array, if <var>name</var> +is subscripted by a negative number, that number is +interpreted as relative to one greater than the maximum index of +<var>name</var>, so negative indices count back from the end of the +array, and an index of -1 references the last element. +</p> +<p>The ‘<samp>+=</samp>’ operator will append to an array variable when assigning +using the compound assignment syntax; see <a href="#Shell-Parameters">Shell Parameters</a> above. +</p> +<p>Any element of an array may be referenced using +<code>${<var>name</var>[<var>subscript</var>]}</code>. +The braces are required to avoid +conflicts with the shell’s filename expansion operators. If the +<var>subscript</var> is ‘<samp>@</samp>’ or ‘<samp>*</samp>’, the word expands to all members +of the array <var>name</var>. These subscripts differ only when the word +appears within double quotes. +If the word is double-quoted, +<code>${<var>name</var>[*]}</code> expands to a single word with +the value of each array member separated by the first character of the +<code>IFS</code> variable, and <code>${<var>name</var>[@]}</code> expands each element of +<var>name</var> to a separate word. When there are no array members, +<code>${<var>name</var>[@]}</code> expands to nothing. +If the double-quoted expansion occurs within a word, the expansion of +the first parameter is joined with the beginning part of the original +word, and the expansion of the last parameter is joined with the last +part of the original word. +This is analogous to the +expansion of the special parameters ‘<samp>@</samp>’ and ‘<samp>*</samp>’. +<code>${#<var>name</var>[<var>subscript</var>]}</code> expands to the length of +<code>${<var>name</var>[<var>subscript</var>]}</code>. +If <var>subscript</var> is ‘<samp>@</samp>’ or +‘<samp>*</samp>’, the expansion is the number of elements in the array. +If the <var>subscript</var> +used to reference an element of an indexed array +evaluates to a number less than zero, it is +interpreted as relative to one greater than the maximum index of the array, +so negative indices count back from the end of the array, +and an index of -1 refers to the last element. +</p> +<p>Referencing an array variable without a subscript is equivalent to +referencing with a subscript of 0. +Any reference to a variable using a valid subscript is legal, and +<code>bash</code> will create an array if necessary. +</p> +<p>An array variable is considered set if a subscript has been assigned a +value. The null string is a valid value. +</p> +<p>It is possible to obtain the keys (indices) of an array as well as the values. +${!<var>name</var>[@]} and ${!<var>name</var>[*]} expand to the indices +assigned in array variable <var>name</var>. +The treatment when in double quotes is similar to the expansion of the +special parameters ‘<samp>@</samp>’ and ‘<samp>*</samp>’ within double quotes. +</p> +<p>The <code>unset</code> builtin is used to destroy arrays. +<code>unset <var>name</var>[<var>subscript</var>]</code> +destroys the array element at index <var>subscript</var>. +Negative subscripts to indexed arrays are interpreted as described above. +Unsetting the last element of an array variable does not unset the variable. +<code>unset <var>name</var></code>, where <var>name</var> is an array, removes the +entire array. +<code>unset <var>name</var>[<var>subscript</var>]</code> behaves differently +depending on the array type when given a +subscript of ‘<samp>*</samp>’ or ‘<samp>@</samp>’. +When <var>name</var> is an associative array, it removes the element with key +‘<samp>*</samp>’ or ‘<samp>@</samp>’. +If <var>name</var> is an indexed array, <code>unset</code> removes all of the elements, +but does not remove the array itself. +</p> +<p>When using a variable name with a subscript as an argument to a command, +such as with <code>unset</code>, without using the word expansion syntax +described above, the argument is subject to the shell’s filename expansion. +If filename expansion is not desired, the argument should be quoted. +</p> +<p>The <code>declare</code>, <code>local</code>, and <code>readonly</code> +builtins each accept a <samp>-a</samp> option to specify an indexed +array and a <samp>-A</samp> option to specify an associative array. +If both options are supplied, <samp>-A</samp> takes precedence. +The <code>read</code> builtin accepts a <samp>-a</samp> +option to assign a list of words read from the standard input +to an array, and can read values from the standard input into +individual array elements. The <code>set</code> and <code>declare</code> +builtins display array values in a way that allows them to be +reused as input. +</p> +<hr> +</div> +<div class="section" id="The-Directory-Stack"> +<div class="header"> +<p> +Next: <a href="#Controlling-the-Prompt" accesskey="n" rel="next">Controlling the Prompt</a>, Previous: <a href="#Arrays" accesskey="p" rel="prev">Arrays</a>, Up: <a href="#Bash-Features" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="The-Directory-Stack-1"></span><h3 class="section">6.8 The Directory Stack</h3> +<span id="index-directory-stack"></span> + + +<p>The directory stack is a list of recently-visited directories. The +<code>pushd</code> builtin adds directories to the stack as it changes +the current directory, and the <code>popd</code> builtin removes specified +directories from the stack and changes the current directory to +the directory removed. The <code>dirs</code> builtin displays the contents +of the directory stack. The current directory is always the "top" +of the directory stack. +</p> +<p>The contents of the directory stack are also visible +as the value of the <code>DIRSTACK</code> shell variable. +</p> +<ul class="section-toc"> +<li><a href="#Directory-Stack-Builtins" accesskey="1">Directory Stack Builtins</a></li> +</ul> +<hr> +<div class="subsection" id="Directory-Stack-Builtins"> +<div class="header"> +<p> +Up: <a href="#The-Directory-Stack" accesskey="u" rel="up">The Directory Stack</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Directory-Stack-Builtins-1"></span><h4 class="subsection">6.8.1 Directory Stack Builtins</h4> + +<dl compact="compact"> +<dt id='index-dirs'><span><code>dirs</code><a href='#index-dirs' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">dirs [-clpv] [+<var>N</var> | -<var>N</var>] +</pre></div> + +<p>Display the list of currently remembered directories. Directories +are added to the list with the <code>pushd</code> command; the +<code>popd</code> command removes directories from the list. +The current directory is always the first directory in the stack. +</p> +<dl compact="compact"> +<dt><span><code>-c</code></span></dt> +<dd><p>Clears the directory stack by deleting all of the elements. +</p></dd> +<dt><span><code>-l</code></span></dt> +<dd><p>Produces a listing using full pathnames; +the default listing format uses a tilde to denote the home directory. +</p></dd> +<dt><span><code>-p</code></span></dt> +<dd><p>Causes <code>dirs</code> to print the directory stack with one entry per +line. +</p></dd> +<dt><span><code>-v</code></span></dt> +<dd><p>Causes <code>dirs</code> to print the directory stack with one entry per +line, prefixing each entry with its index in the stack. +</p></dd> +<dt><span><code>+<var>N</var></code></span></dt> +<dd><p>Displays the <var>N</var>th directory (counting from the left of the +list printed by <code>dirs</code> when invoked without options), starting +with zero. +</p></dd> +<dt><span><code>-<var>N</var></code></span></dt> +<dd><p>Displays the <var>N</var>th directory (counting from the right of the +list printed by <code>dirs</code> when invoked without options), starting +with zero. +</p></dd> +</dl> + +</dd> +<dt id='index-popd'><span><code>popd</code><a href='#index-popd' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">popd [-n] [+<var>N</var> | -<var>N</var>] +</pre></div> + +<p>Removes elements from the directory stack. +The elements are numbered from 0 starting at the first directory +listed by <code>dirs</code>; +that is, <code>popd</code> is equivalent to <code>popd +0</code>. +</p> +<p>When no arguments are given, <code>popd</code> +removes the top directory from the stack and changes to +the new top directory. +</p> +<p>Arguments, if supplied, have the following meanings: +</p> +<dl compact="compact"> +<dt><span><code>-n</code></span></dt> +<dd><p>Suppresses the normal change of directory when removing directories +from the stack, so that only the stack is manipulated. +</p></dd> +<dt><span><code>+<var>N</var></code></span></dt> +<dd><p>Removes the <var>N</var>th directory (counting from the left of the +list printed by <code>dirs</code>), starting with zero, from the stack. +</p></dd> +<dt><span><code>-<var>N</var></code></span></dt> +<dd><p>Removes the <var>N</var>th directory (counting from the right of the +list printed by <code>dirs</code>), starting with zero, from the stack. +</p></dd> +</dl> + +<p>If the top element of the directory stack is modified, and +the <samp>-n</samp> option was not supplied, <code>popd</code> uses the <code>cd</code> +builtin to change to the directory at the top of the stack. +If the <code>cd</code> fails, <code>popd</code> returns a non-zero value. +</p> +<p>Otherwise, <code>popd</code> returns an unsuccessful status if +an invalid option is encountered, the directory stack +is empty, or a non-existent directory stack entry is specified. +</p> +<p>If the <code>popd</code> command is successful, +Bash runs <code>dirs</code> to show the final contents of the directory stack, +and the return status is 0. +</p> +<span id="index-pushd"></span> +</dd> +<dt><span><code>pushd</code></span></dt> +<dd><div class="example"> +<pre class="example">pushd [-n] [<var>+N</var> | <var>-N</var> | <var>dir</var>] +</pre></div> + +<p>Adds a directory to the top of the directory stack, or rotates +the stack, making the new top of the stack the current working +directory. +With no arguments, <code>pushd</code> exchanges the top two elements +of the directory stack. +</p> +<p>Arguments, if supplied, have the following meanings: +</p> +<dl compact="compact"> +<dt><span><code>-n</code></span></dt> +<dd><p>Suppresses the normal change of directory when rotating or +adding directories to the stack, so that only the stack is manipulated. +</p></dd> +<dt><span><code>+<var>N</var></code></span></dt> +<dd><p>Brings the <var>N</var>th directory (counting from the left of the +list printed by <code>dirs</code>, starting with zero) to the top of +the list by rotating the stack. +</p></dd> +<dt><span><code>-<var>N</var></code></span></dt> +<dd><p>Brings the <var>N</var>th directory (counting from the right of the +list printed by <code>dirs</code>, starting with zero) to the top of +the list by rotating the stack. +</p></dd> +<dt><span><code><var>dir</var></code></span></dt> +<dd><p>Makes <var>dir</var> be the top of the stack. +</p></dd> +</dl> + +<p>After the stack has been modified, if the <samp>-n</samp> option was not +supplied, <code>pushd</code> uses the <code>cd</code> builtin to change to the +directory at the top of the stack. +If the <code>cd</code> fails, <code>pushd</code> returns a non-zero value. +</p> +<p>Otherwise, if no arguments are supplied, <code>pushd</code> returns 0 unless the +directory stack is empty. +When rotating the directory stack, <code>pushd</code> returns 0 unless +the directory stack is empty or a non-existent directory stack element +is specified. +</p> +<p>If the <code>pushd</code> command is successful, +Bash runs <code>dirs</code> to show the final contents of the directory stack. +</p> +</dd> +</dl> + +<hr> +</div> +</div> +<div class="section" id="Controlling-the-Prompt"> +<div class="header"> +<p> +Next: <a href="#The-Restricted-Shell" accesskey="n" rel="next">The Restricted Shell</a>, Previous: <a href="#The-Directory-Stack" accesskey="p" rel="prev">The Directory Stack</a>, Up: <a href="#Bash-Features" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Controlling-the-Prompt-1"></span><h3 class="section">6.9 Controlling the Prompt</h3> +<span id="index-prompting"></span> + +<p>Bash examines the value of the array variable <code>PROMPT_COMMAND</code> just before +printing each primary prompt. +If any elements in <code>PROMPT_COMMAND</code> are set and non-null, Bash +executes each value, in numeric order, +just as if it had been typed on the command line. +</p> +<p>In addition, the following table describes the special characters which +can appear in the prompt variables <code>PS0</code>, <code>PS1</code>, <code>PS2</code>, and +<code>PS4</code>: +</p> +<dl compact="compact"> +<dt><span><code>\a</code></span></dt> +<dd><p>A bell character. +</p></dd> +<dt><span><code>\d</code></span></dt> +<dd><p>The date, in "Weekday Month Date" format (e.g., "Tue May 26"). +</p></dd> +<dt><span><code>\D{<var>format</var>}</code></span></dt> +<dd><p>The <var>format</var> is passed to <code>strftime</code>(3) and the result is inserted +into the prompt string; an empty <var>format</var> results in a locale-specific +time representation. The braces are required. +</p></dd> +<dt><span><code>\e</code></span></dt> +<dd><p>An escape character. +</p></dd> +<dt><span><code>\h</code></span></dt> +<dd><p>The hostname, up to the first ‘.’. +</p></dd> +<dt><span><code>\H</code></span></dt> +<dd><p>The hostname. +</p></dd> +<dt><span><code>\j</code></span></dt> +<dd><p>The number of jobs currently managed by the shell. +</p></dd> +<dt><span><code>\l</code></span></dt> +<dd><p>The basename of the shell’s terminal device name. +</p></dd> +<dt><span><code>\n</code></span></dt> +<dd><p>A newline. +</p></dd> +<dt><span><code>\r</code></span></dt> +<dd><p>A carriage return. +</p></dd> +<dt><span><code>\s</code></span></dt> +<dd><p>The name of the shell, the basename of <code>$0</code> (the portion +following the final slash). +</p></dd> +<dt><span><code>\t</code></span></dt> +<dd><p>The time, in 24-hour HH:MM:SS format. +</p></dd> +<dt><span><code>\T</code></span></dt> +<dd><p>The time, in 12-hour HH:MM:SS format. +</p></dd> +<dt><span><code>\@</code></span></dt> +<dd><p>The time, in 12-hour am/pm format. +</p></dd> +<dt><span><code>\A</code></span></dt> +<dd><p>The time, in 24-hour HH:MM format. +</p></dd> +<dt><span><code>\u</code></span></dt> +<dd><p>The username of the current user. +</p></dd> +<dt><span><code>\v</code></span></dt> +<dd><p>The version of Bash (e.g., 2.00) +</p></dd> +<dt><span><code>\V</code></span></dt> +<dd><p>The release of Bash, version + patchlevel (e.g., 2.00.0) +</p></dd> +<dt><span><code>\w</code></span></dt> +<dd><p>The value of the <code>PWD</code> shell variable (<code>$PWD</code>), +with <code>$HOME</code> abbreviated with a tilde +(uses the <code>$PROMPT_DIRTRIM</code> variable). +</p></dd> +<dt><span><code>\W</code></span></dt> +<dd><p>The basename of <code>$PWD</code>, with <code>$HOME</code> abbreviated with a tilde. +</p></dd> +<dt><span><code>\!</code></span></dt> +<dd><p>The history number of this command. +</p></dd> +<dt><span><code>\#</code></span></dt> +<dd><p>The command number of this command. +</p></dd> +<dt><span><code>\$</code></span></dt> +<dd><p>If the effective uid is 0, <code>#</code>, otherwise <code>$</code>. +</p></dd> +<dt><span><code>\<var>nnn</var></code></span></dt> +<dd><p>The character whose ASCII code is the octal value <var>nnn</var>. +</p></dd> +<dt><span><code>\\</code></span></dt> +<dd><p>A backslash. +</p></dd> +<dt><span><code>\[</code></span></dt> +<dd><p>Begin a sequence of non-printing characters. This could be used to +embed a terminal control sequence into the prompt. +</p></dd> +<dt><span><code>\]</code></span></dt> +<dd><p>End a sequence of non-printing characters. +</p></dd> +</dl> + +<p>The command number and the history number are usually different: +the history number of a command is its position in the history +list, which may include commands restored from the history file +(see <a href="#Bash-History-Facilities">Bash History Facilities</a>), while the command number is +the position in the sequence of commands executed during the current +shell session. +</p> +<p>After the string is decoded, it is expanded via +parameter expansion, command substitution, arithmetic +expansion, and quote removal, subject to the value of the +<code>promptvars</code> shell option (see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>). +This can have unwanted side effects if escaped portions of the string +appear within command substitution or contain characters special to +word expansion. +</p> +<hr> +</div> +<div class="section" id="The-Restricted-Shell"> +<div class="header"> +<p> +Next: <a href="#Bash-POSIX-Mode" accesskey="n" rel="next">Bash POSIX Mode</a>, Previous: <a href="#Controlling-the-Prompt" accesskey="p" rel="prev">Controlling the Prompt</a>, Up: <a href="#Bash-Features" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="The-Restricted-Shell-1"></span><h3 class="section">6.10 The Restricted Shell</h3> +<span id="index-restricted-shell"></span> + +<p>If Bash is started with the name <code>rbash</code>, or the +<samp>--restricted</samp> +or +<samp>-r</samp> +option is supplied at invocation, the shell becomes restricted. +A restricted shell is used to +set up an environment more controlled than the standard shell. +A restricted shell behaves identically to <code>bash</code> +with the exception that the following are disallowed or not performed: +</p> +<ul> +<li> Changing directories with the <code>cd</code> builtin. +</li><li> Setting or unsetting the values of the <code>SHELL</code>, <code>PATH</code>, +<code>HISTFILE</code>, +<code>ENV</code>, or <code>BASH_ENV</code> variables. +</li><li> Specifying command names containing slashes. +</li><li> Specifying a filename containing a slash as an argument to the <code>.</code> +builtin command. +</li><li> Specifying a filename containing a slash as an argument to the <code>history</code> +builtin command. +</li><li> Specifying a filename containing a slash as an argument to the <samp>-p</samp> +option to the <code>hash</code> builtin command. +</li><li> Importing function definitions from the shell environment at startup. +</li><li> Parsing the value of <code>SHELLOPTS</code> from the shell environment at startup. +</li><li> Redirecting output using the ‘<samp>></samp>’, ‘<samp>>|</samp>’, ‘<samp><></samp>’, ‘<samp>>&</samp>’, +‘<samp>&></samp>’, and ‘<samp>>></samp>’ redirection operators. +</li><li> Using the <code>exec</code> builtin to replace the shell with another command. +</li><li> Adding or deleting builtin commands with the +<samp>-f</samp> and <samp>-d</samp> options to the <code>enable</code> builtin. +</li><li> Using the <code>enable</code> builtin command to enable disabled shell builtins. +</li><li> Specifying the <samp>-p</samp> option to the <code>command</code> builtin. +</li><li> Turning off restricted mode with ‘<samp>set +r</samp>’ or ‘<samp>shopt -u restricted_shell</samp>’. +</li></ul> + +<p>These restrictions are enforced after any startup files are read. +</p> +<p>When a command that is found to be a shell script is executed +(see <a href="#Shell-Scripts">Shell Scripts</a>), <code>rbash</code> turns off any restrictions in +the shell spawned to execute the script. +</p> +<p>The restricted shell mode is only one component of a useful restricted +environment. It should be accompanied by setting <code>PATH</code> to a value +that allows execution of only a few verified commands (commands that +allow shell escapes are particularly vulnerable), changing the current +directory to a non-writable directory other than <code>$HOME</code> after login, +not allowing the restricted shell to execute shell scripts, and cleaning +the environment of variables that cause some commands to modify their +behavior (e.g., <code>VISUAL</code> or <code>PAGER</code>). +</p> +<p>Modern systems provide more secure ways to implement a restricted environment, +such as <code>jails</code>, <code>zones</code>, or <code>containers</code>. +</p> + +<hr> +</div> +<div class="section" id="Bash-POSIX-Mode"> +<div class="header"> +<p> +Next: <a href="#Shell-Compatibility-Mode" accesskey="n" rel="next">Shell Compatibility Mode</a>, Previous: <a href="#The-Restricted-Shell" accesskey="p" rel="prev">The Restricted Shell</a>, Up: <a href="#Bash-Features" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Bash-POSIX-Mode-1"></span><h3 class="section">6.11 Bash POSIX Mode</h3> +<span id="index-POSIX-Mode"></span> + +<p>Starting Bash with the <samp>--posix</samp> command-line option or executing +‘<samp>set -o posix</samp>’ while Bash is running will cause Bash to conform more +closely to the <small>POSIX</small> standard by changing the behavior to +match that specified by <small>POSIX</small> in areas where the Bash default differs. +</p> +<p>When invoked as <code>sh</code>, Bash enters <small>POSIX</small> mode after reading the +startup files. +</p> +<p>The following list is what’s changed when ‘<small>POSIX</small> mode’ is in effect: +</p> +<ol> +<li> Bash ensures that the <code>POSIXLY_CORRECT</code> variable is set. + +</li><li> When a command in the hash table no longer exists, Bash will re-search +<code>$PATH</code> to find the new location. This is also available with +‘<samp>shopt -s checkhash</samp>’. + +</li><li> Bash will not insert a command without the execute bit set into the +command hash table, even if it returns it as a (last-ditch) result +from a <code>$PATH</code> search. + +</li><li> The message printed by the job control code and builtins when a job +exits with a non-zero status is ‘Done(status)’. + +</li><li> The message printed by the job control code and builtins when a job +is stopped is ‘Stopped(<var>signame</var>)’, where <var>signame</var> is, for +example, <code>SIGTSTP</code>. + +</li><li> Alias expansion is always enabled, even in non-interactive shells. + +</li><li> Reserved words appearing in a context where reserved words are recognized +do not undergo alias expansion. + +</li><li> Alias expansion is performed when initially parsing a command substitution. +The default mode generally defers it, when enabled, until the command +substitution is executed. This means that command substitution will not +expand aliases that are defined after the command substitution is initially +parsed (e.g., as part of a function definition). + +</li><li> The <small>POSIX</small> <code>PS1</code> and <code>PS2</code> expansions of ‘<samp>!</samp>’ to +the history number and ‘<samp>!!</samp>’ to ‘<samp>!</samp>’ are enabled, +and parameter expansion is performed on the values of <code>PS1</code> and +<code>PS2</code> regardless of the setting of the <code>promptvars</code> option. + +</li><li> The <small>POSIX</small> startup files are executed (<code>$ENV</code>) rather than +the normal Bash files. + +</li><li> Tilde expansion is only performed on assignments preceding a command +name, rather than on all assignment statements on the line. + +</li><li> The default history file is <samp>~/.sh_history</samp> (this is the +default value of <code>$HISTFILE</code>). + +</li><li> Redirection operators do not perform filename expansion on the word +in the redirection unless the shell is interactive. + +</li><li> Redirection operators do not perform word splitting on the word in the +redirection. + +</li><li> Function names must be valid shell <code>name</code>s. That is, they may not +contain characters other than letters, digits, and underscores, and +may not start with a digit. Declaring a function with an invalid name +causes a fatal syntax error in non-interactive shells. + +</li><li> Function names may not be the same as one of the <small>POSIX</small> special +builtins. + +</li><li> <small>POSIX</small> special builtins are found before shell functions +during command lookup. + +</li><li> When printing shell function definitions (e.g., by <code>type</code>), Bash does +not print the <code>function</code> keyword. + +</li><li> Literal tildes that appear as the first character in elements of +the <code>PATH</code> variable are not expanded as described above +under <a href="#Tilde-Expansion">Tilde Expansion</a>. + +</li><li> The <code>time</code> reserved word may be used by itself as a command. When +used in this way, it displays timing statistics for the shell and its +completed children. The <code>TIMEFORMAT</code> variable controls the format +of the timing information. + +</li><li> When parsing and expanding a ${…} expansion that appears within +double quotes, single quotes are no longer special and cannot be used to +quote a closing brace or other special character, unless the operator is +one of those defined to perform pattern removal. In this case, they do +not have to appear as matched pairs. + +</li><li> The parser does not recognize <code>time</code> as a reserved word if the next +token begins with a ‘<samp>-</samp>’. + + +</li><li> The ‘<samp>!</samp>’ character does not introduce history expansion within a +double-quoted string, even if the <code>histexpand</code> option is enabled. + +</li><li> If a <small>POSIX</small> special builtin returns an error status, a +non-interactive shell exits. The fatal errors are those listed in +the <small>POSIX</small> standard, and include things like passing incorrect options, +redirection errors, variable assignment errors for assignments preceding +the command name, and so on. + +</li><li> A non-interactive shell exits with an error status if a variable +assignment error occurs when no command name follows the assignment +statements. +A variable assignment error occurs, for example, when trying to assign +a value to a readonly variable. + +</li><li> A non-interactive shell exits with an error status if a variable +assignment error occurs in an assignment statement preceding a special +builtin, but not with any other simple command. For any other simple +command, the shell aborts execution of that command, and execution continues +at the top level ("the shell shall not perform any further processing of the +command in which the error occurred"). + +</li><li> A non-interactive shell exits with an error status if the iteration +variable in a <code>for</code> statement or the selection variable in a +<code>select</code> statement is a readonly variable. + +</li><li> Non-interactive shells exit if <var>filename</var> in <code>.</code> <var>filename</var> +is not found. + +</li><li> Non-interactive shells exit if a syntax error in an arithmetic expansion +results in an invalid expression. + +</li><li> Non-interactive shells exit if a parameter expansion error occurs. + +</li><li> Non-interactive shells exit if there is a syntax error in a script read +with the <code>.</code> or <code>source</code> builtins, or in a string processed by +the <code>eval</code> builtin. + +</li><li> While variable indirection is available, it may not be applied to the +‘<samp>#</samp>’ and ‘<samp>?</samp>’ special parameters. + +</li><li> Expanding the ‘<samp>*</samp>’ special parameter in a pattern context where the +expansion is double-quoted does not treat the <code>$*</code> as if it were +double-quoted. + +</li><li> Assignment statements preceding <small>POSIX</small> special builtins +persist in the shell environment after the builtin completes. + +</li><li> The <code>command</code> builtin does not prevent builtins that take assignment +statements as arguments from expanding them as assignment statements; +when not in <small>POSIX</small> mode, assignment builtins lose their assignment +statement expansion properties when preceded by <code>command</code>. + +</li><li> The <code>bg</code> builtin uses the required format to describe each job placed +in the background, which does not include an indication of whether the job +is the current or previous job. + +</li><li> The output of ‘<samp>kill -l</samp>’ prints all the signal names on a single line, +separated by spaces, without the ‘<samp>SIG</samp>’ prefix. + +</li><li> The <code>kill</code> builtin does not accept signal names with a ‘<samp>SIG</samp>’ +prefix. + +</li><li> The <code>export</code> and <code>readonly</code> builtin commands display their +output in the format required by <small>POSIX</small>. + +</li><li> The <code>trap</code> builtin displays signal names without the leading +<code>SIG</code>. + +</li><li> The <code>trap</code> builtin doesn’t check the first argument for a possible +signal specification and revert the signal handling to the original +disposition if it is, unless that argument consists solely of digits and +is a valid signal number. If users want to reset the handler for a given +signal to the original disposition, they should use ‘<samp>-</samp>’ as the +first argument. + +</li><li> <code>trap -p</code> displays signals whose dispositions are set to SIG_DFL and +those that were ignored when the shell started. + +</li><li> The <code>.</code> and <code>source</code> builtins do not search the current directory +for the filename argument if it is not found by searching <code>PATH</code>. + +</li><li> Enabling <small>POSIX</small> mode has the effect of setting the +<code>inherit_errexit</code> option, so +subshells spawned to execute command substitutions inherit the value of +the <samp>-e</samp> option from the parent shell. +When the <code>inherit_errexit</code> option is not enabled, +Bash clears the <samp>-e</samp> option in such subshells. + +</li><li> Enabling <small>POSIX</small> mode has the effect of setting the +<code>shift_verbose</code> option, so numeric arguments to <code>shift</code> +that exceed the number of positional parameters will result in an +error message. + +</li><li> When the <code>alias</code> builtin displays alias definitions, it does not +display them with a leading ‘<samp>alias </samp>’ unless the <samp>-p</samp> option +is supplied. + +</li><li> When the <code>set</code> builtin is invoked without options, it does not display +shell function names and definitions. + +</li><li> When the <code>set</code> builtin is invoked without options, it displays +variable values without quotes, unless they contain shell metacharacters, +even if the result contains nonprinting characters. + +</li><li> When the <code>cd</code> builtin is invoked in logical mode, and the pathname +constructed from <code>$PWD</code> and the directory name supplied as an argument +does not refer to an existing directory, <code>cd</code> will fail instead of +falling back to physical mode. + +</li><li> When the <code>cd</code> builtin cannot change a directory because the +length of the pathname +constructed from <code>$PWD</code> and the directory name supplied as an argument +exceeds <code>PATH_MAX</code> when all symbolic links are expanded, <code>cd</code> will +fail instead of attempting to use only the supplied directory name. + +</li><li> The <code>pwd</code> builtin verifies that the value it prints is the same as the +current directory, even if it is not asked to check the file system with the +<samp>-P</samp> option. + +</li><li> When listing the history, the <code>fc</code> builtin does not include an +indication of whether or not a history entry has been modified. + +</li><li> The default editor used by <code>fc</code> is <code>ed</code>. + +</li><li> The <code>type</code> and <code>command</code> builtins will not report a non-executable +file as having been found, though the shell will attempt to execute such a +file if it is the only so-named file found in <code>$PATH</code>. + +</li><li> The <code>vi</code> editing mode will invoke the <code>vi</code> editor directly when +the ‘<samp>v</samp>’ command is run, instead of checking <code>$VISUAL</code> and +<code>$EDITOR</code>. + +</li><li> When the <code>xpg_echo</code> option is enabled, Bash does not attempt to interpret +any arguments to <code>echo</code> as options. Each argument is displayed, after +escape characters are converted. + +</li><li> The <code>ulimit</code> builtin uses a block size of 512 bytes for the <samp>-c</samp> +and <samp>-f</samp> options. + +</li><li> The arrival of <code>SIGCHLD</code> when a trap is set on <code>SIGCHLD</code> does +not interrupt the <code>wait</code> builtin and cause it to return immediately. +The trap command is run once for each child that exits. + +</li><li> The <code>read</code> builtin may be interrupted by a signal for which a trap +has been set. +If Bash receives a trapped signal while executing <code>read</code>, the trap +handler executes and <code>read</code> returns an exit status greater than 128. + +</li><li> The <code>printf</code> builtin uses <code>double</code> (via <code>strtod</code>) to convert +arguments corresponding to floating point conversion specifiers, instead of +<code>long double</code> if it’s available. The ‘<samp>L</samp>’ length modifier forces +<code>printf</code> to use <code>long double</code> if it’s available. + +</li><li> Bash removes an exited background process’s status from the list of such +statuses after the <code>wait</code> builtin is used to obtain it. + +</li></ol> + +<p>There is other <small>POSIX</small> behavior that Bash does not implement by +default even when in <small>POSIX</small> mode. +Specifically: +</p> +<ol> +<li> The <code>fc</code> builtin checks <code>$EDITOR</code> as a program to edit history +entries if <code>FCEDIT</code> is unset, rather than defaulting directly to +<code>ed</code>. <code>fc</code> uses <code>ed</code> if <code>EDITOR</code> is unset. + +</li><li> As noted above, Bash requires the <code>xpg_echo</code> option to be enabled for +the <code>echo</code> builtin to be fully conformant. + +</li></ol> + +<p>Bash can be configured to be <small>POSIX</small>-conformant by default, by specifying +the <samp>--enable-strict-posix-default</samp> to <code>configure</code> when building +(see <a href="#Optional-Features">Optional Features</a>). +</p> +<hr> +</div> +<div class="section" id="Shell-Compatibility-Mode"> +<div class="header"> +<p> +Previous: <a href="#Bash-POSIX-Mode" accesskey="p" rel="prev">Bash POSIX Mode</a>, Up: <a href="#Bash-Features" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Shell-Compatibility-Mode-1"></span><h3 class="section">6.12 Shell Compatibility Mode</h3> +<span id="index-Compatibility-Level"></span> +<span id="index-Compatibility-Mode"></span> + +<p>Bash-4.0 introduced the concept of a <em>shell compatibility level</em>, +specified as a set of options to the shopt builtin +(<code>compat31</code>, +<code>compat32</code>, +<code>compat40</code>, +<code>compat41</code>, +and so on). +There is only one current +compatibility level – each option is mutually exclusive. +The compatibility level is intended to allow users to select behavior +from previous versions that is incompatible with newer versions +while they migrate scripts to use current features and +behavior. It’s intended to be a temporary solution. +</p> +<p>This section does not mention behavior that is standard for a particular +version (e.g., setting <code>compat32</code> means that quoting the rhs of the regexp +matching operator quotes special regexp characters in the word, which is +default behavior in bash-3.2 and subsequent versions). +</p> +<p>If a user enables, say, <code>compat32</code>, it may affect the behavior of other +compatibility levels up to and including the current compatibility level. +The idea is that each compatibility level controls behavior that changed +in that version of Bash, +but that behavior may have been present in earlier versions. +For instance, the change to use locale-based comparisons with the <code>[[</code> +command came in bash-4.1, and earlier versions used ASCII-based comparisons, +so enabling <code>compat32</code> will enable ASCII-based comparisons as well. +That granularity may not be sufficient for +all uses, and as a result users should employ compatibility levels carefully. +Read the documentation for a particular feature to find out the +current behavior. +</p> +<p>Bash-4.3 introduced a new shell variable: <code>BASH_COMPAT</code>. +The value assigned +to this variable (a decimal version number like 4.2, or an integer +corresponding to the <code>compat</code><var>NN</var> option, like 42) determines the +compatibility level. +</p> +<p>Starting with bash-4.4, Bash has begun deprecating older compatibility +levels. +Eventually, the options will be removed in favor of <code>BASH_COMPAT</code>. +</p> +<p>Bash-5.0 is the final version for which there will be an individual shopt +option for the previous version. Users should use <code>BASH_COMPAT</code> +on bash-5.0 and later versions. +</p> +<p>The following table describes the behavior changes controlled by each +compatibility level setting. +The <code>compat</code><var>NN</var> tag is used as shorthand for setting the +compatibility level +to <var>NN</var> using one of the following mechanisms. +For versions prior to bash-5.0, the compatibility level may be set using +the corresponding <code>compat</code><var>NN</var> shopt option. +For bash-4.3 and later versions, the <code>BASH_COMPAT</code> variable is preferred, +and it is required for bash-5.1 and later versions. +</p> +<dl compact="compact"> +<dt><span><code>compat31</code></span></dt> +<dd><ul> +<li> quoting the rhs of the <code>[[</code> command’s regexp matching operator (=~) +has no special effect +</li></ul> + +</dd> +<dt><span><code>compat32</code></span></dt> +<dd><ul> +<li> interrupting a command list such as "a ; b ; c" causes the execution +of the next command in the list (in bash-4.0 and later versions, +the shell acts as if it received the interrupt, so +interrupting one command in a list aborts the execution of the +entire list) +</li></ul> + +</dd> +<dt><span><code>compat40</code></span></dt> +<dd><ul> +<li> the ‘<samp><</samp>’ and ‘<samp>></samp>’ operators to the <code>[[</code> command do not +consider the current locale when comparing strings; they use ASCII +ordering. +Bash versions prior to bash-4.1 use ASCII collation and strcmp(3); +bash-4.1 and later use the current locale’s collation sequence and +strcoll(3). +</li></ul> + +</dd> +<dt><span><code>compat41</code></span></dt> +<dd><ul> +<li> in posix mode, <code>time</code> may be followed by options and still be +recognized as a reserved word (this is <small>POSIX</small> interpretation 267) +</li><li> in posix mode, the parser requires that an even number of single +quotes occur in the <var>word</var> portion of a double-quoted ${…} +parameter expansion and treats them specially, so that characters within +the single quotes are considered quoted +(this is <small>POSIX</small> interpretation 221) +</li></ul> + +</dd> +<dt><span><code>compat42</code></span></dt> +<dd><ul> +<li> the replacement string in double-quoted pattern substitution does not +undergo quote removal, as it does in versions after bash-4.2 +</li><li> in posix mode, single quotes are considered special when expanding +the <var>word</var> portion of a double-quoted ${…} parameter expansion +and can be used to quote a closing brace or other special character +(this is part of <small>POSIX</small> interpretation 221); +in later versions, single quotes +are not special within double-quoted word expansions +</li></ul> + +</dd> +<dt><span><code>compat43</code></span></dt> +<dd><ul> +<li> the shell does not print a warning message if an attempt is made to +use a quoted compound assignment as an argument to declare +(e.g., declare -a foo=’(1 2)’). Later versions warn that this usage is +deprecated +</li><li> word expansion errors are considered non-fatal errors that cause the +current command to fail, even in posix mode +(the default behavior is to make them fatal errors that cause the shell +to exit) +</li><li> when executing a shell function, the loop state (while/until/etc.) +is not reset, so <code>break</code> or <code>continue</code> in that function will break +or continue loops in the calling context. Bash-4.4 and later reset +the loop state to prevent this +</li></ul> + +</dd> +<dt><span><code>compat44</code></span></dt> +<dd><ul> +<li> the shell sets up the values used by <code>BASH_ARGV</code> and <code>BASH_ARGC</code> +so they can expand to the shell’s positional parameters even if extended +debugging mode is not enabled +</li><li> a subshell inherits loops from its parent context, so <code>break</code> +or <code>continue</code> will cause the subshell to exit. +Bash-5.0 and later reset the loop state to prevent the exit +</li><li> variable assignments preceding builtins like <code>export</code> and <code>readonly</code> +that set attributes continue to affect variables with the same +name in the calling environment even if the shell is not in posix +mode +</li></ul> + +</dd> +<dt><span><code>compat50 (set using BASH_COMPAT)</code></span></dt> +<dd><ul> +<li> Bash-5.1 changed the way <code>$RANDOM</code> is generated to introduce slightly +more randomness. If the shell compatibility level is set to 50 or +lower, it reverts to the method from bash-5.0 and previous versions, +so seeding the random number generator by assigning a value to +<code>RANDOM</code> will produce the same sequence as in bash-5.0 +</li><li> If the command hash table is empty, Bash versions prior to bash-5.1 +printed an informational message to that effect, even when producing +output that can be reused as input. Bash-5.1 suppresses that message +when the <samp>-l</samp> option is supplied. +</li></ul> + +</dd> +<dt><span><code>compat51 (set using BASH_COMPAT)</code></span></dt> +<dd><ul> +<li> The <code>unset</code> builtin will unset the array <code>a</code> given an argument like +‘<samp>a[@]</samp>’. +Bash-5.2 will unset an element with key ‘<samp>@</samp>’ (associative arrays) +or remove all the elements without unsetting the array (indexed arrays) +</li><li> arithmetic commands ( ((...)) ) and the expressions in an arithmetic for +statement can be expanded more than once +</li><li> expressions used as arguments to arithmetic operators in the <code>[[</code> +conditional command can be expanded more than once +</li><li> the expressions in substring parameter brace expansion can be +expanded more than once +</li><li> the expressions in the $(( ... )) word expansion can be expanded +more than once +</li><li> arithmetic expressions used as indexed array subscripts can be +expanded more than once +</li><li> <code>test -v</code>, when given an argument of ‘<samp>A[@]</samp>’, where <var>A</var> is +an existing associative array, will return true if the array has any set +elements. +Bash-5.2 will look for and report on a key named ‘<samp>@</samp>’ +</li><li> the ${<var>parameter</var>[:]=<var>value</var>} word expansion will return +<var>value</var>, before any variable-specific transformations have been +performed (e.g., converting to lowercase). +Bash-5.2 will return the final value assigned to the variable. +</li><li> Parsing command substitutions will behave as if extended glob +(see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>) +is enabled, so that parsing a command substitution containing an extglob +pattern (say, as part of a shell function) will not fail. +This assumes the intent is to enable extglob before the command is executed +and word expansions are performed. +It will fail at word expansion time if extglob hasn’t been +enabled by the time the command is executed. +</li></ul> +</dd> +</dl> + +<hr> +</div> +</div> +<div class="chapter" id="Job-Control"> +<div class="header"> +<p> +Next: <a href="#Command-Line-Editing" accesskey="n" rel="next">Command Line Editing</a>, Previous: <a href="#Bash-Features" accesskey="p" rel="prev">Bash Features</a>, Up: <a href="#Top" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Job-Control-1"></span><h2 class="chapter">7 Job Control</h2> + +<p>This chapter discusses what job control is, how it works, and how +Bash allows you to access its facilities. +</p> + +<ul class="section-toc"> +<li><a href="#Job-Control-Basics" accesskey="1">Job Control Basics</a></li> +<li><a href="#Job-Control-Builtins" accesskey="2">Job Control Builtins</a></li> +<li><a href="#Job-Control-Variables" accesskey="3">Job Control Variables</a></li> +</ul> +<hr> +<div class="section" id="Job-Control-Basics"> +<div class="header"> +<p> +Next: <a href="#Job-Control-Builtins" accesskey="n" rel="next">Job Control Builtins</a>, Up: <a href="#Job-Control" accesskey="u" rel="up">Job Control</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Job-Control-Basics-1"></span><h3 class="section">7.1 Job Control Basics</h3> +<span id="index-job-control-1"></span> +<span id="index-foreground"></span> +<span id="index-background"></span> +<span id="index-suspending-jobs"></span> + +<p>Job control +refers to the ability to selectively stop (suspend) +the execution of processes and continue (resume) +their execution at a later point. A user typically employs +this facility via an interactive interface supplied jointly +by the operating system kernel’s terminal driver and Bash. +</p> +<p>The shell associates a <var>job</var> with each pipeline. It keeps a +table of currently executing jobs, which may be listed with the +<code>jobs</code> command. When Bash starts a job +asynchronously, it prints a line that looks +like: +</p><div class="example"> +<pre class="example">[1] 25647 +</pre></div> +<p>indicating that this job is job number 1 and that the process <small>ID</small> +of the last process in the pipeline associated with this job is +25647. All of the processes in a single pipeline are members of +the same job. Bash uses the <var>job</var> abstraction as the +basis for job control. +</p> +<p>To facilitate the implementation of the user interface to job +control, the operating system maintains the notion of a current terminal +process group <small>ID</small>. Members of this process group (processes whose +process group <small>ID</small> is equal to the current terminal process group +<small>ID</small>) receive keyboard-generated signals such as <code>SIGINT</code>. +These processes are said to be in the foreground. Background +processes are those whose process group <small>ID</small> differs from the +terminal’s; such processes are immune to keyboard-generated +signals. Only foreground processes are allowed to read from or, if +the user so specifies with <code>stty tostop</code>, write to the terminal. +Background processes which attempt to +read from (write to when <code>stty tostop</code> is in effect) the +terminal are sent a <code>SIGTTIN</code> (<code>SIGTTOU</code>) +signal by the kernel’s terminal driver, +which, unless caught, suspends the process. +</p> +<p>If the operating system on which Bash is running supports +job control, Bash contains facilities to use it. Typing the +<em>suspend</em> character (typically ‘<samp>^Z</samp>’, Control-Z) while a +process is running causes that process to be stopped and returns +control to Bash. Typing the <em>delayed suspend</em> character +(typically ‘<samp>^Y</samp>’, Control-Y) causes the process to be stopped +when it attempts to read input from the terminal, and control to +be returned to Bash. The user then manipulates the state of +this job, using the <code>bg</code> command to continue it in the +background, the <code>fg</code> command to continue it in the +foreground, or the <code>kill</code> command to kill it. A ‘<samp>^Z</samp>’ +takes effect immediately, and has the additional side effect of +causing pending output and typeahead to be discarded. +</p> +<p>There are a number of ways to refer to a job in the shell. The +character ‘<samp>%</samp>’ introduces a job specification (<em>jobspec</em>). +</p> +<p>Job number <code>n</code> may be referred to as ‘<samp>%n</samp>’. +The symbols ‘<samp>%%</samp>’ and ‘<samp>%+</samp>’ refer to the shell’s notion of the +current job, which is the last job stopped while it was in the foreground +or started in the background. +A single ‘<samp>%</samp>’ (with no accompanying job specification) also refers +to the current job. +The previous job may be referenced using ‘<samp>%-</samp>’. +If there is only a single job, ‘<samp>%+</samp>’ and ‘<samp>%-</samp>’ can both be used +to refer to that job. +In output pertaining to jobs (e.g., the output of the <code>jobs</code> +command), the current job is always flagged with a ‘<samp>+</samp>’, and the +previous job with a ‘<samp>-</samp>’. +</p> +<p>A job may also be referred to +using a prefix of the name used to start it, or using a substring +that appears in its command line. For example, ‘<samp>%ce</samp>’ refers +to a stopped job whose command name begins with ‘<samp>ce</samp>’. +Using ‘<samp>%?ce</samp>’, on the +other hand, refers to any job containing the string ‘<samp>ce</samp>’ in +its command line. If the prefix or substring matches more than one job, +Bash reports an error. +</p> +<p>Simply naming a job can be used to bring it into the foreground: +‘<samp>%1</samp>’ is a synonym for ‘<samp>fg %1</samp>’, bringing job 1 from the +background into the foreground. Similarly, ‘<samp>%1 &</samp>’ resumes +job 1 in the background, equivalent to ‘<samp>bg %1</samp>’ +</p> +<p>The shell learns immediately whenever a job changes state. +Normally, Bash waits until it is about to print a prompt +before reporting changes in a job’s status so as to not interrupt +any other output. +If the <samp>-b</samp> option to the <code>set</code> builtin is enabled, +Bash reports such changes immediately (see <a href="#The-Set-Builtin">The Set Builtin</a>). +Any trap on <code>SIGCHLD</code> is executed for each child process +that exits. +</p> +<p>If an attempt to exit Bash is made while jobs are stopped, (or running, if +the <code>checkjobs</code> option is enabled – see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>), the +shell prints a warning message, and if the <code>checkjobs</code> option is +enabled, lists the jobs and their statuses. +The <code>jobs</code> command may then be used to inspect their status. +If a second attempt to exit is made without an intervening command, +Bash does not print another warning, and any stopped jobs are terminated. +</p> +<p>When the shell is waiting for a job or process using the <code>wait</code> +builtin, and job control is enabled, <code>wait</code> will return when the +job changes state. The <samp>-f</samp> option causes <code>wait</code> to wait +until the job or process terminates before returning. +</p> +<hr> +</div> +<div class="section" id="Job-Control-Builtins"> +<div class="header"> +<p> +Next: <a href="#Job-Control-Variables" accesskey="n" rel="next">Job Control Variables</a>, Previous: <a href="#Job-Control-Basics" accesskey="p" rel="prev">Job Control Basics</a>, Up: <a href="#Job-Control" accesskey="u" rel="up">Job Control</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Job-Control-Builtins-1"></span><h3 class="section">7.2 Job Control Builtins</h3> + +<dl compact="compact"> +<dt id='index-bg'><span><code>bg</code><a href='#index-bg' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">bg [<var>jobspec</var> …] +</pre></div> + +<p>Resume each suspended job <var>jobspec</var> in the background, as if it +had been started with ‘<samp>&</samp>’. +If <var>jobspec</var> is not supplied, the current job is used. +The return status is zero unless it is run when job control is not +enabled, or, when run with job control enabled, any +<var>jobspec</var> was not found or specifies a job +that was started without job control. +</p> +</dd> +<dt id='index-fg'><span><code>fg</code><a href='#index-fg' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">fg [<var>jobspec</var>] +</pre></div> + +<p>Resume the job <var>jobspec</var> in the foreground and make it the current job. +If <var>jobspec</var> is not supplied, the current job is used. +The return status is that of the command placed into the foreground, +or non-zero if run when job control is disabled or, when run with +job control enabled, <var>jobspec</var> does not specify a valid job or +<var>jobspec</var> specifies a job that was started without job control. +</p> +</dd> +<dt id='index-jobs'><span><code>jobs</code><a href='#index-jobs' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">jobs [-lnprs] [<var>jobspec</var>] +jobs -x <var>command</var> [<var>arguments</var>] +</pre></div> + +<p>The first form lists the active jobs. The options have the +following meanings: +</p> +<dl compact="compact"> +<dt><span><code>-l</code></span></dt> +<dd><p>List process <small>ID</small>s in addition to the normal information. +</p> +</dd> +<dt><span><code>-n</code></span></dt> +<dd><p>Display information only about jobs that have changed status since +the user was last notified of their status. +</p> +</dd> +<dt><span><code>-p</code></span></dt> +<dd><p>List only the process <small>ID</small> of the job’s process group leader. +</p> +</dd> +<dt><span><code>-r</code></span></dt> +<dd><p>Display only running jobs. +</p> +</dd> +<dt><span><code>-s</code></span></dt> +<dd><p>Display only stopped jobs. +</p></dd> +</dl> + +<p>If <var>jobspec</var> is given, +output is restricted to information about that job. +If <var>jobspec</var> is not supplied, the status of all jobs is +listed. +</p> +<p>If the <samp>-x</samp> option is supplied, <code>jobs</code> replaces any +<var>jobspec</var> found in <var>command</var> or <var>arguments</var> with the +corresponding process group <small>ID</small>, and executes <var>command</var>, +passing it <var>argument</var>s, returning its exit status. +</p> +</dd> +<dt id='index-kill'><span><code>kill</code><a href='#index-kill' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">kill [-s <var>sigspec</var>] [-n <var>signum</var>] [-<var>sigspec</var>] <var>jobspec</var> or <var>pid</var> +kill -l|-L [<var>exit_status</var>] +</pre></div> + +<p>Send a signal specified by <var>sigspec</var> or <var>signum</var> to the process +named by job specification <var>jobspec</var> or process <small>ID</small> <var>pid</var>. +<var>sigspec</var> is either a case-insensitive signal name such as +<code>SIGINT</code> (with or without the <code>SIG</code> prefix) +or a signal number; <var>signum</var> is a signal number. +If <var>sigspec</var> and <var>signum</var> are not present, <code>SIGTERM</code> is used. +The <samp>-l</samp> option lists the signal names. +If any arguments are supplied when <samp>-l</samp> is given, the names of the +signals corresponding to the arguments are listed, and the return status +is zero. +<var>exit_status</var> is a number specifying a signal number or the exit +status of a process terminated by a signal. +The <samp>-L</samp> option is equivalent to <samp>-l</samp>. +The return status is zero if at least one signal was successfully sent, +or non-zero if an error occurs or an invalid option is encountered. +</p> +</dd> +<dt id='index-wait'><span><code>wait</code><a href='#index-wait' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">wait [-fn] [-p <var>varname</var>] [<var>jobspec</var> or <var>pid</var> …] +</pre></div> + +<p>Wait until the child process specified by each process <small>ID</small> <var>pid</var> +or job specification <var>jobspec</var> exits and return the exit status of the +last command waited for. +If a job spec is given, all processes in the job are waited for. +If no arguments are given, +<code>wait</code> waits for all running background jobs and +the last-executed process substitution, if its process id is the same as +<var>$!</var>, +and the return status is zero. +If the <samp>-n</samp> option is supplied, <code>wait</code> waits for a single job +from the list of <var>pid</var>s or <var>jobspec</var>s or, if no arguments are +supplied, any job, +to complete and returns its exit status. +If none of the supplied arguments is a child of the shell, or if no arguments +are supplied and the shell has no unwaited-for children, the exit status +is 127. +If the <samp>-p</samp> option is supplied, the process or job identifier of the job +for which the exit status is returned is assigned to the variable +<var>varname</var> named by the option argument. +The variable will be unset initially, before any assignment. +This is useful only when the <samp>-n</samp> option is supplied. +Supplying the <samp>-f</samp> option, when job control is enabled, +forces <code>wait</code> to wait for each <var>pid</var> or <var>jobspec</var> to +terminate before returning its status, instead of returning when it changes +status. +If neither <var>jobspec</var> nor <var>pid</var> specifies an active child process +of the shell, the return status is 127. +If <code>wait</code> is interrupted by a signal, the return status will be greater +than 128, as described above (see <a href="#Signals">Signals</a>). +Otherwise, the return status is the exit status +of the last process or job waited for. +</p> +</dd> +<dt id='index-disown'><span><code>disown</code><a href='#index-disown' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">disown [-ar] [-h] [<var>jobspec</var> … | <var>pid</var> … ] +</pre></div> + +<p>Without options, remove each <var>jobspec</var> from the table of +active jobs. +If the <samp>-h</samp> option is given, the job is not removed from the table, +but is marked so that <code>SIGHUP</code> is not sent to the job if the shell +receives a <code>SIGHUP</code>. +If <var>jobspec</var> is not present, and neither the <samp>-a</samp> nor the +<samp>-r</samp> option is supplied, the current job is used. +If no <var>jobspec</var> is supplied, the <samp>-a</samp> option means to remove or +mark all jobs; the <samp>-r</samp> option without a <var>jobspec</var> +argument restricts operation to running jobs. +</p> +</dd> +<dt id='index-suspend'><span><code>suspend</code><a href='#index-suspend' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">suspend [-f] +</pre></div> + +<p>Suspend the execution of this shell until it receives a +<code>SIGCONT</code> signal. +A login shell, +or a shell without job control enabled, +cannot be suspended; the <samp>-f</samp> +option can be used to override this and force the suspension. +The return status is 0 unless the shell is a login shell +or job control is not enabled +and +<samp>-f</samp> +is not supplied. +</p> +</dd> +</dl> + +<p>When job control is not active, the <code>kill</code> and <code>wait</code> +builtins do not accept <var>jobspec</var> arguments. They must be +supplied process <small>ID</small>s. +</p> +<hr> +</div> +<div class="section" id="Job-Control-Variables"> +<div class="header"> +<p> +Previous: <a href="#Job-Control-Builtins" accesskey="p" rel="prev">Job Control Builtins</a>, Up: <a href="#Job-Control" accesskey="u" rel="up">Job Control</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Job-Control-Variables-1"></span><h3 class="section">7.3 Job Control Variables</h3> + +<dl compact="compact"> +<dt id='index-auto_005fresume'><span><code>auto_resume</code><a href='#index-auto_005fresume' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This variable controls how the shell interacts with the user and +job control. If this variable exists then single word simple +commands without redirections are treated as candidates for resumption +of an existing job. There is no ambiguity allowed; if there is +more than one job beginning with the string typed, then +the most recently accessed job will be selected. +The name of a stopped job, in this context, is the command line +used to start it. If this variable is set to the value ‘<samp>exact</samp>’, +the string supplied must match the name of a stopped job exactly; +if set to ‘<samp>substring</samp>’, +the string supplied needs to match a substring of the name of a +stopped job. The ‘<samp>substring</samp>’ value provides functionality +analogous to the ‘<samp>%?</samp>’ job <small>ID</small> (see <a href="#Job-Control-Basics">Job Control Basics</a>). +If set to any other value, the supplied string must +be a prefix of a stopped job’s name; this provides functionality +analogous to the ‘<samp>%</samp>’ job <small>ID</small>. +</p> +</dd> +</dl> + +<span id="index-Readline_002c-how-to-use"></span> + + + + +<hr> +</div> +</div> +<div class="chapter" id="Command-Line-Editing"> +<div class="header"> +<p> +Next: <a href="#Using-History-Interactively" accesskey="n" rel="next">Using History Interactively</a>, Previous: <a href="#Job-Control" accesskey="p" rel="prev">Job Control</a>, Up: <a href="#Top" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Command-Line-Editing-1"></span><h2 class="chapter">8 Command Line Editing</h2> + +<p>This chapter describes the basic features of the <small>GNU</small> +command line editing interface. +Command line editing is provided by the Readline library, which is +used by several different programs, including Bash. +Command line editing is enabled by default when using an interactive shell, +unless the <samp>--noediting</samp> option is supplied at shell invocation. +Line editing is also used when using the <samp>-e</samp> option to the +<code>read</code> builtin command (see <a href="#Bash-Builtins">Bash Builtin Commands</a>). +By default, the line editing commands are similar to those of Emacs. +A vi-style line editing interface is also available. +Line editing can be enabled at any time using the <samp>-o emacs</samp> or +<samp>-o vi</samp> options to the <code>set</code> builtin command +(see <a href="#The-Set-Builtin">The Set Builtin</a>), or disabled using the <samp>+o emacs</samp> or +<samp>+o vi</samp> options to <code>set</code>. +</p> + +<ul class="section-toc"> +<li><a href="#Introduction-and-Notation" accesskey="1">Introduction to Line Editing</a></li> +<li><a href="#Readline-Interaction" accesskey="2">Readline Interaction</a></li> +<li><a href="#Readline-Init-File" accesskey="3">Readline Init File</a></li> +<li><a href="#Bindable-Readline-Commands" accesskey="4">Bindable Readline Commands</a></li> +<li><a href="#Readline-vi-Mode" accesskey="5">Readline vi Mode</a></li> +<li><a href="#Programmable-Completion" accesskey="6">Programmable Completion</a></li> +<li><a href="#Programmable-Completion-Builtins" accesskey="7">Programmable Completion Builtins</a></li> +<li><a href="#A-Programmable-Completion-Example" accesskey="8">A Programmable Completion Example</a></li> +</ul> +<hr> +<div class="section" id="Introduction-and-Notation"> +<div class="header"> +<p> +Next: <a href="#Readline-Interaction" accesskey="n" rel="next">Readline Interaction</a>, Up: <a href="#Command-Line-Editing" accesskey="u" rel="up">Command Line Editing</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Introduction-to-Line-Editing"></span><h3 class="section">8.1 Introduction to Line Editing</h3> + +<p>The following paragraphs describe the notation used to represent +keystrokes. +</p> +<p>The text <kbd>C-k</kbd> is read as ‘Control-K’ and describes the character +produced when the <tt class="key">k</tt> key is pressed while the Control key +is depressed. +</p> +<p>The text <kbd>M-k</kbd> is read as ‘Meta-K’ and describes the character +produced when the Meta key (if you have one) is depressed, and the <tt class="key">k</tt> +key is pressed. +The Meta key is labeled <tt class="key">ALT</tt> on many keyboards. +On keyboards with two keys labeled <tt class="key">ALT</tt> (usually to either side of +the space bar), the <tt class="key">ALT</tt> on the left side is generally set to +work as a Meta key. +The <tt class="key">ALT</tt> key on the right may also be configured to work as a +Meta key or may be configured as some other modifier, such as a +Compose key for typing accented characters. +</p> +<p>If you do not have a Meta or <tt class="key">ALT</tt> key, or another key working as +a Meta key, the identical keystroke can be generated by typing <tt class="key">ESC</tt> +<em>first</em>, and then typing <tt class="key">k</tt>. +Either process is known as <em>metafying</em> the <tt class="key">k</tt> key. +</p> +<p>The text <kbd>M-C-k</kbd> is read as ‘Meta-Control-k’ and describes the +character produced by <em>metafying</em> <kbd>C-k</kbd>. +</p> +<p>In addition, several keys have their own names. Specifically, +<tt class="key">DEL</tt>, <tt class="key">ESC</tt>, <tt class="key">LFD</tt>, <tt class="key">SPC</tt>, <tt class="key">RET</tt>, and <tt class="key">TAB</tt> all +stand for themselves when seen in this text, or in an init file +(see <a href="#Readline-Init-File">Readline Init File</a>). +If your keyboard lacks a <tt class="key">LFD</tt> key, typing <tt class="key">C-j</tt> will +produce the desired character. +The <tt class="key">RET</tt> key may be labeled <tt class="key">Return</tt> or <tt class="key">Enter</tt> on +some keyboards. +</p> +<hr> +</div> +<div class="section" id="Readline-Interaction"> +<div class="header"> +<p> +Next: <a href="#Readline-Init-File" accesskey="n" rel="next">Readline Init File</a>, Previous: <a href="#Introduction-and-Notation" accesskey="p" rel="prev">Introduction to Line Editing</a>, Up: <a href="#Command-Line-Editing" accesskey="u" rel="up">Command Line Editing</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Readline-Interaction-1"></span><h3 class="section">8.2 Readline Interaction</h3> +<span id="index-interaction_002c-readline"></span> + +<p>Often during an interactive session you type in a long line of text, +only to notice that the first word on the line is misspelled. The +Readline library gives you a set of commands for manipulating the text +as you type it in, allowing you to just fix your typo, and not forcing +you to retype the majority of the line. Using these editing commands, +you move the cursor to the place that needs correction, and delete or +insert the text of the corrections. Then, when you are satisfied with +the line, you simply press <tt class="key">RET</tt>. You do not have to be at the +end of the line to press <tt class="key">RET</tt>; the entire line is accepted +regardless of the location of the cursor within the line. +</p> + +<ul class="section-toc"> +<li><a href="#Readline-Bare-Essentials" accesskey="1">Readline Bare Essentials</a></li> +<li><a href="#Readline-Movement-Commands" accesskey="2">Readline Movement Commands</a></li> +<li><a href="#Readline-Killing-Commands" accesskey="3">Readline Killing Commands</a></li> +<li><a href="#Readline-Arguments" accesskey="4">Readline Arguments</a></li> +<li><a href="#Searching" accesskey="5">Searching for Commands in the History</a></li> +</ul> +<hr> +<div class="subsection" id="Readline-Bare-Essentials"> +<div class="header"> +<p> +Next: <a href="#Readline-Movement-Commands" accesskey="n" rel="next">Readline Movement Commands</a>, Up: <a href="#Readline-Interaction" accesskey="u" rel="up">Readline Interaction</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Readline-Bare-Essentials-1"></span><h4 class="subsection">8.2.1 Readline Bare Essentials</h4> +<span id="index-notation_002c-readline"></span> +<span id="index-command-editing"></span> +<span id="index-editing-command-lines"></span> + +<p>In order to enter characters into the line, simply type them. The typed +character appears where the cursor was, and then the cursor moves one +space to the right. If you mistype a character, you can use your +erase character to back up and delete the mistyped character. +</p> +<p>Sometimes you may mistype a character, and +not notice the error until you have typed several other characters. In +that case, you can type <kbd>C-b</kbd> to move the cursor to the left, and then +correct your mistake. Afterwards, you can move the cursor to the right +with <kbd>C-f</kbd>. +</p> +<p>When you add text in the middle of a line, you will notice that characters +to the right of the cursor are ‘pushed over’ to make room for the text +that you have inserted. Likewise, when you delete text behind the cursor, +characters to the right of the cursor are ‘pulled back’ to fill in the +blank space created by the removal of the text. A list of the bare +essentials for editing the text of an input line follows. +</p> +<dl compact="compact"> +<dt><span><kbd>C-b</kbd></span></dt> +<dd><p>Move back one character. +</p></dd> +<dt><span><kbd>C-f</kbd></span></dt> +<dd><p>Move forward one character. +</p></dd> +<dt><span><tt class="key">DEL</tt> or <tt class="key">Backspace</tt></span></dt> +<dd><p>Delete the character to the left of the cursor. +</p></dd> +<dt><span><kbd>C-d</kbd></span></dt> +<dd><p>Delete the character underneath the cursor. +</p></dd> +<dt><span>Printing characters<!-- /@w --></span></dt> +<dd><p>Insert the character into the line at the cursor. +</p></dd> +<dt><span><kbd>C-_</kbd> or <kbd>C-x C-u</kbd></span></dt> +<dd><p>Undo the last editing command. You can undo all the way back to an +empty line. +</p></dd> +</dl> + +<p>(Depending on your configuration, the <tt class="key">Backspace</tt> key might be set to +delete the character to the left of the cursor and the <tt class="key">DEL</tt> key set +to delete the character underneath the cursor, like <kbd>C-d</kbd>, rather +than the character to the left of the cursor.) +</p> +<hr> +</div> +<div class="subsection" id="Readline-Movement-Commands"> +<div class="header"> +<p> +Next: <a href="#Readline-Killing-Commands" accesskey="n" rel="next">Readline Killing Commands</a>, Previous: <a href="#Readline-Bare-Essentials" accesskey="p" rel="prev">Readline Bare Essentials</a>, Up: <a href="#Readline-Interaction" accesskey="u" rel="up">Readline Interaction</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Readline-Movement-Commands-1"></span><h4 class="subsection">8.2.2 Readline Movement Commands</h4> + + +<p>The above table describes the most basic keystrokes that you need +in order to do editing of the input line. For your convenience, many +other commands have been added in addition to <kbd>C-b</kbd>, <kbd>C-f</kbd>, +<kbd>C-d</kbd>, and <tt class="key">DEL</tt>. Here are some commands for moving more rapidly +about the line. +</p> +<dl compact="compact"> +<dt><span><kbd>C-a</kbd></span></dt> +<dd><p>Move to the start of the line. +</p></dd> +<dt><span><kbd>C-e</kbd></span></dt> +<dd><p>Move to the end of the line. +</p></dd> +<dt><span><kbd>M-f</kbd></span></dt> +<dd><p>Move forward a word, where a word is composed of letters and digits. +</p></dd> +<dt><span><kbd>M-b</kbd></span></dt> +<dd><p>Move backward a word. +</p></dd> +<dt><span><kbd>C-l</kbd></span></dt> +<dd><p>Clear the screen, reprinting the current line at the top. +</p></dd> +</dl> + +<p>Notice how <kbd>C-f</kbd> moves forward a character, while <kbd>M-f</kbd> moves +forward a word. It is a loose convention that control keystrokes +operate on characters while meta keystrokes operate on words. +</p> +<hr> +</div> +<div class="subsection" id="Readline-Killing-Commands"> +<div class="header"> +<p> +Next: <a href="#Readline-Arguments" accesskey="n" rel="next">Readline Arguments</a>, Previous: <a href="#Readline-Movement-Commands" accesskey="p" rel="prev">Readline Movement Commands</a>, Up: <a href="#Readline-Interaction" accesskey="u" rel="up">Readline Interaction</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Readline-Killing-Commands-1"></span><h4 class="subsection">8.2.3 Readline Killing Commands</h4> + +<span id="index-killing-text"></span> +<span id="index-yanking-text"></span> + +<p><em>Killing</em> text means to delete the text from the line, but to save +it away for later use, usually by <em>yanking</em> (re-inserting) +it back into the line. +(‘Cut’ and ‘paste’ are more recent jargon for ‘kill’ and ‘yank’.) +</p> +<p>If the description for a command says that it ‘kills’ text, then you can +be sure that you can get the text back in a different (or the same) +place later. +</p> +<p>When you use a kill command, the text is saved in a <em>kill-ring</em>. +Any number of consecutive kills save all of the killed text together, so +that when you yank it back, you get it all. The kill +ring is not line specific; the text that you killed on a previously +typed line is available to be yanked back later, when you are typing +another line. +<span id="index-kill-ring"></span> +</p> +<p>Here is the list of commands for killing text. +</p> +<dl compact="compact"> +<dt><span><kbd>C-k</kbd></span></dt> +<dd><p>Kill the text from the current cursor position to the end of the line. +</p> +</dd> +<dt><span><kbd>M-d</kbd></span></dt> +<dd><p>Kill from the cursor to the end of the current word, or, if between +words, to the end of the next word. +Word boundaries are the same as those used by <kbd>M-f</kbd>. +</p> +</dd> +<dt><span><kbd>M-<span class="key">DEL</span></kbd></span></dt> +<dd><p>Kill from the cursor to the start of the current word, or, if between +words, to the start of the previous word. +Word boundaries are the same as those used by <kbd>M-b</kbd>. +</p> +</dd> +<dt><span><kbd>C-w</kbd></span></dt> +<dd><p>Kill from the cursor to the previous whitespace. This is different than +<kbd>M-<span class="key">DEL</span></kbd> because the word boundaries differ. +</p> +</dd> +</dl> + +<p>Here is how to <em>yank</em> the text back into the line. Yanking +means to copy the most-recently-killed text from the kill buffer. +</p> +<dl compact="compact"> +<dt><span><kbd>C-y</kbd></span></dt> +<dd><p>Yank the most recently killed text back into the buffer at the cursor. +</p> +</dd> +<dt><span><kbd>M-y</kbd></span></dt> +<dd><p>Rotate the kill-ring, and yank the new top. You can only do this if +the prior command is <kbd>C-y</kbd> or <kbd>M-y</kbd>. +</p></dd> +</dl> + +<hr> +</div> +<div class="subsection" id="Readline-Arguments"> +<div class="header"> +<p> +Next: <a href="#Searching" accesskey="n" rel="next">Searching for Commands in the History</a>, Previous: <a href="#Readline-Killing-Commands" accesskey="p" rel="prev">Readline Killing Commands</a>, Up: <a href="#Readline-Interaction" accesskey="u" rel="up">Readline Interaction</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Readline-Arguments-1"></span><h4 class="subsection">8.2.4 Readline Arguments</h4> + +<p>You can pass numeric arguments to Readline commands. Sometimes the +argument acts as a repeat count, other times it is the <i>sign</i> of the +argument that is significant. If you pass a negative argument to a +command which normally acts in a forward direction, that command will +act in a backward direction. For example, to kill text back to the +start of the line, you might type ‘<samp>M-- C-k</samp>’. +</p> +<p>The general way to pass numeric arguments to a command is to type meta +digits before the command. If the first ‘digit’ typed is a minus +sign (‘<samp>-</samp>’), then the sign of the argument will be negative. Once +you have typed one meta digit to get the argument started, you can type +the remainder of the digits, and then the command. For example, to give +the <kbd>C-d</kbd> command an argument of 10, you could type ‘<samp>M-1 0 C-d</samp>’, +which will delete the next ten characters on the input line. +</p> +<hr> +</div> +<div class="subsection" id="Searching"> +<div class="header"> +<p> +Previous: <a href="#Readline-Arguments" accesskey="p" rel="prev">Readline Arguments</a>, Up: <a href="#Readline-Interaction" accesskey="u" rel="up">Readline Interaction</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Searching-for-Commands-in-the-History"></span><h4 class="subsection">8.2.5 Searching for Commands in the History</h4> + +<p>Readline provides commands for searching through the command history +(see <a href="#Bash-History-Facilities">Bash History Facilities</a>) +for lines containing a specified string. +There are two search modes: <em>incremental</em> and <em>non-incremental</em>. +</p> +<p>Incremental searches begin before the user has finished typing the +search string. +As each character of the search string is typed, Readline displays +the next entry from the history matching the string typed so far. +An incremental search requires only as many characters as needed to +find the desired history entry. +To search backward in the history for a particular string, type +<kbd>C-r</kbd>. Typing <kbd>C-s</kbd> searches forward through the history. +The characters present in the value of the <code>isearch-terminators</code> variable +are used to terminate an incremental search. +If that variable has not been assigned a value, the <tt class="key">ESC</tt> and +<kbd>C-J</kbd> characters will terminate an incremental search. +<kbd>C-g</kbd> will abort an incremental search and restore the original line. +When the search is terminated, the history entry containing the +search string becomes the current line. +</p> +<p>To find other matching entries in the history list, type <kbd>C-r</kbd> or +<kbd>C-s</kbd> as appropriate. +This will search backward or forward in the history for the next +entry matching the search string typed so far. +Any other key sequence bound to a Readline command will terminate +the search and execute that command. +For instance, a <tt class="key">RET</tt> will terminate the search and accept +the line, thereby executing the command from the history list. +A movement command will terminate the search, make the last line found +the current line, and begin editing. +</p> +<p>Readline remembers the last incremental search string. If two +<kbd>C-r</kbd>s are typed without any intervening characters defining a new +search string, any remembered search string is used. +</p> +<p>Non-incremental searches read the entire search string before starting +to search for matching history lines. The search string may be +typed by the user or be part of the contents of the current line. +</p> +<hr> +</div> +</div> +<div class="section" id="Readline-Init-File"> +<div class="header"> +<p> +Next: <a href="#Bindable-Readline-Commands" accesskey="n" rel="next">Bindable Readline Commands</a>, Previous: <a href="#Readline-Interaction" accesskey="p" rel="prev">Readline Interaction</a>, Up: <a href="#Command-Line-Editing" accesskey="u" rel="up">Command Line Editing</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Readline-Init-File-1"></span><h3 class="section">8.3 Readline Init File</h3> +<span id="index-initialization-file_002c-readline"></span> + +<p>Although the Readline library comes with a set of Emacs-like +keybindings installed by default, it is possible to use a different set +of keybindings. +Any user can customize programs that use Readline by putting +commands in an <em>inputrc</em> file, +conventionally in their home directory. +The name of this +file is taken from the value of the shell variable <code>INPUTRC</code>. If +that variable is unset, the default is <samp>~/.inputrc</samp>. If that +file does not exist or cannot be read, the ultimate default is +<samp>/etc/inputrc</samp>. +The <code>bind</code><!-- /@w --> builtin command can also be used to set Readline +keybindings and variables. +See <a href="#Bash-Builtins">Bash Builtin Commands</a>. +</p> +<p>When a program which uses the Readline library starts up, the +init file is read, and the key bindings are set. +</p> +<p>In addition, the <code>C-x C-r</code> command re-reads this init file, thus +incorporating any changes that you might have made to it. +</p> + +<ul class="section-toc"> +<li><a href="#Readline-Init-File-Syntax" accesskey="1">Readline Init File Syntax</a></li> +<li><a href="#Conditional-Init-Constructs" accesskey="2">Conditional Init Constructs</a></li> +<li><a href="#Sample-Init-File" accesskey="3">Sample Init File</a></li> +</ul> +<hr> +<div class="subsection" id="Readline-Init-File-Syntax"> +<div class="header"> +<p> +Next: <a href="#Conditional-Init-Constructs" accesskey="n" rel="next">Conditional Init Constructs</a>, Up: <a href="#Readline-Init-File" accesskey="u" rel="up">Readline Init File</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Readline-Init-File-Syntax-1"></span><h4 class="subsection">8.3.1 Readline Init File Syntax</h4> + +<p>There are only a few basic constructs allowed in the +Readline init file. Blank lines are ignored. +Lines beginning with a ‘<samp>#</samp>’ are comments. +Lines beginning with a ‘<samp>$</samp>’ indicate conditional +constructs (see <a href="#Conditional-Init-Constructs">Conditional Init Constructs</a>). Other lines +denote variable settings and key bindings. +</p> +<dl compact="compact"> +<dt><span>Variable Settings</span></dt> +<dd><p>You can modify the run-time behavior of Readline by +altering the values of variables in Readline +using the <code>set</code> command within the init file. +The syntax is simple: +</p> +<div class="example"> +<pre class="example">set <var>variable</var> <var>value</var> +</pre></div> + +<p>Here, for example, is how to +change from the default Emacs-like key binding to use +<code>vi</code> line editing commands: +</p> +<div class="example"> +<pre class="example">set editing-mode vi +</pre></div> + +<p>Variable names and values, where appropriate, are recognized without regard +to case. Unrecognized variable names are ignored. +</p> +<p>Boolean variables (those that can be set to on or off) are set to on if +the value is null or empty, <var>on</var> (case-insensitive), or 1. Any other +value results in the variable being set to off. +</p> +<p>The <code>bind <span class="nolinebreak">-V</span></code><!-- /@w --> command lists the current Readline variable names +and values. See <a href="#Bash-Builtins">Bash Builtin Commands</a>. +</p> +<p>A great deal of run-time behavior is changeable with the following +variables. +</p> +<span id="index-variables_002c-readline"></span> +<dl compact="compact"> +<dt id='index-active_002dregion_002dstart_002dcolor'><span><code>active-region-start-color</code><a href='#index-active_002dregion_002dstart_002dcolor' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A string variable that controls the text color and background when displaying +the text in the active region (see the description of +<code>enable-active-region</code> below). +This string must not take up any physical character positions on the display, +so it should consist only of terminal escape sequences. +It is output to the terminal before displaying the text in the active region. +This variable is reset to the default value whenever the terminal type changes. +The default value is the string that puts the terminal in standout mode, +as obtained from the terminal’s terminfo description. +A sample value might be ‘<samp>\e[01;33m</samp>’. +</p> +</dd> +<dt id='index-active_002dregion_002dend_002dcolor'><span><code>active-region-end-color</code><a href='#index-active_002dregion_002dend_002dcolor' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A string variable that "undoes" the effects of <code>active-region-start-color</code> +and restores "normal" terminal display appearance after displaying text +in the active region. +This string must not take up any physical character positions on the display, +so it should consist only of terminal escape sequences. +It is output to the terminal after displaying the text in the active region. +This variable is reset to the default value whenever the terminal type changes. +The default value is the string that restores the terminal from standout mode, +as obtained from the terminal’s terminfo description. +A sample value might be ‘<samp>\e[0m</samp>’. +</p> +</dd> +<dt id='index-bell_002dstyle'><span><code>bell-style</code><a href='#index-bell_002dstyle' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Controls what happens when Readline wants to ring the terminal bell. +If set to ‘<samp>none</samp>’, Readline never rings the bell. If set to +‘<samp>visible</samp>’, Readline uses a visible bell if one is available. +If set to ‘<samp>audible</samp>’ (the default), Readline attempts to ring +the terminal’s bell. +</p> +</dd> +<dt id='index-bind_002dtty_002dspecial_002dchars'><span><code>bind-tty-special-chars</code><a href='#index-bind_002dtty_002dspecial_002dchars' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to ‘<samp>on</samp>’ (the default), Readline attempts to bind the control +characters treated specially by the kernel’s terminal driver to their +Readline equivalents. +</p> +</dd> +<dt id='index-blink_002dmatching_002dparen'><span><code>blink-matching-paren</code><a href='#index-blink_002dmatching_002dparen' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to ‘<samp>on</samp>’, Readline attempts to briefly move the cursor to an +opening parenthesis when a closing parenthesis is inserted. The default +is ‘<samp>off</samp>’. +</p> +</dd> +<dt id='index-colored_002dcompletion_002dprefix'><span><code>colored-completion-prefix</code><a href='#index-colored_002dcompletion_002dprefix' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to ‘<samp>on</samp>’, when listing completions, Readline displays the +common prefix of the set of possible completions using a different color. +The color definitions are taken from the value of the <code>LS_COLORS</code> +environment variable. +If there is a color definition in <code>LS_COLORS</code> for the custom suffix +‘<samp>readline-colored-completion-prefix</samp>’, Readline uses this color for +the common prefix instead of its default. +The default is ‘<samp>off</samp>’. +</p> +</dd> +<dt id='index-colored_002dstats'><span><code>colored-stats</code><a href='#index-colored_002dstats' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to ‘<samp>on</samp>’, Readline displays possible completions using different +colors to indicate their file type. +The color definitions are taken from the value of the <code>LS_COLORS</code> +environment variable. +The default is ‘<samp>off</samp>’. +</p> +</dd> +<dt id='index-comment_002dbegin'><span><code>comment-begin</code><a href='#index-comment_002dbegin' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The string to insert at the beginning of the line when the +<code>insert-comment</code> command is executed. The default value +is <code>"#"</code>. +</p> +</dd> +<dt id='index-completion_002ddisplay_002dwidth'><span><code>completion-display-width</code><a href='#index-completion_002ddisplay_002dwidth' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The number of screen columns used to display possible matches +when performing completion. +The value is ignored if it is less than 0 or greater than the terminal +screen width. +A value of 0 will cause matches to be displayed one per line. +The default value is -1. +</p> +</dd> +<dt id='index-completion_002dignore_002dcase'><span><code>completion-ignore-case</code><a href='#index-completion_002dignore_002dcase' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to ‘<samp>on</samp>’, Readline performs filename matching and completion +in a case-insensitive fashion. +The default value is ‘<samp>off</samp>’. +</p> +</dd> +<dt id='index-completion_002dmap_002dcase'><span><code>completion-map-case</code><a href='#index-completion_002dmap_002dcase' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to ‘<samp>on</samp>’, and <var>completion-ignore-case</var> is enabled, Readline +treats hyphens (‘<samp>-</samp>’) and underscores (‘<samp>_</samp>’) as equivalent when +performing case-insensitive filename matching and completion. +The default value is ‘<samp>off</samp>’. +</p> +</dd> +<dt id='index-completion_002dprefix_002ddisplay_002dlength'><span><code>completion-prefix-display-length</code><a href='#index-completion_002dprefix_002ddisplay_002dlength' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The length in characters of the common prefix of a list of possible +completions that is displayed without modification. When set to a +value greater than zero, common prefixes longer than this value are +replaced with an ellipsis when displaying possible completions. +</p> +</dd> +<dt id='index-completion_002dquery_002ditems'><span><code>completion-query-items</code><a href='#index-completion_002dquery_002ditems' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The number of possible completions that determines when the user is +asked whether the list of possibilities should be displayed. +If the number of possible completions is greater than or equal to this value, +Readline will ask whether or not the user wishes to view them; +otherwise, they are simply listed. +This variable must be set to an integer value greater than or equal to zero. +A zero value means Readline should never ask; negative values are +treated as zero. +The default limit is <code>100</code>. +</p> +</dd> +<dt id='index-convert_002dmeta'><span><code>convert-meta</code><a href='#index-convert_002dmeta' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to ‘<samp>on</samp>’, Readline will convert characters with the +eighth bit set to an <small>ASCII</small> key sequence by stripping the eighth +bit and prefixing an <tt class="key">ESC</tt> character, converting them to a +meta-prefixed key sequence. +The default value is ‘<samp>on</samp>’, but +will be set to ‘<samp>off</samp>’ if the locale is one that contains +eight-bit characters. +This variable is dependent on the <code>LC_CTYPE</code> locale category, and +may change if the locale is changed. +</p> +</dd> +<dt id='index-disable_002dcompletion'><span><code>disable-completion</code><a href='#index-disable_002dcompletion' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to ‘<samp>On</samp>’, Readline will inhibit word completion. +Completion characters will be inserted into the line as if they had +been mapped to <code>self-insert</code>. The default is ‘<samp>off</samp>’. +</p> +</dd> +<dt id='index-echo_002dcontrol_002dcharacters'><span><code>echo-control-characters</code><a href='#index-echo_002dcontrol_002dcharacters' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>When set to ‘<samp>on</samp>’, on operating systems that indicate they support it, +Readline echoes a character corresponding to a signal generated from the +keyboard. The default is ‘<samp>on</samp>’. +</p> +</dd> +<dt id='index-editing_002dmode'><span><code>editing-mode</code><a href='#index-editing_002dmode' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The <code>editing-mode</code> variable controls which default set of +key bindings is used. By default, Readline starts up in Emacs editing +mode, where the keystrokes are most similar to Emacs. This variable can be +set to either ‘<samp>emacs</samp>’ or ‘<samp>vi</samp>’. +</p> +</dd> +<dt id='index-emacs_002dmode_002dstring'><span><code>emacs-mode-string</code><a href='#index-emacs_002dmode_002dstring' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If the <var>show-mode-in-prompt</var> variable is enabled, +this string is displayed immediately before the last line of the primary +prompt when emacs editing mode is active. The value is expanded like a +key binding, so the standard set of meta- and control prefixes and +backslash escape sequences is available. +Use the ‘<samp>\1</samp>’ and ‘<samp>\2</samp>’ escapes to begin and end sequences of +non-printing characters, which can be used to embed a terminal control +sequence into the mode string. +The default is ‘<samp>@</samp>’. +</p> +</dd> +<dt id='index-enable_002dactive_002dregion'><span><code>enable-active-region</code><a href='#index-enable_002dactive_002dregion' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The <em>point</em> is the current cursor position, and <em>mark</em> refers +to a saved cursor position (see <a href="#Commands-For-Moving">Commands For Moving</a>). +The text between the point and mark is referred to as the <em>region</em>. +When this variable is set to ‘<samp>On</samp>’, Readline allows certain commands +to designate the region as <em>active</em>. +When the region is active, Readline highlights the text in the region using +the value of the <code>active-region-start-color</code>, which defaults to the +string that enables +the terminal’s standout mode. +The active region shows the text inserted by bracketed-paste and any +matching text found by incremental and non-incremental history searches. +The default is ‘<samp>On</samp>’. +</p> +</dd> +<dt id='index-enable_002dbracketed_002dpaste'><span><code>enable-bracketed-paste</code><a href='#index-enable_002dbracketed_002dpaste' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>When set to ‘<samp>On</samp>’, Readline configures the terminal to insert each +paste into the editing buffer as a single string of characters, instead +of treating each character as if it had been read from the keyboard. +This is called putting the terminal into <em>bracketed paste mode</em>; +it prevents Readline from executing any editing commands bound to key +sequences appearing in the pasted text. +The default is ‘<samp>On</samp>’. +</p> +</dd> +<dt id='index-enable_002dkeypad'><span><code>enable-keypad</code><a href='#index-enable_002dkeypad' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>When set to ‘<samp>on</samp>’, Readline will try to enable the application +keypad when it is called. Some systems need this to enable the +arrow keys. The default is ‘<samp>off</samp>’. +</p> +</dd> +<dt><span><code>enable-meta-key</code></span></dt> +<dd><p>When set to ‘<samp>on</samp>’, Readline will try to enable any meta modifier +key the terminal claims to support when it is called. On many terminals, +the meta key is used to send eight-bit characters. +The default is ‘<samp>on</samp>’. +</p> +</dd> +<dt id='index-expand_002dtilde'><span><code>expand-tilde</code><a href='#index-expand_002dtilde' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to ‘<samp>on</samp>’, tilde expansion is performed when Readline +attempts word completion. The default is ‘<samp>off</samp>’. +</p> +</dd> +<dt id='index-history_002dpreserve_002dpoint'><span><code>history-preserve-point</code><a href='#index-history_002dpreserve_002dpoint' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to ‘<samp>on</samp>’, the history code attempts to place the point (the +current cursor position) at the +same location on each history line retrieved with <code>previous-history</code> +or <code>next-history</code>. The default is ‘<samp>off</samp>’. +</p> +</dd> +<dt id='index-history_002dsize'><span><code>history-size</code><a href='#index-history_002dsize' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Set the maximum number of history entries saved in the history list. +If set to zero, any existing history entries are deleted and no new entries +are saved. +If set to a value less than zero, the number of history entries is not +limited. +By default, the number of history entries is not limited. +If an attempt is made to set <var>history-size</var> to a non-numeric value, +the maximum number of history entries will be set to 500. +</p> +</dd> +<dt id='index-horizontal_002dscroll_002dmode'><span><code>horizontal-scroll-mode</code><a href='#index-horizontal_002dscroll_002dmode' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This variable can be set to either ‘<samp>on</samp>’ or ‘<samp>off</samp>’. Setting it +to ‘<samp>on</samp>’ means that the text of the lines being edited will scroll +horizontally on a single screen line when they are longer than the width +of the screen, instead of wrapping onto a new screen line. +This variable is automatically set to ‘<samp>on</samp>’ for terminals of height 1. +By default, this variable is set to ‘<samp>off</samp>’. +</p> +</dd> +<dt id='index-input_002dmeta'><span><code>input-meta</code><a href='#index-input_002dmeta' class='copiable-anchor'> ¶</a></span></dt> +<dd><span id="index-meta_002dflag"></span> +<p>If set to ‘<samp>on</samp>’, Readline will enable eight-bit input (it +will not clear the eighth bit in the characters it reads), +regardless of what the terminal claims it can support. The +default value is ‘<samp>off</samp>’, but Readline will set it to ‘<samp>on</samp>’ if the +locale contains eight-bit characters. +The name <code>meta-flag</code> is a synonym for this variable. +This variable is dependent on the <code>LC_CTYPE</code> locale category, and +may change if the locale is changed. +</p> +</dd> +<dt id='index-isearch_002dterminators'><span><code>isearch-terminators</code><a href='#index-isearch_002dterminators' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The string of characters that should terminate an incremental search without +subsequently executing the character as a command (see <a href="#Searching">Searching for Commands in the History</a>). +If this variable has not been given a value, the characters <tt class="key">ESC</tt> and +<kbd>C-J</kbd> will terminate an incremental search. +</p> +</dd> +<dt id='index-keymap'><span><code>keymap</code><a href='#index-keymap' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Sets Readline’s idea of the current keymap for key binding commands. +Built-in <code>keymap</code> names are +<code>emacs</code>, +<code>emacs-standard</code>, +<code>emacs-meta</code>, +<code>emacs-ctlx</code>, +<code>vi</code>, +<code>vi-move</code>, +<code>vi-command</code>, and +<code>vi-insert</code>. +<code>vi</code> is equivalent to <code>vi-command</code> (<code>vi-move</code> is also a +synonym); <code>emacs</code> is equivalent to <code>emacs-standard</code>. +Applications may add additional names. +The default value is <code>emacs</code>. +The value of the <code>editing-mode</code> variable also affects the +default keymap. +</p> +</dd> +<dt><span><code>keyseq-timeout</code></span></dt> +<dd><p>Specifies the duration Readline will wait for a character when reading an +ambiguous key sequence (one that can form a complete key sequence using +the input read so far, or can take additional input to complete a longer +key sequence). +If no input is received within the timeout, Readline will use the shorter +but complete key sequence. +Readline uses this value to determine whether or not input is +available on the current input source (<code>rl_instream</code> by default). +The value is specified in milliseconds, so a value of 1000 means that +Readline will wait one second for additional input. +If this variable is set to a value less than or equal to zero, or to a +non-numeric value, Readline will wait until another key is pressed to +decide which key sequence to complete. +The default value is <code>500</code>. +</p> +</dd> +<dt><span><code>mark-directories</code></span></dt> +<dd><p>If set to ‘<samp>on</samp>’, completed directory names have a slash +appended. The default is ‘<samp>on</samp>’. +</p> +</dd> +<dt id='index-mark_002dmodified_002dlines'><span><code>mark-modified-lines</code><a href='#index-mark_002dmodified_002dlines' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This variable, when set to ‘<samp>on</samp>’, causes Readline to display an +asterisk (‘<samp>*</samp>’) at the start of history lines which have been modified. +This variable is ‘<samp>off</samp>’ by default. +</p> +</dd> +<dt id='index-mark_002dsymlinked_002ddirectories'><span><code>mark-symlinked-directories</code><a href='#index-mark_002dsymlinked_002ddirectories' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to ‘<samp>on</samp>’, completed names which are symbolic links +to directories have a slash appended (subject to the value of +<code>mark-directories</code>). +The default is ‘<samp>off</samp>’. +</p> +</dd> +<dt id='index-match_002dhidden_002dfiles'><span><code>match-hidden-files</code><a href='#index-match_002dhidden_002dfiles' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This variable, when set to ‘<samp>on</samp>’, causes Readline to match files whose +names begin with a ‘<samp>.</samp>’ (hidden files) when performing filename +completion. +If set to ‘<samp>off</samp>’, the leading ‘<samp>.</samp>’ must be +supplied by the user in the filename to be completed. +This variable is ‘<samp>on</samp>’ by default. +</p> +</dd> +<dt id='index-menu_002dcomplete_002ddisplay_002dprefix'><span><code>menu-complete-display-prefix</code><a href='#index-menu_002dcomplete_002ddisplay_002dprefix' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to ‘<samp>on</samp>’, menu completion displays the common prefix of the +list of possible completions (which may be empty) before cycling through +the list. The default is ‘<samp>off</samp>’. +</p> +</dd> +<dt id='index-output_002dmeta'><span><code>output-meta</code><a href='#index-output_002dmeta' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to ‘<samp>on</samp>’, Readline will display characters with the +eighth bit set directly rather than as a meta-prefixed escape +sequence. +The default is ‘<samp>off</samp>’, but Readline will set it to ‘<samp>on</samp>’ if the +locale contains eight-bit characters. +This variable is dependent on the <code>LC_CTYPE</code> locale category, and +may change if the locale is changed. +</p> +</dd> +<dt id='index-page_002dcompletions'><span><code>page-completions</code><a href='#index-page_002dcompletions' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to ‘<samp>on</samp>’, Readline uses an internal <code>more</code>-like pager +to display a screenful of possible completions at a time. +This variable is ‘<samp>on</samp>’ by default. +</p> +</dd> +<dt><span><code>print-completions-horizontally</code></span></dt> +<dd><p>If set to ‘<samp>on</samp>’, Readline will display completions with matches +sorted horizontally in alphabetical order, rather than down the screen. +The default is ‘<samp>off</samp>’. +</p> +</dd> +<dt id='index-revert_002dall_002dat_002dnewline'><span><code>revert-all-at-newline</code><a href='#index-revert_002dall_002dat_002dnewline' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to ‘<samp>on</samp>’, Readline will undo all changes to history lines +before returning when <code>accept-line</code> is executed. By default, +history lines may be modified and retain individual undo lists across +calls to <code>readline()</code>. The default is ‘<samp>off</samp>’. +</p> +</dd> +<dt id='index-show_002dall_002dif_002dambiguous'><span><code>show-all-if-ambiguous</code><a href='#index-show_002dall_002dif_002dambiguous' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This alters the default behavior of the completion functions. If +set to ‘<samp>on</samp>’, +words which have more than one possible completion cause the +matches to be listed immediately instead of ringing the bell. +The default value is ‘<samp>off</samp>’. +</p> +</dd> +<dt id='index-show_002dall_002dif_002dunmodified'><span><code>show-all-if-unmodified</code><a href='#index-show_002dall_002dif_002dunmodified' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This alters the default behavior of the completion functions in +a fashion similar to <var>show-all-if-ambiguous</var>. +If set to ‘<samp>on</samp>’, +words which have more than one possible completion without any +possible partial completion (the possible completions don’t share +a common prefix) cause the matches to be listed immediately instead +of ringing the bell. +The default value is ‘<samp>off</samp>’. +</p> +</dd> +<dt id='index-show_002dmode_002din_002dprompt'><span><code>show-mode-in-prompt</code><a href='#index-show_002dmode_002din_002dprompt' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to ‘<samp>on</samp>’, add a string to the beginning of the prompt +indicating the editing mode: emacs, vi command, or vi insertion. +The mode strings are user-settable (e.g., <var>emacs-mode-string</var>). +The default value is ‘<samp>off</samp>’. +</p> +</dd> +<dt id='index-skip_002dcompleted_002dtext'><span><code>skip-completed-text</code><a href='#index-skip_002dcompleted_002dtext' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to ‘<samp>on</samp>’, this alters the default completion behavior when +inserting a single match into the line. It’s only active when +performing completion in the middle of a word. If enabled, Readline +does not insert characters from the completion that match characters +after point in the word being completed, so portions of the word +following the cursor are not duplicated. +For instance, if this is enabled, attempting completion when the cursor +is after the ‘<samp>e</samp>’ in ‘<samp>Makefile</samp>’ will result in ‘<samp>Makefile</samp>’ +rather than ‘<samp>Makefilefile</samp>’, assuming there is a single possible +completion. +The default value is ‘<samp>off</samp>’. +</p> +</dd> +<dt id='index-vi_002dcmd_002dmode_002dstring'><span><code>vi-cmd-mode-string</code><a href='#index-vi_002dcmd_002dmode_002dstring' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If the <var>show-mode-in-prompt</var> variable is enabled, +this string is displayed immediately before the last line of the primary +prompt when vi editing mode is active and in command mode. +The value is expanded like a +key binding, so the standard set of meta- and control prefixes and +backslash escape sequences is available. +Use the ‘<samp>\1</samp>’ and ‘<samp>\2</samp>’ escapes to begin and end sequences of +non-printing characters, which can be used to embed a terminal control +sequence into the mode string. +The default is ‘<samp>(cmd)</samp>’. +</p> +</dd> +<dt id='index-vi_002dins_002dmode_002dstring'><span><code>vi-ins-mode-string</code><a href='#index-vi_002dins_002dmode_002dstring' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If the <var>show-mode-in-prompt</var> variable is enabled, +this string is displayed immediately before the last line of the primary +prompt when vi editing mode is active and in insertion mode. +The value is expanded like a +key binding, so the standard set of meta- and control prefixes and +backslash escape sequences is available. +Use the ‘<samp>\1</samp>’ and ‘<samp>\2</samp>’ escapes to begin and end sequences of +non-printing characters, which can be used to embed a terminal control +sequence into the mode string. +The default is ‘<samp>(ins)</samp>’. +</p> +</dd> +<dt id='index-visible_002dstats'><span><code>visible-stats</code><a href='#index-visible_002dstats' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If set to ‘<samp>on</samp>’, a character denoting a file’s type +is appended to the filename when listing possible +completions. The default is ‘<samp>off</samp>’. +</p> +</dd> +</dl> + +</dd> +<dt><span>Key Bindings</span></dt> +<dd><p>The syntax for controlling key bindings in the init file is +simple. First you need to find the name of the command that you +want to change. The following sections contain tables of the command +name, the default keybinding, if any, and a short description of what +the command does. +</p> +<p>Once you know the name of the command, simply place on a line +in the init file the name of the key +you wish to bind the command to, a colon, and then the name of the +command. +There can be no space between the key name and the colon – that will be +interpreted as part of the key name. +The name of the key can be expressed in different ways, depending on +what you find most comfortable. +</p> +<p>In addition to command names, Readline allows keys to be bound +to a string that is inserted when the key is pressed (a <var>macro</var>). +</p> +<p>The <code>bind <span class="nolinebreak">-p</span></code><!-- /@w --> command displays Readline function names and +bindings in a format that can be put directly into an initialization file. +See <a href="#Bash-Builtins">Bash Builtin Commands</a>. +</p> +<dl compact="compact"> +<dt><span><var>keyname</var>: <var><span class="nolinebreak">function-name</span></var> or <var>macro</var><!-- /@w --></span></dt> +<dd><p><var>keyname</var> is the name of a key spelled out in English. For example: +</p><div class="example"> +<pre class="example">Control-u: universal-argument +Meta-Rubout: backward-kill-word +Control-o: "> output" +</pre></div> + +<p>In the example above, <kbd>C-u</kbd> is bound to the function +<code>universal-argument</code>, +<kbd>M-DEL</kbd> is bound to the function <code>backward-kill-word</code>, and +<kbd>C-o</kbd> is bound to run the macro +expressed on the right hand side (that is, to insert the text +‘<samp>> output</samp>’ into the line). +</p> +<p>A number of symbolic character names are recognized while +processing this key binding syntax: +<var>DEL</var>, +<var>ESC</var>, +<var>ESCAPE</var>, +<var>LFD</var>, +<var>NEWLINE</var>, +<var>RET</var>, +<var>RETURN</var>, +<var>RUBOUT</var>, +<var>SPACE</var>, +<var>SPC</var>, +and +<var>TAB</var>. +</p> +</dd> +<dt><span>"<var>keyseq</var>": <var><span class="nolinebreak">function-name</span></var> or <var>macro</var><!-- /@w --></span></dt> +<dd><p><var>keyseq</var> differs from <var>keyname</var> above in that strings +denoting an entire key sequence can be specified, by placing +the key sequence in double quotes. Some <small>GNU</small> Emacs style key +escapes can be used, as in the following example, but the +special character names are not recognized. +</p> +<div class="example"> +<pre class="example">"\C-u": universal-argument +"\C-x\C-r": re-read-init-file +"\e[11~": "Function Key 1" +</pre></div> + +<p>In the above example, <kbd>C-u</kbd> is again bound to the function +<code>universal-argument</code> (just as it was in the first example), +‘<samp><kbd>C-x</kbd> <kbd>C-r</kbd></samp>’ is bound to the function <code>re-read-init-file</code>, +and ‘<samp><span class="key">ESC</span> <span class="key">[</span> <span class="key">1</span> <span class="key">1</span> <span class="key">~</span></samp>’ is bound to insert +the text ‘<samp>Function Key 1</samp>’. +</p> +</dd> +</dl> + +<p>The following <small>GNU</small> Emacs style escape sequences are available when +specifying key sequences: +</p> +<dl compact="compact"> +<dt><span><code><kbd>\C-</kbd></code></span></dt> +<dd><p>control prefix +</p></dd> +<dt><span><code><kbd>\M-</kbd></code></span></dt> +<dd><p>meta prefix +</p></dd> +<dt><span><code><kbd>\e</kbd></code></span></dt> +<dd><p>an escape character +</p></dd> +<dt><span><code><kbd>\\</kbd></code></span></dt> +<dd><p>backslash +</p></dd> +<dt><span><code><kbd>\"</kbd></code></span></dt> +<dd><p><tt class="key">"</tt>, a double quotation mark +</p></dd> +<dt><span><code><kbd>\'</kbd></code></span></dt> +<dd><p><tt class="key">'</tt>, a single quote or apostrophe +</p></dd> +</dl> + +<p>In addition to the <small>GNU</small> Emacs style escape sequences, a second +set of backslash escapes is available: +</p> +<dl compact="compact"> +<dt><span><code>\a</code></span></dt> +<dd><p>alert (bell) +</p></dd> +<dt><span><code>\b</code></span></dt> +<dd><p>backspace +</p></dd> +<dt><span><code>\d</code></span></dt> +<dd><p>delete +</p></dd> +<dt><span><code>\f</code></span></dt> +<dd><p>form feed +</p></dd> +<dt><span><code>\n</code></span></dt> +<dd><p>newline +</p></dd> +<dt><span><code>\r</code></span></dt> +<dd><p>carriage return +</p></dd> +<dt><span><code>\t</code></span></dt> +<dd><p>horizontal tab +</p></dd> +<dt><span><code>\v</code></span></dt> +<dd><p>vertical tab +</p></dd> +<dt><span><code>\<var>nnn</var></code></span></dt> +<dd><p>the eight-bit character whose value is the octal value <var>nnn</var> +(one to three digits) +</p></dd> +<dt><span><code>\x<var>HH</var></code></span></dt> +<dd><p>the eight-bit character whose value is the hexadecimal value <var>HH</var> +(one or two hex digits) +</p></dd> +</dl> + +<p>When entering the text of a macro, single or double quotes must +be used to indicate a macro definition. +Unquoted text is assumed to be a function name. +In the macro body, the backslash escapes described above are expanded. +Backslash will quote any other character in the macro text, +including ‘<samp>"</samp>’ and ‘<samp>'</samp>’. +For example, the following binding will make ‘<samp><kbd>C-x</kbd> \</samp>’ +insert a single ‘<samp>\</samp>’ into the line: +</p><div class="example"> +<pre class="example">"\C-x\\": "\\" +</pre></div> + +</dd> +</dl> + +<hr> +</div> +<div class="subsection" id="Conditional-Init-Constructs"> +<div class="header"> +<p> +Next: <a href="#Sample-Init-File" accesskey="n" rel="next">Sample Init File</a>, Previous: <a href="#Readline-Init-File-Syntax" accesskey="p" rel="prev">Readline Init File Syntax</a>, Up: <a href="#Readline-Init-File" accesskey="u" rel="up">Readline Init File</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Conditional-Init-Constructs-1"></span><h4 class="subsection">8.3.2 Conditional Init Constructs</h4> + +<p>Readline implements a facility similar in spirit to the conditional +compilation features of the C preprocessor which allows key +bindings and variable settings to be performed as the result +of tests. There are four parser directives used. +</p> +<dl compact="compact"> +<dt><span><code>$if</code></span></dt> +<dd><p>The <code>$if</code> construct allows bindings to be made based on the +editing mode, the terminal being used, or the application using +Readline. The text of the test, after any comparison operator, +extends to the end of the line; +unless otherwise noted, no characters are required to isolate it. +</p> +<dl compact="compact"> +<dt><span><code>mode</code></span></dt> +<dd><p>The <code>mode=</code> form of the <code>$if</code> directive is used to test +whether Readline is in <code>emacs</code> or <code>vi</code> mode. +This may be used in conjunction +with the ‘<samp>set keymap</samp>’ command, for instance, to set bindings in +the <code>emacs-standard</code> and <code>emacs-ctlx</code> keymaps only if +Readline is starting out in <code>emacs</code> mode. +</p> +</dd> +<dt><span><code>term</code></span></dt> +<dd><p>The <code>term=</code> form may be used to include terminal-specific +key bindings, perhaps to bind the key sequences output by the +terminal’s function keys. The word on the right side of the +‘<samp>=</samp>’ is tested against both the full name of the terminal and +the portion of the terminal name before the first ‘<samp>-</samp>’. This +allows <code>sun</code> to match both <code>sun</code> and <code>sun-cmd</code>, +for instance. +</p> +</dd> +<dt><span><code>version</code></span></dt> +<dd><p>The <code>version</code> test may be used to perform comparisons against +specific Readline versions. +The <code>version</code> expands to the current Readline version. +The set of comparison operators includes +‘<samp>=</samp>’ (and ‘<samp>==</samp>’), ‘<samp>!=</samp>’, ‘<samp><=</samp>’, ‘<samp>>=</samp>’, ‘<samp><</samp>’, +and ‘<samp>></samp>’. +The version number supplied on the right side of the operator consists +of a major version number, an optional decimal point, and an optional +minor version (e.g., ‘<samp>7.1</samp>’). If the minor version is omitted, it +is assumed to be ‘<samp>0</samp>’. +The operator may be separated from the string <code>version</code> and +from the version number argument by whitespace. +The following example sets a variable if the Readline version being used +is 7.0 or newer: +</p><div class="example"> +<pre class="example">$if version >= 7.0 +set show-mode-in-prompt on +$endif +</pre></div> + +</dd> +<dt><span><code>application</code></span></dt> +<dd><p>The <var>application</var> construct is used to include +application-specific settings. Each program using the Readline +library sets the <var>application name</var>, and you can test for +a particular value. +This could be used to bind key sequences to functions useful for +a specific program. For instance, the following command adds a +key sequence that quotes the current or previous word in Bash: +</p><div class="example"> +<pre class="example">$if Bash +# Quote the current or previous word +"\C-xq": "\eb\"\ef\"" +$endif +</pre></div> + +</dd> +<dt><span><code>variable</code></span></dt> +<dd><p>The <var>variable</var> construct provides simple equality tests for Readline +variables and values. +The permitted comparison operators are ‘<samp>=</samp>’, ‘<samp>==</samp>’, and ‘<samp>!=</samp>’. +The variable name must be separated from the comparison operator by +whitespace; the operator may be separated from the value on the right hand +side by whitespace. +Both string and boolean variables may be tested. Boolean variables must be +tested against the values <var>on</var> and <var>off</var>. +The following example is equivalent to the <code>mode=emacs</code> test described +above: +</p><div class="example"> +<pre class="example">$if editing-mode == emacs +set show-mode-in-prompt on +$endif +</pre></div> +</dd> +</dl> + +</dd> +<dt><span><code>$endif</code></span></dt> +<dd><p>This command, as seen in the previous example, terminates an +<code>$if</code> command. +</p> +</dd> +<dt><span><code>$else</code></span></dt> +<dd><p>Commands in this branch of the <code>$if</code> directive are executed if +the test fails. +</p> +</dd> +<dt><span><code>$include</code></span></dt> +<dd><p>This directive takes a single filename as an argument and reads commands +and bindings from that file. +For example, the following directive reads from <samp>/etc/inputrc</samp>: +</p><div class="example"> +<pre class="example">$include /etc/inputrc +</pre></div> +</dd> +</dl> + +<hr> +</div> +<div class="subsection" id="Sample-Init-File"> +<div class="header"> +<p> +Previous: <a href="#Conditional-Init-Constructs" accesskey="p" rel="prev">Conditional Init Constructs</a>, Up: <a href="#Readline-Init-File" accesskey="u" rel="up">Readline Init File</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Sample-Init-File-1"></span><h4 class="subsection">8.3.3 Sample Init File</h4> + +<p>Here is an example of an <var>inputrc</var> file. This illustrates key +binding, variable assignment, and conditional syntax. +</p> +<div class="example"> +<pre class="example"># This file controls the behaviour of line input editing for +# programs that use the GNU Readline library. Existing +# programs include FTP, Bash, and GDB. +# +# You can re-read the inputrc file with C-x C-r. +# Lines beginning with '#' are comments. +# +# First, include any system-wide bindings and variable +# assignments from /etc/Inputrc +$include /etc/Inputrc + +# +# Set various bindings for emacs mode. + +set editing-mode emacs + +$if mode=emacs + +Meta-Control-h: backward-kill-word Text after the function name is ignored + +# +# Arrow keys in keypad mode +# +#"\M-OD": backward-char +#"\M-OC": forward-char +#"\M-OA": previous-history +#"\M-OB": next-history +# +# Arrow keys in ANSI mode +# +"\M-[D": backward-char +"\M-[C": forward-char +"\M-[A": previous-history +"\M-[B": next-history +# +# Arrow keys in 8 bit keypad mode +# +#"\M-\C-OD": backward-char +#"\M-\C-OC": forward-char +#"\M-\C-OA": previous-history +#"\M-\C-OB": next-history +# +# Arrow keys in 8 bit ANSI mode +# +#"\M-\C-[D": backward-char +#"\M-\C-[C": forward-char +#"\M-\C-[A": previous-history +#"\M-\C-[B": next-history + +C-q: quoted-insert + +$endif + +# An old-style binding. This happens to be the default. +TAB: complete + +# Macros that are convenient for shell interaction +$if Bash +# edit the path +"\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" +# prepare to type a quoted word -- +# insert open and close double quotes +# and move to just after the open quote +"\C-x\"": "\"\"\C-b" +# insert a backslash (testing backslash escapes +# in sequences and macros) +"\C-x\\": "\\" +# Quote the current or previous word +"\C-xq": "\eb\"\ef\"" +# Add a binding to refresh the line, which is unbound +"\C-xr": redraw-current-line +# Edit variable on current line. +"\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" +$endif + +# use a visible bell if one is available +set bell-style visible + +# don't strip characters to 7 bits when reading +set input-meta on + +# allow iso-latin1 characters to be inserted rather +# than converted to prefix-meta sequences +set convert-meta off + +# display characters with the eighth bit set directly +# rather than as meta-prefixed characters +set output-meta on + +# if there are 150 or more possible completions for a word, +# ask whether or not the user wants to see all of them +set completion-query-items 150 + +# For FTP +$if Ftp +"\C-xg": "get \M-?" +"\C-xt": "put \M-?" +"\M-.": yank-last-arg +$endif +</pre></div> + +<hr> +</div> +</div> +<div class="section" id="Bindable-Readline-Commands"> +<div class="header"> +<p> +Next: <a href="#Readline-vi-Mode" accesskey="n" rel="next">Readline vi Mode</a>, Previous: <a href="#Readline-Init-File" accesskey="p" rel="prev">Readline Init File</a>, Up: <a href="#Command-Line-Editing" accesskey="u" rel="up">Command Line Editing</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Bindable-Readline-Commands-1"></span><h3 class="section">8.4 Bindable Readline Commands</h3> + + +<p>This section describes Readline commands that may be bound to key +sequences. +You can list your key bindings by executing +<code>bind <span class="nolinebreak">-P</span></code><!-- /@w --> or, for a more terse format, suitable for an +<var>inputrc</var> file, <code>bind <span class="nolinebreak">-p</span></code><!-- /@w -->. (See <a href="#Bash-Builtins">Bash Builtin Commands</a>.) +Command names without an accompanying key sequence are unbound by default. +</p> +<p>In the following descriptions, <em>point</em> refers to the current cursor +position, and <em>mark</em> refers to a cursor position saved by the +<code>set-mark</code> command. +The text between the point and mark is referred to as the <em>region</em>. +</p> +<ul class="section-toc"> +<li><a href="#Commands-For-Moving" accesskey="1">Commands For Moving</a></li> +<li><a href="#Commands-For-History" accesskey="2">Commands For Manipulating The History</a></li> +<li><a href="#Commands-For-Text" accesskey="3">Commands For Changing Text</a></li> +<li><a href="#Commands-For-Killing" accesskey="4">Killing And Yanking</a></li> +<li><a href="#Numeric-Arguments" accesskey="5">Specifying Numeric Arguments</a></li> +<li><a href="#Commands-For-Completion" accesskey="6">Letting Readline Type For You</a></li> +<li><a href="#Keyboard-Macros" accesskey="7">Keyboard Macros</a></li> +<li><a href="#Miscellaneous-Commands" accesskey="8">Some Miscellaneous Commands</a></li> +</ul> +<hr> +<div class="subsection" id="Commands-For-Moving"> +<div class="header"> +<p> +Next: <a href="#Commands-For-History" accesskey="n" rel="next">Commands For Manipulating The History</a>, Up: <a href="#Bindable-Readline-Commands" accesskey="u" rel="up">Bindable Readline Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Commands-For-Moving-1"></span><h4 class="subsection">8.4.1 Commands For Moving</h4> +<dl compact="compact"> +<dt id='index-beginning_002dof_002dline-_0028C_002da_0029'><span><code>beginning-of-line (C-a)</code><a href='#index-beginning_002dof_002dline-_0028C_002da_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Move to the start of the current line. +</p> +</dd> +<dt id='index-end_002dof_002dline-_0028C_002de_0029'><span><code>end-of-line (C-e)</code><a href='#index-end_002dof_002dline-_0028C_002de_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Move to the end of the line. +</p> +</dd> +<dt id='index-forward_002dchar-_0028C_002df_0029'><span><code>forward-char (C-f)</code><a href='#index-forward_002dchar-_0028C_002df_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Move forward a character. +</p> +</dd> +<dt id='index-backward_002dchar-_0028C_002db_0029'><span><code>backward-char (C-b)</code><a href='#index-backward_002dchar-_0028C_002db_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Move back a character. +</p> +</dd> +<dt id='index-forward_002dword-_0028M_002df_0029'><span><code>forward-word (M-f)</code><a href='#index-forward_002dword-_0028M_002df_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Move forward to the end of the next word. +Words are composed of letters and digits. +</p> +</dd> +<dt id='index-backward_002dword-_0028M_002db_0029'><span><code>backward-word (M-b)</code><a href='#index-backward_002dword-_0028M_002db_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Move back to the start of the current or previous word. +Words are composed of letters and digits. +</p> +</dd> +<dt id='index-shell_002dforward_002dword-_0028M_002dC_002df_0029'><span><code>shell-forward-word (M-C-f)</code><a href='#index-shell_002dforward_002dword-_0028M_002dC_002df_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Move forward to the end of the next word. +Words are delimited by non-quoted shell metacharacters. +</p> +</dd> +<dt id='index-shell_002dbackward_002dword-_0028M_002dC_002db_0029'><span><code>shell-backward-word (M-C-b)</code><a href='#index-shell_002dbackward_002dword-_0028M_002dC_002db_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Move back to the start of the current or previous word. +Words are delimited by non-quoted shell metacharacters. +</p> +</dd> +<dt id='index-previous_002dscreen_002dline-_0028_0029'><span><code>previous-screen-line ()</code><a href='#index-previous_002dscreen_002dline-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Attempt to move point to the same physical screen column on the previous +physical screen line. This will not have the desired effect if the current +Readline line does not take up more than one physical line or if point is not +greater than the length of the prompt plus the screen width. +</p> +</dd> +<dt id='index-next_002dscreen_002dline-_0028_0029'><span><code>next-screen-line ()</code><a href='#index-next_002dscreen_002dline-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Attempt to move point to the same physical screen column on the next +physical screen line. This will not have the desired effect if the current +Readline line does not take up more than one physical line or if the length +of the current Readline line is not greater than the length of the prompt +plus the screen width. +</p> +</dd> +<dt id='index-clear_002ddisplay-_0028M_002dC_002dl_0029'><span><code>clear-display (M-C-l)</code><a href='#index-clear_002ddisplay-_0028M_002dC_002dl_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Clear the screen and, if possible, the terminal’s scrollback buffer, +then redraw the current line, +leaving the current line at the top of the screen. +</p> +</dd> +<dt id='index-clear_002dscreen-_0028C_002dl_0029'><span><code>clear-screen (C-l)</code><a href='#index-clear_002dscreen-_0028C_002dl_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Clear the screen, +then redraw the current line, +leaving the current line at the top of the screen. +</p> +</dd> +<dt id='index-redraw_002dcurrent_002dline-_0028_0029'><span><code>redraw-current-line ()</code><a href='#index-redraw_002dcurrent_002dline-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Refresh the current line. By default, this is unbound. +</p> +</dd> +</dl> + +<hr> +</div> +<div class="subsection" id="Commands-For-History"> +<div class="header"> +<p> +Next: <a href="#Commands-For-Text" accesskey="n" rel="next">Commands For Changing Text</a>, Previous: <a href="#Commands-For-Moving" accesskey="p" rel="prev">Commands For Moving</a>, Up: <a href="#Bindable-Readline-Commands" accesskey="u" rel="up">Bindable Readline Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Commands-For-Manipulating-The-History"></span><h4 class="subsection">8.4.2 Commands For Manipulating The History</h4> + +<dl compact="compact"> +<dt id='index-accept_002dline-_0028Newline-or-Return_0029'><span><code>accept-line (Newline or Return)</code><a href='#index-accept_002dline-_0028Newline-or-Return_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Accept the line regardless of where the cursor is. +If this line is +non-empty, add it to the history list according to the setting of +the <code>HISTCONTROL</code> and <code>HISTIGNORE</code> variables. +If this line is a modified history line, then restore the history line +to its original state. +</p> +</dd> +<dt id='index-previous_002dhistory-_0028C_002dp_0029'><span><code>previous-history (C-p)</code><a href='#index-previous_002dhistory-_0028C_002dp_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Move ‘back’ through the history list, fetching the previous command. +</p> +</dd> +<dt id='index-next_002dhistory-_0028C_002dn_0029'><span><code>next-history (C-n)</code><a href='#index-next_002dhistory-_0028C_002dn_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Move ‘forward’ through the history list, fetching the next command. +</p> +</dd> +<dt id='index-beginning_002dof_002dhistory-_0028M_002d_003c_0029'><span><code>beginning-of-history (M-<)</code><a href='#index-beginning_002dof_002dhistory-_0028M_002d_003c_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Move to the first line in the history. +</p> +</dd> +<dt id='index-end_002dof_002dhistory-_0028M_002d_003e_0029'><span><code>end-of-history (M->)</code><a href='#index-end_002dof_002dhistory-_0028M_002d_003e_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Move to the end of the input history, i.e., the line currently +being entered. +</p> +</dd> +<dt id='index-reverse_002dsearch_002dhistory-_0028C_002dr_0029'><span><code>reverse-search-history (C-r)</code><a href='#index-reverse_002dsearch_002dhistory-_0028C_002dr_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Search backward starting at the current line and moving ‘up’ through +the history as necessary. This is an incremental search. +This command sets the region to the matched text and activates the mark. +</p> +</dd> +<dt id='index-forward_002dsearch_002dhistory-_0028C_002ds_0029'><span><code>forward-search-history (C-s)</code><a href='#index-forward_002dsearch_002dhistory-_0028C_002ds_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Search forward starting at the current line and moving ‘down’ through +the history as necessary. This is an incremental search. +This command sets the region to the matched text and activates the mark. +</p> +</dd> +<dt id='index-non_002dincremental_002dreverse_002dsearch_002dhistory-_0028M_002dp_0029'><span><code>non-incremental-reverse-search-history (M-p)</code><a href='#index-non_002dincremental_002dreverse_002dsearch_002dhistory-_0028M_002dp_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Search backward starting at the current line and moving ‘up’ +through the history as necessary using a non-incremental search +for a string supplied by the user. +The search string may match anywhere in a history line. +</p> +</dd> +<dt id='index-non_002dincremental_002dforward_002dsearch_002dhistory-_0028M_002dn_0029'><span><code>non-incremental-forward-search-history (M-n)</code><a href='#index-non_002dincremental_002dforward_002dsearch_002dhistory-_0028M_002dn_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Search forward starting at the current line and moving ‘down’ +through the history as necessary using a non-incremental search +for a string supplied by the user. +The search string may match anywhere in a history line. +</p> +</dd> +<dt id='index-history_002dsearch_002dforward-_0028_0029'><span><code>history-search-forward ()</code><a href='#index-history_002dsearch_002dforward-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Search forward through the history for the string of characters +between the start of the current line and the point. +The search string must match at the beginning of a history line. +This is a non-incremental search. +By default, this command is unbound. +</p> +</dd> +<dt id='index-history_002dsearch_002dbackward-_0028_0029'><span><code>history-search-backward ()</code><a href='#index-history_002dsearch_002dbackward-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Search backward through the history for the string of characters +between the start of the current line and the point. +The search string must match at the beginning of a history line. +This is a non-incremental search. +By default, this command is unbound. +</p> +</dd> +<dt id='index-history_002dsubstring_002dsearch_002dforward-_0028_0029'><span><code>history-substring-search-forward ()</code><a href='#index-history_002dsubstring_002dsearch_002dforward-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Search forward through the history for the string of characters +between the start of the current line and the point. +The search string may match anywhere in a history line. +This is a non-incremental search. +By default, this command is unbound. +</p> +</dd> +<dt id='index-history_002dsubstring_002dsearch_002dbackward-_0028_0029'><span><code>history-substring-search-backward ()</code><a href='#index-history_002dsubstring_002dsearch_002dbackward-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Search backward through the history for the string of characters +between the start of the current line and the point. +The search string may match anywhere in a history line. +This is a non-incremental search. +By default, this command is unbound. +</p> +</dd> +<dt id='index-yank_002dnth_002darg-_0028M_002dC_002dy_0029'><span><code>yank-nth-arg (M-C-y)</code><a href='#index-yank_002dnth_002darg-_0028M_002dC_002dy_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Insert the first argument to the previous command (usually +the second word on the previous line) at point. +With an argument <var>n</var>, +insert the <var>n</var>th word from the previous command (the words +in the previous command begin with word 0). A negative argument +inserts the <var>n</var>th word from the end of the previous command. +Once the argument <var>n</var> is computed, the argument is extracted +as if the ‘<samp>!<var>n</var></samp>’ history expansion had been specified. +</p> +</dd> +<dt id='index-yank_002dlast_002darg-_0028M_002d_002e-or-M_002d_005f_0029'><span><code>yank-last-arg (M-. or M-_)</code><a href='#index-yank_002dlast_002darg-_0028M_002d_002e-or-M_002d_005f_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Insert last argument to the previous command (the last word of the +previous history entry). +With a numeric argument, behave exactly like <code>yank-nth-arg</code>. +Successive calls to <code>yank-last-arg</code> move back through the history +list, inserting the last word (or the word specified by the argument to +the first call) of each line in turn. +Any numeric argument supplied to these successive calls determines +the direction to move through the history. A negative argument switches +the direction through the history (back or forward). +The history expansion facilities are used to extract the last argument, +as if the ‘<samp>!$</samp>’ history expansion had been specified. +</p> +</dd> +<dt id='index-operate_002dand_002dget_002dnext-_0028C_002do_0029'><span><code>operate-and-get-next (C-o)</code><a href='#index-operate_002dand_002dget_002dnext-_0028C_002do_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Accept the current line for return to the calling application as if a +newline had been entered, +and fetch the next line relative to the current line from the history +for editing. +A numeric argument, if supplied, specifies the history entry to use instead +of the current line. +</p> +</dd> +<dt id='index-fetch_002dhistory-_0028_0029'><span><code>fetch-history ()</code><a href='#index-fetch_002dhistory-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>With a numeric argument, fetch that entry from the history list +and make it the current line. +Without an argument, move back to the first entry in the history list. +</p> +</dd> +</dl> + +<hr> +</div> +<div class="subsection" id="Commands-For-Text"> +<div class="header"> +<p> +Next: <a href="#Commands-For-Killing" accesskey="n" rel="next">Killing And Yanking</a>, Previous: <a href="#Commands-For-History" accesskey="p" rel="prev">Commands For Manipulating The History</a>, Up: <a href="#Bindable-Readline-Commands" accesskey="u" rel="up">Bindable Readline Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Commands-For-Changing-Text"></span><h4 class="subsection">8.4.3 Commands For Changing Text</h4> + +<dl compact="compact"> +<dt id='index-end_002dof_002dfile-_0028usually-C_002dd_0029'><span><code><i>end-of-file</i> (usually C-d)</code><a href='#index-end_002dof_002dfile-_0028usually-C_002dd_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The character indicating end-of-file as set, for example, by +<code>stty</code>. If this character is read when there are no characters +on the line, and point is at the beginning of the line, Readline +interprets it as the end of input and returns <small>EOF</small>. +</p> +</dd> +<dt id='index-delete_002dchar-_0028C_002dd_0029'><span><code>delete-char (C-d)</code><a href='#index-delete_002dchar-_0028C_002dd_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Delete the character at point. If this function is bound to the +same character as the tty <small>EOF</small> character, as <kbd>C-d</kbd> +commonly is, see above for the effects. +</p> +</dd> +<dt id='index-backward_002ddelete_002dchar-_0028Rubout_0029'><span><code>backward-delete-char (Rubout)</code><a href='#index-backward_002ddelete_002dchar-_0028Rubout_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Delete the character behind the cursor. A numeric argument means +to kill the characters instead of deleting them. +</p> +</dd> +<dt id='index-forward_002dbackward_002ddelete_002dchar-_0028_0029'><span><code>forward-backward-delete-char ()</code><a href='#index-forward_002dbackward_002ddelete_002dchar-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Delete the character under the cursor, unless the cursor is at the +end of the line, in which case the character behind the cursor is +deleted. By default, this is not bound to a key. +</p> +</dd> +<dt id='index-quoted_002dinsert-_0028C_002dq-or-C_002dv_0029'><span><code>quoted-insert (C-q or C-v)</code><a href='#index-quoted_002dinsert-_0028C_002dq-or-C_002dv_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Add the next character typed to the line verbatim. This is +how to insert key sequences like <kbd>C-q</kbd>, for example. +</p> + +</dd> +<dt id='index-self_002dinsert-_0028a_002c-b_002c-A_002c-1_002c-_0021_002c-_2026_0029'><span><code>self-insert (a, b, A, 1, !, …)</code><a href='#index-self_002dinsert-_0028a_002c-b_002c-A_002c-1_002c-_0021_002c-_2026_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Insert yourself. +</p> +</dd> +<dt id='index-bracketed_002dpaste_002dbegin-_0028_0029'><span><code>bracketed-paste-begin ()</code><a href='#index-bracketed_002dpaste_002dbegin-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This function is intended to be bound to the "bracketed paste" escape +sequence sent by some terminals, and such a binding is assigned by default. +It allows Readline to insert the pasted text as a single unit without treating +each character as if it had been read from the keyboard. The characters +are inserted as if each one was bound to <code>self-insert</code> instead of +executing any editing commands. +</p> +<p>Bracketed paste sets the region (the characters between point and the mark) +to the inserted text. It uses the concept of an <em>active mark</em>: when the +mark is active, Readline redisplay uses the terminal’s standout mode to +denote the region. +</p> +</dd> +<dt id='index-transpose_002dchars-_0028C_002dt_0029'><span><code>transpose-chars (C-t)</code><a href='#index-transpose_002dchars-_0028C_002dt_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Drag the character before the cursor forward over +the character at the cursor, moving the +cursor forward as well. If the insertion point +is at the end of the line, then this +transposes the last two characters of the line. +Negative arguments have no effect. +</p> +</dd> +<dt id='index-transpose_002dwords-_0028M_002dt_0029'><span><code>transpose-words (M-t)</code><a href='#index-transpose_002dwords-_0028M_002dt_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Drag the word before point past the word after point, +moving point past that word as well. +If the insertion point is at the end of the line, this transposes +the last two words on the line. +</p> +</dd> +<dt id='index-upcase_002dword-_0028M_002du_0029'><span><code>upcase-word (M-u)</code><a href='#index-upcase_002dword-_0028M_002du_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Uppercase the current (or following) word. With a negative argument, +uppercase the previous word, but do not move the cursor. +</p> +</dd> +<dt id='index-downcase_002dword-_0028M_002dl_0029'><span><code>downcase-word (M-l)</code><a href='#index-downcase_002dword-_0028M_002dl_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Lowercase the current (or following) word. With a negative argument, +lowercase the previous word, but do not move the cursor. +</p> +</dd> +<dt id='index-capitalize_002dword-_0028M_002dc_0029'><span><code>capitalize-word (M-c)</code><a href='#index-capitalize_002dword-_0028M_002dc_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Capitalize the current (or following) word. With a negative argument, +capitalize the previous word, but do not move the cursor. +</p> +</dd> +<dt id='index-overwrite_002dmode-_0028_0029'><span><code>overwrite-mode ()</code><a href='#index-overwrite_002dmode-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Toggle overwrite mode. With an explicit positive numeric argument, +switches to overwrite mode. With an explicit non-positive numeric +argument, switches to insert mode. This command affects only +<code>emacs</code> mode; <code>vi</code> mode does overwrite differently. +Each call to <code>readline()</code> starts in insert mode. +</p> +<p>In overwrite mode, characters bound to <code>self-insert</code> replace +the text at point rather than pushing the text to the right. +Characters bound to <code>backward-delete-char</code> replace the character +before point with a space. +</p> +<p>By default, this command is unbound. +</p> +</dd> +</dl> + +<hr> +</div> +<div class="subsection" id="Commands-For-Killing"> +<div class="header"> +<p> +Next: <a href="#Numeric-Arguments" accesskey="n" rel="next">Specifying Numeric Arguments</a>, Previous: <a href="#Commands-For-Text" accesskey="p" rel="prev">Commands For Changing Text</a>, Up: <a href="#Bindable-Readline-Commands" accesskey="u" rel="up">Bindable Readline Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Killing-And-Yanking"></span><h4 class="subsection">8.4.4 Killing And Yanking</h4> + +<dl compact="compact"> +<dt id='index-kill_002dline-_0028C_002dk_0029'><span><code>kill-line (C-k)</code><a href='#index-kill_002dline-_0028C_002dk_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Kill the text from point to the end of the line. +With a negative numeric argument, kill backward from the cursor to the +beginning of the current line. +</p> +</dd> +<dt id='index-backward_002dkill_002dline-_0028C_002dx-Rubout_0029'><span><code>backward-kill-line (C-x Rubout)</code><a href='#index-backward_002dkill_002dline-_0028C_002dx-Rubout_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Kill backward from the cursor to the beginning of the current line. +With a negative numeric argument, kill forward from the cursor to the +end of the current line. +</p> +</dd> +<dt id='index-unix_002dline_002ddiscard-_0028C_002du_0029'><span><code>unix-line-discard (C-u)</code><a href='#index-unix_002dline_002ddiscard-_0028C_002du_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Kill backward from the cursor to the beginning of the current line. +</p> +</dd> +<dt id='index-kill_002dwhole_002dline-_0028_0029'><span><code>kill-whole-line ()</code><a href='#index-kill_002dwhole_002dline-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Kill all characters on the current line, no matter where point is. +By default, this is unbound. +</p> +</dd> +<dt id='index-kill_002dword-_0028M_002dd_0029'><span><code>kill-word (M-d)</code><a href='#index-kill_002dword-_0028M_002dd_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Kill from point to the end of the current word, or if between +words, to the end of the next word. +Word boundaries are the same as <code>forward-word</code>. +</p> +</dd> +<dt id='index-backward_002dkill_002dword-_0028M_002dDEL_0029'><span><code>backward-kill-word (M-<span class="key">DEL</span>)</code><a href='#index-backward_002dkill_002dword-_0028M_002dDEL_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Kill the word behind point. +Word boundaries are the same as <code>backward-word</code>. +</p> +</dd> +<dt id='index-shell_002dkill_002dword-_0028M_002dC_002dd_0029'><span><code>shell-kill-word (M-C-d)</code><a href='#index-shell_002dkill_002dword-_0028M_002dC_002dd_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Kill from point to the end of the current word, or if between +words, to the end of the next word. +Word boundaries are the same as <code>shell-forward-word</code>. +</p> +</dd> +<dt id='index-shell_002dbackward_002dkill_002dword-_0028_0029'><span><code>shell-backward-kill-word ()</code><a href='#index-shell_002dbackward_002dkill_002dword-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Kill the word behind point. +Word boundaries are the same as <code>shell-backward-word</code>. +</p> +</dd> +<dt id='index-shell_002dtranspose_002dwords-_0028M_002dC_002dt_0029'><span><code>shell-transpose-words (M-C-t)</code><a href='#index-shell_002dtranspose_002dwords-_0028M_002dC_002dt_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Drag the word before point past the word after point, +moving point past that word as well. +If the insertion point is at the end of the line, this transposes +the last two words on the line. +Word boundaries are the same as <code>shell-forward-word</code> and +<code>shell-backward-word</code>. +</p> +</dd> +<dt id='index-unix_002dword_002drubout-_0028C_002dw_0029'><span><code>unix-word-rubout (C-w)</code><a href='#index-unix_002dword_002drubout-_0028C_002dw_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Kill the word behind point, using white space as a word boundary. +The killed text is saved on the kill-ring. +</p> +</dd> +<dt id='index-unix_002dfilename_002drubout-_0028_0029'><span><code>unix-filename-rubout ()</code><a href='#index-unix_002dfilename_002drubout-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Kill the word behind point, using white space and the slash character +as the word boundaries. +The killed text is saved on the kill-ring. +</p> +</dd> +<dt id='index-delete_002dhorizontal_002dspace-_0028_0029'><span><code>delete-horizontal-space ()</code><a href='#index-delete_002dhorizontal_002dspace-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Delete all spaces and tabs around point. By default, this is unbound. +</p> +</dd> +<dt id='index-kill_002dregion-_0028_0029'><span><code>kill-region ()</code><a href='#index-kill_002dregion-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Kill the text in the current region. +By default, this command is unbound. +</p> +</dd> +<dt id='index-copy_002dregion_002das_002dkill-_0028_0029'><span><code>copy-region-as-kill ()</code><a href='#index-copy_002dregion_002das_002dkill-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Copy the text in the region to the kill buffer, so it can be yanked +right away. By default, this command is unbound. +</p> +</dd> +<dt id='index-copy_002dbackward_002dword-_0028_0029'><span><code>copy-backward-word ()</code><a href='#index-copy_002dbackward_002dword-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Copy the word before point to the kill buffer. +The word boundaries are the same as <code>backward-word</code>. +By default, this command is unbound. +</p> +</dd> +<dt id='index-copy_002dforward_002dword-_0028_0029'><span><code>copy-forward-word ()</code><a href='#index-copy_002dforward_002dword-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Copy the word following point to the kill buffer. +The word boundaries are the same as <code>forward-word</code>. +By default, this command is unbound. +</p> +</dd> +<dt id='index-yank-_0028C_002dy_0029'><span><code>yank (C-y)</code><a href='#index-yank-_0028C_002dy_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Yank the top of the kill ring into the buffer at point. +</p> +</dd> +<dt id='index-yank_002dpop-_0028M_002dy_0029'><span><code>yank-pop (M-y)</code><a href='#index-yank_002dpop-_0028M_002dy_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Rotate the kill-ring, and yank the new top. You can only do this if +the prior command is <code>yank</code> or <code>yank-pop</code>. +</p></dd> +</dl> + +<hr> +</div> +<div class="subsection" id="Numeric-Arguments"> +<div class="header"> +<p> +Next: <a href="#Commands-For-Completion" accesskey="n" rel="next">Letting Readline Type For You</a>, Previous: <a href="#Commands-For-Killing" accesskey="p" rel="prev">Killing And Yanking</a>, Up: <a href="#Bindable-Readline-Commands" accesskey="u" rel="up">Bindable Readline Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Specifying-Numeric-Arguments"></span><h4 class="subsection">8.4.5 Specifying Numeric Arguments</h4> +<dl compact="compact"> +<dt id='index-digit_002dargument-_0028M_002d0_002c-M_002d1_002c-_2026-M_002d_002d_0029'><span><code>digit-argument (<kbd>M-0</kbd>, <kbd>M-1</kbd>, … <kbd>M--</kbd>)</code><a href='#index-digit_002dargument-_0028M_002d0_002c-M_002d1_002c-_2026-M_002d_002d_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Add this digit to the argument already accumulating, or start a new +argument. <kbd>M--</kbd> starts a negative argument. +</p> +</dd> +<dt id='index-universal_002dargument-_0028_0029'><span><code>universal-argument ()</code><a href='#index-universal_002dargument-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This is another way to specify an argument. +If this command is followed by one or more digits, optionally with a +leading minus sign, those digits define the argument. +If the command is followed by digits, executing <code>universal-argument</code> +again ends the numeric argument, but is otherwise ignored. +As a special case, if this command is immediately followed by a +character that is neither a digit nor minus sign, the argument count +for the next command is multiplied by four. +The argument count is initially one, so executing this function the +first time makes the argument count four, a second time makes the +argument count sixteen, and so on. +By default, this is not bound to a key. +</p></dd> +</dl> + +<hr> +</div> +<div class="subsection" id="Commands-For-Completion"> +<div class="header"> +<p> +Next: <a href="#Keyboard-Macros" accesskey="n" rel="next">Keyboard Macros</a>, Previous: <a href="#Numeric-Arguments" accesskey="p" rel="prev">Specifying Numeric Arguments</a>, Up: <a href="#Bindable-Readline-Commands" accesskey="u" rel="up">Bindable Readline Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Letting-Readline-Type-For-You"></span><h4 class="subsection">8.4.6 Letting Readline Type For You</h4> + +<dl compact="compact"> +<dt id='index-complete-_0028TAB_0029'><span><code>complete (<span class="key">TAB</span>)</code><a href='#index-complete-_0028TAB_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Attempt to perform completion on the text before point. +The actual completion performed is application-specific. +Bash attempts completion treating the text as a variable (if the +text begins with ‘<samp>$</samp>’), username (if the text begins with +‘<samp>~</samp>’), hostname (if the text begins with ‘<samp>@</samp>’), or +command (including aliases and functions) in turn. If none +of these produces a match, filename completion is attempted. +</p> +</dd> +<dt id='index-possible_002dcompletions-_0028M_002d_003f_0029'><span><code>possible-completions (M-?)</code><a href='#index-possible_002dcompletions-_0028M_002d_003f_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>List the possible completions of the text before point. +When displaying completions, Readline sets the number of columns used +for display to the value of <code>completion-display-width</code>, the value of +the environment variable <code>COLUMNS</code>, or the screen width, in that order. +</p> +</dd> +<dt id='index-insert_002dcompletions-_0028M_002d_002a_0029'><span><code>insert-completions (M-*)</code><a href='#index-insert_002dcompletions-_0028M_002d_002a_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Insert all completions of the text before point that would have +been generated by <code>possible-completions</code>. +</p> +</dd> +<dt id='index-menu_002dcomplete-_0028_0029'><span><code>menu-complete ()</code><a href='#index-menu_002dcomplete-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Similar to <code>complete</code>, but replaces the word to be completed +with a single match from the list of possible completions. +Repeated execution of <code>menu-complete</code> steps through the list +of possible completions, inserting each match in turn. +At the end of the list of completions, the bell is rung +(subject to the setting of <code>bell-style</code>) +and the original text is restored. +An argument of <var>n</var> moves <var>n</var> positions forward in the list +of matches; a negative argument may be used to move backward +through the list. +This command is intended to be bound to <tt class="key">TAB</tt>, but is unbound +by default. +</p> +</dd> +<dt id='index-menu_002dcomplete_002dbackward-_0028_0029'><span><code>menu-complete-backward ()</code><a href='#index-menu_002dcomplete_002dbackward-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Identical to <code>menu-complete</code>, but moves backward through the list +of possible completions, as if <code>menu-complete</code> had been given a +negative argument. +</p> +</dd> +<dt id='index-delete_002dchar_002dor_002dlist-_0028_0029'><span><code>delete-char-or-list ()</code><a href='#index-delete_002dchar_002dor_002dlist-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Deletes the character under the cursor if not at the beginning or +end of the line (like <code>delete-char</code>). +If at the end of the line, behaves identically to +<code>possible-completions</code>. +This command is unbound by default. +</p> +</dd> +<dt id='index-complete_002dfilename-_0028M_002d_002f_0029'><span><code>complete-filename (M-/)</code><a href='#index-complete_002dfilename-_0028M_002d_002f_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Attempt filename completion on the text before point. +</p> +</dd> +<dt id='index-possible_002dfilename_002dcompletions-_0028C_002dx-_002f_0029'><span><code>possible-filename-completions (C-x /)</code><a href='#index-possible_002dfilename_002dcompletions-_0028C_002dx-_002f_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>List the possible completions of the text before point, +treating it as a filename. +</p> +</dd> +<dt id='index-complete_002dusername-_0028M_002d_007e_0029'><span><code>complete-username (M-~)</code><a href='#index-complete_002dusername-_0028M_002d_007e_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Attempt completion on the text before point, treating +it as a username. +</p> +</dd> +<dt id='index-possible_002dusername_002dcompletions-_0028C_002dx-_007e_0029'><span><code>possible-username-completions (C-x ~)</code><a href='#index-possible_002dusername_002dcompletions-_0028C_002dx-_007e_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>List the possible completions of the text before point, +treating it as a username. +</p> +</dd> +<dt id='index-complete_002dvariable-_0028M_002d_0024_0029'><span><code>complete-variable (M-$)</code><a href='#index-complete_002dvariable-_0028M_002d_0024_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Attempt completion on the text before point, treating +it as a shell variable. +</p> +</dd> +<dt id='index-possible_002dvariable_002dcompletions-_0028C_002dx-_0024_0029'><span><code>possible-variable-completions (C-x $)</code><a href='#index-possible_002dvariable_002dcompletions-_0028C_002dx-_0024_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>List the possible completions of the text before point, +treating it as a shell variable. +</p> +</dd> +<dt id='index-complete_002dhostname-_0028M_002d_0040_0029'><span><code>complete-hostname (M-@)</code><a href='#index-complete_002dhostname-_0028M_002d_0040_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Attempt completion on the text before point, treating +it as a hostname. +</p> +</dd> +<dt id='index-possible_002dhostname_002dcompletions-_0028C_002dx-_0040_0029'><span><code>possible-hostname-completions (C-x @)</code><a href='#index-possible_002dhostname_002dcompletions-_0028C_002dx-_0040_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>List the possible completions of the text before point, +treating it as a hostname. +</p> +</dd> +<dt id='index-complete_002dcommand-_0028M_002d_0021_0029'><span><code>complete-command (M-!)</code><a href='#index-complete_002dcommand-_0028M_002d_0021_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Attempt completion on the text before point, treating +it as a command name. Command completion attempts to +match the text against aliases, reserved words, shell +functions, shell builtins, and finally executable filenames, +in that order. +</p> +</dd> +<dt id='index-possible_002dcommand_002dcompletions-_0028C_002dx-_0021_0029'><span><code>possible-command-completions (C-x !)</code><a href='#index-possible_002dcommand_002dcompletions-_0028C_002dx-_0021_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>List the possible completions of the text before point, +treating it as a command name. +</p> +</dd> +<dt id='index-dynamic_002dcomplete_002dhistory-_0028M_002dTAB_0029'><span><code>dynamic-complete-history (M-<span class="key">TAB</span>)</code><a href='#index-dynamic_002dcomplete_002dhistory-_0028M_002dTAB_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Attempt completion on the text before point, comparing +the text against lines from the history list for possible +completion matches. +</p> +</dd> +<dt id='index-dabbrev_002dexpand-_0028_0029'><span><code>dabbrev-expand ()</code><a href='#index-dabbrev_002dexpand-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Attempt menu completion on the text before point, comparing +the text against lines from the history list for possible +completion matches. +</p> +</dd> +<dt id='index-complete_002dinto_002dbraces-_0028M_002d_007b_0029'><span><code>complete-into-braces (M-{)</code><a href='#index-complete_002dinto_002dbraces-_0028M_002d_007b_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Perform filename completion and insert the list of possible completions +enclosed within braces so the list is available to the shell +(see <a href="#Brace-Expansion">Brace Expansion</a>). +</p> +</dd> +</dl> + +<hr> +</div> +<div class="subsection" id="Keyboard-Macros"> +<div class="header"> +<p> +Next: <a href="#Miscellaneous-Commands" accesskey="n" rel="next">Some Miscellaneous Commands</a>, Previous: <a href="#Commands-For-Completion" accesskey="p" rel="prev">Letting Readline Type For You</a>, Up: <a href="#Bindable-Readline-Commands" accesskey="u" rel="up">Bindable Readline Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Keyboard-Macros-1"></span><h4 class="subsection">8.4.7 Keyboard Macros</h4> +<dl compact="compact"> +<dt id='index-start_002dkbd_002dmacro-_0028C_002dx-_0028_0029'><span><code>start-kbd-macro (C-x ()</code><a href='#index-start_002dkbd_002dmacro-_0028C_002dx-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Begin saving the characters typed into the current keyboard macro. +</p> +</dd> +<dt id='index-end_002dkbd_002dmacro-_0028C_002dx-_0029_0029'><span><code>end-kbd-macro (C-x ))</code><a href='#index-end_002dkbd_002dmacro-_0028C_002dx-_0029_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Stop saving the characters typed into the current keyboard macro +and save the definition. +</p> +</dd> +<dt id='index-call_002dlast_002dkbd_002dmacro-_0028C_002dx-e_0029'><span><code>call-last-kbd-macro (C-x e)</code><a href='#index-call_002dlast_002dkbd_002dmacro-_0028C_002dx-e_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Re-execute the last keyboard macro defined, by making the characters +in the macro appear as if typed at the keyboard. +</p> +</dd> +<dt id='index-print_002dlast_002dkbd_002dmacro-_0028_0029'><span><code>print-last-kbd-macro ()</code><a href='#index-print_002dlast_002dkbd_002dmacro-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Print the last keyboard macro defined in a format suitable for the +<var>inputrc</var> file. +</p> +</dd> +</dl> + +<hr> +</div> +<div class="subsection" id="Miscellaneous-Commands"> +<div class="header"> +<p> +Previous: <a href="#Keyboard-Macros" accesskey="p" rel="prev">Keyboard Macros</a>, Up: <a href="#Bindable-Readline-Commands" accesskey="u" rel="up">Bindable Readline Commands</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Some-Miscellaneous-Commands"></span><h4 class="subsection">8.4.8 Some Miscellaneous Commands</h4> +<dl compact="compact"> +<dt id='index-re_002dread_002dinit_002dfile-_0028C_002dx-C_002dr_0029'><span><code>re-read-init-file (C-x C-r)</code><a href='#index-re_002dread_002dinit_002dfile-_0028C_002dx-C_002dr_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Read in the contents of the <var>inputrc</var> file, and incorporate +any bindings or variable assignments found there. +</p> +</dd> +<dt id='index-abort-_0028C_002dg_0029'><span><code>abort (C-g)</code><a href='#index-abort-_0028C_002dg_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Abort the current editing command and +ring the terminal’s bell (subject to the setting of +<code>bell-style</code>). +</p> +</dd> +<dt id='index-do_002dlowercase_002dversion-_0028M_002dA_002c-M_002dB_002c-M_002dx_002c-_2026_0029'><span><code>do-lowercase-version (M-A, M-B, M-<var>x</var>, …)</code><a href='#index-do_002dlowercase_002dversion-_0028M_002dA_002c-M_002dB_002c-M_002dx_002c-_2026_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>If the metafied character <var>x</var> is upper case, run the command +that is bound to the corresponding metafied lower case character. +The behavior is undefined if <var>x</var> is already lower case. +</p> +</dd> +<dt id='index-prefix_002dmeta-_0028ESC_0029'><span><code>prefix-meta (<span class="key">ESC</span>)</code><a href='#index-prefix_002dmeta-_0028ESC_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Metafy the next character typed. This is for keyboards +without a meta key. Typing ‘<samp><span class="key">ESC</span> f</samp>’ is equivalent to typing +<kbd>M-f</kbd>. +</p> +</dd> +<dt id='index-undo-_0028C_002d_005f-or-C_002dx-C_002du_0029'><span><code>undo (C-_ or C-x C-u)</code><a href='#index-undo-_0028C_002d_005f-or-C_002dx-C_002du_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Incremental undo, separately remembered for each line. +</p> +</dd> +<dt id='index-revert_002dline-_0028M_002dr_0029'><span><code>revert-line (M-r)</code><a href='#index-revert_002dline-_0028M_002dr_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Undo all changes made to this line. This is like executing the <code>undo</code> +command enough times to get back to the beginning. +</p> +</dd> +<dt id='index-tilde_002dexpand-_0028M_002d_0026_0029'><span><code>tilde-expand (M-&)</code><a href='#index-tilde_002dexpand-_0028M_002d_0026_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Perform tilde expansion on the current word. +</p> +</dd> +<dt id='index-set_002dmark-_0028C_002d_0040_0029'><span><code>set-mark (C-@)</code><a href='#index-set_002dmark-_0028C_002d_0040_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Set the mark to the point. If a +numeric argument is supplied, the mark is set to that position. +</p> +</dd> +<dt id='index-exchange_002dpoint_002dand_002dmark-_0028C_002dx-C_002dx_0029'><span><code>exchange-point-and-mark (C-x C-x)</code><a href='#index-exchange_002dpoint_002dand_002dmark-_0028C_002dx-C_002dx_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Swap the point with the mark. The current cursor position is set to +the saved position, and the old cursor position is saved as the mark. +</p> +</dd> +<dt id='index-character_002dsearch-_0028C_002d_005d_0029'><span><code>character-search (C-])</code><a href='#index-character_002dsearch-_0028C_002d_005d_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A character is read and point is moved to the next occurrence of that +character. A negative argument searches for previous occurrences. +</p> +</dd> +<dt id='index-character_002dsearch_002dbackward-_0028M_002dC_002d_005d_0029'><span><code>character-search-backward (M-C-])</code><a href='#index-character_002dsearch_002dbackward-_0028M_002dC_002d_005d_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A character is read and point is moved to the previous occurrence +of that character. A negative argument searches for subsequent +occurrences. +</p> +</dd> +<dt id='index-skip_002dcsi_002dsequence-_0028_0029'><span><code>skip-csi-sequence ()</code><a href='#index-skip_002dcsi_002dsequence-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Read enough characters to consume a multi-key sequence such as those +defined for keys like Home and End. Such sequences begin with a +Control Sequence Indicator (CSI), usually ESC-[. If this sequence is +bound to "\e[", keys producing such sequences will have no effect +unless explicitly bound to a Readline command, instead of inserting +stray characters into the editing buffer. This is unbound by default, +but usually bound to ESC-[. +</p> +</dd> +<dt id='index-insert_002dcomment-_0028M_002d_0023_0029'><span><code>insert-comment (M-#)</code><a href='#index-insert_002dcomment-_0028M_002d_0023_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Without a numeric argument, the value of the <code>comment-begin</code> +variable is inserted at the beginning of the current line. +If a numeric argument is supplied, this command acts as a toggle: if +the characters at the beginning of the line do not match the value +of <code>comment-begin</code>, the value is inserted, otherwise +the characters in <code>comment-begin</code> are deleted from the beginning of +the line. +In either case, the line is accepted as if a newline had been typed. +The default value of <code>comment-begin</code> causes this command +to make the current line a shell comment. +If a numeric argument causes the comment character to be removed, the line +will be executed by the shell. +</p> +</dd> +<dt id='index-dump_002dfunctions-_0028_0029'><span><code>dump-functions ()</code><a href='#index-dump_002dfunctions-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Print all of the functions and their key bindings to the +Readline output stream. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an <var>inputrc</var> file. This command is unbound by default. +</p> +</dd> +<dt id='index-dump_002dvariables-_0028_0029'><span><code>dump-variables ()</code><a href='#index-dump_002dvariables-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Print all of the settable variables and their values to the +Readline output stream. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an <var>inputrc</var> file. This command is unbound by default. +</p> +</dd> +<dt id='index-dump_002dmacros-_0028_0029'><span><code>dump-macros ()</code><a href='#index-dump_002dmacros-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Print all of the Readline key sequences bound to macros and the +strings they output. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an <var>inputrc</var> file. This command is unbound by default. +</p> +</dd> +<dt id='index-spell_002dcorrect_002dword-_0028C_002dx-s_0029'><span><code>spell-correct-word (C-x s)</code><a href='#index-spell_002dcorrect_002dword-_0028C_002dx-s_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Perform spelling correction on the current word, treating it as a directory +or filename, in the same way as the <code>cdspell</code> shell option. +Word boundaries are the same as those used by <code>shell-forward-word</code>. +</p> +</dd> +<dt id='index-glob_002dcomplete_002dword-_0028M_002dg_0029'><span><code>glob-complete-word (M-g)</code><a href='#index-glob_002dcomplete_002dword-_0028M_002dg_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The word before point is treated as a pattern for pathname expansion, +with an asterisk implicitly appended. This pattern is used to +generate a list of matching file names for possible completions. +</p> +</dd> +<dt id='index-glob_002dexpand_002dword-_0028C_002dx-_002a_0029'><span><code>glob-expand-word (C-x *)</code><a href='#index-glob_002dexpand_002dword-_0028C_002dx-_002a_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The word before point is treated as a pattern for pathname expansion, +and the list of matching file names is inserted, replacing the word. +If a numeric argument is supplied, a ‘<samp>*</samp>’ is appended before +pathname expansion. +</p> +</dd> +<dt id='index-glob_002dlist_002dexpansions-_0028C_002dx-g_0029'><span><code>glob-list-expansions (C-x g)</code><a href='#index-glob_002dlist_002dexpansions-_0028C_002dx-g_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>The list of expansions that would have been generated by +<code>glob-expand-word</code> is displayed, and the line is redrawn. +If a numeric argument is supplied, a ‘<samp>*</samp>’ is appended before +pathname expansion. +</p> +</dd> +<dt id='index-display_002dshell_002dversion-_0028C_002dx-C_002dv_0029'><span><code>display-shell-version (C-x C-v)</code><a href='#index-display_002dshell_002dversion-_0028C_002dx-C_002dv_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Display version information about the current instance of Bash. +</p> +</dd> +<dt id='index-shell_002dexpand_002dline-_0028M_002dC_002de_0029'><span><code>shell-expand-line (M-C-e)</code><a href='#index-shell_002dexpand_002dline-_0028M_002dC_002de_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Expand the line as the shell does. +This performs alias and history expansion as well as all of the shell +word expansions (see <a href="#Shell-Expansions">Shell Expansions</a>). +</p> +</dd> +<dt id='index-history_002dexpand_002dline-_0028M_002d_005e_0029'><span><code>history-expand-line (M-^)</code><a href='#index-history_002dexpand_002dline-_0028M_002d_005e_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Perform history expansion on the current line. +</p> +</dd> +<dt id='index-magic_002dspace-_0028_0029'><span><code>magic-space ()</code><a href='#index-magic_002dspace-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Perform history expansion on the current line and insert a space +(see <a href="#History-Interaction">History Expansion</a>). +</p> +</dd> +<dt id='index-alias_002dexpand_002dline-_0028_0029'><span><code>alias-expand-line ()</code><a href='#index-alias_002dexpand_002dline-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Perform alias expansion on the current line (see <a href="#Aliases">Aliases</a>). +</p> +</dd> +<dt id='index-history_002dand_002dalias_002dexpand_002dline-_0028_0029'><span><code>history-and-alias-expand-line ()</code><a href='#index-history_002dand_002dalias_002dexpand_002dline-_0028_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Perform history and alias expansion on the current line. +</p> +</dd> +<dt id='index-insert_002dlast_002dargument-_0028M_002d_002e-or-M_002d_005f_0029'><span><code>insert-last-argument (M-. or M-_)</code><a href='#index-insert_002dlast_002dargument-_0028M_002d_002e-or-M_002d_005f_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>A synonym for <code>yank-last-arg</code>. +</p> +</dd> +<dt id='index-edit_002dand_002dexecute_002dcommand-_0028C_002dx-C_002de_0029'><span><code>edit-and-execute-command (C-x C-e)</code><a href='#index-edit_002dand_002dexecute_002dcommand-_0028C_002dx-C_002de_0029' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>Invoke an editor on the current command line, and execute the result as shell +commands. +Bash attempts to invoke +<code>$VISUAL</code>, <code>$EDITOR</code>, and <code>emacs</code> +as the editor, in that order. +</p> + + +</dd> +</dl> + +<hr> +</div> +</div> +<div class="section" id="Readline-vi-Mode"> +<div class="header"> +<p> +Next: <a href="#Programmable-Completion" accesskey="n" rel="next">Programmable Completion</a>, Previous: <a href="#Bindable-Readline-Commands" accesskey="p" rel="prev">Bindable Readline Commands</a>, Up: <a href="#Command-Line-Editing" accesskey="u" rel="up">Command Line Editing</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Readline-vi-Mode-1"></span><h3 class="section">8.5 Readline vi Mode</h3> + +<p>While the Readline library does not have a full set of <code>vi</code> +editing functions, it does contain enough to allow simple editing +of the line. The Readline <code>vi</code> mode behaves as specified in +the <small>POSIX</small> standard. +</p> +<p>In order to switch interactively between <code>emacs</code> and <code>vi</code> +editing modes, use the ‘<samp>set -o emacs</samp>’ and ‘<samp>set -o vi</samp>’ +commands (see <a href="#The-Set-Builtin">The Set Builtin</a>). +The Readline default is <code>emacs</code> mode. +</p> +<p>When you enter a line in <code>vi</code> mode, you are already placed in +‘insertion’ mode, as if you had typed an ‘<samp>i</samp>’. Pressing <tt class="key">ESC</tt> +switches you into ‘command’ mode, where you can edit the text of the +line with the standard <code>vi</code> movement keys, move to previous +history lines with ‘<samp>k</samp>’ and subsequent lines with ‘<samp>j</samp>’, and +so forth. +</p> +<hr> +</div> +<div class="section" id="Programmable-Completion"> +<div class="header"> +<p> +Next: <a href="#Programmable-Completion-Builtins" accesskey="n" rel="next">Programmable Completion Builtins</a>, Previous: <a href="#Readline-vi-Mode" accesskey="p" rel="prev">Readline vi Mode</a>, Up: <a href="#Command-Line-Editing" accesskey="u" rel="up">Command Line Editing</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Programmable-Completion-1"></span><h3 class="section">8.6 Programmable Completion</h3> +<span id="index-programmable-completion"></span> + +<p>When word completion is attempted for an argument to a command for +which a completion specification (a <var>compspec</var>) has been defined +using the <code>complete</code> builtin (see <a href="#Programmable-Completion-Builtins">Programmable Completion Builtins</a>), +the programmable completion facilities are invoked. +</p> +<p>First, the command name is identified. +If a compspec has been defined for that command, the +compspec is used to generate the list of possible completions for the word. +If the command word is the empty string (completion attempted at the +beginning of an empty line), any compspec defined with +the <samp>-E</samp> option to <code>complete</code> is used. +If the command word is a full pathname, a compspec for the full +pathname is searched for first. +If no compspec is found for the full pathname, an attempt is made to +find a compspec for the portion following the final slash. +If those searches do not result in a compspec, any compspec defined with +the <samp>-D</samp> option to <code>complete</code> is used as the default. +If there is no default compspec, Bash attempts alias expansion +on the command word as a final resort, and attempts to find a compspec +for the command word from any successful expansion +</p> +<p>Once a compspec has been found, it is used to generate the list of +matching words. +If a compspec is not found, the default Bash completion +described above (see <a href="#Commands-For-Completion">Letting Readline Type For You</a>) is performed. +</p> +<p>First, the actions specified by the compspec are used. +Only matches which are prefixed by the word being completed are +returned. +When the <samp>-f</samp> or <samp>-d</samp> option is used for filename or +directory name completion, the shell variable <code>FIGNORE</code> is +used to filter the matches. +See <a href="#Bash-Variables">Bash Variables</a>, for a description of <code>FIGNORE</code>. +</p> +<p>Any completions specified by a filename expansion pattern to the +<samp>-G</samp> option are generated next. +The words generated by the pattern need not match the word being completed. +The <code>GLOBIGNORE</code> shell variable is not used to filter the matches, +but the <code>FIGNORE</code> shell variable is used. +</p> +<p>Next, the string specified as the argument to the <samp>-W</samp> option +is considered. +The string is first split using the characters in the <code>IFS</code> +special variable as delimiters. +Shell quoting is honored within the string, in order to provide a +mechanism for the words to contain shell metacharacters or characters +in the value of <code>IFS</code>. +Each word is then expanded using +brace expansion, tilde expansion, parameter and variable expansion, +command substitution, and arithmetic expansion, +as described above (see <a href="#Shell-Expansions">Shell Expansions</a>). +The results are split using the rules described above +(see <a href="#Word-Splitting">Word Splitting</a>). +The results of the expansion are prefix-matched against the word being +completed, and the matching words become the possible completions. +</p> +<p>After these matches have been generated, any shell function or command +specified with the <samp>-F</samp> and <samp>-C</samp> options is invoked. +When the command or function is invoked, the <code>COMP_LINE</code>, +<code>COMP_POINT</code>, <code>COMP_KEY</code>, and <code>COMP_TYPE</code> variables are +assigned values as described above (see <a href="#Bash-Variables">Bash Variables</a>). +If a shell function is being invoked, the <code>COMP_WORDS</code> and +<code>COMP_CWORD</code> variables are also set. +When the function or command is invoked, the first argument ($1) is the +name of the command whose arguments are being completed, the +second argument ($2) is the word being completed, and the third argument +($3) is the word preceding the word being completed on the current command +line. +No filtering of the generated completions against the word being completed +is performed; the function or command has complete freedom in generating +the matches. +</p> +<p>Any function specified with <samp>-F</samp> is invoked first. +The function may use any of the shell facilities, including the +<code>compgen</code> and <code>compopt</code> builtins described below +(see <a href="#Programmable-Completion-Builtins">Programmable Completion Builtins</a>), to generate the matches. +It must put the possible completions in the <code>COMPREPLY</code> array +variable, one per array element. +</p> +<p>Next, any command specified with the <samp>-C</samp> option is invoked +in an environment equivalent to command substitution. +It should print a list of completions, one per line, to +the standard output. +Backslash may be used to escape a newline, if necessary. +</p> +<p>After all of the possible completions are generated, any filter +specified with the <samp>-X</samp> option is applied to the list. +The filter is a pattern as used for pathname expansion; a ‘<samp>&</samp>’ +in the pattern is replaced with the text of the word being completed. +A literal ‘<samp>&</samp>’ may be escaped with a backslash; the backslash +is removed before attempting a match. +Any completion that matches the pattern will be removed from the list. +A leading ‘<samp>!</samp>’ negates the pattern; in this case any completion +not matching the pattern will be removed. +If the <code>nocasematch</code> shell option +(see the description of <code>shopt</code> in <a href="#The-Shopt-Builtin">The Shopt Builtin</a>) +is enabled, the match is performed without regard to the case +of alphabetic characters. +</p> +<p>Finally, any prefix and suffix specified with the <samp>-P</samp> and <samp>-S</samp> +options are added to each member of the completion list, and the result is +returned to the Readline completion code as the list of possible +completions. +</p> +<p>If the previously-applied actions do not generate any matches, and the +<samp>-o dirnames</samp> option was supplied to <code>complete</code> when the +compspec was defined, directory name completion is attempted. +</p> +<p>If the <samp>-o plusdirs</samp> option was supplied to <code>complete</code> when +the compspec was defined, directory name completion is attempted and any +matches are added to the results of the other actions. +</p> +<p>By default, if a compspec is found, whatever it generates is returned to +the completion code as the full set of possible completions. +The default Bash completions are not attempted, and the Readline default +of filename completion is disabled. +If the <samp>-o bashdefault</samp> option was supplied to <code>complete</code> when +the compspec was defined, the default Bash completions are attempted +if the compspec generates no matches. +If the <samp>-o default</samp> option was supplied to <code>complete</code> when the +compspec was defined, Readline’s default completion will be performed +if the compspec (and, if attempted, the default Bash completions) +generate no matches. +</p> +<p>When a compspec indicates that directory name completion is desired, +the programmable completion functions force Readline to append a slash +to completed names which are symbolic links to directories, subject to +the value of the <var>mark-directories</var> Readline variable, regardless +of the setting of the <var>mark-symlinked-directories</var> Readline variable. +</p> +<p>There is some support for dynamically modifying completions. This is +most useful when used in combination with a default completion specified +with <samp>-D</samp>. It’s possible for shell functions executed as completion +handlers to indicate that completion should be retried by returning an +exit status of 124. If a shell function returns 124, and changes +the compspec associated with the command on which completion is being +attempted (supplied as the first argument when the function is executed), +programmable completion restarts from the beginning, with an +attempt to find a new compspec for that command. This allows a set of +completions to be built dynamically as completion is attempted, rather than +being loaded all at once. +</p> +<p>For instance, assuming that there is a library of compspecs, each kept in a +file corresponding to the name of the command, the following default +completion function would load completions dynamically: +</p> +<div class="example"> +<pre class="example">_completion_loader() +{ + . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124 +} +complete -D -F _completion_loader -o bashdefault -o default +</pre></div> + +<hr> +</div> +<div class="section" id="Programmable-Completion-Builtins"> +<div class="header"> +<p> +Next: <a href="#A-Programmable-Completion-Example" accesskey="n" rel="next">A Programmable Completion Example</a>, Previous: <a href="#Programmable-Completion" accesskey="p" rel="prev">Programmable Completion</a>, Up: <a href="#Command-Line-Editing" accesskey="u" rel="up">Command Line Editing</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Programmable-Completion-Builtins-1"></span><h3 class="section">8.7 Programmable Completion Builtins</h3> +<span id="index-completion-builtins"></span> + +<p>Three builtin commands are available to manipulate the programmable completion +facilities: one to specify how the arguments to a particular command are to +be completed, and two to modify the completion as it is happening. +</p> +<dl compact="compact"> +<dt id='index-compgen'><span><code>compgen</code><a href='#index-compgen' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example"><code>compgen [<var>option</var>] [<var>word</var>]</code> +</pre></div> + +<p>Generate possible completion matches for <var>word</var> according to +the <var>option</var>s, which may be any option accepted by the +<code>complete</code> +builtin with the exception of <samp>-p</samp> and <samp>-r</samp>, and write +the matches to the standard output. +When using the <samp>-F</samp> or <samp>-C</samp> options, the various shell variables +set by the programmable completion facilities, while available, will not +have useful values. +</p> +<p>The matches will be generated in the same way as if the programmable +completion code had generated them directly from a completion specification +with the same flags. +If <var>word</var> is specified, only those completions matching <var>word</var> +will be displayed. +</p> +<p>The return value is true unless an invalid option is supplied, or no +matches were generated. +</p> +</dd> +<dt id='index-complete'><span><code>complete</code><a href='#index-complete' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example"><code>complete [-abcdefgjksuv] [-o <var>comp-option</var>] [-DEI] [-A <var>action</var>] [-G <var>globpat</var>] +[-W <var>wordlist</var>] [-F <var>function</var>] [-C <var>command</var>] [-X <var>filterpat</var>] +[-P <var>prefix</var>] [-S <var>suffix</var>] <var>name</var> [<var>name</var> …]</code> +<code>complete -pr [-DEI] [<var>name</var> …]</code> +</pre></div> + +<p>Specify how arguments to each <var>name</var> should be completed. +If the <samp>-p</samp> option is supplied, or if no options are supplied, existing +completion specifications are printed in a way that allows them to be +reused as input. +The <samp>-r</samp> option removes a completion specification for +each <var>name</var>, or, if no <var>name</var>s are supplied, all +completion specifications. +The <samp>-D</samp> option indicates that other supplied options and actions should +apply to the “default” command completion; that is, completion attempted +on a command for which no completion has previously been defined. +The <samp>-E</samp> option indicates that other supplied options and actions should +apply to “empty” command completion; that is, completion attempted on a +blank line. +The <samp>-I</samp> option indicates that other supplied options and actions should +apply to completion on the initial non-assignment word on the line, or after a +command delimiter such as ‘<samp>;</samp>’ or ‘<samp>|</samp>’, which is usually command +name completion. +If multiple options are supplied, the <samp>-D</samp> option takes precedence +over <samp>-E</samp>, and both take precedence over <samp>-I</samp>. +If any of <samp>-D</samp>, <samp>-E</samp>, or <samp>-I</samp> are supplied, any other +<var>name</var> arguments are ignored; these completions only apply to the case +specified by the option. +</p> +<p>The process of applying these completion specifications when word completion +is attempted is described above (see <a href="#Programmable-Completion">Programmable Completion</a>). +</p> +<p>Other options, if specified, have the following meanings. +The arguments to the <samp>-G</samp>, <samp>-W</samp>, and <samp>-X</samp> options +(and, if necessary, the <samp>-P</samp> and <samp>-S</samp> options) +should be quoted to protect them from expansion before the +<code>complete</code> builtin is invoked. +</p> + +<dl compact="compact"> +<dt><span><code>-o <var>comp-option</var></code></span></dt> +<dd><p>The <var>comp-option</var> controls several aspects of the compspec’s behavior +beyond the simple generation of completions. +<var>comp-option</var> may be one of: +</p> +<dl compact="compact"> +<dt><span><code>bashdefault</code></span></dt> +<dd><p>Perform the rest of the default Bash completions if the compspec +generates no matches. +</p> +</dd> +<dt><span><code>default</code></span></dt> +<dd><p>Use Readline’s default filename completion if the compspec generates +no matches. +</p> +</dd> +<dt><span><code>dirnames</code></span></dt> +<dd><p>Perform directory name completion if the compspec generates no matches. +</p> +</dd> +<dt><span><code>filenames</code></span></dt> +<dd><p>Tell Readline that the compspec generates filenames, so it can perform any +filename-specific processing (like adding a slash to directory names, +quoting special characters, or suppressing trailing spaces). +This option is intended to be used with shell functions specified +with <samp>-F</samp>. +</p> +</dd> +<dt><span><code>noquote</code></span></dt> +<dd><p>Tell Readline not to quote the completed words if they are filenames +(quoting filenames is the default). +</p> +</dd> +<dt><span><code>nosort</code></span></dt> +<dd><p>Tell Readline not to sort the list of possible completions alphabetically. +</p> +</dd> +<dt><span><code>nospace</code></span></dt> +<dd><p>Tell Readline not to append a space (the default) to words completed at +the end of the line. +</p> +</dd> +<dt><span><code>plusdirs</code></span></dt> +<dd><p>After any matches defined by the compspec are generated, +directory name completion is attempted and any +matches are added to the results of the other actions. +</p> +</dd> +</dl> + +</dd> +<dt><span><code>-A <var>action</var></code></span></dt> +<dd><p>The <var>action</var> may be one of the following to generate a list of possible +completions: +</p> +<dl compact="compact"> +<dt><span><code>alias</code></span></dt> +<dd><p>Alias names. May also be specified as <samp>-a</samp>. +</p> +</dd> +<dt><span><code>arrayvar</code></span></dt> +<dd><p>Array variable names. +</p> +</dd> +<dt><span><code>binding</code></span></dt> +<dd><p>Readline key binding names (see <a href="#Bindable-Readline-Commands">Bindable Readline Commands</a>). +</p> +</dd> +<dt><span><code>builtin</code></span></dt> +<dd><p>Names of shell builtin commands. May also be specified as <samp>-b</samp>. +</p> +</dd> +<dt><span><code>command</code></span></dt> +<dd><p>Command names. May also be specified as <samp>-c</samp>. +</p> +</dd> +<dt><span><code>directory</code></span></dt> +<dd><p>Directory names. May also be specified as <samp>-d</samp>. +</p> +</dd> +<dt><span><code>disabled</code></span></dt> +<dd><p>Names of disabled shell builtins. +</p> +</dd> +<dt><span><code>enabled</code></span></dt> +<dd><p>Names of enabled shell builtins. +</p> +</dd> +<dt><span><code>export</code></span></dt> +<dd><p>Names of exported shell variables. May also be specified as <samp>-e</samp>. +</p> +</dd> +<dt><span><code>file</code></span></dt> +<dd><p>File names. May also be specified as <samp>-f</samp>. +</p> +</dd> +<dt><span><code>function</code></span></dt> +<dd><p>Names of shell functions. +</p> +</dd> +<dt><span><code>group</code></span></dt> +<dd><p>Group names. May also be specified as <samp>-g</samp>. +</p> +</dd> +<dt><span><code>helptopic</code></span></dt> +<dd><p>Help topics as accepted by the <code>help</code> builtin (see <a href="#Bash-Builtins">Bash Builtin Commands</a>). +</p> +</dd> +<dt><span><code>hostname</code></span></dt> +<dd><p>Hostnames, as taken from the file specified by the +<code>HOSTFILE</code> shell variable (see <a href="#Bash-Variables">Bash Variables</a>). +</p> +</dd> +<dt><span><code>job</code></span></dt> +<dd><p>Job names, if job control is active. May also be specified as <samp>-j</samp>. +</p> +</dd> +<dt><span><code>keyword</code></span></dt> +<dd><p>Shell reserved words. May also be specified as <samp>-k</samp>. +</p> +</dd> +<dt><span><code>running</code></span></dt> +<dd><p>Names of running jobs, if job control is active. +</p> +</dd> +<dt><span><code>service</code></span></dt> +<dd><p>Service names. May also be specified as <samp>-s</samp>. +</p> +</dd> +<dt><span><code>setopt</code></span></dt> +<dd><p>Valid arguments for the <samp>-o</samp> option to the <code>set</code> builtin +(see <a href="#The-Set-Builtin">The Set Builtin</a>). +</p> +</dd> +<dt><span><code>shopt</code></span></dt> +<dd><p>Shell option names as accepted by the <code>shopt</code> builtin +(see <a href="#Bash-Builtins">Bash Builtin Commands</a>). +</p> +</dd> +<dt><span><code>signal</code></span></dt> +<dd><p>Signal names. +</p> +</dd> +<dt><span><code>stopped</code></span></dt> +<dd><p>Names of stopped jobs, if job control is active. +</p> +</dd> +<dt><span><code>user</code></span></dt> +<dd><p>User names. May also be specified as <samp>-u</samp>. +</p> +</dd> +<dt><span><code>variable</code></span></dt> +<dd><p>Names of all shell variables. May also be specified as <samp>-v</samp>. +</p></dd> +</dl> + +</dd> +<dt><span><code>-C <var>command</var></code></span></dt> +<dd><p><var>command</var> is executed in a subshell environment, and its output is +used as the possible completions. +Arguments are passed as with the <samp>-F</samp> option. +</p> +</dd> +<dt><span><code>-F <var>function</var></code></span></dt> +<dd><p>The shell function <var>function</var> is executed in the current shell +environment. +When it is executed, $1 is the name of the command whose arguments are +being completed, $2 is the word being completed, and $3 is the word +preceding the word being completed, as described above +(see <a href="#Programmable-Completion">Programmable Completion</a>). +When it finishes, the possible completions are retrieved from the value +of the <code>COMPREPLY</code> array variable. +</p> +</dd> +<dt><span><code>-G <var>globpat</var></code></span></dt> +<dd><p>The filename expansion pattern <var>globpat</var> is expanded to generate +the possible completions. +</p> +</dd> +<dt><span><code>-P <var>prefix</var></code></span></dt> +<dd><p><var>prefix</var> is added at the beginning of each possible completion +after all other options have been applied. +</p> +</dd> +<dt><span><code>-S <var>suffix</var></code></span></dt> +<dd><p><var>suffix</var> is appended to each possible completion +after all other options have been applied. +</p> +</dd> +<dt><span><code>-W <var>wordlist</var></code></span></dt> +<dd><p>The <var>wordlist</var> is split using the characters in the +<code>IFS</code> special variable as delimiters, and each resultant word +is expanded. +The possible completions are the members of the resultant list which +match the word being completed. +</p> +</dd> +<dt><span><code>-X <var>filterpat</var></code></span></dt> +<dd><p><var>filterpat</var> is a pattern as used for filename expansion. +It is applied to the list of possible completions generated by the +preceding options and arguments, and each completion matching +<var>filterpat</var> is removed from the list. +A leading ‘<samp>!</samp>’ in <var>filterpat</var> negates the pattern; in this +case, any completion not matching <var>filterpat</var> is removed. +</p></dd> +</dl> + +<p>The return value is true unless an invalid option is supplied, an option +other than <samp>-p</samp> or <samp>-r</samp> is supplied without a <var>name</var> +argument, an attempt is made to remove a completion specification for +a <var>name</var> for which no specification exists, or +an error occurs adding a completion specification. +</p> +</dd> +<dt id='index-compopt'><span><code>compopt</code><a href='#index-compopt' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example"><code>compopt</code> [-o <var>option</var>] [-DEI] [+o <var>option</var>] [<var>name</var>] +</pre></div> +<p>Modify completion options for each <var>name</var> according to the +<var>option</var>s, or for the currently-executing completion if no <var>name</var>s +are supplied. +If no <var>option</var>s are given, display the completion options for each +<var>name</var> or the current completion. +The possible values of <var>option</var> are those valid for the <code>complete</code> +builtin described above. +The <samp>-D</samp> option indicates that other supplied options should +apply to the “default” command completion; that is, completion attempted +on a command for which no completion has previously been defined. +The <samp>-E</samp> option indicates that other supplied options should +apply to “empty” command completion; that is, completion attempted on a +blank line. +The <samp>-I</samp> option indicates that other supplied options should +apply to completion on the initial non-assignment word on the line, or after a +command delimiter such as ‘<samp>;</samp>’ or ‘<samp>|</samp>’, which is usually command +name completion. +</p> +<p>If multiple options are supplied, the <samp>-D</samp> option takes precedence +over <samp>-E</samp>, and both take precedence over <samp>-I</samp> +</p> +<p>The return value is true unless an invalid option is supplied, an attempt +is made to modify the options for a <var>name</var> for which no completion +specification exists, or an output error occurs. +</p> +</dd> +</dl> + +<hr> +</div> +<div class="section" id="A-Programmable-Completion-Example"> +<div class="header"> +<p> +Previous: <a href="#Programmable-Completion-Builtins" accesskey="p" rel="prev">Programmable Completion Builtins</a>, Up: <a href="#Command-Line-Editing" accesskey="u" rel="up">Command Line Editing</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="A-Programmable-Completion-Example-1"></span><h3 class="section">8.8 A Programmable Completion Example</h3> + +<p>The most common way to obtain additional completion functionality beyond +the default actions <code>complete</code> and <code>compgen</code> provide is to use +a shell function and bind it to a particular command using <code>complete -F</code>. +</p> +<p>The following function provides completions for the <code>cd</code> builtin. +It is a reasonably good example of what shell functions must do when +used for completion. This function uses the word passed as <code>$2</code> +to determine the directory name to complete. You can also use the +<code>COMP_WORDS</code> array variable; the current word is indexed by the +<code>COMP_CWORD</code> variable. +</p> +<p>The function relies on the <code>complete</code> and <code>compgen</code> builtins +to do much of the work, adding only the things that the Bash <code>cd</code> +does beyond accepting basic directory names: +tilde expansion (see <a href="#Tilde-Expansion">Tilde Expansion</a>), +searching directories in <var>$CDPATH</var>, which is described above +(see <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>), +and basic support for the <code>cdable_vars</code> shell option +(see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>). +<code>_comp_cd</code> modifies the value of <var>IFS</var> so that it contains only +a newline to accommodate file names containing spaces and tabs – +<code>compgen</code> prints the possible completions it generates one per line. +</p> +<p>Possible completions go into the <var>COMPREPLY</var> array variable, one +completion per array element. The programmable completion system retrieves +the completions from there when the function returns. +</p> +<div class="example"> +<pre class="example"># A completion function for the cd builtin +# based on the cd completion function from the bash_completion package +_comp_cd() +{ + local IFS=$' \t\n' # normalize IFS + local cur _skipdot _cdpath + local i j k + + # Tilde expansion, which also expands tilde to full pathname + case "$2" in + \~*) eval cur="$2" ;; + *) cur=$2 ;; + esac + + # no cdpath or absolute pathname -- straight directory completion + if [[ -z "${CDPATH:-}" ]] || [[ "$cur" == @(./*|../*|/*) ]]; then + # compgen prints paths one per line; could also use while loop + IFS=$'\n' + COMPREPLY=( $(compgen -d -- "$cur") ) + IFS=$' \t\n' + # CDPATH+directories in the current directory if not in CDPATH + else + IFS=$'\n' + _skipdot=false + # preprocess CDPATH to convert null directory names to . + _cdpath=${CDPATH/#:/.:} + _cdpath=${_cdpath//::/:.:} + _cdpath=${_cdpath/%:/:.} + for i in ${_cdpath//:/$'\n'}; do + if [[ $i -ef . ]]; then _skipdot=true; fi + k="${#COMPREPLY[@]}" + for j in $( compgen -d -- "$i/$cur" ); do + COMPREPLY[k++]=${j#$i/} # cut off directory + done + done + $_skipdot || COMPREPLY+=( $(compgen -d -- "$cur") ) + IFS=$' \t\n' + fi + + # variable names if appropriate shell option set and no completions + if shopt -q cdable_vars && [[ ${#COMPREPLY[@]} -eq 0 ]]; then + COMPREPLY=( $(compgen -v -- "$cur") ) + fi + + return 0 +} +</pre></div> + +<p>We install the completion function using the <samp>-F</samp> option to +<code>complete</code>: +</p> +<div class="example"> +<pre class="example"># Tell readline to quote appropriate and append slashes to directories; +# use the bash default completion for other arguments +complete -o filenames -o nospace -o bashdefault -F _comp_cd cd +</pre></div> + +<p>Since we’d like Bash and Readline to take care of some +of the other details for us, we use several other options to tell Bash +and Readline what to do. The <samp>-o filenames</samp> option tells Readline +that the possible completions should be treated as filenames, and quoted +appropriately. That option will also cause Readline to append a slash to +filenames it can determine are directories (which is why we might want to +extend <code>_comp_cd</code> to append a slash if we’re using directories found +via <var>CDPATH</var>: Readline can’t tell those completions are directories). +The <samp>-o nospace</samp> option tells Readline to not append a space +character to the directory name, in case we want to append to it. +The <samp>-o bashdefault</samp> option brings in the rest of the "Bash default" +completions – possible completions that Bash adds to the default Readline +set. These include things like command name completion, variable completion +for words beginning with ‘<samp>$</samp>’ or ‘<samp>${</samp>’, completions containing pathname +expansion patterns (see <a href="#Filename-Expansion">Filename Expansion</a>), and so on. +</p> +<p>Once installed using <code>complete</code>, <code>_comp_cd</code> will be called every +time we attempt word completion for a <code>cd</code> command. +</p> +<p>Many more examples – an extensive collection of completions for most of +the common GNU, Unix, and Linux commands – are available as part of the +bash_completion project. This is installed by default on many GNU/Linux +distributions. Originally written by Ian Macdonald, the project now lives +at <a href="https://github.com/scop/bash-completion/">https://github.com/scop/bash-completion/</a>. There are ports for +other systems such as Solaris and Mac OS X. +</p> +<p>An older version of the bash_completion package is distributed with bash +in the <samp>examples/complete</samp> subdirectory. +</p> +<span id="index-History_002c-how-to-use"></span> + +<hr> +</div> +</div> +<div class="chapter" id="Using-History-Interactively"> +<div class="header"> +<p> +Next: <a href="#Installing-Bash" accesskey="n" rel="next">Installing Bash</a>, Previous: <a href="#Command-Line-Editing" accesskey="p" rel="prev">Command Line Editing</a>, Up: <a href="#Top" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Using-History-Interactively-1"></span><h2 class="chapter">9 Using History Interactively</h2> + + +<p>This chapter describes how to use the <small>GNU</small> History Library +interactively, from a user’s standpoint. +It should be considered a user’s guide. +For information on using the <small>GNU</small> History Library in other programs, +see the <small>GNU</small> Readline Library Manual. +</p> + +<ul class="section-toc"> +<li><a href="#Bash-History-Facilities" accesskey="1">Bash History Facilities</a></li> +<li><a href="#Bash-History-Builtins" accesskey="2">Bash History Builtins</a></li> +<li><a href="#History-Interaction" accesskey="3">History Expansion</a></li> +</ul> +<hr> +<div class="section" id="Bash-History-Facilities"> +<div class="header"> +<p> +Next: <a href="#Bash-History-Builtins" accesskey="n" rel="next">Bash History Builtins</a>, Up: <a href="#Using-History-Interactively" accesskey="u" rel="up">Using History Interactively</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Bash-History-Facilities-1"></span><h3 class="section">9.1 Bash History Facilities</h3> +<span id="index-command-history"></span> +<span id="index-history-list"></span> + +<p>When the <samp>-o history</samp> option to the <code>set</code> builtin +is enabled (see <a href="#The-Set-Builtin">The Set Builtin</a>), +the shell provides access to the <em>command history</em>, +the list of commands previously typed. +The value of the <code>HISTSIZE</code> shell variable is used as the +number of commands to save in a history list. +The text of the last <code>$HISTSIZE</code> +commands (default 500) is saved. +The shell stores each command in the history list prior to +parameter and variable expansion +but after history expansion is performed, subject to the +values of the shell variables +<code>HISTIGNORE</code> and <code>HISTCONTROL</code>. +</p> +<p>When the shell starts up, the history is initialized from the +file named by the <code>HISTFILE</code> variable (default <samp>~/.bash_history</samp>). +The file named by the value of <code>HISTFILE</code> is truncated, if +necessary, to contain no more than the number of lines specified by +the value of the <code>HISTFILESIZE</code> variable. +When a shell with history enabled exits, the last +<code>$HISTSIZE</code> lines are copied from the history list to the file +named by <code>$HISTFILE</code>. +If the <code>histappend</code> shell option is set (see <a href="#Bash-Builtins">Bash Builtin Commands</a>), +the lines are appended to the history file, +otherwise the history file is overwritten. +If <code>HISTFILE</code> +is unset, or if the history file is unwritable, the history is not saved. +After saving the history, the history file is truncated +to contain no more than <code>$HISTFILESIZE</code> lines. +If <code>HISTFILESIZE</code> is unset, or set to null, a non-numeric value, or +a numeric value less than zero, the history file is not truncated. +</p> +<p>If the <code>HISTTIMEFORMAT</code> is set, the time stamp information +associated with each history entry is written to the history file, +marked with the history comment character. +When the history file is read, lines beginning with the history +comment character followed immediately by a digit are interpreted +as timestamps for the following history entry. +</p> +<p>The builtin command <code>fc</code> may be used to list or edit and re-execute +a portion of the history list. +The <code>history</code> builtin may be used to display or modify the history +list and manipulate the history file. +When using command-line editing, search commands +are available in each editing mode that provide access to the +history list (see <a href="#Commands-For-History">Commands For Manipulating The History</a>). +</p> +<p>The shell allows control over which commands are saved on the history +list. The <code>HISTCONTROL</code> and <code>HISTIGNORE</code> +variables may be set to cause the shell to save only a subset of the +commands entered. +The <code>cmdhist</code> +shell option, if enabled, causes the shell to attempt to save each +line of a multi-line command in the same history entry, adding +semicolons where necessary to preserve syntactic correctness. +The <code>lithist</code> +shell option causes the shell to save the command with embedded newlines +instead of semicolons. +The <code>shopt</code> builtin is used to set these options. +See <a href="#The-Shopt-Builtin">The Shopt Builtin</a>, for a description of <code>shopt</code>. +</p> +<hr> +</div> +<div class="section" id="Bash-History-Builtins"> +<div class="header"> +<p> +Next: <a href="#History-Interaction" accesskey="n" rel="next">History Expansion</a>, Previous: <a href="#Bash-History-Facilities" accesskey="p" rel="prev">Bash History Facilities</a>, Up: <a href="#Using-History-Interactively" accesskey="u" rel="up">Using History Interactively</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Bash-History-Builtins-1"></span><h3 class="section">9.2 Bash History Builtins</h3> +<span id="index-history-builtins"></span> + +<p>Bash provides two builtin commands which manipulate the +history list and history file. +</p> +<dl compact="compact"> +<dt id='index-fc'><span><code>fc</code><a href='#index-fc' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example"><code>fc [-e <var>ename</var>] [-lnr] [<var>first</var>] [<var>last</var>]</code> +<code>fc -s [<var>pat</var>=<var>rep</var>] [<var>command</var>]</code> +</pre></div> + +<p>The first form selects a range of commands from <var>first</var> to +<var>last</var> from the history list and displays or edits and re-executes +them. +Both <var>first</var> and +<var>last</var> may be specified as a string (to locate the most recent +command beginning with that string) or as a number (an index into the +history list, where a negative number is used as an offset from the +current command number). +</p> +<p>When listing, a <var>first</var> or <var>last</var> of 0 is equivalent to -1 +and -0 is equivalent to the current command (usually the <code>fc</code> +command); +otherwise 0 is equivalent to -1 and -0 is invalid. +</p> +<p>If <var>last</var> is not specified, it is set to +<var>first</var>. If <var>first</var> is not specified, it is set to the previous +command for editing and -16 for listing. If the <samp>-l</samp> flag is +given, the commands are listed on standard output. The <samp>-n</samp> flag +suppresses the command numbers when listing. The <samp>-r</samp> flag +reverses the order of the listing. Otherwise, the editor given by +<var>ename</var> is invoked on a file containing those commands. If +<var>ename</var> is not given, the value of the following variable expansion +is used: <code>${FCEDIT:-${EDITOR:-vi}}</code>. This says to use the +value of the <code>FCEDIT</code> variable if set, or the value of the +<code>EDITOR</code> variable if that is set, or <code>vi</code> if neither is set. +When editing is complete, the edited commands are echoed and executed. +</p> +<p>In the second form, <var>command</var> is re-executed after each instance +of <var>pat</var> in the selected command is replaced by <var>rep</var>. +<var>command</var> is interpreted the same as <var>first</var> above. +</p> +<p>A useful alias to use with the <code>fc</code> command is <code>r='fc -s'</code>, so +that typing ‘<samp>r cc</samp>’ runs the last command beginning with <code>cc</code> +and typing ‘<samp>r</samp>’ re-executes the last command (see <a href="#Aliases">Aliases</a>). +</p> +</dd> +<dt id='index-history'><span><code>history</code><a href='#index-history' class='copiable-anchor'> ¶</a></span></dt> +<dd><div class="example"> +<pre class="example">history [<var>n</var>] +history -c +history -d <var>offset</var> +history -d <var>start</var>-<var>end</var> +history [-anrw] [<var>filename</var>] +history -ps <var>arg</var> +</pre></div> + +<p>With no options, display the history list with line numbers. +Lines prefixed with a ‘<samp>*</samp>’ have been modified. +An argument of <var>n</var> lists only the last <var>n</var> lines. +If the shell variable <code>HISTTIMEFORMAT</code> is set and not null, +it is used as a format string for <var>strftime</var> to display +the time stamp associated with each displayed history entry. +No intervening blank is printed between the formatted time stamp +and the history line. +</p> +<p>Options, if supplied, have the following meanings: +</p> +<dl compact="compact"> +<dt><span><code>-c</code></span></dt> +<dd><p>Clear the history list. This may be combined +with the other options to replace the history list completely. +</p> +</dd> +<dt><span><code>-d <var>offset</var></code></span></dt> +<dd><p>Delete the history entry at position <var>offset</var>. +If <var>offset</var> is positive, it should be specified as it appears when +the history is displayed. +If <var>offset</var> is negative, it is interpreted as relative to one greater +than the last history position, so negative indices count back from the +end of the history, and an index of ‘<samp>-1</samp>’ refers to the current +<code>history -d</code> command. +</p> +</dd> +<dt><span><code>-d <var>start</var>-<var>end</var></code></span></dt> +<dd><p>Delete the range of history entries between positions <var>start</var> and +<var>end</var>, inclusive. +Positive and negative values for <var>start</var> and <var>end</var> +are interpreted as described above. +</p> +</dd> +<dt><span><code>-a</code></span></dt> +<dd><p>Append the new history lines to the history file. +These are history lines entered since the beginning of the current +Bash session, but not already appended to the history file. +</p> +</dd> +<dt><span><code>-n</code></span></dt> +<dd><p>Append the history lines not already read from the history file +to the current history list. These are lines appended to the history +file since the beginning of the current Bash session. +</p> +</dd> +<dt><span><code>-r</code></span></dt> +<dd><p>Read the history file and append its contents to +the history list. +</p> +</dd> +<dt><span><code>-w</code></span></dt> +<dd><p>Write out the current history list to the history file. +</p> +</dd> +<dt><span><code>-p</code></span></dt> +<dd><p>Perform history substitution on the <var>arg</var>s and display the result +on the standard output, without storing the results in the history list. +</p> +</dd> +<dt><span><code>-s</code></span></dt> +<dd><p>The <var>arg</var>s are added to the end of +the history list as a single entry. +</p> +</dd> +</dl> + +<p>If a <var>filename</var> argument is supplied +when any of the <samp>-w</samp>, <samp>-r</samp>, <samp>-a</samp>, or <samp>-n</samp> options +is used, Bash uses <var>filename</var> as the history file. +If not, then the value of the <code>HISTFILE</code> variable is used. +</p> +<p>The return value is 0 unless an invalid option is encountered, an +error occurs while reading or writing the history file, an invalid +<var>offset</var> or range is supplied as an argument to <samp>-d</samp>, or the +history expansion supplied as an argument to <samp>-p</samp> fails. +</p> +</dd> +</dl> + +<hr> +</div> +<div class="section" id="History-Interaction"> +<div class="header"> +<p> +Previous: <a href="#Bash-History-Builtins" accesskey="p" rel="prev">Bash History Builtins</a>, Up: <a href="#Using-History-Interactively" accesskey="u" rel="up">Using History Interactively</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="History-Expansion"></span><h3 class="section">9.3 History Expansion</h3> +<span id="index-history-expansion"></span> + +<p>The History library provides a history expansion feature that is similar +to the history expansion provided by <code>csh</code>. This section +describes the syntax used to manipulate the history information. +</p> +<p>History expansions introduce words from the history list into +the input stream, making it easy to repeat commands, insert the +arguments to a previous command into the current input line, or +fix errors in previous commands quickly. +</p> +<p>History expansion is performed immediately after a complete line +is read, before the shell breaks it into words, and is performed +on each line individually. Bash attempts to inform the history +expansion functions about quoting still in effect from previous lines. +</p> +<p>History expansion takes place in two parts. The first is to determine +which line from the history list should be used during substitution. +The second is to select portions of that line for inclusion into the +current one. The line selected from the history is called the +<em>event</em>, and the portions of that line that are acted upon are +called <em>words</em>. Various <em>modifiers</em> are available to manipulate +the selected words. The line is broken into words in the same fashion +that Bash does, so that several words +surrounded by quotes are considered one word. +History expansions are introduced by the appearance of the +history expansion character, which is ‘<samp>!</samp>’ by default. +</p> +<p>History expansion implements shell-like quoting conventions: +a backslash can be used to remove the special handling for the next character; +single quotes enclose verbatim sequences of characters, and can be used to +inhibit history expansion; +and characters enclosed within double quotes may be subject to history +expansion, since backslash can escape the history expansion character, +but single quotes may not, since they are not treated specially within +double quotes. +</p> +<p>When using the shell, only ‘<samp>\</samp>’ and ‘<samp>'</samp>’ may be used to escape the +history expansion character, but the history expansion character is +also treated as quoted if it immediately precedes the closing double quote +in a double-quoted string. +</p> +<p>Several shell options settable with the <code>shopt</code> +builtin (see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>) may be used to tailor +the behavior of history expansion. If the +<code>histverify</code> shell option is enabled, and Readline +is being used, history substitutions are not immediately passed to +the shell parser. +Instead, the expanded line is reloaded into the Readline +editing buffer for further modification. +If Readline is being used, and the <code>histreedit</code> +shell option is enabled, a failed history expansion will be +reloaded into the Readline editing buffer for correction. +The <samp>-p</samp> option to the <code>history</code> builtin command +may be used to see what a history expansion will do before using it. +The <samp>-s</samp> option to the <code>history</code> builtin may be used to +add commands to the end of the history list without actually executing +them, so that they are available for subsequent recall. +This is most useful in conjunction with Readline. +</p> +<p>The shell allows control of the various characters used by the +history expansion mechanism with the <code>histchars</code> variable, +as explained above (see <a href="#Bash-Variables">Bash Variables</a>). The shell uses +the history comment character to mark history timestamps when +writing the history file. +</p> + +<ul class="section-toc"> +<li><a href="#Event-Designators" accesskey="1">Event Designators</a></li> +<li><a href="#Word-Designators" accesskey="2">Word Designators</a></li> +<li><a href="#Modifiers" accesskey="3">Modifiers</a></li> +</ul> +<hr> +<div class="subsection" id="Event-Designators"> +<div class="header"> +<p> +Next: <a href="#Word-Designators" accesskey="n" rel="next">Word Designators</a>, Up: <a href="#History-Interaction" accesskey="u" rel="up">History Expansion</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Event-Designators-1"></span><h4 class="subsection">9.3.1 Event Designators</h4> +<span id="index-event-designators"></span> + +<p>An event designator is a reference to a command line entry in the +history list. +Unless the reference is absolute, events are relative to the current +position in the history list. +<span id="index-history-events"></span> +</p> +<dl compact="compact"> +<dt><span><code>!</code></span></dt> +<dd><p>Start a history substitution, except when followed by a space, tab, +the end of the line, ‘<samp>=</samp>’ or ‘<samp>(</samp>’ (when the +<code>extglob</code> shell option is enabled using the <code>shopt</code> builtin). +</p> +</dd> +<dt><span><code>!<var>n</var></code></span></dt> +<dd><p>Refer to command line <var>n</var>. +</p> +</dd> +<dt><span><code>!-<var>n</var></code></span></dt> +<dd><p>Refer to the command <var>n</var> lines back. +</p> +</dd> +<dt><span><code>!!</code></span></dt> +<dd><p>Refer to the previous command. This is a synonym for ‘<samp>!-1</samp>’. +</p> +</dd> +<dt><span><code>!<var>string</var></code></span></dt> +<dd><p>Refer to the most recent command +preceding the current position in the history list +starting with <var>string</var>. +</p> +</dd> +<dt><span><code>!?<var>string</var>[?]</code></span></dt> +<dd><p>Refer to the most recent command +preceding the current position in the history list +containing <var>string</var>. +The trailing +‘<samp>?</samp>’ may be omitted if the <var>string</var> is followed immediately by +a newline. +If <var>string</var> is missing, the string from the most recent search is used; +it is an error if there is no previous search string. +</p> +</dd> +<dt><span><code>^<var>string1</var>^<var>string2</var>^</code></span></dt> +<dd><p>Quick Substitution. Repeat the last command, replacing <var>string1</var> +with <var>string2</var>. Equivalent to +<code>!!:s^<var>string1</var>^<var>string2</var>^</code>. +</p> +</dd> +<dt><span><code>!#</code></span></dt> +<dd><p>The entire command line typed so far. +</p> +</dd> +</dl> + +<hr> +</div> +<div class="subsection" id="Word-Designators"> +<div class="header"> +<p> +Next: <a href="#Modifiers" accesskey="n" rel="next">Modifiers</a>, Previous: <a href="#Event-Designators" accesskey="p" rel="prev">Event Designators</a>, Up: <a href="#History-Interaction" accesskey="u" rel="up">History Expansion</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Word-Designators-1"></span><h4 class="subsection">9.3.2 Word Designators</h4> + +<p>Word designators are used to select desired words from the event. +A ‘<samp>:</samp>’ separates the event specification from the word designator. It +may be omitted if the word designator begins with a ‘<samp>^</samp>’, ‘<samp>$</samp>’, +‘<samp>*</samp>’, ‘<samp>-</samp>’, or ‘<samp>%</samp>’. Words are numbered from the beginning +of the line, with the first word being denoted by 0 (zero). Words are +inserted into the current line separated by single spaces. +</p> +<p>For example, +</p> +<dl compact="compact"> +<dt><span><code>!!</code></span></dt> +<dd><p>designates the preceding command. When you type this, the preceding +command is repeated in toto. +</p> +</dd> +<dt><span><code>!!:$</code></span></dt> +<dd><p>designates the last argument of the preceding command. This may be +shortened to <code>!$</code>. +</p> +</dd> +<dt><span><code>!fi:2</code></span></dt> +<dd><p>designates the second argument of the most recent command starting with +the letters <code>fi</code>. +</p></dd> +</dl> + +<p>Here are the word designators: +</p> +<dl compact="compact"> +<dt><span><code>0 (zero)</code></span></dt> +<dd><p>The <code>0</code>th word. For many applications, this is the command word. +</p> +</dd> +<dt><span><code><var>n</var></code></span></dt> +<dd><p>The <var>n</var>th word. +</p> +</dd> +<dt><span><code>^</code></span></dt> +<dd><p>The first argument; that is, word 1. +</p> +</dd> +<dt><span><code>$</code></span></dt> +<dd><p>The last argument. +</p> +</dd> +<dt><span><code>%</code></span></dt> +<dd><p>The first word matched by the most recent ‘<samp>?<var>string</var>?</samp>’ search, +if the search string begins with a character that is part of a word. +</p> +</dd> +<dt><span><code><var>x</var>-<var>y</var></code></span></dt> +<dd><p>A range of words; ‘<samp>-<var>y</var></samp>’ abbreviates ‘<samp>0-<var>y</var></samp>’. +</p> +</dd> +<dt><span><code>*</code></span></dt> +<dd><p>All of the words, except the <code>0</code>th. This is a synonym for ‘<samp>1-$</samp>’. +It is not an error to use ‘<samp>*</samp>’ if there is just one word in the event; +the empty string is returned in that case. +</p> +</dd> +<dt><span><code><var>x</var>*</code></span></dt> +<dd><p>Abbreviates ‘<samp><var>x</var>-$</samp>’ +</p> +</dd> +<dt><span><code><var>x</var>-</code></span></dt> +<dd><p>Abbreviates ‘<samp><var>x</var>-$</samp>’ like ‘<samp><var>x</var>*</samp>’, but omits the last word. +If ‘<samp>x</samp>’ is missing, it defaults to 0. +</p> +</dd> +</dl> + +<p>If a word designator is supplied without an event specification, the +previous command is used as the event. +</p> +<hr> +</div> +<div class="subsection" id="Modifiers"> +<div class="header"> +<p> +Previous: <a href="#Word-Designators" accesskey="p" rel="prev">Word Designators</a>, Up: <a href="#History-Interaction" accesskey="u" rel="up">History Expansion</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Modifiers-1"></span><h4 class="subsection">9.3.3 Modifiers</h4> + +<p>After the optional word designator, you can add a sequence of one or more +of the following modifiers, each preceded by a ‘<samp>:</samp>’. +These modify, or edit, the word or words selected from the history event. +</p> +<dl compact="compact"> +<dt><span><code>h</code></span></dt> +<dd><p>Remove a trailing pathname component, leaving only the head. +</p> +</dd> +<dt><span><code>t</code></span></dt> +<dd><p>Remove all leading pathname components, leaving the tail. +</p> +</dd> +<dt><span><code>r</code></span></dt> +<dd><p>Remove a trailing suffix of the form ‘<samp>.<var>suffix</var></samp>’, leaving +the basename. +</p> +</dd> +<dt><span><code>e</code></span></dt> +<dd><p>Remove all but the trailing suffix. +</p> +</dd> +<dt><span><code>p</code></span></dt> +<dd><p>Print the new command but do not execute it. +</p> +</dd> +<dt><span><code>q</code></span></dt> +<dd><p>Quote the substituted words, escaping further substitutions. +</p> +</dd> +<dt><span><code>x</code></span></dt> +<dd><p>Quote the substituted words as with ‘<samp>q</samp>’, +but break into words at spaces, tabs, and newlines. +The ‘<samp>q</samp>’ and ‘<samp>x</samp>’ modifiers are mutually exclusive; the last one +supplied is used. +</p> +</dd> +<dt><span><code>s/<var>old</var>/<var>new</var>/</code></span></dt> +<dd><p>Substitute <var>new</var> for the first occurrence of <var>old</var> in the +event line. +Any character may be used as the delimiter in place of ‘<samp>/</samp>’. +The delimiter may be quoted in <var>old</var> and <var>new</var> +with a single backslash. If ‘<samp>&</samp>’ appears in <var>new</var>, +it is replaced by <var>old</var>. A single backslash will quote +the ‘<samp>&</samp>’. +If <var>old</var> is null, it is set to the last <var>old</var> +substituted, or, if no previous history substitutions took place, +the last <var>string</var> +in a !?<var>string</var><code>[?]</code> +search. +If <var>new</var> is null, each matching <var>old</var> is deleted. +The final delimiter is optional if it is the last +character on the input line. +</p> +</dd> +<dt><span><code>&</code></span></dt> +<dd><p>Repeat the previous substitution. +</p> +</dd> +<dt><span><code>g</code></span></dt> +<dt><span><code>a</code></span></dt> +<dd><p>Cause changes to be applied over the entire event line. Used in +conjunction with ‘<samp>s</samp>’, as in <code>gs/<var>old</var>/<var>new</var>/</code>, +or with ‘<samp>&</samp>’. +</p> +</dd> +<dt><span><code>G</code></span></dt> +<dd><p>Apply the following ‘<samp>s</samp>’ or ‘<samp>&</samp>’ modifier once to each word +in the event. +</p> +</dd> +</dl> + +<hr> +</div> +</div> +</div> +<div class="chapter" id="Installing-Bash"> +<div class="header"> +<p> +Next: <a href="#Reporting-Bugs" accesskey="n" rel="next">Reporting Bugs</a>, Previous: <a href="#Using-History-Interactively" accesskey="p" rel="prev">Using History Interactively</a>, Up: <a href="#Top" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Installing-Bash-1"></span><h2 class="chapter">10 Installing Bash</h2> + +<p>This chapter provides basic instructions for installing Bash on +the various supported platforms. The distribution supports the +<small>GNU</small> operating systems, nearly every version of Unix, and several +non-Unix systems such as BeOS and Interix. +Other independent ports exist for +<small>MS-DOS</small>, <small>OS/2</small>, and Windows platforms. +</p> + +<ul class="section-toc"> +<li><a href="#Basic-Installation" accesskey="1">Basic Installation</a></li> +<li><a href="#Compilers-and-Options" accesskey="2">Compilers and Options</a></li> +<li><a href="#Compiling-For-Multiple-Architectures" accesskey="3">Compiling For Multiple Architectures</a></li> +<li><a href="#Installation-Names" accesskey="4">Installation Names</a></li> +<li><a href="#Specifying-the-System-Type" accesskey="5">Specifying the System Type</a></li> +<li><a href="#Sharing-Defaults" accesskey="6">Sharing Defaults</a></li> +<li><a href="#Operation-Controls" accesskey="7">Operation Controls</a></li> +<li><a href="#Optional-Features" accesskey="8">Optional Features</a></li> +</ul> +<hr> +<div class="section" id="Basic-Installation"> +<div class="header"> +<p> +Next: <a href="#Compilers-and-Options" accesskey="n" rel="next">Compilers and Options</a>, Up: <a href="#Installing-Bash" accesskey="u" rel="up">Installing Bash</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Basic-Installation-1"></span><h3 class="section">10.1 Basic Installation</h3> +<span id="index-installation"></span> +<span id="index-configuration"></span> +<span id="index-Bash-installation"></span> +<span id="index-Bash-configuration"></span> + +<p>These are installation instructions for Bash. +</p> +<p>The simplest way to compile Bash is: +</p> +<ol> +<li> <code>cd</code> to the directory containing the source code and type +‘<samp>./configure</samp>’ to configure Bash for your system. If you’re +using <code>csh</code> on an old version of System V, you might need to +type ‘<samp>sh ./configure</samp>’ instead to prevent <code>csh</code> from trying +to execute <code>configure</code> itself. + +<p>Running <code>configure</code> takes some time. +While running, it prints messages telling which features it is +checking for. +</p> +</li><li> Type ‘<samp>make</samp>’ to compile Bash and build the <code>bashbug</code> bug +reporting script. + +</li><li> Optionally, type ‘<samp>make tests</samp>’ to run the Bash test suite. + +</li><li> Type ‘<samp>make install</samp>’ to install <code>bash</code> and <code>bashbug</code>. +This will also install the manual pages and Info file, message translation +files, some supplemental documentation, a number of example loadable +builtin commands, and a set of header files for developing loadable +builtins. +You may need additional privileges to install <code>bash</code> to your +desired destination, so ‘<samp>sudo make install</samp>’ might be required. +More information about controlling the locations where <code>bash</code> and +other files are installed is below (see <a href="#Installation-Names">Installation Names</a>). + +</li></ol> + +<p>The <code>configure</code> shell script attempts to guess correct +values for various system-dependent variables used during +compilation. It uses those values to create a <samp>Makefile</samp> in +each directory of the package (the top directory, the +<samp>builtins</samp>, <samp>doc</samp>, <samp>po</samp>, and <samp>support</samp> directories, +each directory under <samp>lib</samp>, and several others). It also creates a +<samp>config.h</samp> file containing system-dependent definitions. +Finally, it creates a shell script named <code>config.status</code> that you +can run in the future to recreate the current configuration, a +file <samp>config.cache</samp> that saves the results of its tests to +speed up reconfiguring, and a file <samp>config.log</samp> containing +compiler output (useful mainly for debugging <code>configure</code>). +If at some point +<samp>config.cache</samp> contains results you don’t want to keep, you +may remove or edit it. +</p> +<p>To find out more about the options and arguments that the +<code>configure</code> script understands, type +</p> +<div class="example"> +<pre class="example">bash-4.2$ ./configure --help +</pre></div> + +<p>at the Bash prompt in your Bash source directory. +</p> +<p>If you want to build Bash in a directory separate from the source +directory – to build for multiple architectures, for example – +just use the full path to the configure script. The following commands +will build bash in a directory under <samp>/usr/local/build</samp> from +the source code in <samp>/usr/local/src/bash-4.4</samp>: +</p> +<div class="example"> +<pre class="example">mkdir /usr/local/build/bash-4.4 +cd /usr/local/build/bash-4.4 +bash /usr/local/src/bash-4.4/configure +make +</pre></div> + +<p>See <a href="#Compiling-For-Multiple-Architectures">Compiling For Multiple Architectures</a> for more information +about building in a directory separate from the source. +</p> +<p>If you need to do unusual things to compile Bash, please +try to figure out how <code>configure</code> could check whether or not +to do them, and mail diffs or instructions to +<a href="mailto:bash-maintainers@gnu.org">bash-maintainers@gnu.org</a> so they can be +considered for the next release. +</p> +<p>The file <samp>configure.ac</samp> is used to create <code>configure</code> +by a program called Autoconf. +You only need <samp>configure.ac</samp> if you want to change it or regenerate +<code>configure</code> using a newer version of Autoconf. +If you do this, make sure you are using Autoconf version 2.69 or +newer. +</p> +<p>You can remove the program binaries and object files from the +source code directory by typing ‘<samp>make clean</samp>’. To also remove the +files that <code>configure</code> created (so you can compile Bash for +a different kind of computer), type ‘<samp>make distclean</samp>’. +</p> +<hr> +</div> +<div class="section" id="Compilers-and-Options"> +<div class="header"> +<p> +Next: <a href="#Compiling-For-Multiple-Architectures" accesskey="n" rel="next">Compiling For Multiple Architectures</a>, Previous: <a href="#Basic-Installation" accesskey="p" rel="prev">Basic Installation</a>, Up: <a href="#Installing-Bash" accesskey="u" rel="up">Installing Bash</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Compilers-and-Options-1"></span><h3 class="section">10.2 Compilers and Options</h3> + +<p>Some systems require unusual options for compilation or linking +that the <code>configure</code> script does not know about. You can +give <code>configure</code> initial values for variables by setting +them in the environment. Using a Bourne-compatible shell, you +can do that on the command line like this: +</p> +<div class="example"> +<pre class="example">CC=c89 CFLAGS=-O2 LIBS=-lposix ./configure +</pre></div> + +<p>On systems that have the <code>env</code> program, you can do it like this: +</p> +<div class="example"> +<pre class="example">env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure +</pre></div> + +<p>The configuration process uses GCC to build Bash if it +is available. +</p> +<hr> +</div> +<div class="section" id="Compiling-For-Multiple-Architectures"> +<div class="header"> +<p> +Next: <a href="#Installation-Names" accesskey="n" rel="next">Installation Names</a>, Previous: <a href="#Compilers-and-Options" accesskey="p" rel="prev">Compilers and Options</a>, Up: <a href="#Installing-Bash" accesskey="u" rel="up">Installing Bash</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Compiling-For-Multiple-Architectures-1"></span><h3 class="section">10.3 Compiling For Multiple Architectures</h3> + +<p>You can compile Bash for more than one kind of computer at the +same time, by placing the object files for each architecture in their +own directory. To do this, you must use a version of <code>make</code> that +supports the <code>VPATH</code> variable, such as GNU <code>make</code>. +<code>cd</code> to the +directory where you want the object files and executables to go and run +the <code>configure</code> script from the source directory +(see <a href="#Basic-Installation">Basic Installation</a>). +You may need to +supply the <samp>--srcdir=PATH</samp> argument to tell <code>configure</code> where the +source files are. <code>configure</code> automatically checks for the +source code in the directory that <code>configure</code> is in and in ‘..’. +</p> +<p>If you have to use a <code>make</code> that does not support the <code>VPATH</code> +variable, you can compile Bash for one architecture at a +time in the source code directory. After you have installed +Bash for one architecture, use ‘<samp>make distclean</samp>’ before +reconfiguring for another architecture. +</p> +<p>Alternatively, if your system supports symbolic links, you can use the +<samp>support/mkclone</samp> script to create a build tree which has +symbolic links back to each file in the source directory. Here’s an +example that creates a build directory in the current directory from a +source directory <samp>/usr/gnu/src/bash-2.0</samp>: +</p> +<div class="example"> +<pre class="example">bash /usr/gnu/src/bash-2.0/support/mkclone -s /usr/gnu/src/bash-2.0 . +</pre></div> + +<p>The <code>mkclone</code> script requires Bash, so you must have already built +Bash for at least one architecture before you can create build +directories for other architectures. +</p> +<hr> +</div> +<div class="section" id="Installation-Names"> +<div class="header"> +<p> +Next: <a href="#Specifying-the-System-Type" accesskey="n" rel="next">Specifying the System Type</a>, Previous: <a href="#Compiling-For-Multiple-Architectures" accesskey="p" rel="prev">Compiling For Multiple Architectures</a>, Up: <a href="#Installing-Bash" accesskey="u" rel="up">Installing Bash</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Installation-Names-1"></span><h3 class="section">10.4 Installation Names</h3> + +<p>By default, ‘<samp>make install</samp>’ will install into +<samp>/usr/local/bin</samp>, <samp>/usr/local/man</samp>, etc.; +that is, the <em>installation prefix</em> defaults to <samp>/usr/local</samp>. +You can specify an installation prefix other than <samp>/usr/local</samp> by +giving <code>configure</code> the option <samp>--prefix=<var>PATH</var></samp>, +or by specifying a value for the <code>prefix</code> ‘<samp>make</samp>’ +variable when running ‘<samp>make install</samp>’ +(e.g., ‘<samp>make install prefix=<var>PATH</var></samp>’). +The <code>prefix</code> variable provides a default for <code>exec_prefix</code> and +other variables used when installing bash. +</p> +<p>You can specify separate installation prefixes for +architecture-specific files and architecture-independent files. +If you give <code>configure</code> the option +<samp>--exec-prefix=<var>PATH</var></samp>, ‘<samp>make install</samp>’ will use +<var>PATH</var> as the prefix for installing programs and libraries. +Documentation and other data files will still use the regular prefix. +</p> +<p>If you would like to change the installation locations for a single run, +you can specify these variables as arguments to <code>make</code>: +‘<samp>make install exec_prefix=/</samp>’ will install <code>bash</code> and +<code>bashbug</code> into <samp>/bin</samp> instead of the default <samp>/usr/local/bin</samp>. +</p> +<p>If you want to see the files bash will install and where it will install +them without changing anything on your system, specify the variable +<code>DESTDIR</code> as an argument to <code>make</code>. Its value should be the +absolute directory path you’d like to use as the root of your sample +installation tree. For example, +</p> +<div class="example"> +<pre class="example">mkdir /fs1/bash-install +make install DESTDIR=/fs1/bash-install +</pre></div> + +<p>will install <code>bash</code> into <samp>/fs1/bash-install/usr/local/bin/bash</samp>, +the documentation into directories within +<samp>/fs1/bash-install/usr/local/share</samp>, the example loadable builtins into +<samp>/fs1/bash-install/usr/local/lib/bash</samp>, and so on. +You can use the usual <code>exec_prefix</code> and <code>prefix</code> variables to alter +the directory paths beneath the value of <code>DESTDIR</code>. +</p> +<p>The GNU Makefile standards provide a more complete description of these +variables and their effects. +</p> +<hr> +</div> +<div class="section" id="Specifying-the-System-Type"> +<div class="header"> +<p> +Next: <a href="#Sharing-Defaults" accesskey="n" rel="next">Sharing Defaults</a>, Previous: <a href="#Installation-Names" accesskey="p" rel="prev">Installation Names</a>, Up: <a href="#Installing-Bash" accesskey="u" rel="up">Installing Bash</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Specifying-the-System-Type-1"></span><h3 class="section">10.5 Specifying the System Type</h3> + +<p>There may be some features <code>configure</code> can not figure out +automatically, but needs to determine by the type of host Bash +will run on. Usually <code>configure</code> can figure that +out, but if it prints a message saying it can not guess the host +type, give it the <samp>--host=TYPE</samp> option. ‘<samp>TYPE</samp>’ can +either be a short name for the system type, such as ‘<samp>sun4</samp>’, +or a canonical name with three fields: ‘<samp>CPU-COMPANY-SYSTEM</samp>’ +(e.g., ‘<samp>i386-unknown-freebsd4.2</samp>’). +</p> +<p>See the file <samp>support/config.sub</samp> for the possible +values of each field. +</p> +<hr> +</div> +<div class="section" id="Sharing-Defaults"> +<div class="header"> +<p> +Next: <a href="#Operation-Controls" accesskey="n" rel="next">Operation Controls</a>, Previous: <a href="#Specifying-the-System-Type" accesskey="p" rel="prev">Specifying the System Type</a>, Up: <a href="#Installing-Bash" accesskey="u" rel="up">Installing Bash</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Sharing-Defaults-1"></span><h3 class="section">10.6 Sharing Defaults</h3> + +<p>If you want to set default values for <code>configure</code> scripts to +share, you can create a site shell script called +<code>config.site</code> that gives default values for variables like +<code>CC</code>, <code>cache_file</code>, and <code>prefix</code>. <code>configure</code> +looks for <samp>PREFIX/share/config.site</samp> if it exists, then +<samp>PREFIX/etc/config.site</samp> if it exists. Or, you can set the +<code>CONFIG_SITE</code> environment variable to the location of the site +script. A warning: the Bash <code>configure</code> looks for a site script, +but not all <code>configure</code> scripts do. +</p> +<hr> +</div> +<div class="section" id="Operation-Controls"> +<div class="header"> +<p> +Next: <a href="#Optional-Features" accesskey="n" rel="next">Optional Features</a>, Previous: <a href="#Sharing-Defaults" accesskey="p" rel="prev">Sharing Defaults</a>, Up: <a href="#Installing-Bash" accesskey="u" rel="up">Installing Bash</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Operation-Controls-1"></span><h3 class="section">10.7 Operation Controls</h3> + +<p><code>configure</code> recognizes the following options to control how it +operates. +</p> +<dl compact="compact"> +<dt><span><code>--cache-file=<var>file</var></code></span></dt> +<dd><p>Use and save the results of the tests in +<var>file</var> instead of <samp>./config.cache</samp>. Set <var>file</var> to +<samp>/dev/null</samp> to disable caching, for debugging +<code>configure</code>. +</p> +</dd> +<dt><span><code>--help</code></span></dt> +<dd><p>Print a summary of the options to <code>configure</code>, and exit. +</p> +</dd> +<dt><span><code>--quiet</code></span></dt> +<dt><span><code>--silent</code></span></dt> +<dt><span><code>-q</code></span></dt> +<dd><p>Do not print messages saying which checks are being made. +</p> +</dd> +<dt><span><code>--srcdir=<var>dir</var></code></span></dt> +<dd><p>Look for the Bash source code in directory <var>dir</var>. Usually +<code>configure</code> can determine that directory automatically. +</p> +</dd> +<dt><span><code>--version</code></span></dt> +<dd><p>Print the version of Autoconf used to generate the <code>configure</code> +script, and exit. +</p></dd> +</dl> + +<p><code>configure</code> also accepts some other, not widely used, boilerplate +options. ‘<samp>configure --help</samp>’ prints the complete list. +</p> +<hr> +</div> +<div class="section" id="Optional-Features"> +<div class="header"> +<p> +Previous: <a href="#Operation-Controls" accesskey="p" rel="prev">Operation Controls</a>, Up: <a href="#Installing-Bash" accesskey="u" rel="up">Installing Bash</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Optional-Features-1"></span><h3 class="section">10.8 Optional Features</h3> + +<p>The Bash <code>configure</code> has a number of <samp>--enable-<var>feature</var></samp> +options, where <var>feature</var> indicates an optional part of Bash. +There are also several <samp>--with-<var>package</var></samp> options, +where <var>package</var> is something like ‘<samp>bash-malloc</samp>’ or ‘<samp>purify</samp>’. +To turn off the default use of a package, use +<samp>--without-<var>package</var></samp>. To configure Bash without a feature +that is enabled by default, use <samp>--disable-<var>feature</var></samp>. +</p> +<p>Here is a complete list of the <samp>--enable-</samp> and +<samp>--with-</samp> options that the Bash <code>configure</code> recognizes. +</p> +<dl compact="compact"> +<dt><span><code>--with-afs</code></span></dt> +<dd><p>Define if you are using the Andrew File System from Transarc. +</p> +</dd> +<dt><span><code>--with-bash-malloc</code></span></dt> +<dd><p>Use the Bash version of +<code>malloc</code> in the directory <samp>lib/malloc</samp>. This is not the same +<code>malloc</code> that appears in <small>GNU</small> libc, but an older version +originally derived from the 4.2 <small>BSD</small> <code>malloc</code>. This <code>malloc</code> +is very fast, but wastes some space on each allocation. +This option is enabled by default. +The <samp>NOTES</samp> file contains a list of systems for +which this should be turned off, and <code>configure</code> disables this +option automatically for a number of systems. +</p> +</dd> +<dt><span><code>--with-curses</code></span></dt> +<dd><p>Use the curses library instead of the termcap library. This should +be supplied if your system has an inadequate or incomplete termcap +database. +</p> +</dd> +<dt><span><code>--with-gnu-malloc</code></span></dt> +<dd><p>A synonym for <code>--with-bash-malloc</code>. +</p> +</dd> +<dt><span><code>--with-installed-readline[=<var>PREFIX</var>]</code></span></dt> +<dd><p>Define this to make Bash link with a locally-installed version of Readline +rather than the version in <samp>lib/readline</samp>. This works only with +Readline 5.0 and later versions. If <var>PREFIX</var> is <code>yes</code> or not +supplied, <code>configure</code> uses the values of the make variables +<code>includedir</code> and <code>libdir</code>, which are subdirectories of <code>prefix</code> +by default, to find the installed version of Readline if it is not in +the standard system include and library directories. +If <var>PREFIX</var> is <code>no</code>, Bash links with the version in +<samp>lib/readline</samp>. +If <var>PREFIX</var> is set to any other value, <code>configure</code> treats it as +a directory pathname and looks for +the installed version of Readline in subdirectories of that directory +(include files in <var>PREFIX</var>/<code>include</code> and the library in +<var>PREFIX</var>/<code>lib</code>). +</p> +</dd> +<dt><span><code>--with-libintl-prefix[=<var>PREFIX</var>]</code></span></dt> +<dd><p>Define this to make Bash link with a locally-installed version of the +libintl library instead of the version in <samp>lib/intl</samp>. +</p> +</dd> +<dt><span><code>--with-libiconv-prefix[=<var>PREFIX</var>]</code></span></dt> +<dd><p>Define this to make Bash look for libiconv in <var>PREFIX</var> instead of the +standard system locations. There is no version included with Bash. +</p> +</dd> +<dt><span><code>--enable-minimal-config</code></span></dt> +<dd><p>This produces a shell with minimal features, close to the historical +Bourne shell. +</p></dd> +</dl> + +<p>There are several <samp>--enable-</samp> options that alter how Bash is +compiled, linked, and installed, rather than changing run-time features. +</p> +<dl compact="compact"> +<dt><span><code>--enable-largefile</code></span></dt> +<dd><p>Enable support for <a href="http://www.unix.org/version2/whatsnew/lfs20mar.html">large files</a> if the operating system requires special compiler options +to build programs which can access large files. This is enabled by +default, if the operating system provides large file support. +</p> +</dd> +<dt><span><code>--enable-profiling</code></span></dt> +<dd><p>This builds a Bash binary that produces profiling information to be +processed by <code>gprof</code> each time it is executed. +</p> +</dd> +<dt><span><code>--enable-separate-helpfiles</code></span></dt> +<dd><p>Use external files for the documentation displayed by the <code>help</code> builtin +instead of storing the text internally. +</p> +</dd> +<dt><span><code>--enable-static-link</code></span></dt> +<dd><p>This causes Bash to be linked statically, if <code>gcc</code> is being used. +This could be used to build a version to use as root’s shell. +</p> +</dd> +</dl> + +<p>The ‘<samp>minimal-config</samp>’ option can be used to disable all of +the following options, but it is processed first, so individual +options may be enabled using ‘<samp>enable-<var>feature</var></samp>’. +</p> +<p>All of the following options except for +‘<samp>alt-array-implementation</samp>’, +‘<samp>disabled-builtins</samp>’, +‘<samp>direxpand-default</samp>’, +‘<samp>strict-posix-default</samp>’, +and +‘<samp>xpg-echo-default</samp>’ are +enabled by default, unless the operating system does not provide the +necessary support. +</p> +<dl compact="compact"> +<dt><span><code>--enable-alias</code></span></dt> +<dd><p>Allow alias expansion and include the <code>alias</code> and <code>unalias</code> +builtins (see <a href="#Aliases">Aliases</a>). +</p> +</dd> +<dt><span><code>--enable-alt-array-implementation</code></span></dt> +<dd><p>This builds bash using an alternate implementation of arrays +(see <a href="#Arrays">Arrays</a>) that provides faster access at the expense of using +more memory (sometimes many times more, depending on how sparse an array is). +</p> +</dd> +<dt><span><code>--enable-arith-for-command</code></span></dt> +<dd><p>Include support for the alternate form of the <code>for</code> command +that behaves like the C language <code>for</code> statement +(see <a href="#Looping-Constructs">Looping Constructs</a>). +</p> +</dd> +<dt><span><code>--enable-array-variables</code></span></dt> +<dd><p>Include support for one-dimensional array shell variables +(see <a href="#Arrays">Arrays</a>). +</p> +</dd> +<dt><span><code>--enable-bang-history</code></span></dt> +<dd><p>Include support for <code>csh</code>-like history substitution +(see <a href="#History-Interaction">History Expansion</a>). +</p> +</dd> +<dt><span><code>--enable-brace-expansion</code></span></dt> +<dd><p>Include <code>csh</code>-like brace expansion +( <code>b{a,b}c</code> → <code>bac bbc</code> ). +See <a href="#Brace-Expansion">Brace Expansion</a>, for a complete description. +</p> +</dd> +<dt><span><code>--enable-casemod-attributes</code></span></dt> +<dd><p>Include support for case-modifying attributes in the <code>declare</code> builtin +and assignment statements. Variables with the <code>uppercase</code> attribute, +for example, will have their values converted to uppercase upon assignment. +</p> +</dd> +<dt><span><code>--enable-casemod-expansion</code></span></dt> +<dd><p>Include support for case-modifying word expansions. +</p> +</dd> +<dt><span><code>--enable-command-timing</code></span></dt> +<dd><p>Include support for recognizing <code>time</code> as a reserved word and for +displaying timing statistics for the pipeline following <code>time</code> +(see <a href="#Pipelines">Pipelines</a>). +This allows pipelines as well as shell builtins and functions to be timed. +</p> +</dd> +<dt><span><code>--enable-cond-command</code></span></dt> +<dd><p>Include support for the <code>[[</code> conditional command. +(see <a href="#Conditional-Constructs">Conditional Constructs</a>). +</p> +</dd> +<dt><span><code>--enable-cond-regexp</code></span></dt> +<dd><p>Include support for matching <small>POSIX</small> regular expressions using the +‘<samp>=~</samp>’ binary operator in the <code>[[</code> conditional command. +(see <a href="#Conditional-Constructs">Conditional Constructs</a>). +</p> +</dd> +<dt><span><code>--enable-coprocesses</code></span></dt> +<dd><p>Include support for coprocesses and the <code>coproc</code> reserved word +(see <a href="#Pipelines">Pipelines</a>). +</p> +</dd> +<dt><span><code>--enable-debugger</code></span></dt> +<dd><p>Include support for the bash debugger (distributed separately). +</p> +</dd> +<dt><span><code>--enable-dev-fd-stat-broken</code></span></dt> +<dd><p>If calling <code>stat</code> on /dev/fd/<var>N</var> returns different results than +calling <code>fstat</code> on file descriptor <var>N</var>, supply this option to +enable a workaround. +This has implications for conditional commands that test file attributes. +</p> +</dd> +<dt><span><code>--enable-direxpand-default</code></span></dt> +<dd><p>Cause the <code>direxpand</code> shell option (see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>) +to be enabled by default when the shell starts. +It is normally disabled by default. +</p> +</dd> +<dt><span><code>--enable-directory-stack</code></span></dt> +<dd><p>Include support for a <code>csh</code>-like directory stack and the +<code>pushd</code>, <code>popd</code>, and <code>dirs</code> builtins +(see <a href="#The-Directory-Stack">The Directory Stack</a>). +</p> +</dd> +<dt><span><code>--enable-disabled-builtins</code></span></dt> +<dd><p>Allow builtin commands to be invoked via ‘<samp>builtin xxx</samp>’ +even after <code>xxx</code> has been disabled using ‘<samp>enable -n xxx</samp>’. +See <a href="#Bash-Builtins">Bash Builtin Commands</a>, for details of the <code>builtin</code> and +<code>enable</code> builtin commands. +</p> +</dd> +<dt><span><code>--enable-dparen-arithmetic</code></span></dt> +<dd><p>Include support for the <code>((…))</code> command +(see <a href="#Conditional-Constructs">Conditional Constructs</a>). +</p> +</dd> +<dt><span><code>--enable-extended-glob</code></span></dt> +<dd><p>Include support for the extended pattern matching features described +above under <a href="#Pattern-Matching">Pattern Matching</a>. +</p> +</dd> +<dt><span><code>--enable-extended-glob-default</code></span></dt> +<dd><p>Set the default value of the <code>extglob</code> shell option described +above under <a href="#The-Shopt-Builtin">The Shopt Builtin</a> to be enabled. +</p> +</dd> +<dt><span><code>--enable-function-import</code></span></dt> +<dd><p>Include support for importing function definitions exported by another +instance of the shell from the environment. This option is enabled by +default. +</p> +</dd> +<dt><span><code>--enable-glob-asciirange-default</code></span></dt> +<dd><p>Set the default value of the <code>globasciiranges</code> shell option described +above under <a href="#The-Shopt-Builtin">The Shopt Builtin</a> to be enabled. +This controls the behavior of character ranges when used in pattern matching +bracket expressions. +</p> +</dd> +<dt><span><code>--enable-help-builtin</code></span></dt> +<dd><p>Include the <code>help</code> builtin, which displays help on shell builtins and +variables (see <a href="#Bash-Builtins">Bash Builtin Commands</a>). +</p> +</dd> +<dt><span><code>--enable-history</code></span></dt> +<dd><p>Include command history and the <code>fc</code> and <code>history</code> +builtin commands (see <a href="#Bash-History-Facilities">Bash History Facilities</a>). +</p> +</dd> +<dt><span><code>--enable-job-control</code></span></dt> +<dd><p>This enables the job control features (see <a href="#Job-Control">Job Control</a>), +if the operating system supports them. +</p> +</dd> +<dt><span><code>--enable-multibyte</code></span></dt> +<dd><p>This enables support for multibyte characters if the operating +system provides the necessary support. +</p> +</dd> +<dt><span><code>--enable-net-redirections</code></span></dt> +<dd><p>This enables the special handling of filenames of the form +<code>/dev/tcp/<var>host</var>/<var>port</var></code> and +<code>/dev/udp/<var>host</var>/<var>port</var></code> +when used in redirections (see <a href="#Redirections">Redirections</a>). +</p> +</dd> +<dt><span><code>--enable-process-substitution</code></span></dt> +<dd><p>This enables process substitution (see <a href="#Process-Substitution">Process Substitution</a>) if +the operating system provides the necessary support. +</p> +</dd> +<dt><span><code>--enable-progcomp</code></span></dt> +<dd><p>Enable the programmable completion facilities +(see <a href="#Programmable-Completion">Programmable Completion</a>). +If Readline is not enabled, this option has no effect. +</p> +</dd> +<dt><span><code>--enable-prompt-string-decoding</code></span></dt> +<dd><p>Turn on the interpretation of a number of backslash-escaped characters +in the <code>$PS0</code>, <code>$PS1</code>, <code>$PS2</code>, and <code>$PS4</code> prompt +strings. See <a href="#Controlling-the-Prompt">Controlling the Prompt</a>, for a complete list of prompt +string escape sequences. +</p> +</dd> +<dt><span><code>--enable-readline</code></span></dt> +<dd><p>Include support for command-line editing and history with the Bash +version of the Readline library (see <a href="#Command-Line-Editing">Command Line Editing</a>). +</p> +</dd> +<dt><span><code>--enable-restricted</code></span></dt> +<dd><p>Include support for a <em>restricted shell</em>. If this is enabled, Bash, +when called as <code>rbash</code>, enters a restricted mode. See +<a href="#The-Restricted-Shell">The Restricted Shell</a>, for a description of restricted mode. +</p> +</dd> +<dt><span><code>--enable-select</code></span></dt> +<dd><p>Include the <code>select</code> compound command, which allows the generation of +simple menus (see <a href="#Conditional-Constructs">Conditional Constructs</a>). +</p> +</dd> +<dt><span><code>--enable-single-help-strings</code></span></dt> +<dd><p>Store the text displayed by the <code>help</code> builtin as a single string for +each help topic. This aids in translating the text to different languages. +You may need to disable this if your compiler cannot handle very long string +literals. +</p> +</dd> +<dt><span><code>--enable-strict-posix-default</code></span></dt> +<dd><p>Make Bash <small>POSIX</small>-conformant by default (see <a href="#Bash-POSIX-Mode">Bash POSIX Mode</a>). +</p> +</dd> +<dt><span><code>--enable-translatable-strings</code></span></dt> +<dd><p>Enable support for <code>$"<var>string</var>"</code> translatable strings +(see <a href="#Locale-Translation">Locale-Specific Translation</a>). +</p> +</dd> +<dt><span><code>--enable-usg-echo-default</code></span></dt> +<dd><p>A synonym for <code>--enable-xpg-echo-default</code>. +</p> +</dd> +<dt><span><code>--enable-xpg-echo-default</code></span></dt> +<dd><p>Make the <code>echo</code> builtin expand backslash-escaped characters by default, +without requiring the <samp>-e</samp> option. +This sets the default value of the <code>xpg_echo</code> shell option to <code>on</code>, +which makes the Bash <code>echo</code> behave more like the version specified in +the Single Unix Specification, version 3. +See <a href="#Bash-Builtins">Bash Builtin Commands</a>, for a description of the escape sequences that +<code>echo</code> recognizes. +</p></dd> +</dl> + +<p>The file <samp>config-top.h</samp> contains C Preprocessor +‘<samp>#define</samp>’ statements for options which are not settable from +<code>configure</code>. +Some of these are not meant to be changed; beware of the consequences if +you do. +Read the comments associated with each definition for more +information about its effect. +</p> +<hr> +</div> +</div> +<div class="appendix" id="Reporting-Bugs"> +<div class="header"> +<p> +Next: <a href="#Major-Differences-From-The-Bourne-Shell" accesskey="n" rel="next">Major Differences From The Bourne Shell</a>, Previous: <a href="#Installing-Bash" accesskey="p" rel="prev">Installing Bash</a>, Up: <a href="#Top" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Reporting-Bugs-1"></span><h2 class="appendix">Appendix A Reporting Bugs</h2> + +<p>Please report all bugs you find in Bash. +But first, you should +make sure that it really is a bug, and that it appears in the latest +version of Bash. +The latest version of Bash is always available for FTP from +<a href="ftp://ftp.gnu.org/pub/gnu/bash/">ftp://ftp.gnu.org/pub/gnu/bash/</a> and from +<a href="http://git.savannah.gnu.org/cgit/bash.git/snapshot/bash-master.tar.gz">http://git.savannah.gnu.org/cgit/bash.git/snapshot/bash-master.tar.gz</a>. +</p> +<p>Once you have determined that a bug actually exists, use the +<code>bashbug</code> command to submit a bug report. +If you have a fix, you are encouraged to mail that as well! +Suggestions and ‘philosophical’ bug reports may be mailed +to <a href="mailto:bug-bash@gnu.org">bug-bash@gnu.org</a> or posted to the Usenet +newsgroup <code>gnu.bash.bug</code>. +</p> +<p>All bug reports should include: +</p><ul> +<li> The version number of Bash. +</li><li> The hardware and operating system. +</li><li> The compiler used to compile Bash. +</li><li> A description of the bug behaviour. +</li><li> A short script or ‘recipe’ which exercises the bug and may be used +to reproduce it. +</li></ul> + +<p><code>bashbug</code> inserts the first three items automatically into +the template it provides for filing a bug report. +</p> +<p>Please send all reports concerning this manual to +<a href="mailto:bug-bash@gnu.org">bug-bash@gnu.org</a>. +</p> +<hr> +</div> +<div class="appendix" id="Major-Differences-From-The-Bourne-Shell"> +<div class="header"> +<p> +Next: <a href="#GNU-Free-Documentation-License" accesskey="n" rel="next">GNU Free Documentation License</a>, Previous: <a href="#Reporting-Bugs" accesskey="p" rel="prev">Reporting Bugs</a>, Up: <a href="#Top" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Major-Differences-From-The-Bourne-Shell-1"></span><h2 class="appendix">Appendix B Major Differences From The Bourne Shell</h2> + +<p>Bash implements essentially the same grammar, parameter and +variable expansion, redirection, and quoting as the Bourne Shell. +Bash uses the <small>POSIX</small> standard as the specification of +how these features are to be implemented. There are some +differences between the traditional Bourne shell and Bash; this +section quickly details the differences of significance. A +number of these differences are explained in greater depth in +previous sections. +This section uses the version of <code>sh</code> included in SVR4.2 (the +last version of the historical Bourne shell) as the baseline reference. +</p> +<ul> +<li> Bash is <small>POSIX</small>-conformant, even where the <small>POSIX</small> specification +differs from traditional <code>sh</code> behavior (see <a href="#Bash-POSIX-Mode">Bash POSIX Mode</a>). + +</li><li> Bash has multi-character invocation options (see <a href="#Invoking-Bash">Invoking Bash</a>). + +</li><li> Bash has command-line editing (see <a href="#Command-Line-Editing">Command Line Editing</a>) and +the <code>bind</code> builtin. + +</li><li> Bash provides a programmable word completion mechanism +(see <a href="#Programmable-Completion">Programmable Completion</a>), and builtin commands +<code>complete</code>, <code>compgen</code>, and <code>compopt</code>, to +manipulate it. + +</li><li> Bash has command history (see <a href="#Bash-History-Facilities">Bash History Facilities</a>) and the +<code>history</code> and <code>fc</code> builtins to manipulate it. +The Bash history list maintains timestamp information and uses the +value of the <code>HISTTIMEFORMAT</code> variable to display it. + +</li><li> Bash implements <code>csh</code>-like history expansion +(see <a href="#History-Interaction">History Expansion</a>). + +</li><li> Bash has one-dimensional array variables (see <a href="#Arrays">Arrays</a>), and the +appropriate variable expansions and assignment syntax to use them. +Several of the Bash builtins take options to act on arrays. +Bash provides a number of built-in array variables. + +</li><li> The <code>$'…'</code> quoting syntax, which expands ANSI-C +backslash-escaped characters in the text between the single quotes, +is supported (see <a href="#ANSI_002dC-Quoting">ANSI-C Quoting</a>). + +</li><li> Bash supports the <code>$"…"</code> quoting syntax to do +locale-specific translation of the characters between the double +quotes. The <samp>-D</samp>, <samp>--dump-strings</samp>, and <samp>--dump-po-strings</samp> +invocation options list the translatable strings found in a script +(see <a href="#Locale-Translation">Locale-Specific Translation</a>). + +</li><li> Bash implements the <code>!</code> keyword to negate the return value of +a pipeline (see <a href="#Pipelines">Pipelines</a>). +Very useful when an <code>if</code> statement needs to act only if a test fails. +The Bash ‘<samp>-o pipefail</samp>’ option to <code>set</code> will cause a pipeline to +return a failure status if any command fails. + +</li><li> Bash has the <code>time</code> reserved word and command timing (see <a href="#Pipelines">Pipelines</a>). +The display of the timing statistics may be controlled with the +<code>TIMEFORMAT</code> variable. + +</li><li> Bash implements the <code>for (( <var>expr1</var> ; <var>expr2</var> ; <var>expr3</var> ))</code> +arithmetic for command, similar to the C language (see <a href="#Looping-Constructs">Looping Constructs</a>). + +</li><li> Bash includes the <code>select</code> compound command, which allows the +generation of simple menus (see <a href="#Conditional-Constructs">Conditional Constructs</a>). + +</li><li> Bash includes the <code>[[</code> compound command, which makes conditional +testing part of the shell grammar (see <a href="#Conditional-Constructs">Conditional Constructs</a>), including +optional regular expression matching. + +</li><li> Bash provides optional case-insensitive matching for the <code>case</code> and +<code>[[</code> constructs. + +</li><li> Bash includes brace expansion (see <a href="#Brace-Expansion">Brace Expansion</a>) and tilde +expansion (see <a href="#Tilde-Expansion">Tilde Expansion</a>). + +</li><li> Bash implements command aliases and the <code>alias</code> and <code>unalias</code> +builtins (see <a href="#Aliases">Aliases</a>). + +</li><li> Bash provides shell arithmetic, the <code>((</code> compound command +(see <a href="#Conditional-Constructs">Conditional Constructs</a>), +and arithmetic expansion (see <a href="#Shell-Arithmetic">Shell Arithmetic</a>). + +</li><li> Variables present in the shell’s initial environment are automatically +exported to child processes. The Bourne shell does not normally do +this unless the variables are explicitly marked using the <code>export</code> +command. + +</li><li> Bash supports the ‘<samp>+=</samp>’ assignment operator, which appends to the value +of the variable named on the left hand side. + +</li><li> Bash includes the <small>POSIX</small> pattern removal ‘<samp>%</samp>’, ‘<samp>#</samp>’, ‘<samp>%%</samp>’ +and ‘<samp>##</samp>’ expansions to remove leading or trailing substrings from +variable values (see <a href="#Shell-Parameter-Expansion">Shell Parameter Expansion</a>). + +</li><li> The expansion <code>${#xx}</code>, which returns the length of <code>${xx}</code>, +is supported (see <a href="#Shell-Parameter-Expansion">Shell Parameter Expansion</a>). + +</li><li> The expansion <code>${var:</code><var>offset</var><code>[:</code><var>length</var><code>]}</code>, +which expands to the substring of <code>var</code>’s value of length +<var>length</var>, beginning at <var>offset</var>, is present +(see <a href="#Shell-Parameter-Expansion">Shell Parameter Expansion</a>). + +</li><li> The expansion +<code>${<var>var</var>/[/]</code><var>pattern</var><code>[/</code><var>replacement</var><code>]}</code>, +which matches <var>pattern</var> and replaces it with <var>replacement</var> in +the value of <var>var</var>, is available (see <a href="#Shell-Parameter-Expansion">Shell Parameter Expansion</a>). + +</li><li> The expansion <code>${!<var>prefix</var>*}</code> expansion, which expands to +the names of all shell variables whose names begin with <var>prefix</var>, +is available (see <a href="#Shell-Parameter-Expansion">Shell Parameter Expansion</a>). + +</li><li> Bash has indirect variable expansion using <code>${!word}</code> +(see <a href="#Shell-Parameter-Expansion">Shell Parameter Expansion</a>). + +</li><li> Bash can expand positional parameters beyond <code>$9</code> using +<code>${<var>num</var>}</code>. + +</li><li> The <small>POSIX</small> <code>$()</code> form of command substitution +is implemented (see <a href="#Command-Substitution">Command Substitution</a>), +and preferred to the Bourne shell’s <code>``</code> (which +is also implemented for backwards compatibility). + +</li><li> Bash has process substitution (see <a href="#Process-Substitution">Process Substitution</a>). + +</li><li> Bash automatically assigns variables that provide information about the +current user (<code>UID</code>, <code>EUID</code>, and <code>GROUPS</code>), the current host +(<code>HOSTTYPE</code>, <code>OSTYPE</code>, <code>MACHTYPE</code>, and <code>HOSTNAME</code>), +and the instance of Bash that is running (<code>BASH</code>, +<code>BASH_VERSION</code>, and <code>BASH_VERSINFO</code>). See <a href="#Bash-Variables">Bash Variables</a>, +for details. + +</li><li> The <code>IFS</code> variable is used to split only the results of expansion, +not all words (see <a href="#Word-Splitting">Word Splitting</a>). +This closes a longstanding shell security hole. + +</li><li> The filename expansion bracket expression code uses ‘<samp>!</samp>’ and ‘<samp>^</samp>’ +to negate the set of characters between the brackets. +The Bourne shell uses only ‘<samp>!</samp>’. + +</li><li> Bash implements the full set of <small>POSIX</small> filename expansion operators, +including character classes, equivalence classes, and +collating symbols (see <a href="#Filename-Expansion">Filename Expansion</a>). + +</li><li> Bash implements extended pattern matching features when the <code>extglob</code> +shell option is enabled (see <a href="#Pattern-Matching">Pattern Matching</a>). + +</li><li> It is possible to have a variable and a function with the same name; +<code>sh</code> does not separate the two name spaces. + +</li><li> Bash functions are permitted to have local variables using the +<code>local</code> builtin, and thus useful recursive functions may be written +(see <a href="#Bash-Builtins">Bash Builtin Commands</a>). + +</li><li> Variable assignments preceding commands affect only that command, even +builtins and functions (see <a href="#Environment">Environment</a>). +In <code>sh</code>, all variable assignments +preceding commands are global unless the command is executed from the +file system. + +</li><li> Bash performs filename expansion on filenames specified as operands +to input and output redirection operators (see <a href="#Redirections">Redirections</a>). + +</li><li> Bash contains the ‘<samp><></samp>’ redirection operator, allowing a file to be +opened for both reading and writing, and the ‘<samp>&></samp>’ redirection +operator, for directing standard output and standard error to the same +file (see <a href="#Redirections">Redirections</a>). + +</li><li> Bash includes the ‘<samp><<<</samp>’ redirection operator, allowing a string to +be used as the standard input to a command. + +</li><li> Bash implements the ‘<samp>[n]<&<var>word</var></samp>’ and ‘<samp>[n]>&<var>word</var></samp>’ +redirection operators, which move one file descriptor to another. + +</li><li> Bash treats a number of filenames specially when they are +used in redirection operators (see <a href="#Redirections">Redirections</a>). + +</li><li> Bash can open network connections to arbitrary machines and services +with the redirection operators (see <a href="#Redirections">Redirections</a>). + +</li><li> The <code>noclobber</code> option is available to avoid overwriting existing +files with output redirection (see <a href="#The-Set-Builtin">The Set Builtin</a>). +The ‘<samp>>|</samp>’ redirection operator may be used to override <code>noclobber</code>. + +</li><li> The Bash <code>cd</code> and <code>pwd</code> builtins (see <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>) +each take <samp>-L</samp> and <samp>-P</samp> options to switch between logical and +physical modes. + +</li><li> Bash allows a function to override a builtin with the same name, and provides +access to that builtin’s functionality within the function via the +<code>builtin</code> and <code>command</code> builtins (see <a href="#Bash-Builtins">Bash Builtin Commands</a>). + +</li><li> The <code>command</code> builtin allows selective disabling of functions +when command lookup is performed (see <a href="#Bash-Builtins">Bash Builtin Commands</a>). + +</li><li> Individual builtins may be enabled or disabled using the <code>enable</code> +builtin (see <a href="#Bash-Builtins">Bash Builtin Commands</a>). + +</li><li> The Bash <code>exec</code> builtin takes additional options that allow users +to control the contents of the environment passed to the executed +command, and what the zeroth argument to the command is to be +(see <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>). + +</li><li> Shell functions may be exported to children via the environment +using <code>export -f</code> (see <a href="#Shell-Functions">Shell Functions</a>). + +</li><li> The Bash <code>export</code>, <code>readonly</code>, and <code>declare</code> builtins can +take a <samp>-f</samp> option to act on shell functions, a <samp>-p</samp> option to +display variables with various attributes set in a format that can be +used as shell input, a <samp>-n</samp> option to remove various variable +attributes, and ‘<samp>name=value</samp>’ arguments to set variable attributes +and values simultaneously. + +</li><li> The Bash <code>hash</code> builtin allows a name to be associated with +an arbitrary filename, even when that filename cannot be found by +searching the <code>$PATH</code>, using ‘<samp>hash -p</samp>’ +(see <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>). + +</li><li> Bash includes a <code>help</code> builtin for quick reference to shell +facilities (see <a href="#Bash-Builtins">Bash Builtin Commands</a>). + +</li><li> The <code>printf</code> builtin is available to display formatted output +(see <a href="#Bash-Builtins">Bash Builtin Commands</a>). + +</li><li> The Bash <code>read</code> builtin (see <a href="#Bash-Builtins">Bash Builtin Commands</a>) +will read a line ending in ‘<samp>\</samp>’ with +the <samp>-r</samp> option, and will use the <code>REPLY</code> variable as a +default if no non-option arguments are supplied. +The Bash <code>read</code> builtin +also accepts a prompt string with the <samp>-p</samp> option and will use +Readline to obtain the line when given the <samp>-e</samp> option. +The <code>read</code> builtin also has additional options to control input: +the <samp>-s</samp> option will turn off echoing of input characters as +they are read, the <samp>-t</samp> option will allow <code>read</code> to time out +if input does not arrive within a specified number of seconds, the +<samp>-n</samp> option will allow reading only a specified number of +characters rather than a full line, and the <samp>-d</samp> option will read +until a particular character rather than newline. + +</li><li> The <code>return</code> builtin may be used to abort execution of scripts +executed with the <code>.</code> or <code>source</code> builtins +(see <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>). + +</li><li> Bash includes the <code>shopt</code> builtin, for finer control of shell +optional capabilities (see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>), and allows these options +to be set and unset at shell invocation (see <a href="#Invoking-Bash">Invoking Bash</a>). + +</li><li> Bash has much more optional behavior controllable with the <code>set</code> +builtin (see <a href="#The-Set-Builtin">The Set Builtin</a>). + +</li><li> The ‘<samp>-x</samp>’ (<samp>xtrace</samp>) option displays commands other than +simple commands when performing an execution trace +(see <a href="#The-Set-Builtin">The Set Builtin</a>). + +</li><li> The <code>test</code> builtin (see <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>) +is slightly different, as it implements the <small>POSIX</small> algorithm, +which specifies the behavior based on the number of arguments. + +</li><li> Bash includes the <code>caller</code> builtin, which displays the context of +any active subroutine call (a shell function or a script executed with +the <code>.</code> or <code>source</code> builtins). This supports the Bash +debugger. + +</li><li> The <code>trap</code> builtin (see <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>) allows a +<code>DEBUG</code> pseudo-signal specification, similar to <code>EXIT</code>. +Commands specified with a <code>DEBUG</code> trap are executed before every +simple command, <code>for</code> command, <code>case</code> command, +<code>select</code> command, every arithmetic <code>for</code> command, and before +the first command executes in a shell function. +The <code>DEBUG</code> trap is not inherited by shell functions unless the +function has been given the <code>trace</code> attribute or the +<code>functrace</code> option has been enabled using the <code>shopt</code> builtin. +The <code>extdebug</code> shell option has additional effects on the +<code>DEBUG</code> trap. + +<p>The <code>trap</code> builtin (see <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>) allows an +<code>ERR</code> pseudo-signal specification, similar to <code>EXIT</code> and <code>DEBUG</code>. +Commands specified with an <code>ERR</code> trap are executed after a simple +command fails, with a few exceptions. +The <code>ERR</code> trap is not inherited by shell functions unless the +<code>-o errtrace</code> option to the <code>set</code> builtin is enabled. +</p> +<p>The <code>trap</code> builtin (see <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>) allows a +<code>RETURN</code> pseudo-signal specification, similar to +<code>EXIT</code> and <code>DEBUG</code>. +Commands specified with a <code>RETURN</code> trap are executed before +execution resumes after a shell function or a shell script executed with +<code>.</code> or <code>source</code> returns. +The <code>RETURN</code> trap is not inherited by shell functions unless the +function has been given the <code>trace</code> attribute or the +<code>functrace</code> option has been enabled using the <code>shopt</code> builtin. +</p> +</li><li> The Bash <code>type</code> builtin is more extensive and gives more information +about the names it finds (see <a href="#Bash-Builtins">Bash Builtin Commands</a>). + +</li><li> The Bash <code>umask</code> builtin permits a <samp>-p</samp> option to cause +the output to be displayed in the form of a <code>umask</code> command +that may be reused as input (see <a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a>). + +</li><li> Bash implements a <code>csh</code>-like directory stack, and provides the +<code>pushd</code>, <code>popd</code>, and <code>dirs</code> builtins to manipulate it +(see <a href="#The-Directory-Stack">The Directory Stack</a>). +Bash also makes the directory stack visible as the value of the +<code>DIRSTACK</code> shell variable. + +</li><li> Bash interprets special backslash-escaped characters in the prompt +strings when interactive (see <a href="#Controlling-the-Prompt">Controlling the Prompt</a>). + +</li><li> The Bash restricted mode is more useful (see <a href="#The-Restricted-Shell">The Restricted Shell</a>); +the SVR4.2 shell restricted mode is too limited. + +</li><li> The <code>disown</code> builtin can remove a job from the internal shell +job table (see <a href="#Job-Control-Builtins">Job Control Builtins</a>) or suppress the sending +of <code>SIGHUP</code> to a job when the shell exits as the result of a +<code>SIGHUP</code>. + +</li><li> Bash includes a number of features to support a separate debugger for +shell scripts. + +</li><li> The SVR4.2 shell has two privilege-related builtins +(<code>mldmode</code> and <code>priv</code>) not present in Bash. + +</li><li> Bash does not have the <code>stop</code> or <code>newgrp</code> builtins. + +</li><li> Bash does not use the <code>SHACCT</code> variable or perform shell accounting. + +</li><li> The SVR4.2 <code>sh</code> uses a <code>TIMEOUT</code> variable like Bash uses +<code>TMOUT</code>. + +</li></ul> + +<p>More features unique to Bash may be found in <a href="#Bash-Features">Bash Features</a>. +</p> + +<ul class="section-toc"> +<li><a href="#Implementation-Differences-From-The-SVR4_002e2-Shell" accesskey="1">Implementation Differences From The SVR4.2 Shell</a></li> +</ul> +<div class="appendixsec" id="Implementation-Differences-From-The-SVR4_002e2-Shell"> +<h3 class="appendixsec">B.1 Implementation Differences From The SVR4.2 Shell</h3> + +<p>Since Bash is a completely new implementation, it does not suffer from +many of the limitations of the SVR4.2 shell. For instance: +</p> +<ul> +<li> Bash does not fork a subshell when redirecting into or out of +a shell control structure such as an <code>if</code> or <code>while</code> +statement. + +</li><li> Bash does not allow unbalanced quotes. The SVR4.2 shell will silently +insert a needed closing quote at <code>EOF</code> under certain circumstances. +This can be the cause of some hard-to-find errors. + +</li><li> The SVR4.2 shell uses a baroque memory management scheme based on +trapping <code>SIGSEGV</code>. If the shell is started from a process with +<code>SIGSEGV</code> blocked (e.g., by using the <code>system()</code> C library +function call), it misbehaves badly. + +</li><li> In a questionable attempt at security, the SVR4.2 shell, +when invoked without the <samp>-p</samp> option, will alter its real +and effective <small>UID</small> and <small>GID</small> if they are less than some +magic threshold value, commonly 100. +This can lead to unexpected results. + +</li><li> The SVR4.2 shell does not allow users to trap <code>SIGSEGV</code>, +<code>SIGALRM</code>, or <code>SIGCHLD</code>. + +</li><li> The SVR4.2 shell does not allow the <code>IFS</code>, <code>MAILCHECK</code>, +<code>PATH</code>, <code>PS1</code>, or <code>PS2</code> variables to be unset. + +</li><li> The SVR4.2 shell treats ‘<samp>^</samp>’ as the undocumented equivalent of +‘<samp>|</samp>’. + +</li><li> Bash allows multiple option arguments when it is invoked (<code>-x -v</code>); +the SVR4.2 shell allows only one option argument (<code>-xv</code>). In +fact, some versions of the shell dump core if the second argument begins +with a ‘<samp>-</samp>’. + +</li><li> The SVR4.2 shell exits a script if any builtin fails; Bash exits +a script only if one of the <small>POSIX</small> special builtins fails, and +only for certain failures, as enumerated in the <small>POSIX</small> standard. + +</li><li> The SVR4.2 shell behaves differently when invoked as <code>jsh</code> +(it turns on job control). +</li></ul> + +<hr> +</div> +</div> +<div class="appendix" id="GNU-Free-Documentation-License"> +<div class="header"> +<p> +Next: <a href="#Indexes" accesskey="n" rel="next">Indexes</a>, Previous: <a href="#Major-Differences-From-The-Bourne-Shell" accesskey="p" rel="prev">Major Differences From The Bourne Shell</a>, Up: <a href="#Top" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="GNU-Free-Documentation-License-1"></span><h2 class="appendix">Appendix C GNU Free Documentation License</h2> + +<div align="center">Version 1.3, 3 November 2008 +</div> + +<div class="display"> +<pre class="display">Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. +<a href="http://fsf.org/">http://fsf.org/</a> + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +</pre></div> + +<ol start="0"> +<li> PREAMBLE + +<p>The purpose of this License is to make a manual, textbook, or other +functional and useful document <em>free</em> in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. +</p> +<p>This License is a kind of “copyleft”, which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. +</p> +<p>We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. +</p> +</li><li> APPLICABILITY AND DEFINITIONS + +<p>This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The “Document”, below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as “you”. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. +</p> +<p>A “Modified Version” of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. +</p> +<p>A “Secondary Section” is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document’s overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. +</p> +<p>The “Invariant Sections” are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. +</p> +<p>The “Cover Texts” are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. +</p> +<p>A “Transparent” copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not “Transparent” is called “Opaque”. +</p> +<p>Examples of suitable formats for Transparent copies include plain +<small>ASCII</small> without markup, Texinfo input format, LaTeX input +format, <acronym>SGML</acronym> or <acronym>XML</acronym> using a publicly available +<acronym>DTD</acronym>, and standard-conforming simple <acronym>HTML</acronym>, +PostScript or <acronym>PDF</acronym> designed for human modification. Examples +of transparent image formats include <acronym>PNG</acronym>, <acronym>XCF</acronym> and +<acronym>JPG</acronym>. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, <acronym>SGML</acronym> or +<acronym>XML</acronym> for which the <acronym>DTD</acronym> and/or processing tools are +not generally available, and the machine-generated <acronym>HTML</acronym>, +PostScript or <acronym>PDF</acronym> produced by some word processors for +output purposes only. +</p> +<p>The “Title Page” means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, “Title Page” means +the text near the most prominent appearance of the work’s title, +preceding the beginning of the body of the text. +</p> +<p>The “publisher” means any person or entity that distributes copies +of the Document to the public. +</p> +<p>A section “Entitled XYZ” means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as “Acknowledgements”, +“Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” +of such a section when you modify the Document means that it remains a +section “Entitled XYZ” according to this definition. +</p> +<p>The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. +</p> +</li><li> VERBATIM COPYING + +<p>You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. +</p> +<p>You may also lend copies, under the same conditions stated above, and +you may publicly display copies. +</p> +</li><li> COPYING IN QUANTITY + +<p>If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document’s license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. +</p> +<p>If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. +</p> +<p>If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. +</p> +<p>It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. +</p> +</li><li> MODIFICATIONS + +<p>You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: +</p> +<ol type="A" start="1"> +<li> Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +</li><li> List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +</li><li> State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +</li><li> Preserve all the copyright notices of the Document. + +</li><li> Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +</li><li> Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +</li><li> Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document’s license notice. + +</li><li> Include an unaltered copy of this License. + +</li><li> Preserve the section Entitled “History”, Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled “History” in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +</li><li> Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the “History” section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +</li><li> For any section Entitled “Acknowledgements” or “Dedications”, Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +</li><li> Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +</li><li> Delete any section Entitled “Endorsements”. Such a section +may not be included in the Modified Version. + +</li><li> Do not retitle any existing section to be Entitled “Endorsements” or +to conflict in title with any Invariant Section. + +</li><li> Preserve any Warranty Disclaimers. +</li></ol> + +<p>If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version’s license notice. +These titles must be distinct from any other section titles. +</p> +<p>You may add a section Entitled “Endorsements”, provided it contains +nothing but endorsements of your Modified Version by various +parties—for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. +</p> +<p>You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. +</p> +<p>The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. +</p> +</li><li> COMBINING DOCUMENTS + +<p>You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. +</p> +<p>The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. +</p> +<p>In the combination, you must combine any sections Entitled “History” +in the various original documents, forming one section Entitled +“History”; likewise combine any sections Entitled “Acknowledgements”, +and any sections Entitled “Dedications”. You must delete all +sections Entitled “Endorsements.” +</p> +</li><li> COLLECTIONS OF DOCUMENTS + +<p>You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. +</p> +<p>You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. +</p> +</li><li> AGGREGATION WITH INDEPENDENT WORKS + +<p>A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an “aggregate” if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation’s users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. +</p> +<p>If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document’s Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. +</p> +</li><li> TRANSLATION + +<p>Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. +</p> +<p>If a section in the Document is Entitled “Acknowledgements”, +“Dedications”, or “History”, the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. +</p> +</li><li> TERMINATION + +<p>You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. +</p> +<p>However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. +</p> +<p>Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. +</p> +<p>Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. +</p> +</li><li> FUTURE REVISIONS OF THIS LICENSE + +<p>The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +<a href="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</a>. +</p> +<p>Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License “or any later version” applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy’s public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. +</p> +</li><li> RELICENSING + +<p>“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +“Massive Multiauthor Collaboration” (or “MMC”) contained in the +site means any set of copyrightable works thus published on the MMC +site. +</p> +<p>“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. +</p> +<p>“Incorporate” means to publish or republish a Document, in whole or +in part, as part of another Document. +</p> +<p>An MMC is “eligible for relicensing” if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this MMC, and subsequently incorporated in whole +or in part into the MMC, (1) had no cover texts or invariant sections, +and (2) were thus incorporated prior to November 1, 2008. +</p> +<p>The operator of an MMC Site may republish an MMC contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the MMC is eligible for relicensing. +</p> +</li></ol> + +<span id="ADDENDUM_003a-How-to-use-this-License-for-your-documents"></span><h3 class="heading">ADDENDUM: How to use this License for your documents</h3> + +<p>To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: +</p> +<div class="example"> +<pre class="example"> Copyright (C) <var>year</var> <var>your name</var>. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +</pre></div> + +<p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the “with…Texts.” line with this: +</p> +<div class="example"> +<pre class="example"> with the Invariant Sections being <var>list their titles</var>, with + the Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts + being <var>list</var>. +</pre></div> + +<p>If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. +</p> +<p>If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. +</p> + + +<hr> +</div> +<div class="appendix" id="Indexes"> +<div class="header"> +<p> +Previous: <a href="#GNU-Free-Documentation-License" accesskey="p" rel="prev">GNU Free Documentation License</a>, Up: <a href="#Top" accesskey="u" rel="up">Bash Features</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Indexes-1"></span><h2 class="appendix">Appendix D Indexes</h2> + + +<ul class="section-toc"> +<li><a href="#Builtin-Index" accesskey="1">Index of Shell Builtin Commands</a></li> +<li><a href="#Reserved-Word-Index" accesskey="2">Index of Shell Reserved Words</a></li> +<li><a href="#Variable-Index" accesskey="3">Parameter and Variable Index</a></li> +<li><a href="#Function-Index" accesskey="4">Function Index</a></li> +<li><a href="#Concept-Index" accesskey="5">Concept Index</a></li> +</ul> +<hr> +<div class="appendixsec" id="Builtin-Index"> +<div class="header"> +<p> +Next: <a href="#Reserved-Word-Index" accesskey="n" rel="next">Index of Shell Reserved Words</a>, Up: <a href="#Indexes" accesskey="u" rel="up">Indexes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Index-of-Shell-Builtin-Commands"></span><h3 class="appendixsec">D.1 Index of Shell Builtin Commands</h3> +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Builtin-Index_bt_symbol-1"><b>.</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_symbol-2"><b>:</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_symbol-3"><b>[</b></a> + +<br> +<a class="summary-letter" href="#Builtin-Index_bt_letter-A"><b>A</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-B"><b>B</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-D"><b>D</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-E"><b>E</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-G"><b>G</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-H"><b>H</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-J"><b>J</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-K"><b>K</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-L"><b>L</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-M"><b>M</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-P"><b>P</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-R"><b>R</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-S"><b>S</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-T"><b>T</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-U"><b>U</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-W"><b>W</b></a> + +</td></tr></table> +<table class="index-bt" border="0"> +<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_symbol-1">.</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002e"><code>.</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_symbol-2">:</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_003a"><code>:</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_symbol-3">[</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_005b"><code>[</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_letter-A">A</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-alias"><code>alias</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_letter-B">B</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-bg"><code>bg</code></a>:</td><td> </td><td valign="top"><a href="#Job-Control-Builtins">Job Control Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-bind"><code>bind</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-break"><code>break</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-builtin"><code>builtin</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_letter-C">C</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-caller"><code>caller</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-cd"><code>cd</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-command"><code>command</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-compgen"><code>compgen</code></a>:</td><td> </td><td valign="top"><a href="#Programmable-Completion-Builtins">Programmable Completion Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-complete"><code>complete</code></a>:</td><td> </td><td valign="top"><a href="#Programmable-Completion-Builtins">Programmable Completion Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-compopt"><code>compopt</code></a>:</td><td> </td><td valign="top"><a href="#Programmable-Completion-Builtins">Programmable Completion Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-continue"><code>continue</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_letter-D">D</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-declare"><code>declare</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-dirs"><code>dirs</code></a>:</td><td> </td><td valign="top"><a href="#Directory-Stack-Builtins">Directory Stack Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-disown"><code>disown</code></a>:</td><td> </td><td valign="top"><a href="#Job-Control-Builtins">Job Control Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_letter-E">E</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-echo"><code>echo</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-enable"><code>enable</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-eval"><code>eval</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-exec"><code>exec</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-exit"><code>exit</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-export"><code>export</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_letter-F">F</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-fc"><code>fc</code></a>:</td><td> </td><td valign="top"><a href="#Bash-History-Builtins">Bash History Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-fg"><code>fg</code></a>:</td><td> </td><td valign="top"><a href="#Job-Control-Builtins">Job Control Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_letter-G">G</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-getopts"><code>getopts</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_letter-H">H</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-hash"><code>hash</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-help"><code>help</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-history"><code>history</code></a>:</td><td> </td><td valign="top"><a href="#Bash-History-Builtins">Bash History Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_letter-J">J</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-jobs"><code>jobs</code></a>:</td><td> </td><td valign="top"><a href="#Job-Control-Builtins">Job Control Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_letter-K">K</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-kill"><code>kill</code></a>:</td><td> </td><td valign="top"><a href="#Job-Control-Builtins">Job Control Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_letter-L">L</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-let"><code>let</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-local"><code>local</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-logout"><code>logout</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_letter-M">M</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-mapfile"><code>mapfile</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_letter-P">P</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-popd"><code>popd</code></a>:</td><td> </td><td valign="top"><a href="#Directory-Stack-Builtins">Directory Stack Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-printf"><code>printf</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-pushd"><code>pushd</code></a>:</td><td> </td><td valign="top"><a href="#Directory-Stack-Builtins">Directory Stack Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-pwd"><code>pwd</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_letter-R">R</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-read"><code>read</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-readarray"><code>readarray</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-readonly"><code>readonly</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-return"><code>return</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_letter-S">S</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-set"><code>set</code></a>:</td><td> </td><td valign="top"><a href="#The-Set-Builtin">The Set Builtin</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-shift"><code>shift</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-shopt"><code>shopt</code></a>:</td><td> </td><td valign="top"><a href="#The-Shopt-Builtin">The Shopt Builtin</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-source"><code>source</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-suspend"><code>suspend</code></a>:</td><td> </td><td valign="top"><a href="#Job-Control-Builtins">Job Control Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_letter-T">T</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-test"><code>test</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-times"><code>times</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-trap"><code>trap</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-type"><code>type</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-typeset"><code>typeset</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_letter-U">U</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-ulimit"><code>ulimit</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-umask"><code>umask</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-unalias"><code>unalias</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Builtins">Bash Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-unset"><code>unset</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Builtins">Bourne Shell Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Builtin-Index_bt_letter-W">W</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-wait"><code>wait</code></a>:</td><td> </td><td valign="top"><a href="#Job-Control-Builtins">Job Control Builtins</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +</table> +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Builtin-Index_bt_symbol-1"><b>.</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_symbol-2"><b>:</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_symbol-3"><b>[</b></a> + +<br> +<a class="summary-letter" href="#Builtin-Index_bt_letter-A"><b>A</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-B"><b>B</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-D"><b>D</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-E"><b>E</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-G"><b>G</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-H"><b>H</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-J"><b>J</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-K"><b>K</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-L"><b>L</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-M"><b>M</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-P"><b>P</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-R"><b>R</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-S"><b>S</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-T"><b>T</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-U"><b>U</b></a> + +<a class="summary-letter" href="#Builtin-Index_bt_letter-W"><b>W</b></a> + +</td></tr></table> + +<hr> +</div> +<div class="appendixsec" id="Reserved-Word-Index"> +<div class="header"> +<p> +Next: <a href="#Variable-Index" accesskey="n" rel="next">Parameter and Variable Index</a>, Previous: <a href="#Builtin-Index" accesskey="p" rel="prev">Index of Shell Builtin Commands</a>, Up: <a href="#Indexes" accesskey="u" rel="up">Indexes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Index-of-Shell-Reserved-Words"></span><h3 class="appendixsec">D.2 Index of Shell Reserved Words</h3> +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Reserved-Word-Index_rw_symbol-1"><b>!</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_symbol-2"><b>[</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_symbol-3"><b>]</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_symbol-4"><b>{</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_symbol-5"><b>}</b></a> + +<br> +<a class="summary-letter" href="#Reserved-Word-Index_rw_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_letter-D"><b>D</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_letter-E"><b>E</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_letter-I"><b>I</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_letter-S"><b>S</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_letter-T"><b>T</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_letter-U"><b>U</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_letter-W"><b>W</b></a> + +</td></tr></table> +<table class="index-rw" border="0"> +<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Reserved-Word-Index_rw_symbol-1">!</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_0021"><code>!</code></a>:</td><td> </td><td valign="top"><a href="#Pipelines">Pipelines</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Reserved-Word-Index_rw_symbol-2">[</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_005b_005b"><code>[[</code></a>:</td><td> </td><td valign="top"><a href="#Conditional-Constructs">Conditional Constructs</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Reserved-Word-Index_rw_symbol-3">]</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_005d_005d"><code>]]</code></a>:</td><td> </td><td valign="top"><a href="#Conditional-Constructs">Conditional Constructs</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Reserved-Word-Index_rw_symbol-4">{</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_007b"><code>{</code></a>:</td><td> </td><td valign="top"><a href="#Command-Grouping">Command Grouping</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Reserved-Word-Index_rw_symbol-5">}</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_007d"><code>}</code></a>:</td><td> </td><td valign="top"><a href="#Command-Grouping">Command Grouping</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Reserved-Word-Index_rw_letter-C">C</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-case"><code>case</code></a>:</td><td> </td><td valign="top"><a href="#Conditional-Constructs">Conditional Constructs</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Reserved-Word-Index_rw_letter-D">D</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-do"><code>do</code></a>:</td><td> </td><td valign="top"><a href="#Looping-Constructs">Looping Constructs</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-done"><code>done</code></a>:</td><td> </td><td valign="top"><a href="#Looping-Constructs">Looping Constructs</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Reserved-Word-Index_rw_letter-E">E</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-elif"><code>elif</code></a>:</td><td> </td><td valign="top"><a href="#Conditional-Constructs">Conditional Constructs</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-else"><code>else</code></a>:</td><td> </td><td valign="top"><a href="#Conditional-Constructs">Conditional Constructs</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-esac"><code>esac</code></a>:</td><td> </td><td valign="top"><a href="#Conditional-Constructs">Conditional Constructs</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Reserved-Word-Index_rw_letter-F">F</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-fi"><code>fi</code></a>:</td><td> </td><td valign="top"><a href="#Conditional-Constructs">Conditional Constructs</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-for"><code>for</code></a>:</td><td> </td><td valign="top"><a href="#Looping-Constructs">Looping Constructs</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-function"><code>function</code></a>:</td><td> </td><td valign="top"><a href="#Shell-Functions">Shell Functions</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Reserved-Word-Index_rw_letter-I">I</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-if"><code>if</code></a>:</td><td> </td><td valign="top"><a href="#Conditional-Constructs">Conditional Constructs</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-in"><code>in</code></a>:</td><td> </td><td valign="top"><a href="#Conditional-Constructs">Conditional Constructs</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Reserved-Word-Index_rw_letter-S">S</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-select"><code>select</code></a>:</td><td> </td><td valign="top"><a href="#Conditional-Constructs">Conditional Constructs</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Reserved-Word-Index_rw_letter-T">T</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-then"><code>then</code></a>:</td><td> </td><td valign="top"><a href="#Conditional-Constructs">Conditional Constructs</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-time"><code>time</code></a>:</td><td> </td><td valign="top"><a href="#Pipelines">Pipelines</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Reserved-Word-Index_rw_letter-U">U</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-until"><code>until</code></a>:</td><td> </td><td valign="top"><a href="#Looping-Constructs">Looping Constructs</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Reserved-Word-Index_rw_letter-W">W</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-while"><code>while</code></a>:</td><td> </td><td valign="top"><a href="#Looping-Constructs">Looping Constructs</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +</table> +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Reserved-Word-Index_rw_symbol-1"><b>!</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_symbol-2"><b>[</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_symbol-3"><b>]</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_symbol-4"><b>{</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_symbol-5"><b>}</b></a> + +<br> +<a class="summary-letter" href="#Reserved-Word-Index_rw_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_letter-D"><b>D</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_letter-E"><b>E</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_letter-I"><b>I</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_letter-S"><b>S</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_letter-T"><b>T</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_letter-U"><b>U</b></a> + +<a class="summary-letter" href="#Reserved-Word-Index_rw_letter-W"><b>W</b></a> + +</td></tr></table> + +<hr> +</div> +<div class="appendixsec" id="Variable-Index"> +<div class="header"> +<p> +Next: <a href="#Function-Index" accesskey="n" rel="next">Function Index</a>, Previous: <a href="#Reserved-Word-Index" accesskey="p" rel="prev">Index of Shell Reserved Words</a>, Up: <a href="#Indexes" accesskey="u" rel="up">Indexes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Parameter-and-Variable-Index"></span><h3 class="appendixsec">D.3 Parameter and Variable Index</h3> +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Variable-Index_vr_symbol-1"><b>!</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_symbol-2"><b>#</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_symbol-3"><b>$</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_symbol-4"><b>*</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_symbol-5"><b>-</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_symbol-6"><b>0</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_symbol-7"><b>?</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_symbol-8"><b>@</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_symbol-9"><b>_</b></a> + +<br> +<a class="summary-letter" href="#Variable-Index_vr_letter-A"><b>A</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-B"><b>B</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-D"><b>D</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-E"><b>E</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-G"><b>G</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-H"><b>H</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-I"><b>I</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-K"><b>K</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-L"><b>L</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-M"><b>M</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-O"><b>O</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-P"><b>P</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-R"><b>R</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-S"><b>S</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-T"><b>T</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-U"><b>U</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-V"><b>V</b></a> + +</td></tr></table> +<table class="index-vr" border="0"> +<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_symbol-1">!</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_0021-1"><code>!</code></a>:</td><td> </td><td valign="top"><a href="#Special-Parameters">Special Parameters</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_symbol-2">#</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_0023"><code>#</code></a>:</td><td> </td><td valign="top"><a href="#Special-Parameters">Special Parameters</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_symbol-3">$</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_0024"><code>$</code></a>:</td><td> </td><td valign="top"><a href="#Special-Parameters">Special Parameters</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_0024_0021"><code>$!</code></a>:</td><td> </td><td valign="top"><a href="#Special-Parameters">Special Parameters</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_0024_0023"><code>$#</code></a>:</td><td> </td><td valign="top"><a href="#Special-Parameters">Special Parameters</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_0024_0024"><code>$$</code></a>:</td><td> </td><td valign="top"><a href="#Special-Parameters">Special Parameters</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_0024_002a"><code>$*</code></a>:</td><td> </td><td valign="top"><a href="#Special-Parameters">Special Parameters</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_0024_002d"><code>$-</code></a>:</td><td> </td><td valign="top"><a href="#Special-Parameters">Special Parameters</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_00240"><code>$0</code></a>:</td><td> </td><td valign="top"><a href="#Special-Parameters">Special Parameters</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_0024_003f"><code>$?</code></a>:</td><td> </td><td valign="top"><a href="#Special-Parameters">Special Parameters</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_0024_0040"><code>$@</code></a>:</td><td> </td><td valign="top"><a href="#Special-Parameters">Special Parameters</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-_0024_005f"><code>$_</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_symbol-4">*</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002a"><code>*</code></a>:</td><td> </td><td valign="top"><a href="#Special-Parameters">Special Parameters</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_symbol-5">-</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_002d"><code>-</code></a>:</td><td> </td><td valign="top"><a href="#Special-Parameters">Special Parameters</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_symbol-6">0</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-0"><code>0</code></a>:</td><td> </td><td valign="top"><a href="#Special-Parameters">Special Parameters</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_symbol-7">?</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_003f"><code>?</code></a>:</td><td> </td><td valign="top"><a href="#Special-Parameters">Special Parameters</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_symbol-8">@</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_0040"><code>@</code></a>:</td><td> </td><td valign="top"><a href="#Special-Parameters">Special Parameters</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_symbol-9">_</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-_005f"><code>_</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_letter-A">A</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-active_002dregion_002dend_002dcolor"><code>active-region-end-color</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-active_002dregion_002dstart_002dcolor"><code>active-region-start-color</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-auto_005fresume"><code>auto_resume</code></a>:</td><td> </td><td valign="top"><a href="#Job-Control-Variables">Job Control Variables</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_letter-B">B</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASH"><code>BASH</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASHOPTS"><code>BASHOPTS</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASHPID"><code>BASHPID</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASH_005fALIASES"><code>BASH_ALIASES</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASH_005fARGC"><code>BASH_ARGC</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASH_005fARGV"><code>BASH_ARGV</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASH_005fARGV0"><code>BASH_ARGV0</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASH_005fCMDS"><code>BASH_CMDS</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASH_005fCOMMAND"><code>BASH_COMMAND</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASH_005fCOMPAT"><code>BASH_COMPAT</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASH_005fENV"><code>BASH_ENV</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASH_005fEXECUTION_005fSTRING"><code>BASH_EXECUTION_STRING</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASH_005fLINENO"><code>BASH_LINENO</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASH_005fLOADABLES_005fPATH"><code>BASH_LOADABLES_PATH</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASH_005fREMATCH"><code>BASH_REMATCH</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASH_005fSOURCE"><code>BASH_SOURCE</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASH_005fSUBSHELL"><code>BASH_SUBSHELL</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASH_005fVERSINFO"><code>BASH_VERSINFO</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASH_005fVERSION"><code>BASH_VERSION</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-BASH_005fXTRACEFD"><code>BASH_XTRACEFD</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-bell_002dstyle"><code>bell-style</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-bind_002dtty_002dspecial_002dchars"><code>bind-tty-special-chars</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-blink_002dmatching_002dparen"><code>blink-matching-paren</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_letter-C">C</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-CDPATH"><code>CDPATH</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Variables">Bourne Shell Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-CHILD_005fMAX"><code>CHILD_MAX</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-colored_002dcompletion_002dprefix"><code>colored-completion-prefix</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-colored_002dstats"><code>colored-stats</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-COLUMNS"><code>COLUMNS</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-comment_002dbegin"><code>comment-begin</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-completion_002ddisplay_002dwidth"><code>completion-display-width</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-completion_002dignore_002dcase"><code>completion-ignore-case</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-completion_002dmap_002dcase"><code>completion-map-case</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-completion_002dprefix_002ddisplay_002dlength"><code>completion-prefix-display-length</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-completion_002dquery_002ditems"><code>completion-query-items</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-COMPREPLY"><code>COMPREPLY</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-COMP_005fCWORD"><code>COMP_CWORD</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-COMP_005fKEY"><code>COMP_KEY</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-COMP_005fLINE"><code>COMP_LINE</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-COMP_005fPOINT"><code>COMP_POINT</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-COMP_005fTYPE"><code>COMP_TYPE</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-COMP_005fWORDBREAKS"><code>COMP_WORDBREAKS</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-COMP_005fWORDS"><code>COMP_WORDS</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-convert_002dmeta"><code>convert-meta</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-COPROC"><code>COPROC</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_letter-D">D</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-DIRSTACK"><code>DIRSTACK</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-disable_002dcompletion"><code>disable-completion</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_letter-E">E</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-echo_002dcontrol_002dcharacters"><code>echo-control-characters</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-editing_002dmode"><code>editing-mode</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-EMACS"><code>EMACS</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-emacs_002dmode_002dstring"><code>emacs-mode-string</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-enable_002dactive_002dregion"><code>enable-active-region</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-enable_002dbracketed_002dpaste"><code>enable-bracketed-paste</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-enable_002dkeypad"><code>enable-keypad</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-ENV"><code>ENV</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-EPOCHREALTIME"><code>EPOCHREALTIME</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-EPOCHSECONDS"><code>EPOCHSECONDS</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-EUID"><code>EUID</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-EXECIGNORE"><code>EXECIGNORE</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-expand_002dtilde"><code>expand-tilde</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_letter-F">F</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-FCEDIT"><code>FCEDIT</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-FIGNORE"><code>FIGNORE</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-FUNCNAME"><code>FUNCNAME</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-FUNCNEST"><code>FUNCNEST</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_letter-G">G</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-GLOBIGNORE"><code>GLOBIGNORE</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-GROUPS"><code>GROUPS</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_letter-H">H</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-histchars"><code>histchars</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-HISTCMD"><code>HISTCMD</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-HISTCONTROL"><code>HISTCONTROL</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-HISTFILE"><code>HISTFILE</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-HISTFILESIZE"><code>HISTFILESIZE</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-HISTIGNORE"><code>HISTIGNORE</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-history_002dpreserve_002dpoint"><code>history-preserve-point</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-history_002dsize"><code>history-size</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-HISTSIZE"><code>HISTSIZE</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-HISTTIMEFORMAT"><code>HISTTIMEFORMAT</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-HOME"><code>HOME</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Variables">Bourne Shell Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-horizontal_002dscroll_002dmode"><code>horizontal-scroll-mode</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-HOSTFILE"><code>HOSTFILE</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-HOSTNAME"><code>HOSTNAME</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-HOSTTYPE"><code>HOSTTYPE</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_letter-I">I</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-IFS"><code>IFS</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Variables">Bourne Shell Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-IGNOREEOF"><code>IGNOREEOF</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-input_002dmeta"><code>input-meta</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-INPUTRC"><code>INPUTRC</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-INSIDE_005fEMACS"><code>INSIDE_EMACS</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-isearch_002dterminators"><code>isearch-terminators</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_letter-K">K</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-keymap"><code>keymap</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_letter-L">L</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-LANG"><code>LANG</code></a>:</td><td> </td><td valign="top"><a href="#Creating-Internationalized-Scripts">Creating Internationalized Scripts</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LANG-1"><code>LANG</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LC_005fALL"><code>LC_ALL</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LC_005fCOLLATE"><code>LC_COLLATE</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LC_005fCTYPE"><code>LC_CTYPE</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LC_005fMESSAGES"><code>LC_MESSAGES</code></a>:</td><td> </td><td valign="top"><a href="#Creating-Internationalized-Scripts">Creating Internationalized Scripts</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LC_005fMESSAGES-1"><code>LC_MESSAGES</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LC_005fNUMERIC"><code>LC_NUMERIC</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LC_005fTIME"><code>LC_TIME</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LINENO"><code>LINENO</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-LINES"><code>LINES</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_letter-M">M</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-MACHTYPE"><code>MACHTYPE</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-MAIL"><code>MAIL</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Variables">Bourne Shell Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-MAILCHECK"><code>MAILCHECK</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-MAILPATH"><code>MAILPATH</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Variables">Bourne Shell Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-MAPFILE"><code>MAPFILE</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-mark_002dmodified_002dlines"><code>mark-modified-lines</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-mark_002dsymlinked_002ddirectories"><code>mark-symlinked-directories</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-match_002dhidden_002dfiles"><code>match-hidden-files</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-menu_002dcomplete_002ddisplay_002dprefix"><code>menu-complete-display-prefix</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-meta_002dflag"><code>meta-flag</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_letter-O">O</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-OLDPWD"><code>OLDPWD</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-OPTARG"><code>OPTARG</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Variables">Bourne Shell Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-OPTERR"><code>OPTERR</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-OPTIND"><code>OPTIND</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Variables">Bourne Shell Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-OSTYPE"><code>OSTYPE</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-output_002dmeta"><code>output-meta</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_letter-P">P</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-page_002dcompletions"><code>page-completions</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PATH"><code>PATH</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Variables">Bourne Shell Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PIPESTATUS"><code>PIPESTATUS</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-POSIXLY_005fCORRECT"><code>POSIXLY_CORRECT</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PPID"><code>PPID</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PROMPT_005fCOMMAND"><code>PROMPT_COMMAND</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PROMPT_005fDIRTRIM"><code>PROMPT_DIRTRIM</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PS0"><code>PS0</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PS1"><code>PS1</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Variables">Bourne Shell Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PS2"><code>PS2</code></a>:</td><td> </td><td valign="top"><a href="#Bourne-Shell-Variables">Bourne Shell Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PS3"><code>PS3</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PS4"><code>PS4</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-PWD"><code>PWD</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_letter-R">R</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-RANDOM"><code>RANDOM</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-READLINE_005fARGUMENT"><code>READLINE_ARGUMENT</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-READLINE_005fLINE"><code>READLINE_LINE</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-READLINE_005fMARK"><code>READLINE_MARK</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-READLINE_005fPOINT"><code>READLINE_POINT</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-REPLY"><code>REPLY</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-revert_002dall_002dat_002dnewline"><code>revert-all-at-newline</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_letter-S">S</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-SECONDS"><code>SECONDS</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SHELL"><code>SHELL</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SHELLOPTS"><code>SHELLOPTS</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SHLVL"><code>SHLVL</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-show_002dall_002dif_002dambiguous"><code>show-all-if-ambiguous</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-show_002dall_002dif_002dunmodified"><code>show-all-if-unmodified</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-show_002dmode_002din_002dprompt"><code>show-mode-in-prompt</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-skip_002dcompleted_002dtext"><code>skip-completed-text</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-SRANDOM"><code>SRANDOM</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_letter-T">T</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-TEXTDOMAIN"><code>TEXTDOMAIN</code></a>:</td><td> </td><td valign="top"><a href="#Creating-Internationalized-Scripts">Creating Internationalized Scripts</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-TEXTDOMAINDIR"><code>TEXTDOMAINDIR</code></a>:</td><td> </td><td valign="top"><a href="#Creating-Internationalized-Scripts">Creating Internationalized Scripts</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-TIMEFORMAT"><code>TIMEFORMAT</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-TMOUT"><code>TMOUT</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-TMPDIR"><code>TMPDIR</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_letter-U">U</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-UID"><code>UID</code></a>:</td><td> </td><td valign="top"><a href="#Bash-Variables">Bash Variables</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Variable-Index_vr_letter-V">V</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-vi_002dcmd_002dmode_002dstring"><code>vi-cmd-mode-string</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-vi_002dins_002dmode_002dstring"><code>vi-ins-mode-string</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-visible_002dstats"><code>visible-stats</code></a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +</table> +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Variable-Index_vr_symbol-1"><b>!</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_symbol-2"><b>#</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_symbol-3"><b>$</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_symbol-4"><b>*</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_symbol-5"><b>-</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_symbol-6"><b>0</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_symbol-7"><b>?</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_symbol-8"><b>@</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_symbol-9"><b>_</b></a> + +<br> +<a class="summary-letter" href="#Variable-Index_vr_letter-A"><b>A</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-B"><b>B</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-D"><b>D</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-E"><b>E</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-G"><b>G</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-H"><b>H</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-I"><b>I</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-K"><b>K</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-L"><b>L</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-M"><b>M</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-O"><b>O</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-P"><b>P</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-R"><b>R</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-S"><b>S</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-T"><b>T</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-U"><b>U</b></a> + +<a class="summary-letter" href="#Variable-Index_vr_letter-V"><b>V</b></a> + +</td></tr></table> + +<hr> +</div> +<div class="appendixsec" id="Function-Index"> +<div class="header"> +<p> +Next: <a href="#Concept-Index" accesskey="n" rel="next">Concept Index</a>, Previous: <a href="#Variable-Index" accesskey="p" rel="prev">Parameter and Variable Index</a>, Up: <a href="#Indexes" accesskey="u" rel="up">Indexes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Function-Index-1"></span><h3 class="appendixsec">D.4 Function Index</h3> +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Function-Index_fn_letter-A"><b>A</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-B"><b>B</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-D"><b>D</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-E"><b>E</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-G"><b>G</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-H"><b>H</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-I"><b>I</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-K"><b>K</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-M"><b>M</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-N"><b>N</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-O"><b>O</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-P"><b>P</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-Q"><b>Q</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-R"><b>R</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-S"><b>S</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-T"><b>T</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-U"><b>U</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-Y"><b>Y</b></a> + +</td></tr></table> +<table class="index-fn" border="0"> +<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Function-Index_fn_letter-A">A</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-abort-_0028C_002dg_0029"><code>abort (C-g)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-accept_002dline-_0028Newline-or-Return_0029"><code>accept-line (Newline or Return)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-History">Commands For History</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-alias_002dexpand_002dline-_0028_0029"><code>alias-expand-line ()</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Function-Index_fn_letter-B">B</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-backward_002dchar-_0028C_002db_0029"><code>backward-char (C-b)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Moving">Commands For Moving</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-backward_002ddelete_002dchar-_0028Rubout_0029"><code>backward-delete-char (Rubout)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Text">Commands For Text</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-backward_002dkill_002dline-_0028C_002dx-Rubout_0029"><code>backward-kill-line (C-x Rubout)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Killing">Commands For Killing</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-backward_002dkill_002dword-_0028M_002dDEL_0029"><code>backward-kill-word (M-<span class="key">DEL</span>)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Killing">Commands For Killing</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-backward_002dword-_0028M_002db_0029"><code>backward-word (M-b)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Moving">Commands For Moving</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-beginning_002dof_002dhistory-_0028M_002d_003c_0029"><code>beginning-of-history (M-<)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-History">Commands For History</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-beginning_002dof_002dline-_0028C_002da_0029"><code>beginning-of-line (C-a)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Moving">Commands For Moving</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-bracketed_002dpaste_002dbegin-_0028_0029"><code>bracketed-paste-begin ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Text">Commands For Text</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Function-Index_fn_letter-C">C</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-call_002dlast_002dkbd_002dmacro-_0028C_002dx-e_0029"><code>call-last-kbd-macro (C-x e)</code></a>:</td><td> </td><td valign="top"><a href="#Keyboard-Macros">Keyboard Macros</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-capitalize_002dword-_0028M_002dc_0029"><code>capitalize-word (M-c)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Text">Commands For Text</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-character_002dsearch-_0028C_002d_005d_0029"><code>character-search (C-])</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-character_002dsearch_002dbackward-_0028M_002dC_002d_005d_0029"><code>character-search-backward (M-C-])</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-clear_002ddisplay-_0028M_002dC_002dl_0029"><code>clear-display (M-C-l)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Moving">Commands For Moving</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-clear_002dscreen-_0028C_002dl_0029"><code>clear-screen (C-l)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Moving">Commands For Moving</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-complete-_0028TAB_0029"><code>complete (<span class="key">TAB</span>)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Completion">Commands For Completion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-complete_002dcommand-_0028M_002d_0021_0029"><code>complete-command (M-!)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Completion">Commands For Completion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-complete_002dfilename-_0028M_002d_002f_0029"><code>complete-filename (M-/)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Completion">Commands For Completion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-complete_002dhostname-_0028M_002d_0040_0029"><code>complete-hostname (M-@)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Completion">Commands For Completion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-complete_002dinto_002dbraces-_0028M_002d_007b_0029"><code>complete-into-braces (M-{)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Completion">Commands For Completion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-complete_002dusername-_0028M_002d_007e_0029"><code>complete-username (M-~)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Completion">Commands For Completion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-complete_002dvariable-_0028M_002d_0024_0029"><code>complete-variable (M-$)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Completion">Commands For Completion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-copy_002dbackward_002dword-_0028_0029"><code>copy-backward-word ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Killing">Commands For Killing</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-copy_002dforward_002dword-_0028_0029"><code>copy-forward-word ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Killing">Commands For Killing</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-copy_002dregion_002das_002dkill-_0028_0029"><code>copy-region-as-kill ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Killing">Commands For Killing</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Function-Index_fn_letter-D">D</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-dabbrev_002dexpand-_0028_0029"><code>dabbrev-expand ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Completion">Commands For Completion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-delete_002dchar-_0028C_002dd_0029"><code>delete-char (C-d)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Text">Commands For Text</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-delete_002dchar_002dor_002dlist-_0028_0029"><code>delete-char-or-list ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Completion">Commands For Completion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-delete_002dhorizontal_002dspace-_0028_0029"><code>delete-horizontal-space ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Killing">Commands For Killing</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-digit_002dargument-_0028M_002d0_002c-M_002d1_002c-_2026-M_002d_002d_0029"><code>digit-argument (<kbd>M-0</kbd>, <kbd>M-1</kbd>, … <kbd>M--</kbd>)</code></a>:</td><td> </td><td valign="top"><a href="#Numeric-Arguments">Numeric Arguments</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-display_002dshell_002dversion-_0028C_002dx-C_002dv_0029"><code>display-shell-version (C-x C-v)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-do_002dlowercase_002dversion-_0028M_002dA_002c-M_002dB_002c-M_002dx_002c-_2026_0029"><code>do-lowercase-version (M-A, M-B, M-<var>x</var>, …)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-downcase_002dword-_0028M_002dl_0029"><code>downcase-word (M-l)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Text">Commands For Text</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-dump_002dfunctions-_0028_0029"><code>dump-functions ()</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-dump_002dmacros-_0028_0029"><code>dump-macros ()</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-dump_002dvariables-_0028_0029"><code>dump-variables ()</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-dynamic_002dcomplete_002dhistory-_0028M_002dTAB_0029"><code>dynamic-complete-history (M-<span class="key">TAB</span>)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Completion">Commands For Completion</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Function-Index_fn_letter-E">E</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-edit_002dand_002dexecute_002dcommand-_0028C_002dx-C_002de_0029"><code>edit-and-execute-command (C-x C-e)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-end_002dkbd_002dmacro-_0028C_002dx-_0029_0029"><code>end-kbd-macro (C-x ))</code></a>:</td><td> </td><td valign="top"><a href="#Keyboard-Macros">Keyboard Macros</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-end_002dof_002dfile-_0028usually-C_002dd_0029"><code><i>end-of-file</i> (usually C-d)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Text">Commands For Text</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-end_002dof_002dhistory-_0028M_002d_003e_0029"><code>end-of-history (M->)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-History">Commands For History</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-end_002dof_002dline-_0028C_002de_0029"><code>end-of-line (C-e)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Moving">Commands For Moving</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-exchange_002dpoint_002dand_002dmark-_0028C_002dx-C_002dx_0029"><code>exchange-point-and-mark (C-x C-x)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Function-Index_fn_letter-F">F</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-fetch_002dhistory-_0028_0029"><code>fetch-history ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-History">Commands For History</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-forward_002dbackward_002ddelete_002dchar-_0028_0029"><code>forward-backward-delete-char ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Text">Commands For Text</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-forward_002dchar-_0028C_002df_0029"><code>forward-char (C-f)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Moving">Commands For Moving</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-forward_002dsearch_002dhistory-_0028C_002ds_0029"><code>forward-search-history (C-s)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-History">Commands For History</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-forward_002dword-_0028M_002df_0029"><code>forward-word (M-f)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Moving">Commands For Moving</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Function-Index_fn_letter-G">G</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-glob_002dcomplete_002dword-_0028M_002dg_0029"><code>glob-complete-word (M-g)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-glob_002dexpand_002dword-_0028C_002dx-_002a_0029"><code>glob-expand-word (C-x *)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-glob_002dlist_002dexpansions-_0028C_002dx-g_0029"><code>glob-list-expansions (C-x g)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Function-Index_fn_letter-H">H</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-history_002dand_002dalias_002dexpand_002dline-_0028_0029"><code>history-and-alias-expand-line ()</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-history_002dexpand_002dline-_0028M_002d_005e_0029"><code>history-expand-line (M-^)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-history_002dsearch_002dbackward-_0028_0029"><code>history-search-backward ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-History">Commands For History</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-history_002dsearch_002dforward-_0028_0029"><code>history-search-forward ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-History">Commands For History</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-history_002dsubstring_002dsearch_002dbackward-_0028_0029"><code>history-substring-search-backward ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-History">Commands For History</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-history_002dsubstring_002dsearch_002dforward-_0028_0029"><code>history-substring-search-forward ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-History">Commands For History</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Function-Index_fn_letter-I">I</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-insert_002dcomment-_0028M_002d_0023_0029"><code>insert-comment (M-#)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-insert_002dcompletions-_0028M_002d_002a_0029"><code>insert-completions (M-*)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Completion">Commands For Completion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-insert_002dlast_002dargument-_0028M_002d_002e-or-M_002d_005f_0029"><code>insert-last-argument (M-. or M-_)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Function-Index_fn_letter-K">K</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-kill_002dline-_0028C_002dk_0029"><code>kill-line (C-k)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Killing">Commands For Killing</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-kill_002dregion-_0028_0029"><code>kill-region ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Killing">Commands For Killing</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-kill_002dwhole_002dline-_0028_0029"><code>kill-whole-line ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Killing">Commands For Killing</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-kill_002dword-_0028M_002dd_0029"><code>kill-word (M-d)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Killing">Commands For Killing</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Function-Index_fn_letter-M">M</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-magic_002dspace-_0028_0029"><code>magic-space ()</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-menu_002dcomplete-_0028_0029"><code>menu-complete ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Completion">Commands For Completion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-menu_002dcomplete_002dbackward-_0028_0029"><code>menu-complete-backward ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Completion">Commands For Completion</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Function-Index_fn_letter-N">N</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-next_002dhistory-_0028C_002dn_0029"><code>next-history (C-n)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-History">Commands For History</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-next_002dscreen_002dline-_0028_0029"><code>next-screen-line ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Moving">Commands For Moving</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-non_002dincremental_002dforward_002dsearch_002dhistory-_0028M_002dn_0029"><code>non-incremental-forward-search-history (M-n)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-History">Commands For History</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-non_002dincremental_002dreverse_002dsearch_002dhistory-_0028M_002dp_0029"><code>non-incremental-reverse-search-history (M-p)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-History">Commands For History</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Function-Index_fn_letter-O">O</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-operate_002dand_002dget_002dnext-_0028C_002do_0029"><code>operate-and-get-next (C-o)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-History">Commands For History</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-overwrite_002dmode-_0028_0029"><code>overwrite-mode ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Text">Commands For Text</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Function-Index_fn_letter-P">P</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-possible_002dcommand_002dcompletions-_0028C_002dx-_0021_0029"><code>possible-command-completions (C-x !)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Completion">Commands For Completion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-possible_002dcompletions-_0028M_002d_003f_0029"><code>possible-completions (M-?)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Completion">Commands For Completion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-possible_002dfilename_002dcompletions-_0028C_002dx-_002f_0029"><code>possible-filename-completions (C-x /)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Completion">Commands For Completion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-possible_002dhostname_002dcompletions-_0028C_002dx-_0040_0029"><code>possible-hostname-completions (C-x @)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Completion">Commands For Completion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-possible_002dusername_002dcompletions-_0028C_002dx-_007e_0029"><code>possible-username-completions (C-x ~)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Completion">Commands For Completion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-possible_002dvariable_002dcompletions-_0028C_002dx-_0024_0029"><code>possible-variable-completions (C-x $)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Completion">Commands For Completion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-prefix_002dmeta-_0028ESC_0029"><code>prefix-meta (<span class="key">ESC</span>)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-previous_002dhistory-_0028C_002dp_0029"><code>previous-history (C-p)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-History">Commands For History</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-previous_002dscreen_002dline-_0028_0029"><code>previous-screen-line ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Moving">Commands For Moving</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-print_002dlast_002dkbd_002dmacro-_0028_0029"><code>print-last-kbd-macro ()</code></a>:</td><td> </td><td valign="top"><a href="#Keyboard-Macros">Keyboard Macros</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Function-Index_fn_letter-Q">Q</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-quoted_002dinsert-_0028C_002dq-or-C_002dv_0029"><code>quoted-insert (C-q or C-v)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Text">Commands For Text</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Function-Index_fn_letter-R">R</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-re_002dread_002dinit_002dfile-_0028C_002dx-C_002dr_0029"><code>re-read-init-file (C-x C-r)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-redraw_002dcurrent_002dline-_0028_0029"><code>redraw-current-line ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Moving">Commands For Moving</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-reverse_002dsearch_002dhistory-_0028C_002dr_0029"><code>reverse-search-history (C-r)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-History">Commands For History</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-revert_002dline-_0028M_002dr_0029"><code>revert-line (M-r)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Function-Index_fn_letter-S">S</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-self_002dinsert-_0028a_002c-b_002c-A_002c-1_002c-_0021_002c-_2026_0029"><code>self-insert (a, b, A, 1, !, …)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Text">Commands For Text</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-set_002dmark-_0028C_002d_0040_0029"><code>set-mark (C-@)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-shell_002dbackward_002dkill_002dword-_0028_0029"><code>shell-backward-kill-word ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Killing">Commands For Killing</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-shell_002dbackward_002dword-_0028M_002dC_002db_0029"><code>shell-backward-word (M-C-b)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Moving">Commands For Moving</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-shell_002dexpand_002dline-_0028M_002dC_002de_0029"><code>shell-expand-line (M-C-e)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-shell_002dforward_002dword-_0028M_002dC_002df_0029"><code>shell-forward-word (M-C-f)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Moving">Commands For Moving</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-shell_002dkill_002dword-_0028M_002dC_002dd_0029"><code>shell-kill-word (M-C-d)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Killing">Commands For Killing</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-shell_002dtranspose_002dwords-_0028M_002dC_002dt_0029"><code>shell-transpose-words (M-C-t)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Killing">Commands For Killing</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-skip_002dcsi_002dsequence-_0028_0029"><code>skip-csi-sequence ()</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-spell_002dcorrect_002dword-_0028C_002dx-s_0029"><code>spell-correct-word (C-x s)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-start_002dkbd_002dmacro-_0028C_002dx-_0028_0029"><code>start-kbd-macro (C-x ()</code></a>:</td><td> </td><td valign="top"><a href="#Keyboard-Macros">Keyboard Macros</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Function-Index_fn_letter-T">T</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-tilde_002dexpand-_0028M_002d_0026_0029"><code>tilde-expand (M-&)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-transpose_002dchars-_0028C_002dt_0029"><code>transpose-chars (C-t)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Text">Commands For Text</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-transpose_002dwords-_0028M_002dt_0029"><code>transpose-words (M-t)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Text">Commands For Text</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Function-Index_fn_letter-U">U</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-undo-_0028C_002d_005f-or-C_002dx-C_002du_0029"><code>undo (C-_ or C-x C-u)</code></a>:</td><td> </td><td valign="top"><a href="#Miscellaneous-Commands">Miscellaneous Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-universal_002dargument-_0028_0029"><code>universal-argument ()</code></a>:</td><td> </td><td valign="top"><a href="#Numeric-Arguments">Numeric Arguments</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-unix_002dfilename_002drubout-_0028_0029"><code>unix-filename-rubout ()</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Killing">Commands For Killing</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-unix_002dline_002ddiscard-_0028C_002du_0029"><code>unix-line-discard (C-u)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Killing">Commands For Killing</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-unix_002dword_002drubout-_0028C_002dw_0029"><code>unix-word-rubout (C-w)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Killing">Commands For Killing</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-upcase_002dword-_0028M_002du_0029"><code>upcase-word (M-u)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Text">Commands For Text</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Function-Index_fn_letter-Y">Y</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-yank-_0028C_002dy_0029"><code>yank (C-y)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Killing">Commands For Killing</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-yank_002dlast_002darg-_0028M_002d_002e-or-M_002d_005f_0029"><code>yank-last-arg (M-. or M-_)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-History">Commands For History</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-yank_002dnth_002darg-_0028M_002dC_002dy_0029"><code>yank-nth-arg (M-C-y)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-History">Commands For History</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-yank_002dpop-_0028M_002dy_0029"><code>yank-pop (M-y)</code></a>:</td><td> </td><td valign="top"><a href="#Commands-For-Killing">Commands For Killing</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +</table> +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Function-Index_fn_letter-A"><b>A</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-B"><b>B</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-D"><b>D</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-E"><b>E</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-G"><b>G</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-H"><b>H</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-I"><b>I</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-K"><b>K</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-M"><b>M</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-N"><b>N</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-O"><b>O</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-P"><b>P</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-Q"><b>Q</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-R"><b>R</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-S"><b>S</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-T"><b>T</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-U"><b>U</b></a> + +<a class="summary-letter" href="#Function-Index_fn_letter-Y"><b>Y</b></a> + +</td></tr></table> + +<hr> +</div> +<div class="appendixsec" id="Concept-Index"> +<div class="header"> +<p> +Previous: <a href="#Function-Index" accesskey="p" rel="prev">Function Index</a>, Up: <a href="#Indexes" accesskey="u" rel="up">Indexes</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Indexes" title="Index" rel="index">Index</a>]</p> +</div> +<span id="Concept-Index-1"></span><h3 class="appendixsec">D.5 Concept Index</h3> +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Concept-Index_cp_letter-A"><b>A</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-B"><b>B</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-D"><b>D</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-E"><b>E</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-H"><b>H</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-I"><b>I</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-J"><b>J</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-K"><b>K</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-L"><b>L</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-M"><b>M</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-N"><b>N</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-O"><b>O</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-P"><b>P</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-Q"><b>Q</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-R"><b>R</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-S"><b>S</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-T"><b>T</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-V"><b>V</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-W"><b>W</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-Y"><b>Y</b></a> + +</td></tr></table> +<table class="index-cp" border="0"> +<tr><td></td><th align="left">Index Entry</th><td> </td><th align="left"> Section</th></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-A">A</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-alias-expansion">alias expansion</a>:</td><td> </td><td valign="top"><a href="#Aliases">Aliases</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-arithmetic-evaluation">arithmetic evaluation</a>:</td><td> </td><td valign="top"><a href="#Shell-Arithmetic">Shell Arithmetic</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-arithmetic-expansion">arithmetic expansion</a>:</td><td> </td><td valign="top"><a href="#Arithmetic-Expansion">Arithmetic Expansion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-arithmetic_002c-shell">arithmetic, shell</a>:</td><td> </td><td valign="top"><a href="#Shell-Arithmetic">Shell Arithmetic</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-arrays">arrays</a>:</td><td> </td><td valign="top"><a href="#Arrays">Arrays</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-B">B</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-background">background</a>:</td><td> </td><td valign="top"><a href="#Job-Control-Basics">Job Control Basics</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-Bash-configuration">Bash configuration</a>:</td><td> </td><td valign="top"><a href="#Basic-Installation">Basic Installation</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-Bash-installation">Bash installation</a>:</td><td> </td><td valign="top"><a href="#Basic-Installation">Basic Installation</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-Bourne-shell">Bourne shell</a>:</td><td> </td><td valign="top"><a href="#Basic-Shell-Features">Basic Shell Features</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-brace-expansion">brace expansion</a>:</td><td> </td><td valign="top"><a href="#Brace-Expansion">Brace Expansion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-builtin-1">builtin</a>:</td><td> </td><td valign="top"><a href="#Definitions">Definitions</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-C">C</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-command-editing">command editing</a>:</td><td> </td><td valign="top"><a href="#Readline-Bare-Essentials">Readline Bare Essentials</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-command-execution">command execution</a>:</td><td> </td><td valign="top"><a href="#Command-Search-and-Execution">Command Search and Execution</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-command-expansion">command expansion</a>:</td><td> </td><td valign="top"><a href="#Simple-Command-Expansion">Simple Command Expansion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-command-history">command history</a>:</td><td> </td><td valign="top"><a href="#Bash-History-Facilities">Bash History Facilities</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-command-search">command search</a>:</td><td> </td><td valign="top"><a href="#Command-Search-and-Execution">Command Search and Execution</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-command-substitution">command substitution</a>:</td><td> </td><td valign="top"><a href="#Command-Substitution">Command Substitution</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-command-timing">command timing</a>:</td><td> </td><td valign="top"><a href="#Pipelines">Pipelines</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-commands_002c-compound">commands, compound</a>:</td><td> </td><td valign="top"><a href="#Compound-Commands">Compound Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-commands_002c-conditional">commands, conditional</a>:</td><td> </td><td valign="top"><a href="#Conditional-Constructs">Conditional Constructs</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-commands_002c-grouping">commands, grouping</a>:</td><td> </td><td valign="top"><a href="#Command-Grouping">Command Grouping</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-commands_002c-lists">commands, lists</a>:</td><td> </td><td valign="top"><a href="#Lists">Lists</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-commands_002c-looping">commands, looping</a>:</td><td> </td><td valign="top"><a href="#Looping-Constructs">Looping Constructs</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-commands_002c-pipelines">commands, pipelines</a>:</td><td> </td><td valign="top"><a href="#Pipelines">Pipelines</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-commands_002c-shell">commands, shell</a>:</td><td> </td><td valign="top"><a href="#Shell-Commands">Shell Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-commands_002c-simple">commands, simple</a>:</td><td> </td><td valign="top"><a href="#Simple-Commands">Simple Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-comments_002c-shell">comments, shell</a>:</td><td> </td><td valign="top"><a href="#Comments">Comments</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-Compatibility-Level">Compatibility Level</a>:</td><td> </td><td valign="top"><a href="#Shell-Compatibility-Mode">Shell Compatibility Mode</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-Compatibility-Mode">Compatibility Mode</a>:</td><td> </td><td valign="top"><a href="#Shell-Compatibility-Mode">Shell Compatibility Mode</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-completion-builtins">completion builtins</a>:</td><td> </td><td valign="top"><a href="#Programmable-Completion-Builtins">Programmable Completion Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-configuration">configuration</a>:</td><td> </td><td valign="top"><a href="#Basic-Installation">Basic Installation</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-control-operator">control operator</a>:</td><td> </td><td valign="top"><a href="#Definitions">Definitions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-coprocess">coprocess</a>:</td><td> </td><td valign="top"><a href="#Coprocesses">Coprocesses</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-D">D</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-directory-stack">directory stack</a>:</td><td> </td><td valign="top"><a href="#The-Directory-Stack">The Directory Stack</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-E">E</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-editing-command-lines">editing command lines</a>:</td><td> </td><td valign="top"><a href="#Readline-Bare-Essentials">Readline Bare Essentials</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-environment">environment</a>:</td><td> </td><td valign="top"><a href="#Environment">Environment</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-evaluation_002c-arithmetic">evaluation, arithmetic</a>:</td><td> </td><td valign="top"><a href="#Shell-Arithmetic">Shell Arithmetic</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-event-designators">event designators</a>:</td><td> </td><td valign="top"><a href="#Event-Designators">Event Designators</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-execution-environment">execution environment</a>:</td><td> </td><td valign="top"><a href="#Command-Execution-Environment">Command Execution Environment</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-exit-status">exit status</a>:</td><td> </td><td valign="top"><a href="#Definitions">Definitions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-exit-status-1">exit status</a>:</td><td> </td><td valign="top"><a href="#Exit-Status">Exit Status</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-expansion">expansion</a>:</td><td> </td><td valign="top"><a href="#Shell-Expansions">Shell Expansions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-expansion_002c-arithmetic">expansion, arithmetic</a>:</td><td> </td><td valign="top"><a href="#Arithmetic-Expansion">Arithmetic Expansion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-expansion_002c-brace">expansion, brace</a>:</td><td> </td><td valign="top"><a href="#Brace-Expansion">Brace Expansion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-expansion_002c-filename">expansion, filename</a>:</td><td> </td><td valign="top"><a href="#Filename-Expansion">Filename Expansion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-expansion_002c-parameter">expansion, parameter</a>:</td><td> </td><td valign="top"><a href="#Shell-Parameter-Expansion">Shell Parameter Expansion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-expansion_002c-pathname">expansion, pathname</a>:</td><td> </td><td valign="top"><a href="#Filename-Expansion">Filename Expansion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-expansion_002c-tilde">expansion, tilde</a>:</td><td> </td><td valign="top"><a href="#Tilde-Expansion">Tilde Expansion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-expressions_002c-arithmetic">expressions, arithmetic</a>:</td><td> </td><td valign="top"><a href="#Shell-Arithmetic">Shell Arithmetic</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-expressions_002c-conditional">expressions, conditional</a>:</td><td> </td><td valign="top"><a href="#Bash-Conditional-Expressions">Bash Conditional Expressions</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-F">F</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-field">field</a>:</td><td> </td><td valign="top"><a href="#Definitions">Definitions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-filename">filename</a>:</td><td> </td><td valign="top"><a href="#Definitions">Definitions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-filename-expansion">filename expansion</a>:</td><td> </td><td valign="top"><a href="#Filename-Expansion">Filename Expansion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-foreground">foreground</a>:</td><td> </td><td valign="top"><a href="#Job-Control-Basics">Job Control Basics</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-functions_002c-shell">functions, shell</a>:</td><td> </td><td valign="top"><a href="#Shell-Functions">Shell Functions</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-H">H</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-history-builtins">history builtins</a>:</td><td> </td><td valign="top"><a href="#Bash-History-Builtins">Bash History Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-history-events">history events</a>:</td><td> </td><td valign="top"><a href="#Event-Designators">Event Designators</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-history-expansion">history expansion</a>:</td><td> </td><td valign="top"><a href="#History-Interaction">History Interaction</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-history-list">history list</a>:</td><td> </td><td valign="top"><a href="#Bash-History-Facilities">Bash History Facilities</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-History_002c-how-to-use">History, how to use</a>:</td><td> </td><td valign="top"><a href="#A-Programmable-Completion-Example">A Programmable Completion Example</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-I">I</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-identifier">identifier</a>:</td><td> </td><td valign="top"><a href="#Definitions">Definitions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-initialization-file_002c-readline">initialization file, readline</a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File">Readline Init File</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-installation">installation</a>:</td><td> </td><td valign="top"><a href="#Basic-Installation">Basic Installation</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-interaction_002c-readline">interaction, readline</a>:</td><td> </td><td valign="top"><a href="#Readline-Interaction">Readline Interaction</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-interactive-shell">interactive shell</a>:</td><td> </td><td valign="top"><a href="#Invoking-Bash">Invoking Bash</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-interactive-shell-1">interactive shell</a>:</td><td> </td><td valign="top"><a href="#Interactive-Shells">Interactive Shells</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-internationalization">internationalization</a>:</td><td> </td><td valign="top"><a href="#Locale-Translation">Locale Translation</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-internationalized-scripts">internationalized scripts</a>:</td><td> </td><td valign="top"><a href="#Creating-Internationalized-Scripts">Creating Internationalized Scripts</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-J">J</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-job">job</a>:</td><td> </td><td valign="top"><a href="#Definitions">Definitions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-job-control">job control</a>:</td><td> </td><td valign="top"><a href="#Definitions">Definitions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-job-control-1">job control</a>:</td><td> </td><td valign="top"><a href="#Job-Control-Basics">Job Control Basics</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-K">K</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-kill-ring">kill ring</a>:</td><td> </td><td valign="top"><a href="#Readline-Killing-Commands">Readline Killing Commands</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-killing-text">killing text</a>:</td><td> </td><td valign="top"><a href="#Readline-Killing-Commands">Readline Killing Commands</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-L">L</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-localization">localization</a>:</td><td> </td><td valign="top"><a href="#Locale-Translation">Locale Translation</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-login-shell">login shell</a>:</td><td> </td><td valign="top"><a href="#Invoking-Bash">Invoking Bash</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-M">M</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-matching_002c-pattern">matching, pattern</a>:</td><td> </td><td valign="top"><a href="#Pattern-Matching">Pattern Matching</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-metacharacter">metacharacter</a>:</td><td> </td><td valign="top"><a href="#Definitions">Definitions</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-N">N</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-name">name</a>:</td><td> </td><td valign="top"><a href="#Definitions">Definitions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-native-languages">native languages</a>:</td><td> </td><td valign="top"><a href="#Locale-Translation">Locale Translation</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-notation_002c-readline">notation, readline</a>:</td><td> </td><td valign="top"><a href="#Readline-Bare-Essentials">Readline Bare Essentials</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-O">O</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-operator_002c-shell">operator, shell</a>:</td><td> </td><td valign="top"><a href="#Definitions">Definitions</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-P">P</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-parameter-expansion">parameter expansion</a>:</td><td> </td><td valign="top"><a href="#Shell-Parameter-Expansion">Shell Parameter Expansion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-parameters">parameters</a>:</td><td> </td><td valign="top"><a href="#Shell-Parameters">Shell Parameters</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-parameters_002c-positional">parameters, positional</a>:</td><td> </td><td valign="top"><a href="#Positional-Parameters">Positional Parameters</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-parameters_002c-special">parameters, special</a>:</td><td> </td><td valign="top"><a href="#Special-Parameters">Special Parameters</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-pathname-expansion">pathname expansion</a>:</td><td> </td><td valign="top"><a href="#Filename-Expansion">Filename Expansion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-pattern-matching">pattern matching</a>:</td><td> </td><td valign="top"><a href="#Pattern-Matching">Pattern Matching</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-pipeline">pipeline</a>:</td><td> </td><td valign="top"><a href="#Pipelines">Pipelines</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-POSIX">POSIX</a>:</td><td> </td><td valign="top"><a href="#Definitions">Definitions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-POSIX-Mode">POSIX Mode</a>:</td><td> </td><td valign="top"><a href="#Bash-POSIX-Mode">Bash POSIX Mode</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-process-group">process group</a>:</td><td> </td><td valign="top"><a href="#Definitions">Definitions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-process-group-ID">process group ID</a>:</td><td> </td><td valign="top"><a href="#Definitions">Definitions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-process-substitution">process substitution</a>:</td><td> </td><td valign="top"><a href="#Process-Substitution">Process Substitution</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-programmable-completion">programmable completion</a>:</td><td> </td><td valign="top"><a href="#Programmable-Completion">Programmable Completion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-prompting">prompting</a>:</td><td> </td><td valign="top"><a href="#Controlling-the-Prompt">Controlling the Prompt</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-Q">Q</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-quoting">quoting</a>:</td><td> </td><td valign="top"><a href="#Quoting">Quoting</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-quoting_002c-ANSI">quoting, ANSI</a>:</td><td> </td><td valign="top"><a href="#ANSI_002dC-Quoting">ANSI-C Quoting</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-R">R</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-Readline_002c-how-to-use">Readline, how to use</a>:</td><td> </td><td valign="top"><a href="#Job-Control-Variables">Job Control Variables</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-redirection">redirection</a>:</td><td> </td><td valign="top"><a href="#Redirections">Redirections</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-reserved-word">reserved word</a>:</td><td> </td><td valign="top"><a href="#Definitions">Definitions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-reserved-words">reserved words</a>:</td><td> </td><td valign="top"><a href="#Reserved-Words">Reserved Words</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-restricted-shell">restricted shell</a>:</td><td> </td><td valign="top"><a href="#The-Restricted-Shell">The Restricted Shell</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-return-status">return status</a>:</td><td> </td><td valign="top"><a href="#Definitions">Definitions</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-S">S</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-shell-arithmetic">shell arithmetic</a>:</td><td> </td><td valign="top"><a href="#Shell-Arithmetic">Shell Arithmetic</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-shell-function">shell function</a>:</td><td> </td><td valign="top"><a href="#Shell-Functions">Shell Functions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-shell-script">shell script</a>:</td><td> </td><td valign="top"><a href="#Shell-Scripts">Shell Scripts</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-shell-variable">shell variable</a>:</td><td> </td><td valign="top"><a href="#Shell-Parameters">Shell Parameters</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-shell_002c-interactive">shell, interactive</a>:</td><td> </td><td valign="top"><a href="#Interactive-Shells">Interactive Shells</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-signal">signal</a>:</td><td> </td><td valign="top"><a href="#Definitions">Definitions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-signal-handling">signal handling</a>:</td><td> </td><td valign="top"><a href="#Signals">Signals</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-special-builtin">special builtin</a>:</td><td> </td><td valign="top"><a href="#Definitions">Definitions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-special-builtin-1">special builtin</a>:</td><td> </td><td valign="top"><a href="#Special-Builtins">Special Builtins</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-startup-files">startup files</a>:</td><td> </td><td valign="top"><a href="#Bash-Startup-Files">Bash Startup Files</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-string-translations">string translations</a>:</td><td> </td><td valign="top"><a href="#Creating-Internationalized-Scripts">Creating Internationalized Scripts</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-suspending-jobs">suspending jobs</a>:</td><td> </td><td valign="top"><a href="#Job-Control-Basics">Job Control Basics</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-T">T</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-tilde-expansion">tilde expansion</a>:</td><td> </td><td valign="top"><a href="#Tilde-Expansion">Tilde Expansion</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-token">token</a>:</td><td> </td><td valign="top"><a href="#Definitions">Definitions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-translation_002c-native-languages">translation, native languages</a>:</td><td> </td><td valign="top"><a href="#Locale-Translation">Locale Translation</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-V">V</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-variable_002c-shell">variable, shell</a>:</td><td> </td><td valign="top"><a href="#Shell-Parameters">Shell Parameters</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-variables_002c-readline">variables, readline</a>:</td><td> </td><td valign="top"><a href="#Readline-Init-File-Syntax">Readline Init File Syntax</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-W">W</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-word">word</a>:</td><td> </td><td valign="top"><a href="#Definitions">Definitions</a></td></tr> +<tr><td></td><td valign="top"><a href="#index-word-splitting">word splitting</a>:</td><td> </td><td valign="top"><a href="#Word-Splitting">Word Splitting</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +<tr><th id="Concept-Index_cp_letter-Y">Y</th><td></td><td></td></tr> +<tr><td></td><td valign="top"><a href="#index-yanking-text">yanking text</a>:</td><td> </td><td valign="top"><a href="#Readline-Killing-Commands">Readline Killing Commands</a></td></tr> +<tr><td colspan="4"> <hr></td></tr> +</table> +<table><tr><th valign="top">Jump to: </th><td><a class="summary-letter" href="#Concept-Index_cp_letter-A"><b>A</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-B"><b>B</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-C"><b>C</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-D"><b>D</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-E"><b>E</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-F"><b>F</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-H"><b>H</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-I"><b>I</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-J"><b>J</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-K"><b>K</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-L"><b>L</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-M"><b>M</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-N"><b>N</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-O"><b>O</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-P"><b>P</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-Q"><b>Q</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-R"><b>R</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-S"><b>S</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-T"><b>T</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-V"><b>V</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-W"><b>W</b></a> + +<a class="summary-letter" href="#Concept-Index_cp_letter-Y"><b>Y</b></a> + +</td></tr></table> + +</div> +</div> +</div> + + + +</body> +</html> |