2654 lines
150 KiB
HTML
2654 lines
150 KiB
HTML
<!DOCTYPE HTML>
|
||
<html lang="en" class="sidebar-visible no-js light">
|
||
<head>
|
||
<!-- Book generated using mdBook -->
|
||
<meta charset="UTF-8">
|
||
<title>Shell Builtin Commands - 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 -->
|
||
<link rel="stylesheet" href="./theme/catppuccin.css">
|
||
<link rel="stylesheet" href="./theme/catppuccin-highlight.css">
|
||
|
||
</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-&-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"><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" class="active"><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>
|
||
<li role="none"><button role="menuitem" class="theme" id="latte">Latte</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="frappe">Frappé</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="macchiato">Macchiato</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="mocha">Mocha</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" 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="#17-shell-builtin-commands">17 Shell Builtin Commands</a></li>
|
||
</ul>
|
||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||
<p><span id="Shell-Builtin-Commands"></span> <span
|
||
id="Shell-Builtin-Commands-1"></span></p>
|
||
<h1 id="17-shell-builtin-commands"><a class="header" href="#17-shell-builtin-commands">17 Shell Builtin Commands</a></h1>
|
||
<p><span id="index-builtin-commands"></span> <span
|
||
id="index-commands_002c-builtin"></span></p>
|
||
<p>Some shell builtin commands take options as described in individual
|
||
entries; these are often referred to in the list below as ‘flags’ to
|
||
avoid confusion with shell options, which may also have an effect on the
|
||
behaviour of builtin commands. In this introductory section, ‘option’
|
||
always has the meaning of an option to a command that should be familiar
|
||
to most command line users.</p>
|
||
<p>Typically, options are single letters preceded by a hyphen (-). Options
|
||
that take an argument accept it either immediately following the option
|
||
letter or after white space, for example ‘print -C3 {1..9}’ or ‘print -C
|
||
3 {1..9}’ are equivalent. Arguments to options are not the same as
|
||
arguments to the command; the documentation indicates which is which.
|
||
Options that do not take an argument may be combined in a single word,
|
||
for example ‘print -rca – *’ and ‘print -r -c -a – *’ are equivalent.</p>
|
||
<p>Some shell builtin commands also take options that begin with ‘+’
|
||
instead of ‘-’. The list below makes clear which commands these are.</p>
|
||
<p>Options (together with their individual arguments, if any) must appear
|
||
in a group before any non-option arguments; once the first non-option
|
||
argument has been found, option processing is terminated.</p>
|
||
<p>All builtin commands other than ‘echo’ and precommand modifiers, even
|
||
those that have no options, can be given the argument ‘--’ to terminate
|
||
option processing. This indicates that the following words are
|
||
non-option arguments, but is otherwise ignored. This is useful in cases
|
||
where arguments to the command may begin with ‘-’. For historical
|
||
reasons, most builtin commands (including ‘echo’) also recognize a
|
||
single ‘-’ in a separate word for this purpose; note that this is less
|
||
standard and use of ‘--’ is recommended.</p>
|
||
<p>- <code>simple command</code><br />
|
||
See <a href="Shell-Grammar.html#Precommand-Modifiers">Precommand Modifiers</a>.</p>
|
||
<p><span id="index-_002e"></span></p>
|
||
<p>. <code>file</code> [ <code>arg</code> ... ]<br />
|
||
Read commands from <code>file</code> and execute them in the current shell
|
||
environment.</p>
|
||
<p>If <code>file</code> does not contain a slash, or if PATH_DIRS is set, the shell
|
||
looks in the components of $path to find the directory containing
|
||
<code>file</code>. Files in the current directory are not read unless ‘.’ appears
|
||
somewhere in $path. If a file named ‘<code>file</code>.zwc’ is found, is newer than
|
||
<code>file</code>, and is the compiled form (created with the zcompile builtin) of
|
||
<code>file</code>, then commands are read from that file instead of <code>file</code>.</p>
|
||
<p>If any arguments <code>arg</code> are given, they become the positional parameters;
|
||
the old positional parameters are restored when the <code>file</code> is done
|
||
executing. However, if no arguments are given, the positional parameters
|
||
remain those of the calling context, and no restoring is done.</p>
|
||
<p>If <code>file</code> was not found the return status is 127; if <code>file</code> was found
|
||
but contained a syntax error the return status is 126; else the return
|
||
status is the exit status of the last command executed.</p>
|
||
<p><span id="index-_003a"></span> <span
|
||
id="index-expanding-parameters"></span> <span
|
||
id="index-parameters_002c-expanding"></span> <span
|
||
id="index-doing-nothing"></span></p>
|
||
<p>: [ <code>arg</code> ... ]<br />
|
||
This command does nothing, although normal argument expansions is
|
||
performed which may have effects on shell parameters. A zero exit status
|
||
is returned.</p>
|
||
<p><span id="index-alias"></span> <span
|
||
id="index-aliases_002c-defining"></span> <span
|
||
id="index-aliases_002c-listing"></span></p>
|
||
<p>alias [ {+|-}gmrsL ] [ <code>name</code>[=<code>value</code>] ... ]<br />
|
||
For each <code>name</code> with a corresponding <code>value</code>, define an alias with that
|
||
value. A trailing space in <code>value</code> causes the next word to be checked
|
||
for alias expansion. If the -g flag is present, define a global alias;
|
||
global aliases are expanded even if they do not occur in command
|
||
position:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">% perldoc --help 2>&1 | grep 'built-in functions'
|
||
-f Search Perl built-in functions
|
||
% alias -g HG='--help 2>&1 | grep'
|
||
% perldoc HG 'built-in functions'
|
||
-f Search Perl built-in functions
|
||
</code></pre>
|
||
</div>
|
||
<p>If the -s flag is present, define a suffix alias: if the command word on
|
||
a command line is in the form ‘<code>text</code>.<code>name</code>’, where <code>text</code> is any
|
||
non-empty string, it is replaced by the text ‘<code>value</code> <code>text</code>.<code>name</code>’.
|
||
Note that <code>name</code> is treated as a literal string, not a pattern. A
|
||
trailing space in <code>value</code> is not special in this case. For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">alias -s ps='gv --'
|
||
</code></pre>
|
||
</div>
|
||
<p>will cause the command ‘*.ps’ to be expanded to ‘gv – *.ps’. As alias
|
||
expansion is carried out earlier than globbing, the ‘*.ps’ will then be
|
||
expanded. Suffix aliases constitute a different name space from other
|
||
aliases (so in the above example it is still possible to create an alias
|
||
for the command ps) and the two sets are never listed together.</p>
|
||
<p>For each <code>name</code> with no <code>value</code>, print the value of <code>name</code>, if any. With
|
||
no arguments, print all currently defined aliases other than suffix
|
||
aliases. If the -m flag is given the arguments are taken as patterns
|
||
(they should be quoted to preserve them from being interpreted as glob
|
||
patterns), and the aliases matching these patterns are printed. When
|
||
printing aliases and one of the -g, -r or -s flags is present, restrict
|
||
the printing to global, regular or suffix aliases, respectively; a
|
||
regular alias is one which is neither a global nor a suffix alias. Using
|
||
‘+’ instead of ‘-’, or ending the option list with a single ‘+’,
|
||
prevents the values of the aliases from being printed.</p>
|
||
<p>If the -L flag is present, then print each status is nonzero if a <code>name</code>
|
||
(with no <code>value</code>) is given for which no alias has been defined.</p>
|
||
<p>For more on aliases, include common problems, see
|
||
<a href="Shell-Grammar.html#Aliasing">Aliasing</a>.</p>
|
||
<p><span id="index-autoload"></span> <span
|
||
id="index-functions_002c-autoloading-1"></span> <span
|
||
id="index-autoloading-functions-1"></span></p>
|
||
<p>autoload [ {+|-}RTUXdkmrtWz ] [ -w ] [ <code>name</code> ... ]<br />
|
||
<span id="index-fpath_002c-searching"></span></p>
|
||
<p>See the section ‘Autoloading Functions’ in
|
||
<a href="Functions.html#Functions">Functions</a> for full details. The fpath
|
||
parameter will be searched to find the function definition when the
|
||
function is first referenced.</p>
|
||
<p>If <code>name</code> consists of an absolute path, the function is defined to load
|
||
from the file given (searching as usual for dump files in the given
|
||
location). The name of the function is the basename (non-directory part)
|
||
of the file. It is normally an error if the function is not found in the
|
||
given location; however, if the option -d is given, searching for the
|
||
function defaults to $fpath. If a function is loaded by absolute path,
|
||
any functions loaded from it that are marked for autoload without an
|
||
absolute path have the load path of the parent function temporarily
|
||
prepended to $fpath.</p>
|
||
<p>If the option -r or -R is given, the function is searched for
|
||
immediately and the location is recorded internally for use when the
|
||
function is executed; a relative path is expanded using the value of
|
||
$PWD. This protects against a change to $fpath after the call to
|
||
autoload. With -r, if the function is not found, it is silently left
|
||
unresolved until execution; with -R, an error message is printed and
|
||
command processing aborted immediately the search fails, i.e. at the
|
||
autoload command rather than at function execution..</p>
|
||
<p>The flag -X may be used only inside a shell function. It causes the
|
||
calling function to be marked for autoloading and then immediately
|
||
loaded and executed, with the current array of positional parameters as
|
||
arguments. This replaces the previous definition of the function. If no
|
||
function definition is found, an error is printed and the function
|
||
remains undefined and marked for autoloading. If an argument is given,
|
||
it is used as a directory (i.e. it does not include the name of the
|
||
function) in which the function is to be found; this may be combined
|
||
with the -d option to allow the function search to default to $fpath if
|
||
it is not in the given location.</p>
|
||
<p>The flag +X attempts to load each <code>name</code> as an autoloaded function, but
|
||
does <em>not</em> execute it. The exit status is zero (success) if the function
|
||
was not previously defined <em>and</em> a definition for it was found. This
|
||
does <em>not</em> replace any existing definition of the function. The exit
|
||
status is nonzero (failure) if the function was already defined or when
|
||
no definition was found. In the latter case the function remains
|
||
undefined and marked for autoloading. If ksh-style autoloading is
|
||
enabled, the function created will contain the contents of the file plus
|
||
a call to the function itself appended to it, thus giving normal ksh
|
||
autoloading behaviour on the first call to the function. If the -m flag
|
||
is also given each <code>name</code> is treated as a pattern and all functions
|
||
already marked for autoload that match the pattern are loaded.</p>
|
||
<p>With the -t flag, turn on execution tracing; with -T, turn on execution
|
||
tracing only for the current function, turning it off on entry to any
|
||
called functions that do not also have tracing enabled.</p>
|
||
<p>With the -U flag, alias expansion is suppressed when the function is
|
||
loaded.</p>
|
||
<p>With the -w flag, the <code>name</code>s are taken as names of files compiled with
|
||
the zcompile builtin, and all functions defined in them are marked for
|
||
autoloading.</p>
|
||
<p>The flags -z and -k mark the function to be autoloaded using the zsh or
|
||
ksh style, as if the option KSH_AUTOLOAD were unset or were set,
|
||
respectively. The flags override the setting of the option at the time
|
||
the function is loaded.</p>
|
||
<p>Note that the autoload command makes no attempt to ensure the shell
|
||
options set during the loading or execution of the file have any
|
||
particular value. For this, the emulate command can be used:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">emulate zsh -c 'autoload -Uz func'
|
||
</code></pre>
|
||
</div>
|
||
<p>arranges that when <code>func</code> is loaded the shell is in native zsh
|
||
emulation, and this emulation is also applied when <code>func</code> is run.</p>
|
||
<p>Some of the functions of autoload are also provided by functions -u or
|
||
functions -U, but autoload is a more comprehensive interface.</p>
|
||
<p><span id="index-bg"></span> <span
|
||
id="index-jobs_002c-backgrounding"></span></p>
|
||
<p>bg [ <code>job</code> ... ]<br />
|
||
<code>job</code> ... &<br />
|
||
Put each specified <code>job</code> in the background, or the current job if none
|
||
is specified.</p>
|
||
<p>bindkey<br />
|
||
See <a href="Zsh-Line-Editor.html#Zle-Builtins">Zle Builtins</a>.</p>
|
||
<p><span id="index-break"></span> <span id="index-exiting-loops"></span>
|
||
<span id="index-loops_002c-exiting"></span></p>
|
||
<p>break [ <code>n</code> ]<br />
|
||
Exit from an enclosing for, while, until, select or repeat loop. If an
|
||
arithmetic expression <code>n</code> is specified, then break <code>n</code> levels instead of
|
||
just one.</p>
|
||
<p><span id="index-builtin-1"></span></p>
|
||
<p>builtin <code>name</code> [ <code>args</code> ... ]<br />
|
||
Executes the builtin <code>name</code>, with the given <code>args</code>.</p>
|
||
<p><span id="index-bye"></span></p>
|
||
<p>bye<br />
|
||
Same as exit.</p>
|
||
<p>cap<br />
|
||
See <a href="Zsh-Modules.html#The-zsh_002fcap-Module">The zsh/cap Module</a>.</p>
|
||
<p><span id="index-cd"></span> <span
|
||
id="index-directories_002c-changing"></span></p>
|
||
<p>cd [ -qsLP ] [ <code>arg</code> ]<br />
|
||
cd [ -qsLP ] <code>old</code> <code>new</code><br />
|
||
cd [ -qsLP ] {+|-}<code>n</code><br />
|
||
Change the current directory. In the first form, change the current
|
||
directory to <code>arg</code>, or to the value of $HOME if <code>arg</code> is not specified.
|
||
If <code>arg</code> is ‘-’, change to the previous directory.</p>
|
||
<p>Otherwise, if <code>arg</code> begins with a slash, attempt to change to the
|
||
directory given by <code>arg</code>.</p>
|
||
<p>If <code>arg</code> does not begin with a slash, the behaviour depends on whether
|
||
the current directory ‘.’ occurs in the list of directories contained in
|
||
the shell parameter cdpath. If it does not, first attempt to change to
|
||
the directory <code>arg</code> under the current directory, and if that fails but
|
||
cdpath is set and contains at least one element attempt to change to the
|
||
directory <code>arg</code> under each component of cdpath in turn until successful.
|
||
If ‘.’ occurs in cdpath, then cdpath is searched strictly in order so
|
||
that ‘.’ is only tried at the appropriate point.</p>
|
||
<p>The order of testing cdpath is modified if the option POSIX_CD is set,
|
||
as described in the documentation for the option.</p>
|
||
<p>If no directory is found, the option CDABLE_VARS is set, and a parameter
|
||
named <code>arg</code> exists whose value begins with a slash, treat its value as
|
||
the directory. In that case, the parameter is added to the named</p>
|
||
<p>The second form of cd substitutes the string <code>new</code> for the string <code>old</code>
|
||
in the name of the current directory, and tries to change to this new
|
||
directory.</p>
|
||
<p>The third form of cd extracts an entry from the directory stack, and
|
||
changes to that directory. An argument of the form ‘+<code>n</code>’ identifies a
|
||
stack entry by counting from the left of the list shown by the dirs
|
||
command, starting with zero. An argument of the form ‘-<code>n</code>’ counts from
|
||
the right. If the PUSHD_MINUS option is set, the meanings of ‘+’ and ‘-’
|
||
in this context are swapped. If the POSIX_CD option is set, this form of
|
||
cd is not recognised and will be interpreted as the first form.</p>
|
||
<p>If the -q (quiet) option is specified, the hook function chpwd and the
|
||
functions in the array chpwd_functions are not called. This is useful
|
||
for calls to cd that do not change the environment seen by an
|
||
interactive user.</p>
|
||
<p>If the -s option is specified, cd refuses to change the current
|
||
directory if the given pathname contains symlinks. If the -P option is
|
||
given or the CHASE_LINKS option is set, symbolic links are resolved to
|
||
their true values. If the -L option is given symbolic links are retained
|
||
in the directory (and not resolved) regardless of the state of the
|
||
CHASE_LINKS option.</p>
|
||
<p><span id="index-chdir"></span></p>
|
||
<p>chdir<br />
|
||
Same as cd.</p>
|
||
<p>clone<br />
|
||
See <a href="Zsh-Modules.html#The-zsh_002fclone-Module">The zsh/clone Module</a>.</p>
|
||
<p><span id="index-command-1"></span></p>
|
||
<p>command [ -pvV ] <code>simple command</code><br />
|
||
The simple command argument is taken as an external command instead of a
|
||
function or builtin and is executed. If the POSIX_BUILTINS option is
|
||
set, builtins will also be executed but certain special properties of
|
||
them are suppressed. The -p flag causes a default path to be searched
|
||
instead of that in $path. With the -v flag, command is similar to whence
|
||
and with -V, it is equivalent to whence -v.</p>
|
||
<p>See also <a href="Shell-Grammar.html#Precommand-Modifiers">Precommand
|
||
Modifiers</a>.</p>
|
||
<p>comparguments<br />
|
||
See <a href="Zsh-Modules.html#The-zsh_002fcomputil-Module">The zsh/computil
|
||
Module</a>.</p>
|
||
<p>compcall<br />
|
||
See <a href="Zsh-Modules.html#The-zsh_002fcompctl-Module">The zsh/compctl
|
||
Module</a>.</p>
|
||
<p>compctl<br />
|
||
See <a href="Zsh-Modules.html#The-zsh_002fcompctl-Module">The zsh/compctl
|
||
Module</a>.</p>
|
||
<p>compdescribe<br />
|
||
See <a href="Zsh-Modules.html#The-zsh_002fcomputil-Module">The zsh/computil
|
||
Module</a>.</p>
|
||
<p>compfiles<br />
|
||
See <a href="Zsh-Modules.html#The-zsh_002fcomputil-Module">The zsh/computil
|
||
Module</a>.</p>
|
||
<p>compgroups<br />
|
||
See <a href="Zsh-Modules.html#The-zsh_002fcomputil-Module">The zsh/computil
|
||
Module</a>.</p>
|
||
<p>compquote<br />
|
||
See <a href="Zsh-Modules.html#The-zsh_002fcomputil-Module">The zsh/computil
|
||
Module</a>.</p>
|
||
<p>comptags<br />
|
||
See <a href="Zsh-Modules.html#The-zsh_002fcomputil-Module">The zsh/computil
|
||
Module</a>.</p>
|
||
<p>comptry<br />
|
||
See <a href="Zsh-Modules.html#The-zsh_002fcomputil-Module">The zsh/computil
|
||
Module</a>.</p>
|
||
<p>compvalues<br />
|
||
See <a href="Zsh-Modules.html#The-zsh_002fcomputil-Module">The zsh/computil
|
||
Module</a>.</p>
|
||
<p><span id="index-continue"></span> <span
|
||
id="index-loops_002c-continuing"></span> <span
|
||
id="index-continuing-loops"></span></p>
|
||
<p>continue [ <code>n</code> ]<br />
|
||
Resume the next iteration of the enclosing for, while, until, select or
|
||
repeat loop. If an arithmetic expression <code>n</code> is specified, break out of
|
||
<code>n</code>-1 loops and resume at the <code>n</code>th enclosing loop.</p>
|
||
<p><span id="index-declare"></span></p>
|
||
<p>declare<br />
|
||
Same as typeset.</p>
|
||
<p><span id="index-dirs"></span> <span
|
||
id="index-directory-stack_002c-printing"></span></p>
|
||
<p>dirs [ -c ] [ <code>arg</code> ... ]<br />
|
||
dirs [ -lpv ]<br />
|
||
With no arguments, print the contents of the directory stack.
|
||
Directories are added to this stack with the pushd command, and removed
|
||
with the cd or popd commands. If arguments are specified, load them onto
|
||
the directory stack, replacing anything that was there, and push the
|
||
current directory onto the stack.</p>
|
||
<p>-c<br />
|
||
clear the directory stack.</p>
|
||
<p>-l<br />
|
||
print directory names in full instead of using of using ~ expressions
|
||
(<a href="Expansion.html#Filename-Expansion">Filename Expansion</a>).</p>
|
||
<p>-p<br />
|
||
print directory entries one per line.</p>
|
||
<p>-v<br />
|
||
number the directories in the stack when printing.</p>
|
||
<p><span id="index-disable"></span> <span
|
||
id="index-disabling-commands"></span> <span
|
||
id="index-commands_002c-disabling"></span></p>
|
||
<p>disable [ -afmprs ] <code>name</code> ...<br />
|
||
’?’<br />
|
||
The pattern character ? wherever it occurs, including when preceding a
|
||
parenthesis with KSH_GLOB.</p>
|
||
<p>’*’<br />
|
||
The pattern character * wherever it occurs, including recursive
|
||
globbing and when preceding a parenthesis with KSH_GLOB.</p>
|
||
<p>’[’<br />
|
||
Character classes.</p>
|
||
<p>’<’ (NO_SH_GLOB)<br />
|
||
Numeric ranges.</p>
|
||
<p>’|’ (NO_SH_GLOB)<br />
|
||
Alternation in grouped patterns, case statements, or KSH_GLOB
|
||
parenthesised expressions.</p>
|
||
<p>’(’ (NO_SH_GLOB)<br />
|
||
Grouping using single parentheses. Disabling this does not disable the
|
||
use of parentheses for KSH_GLOB where they are introduced by a special
|
||
character, nor for glob qualifiers (use ‘setopt NO_BARE_GLOB_QUAL’ to
|
||
disable glob qualifiers that use parentheses only).</p>
|
||
<p>’~’ (EXTENDED_GLOB)<br />
|
||
Exclusion in the form <code>A</code>~<code>B</code>.</p>
|
||
<p>’^’ (EXTENDED_GLOB)<br />
|
||
Exclusion in the form <code>A</code>^<code>B</code>.</p>
|
||
<p>’#’ (EXTENDED_GLOB)<br />
|
||
The pattern character # wherever it occurs, both for repetition of a
|
||
previous pattern and for indicating globbing flags.</p>
|
||
<p>’?(’ (KSH_GLOB)<br />
|
||
The grouping form ?(<code>...</code>). Note this is also disabled if ’?’ is
|
||
disabled.</p>
|
||
<p>’*(’ (KSH_GLOB)<br />
|
||
The grouping form *(<code>...</code>). Note this is also disabled if ’*’ is
|
||
disabled.</p>
|
||
<p>’+(’ (KSH_GLOB)<br />
|
||
The grouping form +(<code>...</code>).</p>
|
||
<p>’!(’ (KSH_GLOB)<br />
|
||
The grouping form !(<code>...</code>).</p>
|
||
<p>’@(’ (KSH_GLOB)<br />
|
||
The grouping form @(<code>...</code>).</p>
|
||
<p><span id="index-disown"></span> <span
|
||
id="index-jobs_002c-disowning-1"></span></p>
|
||
<p>disown [ <code>job</code> ... ]</p>
|
||
<p><code>job</code> ... &|</p>
|
||
<p><code>job</code> ... &!</p>
|
||
<p>no longer report their status, and will not complain if you try to exit
|
||
an interactive shell with them running or stopped. If no <code>job</code> is
|
||
specified, disown the current job.</p>
|
||
<p>If the <code>job</code>s are currently stopped and the AUTO_CONTINUE option is not
|
||
set, a warning is printed containing information about how to make them
|
||
running after they have been disowned. If one of the latter two forms is
|
||
used, the <code>job</code>s will automatically be made running, independent of the
|
||
setting of the AUTO_CONTINUE option.</p>
|
||
<p><span id="index-echo"></span></p>
|
||
<p>echo [ -neE ] [ <code>arg</code> ... ]</p>
|
||
<p>Write each <code>arg</code> on the standard output, with a space separating each
|
||
one. If the -n flag is not present, print a newline at the end. echo
|
||
recognizes the following escape sequences:</p>
|
||
<p>\a<br />
|
||
bell character</p>
|
||
<p>\b<br />
|
||
backspace</p>
|
||
<p>\c<br />
|
||
suppress subsequent characters and final newline</p>
|
||
<p>\e<br />
|
||
escape</p>
|
||
<p>\f<br />
|
||
form feed</p>
|
||
<p>\n<br />
|
||
linefeed (newline)</p>
|
||
<p>\r<br />
|
||
carriage return</p>
|
||
<p>\t<br />
|
||
horizontal tab</p>
|
||
<p>\v<br />
|
||
vertical tab</p>
|
||
<p>\\<br />
|
||
backslash</p>
|
||
<p>\0<code>NNN</code><br />
|
||
character code in octal</p>
|
||
<p>\x<code>NN</code><br />
|
||
character code in hexadecimal</p>
|
||
<p>\u<code>NNNN</code><br />
|
||
unicode character code in hexadecimal</p>
|
||
<p>\U<code>NNNNNNNN</code><br />
|
||
unicode character code in hexadecimal</p>
|
||
<p><span id="index-BSD_005fECHO_002c-use-of"></span></p>
|
||
<p>The -E flag, or the BSD_ECHO option, can be used to disable these escape
|
||
sequences. In the latter case, -e flag can be used to enable them.</p>
|
||
<p>Note that for standards compliance a double dash does not terminate
|
||
option processing; instead, it is printed directly. However, a single
|
||
dash does terminate option processing, so the first dash, possibly
|
||
following options, is not printed, but everything following it is
|
||
printed as an argument. The single dash behaviour is different printf,
|
||
and for a more controllable way of printing text within zsh, see print.</p>
|
||
<p>echotc</p>
|
||
<p>See <a href="Zsh-Modules.html#The-zsh_002ftermcap-Module">The zsh/termcap
|
||
Module</a>.</p>
|
||
<p>echoti</p>
|
||
<p>See <a href="Zsh-Modules.html#The-zsh_002fterminfo-Module">The zsh/terminfo
|
||
Module</a>.</p>
|
||
<p><span id="index-emulate"></span> <span
|
||
id="index-compatibility_002c-sh"></span> <span
|
||
id="index-compatibility_002c-ksh"></span> <span
|
||
id="index-compatibility_002c-csh"></span> <span
|
||
id="index-sh_002c-compatibility"></span> <span
|
||
id="index-ksh_002c-compatibility"></span> <span
|
||
id="index-csh_002c-compatibility"></span></p>
|
||
<p>emulate [ -lLR ] [ {zsh|sh|ksh|csh} [ <code>flags</code> ... ] ]</p>
|
||
<p>Without any argument print current emulation mode.</p>
|
||
<p>With single argument set up zsh options to emulate the specified shell
|
||
as much as possible. csh will never be fully emulated. If the argument
|
||
is not one of the shells listed above, zsh will be used as a default;
|
||
more precisely, the tests performed on the argument are the same as
|
||
those used to determine the emulation at startup based on the shell
|
||
name, see <a href="Invocation.html#Compatibility">Compatibility</a> . In addition
|
||
to setting shell options, the command also restores the pristine state
|
||
of pattern enables, as if all patterns had been enabled using enable -p.</p>
|
||
<p>If the emulate command occurs inside a function that has been marked for
|
||
execution tracing with functions -t then the xtrace option will be
|
||
turned on regardless of emulation mode or other options. Note that code
|
||
executed inside the function by the ., source, or eval commands is not
|
||
considered to be running directly from the function, hence does not
|
||
provoke this behaviour.</p>
|
||
<p>are reset to their default value corresponding to the specified
|
||
emulation mode, except for certain options describing the interactive
|
||
environment; otherwise, only those options likely to cause portability
|
||
problems in scripts and functions are altered. If the -L switch is
|
||
given, the options LOCAL_OPTIONS, LOCAL_PATTERNS and LOCAL_TRAPS will be
|
||
set as well, causing the effects of the emulate command and any setopt,
|
||
disable -p or enable -p, and trap commands to be local to the
|
||
immediately surrounding shell function, if any; normally these options
|
||
are turned off in all emulation modes except ksh. The -L switch is
|
||
mutually exclusive with the use of -c in <code>flags</code>.</p>
|
||
<p>If there is a single argument and the -l switch is given, the options
|
||
that would be set or unset (the latter indicated with the prefix ‘no’)
|
||
are listed. -l can be combined with -L or -R and the list will be
|
||
modified in the appropriate way. Note the list does not depend on the
|
||
current setting of options, i.e. it includes all options that may in
|
||
principle change, not just those that would actually change.</p>
|
||
<p>The <code>flags</code> may be any of the invocation-time flags described in
|
||
<a href="Invocation.html#Invocation">Invocation</a>, except that ‘-o EMACS’ and ‘-o
|
||
VI’ may not be used. Flags such as ‘+r’/‘+o RESTRICTED’ may be
|
||
prohibited in some circumstances.</p>
|
||
<p>If -c <code>arg</code> appears in <code>flags</code>, <code>arg</code> is evaluated while the requested
|
||
emulation is temporarily in effect. In this case the emulation mode and
|
||
all options are restored to their previous values before emulate
|
||
returns. The -R switch may precede the name of the shell to emulate;
|
||
note this has a meaning distinct from including -R in <code>flags</code>.</p>
|
||
<p>Use of -c enables ‘sticky’ emulation mode for functions defined within
|
||
the evaluated expression: the emulation mode is associated thereafter
|
||
with the function so that whenever the function is executed the
|
||
emulation (respecting the -R switch, if present) and all options are set
|
||
(and pattern disables cleared) before entry to the function, and the
|
||
state is restored after exit. If the function is called when the sticky
|
||
emulation is already in effect, either within an ‘emulate <code>shell</code> -c’
|
||
expression or within another function with the same sticky emulation,
|
||
entry and exit from the function do not cause options to be altered
|
||
(except due to standard processing such as the LOCAL_OPTIONS option).
|
||
This also applies to functions marked for autoload within the sticky
|
||
emulation; the appropriate set of options will be applied at the point
|
||
the function is loaded as well as when it is run.</p>
|
||
<p>For example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">emulate sh -c 'fni() { setopt cshnullglob; }
|
||
fno() { fni; }'
|
||
fno
|
||
</code></pre>
|
||
</div>
|
||
<p>The two functions fni and fno are defined with sticky sh emulation. fno
|
||
is then executed, causing options associated with emulations to be set
|
||
to their values in sh. fno then calls fni; because fni is also marked
|
||
for sticky sh emulation, no option changes take place on entry to or
|
||
exit from it. Hence the option cshnullglob, turned off by sh emulation,
|
||
will be turned on within fni and remain on return to fno. On exit from
|
||
fno, the emulation mode and all options will be restored to the state
|
||
they were in before entry to the temporary emulation.</p>
|
||
<p>The documentation above is typically sufficient for the intended
|
||
environment. More detailed rules follow.</p>
|
||
<p>1.<br />
|
||
The sticky emulation environment provided by ‘emulate <code>shell</code> -c’ is
|
||
identical to that provided by entry to a function marked for sticky
|
||
emulation as a consequence of being defined in such an environment.
|
||
Hence, for example, the sticky emulation is inherited by subfunctions
|
||
defined within functions with sticky emulation.</p>
|
||
<p>2.<br />
|
||
No change of options takes place on entry to or exit from functions that
|
||
are not marked for sticky emulation, other than those that would
|
||
normally take place, even if those functions are called within sticky
|
||
emulation.</p>
|
||
<p>3.<br />
|
||
No special handling is provided for functions marked for autoload nor
|
||
for functions present in wordcode created by the zcompile command.</p>
|
||
<p>4.<br />
|
||
The presence or absence of the -R switch to emulate corresponds to
|
||
different sticky emulation modes, so for example ‘emulate sh -c’,
|
||
‘emulate -R sh -c’ and ‘emulate csh -c’ are treated as three distinct
|
||
sticky emulations.</p>
|
||
<p>5.<br />
|
||
Difference in shell options supplied in addition to the basic emulation
|
||
also mean the sticky emulations are different, so for example ‘emulate
|
||
zsh -c’ and ‘emulate zsh -o cbases -c’ are treated as distinct sticky
|
||
emulations.</p>
|
||
<p><span id="index-enable"></span> <span
|
||
id="index-enabling-commands"></span> <span
|
||
id="index-commands_002c-enabling"></span></p>
|
||
<p>enable [ -afmprs ] <code>name</code> ...</p>
|
||
<p>earlier with disable. The default is to enable builtin commands. The -a
|
||
option causes enable to act on regular or global aliases. The -s option
|
||
causes enable to act on suffix aliases. The -f option causes enable to
|
||
act on shell functions. The -r option causes enable to act on reserved
|
||
words. Without arguments printed. With the -m flag the arguments are
|
||
taken as patterns disabled with the disable builtin command.</p>
|
||
<p>enable -p reenables patterns disabled with disable -p. Note that it does
|
||
not override globbing options; for example, ‘enable -p "~"’ does not
|
||
cause the pattern character ~ to be active unless the EXTENDED_GLOB
|
||
option is also set. To enable all possible patterns (so that they may be
|
||
individually disabled with disable -p), use ‘setopt EXTENDED_GLOB
|
||
KSH_GLOB NO_SH_GLOB’.</p>
|
||
<p><span id="index-eval"></span> <span
|
||
id="index-evaluating-arguments-as-commands"></span></p>
|
||
<p>eval [ <code>arg</code> ... ]</p>
|
||
<p>Read the arguments as input to the shell and execute the resulting
|
||
command(s) in the current shell process. The return status is the same
|
||
as if the commands had been executed directly by the shell; if there are
|
||
no <code>args</code> or they contain no commands (i.e. are an empty string or
|
||
whitespace) the return status is zero.</p>
|
||
<p>exec [ -cl ] [ -a <code>argv0</code> ] [ <code>command</code> [ <code>arg</code> ... ] ]</p>
|
||
<p>Replace the current shell with <code>command</code> rather than forking. If
|
||
<code>command</code> is a shell builtin command or a shell function, the shell
|
||
executes it, and exits when the command is complete.</p>
|
||
<p>With -c clear the environment; with -l prepend - to the argv[0] string
|
||
of the command executed (to simulate a login shell); with -a <code>argv0</code> set
|
||
the argv[0] string of the command executed. See <a href="Shell-Grammar.html#Precommand-Modifiers">Precommand
|
||
Modifiers</a>.</p>
|
||
<p>If the option POSIX_BUILTINS is set, <code>command</code> is never interpreted as a
|
||
shell builtin command or shell function. This means further precommand
|
||
modifiers such as builtin and noglob are also not interpreted within the
|
||
shell. Hence <code>command</code> is always found by searching the command path.</p>
|
||
<p><span id="index-redirection_002c-current-shell_0027s-I_002fO"></span></p>
|
||
<p>If <code>command</code> is omitted but any redirections are specified, then the
|
||
redirections will take effect in the current shell.</p>
|
||
<p><span id="index-exit"></span></p>
|
||
<p>exit [ <code>n</code> ]</p>
|
||
<p>Exit the shell with the exit status specified by an arithmetic
|
||
expression <code>n</code>; if none is specified, use the exit status from the last
|
||
command executed. <span id="index-IGNORE_005fEOF_002c-use-of"></span> An
|
||
EOF condition will also cause the shell to exit, unless the IGNORE_EOF
|
||
option is set.</p>
|
||
<p>See notes at the end of <a href="Jobs-_0026-Signals.html#Jobs-_0026-Signals">Jobs &
|
||
Signals</a> for some possibly
|
||
unexpected interactions of the exit command with jobs.</p>
|
||
<p><span id="index-export-1"></span></p>
|
||
<p>export [ <code>name</code>[=<code>value</code>] ... ]</p>
|
||
<p>The specified <code>name</code>s are marked for automatic export to the environment
|
||
of subsequently executed commands. Equivalent to typeset -gx. If a
|
||
parameter specified does not already exist, it is created in the global
|
||
scope.</p>
|
||
<p><span id="index-false"></span> <span
|
||
id="index-doing-nothing_002c-unsuccessfully"></span></p>
|
||
<p>false [ <code>arg</code> ... ]</p>
|
||
<p>Do nothing and return an exit status of 1.</p>
|
||
<p><span id="index-fc"></span> <span
|
||
id="index-history_002c-editing"></span> <span
|
||
id="index-editing-history"></span></p>
|
||
<p>fc [ -e <code>ename</code> ] [ -s ] [ -LI ] [ -m <code>match</code> ] [ <code>old</code>=<code>new</code>
|
||
... ] [ <code>first</code> [ <code>last</code> ] ]</p>
|
||
<p>fc -l [ -LI ] [ -nrdfEiD ] [ -t <code>timefmt</code> ] [ -m <code>match</code> ]</p>
|
||
<p> [ <code>old</code>=<code>new</code> ... ] [ <code>first</code> [ <code>last</code> ] ]</p>
|
||
<p>fc -p [ -a ] [ <code>filename</code> [ <code>histsize</code> [ <code>savehistsize</code> ] ] ]</p>
|
||
<p>fc -P</p>
|
||
<p>fc -ARWI [ <code>filename</code> ]</p>
|
||
<p>The fc command controls the interactive history mechanism. Note that
|
||
reading and writing of history options is only performed if the shell is
|
||
interactive. Usually this is detected automatically, but it can be
|
||
forced by setting the interactive option when starting the shell.</p>
|
||
<p>The first two forms of this command select a range of events from
|
||
<code>first</code> to <code>last</code> from the history list. The arguments <code>first</code> and
|
||
<code>last</code> may be specified as a number or as a string. A negative number is
|
||
used as an offset to the current history event number. A string
|
||
specifies the most recent event beginning with the given string. All
|
||
substitutions <code>old</code>=<code>new</code>, if any, are then performed on the text of the
|
||
events.</p>
|
||
<p>The range of events selected by numbers can be narrowed further by the
|
||
following flags.</p>
|
||
<p>-I<br />
|
||
restricts to only internal events (not from $HISTFILE)</p>
|
||
<p>-L<br />
|
||
restricts to only local events (not from other shells, see SHARE_HISTORY
|
||
in <a href="Options.html#Description-of-Options">Description of Options</a> – note
|
||
that $HISTFILE is considered local when read at startup)</p>
|
||
<p>-m<br />
|
||
takes the first argument as a pattern (which should be quoted) and only
|
||
the history events matching this pattern are considered</p>
|
||
<p>If <code>first</code> is not specified, it will be set to -1 (the most recent
|
||
event), or to -16 if the -l flag is given. If <code>last</code> is not specified,
|
||
it will be set to <code>first</code>, or to -1 if the -l flag is given. However, if
|
||
the current event has added entries to the history with ‘print -s’ or
|
||
‘fc -R’, then the default <code>last</code> for -l includes all new history entries
|
||
since the current event began.</p>
|
||
<p>When the -l flag is given, the resulting events are listed on standard
|
||
output. Otherwise the editor program specified by -e <code>ename</code> is invoked
|
||
on a file containing these history events. If -e is not given, the value
|
||
of the parameter FCEDIT is used; if that is not set the value of the
|
||
parameter EDITOR is used; if that is not set a builtin default, usually
|
||
‘vi’ is used. If <code>ename</code> is ‘-’, no editor is invoked. When editing is
|
||
complete, the edited command is executed.</p>
|
||
<p>The flag ‘-s’ is equivalent to ‘-e -’. The flag -r reverses the order of
|
||
the events and the flag -n suppresses event numbers when listing.</p>
|
||
<p>Also when listing,</p>
|
||
<p>-d<br />
|
||
prints timestamps for each event</p>
|
||
<p>-f<br />
|
||
prints full time-date stamps in the US ‘<code>MM</code>/<code>DD</code>/<code>YY</code> <code>hh</code>:<code>mm</code>’ format</p>
|
||
<p>-E<br />
|
||
prints full time-date stamps in the European ‘<code>dd</code>.<code>mm</code>.<code>yyyy</code>
|
||
<code>hh</code>:<code>mm</code>’ format</p>
|
||
<p>-i<br />
|
||
prints full time-date stamps in ISO8601 ‘<code>yyyy</code>-<code>mm</code>-<code>dd</code> <code>hh</code>:<code>mm</code>’
|
||
format</p>
|
||
<p>-t <code>fmt</code><br />
|
||
prints time and date stamps in the given format; <code>fmt</code> is formatted with
|
||
the strftime function with the zsh extensions described for the
|
||
%D{<code>string</code>} prompt format in <a href="Prompt-Expansion.html#Prompt-Expansion">Prompt
|
||
Expansion</a>. The resulting
|
||
formatted string must be no more than 256 characters or will not be
|
||
printed</p>
|
||
<p>-D<br />
|
||
prints elapsed times; may be combined with one of the options above</p>
|
||
<p><span id="index-history_002c-stack"></span> <span
|
||
id="index-stack_002c-history"></span></p>
|
||
<p>‘fc -p’ pushes the current history list onto a stack and switches to a
|
||
new history list. If the -a option is also specified, this history list
|
||
will be automatically popped when the current function scope is exited,
|
||
which is a much better solution than creating a trap function to call
|
||
‘fc -P’ manually. If no arguments are specified, the history list is
|
||
left empty, $HISTFILE is unset, and $HISTSIZE & $SAVEHIST are set to
|
||
their default values. If one argument is given, $HISTFILE is set to that
|
||
filename, $HISTSIZE & $SAVEHIST are left unchanged, and the history file
|
||
is read in (if it exists) to initialize the new list. If a second
|
||
argument is specified, $HISTSIZE & $SAVEHIST are instead set to the
|
||
single specified numeric value. Finally, if a third argument is
|
||
specified, $SAVEHIST is set to a separate value from $HISTSIZE. You are
|
||
free to change these environment values for the new history list however
|
||
you desire in order to manipulate the new history list.</p>
|
||
<p>‘fc -P’ pops the history list back to an older list saved by ‘fc -p’.
|
||
The current list is saved to its $HISTFILE before it is destroyed
|
||
(assuming that $HISTFILE and $SAVEHIST are set appropriately, of
|
||
course). The values of $HISTFILE, $HISTSIZE, and $SAVEHIST are restored
|
||
to the values they had when ‘fc -p’ was called. Note that this
|
||
restoration can conflict with making these variables "local", so your
|
||
best bet is to avoid local declarations for these variables in functions
|
||
that use ‘fc -p’. The one other guaranteed-safe combination is declaring
|
||
these variables to be local at the top of your function and using the
|
||
automatic option (-a) with ‘fc -p’. Finally, note that it is legal to
|
||
manually pop a push marked for automatic popping if you need to do so
|
||
before the function exits.</p>
|
||
<p><span id="index-history_002c-file"></span> <span
|
||
id="index-file_002c-history"></span></p>
|
||
<p>‘fc -R’ reads the history from the given file, ‘fc -W’ writes the
|
||
history out to the given file, and ‘fc -A’ appends the history out to
|
||
the given file. If no filename is specified, the $HISTFILE is assumed.
|
||
If the -I option is added to -R, only those events that are not already
|
||
contained within the internal history list are added. If the -I option
|
||
is added to -A or -W, only those events that are new since last
|
||
incremental append/write to the history file are appended/written. In
|
||
any case, the created file will have no more than $SAVEHIST entries.</p>
|
||
<p><span id="index-fg"></span> <span
|
||
id="index-jobs_002c-foregrounding"></span> <span
|
||
id="index-jobs_002c-resuming"></span></p>
|
||
<p>fg [ <code>job</code> ... ]</p>
|
||
<p><code>job</code> ...</p>
|
||
<p>Bring each specified <code>job</code> in turn to the foreground. If no <code>job</code> is
|
||
specified, resume the current job.</p>
|
||
<p><span id="index-float"></span></p>
|
||
<p>float [ {+|-}Hghlprtux ] [ {+|-}EFLRZ [ <code>n</code> ] ] [
|
||
<code>name</code>[=<code>value</code>] ... ]</p>
|
||
<p>Equivalent to typeset -E, except that options irrelevant to floating
|
||
point numbers are not permitted.</p>
|
||
<p><span id="index-functions-1"></span></p>
|
||
<p>functions [ {+|-}UkmtTuWz ] [ -x <code>num</code> ] [ <code>name</code> ... ]</p>
|
||
<p>functions -c <code>oldfn</code> <code>newfn</code></p>
|
||
<p>functions -M [-s] <code>mathfn</code> [ <code>min</code> [ <code>max</code> [ <code>shellfn</code> ] ] ]</p>
|
||
<p>functions -M [ -m <code>pattern</code> ... ]</p>
|
||
<p>functions +M [ -m ] <code>mathfn</code> ...</p>
|
||
<p>Equivalent to typeset -f, with the exception of the -c, -x, -M and -W
|
||
options. For functions -u and functions -U, see autoload, which provides
|
||
additional options. For functions -t and functions -T, see typeset -f.</p>
|
||
<p>The -x option indicates that any functions output will have each leading
|
||
tab for indentation, added by the shell to show syntactic structure,
|
||
expanded to the given number <code>num</code> of spaces. <code>num</code> can also be 0 to
|
||
suppress all indentation.</p>
|
||
<p>The -W option turns on the option WARN_NESTED_VAR for the named function
|
||
or functions only. The option is turned off at the start of nested
|
||
functions (apart from anonoymous functions) unless the called function
|
||
also has the -W attribute.</p>
|
||
<p>The -c option causes <code>oldfn</code> to be copied to <code>newfn</code>. The copy is
|
||
efficiently handled internally by reference counting. If <code>oldfn</code> was
|
||
marked for autoload it is first loaded and if this fails the copy fails.
|
||
Either function may subsequently be redefined without affecting the
|
||
other. A typical idiom is that <code>oldfn</code> is the name of a library shell
|
||
function which is then redefined to call newfn, thereby installing a
|
||
modified version of the function.</p>
|
||
<p><em>The</em> -M <em>and</em> +M <em>flags</em> <span
|
||
id="index-defining-mathematical-functions"></span> <span
|
||
id="index-functions_002c-defining-mathematical"></span></p>
|
||
<p>Use of the -M option may not be combined with any of the options handled
|
||
by typeset -f.</p>
|
||
<p>functions -M <code>mathfn</code> defines <code>mathfn</code> as the name of a mathematical
|
||
function recognised in all forms of arithmetical expressions; see
|
||
<a href="Arithmetic-Evaluation.html#Arithmetic-Evaluation">Arithmetic
|
||
Evaluation</a>. By
|
||
default <code>mathfn</code> may take any number of comma-separated arguments. If
|
||
<code>min</code> is given, it must have exactly <code>min</code> args; if <code>min</code> and <code>max</code> are
|
||
both given, it must have at least <code>min</code> and at most <code>max</code> args. <code>max</code>
|
||
may be -1 to indicate that there is no upper limit.</p>
|
||
<p>By default the function is implemented by a shell function of the same
|
||
name; if <code>shellfn</code> is specified it gives the name of the corresponding
|
||
shell function while <code>mathfn</code> remains the name used in arithmetical
|
||
expressions. The name of the function in $0 is <code>mathfn</code> (not <code>shellfn</code>
|
||
as would usually be the case), provided the option FUNCTION_ARGZERO is
|
||
in effect. The positional parameters in the shell function correspond to
|
||
the arguments of the mathematical function call.</p>
|
||
<p>The result of the last arithmetical expression evaluated inside the
|
||
shell function gives the result of the mathematical function. This is
|
||
not limited to arithmetic substitutions of the form $((<code>...</code>)), but also
|
||
includes arithmetical expressions evaluated in any other way, including
|
||
by the let builtin, by ((<code>...</code>)) statements, and even by the return
|
||
builtin and by array subscripts. Therefore, care must be taken not to
|
||
use syntactical constructs that perform arithmetic evaluation after
|
||
evaluating what is to be the result of the function. For example:</p>
|
||
<p><span id="index-zmath_005fcube"></span> <span id="index-cube"></span></p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh"># WRONG
|
||
zmath_cube() {
|
||
(( $1 * $1 * $1 ))
|
||
return 0
|
||
}
|
||
functions -M cube 1 1 zmath_cube
|
||
print $(( cube(3) ))
|
||
</code></pre>
|
||
</div>
|
||
<p>This will print ‘0’ because of the return.</p>
|
||
<p>Commenting the return out would lead to a different problem: the
|
||
((<code>...</code>)) statement would become the last statement in the function, so
|
||
the <em>return status</em> ($?) of the function would be non-zero (indicating
|
||
failure) whenever the <em>arithmetic result</em> of the function would happen
|
||
to be zero (numerically):</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh"># WRONG
|
||
zmath_cube() {
|
||
(( $1 * $1 * $1 ))
|
||
}
|
||
functions -M cube 1 1 zmath_cube
|
||
print $(( cube(0) ))
|
||
</code></pre>
|
||
</div>
|
||
<p>Instead, the true builtin can be used:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh"># RIGHT
|
||
zmath_cube() {
|
||
(( $1 * $1 * $1 ))
|
||
true
|
||
}
|
||
functions -M cube 1 1 zmath_cube
|
||
print $(( cube(3) ))
|
||
</code></pre>
|
||
</div>
|
||
<p>If the additional option -s is given to functions -M, the argument to
|
||
the function is a single string: anything between the opening and
|
||
matching closing parenthesis is passed to the function as a single
|
||
argument, even if it includes commas or white space. The minimum and
|
||
maximum argument specifiers must therefore be 1 if given. An empty
|
||
argument list is passed as a zero-length string. Thus, the following
|
||
string function takes a single argument, including the commas, and
|
||
prints 11:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">stringfn() { (( $#1 )); true }
|
||
functions -Ms stringfn
|
||
print $(( stringfn(foo,bar,rod) ))
|
||
</code></pre>
|
||
</div>
|
||
<p>functions -M with no arguments lists all such user-defined functions in
|
||
the same form as a definition. With the additional option -m and a list
|
||
of arguments, all functions whose <code>mathfn</code> matches one of the pattern
|
||
arguments are listed.</p>
|
||
<p>function +M removes the list of mathematical functions; with the
|
||
additional option -m the arguments are treated as patterns and all
|
||
functions whose <code>mathfn</code> matches the pattern are removed. Note that the
|
||
shell function implementing the behaviour is not removed (regardless of
|
||
whether its name coincides with <code>mathfn</code>).</p>
|
||
<p>getcap</p>
|
||
<p>See <a href="Zsh-Modules.html#The-zsh_002fcap-Module">The zsh/cap Module</a>.</p>
|
||
<p><span id="index-getln"></span> <span
|
||
id="index-line_002c-reading"></span> <span
|
||
id="index-reading-a-line"></span></p>
|
||
<p>getln [ -AclneE ] <code>name</code> ...</p>
|
||
<p>Read the top value from the buffer stack and put it in the shell
|
||
parameter <code>name</code>. Equivalent to read -zr.</p>
|
||
<p><span id="index-getopts"></span> <span
|
||
id="index-options_002c-processing"></span></p>
|
||
<p>getopts <code>optstring</code> <code>name</code> [ <code>arg</code> ... ]</p>
|
||
<p>Checks the <code>arg</code>s for legal options. If the <code>arg</code>s are omitted, use the
|
||
positional parameters. A valid option argument begins with a ‘+’ or a
|
||
‘-’. An argument not beginning with a ‘+’ or a ‘-’, or the argument
|
||
‘--’, ends the options. Note that a single ‘-’ is not considered a valid
|
||
option argument. <code>optstring</code> contains the letters that getopts
|
||
recognizes. If a letter is followed by a ‘:’, that option requires an
|
||
argument. The options can be separated from the argument by blanks.</p>
|
||
<p>Each time it is invoked, getopts places the option letter it finds in
|
||
the shell parameter <code>name</code>, prepended with a ‘+’ when <code>arg</code> begins with
|
||
a ‘+’. The index of the next <code>arg</code> is stored in OPTIND. The option
|
||
argument, if any, is stored in OPTARG. <span
|
||
id="index-OPTIND_002c-use-of"></span> <span
|
||
id="index-OPTARG_002c-use-of"></span></p>
|
||
<p>The first option to be examined may be changed by explicitly assigning
|
||
to OPTIND. OPTIND has an initial value of 1, and is normally set to 1
|
||
upon entry to a shell function and restored upon exit. (The
|
||
POSIX_BUILTINS option disables this, and also changes the way the value
|
||
is calculated to match other shells.) OPTARG is not reset and retains
|
||
its value from the most recent call to getopts. If either of OPTIND or
|
||
OPTARG is explicitly unset, it remains unset, and the index or option
|
||
argument is not stored. The option itself is still stored in <code>name</code> in
|
||
this case.</p>
|
||
<p>A leading ‘:’ in <code>optstring</code> causes getopts to store the letter of any
|
||
invalid option in OPTARG, and to set <code>name</code> to ‘?’ for an unknown option
|
||
and to ‘:’ when a required argument is missing. Otherwise, getopts sets
|
||
<code>name</code> to ‘?’ and prints an error message when an option is invalid. The
|
||
exit status is nonzero when there are no more options.</p>
|
||
<p><span id="index-hash-1"></span></p>
|
||
<p>hash [ -Ldfmrv ] [ <code>name</code>[=<code>value</code>] ] ...</p>
|
||
<p>hash can be used to directly modify the contents of the command</p>
|
||
<p>A command <code>name</code> starting with a / is never hashed, whether by explicit
|
||
use of the hash command or otherwise. Such a command is always found by
|
||
direct look up in the file system.</p>
|
||
<p>Given no arguments, and neither the -r or -f options,</p>
|
||
<p>It will be subsequently rebuilt in the normal fashion. all the absolute
|
||
directories in the PATH, These two options cannot be used with any
|
||
arguments.</p>
|
||
<p>The -m option causes the arguments to be taken as patterns matching
|
||
those patterns are printed. This is the only way to display</p>
|
||
<p>For each <code>name</code> with a corresponding <code>value</code>, put ‘<code>name</code>’ in whenever
|
||
‘<code>name</code>’ is used as a command argument, the shell will try to execute
|
||
the file given by ‘<code>value</code>’. that ‘<code>value</code>’ may be referred to as
|
||
‘~<code>name</code>’.</p>
|
||
<p>For each <code>name</code> with no checking what the appropriate value is in the
|
||
normal manner for</p>
|
||
<p>added by explicit specification. If has no effect if used with -f.</p>
|
||
<p>the form of a call to hash.</p>
|
||
<p><span id="index-history-1"></span></p>
|
||
<p>history</p>
|
||
<p>Same as fc -l.</p>
|
||
<p><span id="index-integer"></span></p>
|
||
<p>integer [ {+|-}Hghlprtux ] [ {+|-}LRZi [ <code>n</code> ] ] [
|
||
<code>name</code>[=<code>value</code>] ... ]</p>
|
||
<p>Equivalent to typeset -i, except that options irrelevant to integers are
|
||
not permitted.</p>
|
||
<p><span id="index-jobs-1"></span></p>
|
||
<p>jobs [ -dlprs ] [ <code>job</code> ... ]</p>
|
||
<p>jobs -Z <code>string</code></p>
|
||
<p>Lists information about each given job, or all jobs if <code>job</code> is omitted.
|
||
The -l flag lists process IDs, and the -p flag lists process groups. If
|
||
the -r flag is specified only running jobs will be listed and if the -s
|
||
flag is given only stopped jobs are shown. If the -d flag is given, the
|
||
directory from which the job was started (which may not be the current
|
||
directory of the job) will also be shown.</p>
|
||
<p>The -Z option replaces the shell’s argument and environment space with
|
||
the given string, truncated if necessary to fit. This will normally be
|
||
visible in ps (ps(1)) listings. This feature is typically used by
|
||
daemons, to indicate their state.</p>
|
||
<p>Full job control is only available in the top-level interactive shell,
|
||
not in commands run in the left hand side of pipelines or within the
|
||
(<code>...</code>) construct. However, a snapshot of the job state at that point is
|
||
taken, so it is still possible to use the jobs builtin, or any parameter
|
||
providing job information. This gives information about the state of
|
||
jobs at the point the subshell was created. If background processes are
|
||
created within the subshell, then instead information about those
|
||
processes is provided.</p>
|
||
<p>For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">sleep 10 & # Job in background
|
||
( # Shell forks
|
||
jobs # Shows information about "sleep 10 &"
|
||
sleep 5 & # Process in background (no job control)
|
||
jobs # Shows information about "sleep 5 &"
|
||
)
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-kill"></span> <span id="index-killing-jobs"></span>
|
||
<span id="index-jobs_002c-killing"></span></p>
|
||
<p>kill [ -s <code>signal_name</code> | -n <code>signal_number</code> | -<code>sig</code> ] <code>job</code> ...</p>
|
||
<p>kill -l [ <code>sig</code> ... ]</p>
|
||
<p>Sends either SIGTERM or the specified signal to the given jobs or
|
||
processes. Signals are given by number or by names, with or without the
|
||
‘SIG’ prefix. If the signal being sent is not ‘KILL’ or ‘CONT’, then the
|
||
job will be sent a ‘CONT’ signal if it is stopped. The argument <code>job</code>
|
||
can be the process ID of a job not in the job list. In the second form,
|
||
kill -l, if <code>sig</code> is not specified the signal names are listed.
|
||
Otherwise, for each <code>sig</code> that is a name, the corresponding signal
|
||
number is listed. For each <code>sig</code> that is a signal number or a number
|
||
representing the exit status of a process which was terminated or
|
||
stopped by a signal the name of the signal is printed.</p>
|
||
<p>On some systems, alternative signal names are allowed for a few signals.
|
||
Typical examples are SIGCHLD and SIGCLD or SIGPOLL and SIGIO, assuming
|
||
they correspond to the same signal number. kill -l will only list the
|
||
preferred form, however kill -l <code>alt</code> will show if the alternative form
|
||
corresponds to a signal number. For example, under Linux kill -l IO and
|
||
kill -l POLL both output 29, hence kill -IO and kill -POLL have the same
|
||
effect.</p>
|
||
<p>Many systems will allow process IDs to be negative to kill a process
|
||
group or zero to kill the current process group.</p>
|
||
<p><span id="index-let"></span></p>
|
||
<p>let <code>arg</code> ...</p>
|
||
<p>Evaluate each <code>arg</code> as an arithmetic expression. See <a href="Arithmetic-Evaluation.html#Arithmetic-Evaluation">Arithmetic
|
||
Evaluation</a> for a
|
||
description of arithmetic expressions. The exit status is 0 if the value
|
||
of the last expression is nonzero, 1 if it is zero, and 2 if an error
|
||
occurred.</p>
|
||
<p><span id="index-limit"></span> <span id="index-resource-limits"></span>
|
||
<span id="index-limits_002c-resource"></span></p>
|
||
<p>limit [ -hs ] [ <code>resource</code> [ <code>limit</code> ] ] ...</p>
|
||
<p>Set or display resource limits. Unless the -s flag is given, the limit
|
||
applies only the children of the shell. If -s is given without other
|
||
arguments, the resource limits of the current shell is set to the
|
||
previously set resource limits of the children.</p>
|
||
<p>If <code>limit</code> is not specified, print the current limit placed on
|
||
<code>resource</code>, otherwise set the limit to the specified value. If the -h
|
||
flag is given, use hard limits instead of soft limits. If no <code>resource</code>
|
||
is given, print all limits.</p>
|
||
<p>When looping over multiple resources, the shell will abort immediately
|
||
if it detects a badly formed argument. However, if it fails to set a
|
||
limit for some other reason it will continue trying to set the remaining
|
||
limits.</p>
|
||
<p><code>resource</code> can be one of:</p>
|
||
<p>addressspace<br />
|
||
Maximum amount of address space used.</p>
|
||
<p>aiomemorylocked<br />
|
||
Maximum amount of memory locked in RAM for AIO operations.</p>
|
||
<p>aiooperations<br />
|
||
Maximum number of AIO operations.</p>
|
||
<p>cachedthreads<br />
|
||
Maximum number of cached threads.</p>
|
||
<p>coredumpsize<br />
|
||
Maximum size of a core dump.</p>
|
||
<p>cputime<br />
|
||
Maximum CPU seconds per process.</p>
|
||
<p>datasize<br />
|
||
Maximum data size (including stack) for each process.</p>
|
||
<p>descriptors<br />
|
||
Maximum value for a file descriptor.</p>
|
||
<p>filesize<br />
|
||
Largest single file allowed.</p>
|
||
<p>kqueues<br />
|
||
Maximum number of kqueues allocated.</p>
|
||
<p>maxproc<br />
|
||
Maximum number of processes.</p>
|
||
<p>maxpthreads<br />
|
||
Maximum number of threads per process.</p>
|
||
<p>memorylocked<br />
|
||
Maximum amount of memory locked in RAM.</p>
|
||
<p>memoryuse<br />
|
||
Maximum resident set size.</p>
|
||
<p>msgqueue<br />
|
||
Maximum number of bytes in POSIX message queues.</p>
|
||
<p>posixlocks<br />
|
||
Maximum number of POSIX locks per user.</p>
|
||
<p>pseudoterminals<br />
|
||
Maximum number of pseudo-terminals.</p>
|
||
<p>resident<br />
|
||
Maximum resident set size.</p>
|
||
<p>sigpending<br />
|
||
Maximum number of pending signals.</p>
|
||
<p>sockbufsize<br />
|
||
Maximum size of all socket buffers.</p>
|
||
<p>stacksize<br />
|
||
Maximum stack size for each process.</p>
|
||
<p>swapsize<br />
|
||
Maximum amount of swap used.</p>
|
||
<p>vmemorysize<br />
|
||
Maximum amount of virtual memory.</p>
|
||
<p>Which of these resource limits are available depends on the system.
|
||
<code>resource</code> can be abbreviated to any unambiguous prefix. It can also be
|
||
an integer, which corresponds to the integer defined for the resource by
|
||
the operating system.</p>
|
||
<p>If argument corresponds to a number which is out of the range of the
|
||
resources configured into the shell, the shell will try to read or write
|
||
the limit anyway, and will report an error if this fails. As the shell
|
||
does not store such resources internally, an attempt to set the limit
|
||
will fail unless the -s option is present.</p>
|
||
<p><code>limit</code> is a number, with an optional scaling factor, as follows:</p>
|
||
<p><code>n</code>h<br />
|
||
hours</p>
|
||
<p><code>n</code>k<br />
|
||
kilobytes (default)</p>
|
||
<p><code>n</code>m<br />
|
||
megabytes or minutes</p>
|
||
<p><code>n</code>g<br />
|
||
gigabytes</p>
|
||
<p>[<code>mm</code>:]<code>ss</code><br />
|
||
minutes and seconds</p>
|
||
<p>The limit command is not made available by default when the shell starts
|
||
in a mode emulating another shell. It can be made available with the
|
||
command ‘zmodload -F zsh/rlimits b:limit’.</p>
|
||
<p><span id="index-local"></span></p>
|
||
<p>local [ {+|-}AHUahlprtux ] [ {+|-}EFLRZi [ <code>n</code> ] ] [
|
||
<code>name</code>[=<code>value</code>] ... ]</p>
|
||
<p>Same as typeset, except that the options -g, and -f are not permitted.
|
||
In this case the -x option does not force the use of -g, i.e. exported
|
||
variables will be local to functions.</p>
|
||
<p><span id="index-logout"></span></p>
|
||
<p>logout [ <code>n</code> ]</p>
|
||
<p>Same as exit, except that it only works in a login shell.</p>
|
||
<p>noglob <code>simple command</code></p>
|
||
<p>See <a href="Shell-Grammar.html#Precommand-Modifiers">Precommand Modifiers</a>.</p>
|
||
<p><span id="index-popd"></span></p>
|
||
<p>popd [ -q ] [ {+|-}<code>n</code> ]</p>
|
||
<p>Remove an entry from the directory stack, and perform a cd to the new
|
||
top directory. With no argument, the current top entry is removed. An
|
||
argument of the form ‘+<code>n</code>’ identifies a stack entry by counting from
|
||
the left of the list shown by the dirs command, starting with zero. An
|
||
argument of the form -<code>n</code> counts from the right. <span
|
||
id="index-PUSHD_005fMINUS_002c-use-of-1"></span> If the PUSHD_MINUS
|
||
option is set, the meanings of ‘+’ and ‘-’ in this context are swapped.</p>
|
||
<p>If the -q (quiet) option is specified, the hook function chpwd and the
|
||
functions in the array $chpwd_functions are not called, and the new
|
||
directory stack is not printed. This is useful for calls to popd that do
|
||
not change the environment seen by an interactive user.</p>
|
||
<p><span id="index-print"></span></p>
|
||
<p>print [ -abcDilmnNoOpPrsSz ] [ -u <code>n</code> ] [ -f <code>format</code> ] [ -C
|
||
<code>cols</code> ]</p>
|
||
<p> [ -v <code>name</code> ] [ -xX <code>tabstop</code> ] [ -R [ -en ]] [ <code>arg</code> ...
|
||
]</p>
|
||
<p>With the ‘-f’ option the arguments are printed as described by printf.
|
||
With no flags or with the flag ‘-’, the arguments are printed on the
|
||
standard output as described by echo, with the following differences:
|
||
the escape sequence ‘\M-<code>x</code>’ (or ‘\M<code>x</code>’) metafies the character <code>x</code>
|
||
(sets the highest bit), ‘\C-<code>x</code>’ (or ‘\C<code>x</code>’) produces a control
|
||
character (‘\C-@’ and ‘\C-?’ give the characters NULL and delete), a
|
||
character code in octal is represented by ‘\<code>NNN</code>’ (instead of
|
||
‘\0<code>NNN</code>’), and ‘\E’ is a synonym for ‘\e’. Finally, if not in an
|
||
escape sequence, ‘\’ escapes the following character and is not
|
||
printed.</p>
|
||
<p>-a<br />
|
||
Print arguments with the column incrementing first. Only useful with the
|
||
-c and -C options.</p>
|
||
<p>-b<br />
|
||
Recognize all the escape sequences defined for the bindkey command, see
|
||
<a href="Zsh-Line-Editor.html#Zle-Builtins">Zle Builtins</a>.</p>
|
||
<p>-c<br />
|
||
Print the arguments in columns. Unless -a is also given, arguments are
|
||
printed with the row incrementing first.</p>
|
||
<p>-C <code>cols</code><br />
|
||
Print the arguments in <code>cols</code> columns. Unless -a is also given,
|
||
arguments are printed with the row incrementing first.</p>
|
||
<p>-D<br />
|
||
Treat the arguments as paths, replacing directory prefixes with ~
|
||
expressions corresponding to directory names, as appropriate.</p>
|
||
<p>-i<br />
|
||
If given together with -o or -O, sorting is performed
|
||
case-independently.</p>
|
||
<p>-l<br />
|
||
Print the arguments separated by newlines instead of spaces. Note: if
|
||
the list of arguments is empty, print -l will still output one empty
|
||
line. To print a possibly-empty list of arguments one per line, use
|
||
print -C1, as in ‘print -rC1 – "$list[@]"’.</p>
|
||
<p>-m<br />
|
||
Take the first argument as a pattern (should be quoted), and remove it
|
||
from the argument list together with subsequent arguments that do not
|
||
match this pattern.</p>
|
||
<p>-n<br />
|
||
Do not add a newline to the output.</p>
|
||
<p>-N<br />
|
||
Print the arguments separated and terminated by nulls. Again, print
|
||
-rNC1 – "$list[@]" is a canonical way to print an arbitrary list as
|
||
null-delimited records.</p>
|
||
<p>-o<br />
|
||
Print the arguments sorted in ascending order.</p>
|
||
<p>-O<br />
|
||
Print the arguments sorted in descending order.</p>
|
||
<p>-p<br />
|
||
Print the arguments to the input of the coprocess.</p>
|
||
<p>-P<br />
|
||
Perform prompt expansion (see <a href="Prompt-Expansion.html#Prompt-Expansion">Prompt
|
||
Expansion</a>). In combination with
|
||
‘-f’, prompt escape sequences are parsed only within interpolated
|
||
arguments, not within the format string.</p>
|
||
<p>-r<br />
|
||
Ignore the escape conventions of echo.</p>
|
||
<p>-R<br />
|
||
Emulate the BSD echo command, which does not process escape sequences
|
||
unless the -e flag is given. The -n flag suppresses the trailing
|
||
newline. Only the -e and -n flags are recognized after -R; all other
|
||
arguments and options are printed.</p>
|
||
<p>-s<br />
|
||
Place the results in the history list instead of on the standard output.
|
||
Each argument to the print command is treated as a single word in the
|
||
history, regardless of its content.</p>
|
||
<p>-S<br />
|
||
Place the results in the history list instead of on the standard output.
|
||
In this case only a single argument is allowed; it will be split into
|
||
words as if it were a full shell command line. The effect is similar to
|
||
reading the line from a history file with the HIST_LEX_WORDS option
|
||
active.</p>
|
||
<p>-u <code>n</code><br />
|
||
Print the arguments to file descriptor <code>n</code>.</p>
|
||
<p>-v <code>name</code><br />
|
||
Store the printed arguments as the value of the parameter <code>name</code>.</p>
|
||
<p>-x <code>tab-stop</code><br />
|
||
Expand leading tabs on each line of output in the printed string
|
||
assuming a tab stop every <code>tab-stop</code> characters. This is appropriate for
|
||
formatting code that may be indented with tabs. Note that leading tabs
|
||
of any argument to print, not just the first, are expanded, even if
|
||
print is using spaces to separate arguments (the column count is
|
||
maintained across arguments but may be incorrect on output owing to
|
||
previous unexpanded tabs).</p>
|
||
<p>The start of the output of each print command is assumed to be aligned
|
||
with a tab stop. Widths of multibyte characters are handled if the
|
||
option MULTIBYTE is in effect. This option is ignored if other
|
||
formatting options are in effect, namely column alignment or printf
|
||
style, or if output is to a special location such as shell history or
|
||
the command line editor.</p>
|
||
<p>-X <code>tab-stop</code><br />
|
||
This is similar to -x, except that all tabs in the printed string are
|
||
expanded. This is appropriate if tabs in the arguments are</p>
|
||
<p>-z<br />
|
||
Push the arguments onto the editing buffer stack, separated by spaces.</p>
|
||
<p>If any of ‘-m’, ‘-o’ or ‘-O’ are used in combination with ‘-f’ and there
|
||
are no arguments (after the removal process in the case of ‘-m’) then
|
||
nothing is printed.</p>
|
||
<p><span id="index-printf"></span></p>
|
||
<p>printf [ -v <code>name</code> ] <code>format</code> [ <code>arg</code> ... ]</p>
|
||
<p>Print the arguments according to the format specification. Formatting
|
||
rules are the same as used in C. The same escape sequences as for echo
|
||
are recognised in the format. All C conversion specifications ending in
|
||
one of csdiouxXeEfgGn are handled. In addition to this, ‘%b’ can be used
|
||
instead of ‘%s’ to cause escape sequences in the argument to be
|
||
recognised and ‘%q’ can be used to quote the argument in such a way that
|
||
allows it to be reused as shell input. With the numeric format
|
||
specifiers, if the corresponding argument starts with a quote character,
|
||
the numeric value of the following character is used as the number to
|
||
print; otherwise the argument is evaluated as an arithmetic expression.
|
||
See <a href="Arithmetic-Evaluation.html#Arithmetic-Evaluation">Arithmetic
|
||
Evaluation</a> for a
|
||
description of arithmetic expressions. With ‘%n’, the corresponding
|
||
argument is taken as an identifier which is created as an integer
|
||
parameter.</p>
|
||
<p>Normally, conversion specifications are applied to each argument in
|
||
order but they can explicitly specify the <code>n</code>th argument is to be used
|
||
by replacing ‘%’ by ‘%<code>n</code>$’ and ‘*’ by ‘*<code>n</code>$’. It is recommended that
|
||
you do not mix references of this explicit style with the normal style
|
||
and the handling of such mixed styles may be subject to future change.</p>
|
||
<p>If arguments remain unused after formatting, the format string is reused
|
||
until all arguments have been consumed. With the print builtin, this can
|
||
be suppressed by using the -r option. If more arguments are required by
|
||
the format than have been specified, the behaviour is as if zero or an
|
||
empty string had been specified as the argument.</p>
|
||
<p>The -v option causes the output to be stored as the value of the
|
||
parameter <code>name</code>, instead of printed. If <code>name</code> is an array and the
|
||
format string is reused when consuming arguments then one array element
|
||
will be used for each use of the format string.</p>
|
||
<p><span id="index-pushd"></span> <span
|
||
id="index-PUSHD_005fTO_005fHOME_002c-use-of"></span> <span
|
||
id="index-PUSHD_005fMINUS_002c-use-of-2"></span> <span
|
||
id="index-CDABLE_005fVARS_002c-use-of"></span> <span
|
||
id="index-PUSHD_005fSILENT_002c-use-of"></span></p>
|
||
<p>pushd [ -qsLP ] [ <code>arg</code> ]</p>
|
||
<p>pushd [ -qsLP ] <code>old</code> <code>new</code></p>
|
||
<p>pushd [ -qsLP ] {+|-}<code>n</code></p>
|
||
<p>Change the current directory, and push the old current directory onto
|
||
the directory stack. In the first form, change the current directory to
|
||
<code>arg</code>. If <code>arg</code> is not specified, change to the second directory on the
|
||
stack (that is, exchange the top two entries), or change to $HOME if the
|
||
PUSHD_TO_HOME option is set or if there is only one entry on the stack.
|
||
Otherwise, <code>arg</code> is interpreted as it would be by cd. The meaning of
|
||
<code>old</code> and <code>new</code> in the second form is also the same as for cd.</p>
|
||
<p>The third form of pushd changes directory by rotating the directory
|
||
list. An argument of the form ‘+<code>n</code>’ identifies a stack entry by
|
||
counting from the left of the list shown by the dirs command, starting
|
||
with zero. An argument of the form ‘-<code>n</code>’ counts from the right. If the
|
||
PUSHD_MINUS option is set, the meanings of ‘+’ and ‘-’ in this context
|
||
are swapped.</p>
|
||
<p>If the -q (quiet) option is specified, the hook function chpwd and the
|
||
functions in the array $chpwd_functions are not called, and the new
|
||
directory stack is not printed. This is useful for calls to pushd that
|
||
do not change the environment seen by an interactive user.</p>
|
||
<p>If the option -q is not specified and the shell option PUSHD_SILENT is
|
||
not set, the directory stack will be printed after a pushd is performed.</p>
|
||
<p>The options -s, -L and -P have the same meanings as for the cd builtin.</p>
|
||
<p><span id="index-pushln"></span></p>
|
||
<p>pushln [ <code>arg</code> ... ]</p>
|
||
<p>Equivalent to print -nz.</p>
|
||
<p><span id="index-pwd"></span> <span
|
||
id="index-CHASE_005fLINKS_002c-use-of"></span></p>
|
||
<p>pwd [ -rLP ]</p>
|
||
<p>Print the absolute pathname of the current working directory. If the -r
|
||
or the -P flag is specified, or the CHASE_LINKS option is set and the -L
|
||
flag is not given, the printed path will not contain symbolic links.</p>
|
||
<p><span id="index-r"></span></p>
|
||
<p>r</p>
|
||
<p>Same as fc -e -.</p>
|
||
<p><span id="index-read"></span> <span id="index-IFS_002c-use-of-2"></span></p>
|
||
<p>read [ -rszpqAclneE ] [ -t [ <code>num</code> ] ] [ -k [ <code>num</code> ] ] [ -d
|
||
<code>delim</code> ]</p>
|
||
<p> [ -u <code>n</code> ] [ [<code>name</code>][?<code>prompt</code>] ] [ <code>name</code> ... ]</p>
|
||
<p><span id="index-REPLY_002c-use-of-2"></span> <span
|
||
id="index-reply_002c-use-of-1"></span></p>
|
||
<p>Read one line and break it into fields using the characters in $IFS as
|
||
separators, except as noted below. The first field is assigned to the
|
||
first <code>name</code>, the second field to the second <code>name</code>, etc., with leftover
|
||
fields assigned to the last <code>name</code>. If <code>name</code> is omitted then REPLY is
|
||
used for scalars and reply for arrays.</p>
|
||
<p>-r<br />
|
||
Raw mode: a ‘\’ at the end of a line does not signify line continuation
|
||
and backslashes in the line don’t quote the following character and are
|
||
not removed.</p>
|
||
<p>-s<br />
|
||
Don’t echo back characters if reading from the terminal.</p>
|
||
<p>-q<br />
|
||
Read only one character from the terminal and set <code>name</code> to ‘y’ if this
|
||
character was ‘y’ or ‘Y’ and to ‘n’ otherwise. With this flag set the
|
||
return status is zero only if the character was ‘y’ or ‘Y’. This option
|
||
may be used with a timeout (see -t); if the read times out, or
|
||
encounters end of file, status 2 is returned. Input is read from the
|
||
terminal unless one of -u or -p is present. This option may also be used
|
||
within zle widgets.</p>
|
||
<p>-k [ <code>num</code> ]<br />
|
||
Read only one (or <code>num</code>) characters. All are assigned to the first
|
||
<code>name</code>, without word splitting. This flag is ignored when -q is present.
|
||
Input is read from the terminal unless one of -u or -p is present. This
|
||
option may also be used within zle widgets.</p>
|
||
<p>Note that despite the mnemonic ‘key’ this option does read full
|
||
characters, which may consist of multiple bytes if the option MULTIBYTE
|
||
is set.</p>
|
||
<p>-z<br />
|
||
Read one entry from the editor buffer stack and assign it to the first
|
||
<code>name</code>, without word splitting. Text is pushed onto the stack with
|
||
‘print -z’ or with push-line from the line editor (see <a href="Zsh-Line-Editor.html#Zsh-Line-Editor">Zsh Line
|
||
Editor</a>). This flag is ignored
|
||
when the -k or -q flags are present.</p>
|
||
<p>-e<br />
|
||
-E<br />
|
||
The input read is printed (echoed) to the standard output. If the -e
|
||
flag is used, no input is assigned to the parameters.</p>
|
||
<p>-A<br />
|
||
The first <code>name</code> is taken as the name of an array and all words are
|
||
assigned to it.</p>
|
||
<p>-c<br />
|
||
-l<br />
|
||
These flags are allowed only if called inside a function used for
|
||
completion (specified with the -K flag to compctl). If the -c flag is
|
||
given, the words of the current command are read. If the -l flag is
|
||
given, the whole line is assigned as a scalar. If both flags are
|
||
present, -l is used and -c is ignored.</p>
|
||
<p>-n<br />
|
||
Together with -c, the number of the word the cursor is on is read. With
|
||
-l, the index of the character the cursor is on is read. Note that the
|
||
command name is word number 1, not word 0, and that when the cursor is
|
||
at the end of the line, its character index is the length of the line
|
||
plus one.</p>
|
||
<p>-u <code>n</code><br />
|
||
Input is read from file descriptor <code>n</code>.</p>
|
||
<p>-p<br />
|
||
Input is read from the coprocess.</p>
|
||
<p>-d <code>delim</code><br />
|
||
Input is terminated by the first character of <code>delim</code> instead of by
|
||
newline.</p>
|
||
<p>-t [ <code>num</code> ]<br />
|
||
Test if input is available before attempting to read. If <code>num</code> is
|
||
present, it must begin with a digit and will be evaluated to give a
|
||
number of seconds, which may be a floating point number; in this case
|
||
the read times out if input is not available within this time. If <code>num</code>
|
||
is not present, it is taken to be zero, so that read returns immediately
|
||
if no input is available. If no input is available, return status 1 and
|
||
do not set any variables.</p>
|
||
<p>This option is not available when reading from the editor buffer with
|
||
-z, when called from within completion with -c or -l, with -q which
|
||
clears the input queue before reading, or within zle where other
|
||
mechanisms should be used to test for input.</p>
|
||
<p>Note that read does not attempt to alter the input processing mode. The
|
||
default mode is canonical input, in which an entire line is read at a
|
||
time, so usually ‘read -t’ will not read anything until an entire line
|
||
has been typed. However, when reading from the terminal with -k input is
|
||
processed one key at a time; in this case, only availability of the
|
||
first character is tested, so that e.g. ‘read -t -k 2’ can still block
|
||
on the second character. Use two instances of ‘read -t -k’ if this is
|
||
not what is wanted.</p>
|
||
<p>If the first argument contains a ‘?’, the remainder of this word is used
|
||
as a <code>prompt</code> on standard error when the shell is interactive.</p>
|
||
<p>The value (exit status) of read is 1 when an end-of-file is encountered,
|
||
or when -c or -l is present and the command is not called from a compctl
|
||
function, or as described for -q. Otherwise the value is 0.</p>
|
||
<p>The behavior of some combinations of the -k, -p, -q, -u and -z flags is
|
||
undefined. Presently -q cancels all the others, -p cancels -u, -k
|
||
cancels -z, and otherwise -z cancels both -p and -u.</p>
|
||
<p>The -c or -l flags cancel any and all of -kpquz.</p>
|
||
<p><span id="index-parameters_002c-marking-readonly"></span></p>
|
||
<p>readonly</p>
|
||
<p>Same as typeset -r. With the POSIX_BUILTINS option set, same as typeset
|
||
-gr.</p>
|
||
<p><span id="index-rehash"></span></p>
|
||
<p>rehash</p>
|
||
<p>Same as hash -r.</p>
|
||
<p><span id="index-return"></span> <span
|
||
id="index-functions_002c-returning-from"></span></p>
|
||
<p>return [ <code>n</code> ]</p>
|
||
<p>Causes a shell function or ‘.’ script to return to the invoking script
|
||
with the return status specified by an arithmetic expression <code>n</code>. For
|
||
example, the following prints ‘42’:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">() { integer foo=40; return "foo + 2" }
|
||
echo $?
|
||
</code></pre>
|
||
</div>
|
||
<p>If <code>n</code> is omitted, the return status is that of the last command
|
||
executed.</p>
|
||
<p>If return was executed from a trap in a TRAP<code>NAL</code> function, the effect
|
||
is different for zero and non-zero return status. With zero status (or
|
||
after an implicit return at the end of the trap), the shell will return
|
||
to whatever it was previously processing; with a non-zero status, the
|
||
shell will behave as interrupted except that the return status of the
|
||
trap is retained. Note that the numeric value of the signal which caused
|
||
the trap is passed as the first argument, so the statement ‘return
|
||
"128+$1"’ will return the same status as if the signal had not been
|
||
trapped.</p>
|
||
<p>sched</p>
|
||
<p>See <a href="Zsh-Modules.html#The-zsh_002fsched-Module">The zsh/sched Module</a>.</p>
|
||
<p><span id="index-set"></span> <span
|
||
id="index-parameters_002c-listing"></span> <span
|
||
id="index-parameters_002c-positional"></span> <span
|
||
id="index-parameters_002c-setting-array"></span> <span
|
||
id="index-array-parameters_002c-setting"></span> <span
|
||
id="index-KSH_005fARRAYS_002c-use-of-1"></span></p>
|
||
<p>set [ {+|-}<code>options</code> | {+|-}o [ <code>option_name</code> ] ] ... [ {+|-}A
|
||
[ <code>name</code> ] ]</p>
|
||
<p> [ <code>arg</code> ... ]</p>
|
||
<p>Set the options for the shell and/or set the positional parameters, or
|
||
declare and set an array. If the -s option is given, it causes the
|
||
specified arguments to be sorted before assigning them to the positional
|
||
parameters (or to the array <code>name</code> if -A is used). With +s sort
|
||
arguments in descending order. For the meaning of the other flags, see
|
||
<a href="Options.html#Options">Options</a>. Flags may be specified by name using
|
||
the -o option. If no option name is supplied with -o, the current option
|
||
states are printed: see the description of setopt below for more
|
||
information on the format. With +o they are printed in a form that can
|
||
be used as input to the shell.</p>
|
||
<p>If the -A flag is specified, <code>name</code> is set to an array containing the
|
||
given <code>arg</code>s; if no <code>name</code> is specified, all arrays are printed together
|
||
with their values.</p>
|
||
<p>If +A is used and <code>name</code> is an array, the given arguments will replace
|
||
the initial elements of that array; if no <code>name</code> is specified, all
|
||
arrays are printed without their values.</p>
|
||
<p>The behaviour of arguments after -A <code>name</code> or +A <code>name</code> depends on
|
||
whether the option KSH_ARRAYS is set. If it is not set, all arguments
|
||
following <code>name</code> are treated as values for the array, regardless of
|
||
their form. If the option is set, normal option processing continues at
|
||
that point; only regular arguments are treated as values for the array.
|
||
This means that</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">set -A array -x -- foo
|
||
</code></pre>
|
||
</div>
|
||
<p>sets array to ‘-x -- foo’ if KSH_ARRAYS is not set, but sets the array
|
||
to foo and turns on the option ‘-x’ if it is set.</p>
|
||
<p>If the -A flag is not present, but there are arguments beyond the
|
||
options, the positional parameters are set. If the option list (if any)
|
||
is terminated by ‘--’, and there are no further arguments, the
|
||
positional parameters will be unset.</p>
|
||
<p>If no arguments and no ‘--’ are given, then the names and values of all
|
||
parameters are printed on the standard output. If the only argument is
|
||
‘+’, the names of all parameters are printed.</p>
|
||
<p>For historical reasons, ‘set -’ is treated as ‘set +xv’ and ‘set -
|
||
<code>args</code>’ as ‘set +xv – <code>args</code>’ when in any other emulation mode than
|
||
zsh’s native mode.</p>
|
||
<p>setcap</p>
|
||
<p>See <a href="Zsh-Modules.html#The-zsh_002fcap-Module">The zsh/cap Module</a>.</p>
|
||
<p><span id="index-setopt"></span> <span
|
||
id="index-options_002c-setting"></span></p>
|
||
<p>setopt [ {+|-}<code>options</code> | {+|-}o <code>option_name</code> ] [ -m ] [ <code>name</code>
|
||
... ]</p>
|
||
<p>Set the options for the shell. All options specified either with flags
|
||
or by name are set.</p>
|
||
<p>If no arguments are supplied, the names of all options currently set are
|
||
printed. The form is chosen so as to minimize the differences from the
|
||
default options for the current emulation (the default emulation being
|
||
native zsh, shown as <Z> in <a href="Options.html#Description-of-Options">Description of
|
||
Options</a>). Options that are on by
|
||
default for the emulation are shown with the prefix no only if they are
|
||
off, while other options are shown without the prefix no and only if
|
||
they are on. In addition to options changed from the default state by
|
||
the user, any options activated automatically by the shell (for example,
|
||
SHIN_STDIN or INTERACTIVE) will be shown in the list. The format is
|
||
further modified by the option KSH_OPTION_PRINT, however the rationale
|
||
for choosing options with or without the no prefix remains the same in
|
||
this case.</p>
|
||
<p>If the -m flag is given the arguments are taken as patterns (which
|
||
should be quoted to protect them from filename expansion), and all
|
||
options with names matching these patterns are set.</p>
|
||
<p>Note that a bad option name does not cause execution of subsequent shell
|
||
code to be aborted; this is behaviour is different from that of ‘set
|
||
-o’. This is because set is regarded as a special builtin by the POSIX
|
||
standard, but setopt is not.</p>
|
||
<p><span id="index-shift"></span> <span
|
||
id="index-parameters_002c-positional-1"></span></p>
|
||
<p>shift [ -p ] [ <code>n</code> ] [ <code>name</code> ... ]</p>
|
||
<p>The positional parameters ${<code>n</code>+1} ... are renamed to $1 ..., where <code>n</code>
|
||
is an arithmetic expression that defaults to 1. If any <code>name</code>s are given
|
||
then the arrays with these names are shifted instead of the positional
|
||
parameters.</p>
|
||
<p>If the option -p is given arguments are instead removed (popped) from
|
||
the end rather than the start of the array.</p>
|
||
<p><span id="index-source"></span></p>
|
||
<p>source <code>file</code> [ <code>arg</code> ... ]</p>
|
||
<p>Same as ‘.’, except that the current directory is always searched and is
|
||
always searched first, before directories in $path.</p>
|
||
<p>stat</p>
|
||
<p>See <a href="Zsh-Modules.html#The-zsh_002fstat-Module">The zsh/stat Module</a>.</p>
|
||
<p><span id="index-suspend"></span> <span
|
||
id="index-shell_002c-suspending"></span> <span
|
||
id="index-suspending-the-shell"></span></p>
|
||
<p>suspend [ -f ]</p>
|
||
<p>Suspend the execution of the shell (send it a SIGTSTP) until it receives
|
||
a SIGCONT. Unless the -f option is given, this will refuse to suspend a
|
||
login shell.</p>
|
||
<p><span id="index-test"></span></p>
|
||
<p>test [ <code>arg</code> ... ]</p>
|
||
<p>[ [ <code>arg</code> ... ] ]</p>
|
||
<p>Like the system version of test. Added for compatibility; use
|
||
conditional expressions instead (see <a href="Conditional-Expressions.html#Conditional-Expressions">Conditional
|
||
Expressions</a>). The
|
||
main differences between the conditional expression syntax and the test
|
||
and [ builtins are: these commands are not handled syntactically, so
|
||
for example an empty variable expansion may cause an argument to be
|
||
omitted; syntax errors cause status 2 to be returned instead of a shell
|
||
error; and arithmetic operators expect integer arguments rather than
|
||
arithmetic expressions.</p>
|
||
<p>The command attempts to implement POSIX and its extensions where these
|
||
are specified. Unfortunately there are intrinsic ambiguities in the
|
||
syntax; in particular there is no distinction between test operators and
|
||
strings that resemble them. The standard attempts to resolve these for
|
||
small numbers of arguments (up to four); for five or more arguments
|
||
compatibility cannot be relied on. Users are urged wherever possible to
|
||
use the ‘[[’ test syntax which does not have these ambiguities.</p>
|
||
<p><span id="index-times"></span> <span
|
||
id="index-shell_002c-timing"></span> <span
|
||
id="index-timing-the-shell"></span></p>
|
||
<p>times</p>
|
||
<p>Print the accumulated user and system times for the shell and for
|
||
processes run from the shell.</p>
|
||
<p><span id="index-trap"></span> <span
|
||
id="index-signals_002c-trapping-1"></span> <span
|
||
id="index-trapping-signals-1"></span></p>
|
||
<p>trap [ <code>arg</code> ] [ <code>sig</code> ... ]</p>
|
||
<p><code>arg</code> is a series of commands (usually quoted to protect it from
|
||
immediate evaluation by the shell) to be read and executed when the
|
||
shell receives any of the signals specified by one or more <code>sig</code> args.
|
||
Each <code>sig</code> can be given as a number, or as the name of a signal either
|
||
with or without the string SIG in front (e.g. 1, HUP, and SIGHUP are all
|
||
the same signal).</p>
|
||
<p>If <code>arg</code> is ‘-’, then the specified signals are reset to their defaults,
|
||
or, if no <code>sig</code> args are present, all traps are reset.</p>
|
||
<p>If <code>arg</code> is an empty string, then the specified signals are ignored by
|
||
the shell (and by the commands it invokes).</p>
|
||
<p>If <code>arg</code> is omitted but one or more <code>sig</code> args are provided (i.e. the
|
||
first argument is a valid signal number or name), the effect is the same
|
||
as if <code>arg</code> had been specified as ‘-’.</p>
|
||
<p>The trap command with no arguments prints a list of commands associated
|
||
with each signal.</p>
|
||
<p>If <code>sig</code> is ZERR then <code>arg</code> will be executed after each command with a
|
||
nonzero exit status. ERR is an alias for ZERR on systems that have no
|
||
SIGERR signal (this is the usual case).</p>
|
||
<p>If <code>sig</code> is DEBUG then <code>arg</code> will be executed before each command if the
|
||
option DEBUG_BEFORE_CMD is set (as it is by default), else after each
|
||
command. Here, a ‘command’ is what is described as a ‘sublist’ in the
|
||
shell grammar, see <a href="Shell-Grammar.html#Simple-Commands-_0026-Pipelines">Simple Commands &
|
||
Pipelines</a>. If
|
||
DEBUG_BEFORE_CMD is set various additional features are available.
|
||
First, it is possible to skip the next command by setting the option
|
||
ERR_EXIT; see the description of the ERR_EXIT option in <a href="Options.html#Description-of-Options">Description of
|
||
Options</a>. Also, the shell parameter
|
||
ZSH_DEBUG_CMD is set to the string corresponding to the command to be
|
||
executed following the trap. Note that this string is reconstructed from
|
||
the internal format and may not be formatted the same way as the
|
||
original text. The parameter is unset after the trap is executed.</p>
|
||
<p>If <code>sig</code> is 0 or EXIT and the trap statement is executed inside the body
|
||
of a function, then the command <code>arg</code> is executed after the function
|
||
completes. The value of $? at the start of execution is the exit status
|
||
of the shell or the return status of the function exiting. If <code>sig</code> is 0
|
||
or EXIT and the trap statement is not executed inside the body of a
|
||
function, then the command <code>arg</code> is executed when the shell terminates;
|
||
the trap runs before any zshexit hook functions.</p>
|
||
<p>ZERR, DEBUG, and EXIT traps are not executed inside other traps. ZERR
|
||
and DEBUG traps are kept within subshells, while other traps are reset.</p>
|
||
<p>Note that traps defined with the trap builtin are slightly different
|
||
from those defined as ‘TRAP<code>NAL</code> () { ... }’, as the latter have their
|
||
own function environment (line numbers, local variables, etc.) while the
|
||
former use the environment of the command in which they were called. For
|
||
example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">trap 'print $LINENO' DEBUG
|
||
</code></pre>
|
||
</div>
|
||
<p>will print the line number of a command executed after it has run, while</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">TRAPDEBUG() { print $LINENO; }
|
||
</code></pre>
|
||
</div>
|
||
<p>will always print the number zero.</p>
|
||
<p>Alternative signal names are allowed as described under kill above.
|
||
Defining a trap under either name causes any trap under an alternative
|
||
name to be removed. However, it is recommended that for consistency
|
||
users stick exclusively to one name or another.</p>
|
||
<p><span id="index-true"></span> <span
|
||
id="index-doing-nothing_002c-successfully"></span></p>
|
||
<p>true [ <code>arg</code> ... ]</p>
|
||
<p>Do nothing and return an exit status of 0.</p>
|
||
<p><span id="index-ttyctl"></span> <span
|
||
id="index-tty_002c-freezing"></span></p>
|
||
<p>ttyctl [ -fu ]</p>
|
||
<p>The -f option freezes the tty (i.e. terminal or terminal emulator), and
|
||
-u unfreezes it. When the tty is frozen, no changes made to the tty
|
||
settings by external programs will be honored by the shell, except for
|
||
changes in the size of the screen; the shell will simply reset the
|
||
settings to their previous values as soon as each command exits or is
|
||
suspended. Thus, stty and similar programs have no effect when the tty
|
||
is frozen. Freezing the tty does not cause the current state to be
|
||
remembered: instead, it causes future changes to the state to be
|
||
blocked.</p>
|
||
<p>Without options it reports whether the terminal is frozen or not.</p>
|
||
<p>Note that, regardless of whether the tty is frozen or not, the shell
|
||
needs to change the settings when the line editor starts, so unfreezing
|
||
the tty does not guarantee settings made on the command line are
|
||
preserved. Strings of commands run between editing the command line will
|
||
see a consistent tty state. See also the shell variable STTY for a means
|
||
of initialising the tty before running external commands and/or freezing
|
||
the tty around a single command.</p>
|
||
<p><span id="index-type"></span></p>
|
||
<p>type [ -wfpamsS ] <code>name</code> ...</p>
|
||
<p>Equivalent to whence -v.</p>
|
||
<p><span id="index-typeset"></span> <span
|
||
id="index-parameters_002c-setting"></span> <span
|
||
id="index-parameters_002c-declaring"></span></p>
|
||
<p>typeset [ {+|-}AHUaghlmrtux ] [ {+|-}EFLRZip [ <code>n</code> ] ]</p>
|
||
<p> [ + ] [ <code>name</code>[=<code>value</code>] ... ]</p>
|
||
<p>typeset -T [ {+|-}Uglrux ] [ {+|-}LRZp [ <code>n</code> ] ]</p>
|
||
<p> [ + | <code>SCALAR</code>[=<code>value</code>] <code>array</code>[=(<code>value</code> ...)] [ <code>sep</code>
|
||
] ]</p>
|
||
<p>typeset -f [ {+|-}TUkmtuz ] [ + ] [ <code>name</code> ... ]</p>
|
||
<p>Set or display attributes and values for shell parameters.</p>
|
||
<p>Except as noted below for control flags that change the behavior, a
|
||
parameter is created for each <code>name</code> that does not already refer to one.
|
||
When inside a function, a new parameter is created for every <code>name</code>
|
||
(even those that already exist), and is unset again when the function
|
||
completes. See <a href="Parameters.html#Local-Parameters">Local Parameters</a>. The
|
||
same rules apply to special shell parameters, which retain their special
|
||
attributes when made local.</p>
|
||
<p>For each <code>name</code>=<code>value</code> assignment, the parameter <code>name</code> is set to
|
||
<code>value</code>. If the assignment is omitted and <code>name</code> does <em>not</em> refer to an
|
||
existing parameter, a new parameter is intialized to empty string, zero,
|
||
or empty array (as appropriate), <em>unless</em> the shell option
|
||
TYPESET_TO_UNSET is set. When that option is set, the parameter
|
||
attributes are recorded but the parameter remains unset.</p>
|
||
<p>If the shell option TYPESET_SILENT is not set, for each remaining <code>name</code>
|
||
that refers to a parameter that is already set, the name and value of
|
||
the parameter are printed in the form of an assignment. Nothing is
|
||
printed for newly-created parameters, or when any attribute flags listed
|
||
below are given along with the <code>name</code>. Using ‘+’ instead of minus to
|
||
introduce an attribute turns it off.</p>
|
||
<p>If no <code>name</code> is present, the names and values of all parameters are
|
||
printed. In this case the attribute flags restrict the display to only
|
||
those parameters that have the specified attributes, and using ‘+’
|
||
rather than ‘-’ to introduce the flag suppresses printing of the values
|
||
of parameters when there is no parameter name.</p>
|
||
<p>All forms of the command handle scalar assignment. Array assignment is
|
||
possible if any of the reserved words declare, export, float, integer,
|
||
local, readonly or typeset is matched when the line is parsed (N.B. not
|
||
when it is executed). In this case the arguments are parsed as
|
||
assignments, except that the ‘+=’ syntax and the GLOB_ASSIGN option are
|
||
not supported, and scalar values after = are <em>not</em> split further into
|
||
words, even if expanded (regardless of the setting of the KSH_TYPESET
|
||
option; this option is obsolete).</p>
|
||
<p>Examples of the differences between command and reserved word parsing:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh"># Reserved word parsing
|
||
typeset svar=$(echo one word) avar=(several words)
|
||
</code></pre>
|
||
</div>
|
||
<p>The above creates a scalar parameter svar and an array parameter avar as
|
||
if the assignments had been</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">svar="one word"
|
||
avar=(several words)
|
||
</code></pre>
|
||
</div>
|
||
<p>On the other hand:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh"># Normal builtin interface
|
||
builtin typeset svar=$(echo two words)
|
||
</code></pre>
|
||
</div>
|
||
<p>The builtin keyword causes the above to use the standard builtin
|
||
interface to typeset in which argument parsing is performed in the same
|
||
way as for other commands. This example creates a scalar svar containing
|
||
the value two and another scalar parameter words with no value. An array
|
||
value in this case would either cause an error or be treated as an
|
||
obscure set of glob qualifiers.</p>
|
||
<p>Arbitrary arguments are allowed if they take the form of assignments
|
||
after command line expansion; however, these only perform scalar
|
||
assignment:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">var='svar=val'
|
||
typeset $var
|
||
</code></pre>
|
||
</div>
|
||
<p>The above sets the scalar parameter svar to the value val. Parentheses
|
||
around the value within var would not cause array assignment as they
|
||
will be treated as ordinary characters when $var is substituted. Any
|
||
non-trivial expansion in the name part of the assignment causes the
|
||
argument to be treated in this fashion:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">typeset {var1,var2,var3}=name
|
||
</code></pre>
|
||
</div>
|
||
<p>The above syntax is valid, and has the expected effect of setting the
|
||
three parameters to the same value, but the command line is parsed as a
|
||
set of three normal command line arguments to typeset after expansion.
|
||
Hence it is not possible to assign to multiple arrays by this means.</p>
|
||
<p>Note that each interface to any of the commands may be disabled
|
||
separately. For example, ‘disable -r typeset’ disables the reserved word
|
||
interface to typeset, exposing the builtin interface, while ‘disable
|
||
typeset’ disables the builtin. Note that disabling the reserved word
|
||
interface for typeset may cause problems with the output of ‘typeset
|
||
-p’, which assumes the reserved word interface is available in order to
|
||
restore array and associative array values.</p>
|
||
<p>Unlike parameter assignment statements, typeset’s exit status on an
|
||
assignment that involves a command substitution does not reflect the
|
||
exit status of the command substitution. Therefore, to test for an error
|
||
in a command substitution, separate the declaration of the parameter
|
||
from its initialization:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh"># WRONG
|
||
typeset var1=$(exit 1) || echo "Trouble with var1"
|
||
|
||
# RIGHT
|
||
typeset var1 && var1=$(exit 1) || echo "Trouble with var1"
|
||
</code></pre>
|
||
</div>
|
||
<p>To initialize a parameter <code>param</code> to a command output and mark it
|
||
readonly, use typeset -r <code>param</code> or readonly <code>param</code> after the parameter
|
||
assignment statement.</p>
|
||
<p>If no attribute flags are given, and either no <code>name</code> arguments are
|
||
present or the flag +m is used, then each parameter name printed is
|
||
preceded by a list of the attributes of that parameter (array,
|
||
association, exported, float, integer, readonly, or undefined for
|
||
autoloaded parameters not yet loaded). If +m is used with attribute
|
||
flags, and all those flags are introduced with +, the matching parameter
|
||
names are printed but their values are not.</p>
|
||
<p>The following control flags change the behavior of typeset:</p>
|
||
<p>+<br />
|
||
If ‘+’ appears by itself in a separate word as the last option, then the
|
||
names of all parameters (functions with -f) are printed, but the values
|
||
(function bodies) are not. No <code>name</code> arguments may appear, and it is an
|
||
error for any other options to follow ‘+’. The effect of ‘+’ is as if
|
||
all attribute flags which precede it were given with a ‘+’ prefix. For
|
||
example, ‘typeset -U +’ is equivalent to ‘typeset +U’ and displays the
|
||
names of all arrays having the uniqueness attribute, whereas ‘typeset -f
|
||
-U +’ displays the names of all autoloadable functions. If + is the only
|
||
option, then type information (array, readonly, etc.) is also printed
|
||
for each parameter, in the same manner as ‘typeset +m "*"’.</p>
|
||
<p>-g<br />
|
||
The -g (global) means that any resulting parameter will not be
|
||
restricted to local scope. Note that this does not necessarily mean that
|
||
the parameter will be global, as the flag will apply to any existing
|
||
parameter (even if unset) from an enclosing function. This flag does not
|
||
affect the parameter after creation, hence it has no effect when listing
|
||
existing parameters, nor does the flag +g have any effect except in
|
||
combination with -m (see below).</p>
|
||
<p>-m<br />
|
||
If the -m flag is given the <code>name</code> arguments are taken as patterns (use
|
||
quoting to prevent these from being interpreted as file patterns). With
|
||
no attribute flags, all parameters (or functions with the -f flag) with
|
||
matching names are printed (the shell option TYPESET_SILENT is not used
|
||
in this case).</p>
|
||
<p>If the +g flag is combined with -m, a new local parameter is created for
|
||
every matching parameter that is not already local. Otherwise -m applies
|
||
all other flags or assignments to the existing parameters.</p>
|
||
<p>Except when assignments are made with <code>name</code>=<code>value</code>, using +m forces
|
||
the matching parameters and their attributes to be printed, even inside
|
||
a function. Note that -m is ignored if no patterns are given, so
|
||
‘typeset -m’ displays attributes but ‘typeset -a +m’ does not.</p>
|
||
<p>-p [ <code>n</code> ]<br />
|
||
If the -p option is given, parameters and values are printed in the form
|
||
of a typeset command with an assignment, regardless of other flags and
|
||
options. Note that the -H flag on parameters is respected; no value will
|
||
be shown for these parameters.</p>
|
||
<p>-p may be followed by an optional integer argument. Currently only the
|
||
value 1 is supported. In this case arrays and associative arrays are
|
||
printed with newlines between indented elements for readability.</p>
|
||
<p>-T [ <code>scalar</code>[=<code>value</code>] <code>array</code>[=(<code>value</code> ...)] [ <code>sep</code> ] ]<br />
|
||
This flag has a different meaning when used with -f; see below.
|
||
Otherwise the -T option requires zero, two, or three arguments to be
|
||
present. With no arguments, the list of parameters created in this
|
||
fashion is shown. With two or three arguments, the first two are the
|
||
name of a scalar and of an array parameter (in that order) that will be
|
||
tied together in the manner of $PATH and $path. The optional third
|
||
argument is a single-character separator which will be used to join the
|
||
elements of the array to form the scalar; if absent, a colon is used, as
|
||
with $PATH. Only the first character of the separator is significant;
|
||
any remaining characters are ignored. Multibyte characters are not yet
|
||
supported.</p>
|
||
<p>Only one of the scalar and array parameters may be assigned an initial
|
||
value (the restrictions on assignment forms described above also apply).</p>
|
||
<p>Both the scalar and the array may be manipulated as normal. If one is
|
||
unset, the other will automatically be unset too. There is no way of
|
||
untying the variables without unsetting them, nor of converting the type
|
||
of one of them with another typeset command; +T does not work, assigning
|
||
an array to <code>scalar</code> is an error, and assigning a scalar to <code>array</code> sets
|
||
it to be a single-element array.</p>
|
||
<p>Note that both ‘typeset -xT ...’ and ‘export -T ...’ work, but only the
|
||
scalar will be marked for export. Setting the value using the scalar
|
||
version causes a split on all separators (which cannot be quoted). It is
|
||
possible to apply -T to two previously tied variables but with a
|
||
different separator character, in which case the variables remain joined
|
||
as before but the separator is changed.</p>
|
||
<p>When an existing scalar is tied to a new array, the value of the scalar
|
||
is preserved but no attribute other than export will be preserved.</p>
|
||
<p>Attribute flags that transform the final value (-L, -R, -Z, -l, -u) are
|
||
only applied to the expanded value at the point of a parameter expansion
|
||
expression using ‘$’. They are not applied when a parameter is retrieved
|
||
internally by the shell for any purpose.</p>
|
||
<p>The following attribute flags may be specified:</p>
|
||
<p>-A<br />
|
||
The names refer to associative array parameters; see <a href="Parameters.html#Array-Parameters">Array
|
||
Parameters</a>.</p>
|
||
<p>-L [ <code>n</code> ]<br />
|
||
Left justify and remove leading blanks from the value when the parameter
|
||
is expanded. If <code>n</code> is nonzero, it defines the width of the field. If
|
||
<code>n</code> is zero, the width is determined by the width of the value of the
|
||
first assignment. In the case of numeric parameters, the length of the
|
||
complete value assigned to the parameter is used to determine the width,
|
||
not the value that would be output.</p>
|
||
<p>The width is the count of characters, which may be multibyte characters
|
||
if the MULTIBYTE option is in effect. Note that the screen width of the
|
||
character is not taken into account; if this is required, use padding
|
||
with parameter expansion flags ${(ml<code>...</code>)<code>...</code>} as described in
|
||
‘Parameter Expansion Flags’ in <a href="Expansion.html#Parameter-Expansion">Parameter
|
||
Expansion</a>.</p>
|
||
<p>When the parameter is expanded, it is filled on the right with blanks or
|
||
truncated if necessary to fit the field. Note truncation can lead to
|
||
unexpected results with numeric parameters. Leading zeros are removed if
|
||
the -Z flag is also set.</p>
|
||
<p>-R [ <code>n</code> ]<br />
|
||
Similar to -L, except that right justification is used; when the
|
||
parameter is expanded, the field is left filled with blanks or truncated
|
||
from the end. May not be combined with the -Z flag.</p>
|
||
<p>-U<br />
|
||
For arrays (but not for associative arrays), keep only the first
|
||
occurrence of each duplicated value. This may also be set for tied
|
||
parameters (see -T) or colon-separated special parameters like PATH or
|
||
FIGNORE, etc. Note the flag takes effect on assignment, and the type of
|
||
the variable being assigned to is determinative; for variables with
|
||
shared values it is therefore recommended to set the flag for all
|
||
interfaces, e.g. ‘typeset -U PATH path’.</p>
|
||
<p>This flag has a different meaning when used with -f; see below.</p>
|
||
<p>-Z [ <code>n</code> ]<br />
|
||
Specially handled if set along with the -L flag. Otherwise, similar to
|
||
-R, except that leading zeros are used for padding instead of blanks if
|
||
the first non-blank character is a digit. Numeric parameters are
|
||
specially handled: they are always eligible for padding with zeroes, and
|
||
the zeroes are inserted at an appropriate place in the output.</p>
|
||
<p>-a<br />
|
||
The names refer to array parameters. An array parameter may be created
|
||
this way, but it may be assigned to in the typeset statement only if the
|
||
reserved word form of typeset is enabled (as it is by default). When
|
||
displaying, both normal and associative arrays are shown.</p>
|
||
<p>-f<br />
|
||
The names refer to functions rather than parameters. No assignments can
|
||
be made, and the only other valid flags are -t, -T, -k, -u, -U and -z.
|
||
The flag -t turns on execution tracing for this function; the flag -T
|
||
does the same, but turns off tracing for any named (not anonymous)
|
||
function called from the present one, unless that function also has the
|
||
-t or -T flag. The -u and -U flags cause the function to be marked for
|
||
autoloading; -U also causes alias expansion to be suppressed when the
|
||
function is loaded. See the description of the ‘autoload’ builtin for
|
||
details.</p>
|
||
<p>Note that the builtin functions provides the same basic capabilities as
|
||
typeset -f but gives access to a few extra options; autoload gives
|
||
further additional options for the case typeset -fu and typeset -fU.</p>
|
||
<p>-h<br />
|
||
-H<br />
|
||
Hide value: specifies that typeset will not display the value of the
|
||
parameter when listing parameters; the display for such parameters is
|
||
always as if the ‘+’ flag had been given. Use of the parameter is in
|
||
other respects normal, and the option does not apply if the parameter is
|
||
specified by name, or by pattern with the -m option. This is on by
|
||
default for the parameters in the zsh/parameter and zsh/mapfile modules.
|
||
Note, however, that unlike the -h flag this is also useful for
|
||
non-special parameters.</p>
|
||
<p>-i [ <code>n</code> ]<br />
|
||
Use an internal integer representation. If <code>n</code> is nonzero it defines the
|
||
output arithmetic base, otherwise it is determined by the first
|
||
assignment. Bases from 2 to 36 inclusive are allowed.</p>
|
||
<p>-E [ <code>n</code> ]<br />
|
||
Use an internal double-precision floating point representation. On
|
||
output the variable will be converted to scientific notation. If <code>n</code> is
|
||
nonzero it defines the number of significant figures to display; the
|
||
default is ten.</p>
|
||
<p>-F [ <code>n</code> ]<br />
|
||
Use an internal double-precision floating point representation. On
|
||
output the variable will be converted to fixed-point decimal notation.
|
||
If <code>n</code> is nonzero it defines the number of digits to display after the
|
||
decimal point; the default is ten.</p>
|
||
<p>-l<br />
|
||
Convert the result to lower case whenever the parameter is expanded. The
|
||
value is <em>not</em> converted when assigned.</p>
|
||
<p>-r<br />
|
||
The given <code>name</code>s are marked readonly. Note that if <code>name</code> is a special
|
||
parameter, the readonly attribute can be turned on, but cannot then be
|
||
turned off.</p>
|
||
<p>If the POSIX_BUILTINS option is set, the readonly attribute is more
|
||
restrictive: unset variables can be marked readonly and cannot then be
|
||
set; furthermore, the readonly attribute cannot be removed from any
|
||
variable.</p>
|
||
<p>It is still possible to change other attributes of the variable though,
|
||
some of which like -U or -Z would affect the value. More generally, the
|
||
readonly attribute should not be relied on as a security mechanism.</p>
|
||
<p>Note that in zsh (like in pdksh but unlike most other shells) it is
|
||
still possible to create a local variable of the same name as this is
|
||
considered a different variable (though this variable, too, can be
|
||
marked readonly). Special variables that have been made readonly retain
|
||
their value and readonly attribute when made local.</p>
|
||
<p>-t<br />
|
||
Tags the named parameters. Tags have no special meaning to the shell.
|
||
This flag has a different meaning when used with -f; see above.</p>
|
||
<p>-u<br />
|
||
Convert the result to upper case whenever the parameter is expanded. The
|
||
value is <em>not</em> converted when assigned. This flag has a different
|
||
meaning when used with -f; see above.</p>
|
||
<p>-x<br />
|
||
Mark for automatic export to the environment of subsequently executed
|
||
commands. If the option GLOBAL_EXPORT is set, this implies the option
|
||
-g, unless +g is also explicitly given; in other words the parameter is
|
||
not made local to the enclosing function. This is for compatibility with
|
||
previous versions of zsh.</p>
|
||
<p><span id="index-ulimit"></span> <span
|
||
id="index-resource-limits-1"></span> <span
|
||
id="index-limits_002c-resource-1"></span></p>
|
||
<p>ulimit [ -HSa ] [ { -bcdfiklmnpqrsTtvwx | -N <code>resource</code> } [ <code>limit</code>
|
||
] ... ]</p>
|
||
<p>Set or display resource limits of the shell and the processes started by
|
||
the shell. The value of <code>limit</code> can be a number in the unit specified
|
||
below or one of the values ‘unlimited’, which removes the limit on the
|
||
resource, or ‘hard’, which uses the current value of the hard limit on
|
||
the resource.</p>
|
||
<p>By default, only soft limits are manipulated. If the -H flag is given
|
||
use hard limits instead of soft limits. If the -S flag is given together
|
||
with the -H flag set both hard and soft limits.</p>
|
||
<p>If no options are used, the file size limit (-f) is assumed.</p>
|
||
<p>If <code>limit</code> is omitted the current value of the specified resources are
|
||
printed. When more than one resource value is printed, the limit name
|
||
and unit is printed before each value.</p>
|
||
<p>When looping over multiple resources, the shell will abort immediately
|
||
if it detects a badly formed argument. However, if it fails to set a
|
||
limit for some other reason it will continue trying to set the remaining
|
||
limits.</p>
|
||
<p>Not all the following resources are supported on all systems. Running
|
||
ulimit -a will show which are supported.</p>
|
||
<p>-a<br />
|
||
Lists all of the current resource limits.</p>
|
||
<p>-b<br />
|
||
Socket buffer size in bytes (N.B. not kilobytes)</p>
|
||
<p>-c<br />
|
||
512-byte blocks on the size of core dumps.</p>
|
||
<p>-d<br />
|
||
Kilobytes on the size of the data segment.</p>
|
||
<p>-f<br />
|
||
512-byte blocks on the size of files written.</p>
|
||
<p>-i<br />
|
||
The number of pending signals.</p>
|
||
<p>-k<br />
|
||
The number of kqueues allocated.</p>
|
||
<p>-l<br />
|
||
Kilobytes on the size of locked-in memory.</p>
|
||
<p>-m<br />
|
||
Kilobytes on the size of physical memory.</p>
|
||
<p>-n<br />
|
||
open file descriptors.</p>
|
||
<p>-p<br />
|
||
The number of pseudo-terminals.</p>
|
||
<p>-q<br />
|
||
Bytes in POSIX message queues.</p>
|
||
<p>-r<br />
|
||
Maximum real time priority. On some systems where this is not available,
|
||
such as NetBSD, this has the same effect as -T for compatibility with
|
||
sh.</p>
|
||
<p>-s<br />
|
||
Kilobytes on the size of the stack.</p>
|
||
<p>-T<br />
|
||
The number of simultaneous threads available to the user.</p>
|
||
<p>-t<br />
|
||
CPU seconds to be used.</p>
|
||
<p>-u<br />
|
||
The number of processes available to the user.</p>
|
||
<p>-v<br />
|
||
Kilobytes on the size of virtual memory. On some systems this refers to
|
||
the limit called ‘address space’.</p>
|
||
<p>-w<br />
|
||
Kilobytes on the size of swapped out memory.</p>
|
||
<p>-x<br />
|
||
The number of locks on files.</p>
|
||
<p>A resource may also be specified by integer in the form ‘-N <code>resource</code>’,
|
||
where <code>resource</code> corresponds to the integer defined for the resource by
|
||
the operating system. This may be used to set the limits for resources
|
||
known to the shell which do not correspond to option letters. Such
|
||
limits will be shown by number in the output of ‘ulimit -a’.</p>
|
||
<p>The number may alternatively be out of the range of limits compiled into
|
||
the shell. The shell will try to read or write the limit anyway, and
|
||
will report an error if this fails.</p>
|
||
<p><span id="index-umask"></span> <span id="index-umask-1"></span></p>
|
||
<p>umask [ -S ] [ <code>mask</code> ]</p>
|
||
<p>The umask is set to <code>mask</code>. <code>mask</code> can be either an octal number or a
|
||
symbolic value as described in the chmod(1) man page. If <code>mask</code> is
|
||
omitted, the current value is printed. The -S option causes the mask to
|
||
be printed as a symbolic value. Otherwise, the mask is printed as an
|
||
octal number. Note that in the symbolic form the permissions you specify
|
||
are those which are to be allowed (not denied) to the users specified.</p>
|
||
<p><span id="index-aliases_002c-removing"></span></p>
|
||
<p>unalias [ -ams ] <code>name</code> ...</p>
|
||
<p>Removes aliases. This command works the same as unhash -a, except that
|
||
the -a option removes all regular or global aliases, or with -s all
|
||
suffix aliases: in this case no <code>name</code> arguments may appear. The options
|
||
-m (remove by pattern) and -s without -a (remove listed suffix aliases)
|
||
behave as for unhash -a. Note that the meaning of -a is different
|
||
between unalias and unhash.</p>
|
||
<p><span id="index-functions_002c-removing"></span> <span
|
||
id="index-unfunction"></span></p>
|
||
<p>unfunction</p>
|
||
<p>Same as unhash -f.</p>
|
||
<p><span id="index-unhash"></span></p>
|
||
<p>unhash [ -adfms ] <code>name</code> ...</p>
|
||
<p>option causes unhash to remove regular or global aliases; note when
|
||
removing a global aliases that the argument must be quoted to prevent it
|
||
from being expanded before being passed to the command. The -s option
|
||
causes unhash to remove suffix aliases. The -f option causes unhash to
|
||
remove shell functions. The -d options causes unhash to remove named
|
||
directories. If the -m flag is given the arguments are taken as patterns
|
||
(should be quoted) and all elements</p>
|
||
<p><span id="index-unlimit"></span> <span
|
||
id="index-resource-limits-2"></span> <span
|
||
id="index-limits_002c-resource-2"></span></p>
|
||
<p>unlimit [ -hs ] <code>resource</code> ...</p>
|
||
<p>The resource limit for each <code>resource</code> is set to the hard limit. If the
|
||
-h flag is given and the shell has appropriate privileges, the hard
|
||
resource limit for each <code>resource</code> is removed. The resources of the
|
||
shell process are only changed if the -s flag is given.</p>
|
||
<p>The unlimit command is not made available by default when the shell
|
||
starts in a mode emulating another shell. It can be made available with
|
||
the command ‘zmodload -F zsh/rlimits b:unlimit’.</p>
|
||
<p><span id="index-unset"></span> <span
|
||
id="index-parameters_002c-unsetting"></span></p>
|
||
<p>unset [ -fmv ] <code>name</code> ...</p>
|
||
<p>Each named parameter is unset. Local parameters remain local even if
|
||
unset; they appear unset within scope, but the previous value will still
|
||
reappear when the scope ends.</p>
|
||
<p>Individual elements of associative array parameters may be unset by
|
||
using subscript syntax on <code>name</code>, which should be quoted (or the entire
|
||
command prefixed with noglob) to protect the subscript from filename
|
||
generation.</p>
|
||
<p>If the -m flag is specified the arguments are taken as patterns (should
|
||
be quoted) and all parameters with matching names are unset. Note that
|
||
this cannot be used when unsetting associative array elements, as the
|
||
subscript will be treated as part of the pattern.</p>
|
||
<p>The -v flag specifies that <code>name</code> refers to parameters. This is the
|
||
default behaviour.</p>
|
||
<p>unset -f is equivalent to unfunction.</p>
|
||
<p><span id="index-unsetopt"></span> <span
|
||
id="index-options_002c-unsetting"></span></p>
|
||
<p>unsetopt [ {+|-}<code>options</code> | {+|-}o <code>option_name</code> ] [ <code>name</code> ... ]</p>
|
||
<p>Unset the options for the shell. All options specified either with flags
|
||
or by name are unset. If no arguments are supplied, the names of all
|
||
options currently unset are printed. If the -m flag is given the
|
||
arguments are taken as patterns (which should be quoted to preserve them
|
||
from being interpreted as glob patterns), and all options with names
|
||
matching these patterns are unset.</p>
|
||
<p>vared</p>
|
||
<p>See <a href="Zsh-Line-Editor.html#Zle-Builtins">Zle Builtins</a>.</p>
|
||
<p><span id="index-wait"></span> <span id="index-waiting-for-jobs"></span>
|
||
<span id="index-jobs_002c-waiting-for"></span></p>
|
||
<p>wait [ <code>job</code> ... ]</p>
|
||
<p>Wait for the specified jobs or processes. If <code>job</code> is not given then all
|
||
currently active child processes are waited for. Each <code>job</code> can be
|
||
either a job specification or the process ID The exit status from this
|
||
command is that of the job waited for. If <code>job</code> represents an unknown
|
||
job or process ID, a warning is printed (unless the POSIX_BUILTINS
|
||
option is set) and the exit status is 127.</p>
|
||
<p>It is possible to wait for recent processes (specified by process ID,
|
||
not by job) that were running in the background even if the process has
|
||
exited. Typically the process ID will be recorded by capturing the value
|
||
of the variable $! immediately after the process has been started. There
|
||
is a limit on the number of process IDs remembered by the shell; this is
|
||
given by the value of the system configuration parameter CHILD_MAX. When
|
||
this limit is reached, older process IDs are discarded, least recently
|
||
started processes first.</p>
|
||
<p>Note there is no protection against the process ID wrapping, i.e. if the
|
||
wait is not executed soon enough there is a chance the process waited
|
||
for is the wrong one. A conflict implies both process IDs have been
|
||
generated by the shell, as other processes are not recorded, and that
|
||
the user is potentially interested in both, so this problem is intrinsic
|
||
to process IDs.</p>
|
||
<p><span id="index-whence"></span></p>
|
||
<p>whence [ -vcwfpamsS ] [ -x <code>num</code> ] <code>name</code> ...</p>
|
||
<p>For each <code>name</code>, indicate how it would be interpreted if used as a
|
||
command name.</p>
|
||
<p>If <code>name</code> is not an alias, built-in command, external command, shell
|
||
function, hashed command, or a reserved word, the exit status shall be
|
||
non-zero, and — if -v, -c, or -w was passed — a message will be written
|
||
to standard output. (This is different from other shells that write that
|
||
message to standard error.)</p>
|
||
<p>whence is most useful when <code>name</code> is only the last path component of a
|
||
command, i.e. does not include a ‘/’; in particular, pattern matching
|
||
only succeeds if just the non-directory component of the command is
|
||
passed.</p>
|
||
<p>-v<br />
|
||
Produce a more verbose report.</p>
|
||
<p>-c<br />
|
||
Print the results in a csh-like format. This takes precedence over -v.</p>
|
||
<p>-w<br />
|
||
For each <code>name</code>, print ‘<code>name</code>: <code>word</code>’ where <code>word</code> is one of alias,
|
||
builtin, command, function, hashed, reserved or none, according as
|
||
<code>name</code> corresponds to an alias, a built-in command, an external command,
|
||
a shell function, a command defined with the hash builtin, a reserved
|
||
word, or is not recognised. This takes precedence over -v and -c.</p>
|
||
<p>-f<br />
|
||
Causes the contents of a shell function to be displayed, which would
|
||
otherwise not happen unless the -c flag were used.</p>
|
||
<p>-p<br />
|
||
Do a path search for <code>name</code> even if it is an alias, reserved word, shell
|
||
function or builtin.</p>
|
||
<p>-a<br />
|
||
Do a search for all occurrences of <code>name</code> throughout the command path.
|
||
Normally only the first occurrence is printed.</p>
|
||
<p>-m<br />
|
||
The arguments are taken as patterns (pattern characters should be
|
||
quoted), and the information is displayed for each command matching one
|
||
of these patterns.</p>
|
||
<p>-s<br />
|
||
If a pathname contains symlinks, print the symlink-free pathname as
|
||
well.</p>
|
||
<p>-S<br />
|
||
As -s, but if the pathname had to be resolved by following multiple
|
||
symlinks, the intermediate steps are printed, too. The symlink resolved
|
||
at each step might be anywhere in the path.</p>
|
||
<p>-x <code>num</code><br />
|
||
Expand tabs when outputting shell functions using the -c option. This
|
||
has the same effect as the -x option to the functions builtin.</p>
|
||
<p><span id="index-where"></span></p>
|
||
<p>where [ -wpmsS ] [ -x <code>num</code> ] <code>name</code> ...</p>
|
||
<p>Equivalent to whence -ca.</p>
|
||
<p><span id="index-which"></span></p>
|
||
<p>which [ -wpamsS ] [ -x <code>num</code> ] <code>name</code> ...</p>
|
||
<p>Equivalent to whence -c.</p>
|
||
<p><span id="index-zcompile"></span> <span
|
||
id="index-_002ezwc-files_002c-creation"></span> <span
|
||
id="index-compilation"></span></p>
|
||
<p>zcompile [ -U ] [ -z | -k ] [ -R | -M ] <code>file</code> [ <code>name</code> ... ]</p>
|
||
<p>zcompile -ca [ -m ] [ -R | -M ] <code>file</code> [ <code>name</code> ... ]</p>
|
||
<p>zcompile -t <code>file</code> [ <code>name</code> ... ]</p>
|
||
<p>This builtin command can be used to compile functions or scripts,
|
||
storing the compiled form in a file, and to examine files containing the
|
||
compiled form. This allows faster autoloading of functions and sourcing
|
||
of scripts by avoiding parsing of the text when the files are read.</p>
|
||
<p>The first form (without the -c, -a or -t options) creates a compiled
|
||
file. If only the <code>file</code> argument is given, the output file has the name
|
||
‘<code>file</code>.zwc’ and will be placed in the same directory as the <code>file</code>. The
|
||
shell will load the compiled file instead of the normal function file
|
||
when the function is autoloaded; see
|
||
<a href="Functions.html#Functions">Functions</a> for a description of how
|
||
autoloaded functions are searched. The extension .zwc stands for ‘zsh
|
||
word code’.</p>
|
||
<p><span id="index-fpath_002c-with-zcompile"></span></p>
|
||
<p>If there is at least one <code>name</code> argument, all the named files are
|
||
compiled into the output <code>file</code> given as the first argument. If <code>file</code>
|
||
does not end in .zwc, this extension is automatically appended. Files
|
||
containing multiple compiled functions are called ‘digest’ files, and
|
||
are intended to be used as elements of the FPATH/fpath special array.</p>
|
||
<p>The second form, with the -c or -a options, writes the compiled
|
||
definitions for all the named functions into <code>file</code>. For -c, the names
|
||
must be functions currently defined in the shell, not those marked for
|
||
autoloading. Undefined functions that are marked for autoloading may be
|
||
written by using the -a option, in which case the fpath is searched and
|
||
the contents of the definition files for those functions, if found, are
|
||
compiled into <code>file</code>. If both -c and -a are given, names of both defined
|
||
functions and functions marked for autoloading may be given. In either
|
||
case, the functions in files written with the -c or -a option will be
|
||
autoloaded as if the KSH_AUTOLOAD option were unset.</p>
|
||
<p>The reason for handling loaded and not-yet-loaded functions with
|
||
different options is that some definition files for autoloading define
|
||
multiple functions, including the function with the same name as the
|
||
file, and, at the end, call that function. In such cases the output of
|
||
‘zcompile -c’ does not include the additional functions defined in the
|
||
file, and any other initialization code in the file is lost. Using
|
||
‘zcompile -a’ captures all this extra information.</p>
|
||
<p>If the -m option is combined with -c or -a, the <code>name</code>s are used as
|
||
patterns and all functions whose names match one of these patterns will
|
||
be written. If no <code>name</code> is given, the definitions of all functions
|
||
currently defined or marked as autoloaded will be written.</p>
|
||
<p>Note the second form cannot be used for compiling functions that include
|
||
redirections as part of the definition rather than within the body of
|
||
the function; for example</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">fn1() { { ... } >~/logfile }
|
||
</code></pre>
|
||
</div>
|
||
<p>can be compiled but</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">fn1() { ... } >~/logfile
|
||
</code></pre>
|
||
</div>
|
||
<p>cannot. It is possible to use the first form of zcompile to compile
|
||
autoloadable functions that include the full function definition instead
|
||
of just the body of the function.</p>
|
||
<p>The third form, with the -t option, examines an existing compiled file.
|
||
Without further arguments, the names of the original files compiled into
|
||
it are listed. The first line of output shows the version of the shell
|
||
which compiled the file and how the file will be used (i.e. by reading
|
||
it directly or by mapping it into memory). With arguments, nothing is
|
||
output and the return status is set to zero if definitions for <em>all</em>
|
||
<code>name</code>s were found in the compiled file, and non-zero if the definition
|
||
for at least one <code>name</code> was not found.</p>
|
||
<p>Other options:</p>
|
||
<p>-U<br />
|
||
Aliases are not expanded when compiling the <code>name</code>d files.</p>
|
||
<p>-R<br />
|
||
When the compiled file is read, its contents are copied into the shell’s
|
||
memory, rather than memory-mapped (see -M). This happens automatically
|
||
on systems that do not support memory mapping.</p>
|
||
<p>When compiling scripts instead of autoloadable functions, it is often
|
||
desirable to use this option; otherwise the whole file, including the
|
||
code to define functions which have already been defined, will remain
|
||
mapped, consequently wasting memory.</p>
|
||
<p>-M<br />
|
||
The compiled file is mapped into the shell’s memory when read. This is
|
||
done in such a way that multiple instances of the shell running on the
|
||
same host will share this mapped file. If neither -R nor -M is given,
|
||
the zcompile builtin decides what to do based on the size of the
|
||
compiled file.</p>
|
||
<p>-k<br />
|
||
-z<br />
|
||
These options are used when the compiled file contains functions which
|
||
are to be autoloaded. If -z is given, the function will be autoloaded as
|
||
if the KSH_AUTOLOAD option is <em>not</em> set, even if it is set at the time
|
||
the compiled file is read, while if the -k is given, the function will
|
||
be loaded as if KSH_AUTOLOAD <em>is</em> set. These options also take
|
||
precedence over any -k or -z options specified to the autoload builtin.
|
||
If neither of these options is given, the function will be loaded as
|
||
determined by the setting of the KSH_AUTOLOAD option at the time the
|
||
compiled file is read.</p>
|
||
<p>These options may also appear as many times as necessary between the
|
||
listed <code>name</code>s to specify the loading style of all following functions,
|
||
up to the next -k or -z.</p>
|
||
<p>The created file always contains two versions of the compiled format,
|
||
one for big-endian machines and one for small-endian machines. The
|
||
upshot of this is that the compiled file is machine independent and if
|
||
it is read or mapped, only one half of the file is actually used (and
|
||
mapped).</p>
|
||
<p>zformat</p>
|
||
<p>See <a href="Zsh-Modules.html#The-zsh_002fzutil-Module">The zsh/zutil Module</a>.</p>
|
||
<p>zftp</p>
|
||
<p>See <a href="Zsh-Modules.html#The-zsh_002fzftp-Module">The zsh/zftp Module</a>.</p>
|
||
<p>zle</p>
|
||
<p>See <a href="Zsh-Line-Editor.html#Zle-Builtins">Zle Builtins</a>.</p>
|
||
<p><span id="index-zmodload"></span> <span
|
||
id="index-modules_002c-loading"></span> <span
|
||
id="index-loading-modules"></span></p>
|
||
<p>zmodload [ -dL ] [ -s ] [ ... ]</p>
|
||
<p>zmodload -F [ -alLme -P <code>param</code> ] <code>module</code> [ [+-]<code>feature</code> ... ]</p>
|
||
<p>zmodload -e [ -A ] [ ... ]</p>
|
||
<p>zmodload [ -a [ -bcpf [ -I ] ] ] [ -iL ] ...</p>
|
||
<p>zmodload -u [ -abcdpf [ -I ] ] [ -iL ] ...</p>
|
||
<p>zmodload -A [ -L ] [ <code>modalias</code>[=<code>module</code>] ... ]</p>
|
||
<p>zmodload -R <code>modalias</code> ...</p>
|
||
<p>Performs operations relating to zsh’s loadable modules. Loading of
|
||
modules while the shell is running (‘dynamical loading’) is not
|
||
available on all operating systems, or on all installations on a
|
||
particular operating system, although the zmodload command itself is
|
||
always available and can be used to manipulate modules built into
|
||
versions of the</p>
|
||
<p>Without arguments the names of all currently loaded binary modules are
|
||
printed. The -L option causes this list to be in the form of a series of
|
||
zmodload commands. Forms with arguments are:</p>
|
||
<p>zmodload [ -is ] <code>name</code> ...<br />
|
||
zmodload -u [ -i ] <code>name</code> ...<br />
|
||
In the simplest case, zmodload loads a binary module. The module must be
|
||
in a file with a name consisting of the specified <code>name</code> followed by a
|
||
standard suffix, usually ‘.so’ (‘.sl’ on HPUX). If the module to be
|
||
loaded is already loaded the duplicate module is ignored. If zmodload
|
||
detects an inconsistency, such as an invalid module name or circular
|
||
dependency list, the current code block is aborted. If it is available,
|
||
the module is loaded if necessary, while if it is not available,
|
||
non-zero status is silently returned. The option -i is accepted for
|
||
compatibility but has no effect.</p>
|
||
<p>The <code>name</code>d module is searched for in the same way a command is, using
|
||
$module_path instead of $path. However, the path search is performed
|
||
even when the module name contains a ‘/’, which it usually does. There
|
||
is no way to prevent the path search.</p>
|
||
<p>If the module supports features (see below), zmodload tries to enable
|
||
all features when loading a module. If the module was successfully
|
||
loaded but not all features could be enabled, zmodload returns status 2.</p>
|
||
<p>If the option -s is given, no error is printed if the module was not
|
||
available (though other errors indicating a problem with the module are
|
||
printed). The return status indicates if the module was loaded. This is
|
||
appropriate if the caller considers the module optional.</p>
|
||
<p>With -u, zmodload unloads modules. The same <code>name</code> must be given that
|
||
was given when the module was loaded, but it is not necessary for the
|
||
module to exist in the file system. The -i option suppresses the error
|
||
if the module is already unloaded (or was never loaded).</p>
|
||
<p>Each module has a boot and a cleanup function. The module will not be
|
||
loaded if its boot function fails. Similarly a module can only be
|
||
unloaded if its cleanup function runs successfully.</p>
|
||
<p>zmodload -F [ -almLe -P <code>param</code> ] <code>module</code> [ [+-]<code>feature</code> ... ]<br />
|
||
zmodload -F allows more selective control over the features provided by
|
||
modules. With no options apart from -F, the module named <code>module</code> is
|
||
loaded, if it was not already loaded, and the list of <code>feature</code>s is set
|
||
to the required state. If no <code>feature</code>s are specified, the module is
|
||
loaded, if it was not already loaded, but the state of features is
|
||
unchanged. Each feature may be preceded by a + to turn the feature on,
|
||
or - to turn it off; the + is assumed if neither character is present.
|
||
Any feature not explicitly mentioned is left in its current state; if
|
||
the module was not previously loaded this means any such features will
|
||
remain disabled. The return status is zero if all features were set, 1
|
||
if the module failed to load, and 2 if some features could not be set
|
||
(for example, a parameter couldn’t be added because there was a
|
||
different parameter of the same name) but the module was loaded.</p>
|
||
<p>The standard features are builtins, conditions, parameters and math
|
||
functions; these are indicated by the prefix ‘b:’, ‘c:’ (‘C:’ for an
|
||
infix condition), ‘p:’ and ‘f:’, respectively, followed by the name that
|
||
the corresponding feature would have in the shell. For example,
|
||
‘b:strftime’ indicates a builtin named strftime and p:EPOCHSECONDS
|
||
indicates a parameter named EPOCHSECONDS. The module may provide other
|
||
(‘abstract’) features of its own as indicated by its documentation;
|
||
these have no prefix.</p>
|
||
<p>With -l or -L, features provided by the module are listed. With -l
|
||
alone, a list of features together with their states is shown, one
|
||
feature per line. With -L alone, a zmodload -F command that would cause
|
||
enabled features of the module to be turned on is shown. With -lL, a
|
||
zmodload -F command that would cause all the features to be set to their
|
||
current state is shown. If one of these combinations is given with the
|
||
option -P <code>param</code> then the parameter <code>param</code> is set to an array of
|
||
features, either features together with their state or (if -L alone is
|
||
given) enabled features.</p>
|
||
<p>With the option -L the module name may be omitted; then a list of all
|
||
enabled features for all modules providing features is printed in the
|
||
form of zmodload -F commands. If -l is also given, the state of both
|
||
enabled and disabled features is output in that form.</p>
|
||
<p>A set of features may be provided together with -l or -L and a module
|
||
name; in that case only the state of those features is considered. Each
|
||
feature may be preceded by + or - but the character has no effect. If no
|
||
set of features is provided, all features are considered.</p>
|
||
<p>With -e, the command first tests that the module is loaded; if it is
|
||
not, status 1 is returned. If the module is loaded, the list of features
|
||
given as an argument is examined. Any feature given with no prefix is
|
||
simply tested to see if the module provides it; any feature given with a
|
||
prefix + or - is tested to see if is provided and in the given state. If
|
||
the tests on all features in the list succeed, status 0 is returned,
|
||
else status 1.</p>
|
||
<p>With -m, each entry in the given list of features is taken as a pattern
|
||
to be matched against the list of features provided by the module. An
|
||
initial + or - must be given explicitly. This may not be combined with
|
||
the -a option as autoloads must be specified explicitly.</p>
|
||
<p>With -a, the given list of features is marked for autoload from the
|
||
specified module, which may not yet be loaded. An optional + may appear
|
||
before the feature name. If the feature is prefixed with -, any existing
|
||
autoload is removed. The options -l and -L may be used to list
|
||
autoloads. Autoloading is specific to individual features; when the
|
||
module is loaded only the requested feature is enabled. Autoload
|
||
requests are preserved if the module is subsequently unloaded until an
|
||
explicit ‘zmodload -Fa <code>module</code> -<code>feature</code>’ is issued. It is not an
|
||
error to request an autoload for a feature of a module that is already
|
||
loaded.</p>
|
||
<p>When the module is loaded each autoload is checked against the features
|
||
actually provided by the module; if the feature is not provided the
|
||
autoload request is deleted. A warning message is output; if the module
|
||
is being loaded to provide a different feature, and that autoload is
|
||
successful, there is no effect on the status of the current command. If
|
||
the module is already loaded at the time when zmodload -Fa is run, an
|
||
error message is printed and status 1 returned.</p>
|
||
<p>zmodload -Fa can be used with the -l, -L, -e and -P options for listing
|
||
and testing the existence of autoloadable features. In this case -l is
|
||
ignored if -L is specified. zmodload -FaL with no module name lists
|
||
autoloads for all modules.</p>
|
||
<p>Note that only standard features as described above can be autoloaded;
|
||
other features require the module to be loaded before enabling.</p>
|
||
<p>zmodload -d [ -L ] [ <code>name</code> ]<br />
|
||
zmodload -d <code>name</code> <code>dep</code> ...<br />
|
||
zmodload -ud <code>name</code> [ <code>dep</code> ... ]<br />
|
||
The -d option can be used to specify module dependencies. The modules
|
||
named in the second and subsequent arguments will be loaded before the
|
||
module named in the first argument.</p>
|
||
<p>With -d and one argument, all dependencies for that module are listed.
|
||
With -d and no arguments, all module dependencies are listed. This
|
||
listing is by default in a Makefile-like format. The -L option changes
|
||
this format to a list of zmodload -d commands.</p>
|
||
<p>If -d and -u are both used, dependencies are removed. If only one
|
||
argument is given, all dependencies for that module are removed.</p>
|
||
<p>zmodload -ab [ -L ]<br />
|
||
zmodload -ab [ -i ] <code>name</code> [ <code>builtin</code> ... ]<br />
|
||
zmodload -ub [ -i ] <code>builtin</code> ...<br />
|
||
The -ab option defines autoloaded builtins. It defines the specified
|
||
<code>builtin</code>s. When any of those builtins is called, the module specified
|
||
in the first argument is loaded and all its features are enabled (for
|
||
selective control of features use ‘zmodload -F -a’ as described above).
|
||
If only the <code>name</code> is given, one builtin is defined, with the same name
|
||
as the module. -i suppresses the error if the builtin is already defined
|
||
or autoloaded, but not if another builtin of the same name is already
|
||
defined.</p>
|
||
<p>With -ab and no arguments, all autoloaded builtins are listed, with the
|
||
module name (if different) shown in parentheses after the builtin name.
|
||
The -L option changes this format to a list of zmodload -a commands.</p>
|
||
<p>If -b is used together with the -u option, it removes builtins
|
||
previously defined with -ab. This is only possible if the builtin is not
|
||
yet loaded. -i suppresses the error if the builtin is already removed
|
||
(or never existed).</p>
|
||
<p>Autoload requests are retained if the module is subsequently unloaded
|
||
until an explicit ‘zmodload -ub <code>builtin</code>’ is issued.</p>
|
||
<p>zmodload -ac [ -IL ]<br />
|
||
zmodload -ac [ -iI ] <code>name</code> [ <code>cond</code> ... ]<br />
|
||
zmodload -uc [ -iI ] <code>cond</code> ...<br />
|
||
The -ac option is used to define autoloaded condition codes. The <code>cond</code>
|
||
strings give the names of the conditions defined by the module. The
|
||
optional -I option is used to define infix condition names. Without this
|
||
option prefix condition names are defined.</p>
|
||
<p>If given no condition names, all defined names are listed (as a series
|
||
of zmodload commands if the -L option is given).</p>
|
||
<p>The -uc option removes definitions for autoloaded conditions.</p>
|
||
<p>zmodload -ap [ -L ]<br />
|
||
zmodload -ap [ -i ] <code>name</code> [ <code>parameter</code> ... ]<br />
|
||
zmodload -up [ -i ] <code>parameter</code> ...<br />
|
||
The -p option is like the -b and -c options, but makes zmodload work on
|
||
autoloaded parameters instead.</p>
|
||
<p>zmodload -af [ -L ]<br />
|
||
zmodload -af [ -i ] <code>name</code> [ <code>function</code> ... ]<br />
|
||
zmodload -uf [ -i ] <code>function</code> ...<br />
|
||
The -f option is like the -b, -p, and -c options, but makes zmodload
|
||
work on autoloaded math functions instead.</p>
|
||
<p>zmodload -a [ -L ]<br />
|
||
zmodload -a [ -i ] <code>name</code> [ <code>builtin</code> ... ]<br />
|
||
zmodload -ua [ -i ] <code>builtin</code> ...<br />
|
||
Equivalent to -ab and -ub.</p>
|
||
<p>zmodload -e [ -A ] [ <code>string</code> ... ]<br />
|
||
The -e option without arguments lists all loaded modules; if the -A
|
||
option is also given, module aliases corresponding to loaded modules are
|
||
also shown. If arguments are provided, nothing is printed; the return
|
||
status is set to zero if all <code>string</code>s given as arguments are names of
|
||
loaded modules and to one if at least on <code>string</code> is not the name of a
|
||
loaded module. This can be used to test for the availability of things
|
||
implemented by modules. In this case, any aliases are automatically
|
||
resolved and the -A flag is not used.</p>
|
||
<p>zmodload -A [ -L ] [ <code>modalias</code>[=<code>module</code>] ... ]<br />
|
||
For each argument, if both <code>modalias</code> and <code>module</code> are given, define
|
||
<code>modalias</code> to be an alias for the module <code>module</code>. If the module
|
||
<code>modalias</code> is ever subsequently requested, either via a call to zmodload
|
||
or implicitly, the shell will attempt to load <code>module</code> instead. If
|
||
<code>module</code> is not given, show the definition of <code>modalias</code>. If no
|
||
arguments are given, list all defined module aliases. When listing, if
|
||
the -L flag was also given, list the definition as a zmodload command to
|
||
recreate the alias.</p>
|
||
<p>The existence of aliases for modules is completely independent of
|
||
whether the name resolved is actually loaded as a module: while the
|
||
alias exists, loading and unloading the module under any alias has
|
||
exactly the same effect as using the resolved name, and does not affect
|
||
the connection between the alias and the resolved name which can be
|
||
removed either by zmodload -R or by redefining the alias. Chains of
|
||
aliases (i.e. where the first resolved name is itself an alias) are
|
||
valid so long as these are not circular. As the aliases take the same
|
||
format as module names, they may include path separators: in this case,
|
||
there is no requirement for any part of the path named to exist as the
|
||
alias will be resolved first. For example, ‘any/old/alias’ is always a
|
||
valid alias.</p>
|
||
<p>Dependencies added to aliased modules are actually added to the resolved
|
||
module; these remain if the alias is removed. It is valid to create an
|
||
alias whose name is one of the standard shell modules and which resolves
|
||
to a different module. However, if a module has dependencies, it will
|
||
not be possible to use the module name as an alias as the module will
|
||
already be marked as a loadable module in its own right.</p>
|
||
<p>Apart from the above, aliases can be used in the zmodload command
|
||
anywhere module names are required. However, aliases will not be shown
|
||
in lists of loaded modules with a bare ‘zmodload’.</p>
|
||
<p>zmodload -R <code>modalias</code> ...<br />
|
||
For each <code>modalias</code> argument that was previously defined as a module
|
||
alias via zmodload -A, delete the alias. If any was not defined, an
|
||
error is caused and the remainder of the line is ignored.</p>
|
||
<p>Note that zsh makes no distinction between modules that were linked into
|
||
the shell and modules that are loaded dynamically. In both cases this
|
||
builtin command has to be used to make available the builtins and other
|
||
things defined by modules (unless the module is autoloaded on these
|
||
definitions). This is true even for systems that don’t support dynamic
|
||
loading of modules.</p>
|
||
<p>zparseopts</p>
|
||
<p>See <a href="Zsh-Modules.html#The-zsh_002fzutil-Module">The zsh/zutil Module</a>.</p>
|
||
<p>zprof</p>
|
||
<p>See <a href="Zsh-Modules.html#The-zsh_002fzprof-Module">The zsh/zprof Module</a>.</p>
|
||
<p>zpty</p>
|
||
<p>See <a href="Zsh-Modules.html#The-zsh_002fzpty-Module">The zsh/zpty Module</a>.</p>
|
||
<p>zregexparse</p>
|
||
<p>See <a href="Zsh-Modules.html#The-zsh_002fzutil-Module">The zsh/zutil Module</a>.</p>
|
||
<p>zsocket</p>
|
||
<p>See <a href="Zsh-Modules.html#The-zsh_002fnet_002fsocket-Module">The zsh/net/socket
|
||
Module</a>.</p>
|
||
<p>zstyle</p>
|
||
<p>See <a href="Zsh-Modules.html#The-zsh_002fzutil-Module">The zsh/zutil Module</a>.</p>
|
||
<p>ztcp</p>
|
||
<p>See <a href="Zsh-Modules.html#The-zsh_002fnet_002ftcp-Module">The zsh/net/tcp
|
||
Module</a>.</p>
|
||
<hr />
|
||
<p>This document was generated on <em>May 14, 2022</em> using <a href="http://www.nongnu.org/texi2html/"><em>texi2html
|
||
5.0</em></a>.<br />
|
||
Zsh version 5.9, released on May 14, 2022.</p>
|
||
|
||
</main>
|
||
|
||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
<!-- Mobile navigation buttons -->
|
||
<a rel="prev" href="Options.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="Zsh-Line-Editor.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="Options.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="Zsh-Line-Editor.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">
|
||
const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
|
||
const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload";
|
||
const socket = new WebSocket(wsAddress);
|
||
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>
|