2014 lines
106 KiB
HTML
2014 lines
106 KiB
HTML
<!DOCTYPE HTML>
|
||
<html lang="en" class="sidebar-visible no-js light">
|
||
<head>
|
||
<!-- Book generated using mdBook -->
|
||
<meta charset="UTF-8">
|
||
<title>Parameters - Zsh Manual</title>
|
||
|
||
|
||
|
||
|
||
<!-- Custom HTML head -->
|
||
|
||
|
||
|
||
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
|
||
<meta name="description" content="">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<meta name="theme-color" content="#ffffff" />
|
||
|
||
|
||
<link rel="icon" href="favicon.svg">
|
||
|
||
|
||
<link rel="shortcut icon" href="favicon.png">
|
||
|
||
<link rel="stylesheet" href="css/variables.css">
|
||
<link rel="stylesheet" href="css/general.css">
|
||
<link rel="stylesheet" href="css/chrome.css">
|
||
|
||
<link rel="stylesheet" href="css/print.css" media="print">
|
||
|
||
|
||
<!-- Fonts -->
|
||
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
|
||
|
||
<link rel="stylesheet" href="fonts/fonts.css">
|
||
|
||
|
||
<!-- Highlight.js Stylesheets -->
|
||
<link rel="stylesheet" href="highlight.css">
|
||
<link rel="stylesheet" href="tomorrow-night.css">
|
||
<link rel="stylesheet" href="ayu-highlight.css">
|
||
|
||
<!-- Custom theme stylesheets -->
|
||
|
||
|
||
|
||
</head>
|
||
<body>
|
||
<!-- Provide site root to javascript -->
|
||
<script type="text/javascript">
|
||
var path_to_root = "";
|
||
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
|
||
</script>
|
||
|
||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||
<script type="text/javascript">
|
||
try {
|
||
var theme = localStorage.getItem('mdbook-theme');
|
||
var sidebar = localStorage.getItem('mdbook-sidebar');
|
||
|
||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||
}
|
||
|
||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||
}
|
||
} catch (e) { }
|
||
</script>
|
||
|
||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||
<script type="text/javascript">
|
||
var theme;
|
||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||
var html = document.querySelector('html');
|
||
html.classList.remove('no-js')
|
||
html.classList.remove('light')
|
||
html.classList.add(theme);
|
||
html.classList.add('js');
|
||
</script>
|
||
|
||
<!-- Hide / unhide sidebar before it is displayed -->
|
||
<script type="text/javascript">
|
||
var html = document.querySelector('html');
|
||
var sidebar = 'hidden';
|
||
if (document.body.clientWidth >= 1080) {
|
||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||
sidebar = sidebar || 'visible';
|
||
}
|
||
html.classList.remove('sidebar-visible');
|
||
html.classList.add("sidebar-" + sidebar);
|
||
</script>
|
||
|
||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||
<div class="sidebar-scrollbox">
|
||
<ol class="chapter"><li class="chapter-item expanded "><a href="The-Z-Shell-Manual.html"><strong aria-hidden="true">1.</strong> The Z Shell Manual</a></li><li class="chapter-item expanded "><a href="Introduction.html"><strong aria-hidden="true">2.</strong> Introduction</a></li><li class="chapter-item expanded "><a href="Roadmap.html"><strong aria-hidden="true">3.</strong> Roadmap</a></li><li class="chapter-item expanded "><a href="Invocation.html"><strong aria-hidden="true">4.</strong> Invocation</a></li><li class="chapter-item expanded "><a href="Files.html"><strong aria-hidden="true">5.</strong> Files</a></li><li class="chapter-item expanded "><a href="Shell-Grammar.html"><strong aria-hidden="true">6.</strong> Shell Grammar</a></li><li class="chapter-item expanded "><a href="Redirection.html"><strong aria-hidden="true">7.</strong> Redirection</a></li><li class="chapter-item expanded "><a href="Command-Execution.html"><strong aria-hidden="true">8.</strong> Command Execution</a></li><li class="chapter-item expanded "><a href="Functions.html"><strong aria-hidden="true">9.</strong> Functions</a></li><li class="chapter-item expanded "><a href="Jobs-_0026-Signals.html"><strong aria-hidden="true">10.</strong> Jobs & Signals</a></li><li class="chapter-item expanded "><a href="Arithmetic-Evaluation.html"><strong aria-hidden="true">11.</strong> Arithmetic Evaluation</a></li><li class="chapter-item expanded "><a href="Conditional-Expressions.html"><strong aria-hidden="true">12.</strong> Conditional Expressions</a></li><li class="chapter-item expanded "><a href="Prompt-Expansion.html"><strong aria-hidden="true">13.</strong> Prompt Expansion</a></li><li class="chapter-item expanded "><a href="Expansion.html"><strong aria-hidden="true">14.</strong> Expansion</a></li><li class="chapter-item expanded "><a href="Parameters.html" class="active"><strong aria-hidden="true">15.</strong> Parameters</a></li><li class="chapter-item expanded "><a href="Options.html"><strong aria-hidden="true">16.</strong> Options</a></li><li class="chapter-item expanded "><a href="Shell-Builtin-Commands.html"><strong aria-hidden="true">17.</strong> Shell Builtin Commands</a></li><li class="chapter-item expanded "><a href="Zsh-Line-Editor.html"><strong aria-hidden="true">18.</strong> Zsh Line Editor</a></li><li class="chapter-item expanded "><a href="Completion-Widgets.html"><strong aria-hidden="true">19.</strong> Completion Widgets</a></li><li class="chapter-item expanded "><a href="Completion-System.html"><strong aria-hidden="true">20.</strong> Completion System</a></li><li class="chapter-item expanded "><a href="Completion-Using-compctl.html"><strong aria-hidden="true">21.</strong> Completion Using compctl</a></li><li class="chapter-item expanded "><a href="Zsh-Modules.html"><strong aria-hidden="true">22.</strong> Zsh Modules</a></li><li class="chapter-item expanded "><a href="Calendar-Function-System.html"><strong aria-hidden="true">23.</strong> Calendar Function System</a></li><li class="chapter-item expanded "><a href="TCP-Function-System.html"><strong aria-hidden="true">24.</strong> TCP Function System</a></li><li class="chapter-item expanded "><a href="Zftp-Function-System.html"><strong aria-hidden="true">25.</strong> Zftp Function System</a></li><li class="chapter-item expanded "><a href="User-Contributions.html"><strong aria-hidden="true">26.</strong> User Contributions</a></li></ol>
|
||
</div>
|
||
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
|
||
</nav>
|
||
|
||
<div id="page-wrapper" class="page-wrapper">
|
||
|
||
<div class="page">
|
||
|
||
<div id="menu-bar-hover-placeholder"></div>
|
||
<div id="menu-bar" class="menu-bar sticky bordered">
|
||
<div class="left-buttons">
|
||
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
||
<i class="fa fa-bars"></i>
|
||
</button>
|
||
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
||
<i class="fa fa-paint-brush"></i>
|
||
</button>
|
||
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
||
</ul>
|
||
|
||
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
||
<i class="fa fa-search"></i>
|
||
</button>
|
||
|
||
</div>
|
||
|
||
<h1 class="menu-title">Zsh Manual</h1>
|
||
|
||
<div class="right-buttons">
|
||
|
||
<a href="print.html" title="Print this book" aria-label="Print this book">
|
||
<i id="print-button" class="fa fa-print"></i>
|
||
</a>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<div id="search-wrapper" class="hidden">
|
||
<form id="searchbar-outer" class="searchbar-outer">
|
||
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||
</form>
|
||
<div id="searchresults-outer" class="searchresults-outer hidden">
|
||
<div id="searchresults-header" class="searchresults-header"></div>
|
||
<ul id="searchresults">
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||
<script type="text/javascript">
|
||
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
||
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
||
});
|
||
</script>
|
||
|
||
<div id="content" class="content">
|
||
<main>
|
||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||
<p><strong>Table of Contents</strong> <em>generated with <a href="https://github.com/thlorenz/doctoc">DocToc</a></em></p>
|
||
<ul>
|
||
<li><a href="#15-parameters">15 Parameters</a>
|
||
<ul>
|
||
<li><a href="#151-description">15.1 Description</a></li>
|
||
<li><a href="#152-array-parameters">15.2 Array Parameters</a>
|
||
<ul>
|
||
<li><a href="#1521-array-subscripts">15.2.1 Array Subscripts</a></li>
|
||
<li><a href="#1522-array-element-assignment">15.2.2 Array Element Assignment</a></li>
|
||
<li><a href="#1523-subscript-flags">15.2.3 Subscript Flags</a></li>
|
||
<li><a href="#1524-subscript-parsing">15.2.4 Subscript Parsing</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#153-positional-parameters">15.3 Positional Parameters</a></li>
|
||
<li><a href="#154-local-parameters">15.4 Local Parameters</a></li>
|
||
<li><a href="#155-parameters-set-by-the-shell">15.5 Parameters Set By The Shell</a></li>
|
||
<li><a href="#156-parameters-used-by-the-shell">15.6 Parameters Used By The Shell</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||
<p><span id="Parameters"></span> <span id="Parameters-1"></span></p>
|
||
<h1 id="15-parameters"><a class="header" href="#15-parameters">15 Parameters</a></h1>
|
||
<p><span id="index-parameters"></span> <span id="index-variables"></span></p>
|
||
<hr />
|
||
<p><span id="Description-5"></span></p>
|
||
<h2 id="151-description"><a class="header" href="#151-description">15.1 Description</a></h2>
|
||
<p>A parameter has a name, a value, and a number of attributes. A name may
|
||
be any sequence of alphanumeric characters and underscores, or the
|
||
single characters ‘<code>*</code>’, ‘<code>@</code>’, ‘<code>#</code>’, ‘<code>?</code>’, ‘<code>-</code>’, ‘<code>$</code>’, or ‘<code>!</code>’. A
|
||
parameter whose name begins with an alphanumeric or underscore is also
|
||
referred to as a <em>variable</em>.</p>
|
||
<p><span id="index-scalar"></span>
|
||
<span id="index-parameters_002c-scalar"></span>
|
||
<span id="index-parameters_002c-array"></span>
|
||
<span id="index-parameters_002c-associative-array"></span>
|
||
<span id="index-hash"></span></p>
|
||
<p>The attributes of a parameter determine the <em>type</em> of its value, often
|
||
referred to as the parameter type or variable type, and also control
|
||
other processing that may be applied to the value when it is referenced.
|
||
The value type may be a <em>scalar</em> (a string, an integer, or a floating
|
||
point number), an array (indexed numerically), or an <em>associative</em> array
|
||
(an unordered set of name-value pairs, indexed by name, also referred to
|
||
as a <em>hash</em>).</p>
|
||
<p><span id="index-export"></span> <span id="index-environment"></span>
|
||
<span id="index-environment-variables"></span>
|
||
<span id="index-variables_002c-environment"></span></p>
|
||
<p>Named scalar parameters may have the <em>exported</em>, <code>-x</code>, attribute, to
|
||
copy them into the process environment, which is then passed from the
|
||
shell to any new processes that it starts. Exported parameters are
|
||
called <em>environment variables</em>. The shell also <em>imports</em> environment
|
||
variables at startup time and automatically marks the corresponding
|
||
parameters as exported. Some environment variables are not imported for
|
||
reasons of security or because they would interfere with the correct
|
||
operation of other shell features.</p>
|
||
<p><span id="index-special-parameters"></span>
|
||
<span id="index-parameters_002c-special"></span></p>
|
||
<p>Parameters may also be <em>special</em>, that is, they have a predetermined
|
||
meaning to the shell. Special parameters cannot have their type changed
|
||
or their readonly attribute turned off, and if a special parameter is
|
||
unset, then later recreated, the special properties will be retained.</p>
|
||
<p>To declare the type of a parameter, or to assign a string or numeric
|
||
value to a scalar parameter, use the <code>typeset</code> builtin.
|
||
<span id="index-typeset_002c-use-of"></span></p>
|
||
<p>The value of a scalar parameter may also be assigned by writing:
|
||
<span id="index-assignment"></span></p>
|
||
<blockquote>
|
||
<p><code>name``=``value</code></p>
|
||
</blockquote>
|
||
<p>In scalar assignment, <code>value</code> is expanded as a single string, in which
|
||
the elements of arrays are joined together; filename expansion is not
|
||
performed unless the option <code>GLOB_ASSIGN</code> is set.</p>
|
||
<p>When the integer attribute, <code>-i</code>, or a floating point attribute, <code>-E</code> or
|
||
<code>-F</code>, is set for <code>name</code>, the <code>value</code> is subject to arithmetic
|
||
evaluation. Furthermore, by replacing ‘<code>=</code>’ with ‘<code>+=</code>’, a parameter can
|
||
be incremented or appended to. See <a href="#Array-Parameters">Array Parameters</a>
|
||
and <a href="Arithmetic-Evaluation.html#Arithmetic-Evaluation">Arithmetic
|
||
Evaluation</a> for
|
||
additional forms of assignment.</p>
|
||
<p>Note that assignment may implicitly change the attributes of a
|
||
parameter. For example, assigning a number to a variable in arithmetic
|
||
evaluation may change its type to integer or float, and with
|
||
<code>GLOB_ASSIGN</code> assigning a pattern to a variable may change its type to
|
||
an array.</p>
|
||
<p>To reference the value of a parameter, write ‘<code>$``name</code>’ or
|
||
‘<code>${``name``}</code>’. See <a href="Expansion.html#Parameter-Expansion">Parameter
|
||
Expansion</a> for complete details.
|
||
That section also explains the effect of the difference between scalar
|
||
and array assignment on parameter expansion.</p>
|
||
<hr />
|
||
<p><span id="Array-Parameters"></span>
|
||
<span id="Array-Parameters-1"></span></p>
|
||
<h2 id="152-array-parameters"><a class="header" href="#152-array-parameters">15.2 Array Parameters</a></h2>
|
||
<p>To assign an array value, write one of:
|
||
<span id="index-set_002c-use-of"></span>
|
||
<span id="index-array-assignment"></span></p>
|
||
<blockquote>
|
||
<p><code>set -A</code> <code>name</code> <code>value</code> ...</p>
|
||
</blockquote>
|
||
<blockquote>
|
||
<p><code>name``=(``value</code> ...<code>)</code></p>
|
||
</blockquote>
|
||
<blockquote>
|
||
<p><code>name``=(``[``key``]=``value</code> ...<code>)</code></p>
|
||
</blockquote>
|
||
<p>If no parameter <code>name</code> exists, an ordinary array parameter is created.
|
||
If the parameter <code>name</code> exists and is a scalar, it is replaced by a new
|
||
array.</p>
|
||
<p>In the third form, <code>key</code> is an expression that will be evaluated in
|
||
arithmetic context (in its simplest form, an integer) that gives the
|
||
index of the element to be assigned with <code>value</code>. In this form any
|
||
elements not explicitly mentioned that come before the largest index to
|
||
which a value is assigned are assigned an empty string. The indices may
|
||
be in any order. Note that this syntax is strict: <code>[</code> and <code>]=</code> must not
|
||
be quoted, and <code>key</code> may not consist of the unquoted string <code>]=</code>, but is
|
||
otherwise treated as a simple string. The enhanced forms of subscript
|
||
expression that may be used when directly subscripting a variable name,
|
||
described in the section Array Subscripts below, are not available.</p>
|
||
<p>The syntaxes with and without the explicit key may be mixed. An implicit
|
||
<code>key</code> is deduced by incrementing the index from the previously assigned
|
||
element. Note that it is not treated as an error if latter assignments
|
||
in this form overwrite earlier assignments.</p>
|
||
<p>For example, assuming the option <code>KSH_ARRAYS</code> is not set, the following:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">array=(one [3]=three four)
|
||
</code></pre>
|
||
</div>
|
||
<p>causes the array variable <code>array</code> to contain four elements <code>one</code>, an
|
||
empty string, <code>three</code> and <code>four</code>, in that order.</p>
|
||
<p>In the forms where only <code>value</code> is specified, full command line
|
||
expansion is performed.</p>
|
||
<p>In the <code>[``key``]=``value</code> form, both <code>key</code> and <code>value</code> undergo all
|
||
forms of expansion allowed for single word shell expansions (this does
|
||
not include filename generation); these are as performed by the
|
||
parameter expansion flag <code>(e)</code> as described in <a href="Expansion.html#Parameter-Expansion">Parameter
|
||
Expansion</a>. Nested parentheses may
|
||
surround <code>value</code> and are included as part of the value, which is joined
|
||
into a plain string; this differs from ksh which allows the values
|
||
themselves to be arrays. A future version of zsh may support that. To
|
||
cause the brackets to be interpreted as a character class for filename
|
||
generation, and therefore to treat the resulting list of files as a set
|
||
of values, quote the equal sign using any form of quoting. Example:</p>
|
||
<blockquote>
|
||
<p><code>name``=(``[a-z]’=’*)</code></p>
|
||
</blockquote>
|
||
<p>To append to an array without changing the existing values, use one of
|
||
the following:</p>
|
||
<blockquote>
|
||
<p><code>name``+=(``value</code> ...<code>)</code></p>
|
||
</blockquote>
|
||
<blockquote>
|
||
<p><code>name``+=(``[``key``]=``value</code> ...<code>)</code></p>
|
||
</blockquote>
|
||
<p>In the second form <code>key</code> may specify an existing index as well as an
|
||
index off the end of the old array; any existing value is overwritten by
|
||
<code>value</code>. Also, it is possible to use <code>[``key``]+=``value</code> to append to
|
||
the existing value at that index.</p>
|
||
<p>Within the parentheses on the right hand side of either form of the
|
||
assignment, newlines and semicolons are treated the same as white space,
|
||
separating individual <code>value</code>s. Any consecutive sequence of such
|
||
characters has the same effect.</p>
|
||
<p>Ordinary array parameters may also be explicitly declared with:
|
||
<span id="index-typeset_002c-use-of-1"></span></p>
|
||
<blockquote>
|
||
<p><code>typeset -a</code> <code>name</code></p>
|
||
</blockquote>
|
||
<p>Associative arrays <em>must</em> be declared before assignment, by using:</p>
|
||
<blockquote>
|
||
<p><code>typeset -A</code> <code>name</code></p>
|
||
</blockquote>
|
||
<p>When <code>name</code> refers to an associative array, the list in an assignment is
|
||
interpreted as alternating keys and values:</p>
|
||
<blockquote>
|
||
<p><code>set -A</code> <code>name</code> <code>key</code> <code>value</code> ...</p>
|
||
</blockquote>
|
||
<blockquote>
|
||
<p><code>name``=(``key</code> <code>value</code> ...<code>)</code></p>
|
||
</blockquote>
|
||
<blockquote>
|
||
<p><code>name``=(``[``key``]=``value</code> ...<code>)</code></p>
|
||
</blockquote>
|
||
<p>Note that only one of the two syntaxes above may be used in any given
|
||
assignment; the forms may not be mixed. This is unlike the case of
|
||
numerically indexed arrays.</p>
|
||
<p>Every <code>key</code> must have a <code>value</code> in this case. Note that this assigns to
|
||
the entire array, deleting any elements that do not appear in the list.
|
||
The append syntax may also be used with an associative array:</p>
|
||
<blockquote>
|
||
<p><code>name``+=(``key</code> <code>value</code> ...<code>)</code></p>
|
||
</blockquote>
|
||
<blockquote>
|
||
<p><code>name``+=(``[``key``]=``value</code> ...<code>)</code></p>
|
||
</blockquote>
|
||
<p>This adds a new key/value pair if the key is not already present, and
|
||
replaces the value for the existing key if it is. In the second form it
|
||
is also possible to use <code>[``key``]+=``value</code> to append to the existing
|
||
value at that key. Expansion is performed identically to the
|
||
corresponding forms for normal arrays, as described above.</p>
|
||
<p>To create an empty array (including associative arrays), use one of:</p>
|
||
<blockquote>
|
||
<p><code>set -A</code> <code>name</code></p>
|
||
</blockquote>
|
||
<blockquote>
|
||
<p><code>name``=()</code></p>
|
||
</blockquote>
|
||
<hr />
|
||
<p><span id="Array-Subscripts"></span></p>
|
||
<h3 id="1521-array-subscripts"><a class="header" href="#1521-array-subscripts">15.2.1 Array Subscripts</a></h3>
|
||
<p><span id="index-subscripts"></span></p>
|
||
<p>Individual elements of an array may be selected using a subscript. A
|
||
subscript of the form ‘<code>[``exp``]</code>’ selects the single element <code>exp</code>,
|
||
where <code>exp</code> is an arithmetic expression which will be subject to
|
||
arithmetic expansion as if it were surrounded by ‘<code>$((</code>...<code>))</code>’. The
|
||
elements are numbered beginning with 1, unless the <code>KSH_ARRAYS</code> option
|
||
is set in which case they are numbered from zero.
|
||
<span id="index-KSH_005fARRAYS_002c-use-of"></span></p>
|
||
<p>Subscripts may be used inside braces used to delimit a parameter name,
|
||
thus ‘<code>${foo[2]}</code>’ is equivalent to ‘<code>$foo[2]</code>’. If the <code>KSH_ARRAYS</code>
|
||
option is set, the braced form is the only one that works, as bracketed
|
||
expressions otherwise are not treated as subscripts.</p>
|
||
<p>If the <code>KSH_ARRAYS</code> option is not set, then by default accesses to an
|
||
array element with a subscript that evaluates to zero return an empty
|
||
string, while an attempt to write such an element is treated as an
|
||
error. For backward compatibility the <code>KSH_ZERO_SUBSCRIPT</code> option can be
|
||
set to cause subscript values 0 and 1 to be equivalent; see the
|
||
description of the option in <a href="Options.html#Description-of-Options">Description of
|
||
Options</a>.</p>
|
||
<p>The same subscripting syntax is used for associative arrays, except that
|
||
no arithmetic expansion is applied to <code>exp</code>. However, the parsing rules
|
||
for arithmetic expressions still apply, which affects the way that
|
||
certain special characters must be protected from interpretation. See
|
||
<em>Subscript Parsing</em> below for details.</p>
|
||
<p>A subscript of the form ‘<code>[*]</code>’ or ‘<code>[@]</code>’ evaluates to all elements of
|
||
an array; there is no difference between the two except when they appear
|
||
within double quotes. ‘<code>"$foo[*]"</code>’ evaluates to ‘<code>"$foo[1] $foo[2]
|
||
</code>...<code>"</code>’, whereas ‘<code>"$foo[@]"</code>’ evaluates to ‘<code>"$foo[1]" "$foo[2]"
|
||
</code>...’. For associative arrays, ‘<code>[*]</code>’ or ‘<code>[@]</code>’ evaluate to all the
|
||
values, in no particular order. Note that this does not substitute the
|
||
keys; see the documentation for the ‘<code>k</code>’ flag under <a href="Expansion.html#Parameter-Expansion">Parameter
|
||
Expansion</a> for complete details.
|
||
When an array parameter is referenced as ‘<code>$``name</code>’ (with no subscript)
|
||
it evaluates to ‘<code>$``name``[*]</code>’, unless the <code>KSH_ARRAYS</code> option is set
|
||
in which case it evaluates to ‘<code>${``name``[0]}</code>’ (for an associative
|
||
array, this means the value of the key ‘<code>0</code>’, which may not exist even
|
||
if there are values for other keys).</p>
|
||
<p>A subscript of the form ‘<code>[``exp1``,``exp2``]</code>’ selects all elements in
|
||
the range <code>exp1</code> to <code>exp2</code>, inclusive. (Associative arrays are
|
||
unordered, and so do not support ranges.) If one of the subscripts
|
||
evaluates to a negative number, say <code>-``n</code>, then the <code>n</code>th element from
|
||
the end of the array is used. Thus ‘<code>$foo[-3]</code>’ is the third element
|
||
from the end of the array <code>foo</code>, and ‘<code>$foo[1,-1]</code>’ is the same as
|
||
‘<code>$foo[*]</code>’.</p>
|
||
<p>Subscripting may also be performed on non-array values, in which case
|
||
the subscripts specify a substring to be extracted. For example, if
|
||
<code>FOO</code> is set to ‘<code>foobar</code>’, then ‘<code>echo $FOO[2,5]</code>’ prints ‘<code>ooba</code>’.
|
||
Note that some forms of subscripting described below perform pattern
|
||
matching, and in that case the substring extends from the start of the
|
||
match of the first subscript to the end of the match of the second
|
||
subscript. For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">string="abcdefghijklm"
|
||
print ${string[(r)d?,(r)h?]}
|
||
</code></pre>
|
||
</div>
|
||
<p>prints ‘<code>defghi</code>’. This is an obvious generalisation of the rule for
|
||
single-character matches. For a single subscript, only a single
|
||
character is referenced (not the range of characters covered by the
|
||
match).</p>
|
||
<p>Note that in substring operations the second subscript is handled
|
||
differently by the <code>r</code> and <code>R</code> subscript flags: the former takes the
|
||
shortest match as the length and the latter the longest match. Hence in
|
||
the former case a <code>*</code> at the end is redundant while in the latter case
|
||
it matches the whole remainder of the string. This does not affect the
|
||
result of the single subscript case as here the length of the match is
|
||
irrelevant.</p>
|
||
<hr />
|
||
<p><span id="Array-Element-Assignment"></span></p>
|
||
<h3 id="1522-array-element-assignment"><a class="header" href="#1522-array-element-assignment">15.2.2 Array Element Assignment</a></h3>
|
||
<p>A subscript may be used on the left side of an assignment like so:</p>
|
||
<blockquote>
|
||
<p><code>name``[``exp``]=``value</code></p>
|
||
</blockquote>
|
||
<p>In this form of assignment the element or range specified by <code>exp</code> is
|
||
replaced by the expression on the right side. An array (but not an
|
||
associative array) may be created by assignment to a range or element.
|
||
Arrays do not nest, so assigning a parenthesized list of values to an
|
||
element or range changes the number of elements in the array, shifting
|
||
the other elements to accommodate the new values. (This is not supported
|
||
for associative arrays.)</p>
|
||
<p>This syntax also works as an argument to the <code>typeset</code> command:</p>
|
||
<blockquote>
|
||
<p><code>typeset</code> <code>"``name``[``exp``]"=``value</code></p>
|
||
</blockquote>
|
||
<p>The <code>value</code> may <em>not</em> be a parenthesized list in this case; only
|
||
single-element assignments may be made with <code>typeset</code>. Note that quotes
|
||
are necessary in this case to prevent the brackets from being
|
||
interpreted as filename generation operators. The <code>noglob</code> precommand
|
||
modifier could be used instead.</p>
|
||
<p>To delete an element of an ordinary array, assign ‘<code>()</code>’ to that
|
||
element. To delete an element of an associative array, use the <code>unset</code>
|
||
command:</p>
|
||
<blockquote>
|
||
<p><code>unset</code> <code>"``name``[``exp``]"</code></p>
|
||
</blockquote>
|
||
<hr />
|
||
<p><span id="Subscript-Flags"></span></p>
|
||
<h3 id="1523-subscript-flags"><a class="header" href="#1523-subscript-flags">15.2.3 Subscript Flags</a></h3>
|
||
<p><span id="index-subscript-flags"></span></p>
|
||
<p>If the opening bracket, or the comma in a range, in any subscript
|
||
expression is directly followed by an opening parenthesis, the string up
|
||
to the matching closing one is considered to be a list of flags, as in
|
||
‘<code>name``[(``flags``)``exp``]</code>’.</p>
|
||
<p>The flags <code>s</code>, <code>n</code> and <code>b</code> take an argument; the delimiter is shown
|
||
below as ‘<code>:</code>’, but any character, or the matching pairs ‘<code>(</code>...<code>)</code>’,
|
||
‘<code>{</code>...<code>}</code>’, ‘<code>[</code>...<code>]</code>’, or ‘<code><</code>...<code>></code>’, may be used, but note that
|
||
‘<code><</code>...<code>></code>’ can only be used if the subscript is inside a double
|
||
quoted expression or a parameter substitution enclosed in braces as
|
||
otherwise the expression is interpreted as a redirection.</p>
|
||
<p>The flags currently understood are:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>w</code><br />
|
||
If the parameter subscripted is a scalar then this flag makes
|
||
subscripting work on words instead of characters. The default word
|
||
separator is whitespace. When combined with the <code>i</code> or <code>I</code> flag, the
|
||
effect is to produce the index of the first character of the
|
||
first/last word which matches the given pattern; note that a failed
|
||
match in this case always yields 0.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>s:``string``:</code><br />
|
||
This gives the <code>string</code> that separates words (for use with the <code>w</code>
|
||
flag). The delimiter character <code>:</code> is arbitrary; see above.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>p</code><br />
|
||
Recognize the same escape sequences as the <code>print</code> builtin in the
|
||
string argument of a subsequent ‘<code>s</code>’ flag.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>f</code><br />
|
||
If the parameter subscripted is a scalar then this flag makes
|
||
subscripting work on lines instead of characters, i.e. with elements
|
||
separated by newlines. This is a shorthand for ‘<code>pws:\n:</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>r</code><br />
|
||
Reverse subscripting: if this flag is given, the <code>exp</code> is taken as a
|
||
pattern and the result is the first matching array element,
|
||
substring or word (if the parameter is an array, if it is a scalar,
|
||
or if it is a scalar and the ‘<code>w</code>’ flag is given, respectively). The
|
||
subscript used is the number of the matching element, so that pairs
|
||
of subscripts such as ‘<code>$foo[(r)??,3]</code>’ and ‘<code>$foo[(r)??,(r)f*]</code>’
|
||
are possible if the parameter is not an associative array. If the
|
||
parameter is an associative array, only the value part of each pair
|
||
is compared to the pattern, and the result is that value.</p>
|
||
<p>If a search through an ordinary array failed, the search sets the
|
||
subscript to one past the end of the array, and hence
|
||
<code>${array[(r)``pattern``]}</code> will substitute the empty string. Thus
|
||
the success of a search can be tested by using the <code>(i)</code> flag, for
|
||
example (assuming the option <code>KSH_ARRAYS</code> is not in effect):</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">[[ ${array[(i)pattern]} -le ${#array} ]]
|
||
</code></pre>
|
||
</div>
|
||
<p>If <code>KSH_ARRAYS</code> is in effect, the <code>-le</code> should be replaced by <code>-lt</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>R</code><br />
|
||
Like ‘<code>r</code>’, but gives the last match. For associative arrays, gives
|
||
all possible matches. May be used for assigning to ordinary array
|
||
elements, but not for assigning to associative arrays. On failure,
|
||
for normal arrays this has the effect of returning the element
|
||
corresponding to subscript 0; this is empty unless one of the
|
||
options <code>KSH_ARRAYS</code> or <code>KSH_ZERO_SUBSCRIPT</code> is in effect.</p>
|
||
<p>Note that in subscripts with both ‘<code>r</code>’ and ‘<code>R</code>’ pattern characters
|
||
are active even if they were substituted for a parameter (regardless
|
||
of the setting of <code>GLOB_SUBST</code> which controls this feature in normal
|
||
pattern matching). The flag ‘<code>e</code>’ can be added to inhibit pattern
|
||
matching. As this flag does not inhibit other forms of substitution,
|
||
care is still required; using a parameter to hold the key has the
|
||
desired effect:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">key2='original key'
|
||
print ${array[(Re)$key2]}
|
||
</code></pre>
|
||
</div>
|
||
</li>
|
||
<li>
|
||
<p><code>i</code><br />
|
||
Like ‘<code>r</code>’, but gives the index of the match instead; this may not
|
||
be combined with a second argument. On the left side of an
|
||
assignment, behaves like ‘<code>r</code>’. For associative arrays, the key part
|
||
of each pair is compared to the pattern, and the first matching key
|
||
found is the result. On failure substitutes the length of the array
|
||
plus one, as discussed under the description of ‘<code>r</code>’, or the empty
|
||
string for an associative array.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>I</code><br />
|
||
Like ‘<code>i</code>’, but gives the index of the last match, or all possible
|
||
matching keys in an associative array. On failure substitutes 0, or
|
||
the empty string for an associative array. This flag is best when
|
||
testing for values or keys that do not exist.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>k</code><br />
|
||
If used in a subscript on an associative array, this flag causes the
|
||
keys to be interpreted as patterns, and returns the value for the
|
||
first key found where <code>exp</code> is matched by the key. Note this could
|
||
be any such key as no ordering of associative arrays is defined.
|
||
This flag does not work on the left side of an assignment to an
|
||
associative array element. If used on another type of parameter,
|
||
this behaves like ‘<code>r</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>K</code><br />
|
||
On an associative array this is like ‘<code>k</code>’ but returns all values
|
||
where <code>exp</code> is matched by the keys. On other types of parameters
|
||
this has the same effect as ‘<code>R</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>n:``expr``:</code><br />
|
||
If combined with ‘<code>r</code>’, ‘<code>R</code>’, ‘<code>i</code>’ or ‘<code>I</code>’, makes them give the
|
||
<code>n</code>th or <code>n</code>th last match (if <code>expr</code> evaluates to <code>n</code>). This flag is
|
||
ignored when the array is associative. The delimiter character <code>:</code>
|
||
is arbitrary; see above.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>b:``expr``:</code><br />
|
||
If combined with ‘<code>r</code>’, ‘<code>R</code>’, ‘<code>i</code>’ or ‘<code>I</code>’, makes them begin at
|
||
the <code>n</code>th or <code>n</code>th last element, word, or character (if <code>expr</code>
|
||
evaluates to <code>n</code>). This flag is ignored when the array is
|
||
associative. The delimiter character <code>:</code> is arbitrary; see above.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>e</code><br />
|
||
This flag causes any pattern matching that would be performed on the
|
||
subscript to use plain string matching instead. Hence
|
||
‘<code>${array[(re)*]}</code>’ matches only the array element whose value is
|
||
<code>*</code>. Note that other forms of substitution such as parameter
|
||
substitution are not inhibited.</p>
|
||
<p>This flag can also be used to force <code>*</code> or <code>@</code> to be interpreted as
|
||
a single key rather than as a reference to all values. It may be
|
||
used for either purpose on the left side of an assignment.</p>
|
||
</li>
|
||
</ul>
|
||
<p>See <em>Parameter Expansion Flags</em> (<a href="Expansion.html#Parameter-Expansion">Parameter
|
||
Expansion</a>) for additional ways to
|
||
manipulate the results of array subscripting.</p>
|
||
<hr />
|
||
<p><span id="Subscript-Parsing"></span></p>
|
||
<h3 id="1524-subscript-parsing"><a class="header" href="#1524-subscript-parsing">15.2.4 Subscript Parsing</a></h3>
|
||
<p>This discussion applies mainly to associative array key strings and to
|
||
patterns used for reverse subscripting (the ‘<code>r</code>’, ‘<code>R</code>’, ‘<code>i</code>’, etc.
|
||
flags), but it may also affect parameter substitutions that appear as
|
||
part of an arithmetic expression in an ordinary subscript.</p>
|
||
<p>To avoid subscript parsing limitations in assignments to associative
|
||
array elements, use the append syntax:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">aa+=('key with "*strange*" characters' 'value string')
|
||
</code></pre>
|
||
</div>
|
||
<p>The basic rule to remember when writing a subscript expression is that
|
||
all text between the opening ‘<code>[</code>’ and the closing ‘<code>]</code>’ is interpreted
|
||
<em>as if</em> it were in double quotes
|
||
(<a href="Shell-Grammar.html#Quoting">Quoting</a>). However, unlike double quotes
|
||
which normally cannot nest, subscript expressions may appear inside
|
||
double-quoted strings or inside other subscript expressions (or both!),
|
||
so the rules have two important differences.</p>
|
||
<p>The first difference is that brackets (‘<code>[</code>’ and ‘<code>]</code>’) must appear as
|
||
balanced pairs in a subscript expression unless they are preceded by a
|
||
backslash (‘<code>\</code>’). Therefore, within a subscript expression (and unlike
|
||
true double-quoting) the sequence ‘<code>\[</code>’ becomes ‘<code>[</code>’, and similarly
|
||
‘<code>\]</code>’ becomes ‘<code>]</code>’. This applies even in cases where a backslash is
|
||
not normally required; for example, the pattern ‘<code>[^[]</code>’ (to match any
|
||
character other than an open bracket) should be written ‘<code>[^\[]</code>’ in a
|
||
reverse-subscript pattern. However, note that ‘<code>\[^\[\]</code>’ and even
|
||
‘<code>\[^[]</code>’ mean the <em>same</em> thing, because backslashes are always
|
||
stripped when they appear before brackets!</p>
|
||
<p>The same rule applies to parentheses (‘<code>(</code>’ and ‘<code>)</code>’) and braces (‘<code>{</code>’
|
||
and ‘<code>}</code>’): they must appear either in balanced pairs or preceded by a
|
||
backslash, and backslashes that protect parentheses or braces are
|
||
removed during parsing. This is because parameter expansions may be
|
||
surrounded by balanced braces, and subscript flags are introduced by
|
||
balanced parentheses.</p>
|
||
<p>The second difference is that a double-quote (‘<code>"</code>’) may appear as part
|
||
of a subscript expression without being preceded by a backslash, and
|
||
therefore that the two characters ‘<code>\"</code>’ remain as two characters in the
|
||
subscript (in true double-quoting, ‘<code>\"</code>’ becomes ‘<code>"</code>’). However,
|
||
because of the standard shell quoting rules, any double-quotes that
|
||
appear must occur in balanced pairs unless preceded by a backslash. This
|
||
makes it more difficult to write a subscript expression that contains an
|
||
odd number of double-quote characters, but the reason for this
|
||
difference is so that when a subscript expression appears inside true
|
||
double-quotes, one can still write ‘<code>\"</code>’ (rather than ‘<code>\\\"</code>’) for
|
||
‘<code>"</code>’.</p>
|
||
<p>To use an odd number of double quotes as a key in an assignment, use the
|
||
<code>typeset</code> builtin and an enclosing pair of double quotes; to refer to
|
||
the value of that key, again use double quotes:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">typeset -A aa
|
||
typeset "aa[one\"two\"three\"quotes]"=QQQ
|
||
print "$aa[one\"two\"three\"quotes]"
|
||
</code></pre>
|
||
</div>
|
||
<p>It is important to note that the quoting rules do not change when a
|
||
parameter expansion with a subscript is nested inside another subscript
|
||
expression. That is, it is not necessary to use additional backslashes
|
||
within the inner subscript expression; they are removed only once, from
|
||
the innermost subscript outwards. Parameters are also expanded from the
|
||
innermost subscript first, as each expansion is encountered left to
|
||
right in the outer expression.</p>
|
||
<p>A further complication arises from a way in which subscript parsing is
|
||
<em>not</em> different from double quote parsing. As in true double-quoting,
|
||
the sequences ‘<code>\*</code>’, and ‘<code>\@</code>’ remain as two characters when they
|
||
appear in a subscript expression. To use a literal ‘<code>*</code>’ or ‘<code>@</code>’ as an
|
||
associative array key, the ‘<code>e</code>’ flag must be used:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">typeset -A aa
|
||
aa[(e)*]=star
|
||
print $aa[(e)*]
|
||
</code></pre>
|
||
</div>
|
||
<p>A last detail must be considered when reverse subscripting is performed.
|
||
Parameters appearing in the subscript expression are first expanded and
|
||
then the complete expression is interpreted as a pattern. This has two
|
||
effects: first, parameters behave as if <code>GLOB_SUBST</code> were on (and it
|
||
cannot be turned off); second, backslashes are interpreted twice, once
|
||
when parsing the array subscript and again when parsing the pattern. In
|
||
a reverse subscript, it’s necessary to use <em>four</em> backslashes to cause a
|
||
single backslash to match literally in the pattern. For complex
|
||
patterns, it is often easiest to assign the desired pattern to a
|
||
parameter and then refer to that parameter in the subscript, because
|
||
then the backslashes, brackets, parentheses, etc., are seen only when
|
||
the complete expression is converted to a pattern. To match the value of
|
||
a parameter literally in a reverse subscript, rather than as a pattern,
|
||
use ‘<code>${(q``)``name``}</code>’ (<a href="Expansion.html#Parameter-Expansion">Parameter
|
||
Expansion</a>) to quote the expanded
|
||
value.</p>
|
||
<p>Note that the ‘<code>k</code>’ and ‘<code>K</code>’ flags are reverse subscripting for an
|
||
ordinary array, but are <em>not</em> reverse subscripting for an associative
|
||
array! (For an associative array, the keys in the array itself are
|
||
interpreted as patterns by those flags; the subscript is a plain string
|
||
in that case.)</p>
|
||
<p>One final note, not directly related to subscripting: the numeric names
|
||
of positional parameters (<a href="#Positional-Parameters">Positional
|
||
Parameters</a>) are parsed specially, so for
|
||
example ‘<code>$2foo</code>’ is equivalent to ‘<code>${2}foo</code>’. Therefore, to use
|
||
subscript syntax to extract a substring from a positional parameter, the
|
||
expansion must be surrounded by braces; for example, ‘<code>${2[3,5]}</code>’
|
||
evaluates to the third through fifth characters of the second positional
|
||
parameter, but ‘<code>$2[3,5]</code>’ is the entire second parameter concatenated
|
||
with the filename generation pattern ‘<code>[3,5]</code>’.</p>
|
||
<hr />
|
||
<p><span id="Positional-Parameters"></span>
|
||
<span id="Positional-Parameters-1"></span></p>
|
||
<h2 id="153-positional-parameters"><a class="header" href="#153-positional-parameters">15.3 Positional Parameters</a></h2>
|
||
<p>The positional parameters provide access to the command-line arguments
|
||
of a shell function, shell script, or the shell itself; see
|
||
<a href="Invocation.html#Invocation">Invocation</a>, and also
|
||
<a href="Functions.html#Functions">Functions</a>. The parameter <code>n</code>, where <code>n</code> is a
|
||
number, is the <code>n</code>th positional parameter. The parameter ‘<code>$0</code>’ is a
|
||
special case, see <a href="#Parameters-Set-By-The-Shell">Parameters Set By The
|
||
Shell</a>.</p>
|
||
<p>The parameters <code>*</code>, <code>@</code> and <code>argv</code> are arrays containing all the
|
||
positional parameters; thus ‘<code>$argv[``n``]</code>’, etc., is equivalent to
|
||
simply ‘<code>$``n</code>’. Note that the options <code>KSH_ARRAYS</code> or
|
||
<code>KSH_ZERO_SUBSCRIPT</code> apply to these arrays as well, so with either of
|
||
those options set, ‘<code>${argv[0]}</code>’ is equivalent to ‘<code>$1</code>’ and so on.</p>
|
||
<p>Positional parameters may be changed after the shell or function starts
|
||
by using the <code>set</code> builtin, by assigning to the <code>argv</code> array, or by
|
||
direct assignment of the form ‘<code>n``=``value</code>’ where <code>n</code> is the number of
|
||
the positional parameter to be changed. This also creates (with empty
|
||
values) any of the positions from 1 to <code>n</code> that do not already have
|
||
values. Note that, because the positional parameters form an array, an
|
||
array assignment of the form ‘<code>n``=(``value</code> ...<code>)</code>’ is allowed, and has
|
||
the effect of shifting all the values at positions greater than <code>n</code> by
|
||
as many positions as necessary to accommodate the new values.</p>
|
||
<hr />
|
||
<p><span id="Local-Parameters"></span>
|
||
<span id="Local-Parameters-1"></span></p>
|
||
<h2 id="154-local-parameters"><a class="header" href="#154-local-parameters">15.4 Local Parameters</a></h2>
|
||
<p>Shell function executions delimit scopes for shell parameters.
|
||
(Parameters are dynamically scoped.) The <code>typeset</code> builtin, and its
|
||
alternative forms <code>declare</code>, <code>integer</code>, <code>local</code> and <code>readonly</code> (but not
|
||
<code>export</code>), can be used to declare a parameter as being local to the
|
||
innermost scope.</p>
|
||
<p>When a parameter is read or assigned to, the innermost existing
|
||
parameter of that name is used. (That is, the local parameter hides any
|
||
less-local parameter.) However, assigning to a non-existent parameter,
|
||
or declaring a new parameter with <code>export</code>, causes it to be created in
|
||
the <em>outer</em>most scope.</p>
|
||
<p>Local parameters disappear when their scope ends. <code>unset</code> can be used to
|
||
delete a parameter while it is still in scope; any outer parameter of
|
||
the same name remains hidden.</p>
|
||
<p>Special parameters may also be made local; they retain their special
|
||
attributes unless either the existing or the newly-created parameter has
|
||
the <code>-h</code> (hide) attribute. This may have unexpected effects: there is no
|
||
default value, so if there is no assignment at the point the variable is
|
||
made local, it will be set to an empty value (or zero in the case of
|
||
integers). The following:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">typeset PATH=/new/directory:$PATH
|
||
</code></pre>
|
||
</div>
|
||
<p>is valid for temporarily allowing the shell or programmes called from it
|
||
to find the programs in <code>/new/directory</code> inside a function.</p>
|
||
<p>Note that the restriction in older versions of zsh that local parameters
|
||
were never exported has been removed.</p>
|
||
<hr />
|
||
<p><span id="Parameters-Set-By-The-Shell"></span>
|
||
<span id="Parameters-Set-By-The-Shell-1"></span></p>
|
||
<h2 id="155-parameters-set-by-the-shell"><a class="header" href="#155-parameters-set-by-the-shell">15.5 Parameters Set By The Shell</a></h2>
|
||
<p>In the parameter lists that follow, the mark ‘<S>’ indicates that the
|
||
parameter is special. ‘<Z>’ indicates that the parameter does not
|
||
exist when the shell initializes in <code>sh</code> or <code>ksh</code> emulation mode.</p>
|
||
<p>The following parameters are automatically set by the shell:</p>
|
||
<p><span id="index-_0021"></span></p>
|
||
<p><code>!</code> <S></p>
|
||
<p>The process ID of the last command started in the background with <code>&</code>,
|
||
put into the background with the <code>bg</code> builtin, or spawned with <code>coproc</code>.</p>
|
||
<p><span id="index-_0023"></span></p>
|
||
<p><code>#</code> <S></p>
|
||
<p>The number of positional parameters in decimal. Note that some confusion
|
||
may occur with the syntax <code>$#``param</code> which substitutes the length of
|
||
<code>param</code>. Use <code>${#}</code> to resolve ambiguities. In particular, the sequence
|
||
‘<code>$#-``...</code>’ in an arithmetic expression is interpreted as the length
|
||
of the parameter <code>-</code>, q.v.</p>
|
||
<p><span id="index-ARGC"></span></p>
|
||
<p><code>ARGC</code> <S> <Z></p>
|
||
<p>Same as <code>#</code>.</p>
|
||
<p><span id="index-_0024"></span></p>
|
||
<p><code>$</code> <S></p>
|
||
<p>The process ID of this shell. Note that this indicates the original
|
||
shell started by invoking <code>zsh</code>; all processes forked from the shells
|
||
without executing a new program, such as subshells started by
|
||
<code>(``...``)</code>, substitute the same value.</p>
|
||
<p><span id="index-_002d-1"></span></p>
|
||
<p><code>-</code> <S></p>
|
||
<p>Flags supplied to the shell on invocation or by the <code>set</code> or <code>setopt</code>
|
||
commands.</p>
|
||
<p><span id="index-_002a"></span></p>
|
||
<p><code>*</code> <S></p>
|
||
<p>An array containing the positional parameters.</p>
|
||
<p><span id="index-argv"></span></p>
|
||
<p><code>argv</code> <S> <Z></p>
|
||
<p>Same as <code>*</code>. Assigning to <code>argv</code> changes the local positional
|
||
parameters, but <code>argv</code> is <em>not</em> itself a local parameter. Deleting
|
||
<code>argv</code> with <code>unset</code> in any function deletes it everywhere, although only
|
||
the innermost positional parameter array is deleted (so <code>*</code> and <code>@</code> in
|
||
other scopes are not affected).</p>
|
||
<p><span id="index-_0040"></span></p>
|
||
<p><code>@</code> <S></p>
|
||
<p>Same as <code>argv[@]</code>, even when <code>argv</code> is not set.</p>
|
||
<p><span id="index-_003f"></span></p>
|
||
<p><code>?</code> <S></p>
|
||
<p>The exit status returned by the last command.</p>
|
||
<p><span id="index-0"></span></p>
|
||
<p><code>0</code> <S></p>
|
||
<p>The name used to invoke the current shell, or as set by the <code>-c</code> command
|
||
line option upon invocation. If the <code>FUNCTION_ARGZERO</code> option is set,
|
||
<code>$0</code> is set upon entry to a shell function to the name of the function,
|
||
and upon entry to a sourced script to the name of the script, and reset
|
||
to its previous value when the function or script returns.</p>
|
||
<p><span id="index-status"></span></p>
|
||
<p><code>status</code> <S> <Z></p>
|
||
<p>Same as <code>?</code>.</p>
|
||
<p><span id="index-pipestatus"></span></p>
|
||
<p><code>pipestatus</code> <S> <Z></p>
|
||
<p>An array containing the exit statuses returned by all commands in the
|
||
last pipeline.</p>
|
||
<p><span id="index-_005f"></span></p>
|
||
<p><code>_</code> <S></p>
|
||
<p>The last argument of the previous command. Also, this parameter is set
|
||
in the environment of every command executed to the full pathname of the
|
||
command.</p>
|
||
<p><span id="index-CPUTYPE"></span></p>
|
||
<p><code>CPUTYPE</code></p>
|
||
<p>The machine type (microprocessor class or machine model), as determined
|
||
at run time.</p>
|
||
<p><span id="index-EGID"></span></p>
|
||
<p><code>EGID</code> <S></p>
|
||
<p>The effective group ID of the shell process. If you have sufficient
|
||
privileges, you may change the effective group ID of the shell process
|
||
by assigning to this parameter. Also (assuming sufficient privileges),
|
||
you may start a single command with a different effective group ID by
|
||
‘<code>(EGID=``gid``; command)</code>’</p>
|
||
<p>If this is made local, it is not implicitly set to 0, but may be
|
||
explicitly set locally.</p>
|
||
<p><span id="index-EUID"></span></p>
|
||
<p><code>EUID</code> <S></p>
|
||
<p>The effective user ID of the shell process. If you have sufficient
|
||
privileges, you may change the effective user ID of the shell process by
|
||
assigning to this parameter. Also (assuming sufficient privileges), you
|
||
may start a single command with a different effective user ID by
|
||
‘<code>(EUID=``uid``; command)</code>’</p>
|
||
<p>If this is made local, it is not implicitly set to 0, but may be
|
||
explicitly set locally.</p>
|
||
<p><span id="index-ERRNO"></span></p>
|
||
<p><code>ERRNO</code> <S></p>
|
||
<p>The value of errno (see man page errno(3)) as set by the most recently
|
||
failed system call. This value is system dependent and is intended for
|
||
debugging purposes. It is also useful with the <code>zsh/system</code> module which
|
||
allows the number to be turned into a name or message.</p>
|
||
<p><span id="index-FUNCNEST"></span></p>
|
||
<p><code>FUNCNEST</code> <S></p>
|
||
<p>Integer. If greater than or equal to zero, the maximum nesting depth of
|
||
shell functions. When it is exceeded, an error is raised at the point
|
||
where a function is called. The default value is determined when the
|
||
shell is configured, but is typically 500. Increasing the value
|
||
increases the danger of a runaway function recursion causing the shell
|
||
to crash. Setting a negative value turns off the check.</p>
|
||
<p><span id="index-GID"></span></p>
|
||
<p><code>GID</code> <S></p>
|
||
<p>The real group ID of the shell process. If you have sufficient
|
||
privileges, you may change the group ID of the shell process by
|
||
assigning to this parameter. Also (assuming sufficient privileges), you
|
||
may start a single command under a different group ID by ‘<code>(GID=``gid``; command)</code>’</p>
|
||
<p>If this is made local, it is not implicitly set to 0, but may be
|
||
explicitly set locally.</p>
|
||
<p><span id="index-HISTCMD"></span></p>
|
||
<p><code>HISTCMD</code></p>
|
||
<p>The current history event number in an interactive shell, in other words
|
||
the event number for the command that caused <code>$HISTCMD</code> to be read. If
|
||
the current history event modifies the history, <code>HISTCMD</code> changes to the
|
||
new maximum history event number.</p>
|
||
<p><span id="index-HOST"></span></p>
|
||
<p><code>HOST</code></p>
|
||
<p>The current hostname.</p>
|
||
<p><span id="index-LINENO"></span></p>
|
||
<p><code>LINENO</code> <S></p>
|
||
<p>The line number of the current line within the current script, sourced
|
||
file, or shell function being executed, whichever was started most
|
||
recently. Note that in the case of shell functions the line number
|
||
refers to the function as it appeared in the original definition, not
|
||
necessarily as displayed by the <code>functions</code> builtin.</p>
|
||
<p><span id="index-LOGNAME"></span></p>
|
||
<p><code>LOGNAME</code></p>
|
||
<p>If the corresponding variable is not set in the environment of the
|
||
shell, it is initialized to the login name corresponding to the current
|
||
login session. This parameter is exported by default but this can be
|
||
disabled using the <code>typeset</code> builtin. The value is set to the string
|
||
returned by the man page getlogin(3) system call if that is available.</p>
|
||
<p><span id="index-MACHTYPE"></span></p>
|
||
<p><code>MACHTYPE</code></p>
|
||
<p>The machine type (microprocessor class or machine model), as determined
|
||
at compile time.</p>
|
||
<p><span id="index-OLDPWD"></span></p>
|
||
<p><code>OLDPWD</code></p>
|
||
<p>The previous working directory. This is set when the shell initializes
|
||
and whenever the directory changes.</p>
|
||
<p><span id="index-OPTARG"></span></p>
|
||
<p><code>OPTARG</code> <S></p>
|
||
<p>The value of the last option argument processed by the <code>getopts</code>
|
||
command.</p>
|
||
<p><span id="index-OPTIND"></span></p>
|
||
<p><code>OPTIND</code> <S></p>
|
||
<p>The index of the last option argument processed by the <code>getopts</code>
|
||
command.</p>
|
||
<p><span id="index-OSTYPE"></span></p>
|
||
<p><code>OSTYPE</code></p>
|
||
<p>The operating system, as determined at compile time.</p>
|
||
<p><span id="index-PPID"></span></p>
|
||
<p><code>PPID</code> <S></p>
|
||
<p>The process ID of the parent of the shell. As for <code>$$</code>, the value
|
||
indicates the parent of the original shell and does not change in
|
||
subshells.</p>
|
||
<p><span id="index-PWD"></span></p>
|
||
<p><code>PWD</code></p>
|
||
<p>The present working directory. This is set when the shell initializes
|
||
and whenever the directory changes.</p>
|
||
<p><span id="index-RANDOM"></span></p>
|
||
<p><code>RANDOM</code> <S></p>
|
||
<p>A pseudo-random integer from 0 to 32767, newly generated each time this
|
||
parameter is referenced. The random number generator can be seeded by
|
||
assigning a numeric value to <code>RANDOM</code>.</p>
|
||
<p>sequence; subshells that reference <code>RANDOM</code> will result in identical
|
||
pseudo-random values unless the value of <code>RANDOM</code> is referenced or
|
||
seeded in the parent shell in between subshell invocations.</p>
|
||
<p><span id="index-SECONDS"></span></p>
|
||
<p><code>SECONDS</code> <S></p>
|
||
<p>The number of seconds since shell invocation. If this parameter is
|
||
assigned a value, then the value returned upon reference will be the
|
||
value that was assigned plus the number of seconds since the assignment.</p>
|
||
<p>Unlike other special parameters, the type of the <code>SECONDS</code> parameter can
|
||
be changed using the <code>typeset</code> command. Only integer and one of the
|
||
floating point types are allowed. For example, ‘<code>typeset -F SECONDS</code>’
|
||
causes the value to be reported as a floating point number. The value is
|
||
available to microsecond accuracy, although the shell may show more or
|
||
fewer digits depending on the use of <code>typeset</code>. See the documentation
|
||
for the builtin <code>typeset</code> in <a href="Shell-Builtin-Commands.html#Shell-Builtin-Commands">Shell Builtin
|
||
Commands</a> for more
|
||
details.</p>
|
||
<p><span id="index-SHLVL"></span></p>
|
||
<p><code>SHLVL</code> <S></p>
|
||
<p>Incremented by one each time a new shell is started.</p>
|
||
<p><span id="index-signals"></span></p>
|
||
<p><code>signals</code></p>
|
||
<p>An array containing the names of the signals. Note that with the
|
||
standard zsh numbering of array indices, where the first element has
|
||
index 1, the signals are offset by 1 from the signal number used by the
|
||
operating system. For example, on typical Unix-like systems <code>HUP</code> is
|
||
signal number 1, but is referred to as <code>$signals[2]</code>. This is because of
|
||
<code>EXIT</code> at position 1 in the array, which is used internally by zsh but
|
||
is not known to the operating system.</p>
|
||
<p><span id="index-TRY_005fBLOCK_005fERROR"></span></p>
|
||
<p><code>TRY_BLOCK_ERROR</code> <S></p>
|
||
<p>In an <code>always</code> block, indicates whether the preceding list of code
|
||
caused an error. The value is 1 to indicate an error, 0 otherwise. It
|
||
may be reset, clearing the error condition. See <a href="Shell-Grammar.html#Complex-Commands">Complex
|
||
Commands</a></p>
|
||
<p><span id="index-TRY_005fBLOCK_005fINTERRUPT"></span></p>
|
||
<p><code>TRY_BLOCK_INTERRUPT</code> <S></p>
|
||
<p>This variable works in a similar way to <code>TRY_BLOCK_ERROR</code>, but
|
||
represents the status of an interrupt from the signal SIGINT, which
|
||
typically comes from the keyboard when the user types <code>^C</code>. If set to 0,
|
||
any such interrupt will be reset; otherwise, the interrupt is propagated
|
||
after the <code>always</code> block.</p>
|
||
<p>Note that it is possible that an interrupt arrives during the execution
|
||
of the <code>always</code> block; this interrupt is also propagated.</p>
|
||
<p><span id="index-TTY"></span></p>
|
||
<p><code>TTY</code></p>
|
||
<p>The name of the tty associated with the shell, if any.</p>
|
||
<p><span id="index-TTYIDLE"></span></p>
|
||
<p><code>TTYIDLE</code> <S></p>
|
||
<p>The idle time of the tty associated with the shell in seconds or -1 if
|
||
there is no such tty.</p>
|
||
<p><span id="index-UID"></span></p>
|
||
<p><code>UID</code> <S></p>
|
||
<p>The real user ID of the shell process. If you have sufficient
|
||
privileges, you may change the user ID of the shell by assigning to this
|
||
parameter. Also (assuming sufficient privileges), you may start a single
|
||
command under a different user ID by ‘<code>(UID=``uid``; command)</code>’</p>
|
||
<p>If this is made local, it is not implicitly set to 0, but may be
|
||
explicitly set locally.</p>
|
||
<p><span id="index-USERNAME"></span></p>
|
||
<p><code>USERNAME</code> <S></p>
|
||
<p>The username corresponding to the real user ID of the shell process. If
|
||
you have sufficient privileges, you may change the username (and also
|
||
the user ID and group ID) of the shell by assigning to this parameter.
|
||
Also (assuming sufficient privileges), you may start a single command
|
||
under a different username (and user ID and group ID) by
|
||
‘<code>(USERNAME=``username``; command)</code>’</p>
|
||
<p><span id="index-VENDOR"></span></p>
|
||
<p><code>VENDOR</code></p>
|
||
<p>The vendor, as determined at compile time.</p>
|
||
<p><span id="index-zsh_005feval_005fcontext"></span>
|
||
<span id="index-ZSH_005fEVAL_005fCONTEXT"></span></p>
|
||
<p><code>zsh_eval_context</code> <S> <Z> (<code>ZSH_EVAL_CONTEXT</code> <S>)</p>
|
||
<p>An array (colon-separated list) indicating the context of shell code
|
||
that is being run. Each time a piece of shell code that is stored within
|
||
the shell is executed a string is temporarily appended to the array to
|
||
indicate the type of operation that is being performed. Read in order
|
||
the array gives an indication of the stack of operations being performed
|
||
with the most immediate context last.</p>
|
||
<p>Note that the variable does not give information on syntactic context
|
||
such as pipelines or subshells. Use <code>$ZSH_SUBSHELL</code> to detect subshells.</p>
|
||
<p>The context is one of the following:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>cmdarg</code><br />
|
||
Code specified by the <code>-c</code> option to the command line that invoked
|
||
the shell.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>cmdsubst</code><br />
|
||
Command substitution using the <code>‘``...``‘</code> or <code>$(``...``)</code>
|
||
construct.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>equalsubst</code><br />
|
||
File substitution using the <code>=(``...``)</code> construct.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>eval</code><br />
|
||
Code executed by the <code>eval</code> builtin.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>evalautofunc</code><br />
|
||
Code executed with the <code>KSH_AUTOLOAD</code> mechanism in order to define
|
||
an autoloaded function.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>fc</code><br />
|
||
Code from the shell history executed by the <code>-e</code> option to the <code>fc</code>
|
||
builtin.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>file</code><br />
|
||
Lines of code being read directly from a file, for example by the
|
||
<code>source</code> builtin.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>filecode</code><br />
|
||
Lines of code being read from a <code>.zwc</code> file instead of directly from
|
||
the source file.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>globqual</code><br />
|
||
Code executed by the <code>e</code> or <code>+</code> glob qualifier.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>globsort</code><br />
|
||
Code executed to order files by the <code>o</code> glob qualifier.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>insubst</code><br />
|
||
File substitution using the <code><(``...``)</code> construct.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>loadautofunc</code><br />
|
||
Code read directly from a file to define an autoloaded function.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>outsubst</code><br />
|
||
File substitution using the <code>>(``...``)</code> construct.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>sched</code><br />
|
||
Code executed by the <code>sched</code> builtin.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>shfunc</code><br />
|
||
A shell function.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>stty</code><br />
|
||
Code passed to <code>stty</code> by the <code>STTY</code> environment variable. Normally
|
||
this is passed directly to the system’s <code>stty</code> command, so this
|
||
value is unlikely to be seen in practice.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>style</code><br />
|
||
Code executed as part of a style retrieved by the <code>zstyle</code> builtin
|
||
from the <code>zsh/zutil</code> module.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>toplevel</code><br />
|
||
The highest execution level of a script or interactive shell.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>trap</code><br />
|
||
Code executed as a trap defined by the <code>trap</code> builtin. Traps defined
|
||
as functions have the context <code>shfunc</code>. As traps are asynchronous
|
||
they may have a different hierarchy from other code.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zpty</code><br />
|
||
Code executed by the <code>zpty</code> builtin from the <code>zsh/zpty</code> module.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zregexparse-guard</code><br />
|
||
Code executed as a guard by the <code>zregexparse</code> command from the
|
||
<code>zsh/zutil</code> module.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zregexparse-action</code><br />
|
||
Code executed as an action by the <code>zregexparse</code> command from the
|
||
<code>zsh/zutil</code> module.</p>
|
||
</li>
|
||
</ul>
|
||
<p><span id="index-ZSH_005fARGZERO"></span></p>
|
||
<p><code>ZSH_ARGZERO</code></p>
|
||
<p>If zsh was invoked to run a script, this is the name of the script.
|
||
Otherwise, it is the name used to invoke the current shell. This is the
|
||
same as the value of <code>$0</code> when the <code>POSIX_ARGZERO</code> option is set, but is
|
||
always available.</p>
|
||
<p><span id="index-ZSH_005fEXECUTION_005fSTRING"></span></p>
|
||
<p><code>ZSH_EXECUTION_STRING</code></p>
|
||
<p>If the shell was started with the option <code>-c</code>, this contains the
|
||
argument passed to the option. Otherwise it is not set.</p>
|
||
<p><span id="index-ZSH_005fNAME"></span></p>
|
||
<p><code>ZSH_NAME</code></p>
|
||
<p>Expands to the basename of the command used to invoke this instance of
|
||
zsh.</p>
|
||
<p><span id="index-ZSH_005fPATCHLEVEL"></span></p>
|
||
<p><code>ZSH_PATCHLEVEL</code></p>
|
||
<p>The output of ‘<code>git describe –tags –long</code>’ for the zsh repository used
|
||
to build the shell. This is most useful in order to keep track of
|
||
versions of the shell during development between releases; hence most
|
||
users should not use it and should instead rely on <code>$ZSH_VERSION</code>.</p>
|
||
<p><code>zsh_scheduled_events</code></p>
|
||
<p>See <a href="Zsh-Modules.html#The-zsh_002fsched-Module">The zsh/sched Module</a>.</p>
|
||
<p><span id="index-ZSH_005fSCRIPT"></span></p>
|
||
<p><code>ZSH_SCRIPT</code></p>
|
||
<p>If zsh was invoked to run a script, this is the name of the script,
|
||
otherwise it is unset.</p>
|
||
<p><span id="index-ZSH_005fSUBSHELL-_003cS_003e"></span></p>
|
||
<p><code>ZSH_SUBSHELL</code></p>
|
||
<p>Readonly integer. Initially zero, incremented each time the shell forks
|
||
to create a subshell for executing code. Hence ‘<code>(print $ZSH_SUBSHELL)</code>’
|
||
and ‘<code>print $(print $ZSH_SUBSHELL)</code>’ output 1, while ‘<code>( (print $ZSH_SUBSHELL) )</code>’ outputs 2.</p>
|
||
<p><span id="index-ZSH_005fVERSION"></span></p>
|
||
<p><code>ZSH_VERSION</code></p>
|
||
<p>The version number of the release of zsh.</p>
|
||
<hr />
|
||
<p><span id="Parameters-Used-By-The-Shell"></span>
|
||
<span id="Parameters-Used-By-The-Shell-1"></span></p>
|
||
<h2 id="156-parameters-used-by-the-shell"><a class="header" href="#156-parameters-used-by-the-shell">15.6 Parameters Used By The Shell</a></h2>
|
||
<p>The following parameters are used by the shell. Again, ‘<S>’ indicates
|
||
that the parameter is special and ‘<Z>’ indicates that the parameter
|
||
does not exist when the shell initializes in <code>sh</code> or <code>ksh</code> emulation
|
||
mode.</p>
|
||
<p>In cases where there are two parameters with an upper- and lowercase
|
||
form of the same name, such as <code>path</code> and <code>PATH</code>, the lowercase form is
|
||
an array and the uppercase form is a scalar with the elements of the
|
||
array joined together by colons. These are similar to tied parameters
|
||
created via ‘<code>typeset -T</code>’. The normal use for the colon-separated form
|
||
is for exporting to the environment, while the array form is easier to
|
||
manipulate within the shell. Note that unsetting either of the pair will
|
||
unset the other; they retain their special properties when recreated,
|
||
and recreating one of the pair will recreate the other.</p>
|
||
<p><span id="index-ARGV0"></span></p>
|
||
<p><code>ARGV0</code></p>
|
||
<p>If exported, its value is used as the <code>argv[0]</code> of external commands.
|
||
Usually used in constructs like ‘<code>ARGV0=emacs nethack</code>’.</p>
|
||
<p><span id="index-editing-over-slow-connection"></span>
|
||
<span id="index-slow-connection_002c-editing-over"></span>
|
||
<span id="index-BAUD"></span></p>
|
||
<p><code>BAUD</code></p>
|
||
<p>The rate in bits per second at which data reaches the terminal. The line
|
||
editor will use this value in order to compensate for a slow terminal by
|
||
delaying updates to the display until necessary. If the parameter is
|
||
unset or the value is zero the compensation mechanism is turned off. The
|
||
parameter is not set by default.</p>
|
||
<p>This parameter may be profitably set in some circumstances, e.g. for
|
||
slow modems dialing into a communications server, or on a slow wide area
|
||
network. It should be set to the baud rate of the slowest part of the
|
||
link for best performance.</p>
|
||
<p><span id="index-cdpath"></span> <span id="index-CDPATH"></span></p>
|
||
<p><code>cdpath</code> <S> <Z> (<code>CDPATH</code> <S>)</p>
|
||
<p>An array (colon-separated list) of directories specifying the search
|
||
path for the <code>cd</code> command.</p>
|
||
<p><span id="index-COLUMNS"></span></p>
|
||
<p><code>COLUMNS</code> <S></p>
|
||
<p>The number of columns for this terminal session. Used for printing
|
||
select lists and for the line editor.</p>
|
||
<p><span id="index-CORRECT_005fIGNORE"></span></p>
|
||
<p><code>CORRECT_IGNORE</code></p>
|
||
<p>If set, is treated as a pattern during spelling correction. Any
|
||
potential correction that matches the pattern is ignored. For example,
|
||
if the value is ‘<code>_*</code>’ then completion functions (which, by convention,
|
||
have names beginning with ‘<code>_</code>’) will never be offered as spelling
|
||
corrections. The pattern does not apply to the correction of file names,
|
||
as applied by the <code>CORRECT_ALL</code> option (so with the example just given
|
||
files beginning with ‘<code>_</code>’ in the current directory would still be
|
||
completed).</p>
|
||
<p><span id="index-CORRECT_005fIGNORE_005fFILE"></span></p>
|
||
<p><code>CORRECT_IGNORE_FILE</code></p>
|
||
<p>If set, is treated as a pattern during spelling correction of file
|
||
names. Any file name that matches the pattern is never offered as a
|
||
correction. For example, if the value is ‘<code>.*</code>’ then dot file names will
|
||
never be offered as spelling corrections. This is useful with the
|
||
<code>CORRECT_ALL</code> option.</p>
|
||
<p><span id="index-DIRSTACKSIZE"></span></p>
|
||
<p><code>DIRSTACKSIZE</code></p>
|
||
<p>The maximum size of the directory stack, by default there is no limit.
|
||
If the stack gets larger than this, it will be truncated automatically.
|
||
This is useful with the <code>AUTO_PUSHD</code> option.
|
||
<span id="index-AUTO_005fPUSHD_002c-use-of"></span></p>
|
||
<p><span id="index-ENV"></span></p>
|
||
<p><code>ENV</code></p>
|
||
<p>If the <code>ENV</code> environment variable is set when zsh is invoked as <code>sh</code> or
|
||
<code>ksh</code>, <code>$ENV</code> is sourced after the profile scripts. The value of <code>ENV</code>
|
||
is subjected to parameter expansion, command substitution, and
|
||
arithmetic expansion before being interpreted as a pathname. Note that
|
||
<code>ENV</code> is <em>not</em> used unless the shell is interactive and zsh is emulating
|
||
sh or ksh.</p>
|
||
<p><span id="index-FCEDIT"></span></p>
|
||
<p><code>FCEDIT</code></p>
|
||
<p>The default editor for the <code>fc</code> builtin. If <code>FCEDIT</code> is not set, the
|
||
parameter <code>EDITOR</code> is used; if that is not set either, a builtin
|
||
default, usually <code>vi</code>, is used.</p>
|
||
<p><span id="index-fignore"></span> <span id="index-FIGNORE"></span></p>
|
||
<p><code>fignore</code> <S> <Z> (<code>FIGNORE</code> <S>)</p>
|
||
<p>An array (colon separated list) containing the suffixes of files to be
|
||
ignored during filename completion. However, if completion only
|
||
generates files with suffixes in this list, then these files are
|
||
completed anyway.</p>
|
||
<p><span id="index-fpath"></span> <span id="index-FPATH"></span></p>
|
||
<p><code>fpath</code> <S> <Z> (<code>FPATH</code> <S>)</p>
|
||
<p>An array (colon separated list) of directories specifying the search
|
||
path for function definitions. This path is searched when a function
|
||
file is found, then it is read and executed in the current environment.</p>
|
||
<p><span id="index-histchars"></span></p>
|
||
<p><code>histchars</code> <S></p>
|
||
<p>Three characters used by the shell’s history and lexical analysis
|
||
mechanism. The first character signals the start of a history expansion
|
||
(default ‘<code>!</code>’). The second character signals the start of a quick
|
||
history substitution (default ‘<code>^</code>’). The third character is the comment
|
||
character (default ‘<code>#</code>’).</p>
|
||
<p>The characters must be in the ASCII character set; any attempt to set
|
||
<code>histchars</code> to characters with a locale-dependent meaning will be
|
||
rejected with an error message.</p>
|
||
<p><span id="index-HISTCHARS"></span></p>
|
||
<p><code>HISTCHARS</code> <S> <Z></p>
|
||
<p>Same as <code>histchars</code>. (Deprecated.)</p>
|
||
<p><span id="index-HISTFILE"></span></p>
|
||
<p><code>HISTFILE</code></p>
|
||
<p>The file to save the history in when an interactive shell exits. If
|
||
unset, the history is not saved.</p>
|
||
<p><span id="index-HISTORY_005fIGNORE"></span></p>
|
||
<p><code>HISTORY_IGNORE</code></p>
|
||
<p>If set, is treated as a pattern at the time history files are written.
|
||
Any potential history entry that matches the pattern is skipped. For
|
||
example, if the value is ‘<code>fc *</code>’ then commands that invoke the
|
||
interactive history editor are never written to the history file.</p>
|
||
<p>Note that <code>HISTORY_IGNORE</code> defines a single pattern: to specify
|
||
alternatives use the ‘<code>(``first``|``second``|``...``)</code>’ syntax.</p>
|
||
<p>Compare the <code>HIST_NO_STORE</code> option or the <code>zshaddhistory</code> hook, either
|
||
of which would prevent such commands from being added to the interactive
|
||
history at all. If you wish to use <code>HISTORY_IGNORE</code> to stop history
|
||
being added in the first place, you can define the following hook:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zshaddhistory() {
|
||
emulate -L zsh
|
||
## uncomment if HISTORY_IGNORE
|
||
## should use EXTENDED_GLOB syntax
|
||
# setopt extendedglob
|
||
[[ $1 != ${~HISTORY_IGNORE} ]]
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-HISTSIZE"></span></p>
|
||
<p><code>HISTSIZE</code> <S></p>
|
||
<p>The maximum number of events stored in the internal history list. If you
|
||
use the <code>HIST_EXPIRE_DUPS_FIRST</code> option, setting this value larger than
|
||
the <code>SAVEHIST</code> size will give you the difference as a cushion for saving
|
||
duplicated history events.</p>
|
||
<p>If this is made local, it is not implicitly set to 0, but may be
|
||
explicitly set locally.</p>
|
||
<p><span id="index-HOME"></span></p>
|
||
<p><code>HOME</code> <S></p>
|
||
<p>The default argument for the <code>cd</code> command. This is not set automatically
|
||
by the shell in <code>sh</code>, <code>ksh</code> or <code>csh</code> emulation, but it is typically
|
||
present in the environment anyway, and if it becomes set it has its
|
||
usual special behaviour.</p>
|
||
<p><span id="index-IFS"></span></p>
|
||
<p><code>IFS</code> <S></p>
|
||
<p>Internal field separators (by default space, tab, newline and NUL), that
|
||
are used to separate words which result from command or parameter
|
||
expansion and words read by the <code>read</code> builtin. Any characters from the
|
||
set space, tab and newline that appear in the IFS are called <em>IFS white
|
||
space</em>. One or more IFS white space characters or one non-IFS white
|
||
space character together with any adjacent IFS white space character
|
||
delimit a field. If an IFS white space character appears twice
|
||
consecutively in the IFS, this character is treated as if it were not an
|
||
IFS white space character.</p>
|
||
<p>If the parameter is unset, the default is used. Note this has a
|
||
different effect from setting the parameter to an empty string.</p>
|
||
<p><span id="index-KEYBOARD_005fHACK"></span></p>
|
||
<p><code>KEYBOARD_HACK</code></p>
|
||
<p>This variable defines a character to be removed from the end of the
|
||
command line before interpreting it (interactive shells only). It is
|
||
intended to fix the problem with keys placed annoyingly close to return
|
||
and replaces the <code>SUNKEYBOARDHACK</code> option which did this for backquotes
|
||
only. Should the chosen character be one of singlequote, doublequote or
|
||
backquote, there must also be an odd number of them on the command line
|
||
for the last one to be removed.</p>
|
||
<p>For backward compatibility, if the <code>SUNKEYBOARDHACK</code> option is
|
||
explicitly set, the value of <code>KEYBOARD_HACK</code> reverts to backquote. If
|
||
the option is explicitly unset, this variable is set to empty.</p>
|
||
<p><span id="index-KEYTIMEOUT"></span></p>
|
||
<p><code>KEYTIMEOUT</code></p>
|
||
<p>The time the shell waits, in hundredths of seconds, for another key to
|
||
be pressed when reading bound multi-character sequences.</p>
|
||
<p><span id="index-LANG"></span></p>
|
||
<p><code>LANG</code> <S></p>
|
||
<p>This variable determines the locale category for any category not
|
||
specifically selected via a variable starting with ‘<code>LC_</code>’.</p>
|
||
<p><span id="index-LC_005fALL"></span></p>
|
||
<p><code>LC_ALL</code> <S></p>
|
||
<p>This variable overrides the value of the ‘<code>LANG</code>’ variable and the value
|
||
of any of the other variables starting with ‘<code>LC_</code>’.</p>
|
||
<p><span id="index-LC_005fCOLLATE"></span></p>
|
||
<p><code>LC_COLLATE</code> <S></p>
|
||
<p>This variable determines the locale category for character collation
|
||
information within ranges in glob brackets and for sorting.</p>
|
||
<p><span id="index-LC_005fCTYPE"></span></p>
|
||
<p><code>LC_CTYPE</code> <S></p>
|
||
<p>This variable determines the locale category for character handling
|
||
functions. If the <code>MULTIBYTE</code> option is in effect this variable or
|
||
<code>LANG</code> should contain a value that reflects the character set in use,
|
||
even if it is a single-byte character set, unless only the 7-bit subset
|
||
(ASCII) is used. For example, if the character set Linux distributions)
|
||
or <code>en_US.ISO8859-1</code> (MacOS).</p>
|
||
<p><span id="index-LC_005fMESSAGES"></span></p>
|
||
<p><code>LC_MESSAGES</code> <S></p>
|
||
<p>This variable determines the language in which messages should be
|
||
written. Note that zsh does not use message catalogs.</p>
|
||
<p><span id="index-LC_005fNUMERIC"></span></p>
|
||
<p><code>LC_NUMERIC</code> <S></p>
|
||
<p>This variable affects the decimal point character and thousands
|
||
separator character for the formatted input/output functions and string
|
||
conversion functions. Note that zsh ignores this setting when parsing
|
||
floating point mathematical expressions.</p>
|
||
<p><span id="index-LC_005fTIME"></span></p>
|
||
<p><code>LC_TIME</code> <S></p>
|
||
<p>This variable determines the locale category for date and time
|
||
formatting in prompt escape sequences.</p>
|
||
<p><span id="index-LINES"></span></p>
|
||
<p><code>LINES</code> <S></p>
|
||
<p>The number of lines for this terminal session. Used for printing select
|
||
lists and for the line editor.</p>
|
||
<p><span id="index-LISTMAX"></span></p>
|
||
<p><code>LISTMAX</code></p>
|
||
<p>In the line editor, the number of matches to list without asking most as
|
||
many lines as given by the absolute value. If set to zero, the shell
|
||
asks only if the top of the listing would scroll off the screen.</p>
|
||
<p><span id="index-LOGCHECK"></span></p>
|
||
<p><code>LOGCHECK</code></p>
|
||
<p>The interval in seconds between checks for login/logout activity using
|
||
the <code>watch</code> parameter.</p>
|
||
<p><span id="index-MAIL"></span></p>
|
||
<p><code>MAIL</code></p>
|
||
<p>If this parameter is set and <code>mailpath</code> is not set, the shell looks for
|
||
mail in the specified file.</p>
|
||
<p><span id="index-MAILCHECK"></span></p>
|
||
<p><code>MAILCHECK</code></p>
|
||
<p>The interval in seconds between checks for new mail.</p>
|
||
<p><span id="index-mailpath"></span> <span id="index-MAILPATH"></span></p>
|
||
<p><code>mailpath</code> <S> <Z> (<code>MAILPATH</code> <S>)</p>
|
||
<p>An array (colon-separated list) of filenames to check for new mail. Each
|
||
filename can be followed by a ‘<code>?</code>’ and a message that will be printed.
|
||
The message will undergo parameter expansion, command substitution and
|
||
arithmetic expansion with the variable <code>$_</code> defined as the name of the
|
||
file that has changed. The default message is ‘<code>You have new mail</code>’. If
|
||
an element is a directory instead of a file the shell will recursively
|
||
check every file in every subdirectory of the element.</p>
|
||
<p><span id="index-manpath"></span> <span id="index-MANPATH"></span></p>
|
||
<p><code>manpath</code> <S> <Z> (<code>MANPATH</code> <S> <Z>)</p>
|
||
<p>An array (colon-separated list) whose value is not used by the shell.
|
||
The <code>manpath</code> array can be useful, however, since setting it also sets
|
||
<code>MANPATH</code>, and vice versa.</p>
|
||
<p><code>match</code></p>
|
||
<p><code>mbegin</code></p>
|
||
<p><code>mend</code></p>
|
||
<p>Arrays set by the shell when the <code>b</code> globbing flag is used in pattern
|
||
matches. See the subsection <em>Globbing flags</em> in <a href="Expansion.html#Filename-Generation">Filename
|
||
Generation</a>.</p>
|
||
<p><code>MATCH</code></p>
|
||
<p><code>MBEGIN</code></p>
|
||
<p><code>MEND</code></p>
|
||
<p>Set by the shell when the <code>m</code> globbing flag is used in pattern matches.
|
||
See the subsection <em>Globbing flags</em> in <a href="Expansion.html#Filename-Generation">Filename
|
||
Generation</a>.</p>
|
||
<p><span id="index-module_005fpath"></span>
|
||
<span id="index-MODULE_005fPATH"></span></p>
|
||
<p><code>module_path</code> <S> <Z> (<code>MODULE_PATH</code> <S>)</p>
|
||
<p>An array (colon-separated list) of directories that <code>zmodload</code> searches
|
||
for dynamically loadable modules. This is initialized to a standard
|
||
pathname, usually ‘<code>/usr/local/lib/zsh/$ZSH_VERSION</code>’. (The
|
||
‘<code>/usr/local/lib</code>’ part varies from installation to installation.) For
|
||
security reasons, any value set in the environment when the shell is
|
||
started will be ignored.</p>
|
||
<p>These parameters only exist if the installation supports dynamic module
|
||
loading.</p>
|
||
<p><span id="index-NULLCMD"></span>
|
||
<span id="index-null-command-style"></span>
|
||
<span id="index-csh_002c-null-command-style"></span>
|
||
<span id="index-ksh_002c-null-command-style"></span></p>
|
||
<p><code>NULLCMD</code> <S></p>
|
||
<p>The command name to assume if a redirection is specified with no
|
||
command. Defaults to <code>cat</code>. For sh/ksh behavior, change this to <code>:</code>. For
|
||
csh-like behavior, unset this parameter; the shell will print an error
|
||
message if null commands are entered.</p>
|
||
<p><span id="index-path"></span> <span id="index-PATH"></span></p>
|
||
<p><code>path</code> <S> <Z> (<code>PATH</code> <S>)</p>
|
||
<p>An array (colon-separated list) of directories to search for commands.
|
||
When this parameter is set, each directory is scanned</p>
|
||
<p><span id="index-POSTEDIT"></span></p>
|
||
<p><code>POSTEDIT</code> <S></p>
|
||
<p>This string is output whenever the line editor exits. It usually
|
||
contains termcap strings to reset the terminal.</p>
|
||
<p><span id="index-PROMPT"></span></p>
|
||
<p><code>PROMPT</code> <S> <Z></p>
|
||
<p><span id="index-PROMPT2"></span></p>
|
||
<p><code>PROMPT2</code> <S> <Z></p>
|
||
<p><span id="index-PROMPT3"></span></p>
|
||
<p><code>PROMPT3</code> <S> <Z></p>
|
||
<p><span id="index-PROMPT4"></span></p>
|
||
<p><code>PROMPT4</code> <S> <Z></p>
|
||
<p>Same as <code>PS1</code>, <code>PS2</code>, <code>PS3</code> and <code>PS4</code>, respectively.</p>
|
||
<p><span id="index-prompt"></span></p>
|
||
<p><code>prompt</code> <S> <Z></p>
|
||
<p>Same as <code>PS1</code>.</p>
|
||
<p><span id="index-PROMPT_005fEOL_005fMARK"></span></p>
|
||
<p><code>PROMPT_EOL_MARK</code></p>
|
||
<p>When the <code>PROMPT_CR</code> and <code>PROMPT_SP</code> options are set, the
|
||
<code>PROMPT_EOL_MARK</code> parameter can be used to customize how the end of
|
||
partial lines are shown. This parameter undergoes prompt expansion, with
|
||
the <code>PROMPT_PERCENT</code> option set. If not set, the default behavior is
|
||
equivalent to the value ‘<code>%B%S%#%s%b</code>’.</p>
|
||
<p><span id="index-PS1"></span></p>
|
||
<p><code>PS1</code> <S></p>
|
||
<p>The primary prompt string, printed before a command is read. It
|
||
undergoes a special form of expansion before being displayed; see
|
||
<a href="Prompt-Expansion.html#Prompt-Expansion">Prompt Expansion</a>. The default
|
||
is ‘<code>%m%# </code>’.</p>
|
||
<p><span id="index-PS2"></span></p>
|
||
<p><code>PS2</code> <S></p>
|
||
<p>The secondary prompt, printed when the shell needs more information to
|
||
complete a command. It is expanded in the same way as <code>PS1</code>. The default
|
||
is ‘<code>%_> </code>’, which displays any shell constructs or quotation marks
|
||
which are currently being processed.</p>
|
||
<p><span id="index-PS3"></span></p>
|
||
<p><code>PS3</code> <S></p>
|
||
<p>Selection prompt used within a <code>select</code> loop. It is expanded in the same
|
||
way as <code>PS1</code>. The default is ‘<code>?# </code>’.</p>
|
||
<p><span id="index-PS4"></span></p>
|
||
<p><code>PS4</code> <S></p>
|
||
<p>The execution trace prompt. Default is ‘<code>+%N:%i> </code>’, which displays
|
||
the name of the current shell structure and the line number within it.
|
||
In sh or ksh emulation, the default is ‘<code>+ </code>’.</p>
|
||
<p><span id="index-psvar"></span> <span id="index-PSVAR"></span></p>
|
||
<p><code>psvar</code> <S> <Z> (<code>PSVAR</code> <S>)</p>
|
||
<p>An array (colon-separated list) whose elements can be used in <code>PROMPT</code>
|
||
strings. Setting <code>psvar</code> also sets <code>PSVAR</code>, and vice versa.</p>
|
||
<p><span id="index-READNULLCMD"></span></p>
|
||
<p><code>READNULLCMD</code> <S></p>
|
||
<p>The command name to assume if a single input redirection is specified
|
||
with no command. Defaults to <code>more</code>.</p>
|
||
<p><span id="index-REPORTMEMORY"></span></p>
|
||
<p><code>REPORTMEMORY</code></p>
|
||
<p>If nonnegative, commands whose maximum resident set size (roughly
|
||
speaking, main memory usage) in kilobytes is greater than this value
|
||
have timing statistics reported. The format used to output statistics is
|
||
the value of the <code>TIMEFMT</code> parameter, which is the same as for the
|
||
<code>REPORTTIME</code> variable and the <code>time</code> builtin; note that by default this
|
||
does not output memory usage. Appending <code>" max RSS %M"</code> to the value of
|
||
<code>TIMEFMT</code> causes it to output the value that triggered the report. If
|
||
<code>REPORTTIME</code> is also in use, at most a single report is printed for both
|
||
triggers. This feature requires the <code>getrusage()</code> system call, commonly
|
||
supported by modern Unix-like systems.</p>
|
||
<p><span id="index-REPORTTIME"></span></p>
|
||
<p><code>REPORTTIME</code></p>
|
||
<p>If nonnegative, commands whose combined user and system execution times
|
||
(measured in seconds) are greater than this value have timing statistics
|
||
printed for them. Output is suppressed for commands executed within the
|
||
line editor, including completion; commands explicitly marked with the
|
||
<code>time</code> keyword still cause the summary to be printed in this case.</p>
|
||
<p><span id="index-REPLY"></span></p>
|
||
<p><code>REPLY</code></p>
|
||
<p>This parameter is reserved by convention to pass string values between
|
||
shell scripts and shell builtins in situations where a function call or
|
||
redirection are impossible or undesirable. The <code>read</code> builtin and the
|
||
<code>select</code> complex command may set <code>REPLY</code>, and filename generation both
|
||
sets and examines its value when evaluating certain expressions. Some
|
||
modules also employ <code>REPLY</code> for similar purposes.</p>
|
||
<p><span id="index-reply"></span></p>
|
||
<p><code>reply</code></p>
|
||
<p>As <code>REPLY</code>, but for array values rather than strings.</p>
|
||
<p><span id="index-RPROMPT"></span></p>
|
||
<p><code>RPROMPT</code> <S></p>
|
||
<p><span id="index-RPS1"></span></p>
|
||
<p><code>RPS1</code> <S></p>
|
||
<p>This prompt is displayed on the right-hand side of the screen when the
|
||
primary prompt is being displayed on the left. This does not work if the
|
||
<code>SINGLE_LINE_ZLE</code> option is set. It is expanded in the same way as
|
||
<code>PS1</code>.</p>
|
||
<p><span id="index-RPROMPT2"></span></p>
|
||
<p><code>RPROMPT2</code> <S></p>
|
||
<p><span id="index-RPS2"></span></p>
|
||
<p><code>RPS2</code> <S></p>
|
||
<p>This prompt is displayed on the right-hand side of the screen when the
|
||
secondary prompt is being displayed on the left. This does not work if
|
||
the <code>SINGLE_LINE_ZLE</code> option is set. It is expanded in the same way as
|
||
<code>PS2</code>.</p>
|
||
<p><span id="index-SAVEHIST"></span></p>
|
||
<p><code>SAVEHIST</code></p>
|
||
<p>The maximum number of history events to save in the history file.</p>
|
||
<p>If this is made local, it is not implicitly set to 0, but may be
|
||
explicitly set locally.</p>
|
||
<p><span id="index-SPROMPT"></span></p>
|
||
<p><code>SPROMPT</code> <S></p>
|
||
<p>The prompt used for spelling correction. The sequence ‘<code>%R</code>’ expands to
|
||
the string which presumably needs spelling correction, and ‘<code>%r</code>’
|
||
expands to the proposed correction. All other prompt escapes are also
|
||
allowed.</p>
|
||
<p>The actions available at the prompt are <code>[nyae]</code>:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>n</code> (‘no’) (default)<br />
|
||
Discard the correction and run the command.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>y</code> (‘yes’)<br />
|
||
Make the correction and run the command.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>a</code> (‘abort’)<br />
|
||
Discard the entire command line without running it.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>e</code> (‘edit’)<br />
|
||
Resume editing the command line.</p>
|
||
</li>
|
||
</ul>
|
||
<p><span id="index-STTY"></span></p>
|
||
<p><code>STTY</code></p>
|
||
<p>If this parameter is set in a command’s environment, the shell runs the
|
||
<code>stty</code> command with the value of this parameter as arguments in order to
|
||
set up the terminal before executing the command. The modes apply only
|
||
to the command, and are reset when it finishes or is suspended. If the
|
||
command is suspended and continued later with the <code>fg</code> or <code>wait</code>
|
||
builtins it will see the modes specified by <code>STTY</code>, as if it were not
|
||
suspended. This (intentionally) does not apply if the command is
|
||
continued via ‘<code>kill -CONT</code>’. <code>STTY</code> is ignored if the command is run in
|
||
the background, or if it is in the environment of the shell but not
|
||
explicitly assigned to in the input line. This avoids running stty at
|
||
every external command by accidentally exporting it. Also note that
|
||
<code>STTY</code> should not be used for window size specifications; these will not
|
||
be local to the command.</p>
|
||
<p><span id="index-TERM"></span></p>
|
||
<p><code>TERM</code> <S></p>
|
||
<p>The type of terminal in use. This is used when looking up termcap
|
||
sequences. An assignment to <code>TERM</code> causes zsh to re-initialize the
|
||
terminal, even if the value does not change (e.g., ‘<code>TERM=$TERM</code>’). It
|
||
is necessary to make such an assignment upon any change to the terminal
|
||
definition database or terminal type in order for the new settings to
|
||
take effect.</p>
|
||
<p><span id="index-TERMINFO"></span></p>
|
||
<p><code>TERMINFO</code> <S></p>
|
||
<p>A reference to your terminfo database, used by the ‘terminfo’ library
|
||
when the system has it; see man page terminfo(5). If set, this causes
|
||
the shell to reinitialise the terminal, making the workaround
|
||
‘<code>TERM=$TERM</code>’ unnecessary.</p>
|
||
<p><span id="index-TERMINFO_005fDIRS"></span></p>
|
||
<p><code>TERMINFO_DIRS</code> <S></p>
|
||
<p>A colon-seprarated list of terminfo databases, used by the ‘terminfo’
|
||
library when the system has it; see man page terminfo(5). This variable
|
||
is only used by certain terminal libraries, in particular ncurses; see
|
||
man page terminfo(5) to check support on your system. If set, this
|
||
causes the shell to reinitialise the terminal, making the workaround
|
||
‘<code>TERM=$TERM</code>’ unnecessary. Note that unlike other colon-separated
|
||
arrays this is not tied to a zsh array.</p>
|
||
<p><span id="index-TIMEFMT"></span></p>
|
||
<p><code>TIMEFMT</code></p>
|
||
<p>The format of process time reports with the <code>time</code> keyword. The default
|
||
is ‘<code>%J %U user %S system %P cpu %*E total</code>’. Recognizes the following
|
||
escape sequences, although not all may be available on all systems, and
|
||
some that are available may not be useful:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>%%</code><br />
|
||
A ‘<code>%</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%U</code><br />
|
||
CPU seconds spent in user mode.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%S</code><br />
|
||
CPU seconds spent in kernel mode.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%E</code><br />
|
||
Elapsed time in seconds.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%P</code><br />
|
||
The CPU percentage, computed as 100*(<code>%U</code>+<code>%S</code>)/<code>%E</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%W</code><br />
|
||
Number of times the process was swapped.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%X</code><br />
|
||
The average amount in (shared) text space used in kilobytes.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%D</code><br />
|
||
The average amount in (unshared) data/stack space used in kilobytes.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%K</code><br />
|
||
The total space used (<code>%X</code>+<code>%D</code>) in kilobytes.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%M</code><br />
|
||
The maximum memory the process had in use at any time in kilobytes.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%F</code><br />
|
||
The number of major page faults (page needed to be brought from
|
||
disk).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%R</code><br />
|
||
The number of minor page faults.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%I</code><br />
|
||
The number of input operations.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%O</code><br />
|
||
The number of output operations.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%r</code><br />
|
||
The number of socket messages received.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%s</code><br />
|
||
The number of socket messages sent.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%k</code><br />
|
||
The number of signals received.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%w</code><br />
|
||
Number of voluntary context switches (waits).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%c</code><br />
|
||
Number of involuntary context switches.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%J</code><br />
|
||
The name of this job.</p>
|
||
</li>
|
||
</ul>
|
||
<p>A star may be inserted between the percent sign and flags printing time
|
||
(e.g., ‘<code>%*E</code>’); this causes the time to be printed in
|
||
‘<code>hh``:``mm``:``ss``.``ttt</code>’ format (hours and minutes are only
|
||
printed if they are not zero). Alternatively, ‘<code>m</code>’ or ‘<code>u</code>’ may be used
|
||
(e.g., ‘<code>%mE</code>’) to produce time output in milliseconds or microseconds,
|
||
respectively.</p>
|
||
<p><span id="index-TMOUT"></span></p>
|
||
<p><code>TMOUT</code></p>
|
||
<p>If this parameter is nonzero, the shell will receive an <code>ALRM</code> signal if
|
||
a command is not entered within the specified number of seconds after
|
||
issuing a prompt. If there is a trap on <code>SIGALRM</code>, it will be executed
|
||
and a new alarm is scheduled using the value of the <code>TMOUT</code> parameter
|
||
after executing the trap. If no trap is set, and the idle time of the
|
||
terminal is not less than the value of the <code>TMOUT</code> parameter, zsh
|
||
terminates. Otherwise a new alarm is scheduled to <code>TMOUT</code> seconds after
|
||
the last keypress.</p>
|
||
<p><span id="index-TMPPREFIX"></span></p>
|
||
<p><code>TMPPREFIX</code></p>
|
||
<p>A pathname prefix which the shell will use for all temporary files. Note
|
||
that this should include an initial part for the file name as well as
|
||
any directory names. The default is ‘<code>/tmp/zsh</code>’.</p>
|
||
<p><span id="index-TMPSUFFIX"></span></p>
|
||
<p><code>TMPSUFFIX</code></p>
|
||
<p>A filename suffix which the shell will use for temporary files created
|
||
by process substitutions (e.g., ‘<code>=(list)</code>’). Note that the value should
|
||
include a leading dot ‘<code>.</code>’ if intended to be interpreted as a file
|
||
extension. The default is not to append any suffix, thus this parameter
|
||
should be assigned only when needed and then unset again.</p>
|
||
<p><span id="index-watch"></span> <span id="index-WATCH"></span></p>
|
||
<p><code>watch</code> <S> <Z> (<code>WATCH</code> <S>)</p>
|
||
<p>An array (colon-separated list) of login/logout events to report.</p>
|
||
<p>If it contains the single word ‘<code>all</code>’, then all login/logout events are
|
||
reported. If it contains the single word ‘<code>notme</code>’, then all events are
|
||
reported as with ‘<code>all</code>’ except <code>$USERNAME</code>.</p>
|
||
<p>An entry in this list may consist of a username, an ‘<code>@</code>’ followed by a
|
||
remote hostname, and a ‘<code>%</code>’ followed by a line (tty). Any of these may
|
||
be a pattern (be sure to quote this during the assignment to <code>watch</code> so
|
||
that it does not immediately perform file generation); the setting of
|
||
the <code>EXTENDED_GLOB</code> option is respected. Any or all of these components
|
||
may be present in an entry; if a login/logout event matches all of them,
|
||
it is reported.</p>
|
||
<p>For example, with the <code>EXTENDED_GLOB</code> option set, the following:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">watch=('^(pws|barts)')
|
||
</code></pre>
|
||
</div>
|
||
<p>causes reports for activity associated with any user other than <code>pws</code> or
|
||
<code>barts</code>.</p>
|
||
<p><span id="index-WATCHFMT"></span></p>
|
||
<p><code>WATCHFMT</code></p>
|
||
<p>The format of login/logout reports if the <code>watch</code> parameter is set.
|
||
Default is ‘<code>%n has %a %l from %m</code>’. Recognizes the following escape
|
||
sequences:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>%n</code><br />
|
||
The name of the user that logged in/out.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%a</code><br />
|
||
The observed action, i.e. "logged on" or "logged off".</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%l</code><br />
|
||
The line (tty) the user is logged in on.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%M</code><br />
|
||
The full hostname of the remote host.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%m</code><br />
|
||
The hostname up to the first ‘<code>.</code>’. If only the IP address is
|
||
available or the utmp field contains the name of an X-windows
|
||
display, the whole name is printed.</p>
|
||
<p><em>NOTE:</em> The ‘<code>%m</code>’ and ‘<code>%M</code>’ escapes will work only if there is a
|
||
host name field in the utmp on your machine. Otherwise they are
|
||
treated as ordinary strings.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%S</code> (<code>%s</code>)<br />
|
||
Start (stop) standout mode.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%U</code> (<code>%u</code>)<br />
|
||
Start (stop) underline mode.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%B</code> (<code>%b</code>)<br />
|
||
Start (stop) boldface mode.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%t</code><br />
|
||
<code>%@</code><br />
|
||
The time, in 12-hour, am/pm format.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%T</code><br />
|
||
The time, in 24-hour format.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%w</code><br />
|
||
The date in ‘<code>day``-``dd</code>’ format.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%W</code><br />
|
||
The date in ‘<code>mm``/``dd``/``yy</code>’ format.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%D</code><br />
|
||
The date in ‘<code>yy``-``mm``-``dd</code>’ format.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%D{``string``}</code><br />
|
||
The date formatted as <code>string</code> using the <code>strftime</code> function, with
|
||
zsh extensions as described by <a href="Prompt-Expansion.html#Prompt-Expansion">Prompt
|
||
Expansion</a>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>%(``x``:``true-text``:``false-text``)</code><br />
|
||
Specifies a ternary expression. The character following the <code>x</code> is
|
||
arbitrary; the same character is used to separate the text for the
|
||
"true" result from that for the "false" result. Both the separator
|
||
and the right parenthesis may be escaped with a backslash. Ternary
|
||
expressions may be nested.</p>
|
||
<p>The test character <code>x</code> may be any one of ‘<code>l</code>’, ‘<code>n</code>’, ‘<code>m</code>’ or
|
||
‘<code>M</code>’, which indicate a ‘true’ result if the corresponding
|
||
escape sequence would return a non-empty value; or it may be ‘<code>a</code>’,
|
||
which indicates a ‘true’ result if the watched user has logged in,
|
||
or ‘false’ if he has logged out. Other characters evaluate to
|
||
neither true nor false; the entire expression is omitted in this
|
||
case.</p>
|
||
<p>If the result is ‘true’, then the <code>true-text</code> is formatted according
|
||
to the rules above and printed, and the <code>false-text</code> is skipped. If
|
||
‘false’, the <code>true-text</code> is skipped and the <code>false-text</code> is
|
||
formatted and printed. Either or both of the branches may be empty,
|
||
but both separators must be present in any case.</p>
|
||
</li>
|
||
</ul>
|
||
<p><span id="index-WORDCHARS"></span></p>
|
||
<p><code>WORDCHARS</code> <S></p>
|
||
<p>A list of non-alphanumeric characters considered part of a word by the
|
||
line editor.</p>
|
||
<p><span id="index-ZBEEP"></span></p>
|
||
<p><code>ZBEEP</code></p>
|
||
<p>If set, this gives a string of characters, which can use all the same
|
||
codes as the <code>bindkey</code> command as described in <a href="Zsh-Modules.html#The-zsh_002fzle-Module">The zsh/zle
|
||
Module</a>, that will be output to
|
||
the terminal instead of beeping. This may have a visible instead of an
|
||
audible effect; for example, the string ‘<code>\e[?5h\e[?5l</code>’ on a vt100 or
|
||
xterm will have the effect of flashing reverse video on and off (if you
|
||
usually use reverse video, you should use the string ‘<code>\e[?5l\e[?5h</code>’
|
||
instead). This takes precedence over the <code>NOBEEP</code> option.</p>
|
||
<p><span id="index-ZDOTDIR"></span></p>
|
||
<p><code>ZDOTDIR</code></p>
|
||
<p>The directory to search for shell startup files (.zshrc, etc), if not
|
||
<code>$HOME</code>.</p>
|
||
<p><span id="index-zle_005fbracketed_005fpaste"></span>
|
||
<span id="index-bracketed-paste"></span>
|
||
<span id="index-enabling-bracketed-paste"></span></p>
|
||
<p><code>zle_bracketed_paste</code></p>
|
||
<p>Many terminal emulators have a feature that allows applications to
|
||
identify when text is pasted into the terminal rather than being typed
|
||
normally. For ZLE, this means that special characters such as tabs and
|
||
newlines can be inserted instead of invoking editor commands.
|
||
Furthermore, pasted text forms a single undo event and if the region is
|
||
active, pasted text will replace the region.</p>
|
||
<p>This two-element array contains the terminal escape sequences for
|
||
enabling and disabling the feature. These escape sequences are used to
|
||
enable bracketed paste when ZLE is active and disable it at other times.
|
||
Unsetting the parameter has the effect of ensuring that bracketed paste
|
||
remains disabled.</p>
|
||
<p><span id="index-zle_005fhighlight"></span></p>
|
||
<p><code>zle_highlight</code></p>
|
||
<p>An array describing contexts in which ZLE should highlight the input
|
||
text. See <a href="Zsh-Line-Editor.html#Character-Highlighting">Character
|
||
Highlighting</a>.</p>
|
||
<p><span id="index-ZLE_005fLINE_005fABORTED"></span></p>
|
||
<p><code>ZLE_LINE_ABORTED</code></p>
|
||
<p>This parameter is set by the line editor when an error occurs. It
|
||
contains the line that was being edited at the point of the error.
|
||
‘<code>print -zr – $ZLE_LINE_ABORTED</code>’ can be used to recover the line.
|
||
Only the most recent line of this kind is remembered.</p>
|
||
<p><span id="index-ZLE_005fREMOVE_005fSUFFIX_005fCHARS"></span>
|
||
<span id="index-ZLE_005fSPACE_005fSUFFIX_005fCHARS"></span></p>
|
||
<p><code>ZLE_REMOVE_SUFFIX_CHARS</code></p>
|
||
<p><code>ZLE_SPACE_SUFFIX_CHARS</code></p>
|
||
<p>These parameters are used by the line editor. In certain circumstances
|
||
suffixes (typically space or slash) added by the completion system will
|
||
be removed automatically, either because the next editing command as
|
||
requiring the suffix to be removed.</p>
|
||
<p>These variables can contain the sets of characters that will cause the
|
||
suffix to be removed. If <code>ZLE_REMOVE_SUFFIX_CHARS</code> is set, those
|
||
characters will cause the suffix to be removed; if
|
||
<code>ZLE_SPACE_SUFFIX_CHARS</code> is set, those characters will cause the suffix
|
||
to be removed and replaced by a space.</p>
|
||
<p>If <code>ZLE_REMOVE_SUFFIX_CHARS</code> is not set, the default behaviour is
|
||
equivalent to:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">ZLE_REMOVE_SUFFIX_CHARS=$' \t\n;&|'
|
||
</code></pre>
|
||
</div>
|
||
<p>If <code>ZLE_REMOVE_SUFFIX_CHARS</code> is set but is empty, no characters have
|
||
this behaviour. <code>ZLE_SPACE_SUFFIX_CHARS</code> takes precedence, so that the
|
||
following:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">ZLE_SPACE_SUFFIX_CHARS=$'&|'
|
||
</code></pre>
|
||
</div>
|
||
<p>causes the characters ‘<code>&</code>’ and ‘<code>|</code>’ to remove the suffix but to
|
||
replace it with a space.</p>
|
||
<p>To illustrate the difference, suppose that the option
|
||
<code>AUTO_REMOVE_SLASH</code> is in effect and the directory <code>DIR</code> has just been
|
||
completed, with an appended <code>/</code>, following which the user types ‘<code>&</code>’.
|
||
The default result is ‘<code>DIR&</code>’. With <code>ZLE_REMOVE_SUFFIX_CHARS</code> set but
|
||
without including ‘<code>&</code>’ the result is ‘<code>DIR/&</code>’. With
|
||
<code>ZLE_SPACE_SUFFIX_CHARS</code> set to include ‘<code>&</code>’ the result is ‘<code>DIR &</code>’.</p>
|
||
<p>Note that certain completions may provide their own suffix removal or
|
||
replacement behaviour which overrides the values described here. See the
|
||
completion system documentation in <a href="Completion-System.html#Completion-System">Completion
|
||
System</a>.</p>
|
||
<p><span id="index-ZLE_005fRPROMPT_005fINDENT"></span></p>
|
||
<p><code>ZLE_RPROMPT_INDENT</code> <S></p>
|
||
<p>If set, used to give the indentation between the right hand side of the
|
||
right prompt in the line editor as given by <code>RPS1</code> or <code>RPROMPT</code> and the
|
||
right hand side of the screen. If not set, the value 1 is used.</p>
|
||
<p>Typically this will be used to set the value to 0 so that the prompt
|
||
appears flush with the right hand side of the screen. This is not the
|
||
default as many terminals do not handle this correctly, in particular
|
||
when the prompt appears at the extreme bottom right of the screen.
|
||
Recent virtual terminals are more likely to handle this case correctly.
|
||
Some experimentation is necessary.</p>
|
||
<hr />
|
||
<p>This document was generated on <em>February 15, 2020</em> using
|
||
<a href="http://www.nongnu.org/texi2html/"><em>texi2html 5.0</em></a>.<br />
|
||
Zsh version 5.8, released on February 14, 2020.</p>
|
||
|
||
</main>
|
||
|
||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
<!-- Mobile navigation buttons -->
|
||
|
||
<a rel="prev" href="Expansion.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||
<i class="fa fa-angle-left"></i>
|
||
</a>
|
||
|
||
|
||
|
||
<a rel="next" href="Options.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||
<i class="fa fa-angle-right"></i>
|
||
</a>
|
||
|
||
|
||
<div style="clear: both"></div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
||
|
||
<a rel="prev" href="Expansion.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
||
<i class="fa fa-angle-left"></i>
|
||
</a>
|
||
|
||
|
||
|
||
<a rel="next" href="Options.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||
<i class="fa fa-angle-right"></i>
|
||
</a>
|
||
|
||
</nav>
|
||
|
||
</div>
|
||
|
||
|
||
<!-- Livereload script (if served using the cli tool) -->
|
||
<script type="text/javascript">
|
||
var socket = new WebSocket("ws://localhost:3000/__livereload");
|
||
socket.onmessage = function (event) {
|
||
if (event.data === "reload") {
|
||
socket.close();
|
||
location.reload();
|
||
}
|
||
};
|
||
|
||
window.onbeforeunload = function() {
|
||
socket.close();
|
||
}
|
||
</script>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<script type="text/javascript">
|
||
window.playground_copyable = true;
|
||
</script>
|
||
|
||
|
||
|
||
|
||
|
||
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
|
||
|
||
|
||
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="book.js" type="text/javascript" charset="utf-8"></script>
|
||
|
||
<!-- Custom JS scripts -->
|
||
|
||
|
||
|
||
|
||
</body>
|
||
</html>
|