/proc/self/root/proc/thread-self/root/usr/share/doc/bash
This explorer reads the filesystem of the server it runs on, so /workspace/user isn't present here. Browsing and the terminal still work against this server's own disk from /.
<!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 inthe 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 documentunder the terms of the GNU Free Documentation License, Version 1.3 orany later version published by the Free Software Foundation; with noInvariant 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 inthe 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 somefeatures that only appear in Bash. Some of the shells that Bash hasborrowed 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 intocategories, noting which features were inspired by other shells andwhich are specific to Bash.</p><p>This manual is meant as a brief introduction to features found inBash. The Bash manual page should be used as the definitivereference 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 ofthe current Unix shell <code>sh</code>, which appeared in the Seventh Edition Bell Labs Research versionof Unix.</p><p>Bash is largely compatible with <code>sh</code> and incorporates usefulfeatures 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 andprogramming use.</p><p>While the <small>GNU</small> operating system provides other shells, includinga version of <code>csh</code>, Bash is the default shell.Like other <small>GNU</small> software, Bash is quite portable. It currently runson 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 executescommands. The term macro processor means functionality where textand symbols are expanded to create larger expressions.</p><p>A Unix shell is both a command interpreter and a programminglanguage. As a command interpreter, the shell provides the userinterface to the rich set of <small>GNU</small> utilities. The programminglanguage features allow these utilities to be combined.Files containing commands can be created, and becomecommands themselves. These new commands have the same status assystem commands in directories such as <samp>/bin</samp>, allowing usersor groups to establish custom environments to automate their commontasks.</p><p>Shells may be used interactively or non-interactively. Ininteractive mode, they accept input typed from the keyboard.When executing non-interactively, shells execute commands readfrom a file.</p><p>A shell allows execution of <small>GNU</small> commands, both synchronously andasynchronously.The shell waits for synchronous commands to complete before acceptingmore input; asynchronous commands continue to execute in parallelwith the shell while it reads and executes additional commands.The <em>redirection</em> constructs permitfine-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-incommands (<em>builtins</em>) implementing functionality impossibleor 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 becausethey 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 insubsequent sections.</p><p>While executing commands is essential, most of the power (andcomplexity) of shells is due to their embedded programminglanguages. Like any high-level language, the shell providesvariables, flow control constructs, quoting, and functions. </p><p>Shells offer features geared specifically forinteractive use rather than to augment the programming language. These interactive features include job control, command lineediting, command history and aliases. Each of these features isdescribed 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. Bashis 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, ratherthan 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 restrictedto 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. Afterexpansion, when executing a command, the resulting fields are used asthe 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 descendedfrom 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 isa <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 asshell 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 processgroup <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 reservedwords 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 kernelof 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 isthe 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 fromand 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 asequence of operations. If the input indicates the beginning of acomment, the shell ignores the comment symbol (‘<samp>#</samp>’), and the restof that line.</p> <p>Otherwise, roughly speaking, the shell reads its input anddivides the input into words and operators, employing the quoting rulesto 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, expandsothers, redirects input and output as needed, executes the specifiedcommand, waits for the command’s exit status, and makes that exit statusavailable 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 itreads and executes a command. Basically, the shell does thefollowing:</p><ol><li> Reads its input from a file (see <a href="#Shell-Scripts">Shell Scripts</a>), from a stringsupplied 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 rulesdescribed 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>), breakingthe 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 removesthe 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 exitstatus (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 certaincharacters or words to the shell. Quoting can be used todisable special treatment for special characters, to preventreserved words from being recognized as such, and to preventparameter 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 torepresent 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 quotedto prevent history expansion. See <a href="#Bash-History-Facilities">Bash History Facilities</a>, formore 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> pairappears, and the backslash itself is not quoted, the <code>\newline</code>is treated as a line continuation (that is, it is removed fromthe 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 valueof each character within the quotes. A single quote may not occurbetween 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 valueof 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 meaningwithin 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 ofthe following characters:‘<samp>$</samp>’, ‘<samp>`</samp>’, ‘<samp>"</samp>’, ‘<samp>\</samp>’, or <code>newline</code>.Within double quotes, backslashes that are followed by one of thesecharacters are removed. Backslashes preceding characters without aspecial meaning are left unmodified.A double quote may be quoted within double quotes by preceding it witha 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 meaningwhen 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 specialkind of single quotes.The sequence expands to <var>string</var>, with backslash-escaped charactersin <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 notbeen 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>’), suchas <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-quotedby default, whether or not it is translated and replaced.If the <code>noexpand_translation</code> option is enabledusing 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 tocreate 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 scriptthat 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 gettextneeds, like a package or script name.It needs to be unique among allthe message domains on systems where you install the translations, sogettext 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 languageyou want to support (called "PO" files, which use the suffix ‘<samp>.po</samp>’).PO files use various naming conventions, butwhen you are working to translate a template file into a particularlanguage, you first copy the template file to a file whose name is thelanguage you want to target, with the ‘<samp>.po</samp>’ suffix.For instance, the Spanish translations of your strings would bein a file named ‘<samp>es.po</samp>’, and to get started using a messagedomain 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 indirectories that contain multiple translation files for a particular language.</p><p>Whichever naming convention you choose, you will need to translate thestrings 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 thegettext tools to produce what are called "MO" files, which are compiledversions of the PO files the gettext tools use to look up translationsefficiently.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 toselect 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 thename of a directory where the message catalog files are stored.If you install the message files into the system’s standard message catalogdirectory, you don’t need to worry about this variable.</p><p>The directory where the message catalog files are stored varies betweensystems.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 messagecatalog files with Spanish (es) and Esperanto (eo) translations into alocal directory you use for custom translation files, you could run</p><div class="example"><pre class="example">TEXTDOMAIN=exampleTEXTDOMAINDIR=/usr/local/share/locale cp es.mo ${TEXTDOMAINDIR}/es/LC_MESSAGES/${TEXTDOMAIN}.mocp eo.mo ${TEXTDOMAINDIR}/eo/LC_MESSAGES/${TEXTDOMAIN}.mo</pre></div> <p>When all of this is done, and the message catalog files containing thecompiled translations are installed in the correct location,your users will be able to see translated stringsin 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 tobe 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 makesa 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 commanditself followed by arguments, separated by spaces.</p><p>More complex shell commands are composed of simple commands arranged togetherin a variety of ways: in a pipeline in which the output of one commandbecomes the input of a second, in a loop or conditional construct, or insome 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 reservedwords 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, terminatedby one of the shell’s control operators (see <a href="#Definitions">Definitions</a>). Thefirst word generally specifies a command to be executed, with therest 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 isits exit status as providedby the <small>POSIX</small> 1003.1 <code>waitpid</code> function, or 128+<var>n</var> ifthe 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 byone 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 pipeto the input of the next command.That is, each command reads the previous command’s output. Thisconnection 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 toits 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 isperformed after any redirections specified by <var>command1</var>.</p><p>The reserved word <code>time</code> causes timing statisticsto be printed for the pipeline once it finishes.The statistics currently consist of elapsed (wall-clock) time anduser and system time consumed by the command’s execution.The <samp>-p</samp> option changes the output format to that specifiedby <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 nexttoken begins with a ‘<samp>-</samp>’.The <code>TIMEFORMAT</code> variable may be set to a format string thatspecifies 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 ofshell 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 thetotal user and system time consumed by the shell and its children.The <code>TIMEFORMAT</code> variable may be used to specify the format ofthe time information.</p><p>If the pipeline is not executed asynchronously (see <a href="#Lists">Lists of Commands</a>), theshell 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 aseparate 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 processwhen job control is not active.</p><p>The exitstatus of a pipeline is the exit status of the last command in thepipeline, 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 thevalue 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, theexit status is the logical negation of the exit status as describedabove.The shell waits for all commands in the pipeline to terminate beforereturning 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 oneof 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 returnstatus 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 anyexplicit redirections, is redirected from <code>/dev/null</code>.</p><p>Commands separated by a ‘<samp>;</samp>’ are executed sequentially; the shellwaits for each command to terminate in turn. The return status is theexit status of the last command executed.</p><p><small>AND</small> and <small>OR</small> lists are sequences of one or more pipelinesseparated by the control operators ‘<samp>&&</samp>’ and ‘<samp>||</samp>’,respectively. <small>AND</small> and <small>OR</small> lists are executed with leftassociativity.</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 commandexecuted 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 isterminated by a corresponding reserved word or operator.Any redirections (see <a href="#Redirections">Redirections</a>) associated with a compound commandapply 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 beseparated from the rest of the command by one or more newlines, and may befollowed by a newline in place of a semicolon.</p><p>Bash provides looping constructs, conditional commands, and mechanismsto 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 acommand’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 executedin <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 executedin <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 memberin 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> commandexecutes the <var>commands</var> once for each positional parameter that isset, 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 areexecuted, 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 accordingto the rules described below (see <a href="#Shell-Arithmetic">Shell Arithmetic</a>).The arithmetic expression <var>expr2</var> is then evaluated repeatedlyuntil it evaluates to zero. Each time <var>expr2</var> evaluates to a non-zero value, <var>commands</var> areexecuted 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> listis 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, andthe final command in the final <code>if</code> or <code>elif</code> clausehas a non-zero exit status, then <var>alternate-consequents</var> is executed.The return status is the exit status of the last command executed, orzero 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 tothe first <var>pattern</var> that matches <var>word</var>.The match is performed accordingto 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 caseof 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 knownas 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, commandsubstitution, 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, andquote removal.</p><p>There may be an arbitrary number of <code>case</code> clauses, each terminatedby a ‘<samp>;;</samp>’, ‘<samp>;&</samp>’, or ‘<samp>;;&</samp>’.The first pattern that matches determines thecommand-list that is executed.It’s a common idiom to use ‘<samp>*</samp>’ as the final pattern to define thedefault case, since that pattern will always match.</p><p>Here is an example using <code>case</code> in a script that could be used todescribe one interesting feature of an animal:</p><div class="example"><pre class="example">echo -n "Enter the name of an animal: "read ANIMALecho -n "The $ANIMAL has "case $ANIMAL in horse | dog | cat) echo -n "four";; man | kangaroo ) echo -n "two";; *) echo -n "an unknown number of";;esacecho " legs."</pre></div> <p>If the ‘<samp>;;</samp>’ operator is used, no subsequent matches are attempted afterthe first pattern match.Using ‘<samp>;&</samp>’ in place of ‘<samp>;;</samp>’ causes execution to continue withthe <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 patternsin 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, thereturn 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 listof items, and the set of expanded words is printed on the standarderror 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 displayedwords, 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 whichpoint the <code>select</code> command completes.</p><p>Here is an example that allows the user to pick a filename from thecurrent directory, and displays the name and index of the fileselected.</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 rulesdescribed below (see <a href="#Shell-Arithmetic">Shell Arithmetic</a>).The <var>expression</var> undergoes the same expansionsas if it were within double quotes,but double quote characters in <var>expression</var> are not treated speciallyare 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 ofthe 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 splittingand filename expansion.The shell performs tilde expansion, parameter andvariable expansion, arithmetic expansion, command substitution, processsubstitution, 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 recognizedas primaries.</p><p>When used with <code>[[</code>, the ‘<samp><</samp>’ and ‘<samp>></samp>’ operators sortlexicographically using the current locale.</p><p>When the ‘<samp>==</samp>’ and ‘<samp>!=</samp>’ operators are used, the string to theright of the operator is considered a pattern and matched accordingto 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 caseof alphabetic characters.The return value is 0 if the string matches (‘<samp>==</samp>’) or does notmatch (‘<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 sameprecedence as ‘<samp>==</samp>’ and ‘<samp>!=</samp>’.When you use ‘<samp>=~</samp>’, the string to the right of the operator is considereda <small>POSIX</small> extended regular expression pattern and matched accordingly(using the <small>POSIX</small> <code>regcomp</code> and <code>regexec</code> interfacesusually 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 conditionalexpression 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 caseof alphabetic characters.</p><p>You can quote any part of the patternto force the quoted portion to be matched literallyinstead of as a regular expression (see above).If the pattern is stored in a shell variable, quoting the variableexpansion 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 expressionoperators.</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 ofany 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 expressiongrammar (‘<samp>^$|[]()\.*+?</samp>’), it has to be quoted to remove its specialmeaning.This means that in the pattern ‘<samp>xxx.txt</samp>’, the ‘<samp>.</samp>’ matches anycharacter in the string (its usual regular expression meaning), but in thepattern ‘<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 aspecial meaning to the regular expression grammar, you must make sure it’snot 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 itsusual special meaning.</p><p>It is sometimes difficult to specify a regular expression properlywithout using quotes, or to keep track of the quoting used by regularexpressions while paying attention toshell quoting and the shell’s quote removal.Storing the regular expression in a shell variable is often a usefulway to avoid problems with quoting characters that are special to theshell.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, sincebackslashes are used by both the shell and regular expressions to removethe 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 patternthat were originally not quoted can remove thespecial meaning of pattern characters.If any part of the pattern is quoted, the shell does its best to ensure thatthe 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, becausein 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 expressionparser 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 expressionparser has the backslash quoted (e.g., ‘<samp>\\\.</samp>’), which will not matchthe 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 thepattern 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 expressionslose their special meanings between brackets.However, you can use bracket expressions to match special pattern characterswithout 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 patternwill 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 patternto the regular expression functions,so you can assume that the shell’s quoting takes precedence.As noted above, the regular expression parser will interpret anyunquoted backslashes remaining in the pattern after shell expansionaccording to its own rules.The intention is to avoid making shell programmers quote things twiceas much as possible, so shell quoting should be sufficient to quotespecial pattern characters where that’s necessary.</p><p>The array variable <code>BASH_REMATCH</code> records which parts of the stringmatched the pattern.The element of <code>BASH_REMATCH</code> with index 0 contains the portion ofthe string matching the entire regular expression.Substrings matched by parenthesized subexpressions within the regularexpression 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 thestring 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 tounexpected results.</p><p>Expressions may be combined using the following operators, listedin 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 thevalue of <var>expression1</var> is sufficient to determine the returnvalue 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 executedas a unit. When commands are grouped, redirections may be appliedto the entire command list. For example, the output of all thecommands 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 createa subshell (see <a href="#Command-Execution-Environment">Command Execution Environment</a>), and eachof 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 notremain 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 tobe 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 differencebetween these two constructs due to historical reasons. The bracesare 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 arerecognized as separate tokens by the shell even if they are not separatedfrom 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 commandhad been terminated with the ‘<samp>&</samp>’ control operator, with a two-way pipeestablished 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 coprocessalways being named <code>COPROC</code>, and it is simpler to use and more completethan 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. Theword following <code>coproc</code> determines whether that word is interpretedas a variable name: it is interpreted as <var>NAME</var> if it is not areserved word that introduces a compound command.If <var>command</var> is a simple command, <var>NAME</var> is not allowed; thisis to avoid confusion between <var>NAME</var> and the first word of the simplecommand.</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 thecommand (see <a href="#Redirections">Redirections</a>).The file descriptors can be utilized as arguments to shell commandsand 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 isavailable 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 commandsin parallel. You may run the same command with different arguments, whetherthey are filenames, usernames, hostnames, or lines read from files. GNUParallel provides shorthand references to many of the most common operations(input lines, various portions of the input line, different ways to specifythe input source, and so on). Parallel can replace <code>xargs</code> or feedcommands from its input sources to several different instances of Bash.</p><p>For a complete description, refer to the GNU Parallel documentation, whichis 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 executionusing a single name for the group. They are executed just likea "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 currentshell 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 reservedword <code>function</code> is optional.If the <code>function</code> reservedword 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 }, butmay be any compound command listed above.If the <code>function</code> reserved word is used, but theparentheses are not supplied, the braces are recommended.<var>compound-command</var> is executed whenever <var>fname</var> is specified as thename 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 andmay 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 doesnot contain ‘<samp>$</samp>’.Any redirections (see <a href="#Redirections">Redirections</a>) associated with the shell functionare 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 erroroccurs or a readonly function with the same name already exists.When executed, the exit status of a function is the exit status of thelast command executed in the body.</p><p>Note that for historical reasons, in the most common usage the curly bracesthat 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 recognizedas such when they are separated from the command listby 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 thefunction become the positional parametersduring its execution (see <a href="#Positional-Parameters">Positional Parameters</a>).The special parameter ‘<samp>#</samp>’ that expands to the number ofpositional 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 thename of the function while the function is executing.</p><p>All other aspects of the shell executionenvironment are identical between a function and its callerwith these exceptions:the <code>DEBUG</code> and <code>RETURN</code> trapsare not inherited unless the function has been given the<code>trace</code> attribute using the <code>declare</code> builtin orthe <code>-o functrace</code> option has been enabled withthe <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 greaterthan 0, defines a maximum function nesting level. Functioninvocations that exceed the limit cause the entire command toabort.</p><p>If the builtin command <code>return</code>is executed in a function, the function completes andexecution resumes with the next command after the functioncall.Any command associated with the <code>RETURN</code> trap is executedbefore execution resumes.When a function completes, the values of thepositional parameters and the special parameter ‘<samp>#</samp>’are restored to the values they had prior to the function’sexecution. If a numeric argument is given to <code>return</code>,that is the function’s return status; otherwise the function’sreturn status is the exit status of the last command executedbefore 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 valuesare shared between a function and its caller.These variables are visible only tothe function and the commands it invokes. This is particularlyimportant 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 executingany shell function.Consequently, a local variable at the current local scope is a variabledeclared using the <code>local</code> or <code>declare</code> builtins in thefunction that is currently executing.</p><p>Local variables "shadow" variables with the same name declared atprevious scopes. For instance, a local variable declared in a functionhides a global variable of the same name: references and assignmentsrefer 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 visibilitywithin functions.With dynamic scoping, visible variables and their valuesare a result of the sequence of function calls that caused executionto reach the current function.The value of a variable that a function sees dependson its value within its caller, if any, whether that caller isthe "global" scope or another shell function.This is also the value that a local variabledeclaration "shadows", and the value that is restored when the functionreturns.</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 thelocal variable <code>var</code> from <code>func1</code>, shadowing any global variablenamed <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=globalfunc1</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 previousscope 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 thefunction 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 characterslisted 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 isa valid value. Once a variable is set, it may be unset only by usingthe <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 quoteremoval (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 appearin a command after one or more instances of the <code>command</code> builtinand 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> thataccept assignment statements (declaration commands).When ‘<samp>+=</samp>’ is applied to a variable for which the <code>integer</code> attributehas been set, <var>value</var> is evaluated as an arithmetic expression andadded 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>), thevariable’s value is not unset (as it is when using ‘<samp>=</samp>’), and newvalues are appended to the array beginning at one greater than the array’smaximum index (for indexed arrays), or added as additional key-value pairsin an associative array.When applied to a string-valued variable, <var>value</var> is expanded andappended 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 hasits attributes modified (other than using or changing the namerefattribute itself), theoperation is actually performed on the variable specified by the namerefvariable’s value.A nameref is commonly used within shell functions to refer to a variablewhose name is passed as an argument to the function.For instance, if a variable name is passed to a shell function as its firstargument, 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 isthe 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 modificationsto 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 referencewill be established for each word in the list, in turn, when the loop isexecuted.Array variables cannot be given the nameref attribute.However, nameref variables can reference array variables and subscriptedarray 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 variableas 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 moredigits, other than the single digit <code>0</code>. Positional parameters areassigned 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>, oras <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 andunset them (see <a href="#Shell-Builtin-Commands">Shell Builtin Commands</a>).The positional parameters aretemporarily 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 singledigit 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 mayonly 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 parameterexpands to a separate word.In contexts where it is performed, those wordsare subject to further word splitting and filename expansion.When the expansion occurs within double quotes, it expands to a single wordwith the value of each parameter separated by the first character of the<code>IFS</code> special variable. That is, <code>"$*"</code> is equivalentto <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 interveningseparators.</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 eachpositional parameter to a separate word; if not within doublequotes, these words are subject to word splitting.In contexts where word splitting is not performed,this expands to a single wordwith each positional parameter separated by a space.When theexpansion occurs within double quotes, and word splitting is performed,each parameter expands to aseparate word. That is, <code>"$@"</code> is equivalent to<code>"$1" "$2" …</code>.If the double-quoted expansion occurs within a word, the expansion ofthe first parameter is joined with the beginning part of the originalword, and the expansion of the last parameter is joined with the lastpart 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 foregroundpipeline.</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 uponinvocation, 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, itexpands 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 thebackground, whether executed as an asynchronous command or usingthe <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 atshell 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 beexecuted, if one is present. Otherwise, it is setto 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 expansionavailable: <em>process substitution</em>.This is performed at thesame time as tilde, parameter, variable, and arithmetic expansion andcommand substitution.</p><p>After these expansions are performed, quote characters present in theoriginal word are removed unless they have been quoted themselves(<em>quote removal</em>).</p><p>Only brace expansion, word splitting, and filename expansioncan increase the number of words of the expansion; other expansionsexpand 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 expressionbetween a pair of braces,followed by an optional <var>postscript</var>.The preamble is prefixed to each string contained within the braces, andthe postscript is then appended to each resulting string, expanding leftto right.</p><p>Brace expansions may be nested.The results of each expanded string are not sorted; left to right orderis preserved.For example,</p><div class="example"><pre class="example">bash$ echo a{d,c,b}eade 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 thesame width.When either <var>x</var> or <var>y</var> begins with a zero, the shellattempts 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 characterlexicographically 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 betweeneach 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 preservedin the result. It is strictly textual. Bashdoes not apply any syntactic interpretation to the context of theexpansion or the text between the braces.</p><p>A correctly-formed brace expansion must contain unquoted openingand closing braces, and at least one unquoted comma or a validsequence expression.Any incorrectly formed brace expansion is left unchanged.</p><p>A { or ‘<samp>,</samp>’ may be quoted with a backslash to prevent itsbeing 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 commonprefix of the strings to be generated is longer than in theabove 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 thecharacters 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, thecharacters in the tilde-prefix following the tilde are treated as apossible <em>login name</em>.If this login name is the null string, the tilde is replaced with thevalue of the <code>HOME</code> shell variable.If <code>HOME</code> is unset, the home directory of the user executing theshell is substituted instead.Otherwise, the tilde-prefix is replaced with the home directoryassociated with the specified login name.</p><p>If the tilde-prefix is ‘<samp>~+</samp>’, the value ofthe 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 anumber <var>N</var>, optionally prefixed by a ‘<samp>+</samp>’ or a ‘<samp>-</samp>’,the tilde-prefix is replaced with thecorresponding element from the directory stack, as it would be displayedby the <code>dirs</code> builtin invoked with the characters following tildein 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 aleading ‘<samp>+</samp>’ or ‘<samp>-</samp>’, ‘<samp>+</samp>’ is assumed.</p><p>If the login name is invalid, or the tilde expansion fails, the word isleft unchanged.</p><p>Each variable assignment is checked for unquoted tilde-prefixes immediatelyfollowing 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 ofvariable 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 listedabove, 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 nameor symbol to be expanded may be enclosed in braces, whichare optional but serve to protect the variable to be expanded fromcharacters immediately following it which could beinterpreted 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 anembedded arithmetic expansion, command substitution, or parameterexpansion.</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 beinterpreted 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 thenexpanded and that value is used in the rest of the expansion, ratherthan 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 thevariable referenced by <var>parameter</var> instead of performing thecomplete 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 tointroduce 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 describedbelow (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 valueis 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 toin this way.</p><div class="example"><pre class="example">$ var=$ : ${var:=DEFAULT}$ echo $varDEFAULT</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 messageto that effect if <var>word</var>is not present) is written to the standard error and the shell, if itis not interactive, exits. Otherwise, the value of <var>parameter</var> issubstituted.</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 asdescribed 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 valueis used as an offset in charactersfrom 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 charactersfrom the end of the value of <var>parameter</var> rather thana 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 leastone space to avoid being confused with the ‘<samp>:-</samp>’ expansion.</p><p>Here are some examples illustrating substring expansion on parameters andsubscripted 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 greatestpositional parameter, so an offset of -1 evaluates to the last positionalparameter.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 positionalparameters:</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 subscriptedby ‘<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 maximumindex 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 indexedarrays:</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 undefinedresults.</p><p>Substring indexing is zero-based unless the positional parametersare 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> isprefixed 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, eachvariable 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 nullotherwise.When ‘<samp>@</samp>’ is used and the expansion appears within double quotes, eachkey 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> issubstituted.If <var>parameter</var> is ‘<samp>*</samp>’ or ‘<samp>@</samp>’, the value substitutedis 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 isinterpreted as relative to one greater than the maximum index of<var>parameter</var>, so negative indices count back from the end of thearray, 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 rulesdescribed below (see <a href="#Pattern-Matching">Pattern Matching</a>). If the pattern matchesthe 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 thelongest 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 positionalparameter 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 thearray 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 rulesdescribed 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 positionalparameter 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 thearray 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 infilename 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> arereplaced 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 deletedand 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 thematching 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 theexpansion of the quoted portion, including replacement strings storedin shell variables.Backslash will escape ‘<samp>&</samp>’ in <var>string</var>; the backslash is removedin order to permit a literal ‘<samp>&</samp>’ in the replacement string.Users should take care if <var>string</var> is double-quoted to avoidunwanted interactions between the backslash and double-quoting, sincebackslash has special meaning within double quotes.Pattern substitution performs the check for unquoted ‘<samp>&</samp>’ afterexpanding <var>string</var>,so users should ensure to properly quote any occurrences of ‘<samp>&</samp>’they want to be taken literally in the replacementand 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=abcdefrep='& '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=abcdefrep='& '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 thereplacement string quote the expanded characters, while double quotesenclosing the entire parameter substitution do not, sincethe expansion is performed in acontext that doesn’t take any enclosing double quotes into account.</p><p>Since backslash can escape ‘<samp>&</samp>’, it can also escape a backslash inthe replacement string.This means that ‘<samp>\\</samp>’ will insert a literalbackslash into the replacement, so these two <code>echo</code> commands</p><div class="example"><pre class="example">var=abcdefrep='\\&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 doublequotes.</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 positionalparameter 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 thearray 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 infilename 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 lettersto lowercase.The ‘<samp>^^</samp>’ and ‘<samp>,,</samp>’ expansions convert each matched character in theexpanded value; the ‘<samp>^</samp>’ and ‘<samp>,</samp>’ expansions match and convert onlythe first character in the expanded value.If <var>pattern</var> is omitted, it is treated like a ‘<samp>?</samp>’, which matchesevery character.</p><p>If <var>parameter</var> is ‘<samp>@</samp>’ or ‘<samp>*</samp>’,the case modification operation is applied to each positionalparameter 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 thearray 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 lowercasealphabetic 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 firstcharacter 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 uppercasealphabetic 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 aformat 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 backslashescape 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 ofan assignment statement or <code>declare</code> command that, ifevaluated, 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 ofindexed 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 ofindexed 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 positionalparameter 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 thearray in turn, and the expansion is the resultant list.</p><p>The result of the expansion is subject to word splitting and filenameexpansion 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 replacethe 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 environmentand replacing the command substitution with the standard output of thecommand, with any trailing newlines deleted.Embedded newlines are not deleted, but they may be removed duringword splitting.The command substitution <code>$(cat <var>file</var>)</code> can bereplaced 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 thecommand substitution.When using the <code>$(<var>command</var>)</code> form, all characters betweenthe parentheses make up the command; none are treated specially.</p><p>Command substitutions may be nested. To nest when using the backquotedform, escape the inner backquotes with backslashes.</p><p>If the substitution appears within double quotes, word splitting andfilename 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 expressionand 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 expansionsas if it were within double quotes,but double quote characters in <var>expression</var> are not treated speciallyand 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 indicatingfailure 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 bereferred 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 ispassed as an argument to the current command as the result of theexpansion.If the <code>>(<var>list</var>)</code> form is used, writing tothe file will provide input for <var>list</var>. If the<code><(<var>list</var>)</code> form is used, the file passed as anargument 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 interpretedas a redirection.Process substitution is supported on systems that support namedpipes (<small>FIFO</small>s) or the <samp>/dev/fd</samp> method of naming open files.</p><p>When available, process substitution is performed simultaneously withparameter and variable expansion, command substitution, and arithmeticexpansion.</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 forword splitting.</p><p>The shell treats each character of <code>$IFS</code> as a delimiter, and splitsthe results of the other expansions into words using these charactersas 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 previousexpansions 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 ofthe whitespace characters <code>space</code>, <code>tab</code>, and <code>newline</code>are ignored at the beginning and end of theword, as long as the whitespace character is in thevalue 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 retainedand passed to commands as empty strings.Unquoted implicit null arguments, resulting from the expansion ofparameters that have no values, are removed.If a parameter with no value is expanded within double quotes, anull argument results and is retainedand passed to a command as an empty string.When a quoted null argument appears as part of a word whose expansion isnon-null, the null argument is removed.That is, the word<code>-d''</code> becomes <code>-d</code> after word splitting andnull argument removal.</p><p>Note that if no expansion occurs, no splittingis 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 isregarded as a <var>pattern</var>,and replaced with an alphabetically sorted list offilenames 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 leftunchanged.If the <code>nullglob</code> option is set, and no matches are found, the wordis 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 performedwithout 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 slashmust 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 beginswith 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 bematched explicitly by a slash in the pattern, but in other matchingcontexts it can be matched by a special pattern character as describedbelow (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 apattern. 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 ofenabling 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 patterncharacters described below, matches itself.The <small>NUL</small> character may not occur in a pattern.A backslash escapes the following character; theescaping backslash is discarded when matching.The special pattern characters must be quoted if they are to be matchedliterally.</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 ina filename expansion context, two adjacent ‘<samp>*</samp>’s used as a singlepattern will match all files and zero or more directories andsubdirectories.If followed by a ‘<samp>/</samp>’, two adjacent ‘<samp>*</samp>’s will match onlydirectories 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 charactersseparated 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 characterin the set. A ‘<samp>]</samp>’ may be matched by including it as the firstcharacter in the set.The sorting order of characters in range expressions,and the characters included in the range,are determined bythe 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 inthese 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 obtainthe traditional interpretation of ranges in bracket expressions, you canforce 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 specifiedusing the syntax<code>[:</code><var>class</var><code>:]</code>, where <var>class</var> is one of thefollowing classes defined in the <small>POSIX</small> standard:</p><div class="example"><pre class="example">alnum alpha ascii blank cntrl digit graph lowerprint 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 bespecified using the syntax <code>[=</code><var>c</var><code>=]</code>, whichmatches all characters with the same collation weight (as definedby 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 oneor more patterns separated by a ‘<samp>|</samp>’.When matching filenames, the <code>dotglob</code> shell option determinesthe set of filenames that are tested, as described above.Composite patterns may be formed using one or more of the followingsub-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 theparentheses are normally treated as operators with syntactic meaning.To ensure that extended matching patterns are parsed correctly, make surethat <code>extglob</code> is enabled before parsing constructs containing thepatterns, including shell functions and command substitutions.</p><p>When matching filenames, the <code>dotglob</code> shell option determinesthe set of filenames that are tested:when <code>dotglob</code> is enabled, the set of filenames includes all filesbeginning with ‘<samp>.</samp>’, but the filenames‘<samp>.</samp>’ and ‘<samp>..</samp>’ must be matched by apattern or sub-pattern that begins with a dot;when it is disabled, the set does notinclude any filenames beginning with “.” unless the patternor 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 stringscontain multiple matches.Using separate matches against shorter strings, or using arrays ofstrings 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 thecharacters ‘<samp>\</samp>’, ‘<samp>'</samp>’, and ‘<samp>"</samp>’ that did notresult 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 outputmay be <em>redirected</em>using a special notation interpreted by the shell.<em>Redirection</em> allows commands’ file handles to beduplicated, 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 thecurrent shell execution environment. The following redirectionoperators may precede or appear anywhere within asimple command or may follow a command.Redirections are processed in the order they appear, fromleft to right.</p><p>Each redirection that may be preceded by a file descriptor numbermay 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 greaterthan 10 and assign it to {<var>varname</var>}. If >&- or <&- is precededby {<var>varname</var>}, the value of <var>varname</var> defines the filedescriptor to close.If {<var>varname</var>} is supplied, the redirection persists beyondthe scope of the command, allowing the shell programmer to managethe 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 isomitted, and the first character of the redirection operator is‘<samp><</samp>’, the redirection refers to the standard input (filedescriptor 0). If the first character of the redirection operatoris ‘<samp>></samp>’, the redirection refers to the standard output (filedescriptor 1).</p><p>The word following the redirection operator in the followingdescriptions, unless otherwise noted, is subjected to brace expansion,tilde expansion, parameter expansion, command substitution, arithmeticexpansion, 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 outputbefore the standard output was redirected to <var>dirlist</var>.</p><p>Bash handles several filenames specially when they are used inredirections, as described in the following table.If the operating system on which Bash is running provides thesespecial files, bash will use them; otherwise it will emulate theminternally 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 openthe 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 withcare, as they may conflict with file descriptors the shell usesinternally.</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 fromthe 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 fromthe 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 redirectionwill 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 redirectionis 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 fashioncauses the file whose name results fromthe 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 thestandard output (file descriptor 1) andthe standard error output (file descriptor 2)to be redirected to the file whose name is theexpansion of <var>word</var>.</p><p>There are two formats for redirecting standard output andstandard 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 thestandard output (file descriptor 1) andthe standard error output (file descriptor 2)to be appended to the file whose name is theexpansion 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 thecurrent source until a line containing only <var>word</var>(with no trailing blanks) is seen. All ofthe lines read up to that point are then used as the standardinput (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 toparameter 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 theline containing <var>delimiter</var>.This allows here-documents within shell scripts to be indented in anatural 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> undergoestilde 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 itsstandard 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 forinput, 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 foroutput, 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 notexpand to one or more digits or ‘<samp>-</samp>’, the standard output and standarderror 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 followingexpansions, assignments, and redirections, from left to right, inthe following order.</p><ol><li> The words that the parser has marked as variable assignments (thosepreceding the command name) and redirections are saved for laterprocessing. </li><li> The words that are not variable assignments or redirections areexpanded (see <a href="#Shell-Expansions">Shell Expansions</a>).If any words remain after expansion, the first wordis taken to be the name of the command and the remaining words arethe 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 tildeexpansion, 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 currentshell environment.In the case of such a command (one that consists only of assignmentstatements and redirections), assignment statements are performed beforeredirections.Otherwise, the variables are added to the environmentof 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 notaffect the current shell environment. A redirection error causes thecommand to exit with a non-zero status.</p><p>If there is a command name left after expansion, execution proceeds asdescribed below. Otherwise, the command exits. If one of the expansionscontained a command substitution, the exit status of the command isthe exit status of the last command substitution performed. If therewere 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 asimple command and an optional list of arguments, the followingactions are taken.</p><ol><li> If the command name contains no slashes, the shell attempts tolocate it. If there exists a shell function by that name, thatfunction 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 forit in the list of shell builtins. If a match is found, thatbuiltin 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 fileby that name. Bash uses a hash table to remember the fullpathnames 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 shellfunction named <code>command_not_found_handle</code>.If that function exists, it is invoked in a separate execution environmentwith the original command andthe original command’s arguments as its arguments, and the function’sexit status becomes the exit status of that subshell.If that function is not defined, the shell prints an errormessage and returns an exit status of 127. </li><li> If the search is successful, or if the command name containsone or more slashes, the shell executes the named program ina separate execution environment.Argument 0 is set to the name given, and the remaining argumentsto the command are set to the arguments supplied, if any. </li><li> If this execution fails because the file is not in executableformat, 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 forthe 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 thefollowing:</p><ul><li> open files inherited by the shell at invocation, as modified byredirections 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 fromthe 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’sparent in the environment </li><li> options enabled at invocation (either by default or with command-linearguments) 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 functionis to be executed, itis invoked in a separate execution environment that consists ofthe following. Unless otherwise noted, the values are inheritedfrom the shell.</p><ul><li> the shell’s open files, plus any modifications and additions specifiedby 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 variablesexported 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 theshell’s parent, and traps ignored by the shell are ignored </li></ul> <p>A command invoked in this separate environment cannot affect theshell’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 asubshell environment that is a duplicate of the shell environment,except that traps caught by the shell are reset to the valuesthat the shell inherited from its parent at invocation. Builtincommands that are invoked as part of a pipeline are also executedin a subshell environment. Changes made to the subshell environmentcannot affect the shell’s execution environment.</p><p>Subshells spawned to execute command substitutions inherit the value ofthe <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, thedefault standard input for the command is the empty file <samp>/dev/null</samp>.Otherwise, the invoked command inherits the file descriptors of the callingshell 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 stringscalled 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 andcreates a parameter for each name found, automatically markingit 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 anddeleted from the environment. If the value of a parameterin the environment is modified, the new value becomes partof the environment, replacing the old. The environmentinherited by any executed command consists of the shell’sinitial 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 commandor function may be augmented temporarily by prefixing it withparameter assignments, as described in <a href="#Shell-Parameters">Shell Parameters</a>.These assignment statements affect only the environment seenby that command.</p><p>If the <samp>-k</samp> option is set (see <a href="#The-Set-Builtin">The Set Builtin</a>), then allparameter 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 thatcommand 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 mayuse values above 125 specially. Exit statuses from shell builtins andcompound commands are also limited to this range. Under certaincircumstances, the shell will use special values to indicate specificfailure modes.</p><p>For the shell’s purposes, a command which exits with azero exit status has succeeded.A non-zero exit status indicates failure.This seemingly counter-intuitive scheme is used so thereis one well-defined way to indicate success and a variety ofways 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 toexecute 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 listconstructs (see <a href="#Lists">Lists of Commands</a>).</p><p>All of the Bash builtins return an exit status of zero if they succeedand a non-zero status on failure, so they may be used by theconditional 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 specialparameter $? (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>), Bashignores <code>SIGTTIN</code>, <code>SIGTTOU</code>, and <code>SIGTSTP</code>.</p><p>Non-builtin commands started by Bash have signal handlers set to thevalues inherited by the shell from its parent.When job control is not in effect, asynchronous commandsignore <code>SIGINT</code> and <code>SIGQUIT</code> in addition to these inheritedhandlers.Commands run as a result ofcommand 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> toall jobs, running or stopped.Stopped jobs are sent <code>SIGCONT</code> to ensure that they receivethe <code>SIGHUP</code>.To prevent the shell from sending the <code>SIGHUP</code> signal to aparticular job, it should be removedfrom the jobs table with the <code>disown</code>builtin (see <a href="#Job-Control-Builtins">Job Control Builtins</a>) or markedto 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 whenan interactive login shell exits.</p><p>If Bash is waiting for a command to complete and receives a signalfor which a trap has been set, the trap will not be executed untilthe command completes.When Bash is waiting for an asynchronouscommand via the <code>wait</code> builtin, the reception of a signal forwhich a trap has been set will cause the <code>wait</code> builtin to returnimmediately with an exit status greater than 128, immediately afterwhich the trap is executed.</p><p>When job control is not enabled, and Bash is waiting for a foregroundcommand to complete, the shell receives keyboard-generated signalssuch as <code>SIGINT</code> (usually generated by ‘<samp>^C</samp>’) that userscommonly intend to send to that command.This happens because the shell and the command are in the same processgroup as the terminal, and ‘<samp>^C</samp>’ sends <code>SIGINT</code> to all processesin 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 foregroundcommand 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 concludesthat 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 programhandled 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 theprogram’s normal operation (e.g., <code>emacs</code> uses it to abort editingcommands) or deliberately discarded. However, Bash will run anytrap set on <code>SIGINT</code>, as it does with any other trapped signal itreceives while it is waiting for the foreground command tocomplete, 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 sucha 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. Thismode of operation creates a non-interactive shell. The shell firstsearches for the file in the current directory, and looks in thedirectories in <code>$PATH</code> if not found there.</p><p>When Bash runsa shell script, it sets the special parameter <code>0</code> to the nameof the file, rather than the name of the shell, and the positionalparameters are set to the remaining arguments, if any are given.If no additional arguments are supplied, the positional parametersare unset.</p><p>A shell script may be made executable by using the <code>chmod</code> commandto turn on the execute bit. When Bash finds such a file whilesearching the <code>$PATH</code> for a command, it creates anew instance of itselfto 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 anew shell had been invoked to interpret the script, with theexception 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 commandexecution mechanism. If the first line of a script begins withthe two characters ‘<samp>#!</samp>’, the remainder of the line specifiesan interpreter for the program and, depending on the operating system, oneor more optional arguments for that interpreter.Thus, you can specify Bash, <code>awk</code>, Perl, or some otherinterpreter and write the rest of the script file in that language.</p><p>The arguments to the interpreterconsist of one or more optional arguments following the interpretername on the first line of the script file, followed by the name ofthe script file, followed by the rest of the arguments supplied to thescript.The details of how the interpreter line is split into an interpreter nameand a set of arguments vary across systems.Bash will perform this action on operating systems that do not handle itthemselves.Note that some older versions of Unix limit the interpretername and a single argument to a maximum of 32 characters, so it’s notportable to assume that using more than one argument will work.</p><p>Bash scripts often begin with <code>#! /bin/bash</code> (assuming thatBash has been installed in <samp>/bin</samp>), since this ensures thatBash will be used to interpret the script, even if it is executedunder 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 ofa simple command (see <a href="#Simple-Commands">Simple Commands</a>), the shell executesthe command directly, without invoking another program.Builtin commands are necessary to implement functionality impossibleor inconvenient to obtain with separate utilities.</p><p>This section briefly describes the builtins which Bash inherits fromthe Bourne Shell, as well as the builtin commands which are uniqueto or have been extended in Bash.</p><p>Several builtin commands are described in other chapters: builtincommands which provide the Bash interface to the job controlfacilities (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 completionfacilities (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 acceptingoptions 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 beginningwith ‘<samp>-</samp>’ without requiring ‘<samp>--</samp>’.Other builtins that accept arguments but are not specified as acceptingoptions interpret arguments beginning with ‘<samp>-</samp>’ as invalid options andrequire ‘<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 thecurrent 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 directoryif <var>filename</var> is not found in <code>$PATH</code>.If any <var>arguments</var> are supplied, they become the positionalparameters when <var>filename</var> is executed. Otherwise the positionalparameters 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 andrestored 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 changesthe <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, orzero if no commands are executed. If <var>filename</var> is not found, orcannot 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 linksare resolved while <code>cd</code> is traversing <var>directory</var> and beforeprocessing an instance of ‘<samp>..</samp>’ in <var>directory</var>.</p><p>By default, or when the <samp>-L</samp> option is supplied, symbolic linksin <var>directory</var> are resolved after <code>cd</code> processes an instanceof ‘<samp>..</samp>’ in <var>directory</var>.</p><p>If ‘<samp>..</samp>’ appears in <var>directory</var>, it is processed by removing theimmediately preceding pathname component, back to a slash or the beginningof <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 determinedafter a successful directory change, <code>cd</code> will return an unsuccessfulstatus.</p><p>On systems that support it, the <samp>-@</samp> option presents the extendedattributes 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 issuccessful, the absolute pathname of the new working directory iswritten 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 workingdirectory 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 loopis 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 isthen read and executed, and its exit status returned as the exit statusof <code>eval</code>.If there are no arguments or only empty arguments, the return status iszero.</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 thebeginning 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 emptyenvironment.If <samp>-a</samp> is supplied, the shell passes <var>name</var> as the zerothargument 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 optionis 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 affectthe current shell environment. If there are no redirection errors, thereturn 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 processesin the environment. If the <samp>-f</samp> option is supplied, the <var>name</var>srefer 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, alist 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 ofthe variable is set to <var>value</var>.</p><p>The return status is zero unless an invalid option is supplied, one ofthe names is not a valid shell variable name, or <samp>-f</samp> is suppliedwith 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 acharacter is followed by a colon, the option is expected to have anargument, which should be separated from it by whitespace.The colon (‘<samp>:</samp>’) and question mark (‘<samp>?</samp>’) may not beused 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 thevariable <code>OPTIND</code>.<code>OPTIND</code> is initialized to 1 each time the shell or a shell scriptis 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 manuallyreset between multiple calls to <code>getopts</code> within the same shellinvocation if a new set of parameters is to be used.</p><p>When the end of options is encountered, <code>getopts</code> exits with areturn 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 aresupplied 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 messagesare printed when invalid options or missing option arguments areencountered.If the variable <code>OPTERR</code>is set to 0, no error messages will be displayed, even if the firstcharacter 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 thecommands 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> isused 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 locationof 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 aresupplied with <samp>-t</samp>, the <var>name</var> is printed before the hashedfull pathname.The <samp>-l</samp> option causes output to be displayed in a formatthat 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 invalidoption 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 notcontain symbolic links.If the <samp>-L</samp> option is supplied, the pathname printed may containsymbolic links.The return status is zero unless an error is encountered whiledetermining the name of the current directory or an invalid optionis 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 shellfunction.The <samp>-a</samp> option means each <var>name</var> refers to an indexedarray variable; the <samp>-A</samp> option means each <var>name</var> refersto 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 ofthe set of readonly names.The <samp>-p</samp> option causes output to be displayed in a format thatmay be reused as input.If a variable name is followed by =<var>value</var>, the value ofthe variable is set to <var>value</var>.The return status is zero unless an invalid option is supplied, one ofthe <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 thelast command executed in the function.If <code>return</code> is executed by a trap handler, the last command used todetermine 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 commandused to determine the status is the last command executed by the traphandler before <code>return</code> was invoked.<code>return</code> may also be used to terminate execution of a scriptbeing executed with the <code>.</code> (<code>source</code>) builtin,returning either <var>n</var> orthe exit status of the last command executed within the script as the exitstatus of the script.If <var>n</var> is supplied, the return value is its least significant8 bits.Any command associated with the <code>RETURN</code> trap is executedbefore execution resumes after the function or script.The return status is non-zero if <code>return</code> is supplied a non-numericargument or is used outside a functionand 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> arerenamed to <code>$1</code> … <code>$#</code>-<var>n</var>.Parameters represented by the numbers <code>$#</code> down to <code>$#</code>-<var>n</var>+1are 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 parametersare 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> orless 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 ignorean 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 mustbe a <code>]</code>.</p><p>Expressions may be combined using the following operators, listed indecreasing 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 conditionalexpressions 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 andonly 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 expressionis true if the unary test is true.If the first argument is not a valid unary operator, the expression isfalse.</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 conditionaloperators (see <a href="#Bash-Conditional-Expressions">Bash Conditional Expressions</a>), theresult of the expression is the result of the binary test using thefirst and third arguments as operands.The ‘<samp>-a</samp>’ and ‘<samp>-o</samp>’ operators are considered binary operatorswhen there are three arguments.</li><li> If the first argument is ‘<samp>!</samp>’, the value is the negation ofthe two-argument test using the second and third arguments.</li><li> If the first argument is exactly ‘<samp>(</samp>’ and the third argument isexactly ‘<samp>)</samp>’, the result is the one-argument test of the secondargument.</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 ofthe three-argument expression composed of the remaining arguments.</li><li> If the first argument is exactly ‘<samp>(</samp>’ and the fourth argument isexactly ‘<samp>)</samp>’, the result is the two-argument test of the secondand third arguments.</li><li> Otherwise, the expression is parsed and evaluated according toprecedence 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 precedenceusing 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 theshell receives signal <var>sigspec</var>. If <var>arg</var> is absent (andthere is a single <var>sigspec</var>) orequal to ‘<samp>-</samp>’, each specified signal’s disposition is resetto the value it had when the shell was started.If <var>arg</var> is the null string, then the signal specified byeach <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, oronly <samp>-p</samp> is given, <code>trap</code> prints the list of commandsassociated with each signal number in a form that may be reused asshell input.The <samp>-l</samp> option causes the shell to print a list of signal namesand 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 executedbefore every simple command, <code>for</code> command, <code>case</code> command,<code>select</code> command, every arithmetic <code>for</code> command, and beforethe 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 itseffect on the <code>DEBUG</code> trap.If a <var>sigspec</var> is <code>RETURN</code>, the command <var>arg</var> is executedeach 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 whenevera pipeline (which may consist of a single simplecommand), a list, or a compound command returns anon-zero exit status,subject to the following conditions.The <code>ERR</code> trap is not executed if the failed command is part of thecommand 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> listexcept the command following the final <code>&&</code> or <code>||</code>,any command in a pipeline but the last,or if the command’s returnstatus 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 originalvalues 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 avalid 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 similarto that accepted by the <code>chmod</code> command. If <var>mode</var> isomitted, 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 printedin 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 ifno <var>mode</var> argument is supplied, and non-zero otherwise.</p><p>Note that when the mode is interpreted as an octal number, each numberof 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 shellfunctions, and the function definition is removed.If the <samp>-n</samp> option is supplied, and <var>name</var> is a variable withthe <code>nameref</code> attribute, <var>name</var> will be unset rather than thevariable 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; ifthere is no variable by that name, a function with that name, if any, isunset.Readonly variables and functions may not be unset.Some shell variables lose their special behavior if they are unset; suchbehavior 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 toor 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> printsthe list of aliases on the standard output in a form that allowsthem 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 nameand 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 aReadline 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 bythe 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 asynonym); <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 theycan 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 theycan 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 outputin such a way that they can be used as input or in a Readlineinitialization 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> isentered.When <var>shell-command</var> is executed, the shell sets the<code>READLINE_LINE</code> variable to the contents of the Readline linebuffer and the <code>READLINE_POINT</code> and <code>READLINE_MARK</code> variablesto the current location of the insertion point and the saved insertionpoint (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 bereflected 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 commandsin a format that can be reused as input.</p></dd></dl> <p>The return status is zero unless an invalid option is supplied or anerror 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 samename as a shell builtin, retaining the functionality of the builtin withinthe function.The return status is non-zero if <var>shell-builtin</var> is not a shellbuiltin 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 ora 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 sourcefilename 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 correspondingto that position in the current execution call stack. This extrainformation may be used, for example, to print a stack trace. Thecurrent frame is frame 0.</p><p>The return value is 0 unless the shell is not executing a subroutinecall or <var>expr</var> does not correspond to a valid position in thecall 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 functionnamed <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 befound 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, adescription of <var>command</var> is printed. The <samp>-v</samp> optioncauses a single word indicating the command or file name used toinvoke <var>command</var> to be displayed; the <samp>-V</samp> option producesa more verbose description. In this case, the return status iszero 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>sare 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 theattributes specified by the additional options.If no other options are supplied with <samp>-p</samp>, <code>declare</code> willdisplay 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 whereeach <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 atthe 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 withthe 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 asan integer; arithmetic evaluation (see <a href="#Shell-Arithmetic">Shell Arithmetic</a>) isperformed 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 areconverted 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, makingit a name reference to another variable.That other variable is defined by the value of <var>name</var>.All references, assignments, and attribute modificationsto <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 valuesby 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 fromthe 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 areconverted 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 viathe 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 notremove 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 variableis 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 untilsubsequent 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 withoutusing 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 anewline.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 followingbackslash-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 todynamically determine whether or not <code>echo</code> expands theseescape 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 nameas 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> binaryfound 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 listconsists of all enabled shell builtins.The <samp>-a</samp> option means to listeach 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 acolon-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> specialbuiltins. If <samp>-s</samp> is used with <samp>-f</samp>, the new builtin becomesa 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 builtinor 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 helpon all commands matching <var>pattern</var>, otherwise a list ofthe 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 shellvariables. Each <var>expression</var> is evaluated according to therules given below in <a href="#Shell-Arithmetic">Shell Arithmetic</a>. If thelast <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 itschildren.If <var>name</var> is ‘<samp>-</samp>’, the set of shell options is made local to thefunction in which <code>local</code> is invoked: shell options changed usingthe <code>set</code> builtin inside the function are restored to their originalvalues when the function returns.The restore is effected as if a series of <code>set</code> commands were executedto restore the values that were in place before the function.The return status is zero unless <code>local</code> is used outsidea function, an invalid <var>name</var> is supplied, or <var>name</var> is areadonly 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’sparent.</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 linewhen 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 nextarray element to be assigned and the line to be assigned to that elementas additional arguments.<var>callback</var> is evaluated after the line is read but before thearray 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 optionargument 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 thecontrol 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, characterescape sequences, which are converted and copied to the standard output, andformat 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 thecorresponding <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 thecorresponding <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 ofseconds since the epoch.Two special argument values may be used: -1 represents the currenttime, 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 precisionarguments from the format specification and write that many bytes from (or use that wide a field for) the expanded argument, which usuallycontains 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 leadingcharacter is a single or double quote, the value is the ASCII value ofthe 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, theextra format specifications behave as if a zero value or null string, asappropriate, 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 wordis 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 assignedto 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> variableare used to split the line into words using the same rules the shelluses for expansion (described above in <a href="#Word-Splitting">Word Splitting</a>).The backslash character ‘<samp>\</samp>’ may be used to remove any specialmeaning 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 linewhen 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 previouslyactive) 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 intothe 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 thanwaiting for a complete line of input, but honors a delimiter if fewerthan <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 ratherthan waiting for a complete line of input, unless EOF is encountered or<code>read</code> times out.Delimiter characters encountered in the input arenot 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 isthat 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 attemptingto 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 linecontinuation.</p></dd><dt><span><code>-s</code></span></dt><dd><p>Silent mode. If input is coming from a terminal, characters arenot 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 ofinput (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 followingthe decimal point.This option is only effective if <code>read</code> is reading input from aterminal, pipe, or other special file; it has no effect when readingfrom regular files.If <code>read</code> times out, <code>read</code> saves any partial input read intothe specified variable <var>name</var>.If <var>timeout</var> is 0, <code>read</code> returns immediately, without trying toread 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 thevariable <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 acommand name.</p><p>If the <samp>-t</samp> option is used, <code>type</code> prints a single wordwhich 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 nameof 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 placesthat contain an executable named <var>file</var>.This includes aliases and functions, if and only if the <samp>-p</samp> optionis not also used.</p><p>If the <samp>-f</samp> option is used, <code>type</code> does not attempt to findshell 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-zeroif 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 Kornshell.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] -aulimit [-HS] [-bcdefiklmnpqrstuvxPRT] [<var>limit</var>]</pre></div> <p><code>ulimit</code> provides control over the resources available to processesstarted by the shell, on systems that allow such control. If anoption 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 notallow 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, onsome 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 resourceis printed, unless the <samp>-H</samp> option is supplied.When more than oneresource 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-byteincrements, 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> issupplied, 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 positionalparameters, 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 namesand values of all shell variables and functions, sorted according to thecurrent locale, in a format that may be reused as inputfor 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 theexport attribute and marked for export to the environment ofsubsequent commands.</p></dd><dt><span><code>-b</code></span></dt><dd><p>Cause the status of terminated background jobs to be reportedimmediately, rather than before printing the next primary prompt.</p></dd><dt><span><code>-e</code></span></dt><dd><p>Exit immediately ifa 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 thecommand 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 exceptthe 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 subshellreturns a non-zero status because a command failedwhile <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 environmentseparately (see <a href="#Command-Execution-Environment">Command Execution Environment</a>), and may causesubshells 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 bodywill be affected by the <samp>-e</samp> setting, even if <samp>-e</samp> is setand a command returns a failure status.If a compound command or shell function sets <samp>-e</samp> while executing ina context where <samp>-e</samp> is ignored, that setting will not have anyeffect until the compound command or the command containing the functioncall 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 placedin the environment for a command, not just those that precedethe 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 linecontaining 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 allcommands 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 differsfrom 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 thatstandard.</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 notprocessed, 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 thereal user (group) id, and the <samp>-p</samp> option is not supplied, these actionsare 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 isnot reset.Turning this option off causes the effective userand 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-interactiveshell 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> commandsand their arguments or associated word lists after they areexpanded and before they are executed. The value of the <code>PS4</code>variable is expanded and the resultant value is printed beforethe 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, commandsubstitutions, 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 directoryis used instead. By default, Bash followsthe logical chain of directories when performing commandswhich 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 byshell functions, command substitutions, and commands executedin a subshell environment.The <code>DEBUG</code> and <code>RETURN</code> traps are normally not inheritedin such cases.</p></dd><dt><span><code>--</code></span></dt><dd><p>If no arguments follow this option, then the positional parameters areunset. 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 beturned off. The options can also be used upon invocation of theshell. The current set of options may be found in <code>$-</code>.</p><p>The remaining N <var>arguments</var> are positional parameters and areassigned, 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 settableoptions 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 thatmay 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 statusindicates 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 onlythose 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>sare enabled, non-zero otherwise. When setting or unsetting options,the return status is zero unless an <var>optname</var> is not a valid shelloption.</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 arraysubscripts during arithmetic expression evaluation, while executingbuiltins 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 ifit 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 thatis not a directory is assumed to be the name of a variable whosevalue 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 hashtable exists before trying to execute it. If a hashed command nolonger 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 beforeexiting an interactive shell. If any jobs are running, this causesthe exit to be deferred until a second exit is attempted without anintervening 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, Bashattempts to save all lines of a multiple-linecommand in the same history entry. This allowseasy re-editing of multi-line commands.This option is enabled by default, but only has an effect if commandhistory 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, Bashquotes all shell metacharacters in filenames and directory names whenperforming completion.If not set, Bashremoves metacharacters such as the dollar sign from the set ofcharacters that will be quoted in completed filenameswhen these metacharacters appear in shell variable references in words to becompleted.This means that dollar signs in variable names that expand to directorieswill 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 completedfilenames.This variable is set by default, which is the default Bash behavior inversions through 4.2.</p></dd><dt><span><code>direxpand</code></span></dt><dd><p>If set, Bashreplaces directory names with the results of word expansion when performingfilename completion. This changes the contents of the Readline editingbuffer.If not set, Bash attempts to preserve what the user typed.</p></dd><dt><span><code>dirspell</code></span></dt><dd><p>If set, Bashattempts 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 ‘.’ inthe 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 ifit 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 profilebefore 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 functionname supplied as an argument. </li><li> If the command run by the <code>DEBUG</code> trap returns a non-zero value, thenext command is skipped and not executed. </li><li> If the command run by the <code>DEBUG</code> trap returns a value of 2, and theshell is executing in a subroutine (a shell function or a shell scriptexecuted by the <code>.</code> or <code>source</code> builtins), the shell simulatesa call to <code>return</code>. </li><li> <code>BASH_ARGC</code> and <code>BASH_ARGV</code> are updated as described in theirdescriptions (see <a href="#Bash-Variables">Bash Variables</a>). </li><li> Function tracing is enabled: command substitution, shell functions, andsubshells 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, andsubshells 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 expansionresult 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 variablecause words to be ignored when performing word completion even ifthe 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 performingcomparisons. That is, the current locale’s collating sequenceis 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 willmatch all files and zero or more directories and subdirectories.If the pattern is followed by a ‘<samp>/</samp>’, only directories andsubdirectories 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> errormessage 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 valueof 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 Readlineis being used, a user is given the opportunity to re-edit afailed history substitution.</p></dd><dt><span><code>histverify</code></span></dt><dd><p>If set, and Readlineis being used, the results of history substitution are not immediatelypassed to the shell parser. Instead, the resulting line is loaded intothe 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 performhostname completion when a word containing a ‘<samp>@</samp>’ is beingcompleted (see <a href="#Commands-For-Completion">Letting Readline Type For You</a>). This option is enabledby 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 interactivelogin 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 thatline 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 ofa 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 withembedded 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 ofthe same name that exists at a previous scope before any new value isassigned. 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 scopesmarks them so subsequent lookups find them unset until that functionreturns. This is identical to the behavior of unsetting local variablesat 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 beenaccessed 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 searchthe <code>PATH</code> for possible completions when completion is attemptedon an empty line.</p></dd><dt><span><code>nocaseglob</code></span></dt><dd><p>If set, Bash matches filenames in a case-insensitive fashion whenperforming filename expansion.</p></dd><dt><span><code>nocasematch</code></span></dt><dd><p>If set, Bash matches patterns in a case-insensitive fashion whenperforming 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, Bashencloses the translated results of $"..." quoting in single quotesinstead 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 nofiles to expand to a null string, rather than themselves.</p></dd><dt><span><code>patsub_replacement</code></span></dt><dd><p>If set, Bashexpands occurrences of ‘<samp>&</samp>’ in the replacement string of patternsubstitution to the text matched by the pattern, as describedabove (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 commandname that doesn’t have any completions as a possible alias and attemptsalias expansion. If it has an alias, Bash attempts programmablecompletion using the command word resulting from the expanded alias.</p></dd><dt><span><code>promptvars</code></span></dt><dd><p>If set, prompt strings undergoparameter expansion, command substitution, arithmeticexpansion, and quote removal after being expandedas 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, allowingthe 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 thenumber 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 ofleaving 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 sequencesby 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 classifiedseveral builtin commands as <em>special</em>.When Bash is executing in <small>POSIX</small> mode, the special builtinsdiffer 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 shellenvironment after the command completes.</li></ol> <p>When Bash is not executing in <small>POSIX</small> mode, these builtins behave nodifferently 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 forthe <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> builtincommand.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 splitswords 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 nameand the <code>MAILPATH</code> variableis not set, Bash informs the user of the arrival of mail inthe 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 checksfor new mail.Each list entry can specify the message that is printed when new mailarrives in the mail file by separating the filename from the message witha ‘<samp>?</samp>’.When used in the text of the message, <code>$_</code> expands to the name ofthe 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 forcommands.A zero-length (null) directory name in the value of <code>PATH</code> indicates thecurrent directory.A null directory name may appear as two adjacent colons, or as an initialor 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 escapesequences 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 beingdisplayed.</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 shellsdo 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 theshell or shell script being executed as passed in the environmentor argument list.Subsequently, expands to the last argument to the previous simplecommand executed in the foreground, after expansion. Also set to the full pathname used to invoke each command executedand 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 inthe 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 reportedas ‘<samp>on</samp>’ by ‘<samp>shopt</samp>’.If this variable is in the environment when Bashstarts up, each shell option in the list will be enabled beforereading 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 subshellsthat 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 issubsequently 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 internallist 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 removedfrom the alias list.If <code>BASH_ALIASES</code>is unset, it loses its special properties, even if it issubsequently 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 eachframe of the current bash execution call stack. The number ofparameters to the current subroutine (shell function or script executedwith <code>.</code> or <code>source</code>) is at the top of the stack. When asubroutine 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 bashexecution call stack. The final parameter of the last subroutine callis at the top of the stack; the first parameter of the initial call isat the bottom. When a subroutine is executed, the parameters suppliedare 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 shellscript (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 issubsequently 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 internalhash 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 removedfrom the hash table.If <code>BASH_CMDS</code>is unset, it loses its special properties, even if it issubsequently 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 theshell 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 issubsequently 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 variouscompatibility 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 compatibilitylevel 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 validcompatibility levels, the shell prints an error message and sets thecompatibility level to the default for the current version.The valid values correspond to the compatibility levelsdescribed below (see <a href="#Shell-Compatibility-Mode">Shell Compatibility Mode</a>).For example, 4.2 and 42 are valid values that correspondto the <code>compat42</code> <code>shopt</code> optionand 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 shellscript, its value is expanded and used as the name of a startup fileto 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 fileswhere 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> ifreferenced 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 fordynamically 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>’ binaryoperator to the <code>[[</code> conditional command(see <a href="#Conditional-Constructs">Conditional Constructs</a>).The element with index 0 is the portion of the stringmatching the entire regular expression.The element with index <var>n</var> is the portion of thestring 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 thecorresponding shell function names in the <code>FUNCNAME</code> arrayvariable 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 whenthe 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 issubsequently 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, Bashwill 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 errormessages.The file descriptor is closed when <code>BASH_XTRACEFD</code> is unset or assigneda new value.Unsetting <code>BASH_XTRACEFD</code> or assigning it the empty string causes thetrace output to be sent to the standard error.Note that setting <code>BASH_XTRACEFD</code> to 2 (the standard error filedescriptor) and then unsetting it will result in the standard errorbeing 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>-mandatedminimum, and there is a maximum value (currently 8192) that this maynot 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 widthwhen 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 currentcursor position.This variable is available only in shell functions invoked by theprogrammable 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 externalcommands invoked by theprogrammable 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 ofthe 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 externalcommands invoked by theprogrammable 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 attemptedthat 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 externalcommands invoked by theprogrammable 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 currentcompletion 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 wordseparators 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 individualwords 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 theprogrammable 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 completionsgenerated by a shell function invoked by the programmable completionfacility (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 descriptorsfor 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 modifydirectories 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 ifit 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 shellstarts with value ‘<samp>t</samp>’, it assumes that the shell is running in anEmacs 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 secondssince the Unix Epoch as a floating point value with micro-second granularity(see the documentation for the C library function <code>time</code> for thedefinition of Epoch).Assignments to <code>EPOCHREALTIME</code> are ignored.If <code>EPOCHREALTIME</code>is unset, it loses its special properties, even ifit 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 secondssince 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 ifit 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 variableis 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 consideredexecutable files for the purposes of completion and command executionvia <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 executablebit 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 performingfilename completion.A filename whose suffix matches one of the entries in <code>FIGNORE</code>is excluded from the list of matched filenames. A samplevalue 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 functionscurrently in the execution call stack.The element with index 0 is the name of any currently-executingshell 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 ifit 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 thisinformation.</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 functionnesting level. Function invocations that exceed this nesting levelwill 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 tobe ignored by filename expansion.If a file name matched by a filename expansion pattern also matches oneof the patterns in <code>GLOBIGNORE</code>, it is removed from the listof matches.The pattern matching honors the setting of the <code>extglob</code> shelloption.</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 issubsequently 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, quicksubstitution, 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 thestart of a history expansion, normally ‘<samp>!</samp>’. The second character is thecharacter which signifies ‘quick substitution’ when seen as the firstcharacter on a line, normally ‘<samp>^</samp>’. The optional third character is thecharacter which indicates that the remainder of the line is a comment whenfound as the first character of a word, usually ‘<samp>#</samp>’. The historycomment character causes history substitution to be skipped for theremaining words on the line. It does not necessarily cause the shellparser 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 currentcommand.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 onthe history list.If the list of values includes ‘<samp>ignorespace</samp>’, lines which beginwith a space character are not saved in the history list.A value of ‘<samp>ignoredups</samp>’ causes lines which match the previoushistory 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 thecurrent line to be removed from the history list before that lineis 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 arenot 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. Thedefault 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 linesby removing the oldest entries.The history file is also truncated to this size afterwriting 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 commandlines should be saved on the history list. Each pattern isanchored at the beginning of the line and must match the completeline (no implicit ‘<samp>*</samp>’ is appended). Each pattern is testedagainst the line after the checks specified by <code>HISTCONTROL</code>are applied. In addition to the normal shell pattern matchingcharacters, ‘<samp>&</samp>’ matches the previous history line. ‘<samp>&</samp>’may be escaped using a backslash; the backslash is removedbefore attempting a match. The second and subsequent lines of a multi-line compound command arenot 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> shelloption.</p><p><code>HISTIGNORE</code> subsumes the function of <code>HISTCONTROL</code>. Apattern of ‘<samp>&</samp>’ is identical to <code>ignoredups</code>, and apattern 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 savedon 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 stringfor <code>strftime</code> to print the time stamp associated with each historyentry displayed by the <code>history</code> builtin.If this variable is set, time stamps are written to the history file sothey may be preserved across shell sessions.This uses the history comment character to distinguish timestamps fromother 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> thatshould be read when the shell needs to complete a hostname.The list of possible hostname completions may be changed while the shellis running;the next time hostname completion is attempted after thevalue is changed, Bash adds the contents of the new file to theexisting 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> characteras the sole input. If set, the value denotes the numberof consecutive <code>EOF</code> characters that can be read as thefirst character on an input linebefore the shell will exit. If the variable exists but does nothave 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 defaultof <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 shellstarts, it assumes that the shell is running in an Emacs shell bufferand 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 specificallyselected 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 theresults of filename expansion, anddetermines 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 thebehavior of character classes within filename expansion and patternmatching (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-quotedstrings 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 timeformatting.</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 issubsequently 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 lengthfor 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 Bashis 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 thefiles specified in the <code>MAILPATH</code> or <code>MAIL</code> variables.The default is 60 seconds. When it is time to checkfor mail, the shell does so before displaying the primary prompt.If this variable is unset, or set to a value that is not a numbergreater 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 messagesgenerated 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 processesin the most-recently-executed foreground pipeline (which maycontain 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 shellenters <small>POSIX</small> mode (see <a href="#Bash-POSIX-Mode">Bash POSIX Mode</a>) before reading thestartup 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 wasnot 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 variableis 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 executebefore 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 oftrailing 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 commandand 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 lineis 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 integerbetween 0 and 32767. Assigning a value to thisvariable seeds the random number generator.If <code>RANDOM</code>is unset, it loses its special properties, even if it issubsequently 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 usewith ‘<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 theReadline line buffer, for usewith ‘<samp>bind -x</samp>’ (see <a href="#Bash-Builtins">Bash Builtin Commands</a>).The characters between the insertion point and the mark are oftencalled 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 usewith ‘<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 theexpanded value becomes the value assigned plus the number of secondssince the assignment.The number of seconds at shell invocation and the current time are alwaysdetermined 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 inthe 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 reportedas ‘<samp>on</samp>’ by ‘<samp>set -o</samp>’.If this variable is in the environment when Bashstarts up, each shell option in the list will be enabled beforereading 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 isintended 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 isreferenced. The random number generator is not linear on systems thatsupport <samp>/dev/urandom</samp> or <code>arc4random</code>, so each returned numberhas no relationship to the numbers preceding it.The random number generator cannot be seeded, so assignments to thisvariable 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 specifyinghow the timing information for pipelines prefixed with the <code>time</code>reserved word should be displayed.The ‘<samp>%</samp>’ character introduces anescape sequence that is expanded to a time value or otherinformation.The escape sequences and their meanings are asfollows; 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 offractional 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; valuesof <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, ofthe 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 thedefault 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>) terminatesif input does not arrive after <code>TMOUT</code> seconds when input is comingfrom a terminal.</p><p>In an interactive shell, the value is interpreted asthe number of seconds to wait for a line of input after issuingthe primary prompt.Bashterminates after waiting for that number of seconds if a completeline 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 whichBash 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-characteroptions that you can use. These options must appear on the commandline 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 shellstarts. 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 outputin 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 aninteractive shell. This is on by default if the shell isinvoked as <code>sh</code>.</p></dd><dt><span><code>--posix</code></span></dt><dd><p>Change the behavior of Bash where the default operation differsfrom the <small>POSIX</small> standard to match the standard. Thisis intended to make Bash behave as a strict superset of thatstandard. 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 ofBash on the standard output and exit successfully.</p></dd></dl> <p>There are several single-character options that may be supplied atinvocation 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 usedin warning and error messages.</p></dd><dt><span><code>-i</code></span></dt><dd><p>Force the shell to run interactively. Interactive shells aredescribed 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 alogin shell with ‘<samp>exec -l bash</samp>’.When the shell is not interactive, the login shell startup files willbe 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 behaviorof 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 optionprocessing, then commands are read from the standard input.This option allows the positional parameters to be setwhen invoking an interactive shell or when reading inputthrough 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 thatare subject to language translation when the current localeis 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 shelloptions 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 formatthat 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 optionprocessing.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 bothconnected to terminals (as determined by <code>isatty(3)</code>), or onestarted with the <samp>-i</samp> option. See <a href="#Interactive-Shells">Interactive Shells</a>, for moreinformation.</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 tobe 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 parametersare 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 executedin 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 underTilde 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 anon-interactive shell with the <samp>--login</samp> option, it first reads andexecutes 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 readsand executes commands from the first one that exists and is readable.The <samp>--noprofile</samp> option may be used when the shell is started toinhibit 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 fromthe 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, Bashreads 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 andexecute 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 asthe name of a file to read and execute. Bash behaves as if thefollowing 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 thefilename.</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 thelogin 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 thestartup behavior of historical versions of <code>sh</code> as closely aspossible, while conforming to the <small>POSIX</small> standard as well.</p><p>When invoked as an interactive login shell, or as a non-interactiveshell with the <samp>--login</samp> option, it first attempts to readand execute commands from <samp>/etc/profile</samp> and <samp>~/.profile</samp>, inthat 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>, Bashlooks 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 executecommands from any other startup files, the <samp>--rcfile</samp> option hasno effect.A non-interactive shell invoked with the name <code>sh</code> does not attemptto read any other startup files.</p><p>When invoked as <code>sh</code>, Bash enters <small>POSIX</small> mode afterthe 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> standardfor startup files.In this mode, interactive shells expand the <code>ENV</code> variableand commands are read and executed from the file whose name is theexpanded 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 inputconnected to a network connection, as when executed bythe historical remote shell daemon, usually <code>rshd</code>,or the secure shell daemon <code>sshd</code>.If Bashdetermines it is being run non-interactively in this fashion,it reads and executes commands from <samp>~/.bashrc</samp>, if thatfile 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, butneither <code>rshd</code> nor <code>sshd</code> generally invoke the shell with thoseoptions 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 thereal user (group) id, and the <samp>-p</samp> option is not supplied, no startupfiles 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 effectiveuser id is set to the real user id.If the <samp>-p</samp> option is supplied at invocation, the startup behavior isthe 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 shellis 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 bothconnected 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’sterminal.</p><p>The <samp>-s</samp> invocation option may be used to set the positional parameterswhen 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 isrunning 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 ininteractive shells. Thus:</p><div class="example"><pre class="example">if [ -z "$PS1" ]; then echo This shell is not interactiveelse echo This shell is interactivefi</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 inseveral 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 jobcontrol is in effect, Bash ignores the keyboard-generated job controlsignals <code>SIGTTIN</code>, <code>SIGTTOU</code>, and <code>SIGTSTP</code>. </li><li> Bash expands and displays <code>PS1</code> before reading the first lineof a command, and expands and displays <code>PS2</code> before reading thesecond and subsequent lines of a multi-line command.Bash expands and displays <code>PS0</code> after it reads a command but beforeexecuting it.See <a href="#Controlling-the-Prompt">Controlling the Prompt</a>, for a complete list of promptstring 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 fromthe 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 itsstandard 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 exitif 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>’ hasno 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 unsetor 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 theshell to exit. </li><li> When running in <small>POSIX</small> mode, a special builtin returning an errorstatus 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 attemptsimple 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 exitif a command is not read within the specified number of seconds afterprinting <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 numberof arguments; see the descriptions of those commands for any othercommand-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 inexpressions.If the operating system on which Bash is running provides thesespecial files, Bash will use them; otherwise it will emulate theminternally 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>, filedescriptor 0, 1, or 2, respectively, is checked.</p><p>When used with <code>[[</code>, the ‘<samp><</samp>’ and ‘<samp>></samp>’ operators sortlexicographically using the current locale.The <code>test</code> command uses ASCII ordering.</p><p>Unless otherwise specified, primaries that operate on files follow symboliclinks 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 andinode 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 asdescribed 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 ofthe 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 valuesare the same as in the C language.The following list of operators is grouped into levels ofequal-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 isperformed before the expression is evaluated. Within an expression, shell variables may also be referenced by namewithout using the parameter expansion syntax.A shell variable that is null or unset evaluates to 0 when referencedby name without using the parameter expansion syntax.The value of a variable is evaluated as an arithmetic expressionwhen 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 onto be used in an expression.</p><p>Integer constants follow the C language definition, without suffixes orcharacter 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 arithmeticbase, 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 uppercaseletters may be used interchangeably to represent numbers between 10and 35.</p><p>Operators are evaluated in order of precedence. Sub-expressions inparentheses are evaluated first and may override the precedencerules 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 usedas the first word of a simple command.The shell maintains a list of aliases that may be set and unset withthe <code>alias</code> and <code>unalias</code> builtin commands.</p><p>The first word of each simple command, if unquoted, is checked to seeif 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 theshell metacharacters or quoting characters listed above may not appearin an alias name.The replacement text may contain any validshell input, including shell metacharacters.The first word of the replacement text is tested foraliases, but a word that is identical to an alias being expandedis 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 thereplacement text.If the last character of the alias value is a<code>blank</code>, then the next command word following thealias 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 aresomewhat confusing. Bashalways 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 acommand is read, not when it is executed. Therefore, analias definition appearing on the same line as anothercommand does not take effect until the next line of input is read.The commands following the alias definitionon 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 definitionis itself a command. As a consequence, aliasesdefined in a function are not available until after thatfunction is executed. To be safe, always putalias 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 maximumlimit on the size of an array, nor any requirement that membersbe indexed or assigned contiguously.Indexed arrays are referenced using integers (including arithmeticexpressions (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 tousing 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 bespecified for an array variable using the <code>declare</code> and<code>readonly</code> builtins. Each attribute applies to all members ofan 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, ifthe optional subscript is supplied, that index is assigned to;otherwise the index of the element assigned is the last index assignedto by the statement plus one. Indexing starts at zero.</p><p>Each <var>value</var> in the list undergoes all the shell expansionsdescribed above (see <a href="#Shell-Expansions">Shell Expansions</a>).</p><p>When assigning to an associative array, the words in a compound assignmentmay be either assignment statements, for which the subscript is required,or a list of words that is interpreted as a sequence of alternating keysand 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 wordsare 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 isinterpreted as relative to one greater than the maximum index of<var>name</var>, so negative indices count back from the end of thearray, and an index of -1 references the last element.</p><p>The ‘<samp>+=</samp>’ operator will append to an array variable when assigningusing 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 avoidconflicts with the shell’s filename expansion operators. If the<var>subscript</var> is ‘<samp>@</samp>’ or ‘<samp>*</samp>’, the word expands to all membersof the array <var>name</var>. These subscripts differ only when the wordappears within double quotes.If the word is double-quoted,<code>${<var>name</var>[*]}</code> expands to a single word withthe 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 ofthe first parameter is joined with the beginning part of the originalword, and the expansion of the last parameter is joined with the lastpart of the original word.This is analogous to theexpansion 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 arrayevaluates to a number less than zero, it isinterpreted 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 toreferencing 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 avalue. 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 indicesassigned in array variable <var>name</var>.The treatment when in double quotes is similar to the expansion of thespecial 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 theentire array.<code>unset <var>name</var>[<var>subscript</var>]</code> behaves differentlydepending on the array type when given asubscript 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 syntaxdescribed 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 indexedarray 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 inputto an array, and can read values from the standard input intoindividual array elements. The <code>set</code> and <code>declare</code>builtins display array values in a way that allows them to bereused 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 changesthe current directory, and the <code>popd</code> builtin removes specifieddirectories from the stack and changes the current directory tothe directory removed. The <code>dirs</code> builtin displays the contentsof the directory stack. The current directory is always the "top"of the directory stack.</p><p>The contents of the directory stack are also visibleas 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. Directoriesare 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 perline.</p></dd><dt><span><code>-v</code></span></dt><dd><p>Causes <code>dirs</code> to print the directory stack with one entry perline, 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 thelist printed by <code>dirs</code> when invoked without options), startingwith 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 thelist printed by <code>dirs</code> when invoked without options), startingwith 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 directorylisted 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 tothe 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 directoriesfrom 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 thelist 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 thelist 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, andthe <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 ifan invalid option is encountered, the directory stackis 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 rotatesthe stack, making the new top of the stack the current workingdirectory.With no arguments, <code>pushd</code> exchanges the top two elementsof 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 oradding 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 thelist printed by <code>dirs</code>, starting with zero) to the top ofthe 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 thelist printed by <code>dirs</code>, starting with zero) to the top ofthe 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 notsupplied, <code>pushd</code> uses the <code>cd</code> builtin to change to thedirectory 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 thedirectory stack is empty.When rotating the directory stack, <code>pushd</code> returns 0 unlessthe directory stack is empty or a non-existent directory stack elementis 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 beforeprinting each primary prompt.If any elements in <code>PROMPT_COMMAND</code> are set and non-null, Bashexecutes 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 whichcan 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 insertedinto the prompt string; an empty <var>format</var> results in a locale-specifictime 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 portionfollowing 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 toembed 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 historylist, which may include commands restored from the history file(see <a href="#Bash-History-Facilities">Bash History Facilities</a>), while the command number isthe position in the sequence of commands executed during the currentshell session.</p><p>After the string is decoded, it is expanded viaparameter expansion, command substitution, arithmeticexpansion, 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 stringappear within command substitution or contain characters special toword 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 toset 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 inthe shell spawned to execute the script.</p><p>The restricted shell mode is only one component of a useful restrictedenvironment. It should be accompanied by setting <code>PATH</code> to a valuethat allows execution of only a few verified commands (commands thatallow shell escapes are particularly vulnerable), changing the currentdirectory to a non-writable directory other than <code>$HOME</code> after login,not allowing the restricted shell to execute shell scripts, and cleaningthe environment of variables that cause some commands to modify theirbehavior (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 moreclosely to the <small>POSIX</small> standard by changing the behavior tomatch 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 thestartup 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 thecommand hash table, even if it returns it as a (last-ditch) resultfrom a <code>$PATH</code> search. </li><li> The message printed by the job control code and builtins when a jobexits with a non-zero status is ‘Done(status)’. </li><li> The message printed by the job control code and builtins when a jobis stopped is ‘Stopped(<var>signame</var>)’, where <var>signame</var> is, forexample, <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 recognizeddo 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 commandsubstitution is executed. This means that command substitution will notexpand aliases that are defined after the command substitution is initiallyparsed (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>’ tothe 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 thanthe normal Bash files. </li><li> Tilde expansion is only performed on assignments preceding a commandname, rather than on all assignment statements on the line. </li><li> The default history file is <samp>~/.sh_history</samp> (this is thedefault value of <code>$HISTFILE</code>). </li><li> Redirection operators do not perform filename expansion on the wordin the redirection unless the shell is interactive. </li><li> Redirection operators do not perform word splitting on the word in theredirection. </li><li> Function names must be valid shell <code>name</code>s. That is, they may notcontain characters other than letters, digits, and underscores, andmay not start with a digit. Declaring a function with an invalid namecauses a fatal syntax error in non-interactive shells. </li><li> Function names may not be the same as one of the <small>POSIX</small> specialbuiltins. </li><li> <small>POSIX</small> special builtins are found before shell functionsduring command lookup. </li><li> When printing shell function definitions (e.g., by <code>type</code>), Bash doesnot print the <code>function</code> keyword. </li><li> Literal tildes that appear as the first character in elements ofthe <code>PATH</code> variable are not expanded as described aboveunder <a href="#Tilde-Expansion">Tilde Expansion</a>. </li><li> The <code>time</code> reserved word may be used by itself as a command. Whenused in this way, it displays timing statistics for the shell and itscompleted children. The <code>TIMEFORMAT</code> variable controls the formatof the timing information. </li><li> When parsing and expanding a ${…} expansion that appears withindouble quotes, single quotes are no longer special and cannot be used toquote a closing brace or other special character, unless the operator isone of those defined to perform pattern removal. In this case, they donot have to appear as matched pairs. </li><li> The parser does not recognize <code>time</code> as a reserved word if the nexttoken begins with a ‘<samp>-</samp>’. </li><li> The ‘<samp>!</samp>’ character does not introduce history expansion within adouble-quoted string, even if the <code>histexpand</code> option is enabled. </li><li> If a <small>POSIX</small> special builtin returns an error status, anon-interactive shell exits. The fatal errors are those listed inthe <small>POSIX</small> standard, and include things like passing incorrect options,redirection errors, variable assignment errors for assignments precedingthe command name, and so on. </li><li> A non-interactive shell exits with an error status if a variableassignment error occurs when no command name follows the assignmentstatements.A variable assignment error occurs, for example, when trying to assigna value to a readonly variable. </li><li> A non-interactive shell exits with an error status if a variableassignment error occurs in an assignment statement preceding a specialbuiltin, but not with any other simple command. For any other simplecommand, the shell aborts execution of that command, and execution continuesat the top level ("the shell shall not perform any further processing of thecommand in which the error occurred"). </li><li> A non-interactive shell exits with an error status if the iterationvariable 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 expansionresults 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 readwith the <code>.</code> or <code>source</code> builtins, or in a string processed bythe <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 theexpansion is double-quoted does not treat the <code>$*</code> as if it weredouble-quoted. </li><li> Assignment statements preceding <small>POSIX</small> special builtinspersist in the shell environment after the builtin completes. </li><li> The <code>command</code> builtin does not prevent builtins that take assignmentstatements as arguments from expanding them as assignment statements;when not in <small>POSIX</small> mode, assignment builtins lose their assignmentstatement expansion properties when preceded by <code>command</code>. </li><li> The <code>bg</code> builtin uses the required format to describe each job placedin the background, which does not include an indication of whether the jobis 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 theiroutput 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 possiblesignal specification and revert the signal handling to the originaldisposition if it is, unless that argument consists solely of digits andis a valid signal number. If users want to reset the handler for a givensignal to the original disposition, they should use ‘<samp>-</samp>’ as thefirst argument. </li><li> <code>trap -p</code> displays signals whose dispositions are set to SIG_DFL andthose that were ignored when the shell started. </li><li> The <code>.</code> and <code>source</code> builtins do not search the current directoryfor 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, sosubshells spawned to execute command substitutions inherit the value ofthe <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 anerror message. </li><li> When the <code>alias</code> builtin displays alias definitions, it does notdisplay them with a leading ‘<samp>alias </samp>’ unless the <samp>-p</samp> optionis supplied. </li><li> When the <code>set</code> builtin is invoked without options, it does not displayshell function names and definitions. </li><li> When the <code>set</code> builtin is invoked without options, it displaysvariable 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 pathnameconstructed from <code>$PWD</code> and the directory name supplied as an argumentdoes not refer to an existing directory, <code>cd</code> will fail instead offalling back to physical mode. </li><li> When the <code>cd</code> builtin cannot change a directory because thelength of the pathname constructed from <code>$PWD</code> and the directory name supplied as an argumentexceeds <code>PATH_MAX</code> when all symbolic links are expanded, <code>cd</code> willfail 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 thecurrent 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 anindication 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-executablefile as having been found, though the shell will attempt to execute such afile 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 whenthe ‘<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 interpretany arguments to <code>echo</code> as options. Each argument is displayed, afterescape 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> doesnot 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 traphas been set.If Bash receives a trapped signal while executing <code>read</code>, the traphandler 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 convertarguments 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 suchstatuses 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 bydefault 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 historyentries 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 forthe <code>echo</code> builtin to be fully conformant. </li></ol> <p>Bash can be configured to be <small>POSIX</small>-conformant by default, by specifyingthe <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 currentcompatibility level – each option is mutually exclusive.The compatibility level is intended to allow users to select behaviorfrom previous versions that is incompatible with newer versionswhile they migrate scripts to use current features andbehavior. It’s intended to be a temporary solution.</p><p>This section does not mention behavior that is standard for a particularversion (e.g., setting <code>compat32</code> means that quoting the rhs of the regexpmatching operator quotes special regexp characters in the word, which isdefault behavior in bash-3.2 and subsequent versions). </p><p>If a user enables, say, <code>compat32</code>, it may affect the behavior of othercompatibility levels up to and including the current compatibility level.The idea is that each compatibility level controls behavior that changedin 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 forall uses, and as a result users should employ compatibility levels carefully.Read the documentation for a particular feature to find out thecurrent behavior.</p><p>Bash-4.3 introduced a new shell variable: <code>BASH_COMPAT</code>.The value assignedto this variable (a decimal version number like 4.2, or an integercorresponding to the <code>compat</code><var>NN</var> option, like 42) determines thecompatibility level.</p><p>Starting with bash-4.4, Bash has begun deprecating older compatibilitylevels.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 shoptoption 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 eachcompatibility level setting.The <code>compat</code><var>NN</var> tag is used as shorthand for setting thecompatibility levelto <var>NN</var> using one of the following mechanisms.For versions prior to bash-5.0, the compatibility level may be set usingthe 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 executionof the next command in the list (in bash-4.0 and later versions,the shell acts as if it received the interrupt, sointerrupting one command in a list aborts the execution of theentire 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 notconsider the current locale when comparing strings; they use ASCIIordering.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 andstrcoll(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 berecognized as a reserved word (this is <small>POSIX</small> interpretation 267)</li><li> in posix mode, the parser requires that an even number of singlequotes occur in the <var>word</var> portion of a double-quoted ${…}parameter expansion and treats them specially, so that characters withinthe 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 notundergo quote removal, as it does in versions after bash-4.2</li><li> in posix mode, single quotes are considered special when expandingthe <var>word</var> portion of a double-quoted ${…} parameter expansionand 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 quotesare 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 touse a quoted compound assignment as an argument to declare(e.g., declare -a foo=’(1 2)’). Later versions warn that this usage isdeprecated</li><li> word expansion errors are considered non-fatal errors that cause thecurrent command to fail, even in posix mode(the default behavior is to make them fatal errors that cause the shellto 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 breakor continue loops in the calling context. Bash-4.4 and later resetthe 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 extendeddebugging 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 samename in the calling environment even if the shell is not in posixmode</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 slightlymore randomness. If the shell compatibility level is set to 50 orlower, 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.1printed an informational message to that effect, even when producingoutput that can be reused as input. Bash-5.1 suppresses that messagewhen 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 forstatement 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 beexpanded more than once</li><li> the expressions in the $(( ... )) word expansion can be expandedmore than once</li><li> arithmetic expressions used as indexed array subscripts can beexpanded more than once</li><li> <code>test -v</code>, when given an argument of ‘<samp>A[@]</samp>’, where <var>A</var> isan existing associative array, will return true if the array has any setelements.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 beenperformed (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 extglobpattern (say, as part of a shell function) will not fail.This assumes the intent is to enable extglob before the command is executedand word expansions are performed.It will fail at word expansion time if extglob hasn’t beenenabled 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 howBash 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 controlrefers to the ability to selectively stop (suspend)the execution of processes and continue (resume)their execution at a later point. A user typically employsthis facility via an interactive interface supplied jointlyby the operating system kernel’s terminal driver and Bash.</p><p>The shell associates a <var>job</var> with each pipeline. It keeps atable of currently executing jobs, which may be listed with the<code>jobs</code> command. When Bash starts a jobasynchronously, it prints a line that lookslike:</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 is25647. All of the processes in a single pipeline are members ofthe same job. Bash uses the <var>job</var> abstraction as thebasis for job control. </p><p>To facilitate the implementation of the user interface to jobcontrol, the operating system maintains the notion of a current terminalprocess group <small>ID</small>. Members of this process group (processes whoseprocess 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. Backgroundprocesses are those whose process group <small>ID</small> differs from theterminal’s; such processes are immune to keyboard-generatedsignals. Only foreground processes are allowed to read from or, ifthe user so specifies with <code>stty tostop</code>, write to the terminal.Background processes which attempt toread from (write to when <code>stty tostop</code> is in effect) theterminal 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 supportsjob control, Bash contains facilities to use it. Typing the<em>suspend</em> character (typically ‘<samp>^Z</samp>’, Control-Z) while aprocess is running causes that process to be stopped and returnscontrol to Bash. Typing the <em>delayed suspend</em> character(typically ‘<samp>^Y</samp>’, Control-Y) causes the process to be stoppedwhen it attempts to read input from the terminal, and control tobe returned to Bash. The user then manipulates the state ofthis job, using the <code>bg</code> command to continue it in thebackground, the <code>fg</code> command to continue it in theforeground, or the <code>kill</code> command to kill it. A ‘<samp>^Z</samp>’takes effect immediately, and has the additional side effect ofcausing pending output and typeahead to be discarded. </p><p>There are a number of ways to refer to a job in the shell. Thecharacter ‘<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 thecurrent job, which is the last job stopped while it was in the foregroundor started in the background.A single ‘<samp>%</samp>’ (with no accompanying job specification) also refersto 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 usedto 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 theprevious job with a ‘<samp>-</samp>’. </p><p>A job may also be referred tousing a prefix of the name used to start it, or using a substringthat appears in its command line. For example, ‘<samp>%ce</samp>’ refersto a stopped job whose command name begins with ‘<samp>ce</samp>’.Using ‘<samp>%?ce</samp>’, on theother hand, refers to any job containing the string ‘<samp>ce</samp>’ inits 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 thebackground into the foreground. Similarly, ‘<samp>%1 &</samp>’ resumesjob 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 promptbefore reporting changes in a job’s status so as to not interruptany 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 processthat exits.</p><p>If an attempt to exit Bash is made while jobs are stopped, (or running, ifthe <code>checkjobs</code> option is enabled – see <a href="#The-Shopt-Builtin">The Shopt Builtin</a>), theshell prints a warning message, and if the <code>checkjobs</code> option isenabled, 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 thejob changes state. The <samp>-f</samp> option causes <code>wait</code> to waituntil 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 ithad 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 notenabled, or, when run with job control enabled, any<var>jobspec</var> was not found or specifies a jobthat 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 withjob 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 thefollowing 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 sincethe 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 islisted.</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 thecorresponding 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 processnamed 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 thesignals corresponding to the arguments are listed, and the return statusis zero.<var>exit_status</var> is a number specifying a signal number or the exitstatus 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 thelast 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 andthe 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 jobfrom the list of <var>pid</var>s or <var>jobspec</var>s or, if no arguments aresupplied, any job, to complete and returns its exit status.If none of the supplied arguments is a child of the shell, or if no argumentsare supplied and the shell has no unwaited-for children, the exit statusis 127.If the <samp>-p</samp> option is supplied, the process or job identifier of the jobfor 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> toterminate before returning its status, instead of returning when it changesstatus.If neither <var>jobspec</var> nor <var>pid</var> specifies an active child processof the shell, the return status is 127.If <code>wait</code> is interrupted by a signal, the return status will be greaterthan 128, as described above (see <a href="#Signals">Signals</a>).Otherwise, the return status is the exit statusof 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 ofactive 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 shellreceives 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 ormark 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 shellor job control is not enabledand<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 besupplied 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 andjob control. If this variable exists then single word simplecommands without redirections are treated as candidates for resumptionof an existing job. There is no ambiguity allowed; if there ismore than one job beginning with the string typed, thenthe most recently accessed job will be selected.The name of a stopped job, in this context, is the command lineused 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 astopped job. The ‘<samp>substring</samp>’ value provides functionalityanalogous 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 mustbe a prefix of a stopped job’s name; this provides functionalityanalogous 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 isused 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 representkeystrokes.</p><p>The text <kbd>C-k</kbd> is read as ‘Control-K’ and describes the characterproduced when the <tt class="key">k</tt> key is pressed while the Control keyis depressed.</p><p>The text <kbd>M-k</kbd> is read as ‘Meta-K’ and describes the characterproduced 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 ofthe space bar), the <tt class="key">ALT</tt> on the left side is generally set towork as a Meta key.The <tt class="key">ALT</tt> key on the right may also be configured to work as aMeta key or may be configured as some other modifier, such as aCompose 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 asa 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 thecharacter 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> allstand 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> willproduce the desired character.The <tt class="key">RET</tt> key may be labeled <tt class="key">Return</tt> or <tt class="key">Enter</tt> onsome 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. TheReadline library gives you a set of commands for manipulating the textas you type it in, allowing you to just fix your typo, and not forcingyou to retype the majority of the line. Using these editing commands,you move the cursor to the place that needs correction, and delete orinsert the text of the corrections. Then, when you are satisfied withthe line, you simply press <tt class="key">RET</tt>. You do not have to be at theend of the line to press <tt class="key">RET</tt>; the entire line is acceptedregardless 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 typedcharacter appears where the cursor was, and then the cursor moves onespace to the right. If you mistype a character, you can use yourerase character to back up and delete the mistyped character.</p><p>Sometimes you may mistype a character, andnot notice the error until you have typed several other characters. Inthat case, you can type <kbd>C-b</kbd> to move the cursor to the left, and thencorrect your mistake. Afterwards, you can move the cursor to the rightwith <kbd>C-f</kbd>.</p><p>When you add text in the middle of a line, you will notice that charactersto the right of the cursor are ‘pushed over’ to make room for the textthat you have inserted. Likewise, when you delete text behind the cursor,characters to the right of the cursor are ‘pulled back’ to fill in theblank space created by the removal of the text. A list of the bareessentials 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 anempty line.</p></dd></dl> <p>(Depending on your configuration, the <tt class="key">Backspace</tt> key might be set todelete the character to the left of the cursor and the <tt class="key">DEL</tt> key setto delete the character underneath the cursor, like <kbd>C-d</kbd>, ratherthan 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 needin order to do editing of the input line. For your convenience, manyother 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 rapidlyabout 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> movesforward a word. It is a loose convention that control keystrokesoperate 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 saveit 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 canbe 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, sothat when you yank it back, you get it all. The killring is not line specific; the text that you killed on a previouslytyped line is available to be yanked back later, when you are typinganother 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 betweenwords, 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 betweenwords, 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. Yankingmeans 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 ifthe 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 theargument acts as a repeat count, other times it is the <i>sign</i> of theargument that is significant. If you pass a negative argument to acommand which normally acts in a forward direction, that command willact in a backward direction. For example, to kill text back to thestart 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 metadigits before the command. If the first ‘digit’ typed is a minussign (‘<samp>-</samp>’), then the sign of the argument will be negative. Onceyou have typed one meta digit to get the argument started, you can typethe remainder of the digits, and then the command. For example, to givethe <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 thesearch string.As each character of the search string is typed, Readline displaysthe next entry from the history matching the string typed so far.An incremental search requires only as many characters as needed tofind 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> variableare 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 thesearch 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 nextentry matching the search string typed so far.Any other key sequence bound to a Readline command will terminatethe search and execute that command.For instance, a <tt class="key">RET</tt> will terminate the search and acceptthe line, thereby executing the command from the history list.A movement command will terminate the search, make the last line foundthe 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 newsearch string, any remembered search string is used.</p><p>Non-incremental searches read the entire search string before startingto search for matching history lines. The search string may betyped 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-likekeybindings installed by default, it is possible to use a different setof keybindings.Any user can customize programs that use Readline by puttingcommands in an <em>inputrc</em> file,conventionally in their home directory.The name of thisfile is taken from the value of the shell variable <code>INPUTRC</code>. Ifthat variable is unset, the default is <samp>~/.inputrc</samp>. If thatfile 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 Readlinekeybindings and variables.See <a href="#Bash-Builtins">Bash Builtin Commands</a>.</p><p>When a program which uses the Readline library starts up, theinit 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, thusincorporating 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 theReadline init file. Blank lines are ignored.Lines beginning with a ‘<samp>#</samp>’ are comments.Lines beginning with a ‘<samp>$</samp>’ indicate conditionalconstructs (see <a href="#Conditional-Init-Constructs">Conditional Init Constructs</a>). Other linesdenote 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 byaltering the values of variables in Readlineusing 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 tochange 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 regardto case. Unrecognized variable names are ignored.</p><p>Boolean variables (those that can be set to on or off) are set to on ifthe value is null or empty, <var>on</var> (case-insensitive), or 1. Any othervalue 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 namesand values. See <a href="#Bash-Builtins">Bash Builtin Commands</a>.</p><p>A great deal of run-time behavior is changeable with the followingvariables.</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 displayingthe 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 textin 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 ringthe 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 controlcharacters treated specially by the kernel’s terminal driver to theirReadline 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 anopening parenthesis when a closing parenthesis is inserted. The defaultis ‘<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 thecommon 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 forthe 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 differentcolors 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 valueis <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 matcheswhen performing completion.The value is ignored if it is less than 0 or greater than the terminalscreen 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 completionin 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, Readlinetreats hyphens (‘<samp>-</samp>’) and underscores (‘<samp>_</samp>’) as equivalent whenperforming 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 possiblecompletions that is displayed without modification. When set to avalue greater than zero, common prefixes longer than this value arereplaced 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 isasked 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 aretreated 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 theeighth bit set to an <small>ASCII</small> key sequence by stripping the eighthbit and prefixing an <tt class="key">ESC</tt> character, converting them to ameta-prefixed key sequence.The default value is ‘<samp>on</samp>’, butwill be set to ‘<samp>off</samp>’ if the locale is one that containseight-bit characters.This variable is dependent on the <code>LC_CTYPE</code> locale category, andmay 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 hadbeen 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 thekeyboard. 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 ofkey bindings is used. By default, Readline starts up in Emacs editingmode, where the keystrokes are most similar to Emacs. This variable can beset 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 primaryprompt when emacs editing mode is active. The value is expanded like akey binding, so the standard set of meta- and control prefixes andbackslash escape sequences is available.Use the ‘<samp>\1</samp>’ and ‘<samp>\2</samp>’ escapes to begin and end sequences ofnon-printing characters, which can be used to embed a terminal controlsequence 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> refersto 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 commandsto designate the region as <em>active</em>.When the region is active, Readline highlights the text in the region usingthe value of the <code>active-region-start-color</code>, which defaults to thestring that enablesthe terminal’s standout mode.The active region shows the text inserted by bracketed-paste and anymatching 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 eachpaste into the editing buffer as a single string of characters, insteadof 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 keysequences 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 applicationkeypad when it is called. Some systems need this to enable thearrow 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 modifierkey 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 Readlineattempts 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 (thecurrent cursor position) at thesame 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 entriesare saved.If set to a value less than zero, the number of history entries is notlimited.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 itto ‘<samp>on</samp>’ means that the text of the lines being edited will scrollhorizontally on a single screen line when they are longer than the widthof 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 (itwill not clear the eighth bit in the characters it reads),regardless of what the terminal claims it can support. Thedefault 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, andmay 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 withoutsubsequently 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 asynonym); <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 thedefault keymap.</p></dd><dt><span><code>keyseq-timeout</code></span></dt><dd><p>Specifies the duration Readline will wait for a character when reading anambiguous key sequence (one that can form a complete key sequence usingthe input read so far, or can take additional input to complete a longerkey sequence).If no input is received within the timeout, Readline will use the shorterbut complete key sequence.Readline uses this value to determine whether or not input isavailable on the current input source (<code>rl_instream</code> by default).The value is specified in milliseconds, so a value of 1000 means thatReadline will wait one second for additional input.If this variable is set to a value less than or equal to zero, or to anon-numeric value, Readline will wait until another key is pressed todecide 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 slashappended. 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 anasterisk (‘<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 linksto 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 whosenames begin with a ‘<samp>.</samp>’ (hidden files) when performing filenamecompletion.If set to ‘<samp>off</samp>’, the leading ‘<samp>.</samp>’ must besupplied 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 thelist of possible completions (which may be empty) before cycling throughthe 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 theeighth bit set directly rather than as a meta-prefixed escapesequence.The default is ‘<samp>off</samp>’, but Readline will set it to ‘<samp>on</samp>’ if thelocale contains eight-bit characters.This variable is dependent on the <code>LC_CTYPE</code> locale category, andmay 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 pagerto 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 matchessorted 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 linesbefore returning when <code>accept-line</code> is executed. By default,history lines may be modified and retain individual undo lists acrosscalls 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. Ifset to ‘<samp>on</samp>’, words which have more than one possible completion cause thematches 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 ina fashion similar to <var>show-all-if-ambiguous</var>.If set to ‘<samp>on</samp>’, words which have more than one possible completion without anypossible partial completion (the possible completions don’t sharea common prefix) cause the matches to be listed immediately insteadof 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 promptindicating 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 wheninserting a single match into the line. It’s only active whenperforming completion in the middle of a word. If enabled, Readlinedoes not insert characters from the completion that match charactersafter point in the word being completed, so portions of the wordfollowing the cursor are not duplicated.For instance, if this is enabled, attempting completion when the cursoris 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 possiblecompletion.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 primaryprompt when vi editing mode is active and in command mode.The value is expanded like akey binding, so the standard set of meta- and control prefixes andbackslash escape sequences is available.Use the ‘<samp>\1</samp>’ and ‘<samp>\2</samp>’ escapes to begin and end sequences ofnon-printing characters, which can be used to embed a terminal controlsequence 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 primaryprompt when vi editing mode is active and in insertion mode.The value is expanded like akey binding, so the standard set of meta- and control prefixes andbackslash escape sequences is available.Use the ‘<samp>\1</samp>’ and ‘<samp>\2</samp>’ escapes to begin and end sequences ofnon-printing characters, which can be used to embed a terminal controlsequence 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 typeis appended to the filename when listing possiblecompletions. 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 issimple. First you need to find the name of the command that youwant to change. The following sections contain tables of the commandname, the default keybinding, if any, and a short description of whatthe command does.</p><p>Once you know the name of the command, simply place on a linein the init file the name of the keyyou wish to bind the command to, a colon, and then the name of thecommand.There can be no space between the key name and the colon – that will beinterpreted as part of the key name.The name of the key can be expressed in different ways, depending onwhat you find most comfortable.</p><p>In addition to command names, Readline allows keys to be boundto 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 andbindings 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-argumentMeta-Rubout: backward-kill-wordControl-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 macroexpressed 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 whileprocessing 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 stringsdenoting an entire key sequence can be specified, by placingthe key sequence in double quotes. Some <small>GNU</small> Emacs style keyescapes can be used, as in the following example, but thespecial 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 insertthe text ‘<samp>Function Key 1</samp>’.</p></dd></dl> <p>The following <small>GNU</small> Emacs style escape sequences are available whenspecifying 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 secondset 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 mustbe 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 conditionalcompilation features of the C preprocessor which allows keybindings and variable settings to be performed as the resultof 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 theediting mode, the terminal being used, or the application usingReadline. 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 testwhether Readline is in <code>emacs</code> or <code>vi</code> mode.This may be used in conjunctionwith the ‘<samp>set keymap</samp>’ command, for instance, to set bindings inthe <code>emacs-standard</code> and <code>emacs-ctlx</code> keymaps only ifReadline 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-specifickey bindings, perhaps to bind the key sequences output by theterminal’s function keys. The word on the right side of the‘<samp>=</samp>’ is tested against both the full name of the terminal andthe portion of the terminal name before the first ‘<samp>-</samp>’. Thisallows <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 againstspecific 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 consistsof a major version number, an optional decimal point, and an optionalminor version (e.g., ‘<samp>7.1</samp>’). If the minor version is omitted, itis assumed to be ‘<samp>0</samp>’.The operator may be separated from the string <code>version</code> andfrom the version number argument by whitespace.The following example sets a variable if the Readline version being usedis 7.0 or newer:</p><div class="example"><pre class="example">$if version >= 7.0set 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 includeapplication-specific settings. Each program using the Readlinelibrary sets the <var>application name</var>, and you can test fora particular value. This could be used to bind key sequences to functions useful fora specific program. For instance, the following command adds akey 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 Readlinevariables and values.The permitted comparison operators are ‘<samp>=</samp>’, ‘<samp>==</samp>’, and ‘<samp>!=</samp>’.The variable name must be separated from the comparison operator bywhitespace; the operator may be separated from the value on the right handside by whitespace.Both string and boolean variables may be tested. Boolean variables must betested against the values <var>on</var> and <var>off</var>.The following example is equivalent to the <code>mode=emacs</code> test describedabove:</p><div class="example"><pre class="example">$if editing-mode == emacsset 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 ifthe test fails.</p></dd><dt><span><code>$include</code></span></dt><dd><p>This directive takes a single filename as an argument and reads commandsand 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 keybinding, 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 availableset bell-style visible # don't strip characters to 7 bits when readingset input-meta on # allow iso-latin1 characters to be inserted rather# than converted to prefix-meta sequencesset convert-meta off # display characters with the eighth bit set directly# rather than as meta-prefixed charactersset 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 themset 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 keysequences.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 cursorposition, 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 previousphysical screen line. This will not have the desired effect if the currentReadline line does not take up more than one physical line or if point is notgreater 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 nextphysical screen line. This will not have the desired effect if the currentReadline line does not take up more than one physical line or if the lengthof the current Readline line is not greater than the length of the promptplus 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 isnon-empty, add it to the history list according to the setting ofthe <code>HISTCONTROL</code> and <code>HISTIGNORE</code> variables.If this line is a modified history line, then restore the history lineto 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 currentlybeing 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’ throughthe 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’ throughthe 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 searchfor 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 searchfor 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 charactersbetween 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 charactersbetween 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 charactersbetween 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 charactersbetween 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 (usuallythe 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 wordsin the previous command begin with word 0). A negative argumentinserts the <var>n</var>th word from the end of the previous command.Once the argument <var>n</var> is computed, the argument is extractedas 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 theprevious 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 historylist, inserting the last word (or the word specified by the argument tothe first call) of each line in turn.Any numeric argument supplied to these successive calls determinesthe direction to move through the history. A negative argument switchesthe 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 anewline had been entered,and fetch the next line relative to the current line from the historyfor editing.A numeric argument, if supplied, specifies the history entry to use insteadof 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 listand 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 characterson the line, and point is at the beginning of the line, Readlineinterprets 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 thesame 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 meansto 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 theend of the line, in which case the character behind the cursor isdeleted. 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 ishow 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" escapesequence 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 treatingeach character as if it had been read from the keyboard. The charactersare inserted as if each one was bound to <code>self-insert</code> instead ofexecuting 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 themark is active, Readline redisplay uses the terminal’s standout mode todenote 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 overthe character at the cursor, moving thecursor forward as well. If the insertion pointis at the end of the line, then thistransposes 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 transposesthe 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 numericargument, 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> replacethe text at point rather than pushing the text to the right.Characters bound to <code>backward-delete-char</code> replace the characterbefore 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 thebeginning 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 theend 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 betweenwords, 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 betweenwords, 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 transposesthe 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 characteras 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 yankedright 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 ifthe 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 newargument. <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 aleading 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 acharacter that is neither a digit nor minus sign, the argument countfor the next command is multiplied by four.The argument count is initially one, so executing this function thefirst time makes the argument count four, a second time makes theargument 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 thetext begins with ‘<samp>$</samp>’), username (if the text begins with‘<samp>~</samp>’), hostname (if the text begins with ‘<samp>@</samp>’), orcommand (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 usedfor display to the value of <code>completion-display-width</code>, the value ofthe 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 havebeen 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 completedwith a single match from the list of possible completions.Repeated execution of <code>menu-complete</code> steps through the listof 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 listof matches; a negative argument may be used to move backwardthrough the list.This command is intended to be bound to <tt class="key">TAB</tt>, but is unboundby 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 listof possible completions, as if <code>menu-complete</code> had been given anegative 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 orend 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, treatingit 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, treatingit 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, treatingit 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, treatingit as a command name. Command completion attempts tomatch the text against aliases, reserved words, shellfunctions, 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, comparingthe text against lines from the history list for possiblecompletion 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, comparingthe text against lines from the history list for possiblecompletion 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 completionsenclosed 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 macroand 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 charactersin 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 incorporateany 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 andring 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 commandthat 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 keyboardswithout 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 anumeric 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 tothe 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 thatcharacter. 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 occurrenceof that character. A negative argument searches for subsequentoccurrences.</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 thosedefined for keys like Home and End. Such sequences begin with aControl Sequence Indicator (CSI), usually ESC-[. If this sequence isbound to "\e[", keys producing such sequences will have no effectunless explicitly bound to a Readline command, instead of insertingstray 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: ifthe characters at the beginning of the line do not match the valueof <code>comment-begin</code>, the value is inserted, otherwisethe characters in <code>comment-begin</code> are deleted from the beginning ofthe 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 commandto make the current line a shell comment.If a numeric argument causes the comment character to be removed, the linewill 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 theReadline output stream. If a numeric argument is supplied,the output is formatted in such a way that it can be made partof 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 theReadline output stream. If a numeric argument is supplied,the output is formatted in such a way that it can be made partof 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 thestrings they output. If a numeric argument is supplied,the output is formatted in such a way that it can be made partof 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 directoryor 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 togenerate 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 beforepathname 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 beforepathname 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 shellword 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 shellcommands.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 editingof the line. The Readline <code>vi</code> mode behaves as specified inthe <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 theline with the standard <code>vi</code> movement keys, move to previoushistory lines with ‘<samp>k</samp>’ and subsequent lines with ‘<samp>j</samp>’, andso 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 forwhich a completion specification (a <var>compspec</var>) has been definedusing 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, thecompspec is used to generate the list of possible completions for the word.If the command word is the empty string (completion attempted at thebeginning of an empty line), any compspec defined withthe <samp>-E</samp> option to <code>complete</code> is used.If the command word is a full pathname, a compspec for the fullpathname is searched for first.If no compspec is found for the full pathname, an attempt Preview truncated. File is larger than the inline limit.