653 lines
34 KiB
HTML
653 lines
34 KiB
HTML
<!DOCTYPE HTML>
|
||
<html lang="en" class="sidebar-visible no-js light">
|
||
<head>
|
||
<!-- Book generated using mdBook -->
|
||
<meta charset="UTF-8">
|
||
<title>Functions - Zsh Manual</title>
|
||
|
||
|
||
|
||
|
||
<!-- Custom HTML head -->
|
||
|
||
|
||
|
||
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
|
||
<meta name="description" content="">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<meta name="theme-color" content="#ffffff" />
|
||
|
||
|
||
<link rel="icon" href="favicon.svg">
|
||
|
||
|
||
<link rel="shortcut icon" href="favicon.png">
|
||
|
||
<link rel="stylesheet" href="css/variables.css">
|
||
<link rel="stylesheet" href="css/general.css">
|
||
<link rel="stylesheet" href="css/chrome.css">
|
||
|
||
<link rel="stylesheet" href="css/print.css" media="print">
|
||
|
||
|
||
<!-- Fonts -->
|
||
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
|
||
|
||
<link rel="stylesheet" href="fonts/fonts.css">
|
||
|
||
|
||
<!-- Highlight.js Stylesheets -->
|
||
<link rel="stylesheet" href="highlight.css">
|
||
<link rel="stylesheet" href="tomorrow-night.css">
|
||
<link rel="stylesheet" href="ayu-highlight.css">
|
||
|
||
<!-- Custom theme stylesheets -->
|
||
|
||
|
||
|
||
</head>
|
||
<body>
|
||
<!-- Provide site root to javascript -->
|
||
<script type="text/javascript">
|
||
var path_to_root = "";
|
||
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
|
||
</script>
|
||
|
||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||
<script type="text/javascript">
|
||
try {
|
||
var theme = localStorage.getItem('mdbook-theme');
|
||
var sidebar = localStorage.getItem('mdbook-sidebar');
|
||
|
||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||
}
|
||
|
||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||
}
|
||
} catch (e) { }
|
||
</script>
|
||
|
||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||
<script type="text/javascript">
|
||
var theme;
|
||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||
var html = document.querySelector('html');
|
||
html.classList.remove('no-js')
|
||
html.classList.remove('light')
|
||
html.classList.add(theme);
|
||
html.classList.add('js');
|
||
</script>
|
||
|
||
<!-- Hide / unhide sidebar before it is displayed -->
|
||
<script type="text/javascript">
|
||
var html = document.querySelector('html');
|
||
var sidebar = 'hidden';
|
||
if (document.body.clientWidth >= 1080) {
|
||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||
sidebar = sidebar || 'visible';
|
||
}
|
||
html.classList.remove('sidebar-visible');
|
||
html.classList.add("sidebar-" + sidebar);
|
||
</script>
|
||
|
||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||
<div class="sidebar-scrollbox">
|
||
<ol class="chapter"><li class="chapter-item expanded "><a href="The-Z-Shell-Manual.html"><strong aria-hidden="true">1.</strong> The Z Shell Manual</a></li><li class="chapter-item expanded "><a href="Introduction.html"><strong aria-hidden="true">2.</strong> Introduction</a></li><li class="chapter-item expanded "><a href="Roadmap.html"><strong aria-hidden="true">3.</strong> Roadmap</a></li><li class="chapter-item expanded "><a href="Invocation.html"><strong aria-hidden="true">4.</strong> Invocation</a></li><li class="chapter-item expanded "><a href="Files.html"><strong aria-hidden="true">5.</strong> Files</a></li><li class="chapter-item expanded "><a href="Shell-Grammar.html"><strong aria-hidden="true">6.</strong> Shell Grammar</a></li><li class="chapter-item expanded "><a href="Redirection.html"><strong aria-hidden="true">7.</strong> Redirection</a></li><li class="chapter-item expanded "><a href="Command-Execution.html"><strong aria-hidden="true">8.</strong> Command Execution</a></li><li class="chapter-item expanded "><a href="Functions.html" class="active"><strong aria-hidden="true">9.</strong> Functions</a></li><li class="chapter-item expanded "><a href="Jobs-_0026-Signals.html"><strong aria-hidden="true">10.</strong> Jobs & Signals</a></li><li class="chapter-item expanded "><a href="Arithmetic-Evaluation.html"><strong aria-hidden="true">11.</strong> Arithmetic Evaluation</a></li><li class="chapter-item expanded "><a href="Conditional-Expressions.html"><strong aria-hidden="true">12.</strong> Conditional Expressions</a></li><li class="chapter-item expanded "><a href="Prompt-Expansion.html"><strong aria-hidden="true">13.</strong> Prompt Expansion</a></li><li class="chapter-item expanded "><a href="Expansion.html"><strong aria-hidden="true">14.</strong> Expansion</a></li><li class="chapter-item expanded "><a href="Parameters.html"><strong aria-hidden="true">15.</strong> Parameters</a></li><li class="chapter-item expanded "><a href="Options.html"><strong aria-hidden="true">16.</strong> Options</a></li><li class="chapter-item expanded "><a href="Shell-Builtin-Commands.html"><strong aria-hidden="true">17.</strong> Shell Builtin Commands</a></li><li class="chapter-item expanded "><a href="Zsh-Line-Editor.html"><strong aria-hidden="true">18.</strong> Zsh Line Editor</a></li><li class="chapter-item expanded "><a href="Completion-Widgets.html"><strong aria-hidden="true">19.</strong> Completion Widgets</a></li><li class="chapter-item expanded "><a href="Completion-System.html"><strong aria-hidden="true">20.</strong> Completion System</a></li><li class="chapter-item expanded "><a href="Completion-Using-compctl.html"><strong aria-hidden="true">21.</strong> Completion Using compctl</a></li><li class="chapter-item expanded "><a href="Zsh-Modules.html"><strong aria-hidden="true">22.</strong> Zsh Modules</a></li><li class="chapter-item expanded "><a href="Calendar-Function-System.html"><strong aria-hidden="true">23.</strong> Calendar Function System</a></li><li class="chapter-item expanded "><a href="TCP-Function-System.html"><strong aria-hidden="true">24.</strong> TCP Function System</a></li><li class="chapter-item expanded "><a href="Zftp-Function-System.html"><strong aria-hidden="true">25.</strong> Zftp Function System</a></li><li class="chapter-item expanded "><a href="User-Contributions.html"><strong aria-hidden="true">26.</strong> User Contributions</a></li></ol>
|
||
</div>
|
||
<div id="sidebar-resize-handle" class="sidebar-resize-handle"></div>
|
||
</nav>
|
||
|
||
<div id="page-wrapper" class="page-wrapper">
|
||
|
||
<div class="page">
|
||
|
||
<div id="menu-bar-hover-placeholder"></div>
|
||
<div id="menu-bar" class="menu-bar sticky bordered">
|
||
<div class="left-buttons">
|
||
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
||
<i class="fa fa-bars"></i>
|
||
</button>
|
||
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
||
<i class="fa fa-paint-brush"></i>
|
||
</button>
|
||
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
||
<li role="none"><button role="menuitem" class="theme" id="light">Light (default)</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
||
</ul>
|
||
|
||
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
||
<i class="fa fa-search"></i>
|
||
</button>
|
||
|
||
</div>
|
||
|
||
<h1 class="menu-title">Zsh Manual</h1>
|
||
|
||
<div class="right-buttons">
|
||
|
||
<a href="print.html" title="Print this book" aria-label="Print this book">
|
||
<i id="print-button" class="fa fa-print"></i>
|
||
</a>
|
||
|
||
|
||
|
||
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<div id="search-wrapper" class="hidden">
|
||
<form id="searchbar-outer" class="searchbar-outer">
|
||
<input type="search" 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="#9-functions">9 Functions</a>
|
||
<ul>
|
||
<li><a href="#91-autoloading-functions">9.1 Autoloading Functions</a></li>
|
||
<li><a href="#92-anonymous-functions">9.2 Anonymous Functions</a></li>
|
||
<li><a href="#93-special-functions">9.3 Special Functions</a>
|
||
<ul>
|
||
<li><a href="#931-hook-functions">9.3.1 Hook Functions</a></li>
|
||
<li><a href="#932-trap-functions">9.3.2 Trap Functions</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||
<p><span id="Functions"></span> <span id="Functions-3"></span></p>
|
||
<h1 id="9-functions"><a class="header" href="#9-functions">9 Functions</a></h1>
|
||
<p><span id="index-functions"></span>
|
||
<span id="index-function_002c-use-of"></span></p>
|
||
<p>Shell functions are defined with the <code>function</code> reserved word or the
|
||
special syntax ‘<code>funcname</code> <code>()</code>’. Shell functions are read in and stored
|
||
internally. Alias names are resolved when the function is read.
|
||
Functions are executed like commands with the arguments passed as
|
||
positional parameters. (See <a href="Command-Execution.html#Command-Execution">Command
|
||
Execution</a>.)</p>
|
||
<p>Functions execute in the same process as the caller and share all files
|
||
and present working directory with the caller. A trap on <code>EXIT</code> set
|
||
inside a function is executed after the function completes in the
|
||
environment of the caller.</p>
|
||
<p><span id="index-return_002c-use-of"></span></p>
|
||
<p>The <code>return</code> builtin is used to return from function calls.</p>
|
||
<p><span id="index-functions_002c-use-of"></span></p>
|
||
<p>Function identifiers can be listed with the <code>functions</code> builtin.
|
||
<span id="index-unfunction_002c-use-of"></span> Functions can be
|
||
undefined with the <code>unfunction</code> builtin.</p>
|
||
<hr />
|
||
<p><span id="Autoloading-Functions"></span></p>
|
||
<h2 id="91-autoloading-functions"><a class="header" href="#91-autoloading-functions">9.1 Autoloading Functions</a></h2>
|
||
<p><span id="index-autoloading-functions"></span>
|
||
<span id="index-functions_002c-autoloading"></span>
|
||
<span id="index-autoload_002c-use-of"></span>
|
||
<span id="index-fpath_002c-use-of"></span></p>
|
||
<p>A function can be marked as <em>undefined</em> using the <code>autoload</code> builtin (or
|
||
‘<code>functions -u</code>’ or ‘<code>typeset -fu</code>’). Such a function has no body. When
|
||
the function is first executed, the shell searches for its definition
|
||
using the elements of the <code>fpath</code> variable. Thus to define functions for
|
||
autoloading, a typical sequence is:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">fpath=(~/myfuncs $fpath)
|
||
autoload myfunc1 myfunc2 ...
|
||
</code></pre>
|
||
</div>
|
||
<p>The usual alias expansion during reading will be suppressed if the
|
||
<code>autoload</code> builtin or its equivalent is given the option <code>-U</code>. This is
|
||
recommended for the use of functions supplied with the zsh distribution.
|
||
<span id="index-zcompile_002c-use-of"></span> Note that for functions
|
||
precompiled with the <code>zcompile</code> builtin command the flag <code>-U</code> must be
|
||
provided when the <code>.zwc</code> file is created, as the corresponding
|
||
information is compiled into the latter.</p>
|
||
<p>For each <code>element</code> in <code>fpath</code>, the shell looks for three possible files,
|
||
the newest of which is used to load the definition for the function:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>element``.zwc</code><br />
|
||
A file created with the <code>zcompile</code> builtin command, which is
|
||
expected to contain the definitions for all functions in the
|
||
directory named <code>element</code>. The file is treated in the same manner as
|
||
a directory containing files for functions and is searched for the
|
||
definition of the function. If the definition is not found, the
|
||
search for a definition proceeds with the other two possibilities
|
||
described below.</p>
|
||
<p>If <code>element</code> already includes a <code>.zwc</code> extension (i.e. the extension
|
||
was explicitly given by the user), <code>element</code> is searched for the
|
||
definition of the function without comparing its age to that of
|
||
other files; in fact, there does not need to be any directory named
|
||
<code>element</code> without the suffix. Thus including an element such as
|
||
‘<code>/usr/local/funcs.zwc</code>’ in <code>fpath</code> will speed up the search for
|
||
functions, with the disadvantage that functions included must be
|
||
explicitly recompiled by hand before the shell notices any changes.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>element``/``function``.zwc</code><br />
|
||
A file created with <code>zcompile</code>, which is expected to contain the
|
||
definition for <code>function</code>. It may include other function definitions
|
||
as well, but those are neither loaded nor executed; a file found in
|
||
this way is searched <em>only</em> for the definition of <code>function</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>element``/``function</code><br />
|
||
A file of zsh command text, taken to be the definition for
|
||
<code>function</code>.</p>
|
||
</li>
|
||
</ul>
|
||
<p>In summary, the order of searching is, first, in the <em>parents of</em>
|
||
directories in <code>fpath</code> for the newer of either a compiled directory or a
|
||
directory in <code>fpath</code>; second, if more than one of these contains a
|
||
definition for the function that is sought, the leftmost in the <code>fpath</code>
|
||
is chosen; and third, within a directory, the newer of either a compiled
|
||
function or an ordinary function definition is used.</p>
|
||
<p><span id="index-KSH_005fAUTOLOAD_002c-use-of"></span></p>
|
||
<p>If the <code>KSH_AUTOLOAD</code> option is set, or the file contains only a simple
|
||
definition of the function, the file’s contents will be executed. This
|
||
will normally define the function in question, but may also perform
|
||
initialization, which is executed in the context of the function
|
||
execution, and may therefore define local parameters. It is an error if
|
||
the function is not defined by loading the file.</p>
|
||
<p>Otherwise, the function body (with no surrounding ‘<code>funcname``() {``...``}</code>’) is taken to be the complete contents of the file. This
|
||
processing of the file results in the function being re-defined, the
|
||
function itself is not re-executed. To force the shell to perform
|
||
initialization and then call the function defined, the file should
|
||
contain initialization code (which will be executed then discarded) in
|
||
addition to a complete function definition (which will be retained for
|
||
subsequent calls to the function), and a call to the shell function,
|
||
including any arguments, at the end.</p>
|
||
<p>For example, suppose the autoload file <code>func</code> contains</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">func() { print This is func; }
|
||
print func is initialized
|
||
</code></pre>
|
||
</div>
|
||
<p>then ‘<code>func; func</code>’ with <code>KSH_AUTOLOAD</code> set will produce both messages
|
||
on the first call, but only the message ‘<code>This is func</code>’ on the second
|
||
and subsequent calls. Without <code>KSH_AUTOLOAD</code> set, it will produce the
|
||
initialization message on the first call, and the other message on the
|
||
second and subsequent calls.</p>
|
||
<p>It is also possible to create a function that is not marked as
|
||
autoloaded, but which loads its own definition by searching <code>fpath</code>, by
|
||
using ‘<code>autoload -X</code>’ within a shell function. For example, the
|
||
following are equivalent:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">myfunc() {
|
||
autoload -X
|
||
}
|
||
myfunc args...
|
||
</code></pre>
|
||
</div>
|
||
<p>and</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">unfunction myfunc # if myfunc was defined
|
||
autoload myfunc
|
||
myfunc args...
|
||
</code></pre>
|
||
</div>
|
||
<p>In fact, the <code>functions</code> command outputs ‘<code>builtin autoload -X</code>’ as the
|
||
body of an autoloaded function. This is done so that</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">eval "$(functions)"
|
||
</code></pre>
|
||
</div>
|
||
<p>produces a reasonable result. A true autoloaded function can be
|
||
identified by the presence of the comment ‘<code># undefined</code>’ in the body,
|
||
because all comments are discarded from defined functions.</p>
|
||
<p>To load the definition of an autoloaded function <code>myfunc</code> without
|
||
executing <code>myfunc</code>, use:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">autoload +X myfunc
|
||
</code></pre>
|
||
</div>
|
||
<hr />
|
||
<p><span id="Anonymous-Functions"></span></p>
|
||
<h2 id="92-anonymous-functions"><a class="header" href="#92-anonymous-functions">9.2 Anonymous Functions</a></h2>
|
||
<p><span id="index-anonymous-functions"></span>
|
||
<span id="index-functions_002c-anonymous"></span></p>
|
||
<p>If no name is given for a function, it is ‘anonymous’ and is handled
|
||
specially. Either form of function definition may be used: a ‘<code>()</code>’ with
|
||
no preceding name, or a ‘<code>function</code>’ with an immediately following open
|
||
brace. The function is executed immediately at the point of definition
|
||
and is not stored for future use. The function name is set to
|
||
‘<code>(anon)</code>’.</p>
|
||
<p>Arguments to the function may be specified as words following the
|
||
closing brace defining the function, hence if there are none no
|
||
arguments (other than <code>$0</code>) are set. This is a difference from the way
|
||
other functions are parsed: normal function definitions may be followed
|
||
by certain keywords such as ‘<code>else</code>’ or ‘<code>fi</code>’, which will be treated as
|
||
arguments to anonymous functions, so that a newline or semicolon is
|
||
needed to force keyword interpretation.</p>
|
||
<p>Note also that the argument list of any enclosing script or function is
|
||
hidden (as would be the case for any other function called at this
|
||
point).</p>
|
||
<p>Redirections may be applied to the anonymous function in the same manner
|
||
as to a current-shell structure enclosed in braces. The main use of
|
||
anonymous functions is to provide a scope for local variables. This is
|
||
particularly convenient in start-up files as these do not provide their
|
||
own local variable scope.</p>
|
||
<p>For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">variable=outside
|
||
function {
|
||
local variable=inside
|
||
print "I am $variable with arguments $*"
|
||
} this and that
|
||
print "I am $variable"
|
||
</code></pre>
|
||
</div>
|
||
<p>outputs the following:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">I am inside with arguments this and that
|
||
I am outside
|
||
</code></pre>
|
||
</div>
|
||
<p>Note that function definitions with arguments that expand to nothing,
|
||
for example ‘<code>name=; function $name { ``...`` }</code>’, are not treated
|
||
as anonymous functions. Instead, they are treated as normal function
|
||
definitions where the definition is silently discarded.</p>
|
||
<hr />
|
||
<p><span id="Special-Functions"></span></p>
|
||
<h2 id="93-special-functions"><a class="header" href="#93-special-functions">9.3 Special Functions</a></h2>
|
||
<p>Certain functions, if defined, have special meaning to the shell.</p>
|
||
<hr />
|
||
<p><span id="Hook-Functions"></span></p>
|
||
<h3 id="931-hook-functions"><a class="header" href="#931-hook-functions">9.3.1 Hook Functions</a></h3>
|
||
<p><span id="index-functions_002c-hook"></span>
|
||
<span id="index-hook-functions"></span></p>
|
||
<p>For the functions below, it is possible to define an array that has the
|
||
same name as the function with ‘<code>_functions</code>’ appended. Any element in
|
||
such an array is taken as the name of a function to execute; it is
|
||
executed in the same context and with the same arguments as the basic
|
||
function. For example, if <code>$chpwd_functions</code> is an array containing the
|
||
values ‘<code>mychpwd</code>’, ‘<code>chpwd_save_dirstack</code>’, then the shell attempts to
|
||
execute the functions ‘<code>chpwd</code>’, ‘<code>mychpwd</code>’ and
|
||
‘<code>chpwd_save_dirstack</code>’, in that order. Any function that does not
|
||
exist is silently ignored. A function found by this mechanism is
|
||
referred to elsewhere as a ‘hook function’. An error in any function
|
||
causes subsequent functions not to be run. Note further that an error in
|
||
a <code>precmd</code> hook causes an immediately following <code>periodic</code> function not
|
||
to run (though it may run at the next opportunity).</p>
|
||
<p><span id="index-chpwd"></span>
|
||
<span id="index-chpwd_005ffunctions"></span></p>
|
||
<p><code>chpwd</code></p>
|
||
<p>Executed whenever the current working directory is changed.</p>
|
||
<p><span id="index-periodic"></span>
|
||
<span id="index-periodic_005ffunctions"></span></p>
|
||
<p><code>periodic</code></p>
|
||
<p><span id="index-PERIOD"></span></p>
|
||
<p>If the parameter <code>PERIOD</code> is set, this function is executed every
|
||
<code>$PERIOD</code> seconds, just before a prompt. Note that if multiple functions
|
||
are defined using the array <code>periodic_functions</code> only one period is
|
||
applied to the complete set of functions, and the scheduled time is not
|
||
reset if the list of functions is altered. Hence the set of functions is
|
||
always called together.</p>
|
||
<p><span id="index-precmd"></span>
|
||
<span id="index-precmd_005ffunctions"></span></p>
|
||
<p><code>precmd</code></p>
|
||
<p>Executed before each prompt. Note that precommand functions are not
|
||
re-executed simply because the command line is redrawn, as happens, for
|
||
example, when a notification about an exiting job is displayed.</p>
|
||
<p><span id="index-preexec"></span>
|
||
<span id="index-preexec_005ffunctions"></span></p>
|
||
<p><code>preexec</code></p>
|
||
<p>Executed just after a command has been read and is about to be executed.
|
||
If the history mechanism is active (regardless of whether the line was
|
||
discarded from the history buffer), the string that the user typed is
|
||
passed as the first argument, otherwise it is an empty string. The
|
||
actual command that will be executed (including expanded aliases) is
|
||
passed in two different forms: the second argument is a single-line,
|
||
size-limited version of the command (with things like function bodies
|
||
elided); the third argument contains the full text that is being
|
||
executed.</p>
|
||
<p><span id="index-zshaddhistory"></span>
|
||
<span id="index-zshaddhistory_005ffunctions"></span></p>
|
||
<p><code>zshaddhistory</code></p>
|
||
<p><span id="index-history_002c-hook-when-line-is-saved"></span></p>
|
||
<p>Executed when a history line has been read interactively, but before it
|
||
is executed. The sole argument is the complete history line (so that any
|
||
terminating newline will still be present).</p>
|
||
<p>If any of the hook functions returns status 1 (or any non-zero value
|
||
other than 2, though this is not guaranteed for future versions of the
|
||
shell) the history line will not be saved, although it lingers in the
|
||
history until the next line is executed, allowing you to reuse or edit
|
||
it immediately.</p>
|
||
<p>If any of the hook functions returns status 2 the history line will be
|
||
saved on the internal history list, but not written to the history file.
|
||
In case of a conflict, the first non-zero status value is taken.</p>
|
||
<p>A hook function may call ‘<code>fc -p</code> <code>...</code>’ to switch the history context
|
||
so that the history is saved in a different file from the that in the
|
||
global <code>HISTFILE</code> parameter. This is handled specially: the history
|
||
context is automatically restored after the processing of the history
|
||
line is finished.</p>
|
||
<p>The following example function works with one of the options
|
||
<code>INC_APPEND_HISTORY</code> or <code>SHARE_HISTORY</code> set, in order that the line is
|
||
written out immediately after the history entry is added. It first adds
|
||
the history line to the normal history with the newline stripped, which
|
||
is usually the correct behaviour. Then it switches the history context
|
||
so that the line will be written to a history file in the current
|
||
directory.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zshaddhistory() {
|
||
print -sr -- ${1%%$'\n'}
|
||
fc -p .zsh_local_history
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-zshexit"></span>
|
||
<span id="index-zshexit_005ffunctions"></span></p>
|
||
<p><code>zshexit</code></p>
|
||
<p>Executed at the point where the main shell is about to exit normally.
|
||
This is not called by exiting subshells, nor when the <code>exec</code> precommand
|
||
modifier is used before an external command. Also, unlike <code>TRAPEXIT</code>, it
|
||
is not called when functions exit.</p>
|
||
<hr />
|
||
<p><span id="Trap-Functions"></span></p>
|
||
<h3 id="932-trap-functions"><a class="header" href="#932-trap-functions">9.3.2 Trap Functions</a></h3>
|
||
<p>The functions below are treated specially but do not have corresponding
|
||
hook arrays.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>TRAP``NAL</code><br />
|
||
<span id="index-signals_002c-trapping"></span>
|
||
<span id="index-trapping-signals"></span></p>
|
||
<p>If defined and non-null, this function will be executed whenever the
|
||
shell catches a signal <code>SIG``NAL</code>, where <code>NAL</code> is a signal name as
|
||
specified for the <code>kill</code> builtin. The signal number will be passed
|
||
as the first parameter to the function.</p>
|
||
<p>If a function of this form is defined and null, the shell and
|
||
processes spawned by it will ignore <code>SIG``NAL</code>.</p>
|
||
<p>The return status from the function is handled specially. If it is
|
||
zero, the signal is assumed to have been handled, and execution
|
||
continues normally. Otherwise, the shell will behave as interrupted
|
||
except that the return status of the trap is retained.</p>
|
||
<p>Programs terminated by uncaught signals typically return the status
|
||
128 plus the signal number. Hence the following causes the handler
|
||
for <code>SIGINT</code> to print a message, then mimic the usual effect of the
|
||
signal.</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">TRAPINT() {
|
||
print "Caught SIGINT, aborting."
|
||
return $(( 128 + $1 ))
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
<p>The functions <code>TRAPZERR</code>, <code>TRAPDEBUG</code> and <code>TRAPEXIT</code> are never
|
||
executed inside other traps.</p>
|
||
<p><span id="index-TRAPDEBUG"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>TRAPDEBUG</code><br />
|
||
If the option <code>DEBUG_BEFORE_CMD</code> is set (as it is by default),
|
||
executed before each command; otherwise executed after each command.
|
||
See the description of the <code>trap</code> builtin in <a href="Shell-Builtin-Commands.html#Shell-Builtin-Commands">Shell Builtin
|
||
Commands</a> for
|
||
details of additional features provided in debug traps.</p>
|
||
<p><span id="index-TRAPEXIT"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>TRAPEXIT</code><br />
|
||
Executed when the shell exits, or when the current function exits if
|
||
defined inside a function. The value of <code>$?</code> at the start of
|
||
execution is the exit status of the shell or the return status of
|
||
the function exiting.</p>
|
||
<p><span id="index-TRAPZERR"></span> <span id="index-TRAPERR"></span></p>
|
||
</li>
|
||
<li>
|
||
<p><code>TRAPZERR</code><br />
|
||
Executed whenever a command has a non-zero exit status. However, the
|
||
function is not executed if the command occurred in a sublist
|
||
followed by ‘<code>&&</code>’ or ‘<code>||</code>’; only the final command in a sublist of
|
||
this type causes the trap to be executed. The function <code>TRAPERR</code>
|
||
acts the same as <code>TRAPZERR</code> on systems where there is no <code>SIGERR</code>
|
||
(this is the usual case).</p>
|
||
</li>
|
||
</ul>
|
||
<p><span id="index-trap_002c-use-of"></span></p>
|
||
<p>The functions beginning ‘<code>TRAP</code>’ may alternatively be defined with the
|
||
<code>trap</code> builtin: this may be preferable for some uses. Setting a trap
|
||
with one form removes any trap of the other form for the same signal;
|
||
removing a trap in either form removes all traps for the same signal.
|
||
The forms</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">TRAPNAL() {
|
||
# code
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
<p>(’function traps’) and</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">trap '
|
||
# code
|
||
' NAL
|
||
</code></pre>
|
||
</div>
|
||
<p>(’list traps’) are equivalent in most ways, the exceptions being the
|
||
following:</p>
|
||
<ul>
|
||
<li>Function traps have all the properties of normal functions,
|
||
appearing in the list of functions and being called with their own
|
||
function context rather than the context where the trap was
|
||
triggered.</li>
|
||
<li>The return status from function traps is special, whereas a return
|
||
from a list trap causes the surrounding context to return with the
|
||
given status.</li>
|
||
<li>Function traps are not reset within subshells, in accordance with
|
||
zsh behaviour; list traps are reset, in accordance with POSIX
|
||
behaviour.</li>
|
||
</ul>
|
||
<hr />
|
||
<p>This document was generated on <em>February 15, 2020</em> using
|
||
<a href="http://www.nongnu.org/texi2html/"><em>texi2html 5.0</em></a>.<br />
|
||
Zsh version 5.8, released on February 14, 2020.</p>
|
||
|
||
</main>
|
||
|
||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
<!-- Mobile navigation buttons -->
|
||
|
||
<a rel="prev" href="Command-Execution.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="Jobs-_0026-Signals.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="Command-Execution.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="Jobs-_0026-Signals.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
||
<i class="fa fa-angle-right"></i>
|
||
</a>
|
||
|
||
</nav>
|
||
|
||
</div>
|
||
|
||
|
||
<!-- Livereload script (if served using the cli tool) -->
|
||
<script type="text/javascript">
|
||
var socket = new WebSocket("ws://localhost:3000/__livereload");
|
||
socket.onmessage = function (event) {
|
||
if (event.data === "reload") {
|
||
socket.close();
|
||
location.reload();
|
||
}
|
||
};
|
||
|
||
window.onbeforeunload = function() {
|
||
socket.close();
|
||
}
|
||
</script>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<script type="text/javascript">
|
||
window.playground_copyable = true;
|
||
</script>
|
||
|
||
|
||
|
||
|
||
|
||
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
|
||
|
||
|
||
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="book.js" type="text/javascript" charset="utf-8"></script>
|
||
|
||
<!-- Custom JS scripts -->
|
||
|
||
|
||
|
||
|
||
</body>
|
||
</html>
|