4024 lines
222 KiB
HTML
4024 lines
222 KiB
HTML
<!DOCTYPE HTML>
|
||
<html lang="en" class="sidebar-visible no-js light">
|
||
<head>
|
||
<!-- Book generated using mdBook -->
|
||
<meta charset="UTF-8">
|
||
<title>Zsh Modules - Zsh Manual</title>
|
||
|
||
|
||
|
||
|
||
<!-- Custom HTML head -->
|
||
|
||
|
||
|
||
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
|
||
<meta name="description" content="">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<meta name="theme-color" content="#ffffff" />
|
||
|
||
|
||
<link rel="icon" href="favicon.svg">
|
||
|
||
|
||
<link rel="shortcut icon" href="favicon.png">
|
||
|
||
<link rel="stylesheet" href="css/variables.css">
|
||
<link rel="stylesheet" href="css/general.css">
|
||
<link rel="stylesheet" href="css/chrome.css">
|
||
|
||
<link rel="stylesheet" href="css/print.css" media="print">
|
||
|
||
|
||
<!-- Fonts -->
|
||
<link rel="stylesheet" href="FontAwesome/css/font-awesome.css">
|
||
|
||
<link rel="stylesheet" href="fonts/fonts.css">
|
||
|
||
|
||
<!-- Highlight.js Stylesheets -->
|
||
<link rel="stylesheet" href="highlight.css">
|
||
<link rel="stylesheet" href="tomorrow-night.css">
|
||
<link rel="stylesheet" href="ayu-highlight.css">
|
||
|
||
<!-- Custom theme stylesheets -->
|
||
|
||
|
||
|
||
</head>
|
||
<body>
|
||
<!-- Provide site root to javascript -->
|
||
<script type="text/javascript">
|
||
var path_to_root = "";
|
||
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
|
||
</script>
|
||
|
||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||
<script type="text/javascript">
|
||
try {
|
||
var theme = localStorage.getItem('mdbook-theme');
|
||
var sidebar = localStorage.getItem('mdbook-sidebar');
|
||
|
||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||
}
|
||
|
||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||
}
|
||
} catch (e) { }
|
||
</script>
|
||
|
||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||
<script type="text/javascript">
|
||
var theme;
|
||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||
var html = document.querySelector('html');
|
||
html.classList.remove('no-js')
|
||
html.classList.remove('light')
|
||
html.classList.add(theme);
|
||
html.classList.add('js');
|
||
</script>
|
||
|
||
<!-- Hide / unhide sidebar before it is displayed -->
|
||
<script type="text/javascript">
|
||
var html = document.querySelector('html');
|
||
var sidebar = 'hidden';
|
||
if (document.body.clientWidth >= 1080) {
|
||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||
sidebar = sidebar || 'visible';
|
||
}
|
||
html.classList.remove('sidebar-visible');
|
||
html.classList.add("sidebar-" + sidebar);
|
||
</script>
|
||
|
||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||
<div class="sidebar-scrollbox">
|
||
<ol class="chapter"><li class="chapter-item expanded "><a href="The-Z-Shell-Manual.html"><strong aria-hidden="true">1.</strong> The Z Shell Manual</a></li><li class="chapter-item expanded "><a href="Introduction.html"><strong aria-hidden="true">2.</strong> Introduction</a></li><li class="chapter-item expanded "><a href="Roadmap.html"><strong aria-hidden="true">3.</strong> Roadmap</a></li><li class="chapter-item expanded "><a href="Invocation.html"><strong aria-hidden="true">4.</strong> Invocation</a></li><li class="chapter-item expanded "><a href="Files.html"><strong aria-hidden="true">5.</strong> Files</a></li><li class="chapter-item expanded "><a href="Shell-Grammar.html"><strong aria-hidden="true">6.</strong> Shell Grammar</a></li><li class="chapter-item expanded "><a href="Redirection.html"><strong aria-hidden="true">7.</strong> Redirection</a></li><li class="chapter-item expanded "><a href="Command-Execution.html"><strong aria-hidden="true">8.</strong> Command Execution</a></li><li class="chapter-item expanded "><a href="Functions.html"><strong aria-hidden="true">9.</strong> Functions</a></li><li class="chapter-item expanded "><a href="Jobs-_0026-Signals.html"><strong aria-hidden="true">10.</strong> Jobs & Signals</a></li><li class="chapter-item expanded "><a href="Arithmetic-Evaluation.html"><strong aria-hidden="true">11.</strong> Arithmetic Evaluation</a></li><li class="chapter-item expanded "><a href="Conditional-Expressions.html"><strong aria-hidden="true">12.</strong> Conditional Expressions</a></li><li class="chapter-item expanded "><a href="Prompt-Expansion.html"><strong aria-hidden="true">13.</strong> Prompt Expansion</a></li><li class="chapter-item expanded "><a href="Expansion.html"><strong aria-hidden="true">14.</strong> Expansion</a></li><li class="chapter-item expanded "><a href="Parameters.html"><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" class="active"><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="#22-zsh-modules">22 Zsh Modules</a>
|
||
<ul>
|
||
<li><a href="#221-description">22.1 Description</a></li>
|
||
<li><a href="#222-the-zshattr-module">22.2 The zsh/attr Module</a></li>
|
||
<li><a href="#223-the-zshcap-module">22.3 The zsh/cap Module</a></li>
|
||
<li><a href="#224-the-zshclone-module">22.4 The zsh/clone Module</a></li>
|
||
<li><a href="#225-the-zshcompctl-module">22.5 The zsh/compctl Module</a></li>
|
||
<li><a href="#226-the-zshcomplete-module">22.6 The zsh/complete Module</a></li>
|
||
<li><a href="#227-the-zshcomplist-module">22.7 The zsh/complist Module</a>
|
||
<ul>
|
||
<li><a href="#2271-colored-completion-listings">22.7.1 Colored completion listings</a></li>
|
||
<li><a href="#2272-scrolling-in-completion-listings">22.7.2 Scrolling in completion listings</a></li>
|
||
<li><a href="#2273-menu-selection">22.7.3 Menu selection</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#228-the-zshcomputil-module">22.8 The zsh/computil Module</a></li>
|
||
<li><a href="#229-the-zshcurses-module">22.9 The zsh/curses Module</a>
|
||
<ul>
|
||
<li><a href="#2291-builtin">22.9.1 Builtin</a></li>
|
||
<li><a href="#2292-parameters">22.9.2 Parameters</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#2210-the-zshdatetime-module">22.10 The zsh/datetime Module</a></li>
|
||
<li><a href="#2211-the-zshdbgdbm-module">22.11 The zsh/db/gdbm Module</a></li>
|
||
<li><a href="#2212-the-zshdeltochar-module">22.12 The zsh/deltochar Module</a></li>
|
||
<li><a href="#2213-the-zshexample-module">22.13 The zsh/example Module</a></li>
|
||
<li><a href="#2214-the-zshfiles-module">22.14 The zsh/files Module</a></li>
|
||
<li><a href="#2215-the-zshlanginfo-module">22.15 The zsh/langinfo Module</a></li>
|
||
<li><a href="#2216-the-zshmapfile-module">22.16 The zsh/mapfile Module</a>
|
||
<ul>
|
||
<li><a href="#22161-limitations">22.16.1 Limitations</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#2217-the-zshmathfunc-module">22.17 The zsh/mathfunc Module</a></li>
|
||
<li><a href="#2218-the-zshnearcolor-module">22.18 The zsh/nearcolor Module</a></li>
|
||
<li><a href="#2219-the-zshnewuser-module">22.19 The zsh/newuser Module</a></li>
|
||
<li><a href="#2220-the-zshparameter-module">22.20 The zsh/parameter Module</a></li>
|
||
<li><a href="#2221-the-zshpcre-module">22.21 The zsh/pcre Module</a></li>
|
||
<li><a href="#2222-the-zshparamprivate-module">22.22 The zsh/param/private Module</a></li>
|
||
<li><a href="#2223-the-zshregex-module">22.23 The zsh/regex Module</a></li>
|
||
<li><a href="#2224-the-zshsched-module">22.24 The zsh/sched Module</a></li>
|
||
<li><a href="#2225-the-zshnetsocket-module">22.25 The zsh/net/socket Module</a>
|
||
<ul>
|
||
<li><a href="#22251-outbound-connections">22.25.1 Outbound Connections</a></li>
|
||
<li><a href="#22252-inbound-connections">22.25.2 Inbound Connections</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#2226-the-zshstat-module">22.26 The zsh/stat Module</a></li>
|
||
<li><a href="#2227-the-zshsystem-module">22.27 The zsh/system Module</a>
|
||
<ul>
|
||
<li><a href="#22271-builtins">22.27.1 Builtins</a></li>
|
||
<li><a href="#22272-math-functions">22.27.2 Math Functions</a></li>
|
||
<li><a href="#22273-parameters">22.27.3 Parameters</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#2228-the-zshnettcp-module">22.28 The zsh/net/tcp Module</a>
|
||
<ul>
|
||
<li><a href="#22281-outbound-connections">22.28.1 Outbound Connections</a></li>
|
||
<li><a href="#22282-inbound-connections">22.28.2 Inbound Connections</a></li>
|
||
<li><a href="#22283-closing-connections">22.28.3 Closing Connections</a></li>
|
||
<li><a href="#22284-example">22.28.4 Example</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#2229-the-zshtermcap-module">22.29 The zsh/termcap Module</a></li>
|
||
<li><a href="#2230-the-zshterminfo-module">22.30 The zsh/terminfo Module</a></li>
|
||
<li><a href="#2231-the-zshzftp-module">22.31 The zsh/zftp Module</a>
|
||
<ul>
|
||
<li><a href="#22311-subcommands">22.31.1 Subcommands</a></li>
|
||
<li><a href="#22312-parameters">22.31.2 Parameters</a></li>
|
||
<li><a href="#22313-functions">22.31.3 Functions</a></li>
|
||
<li><a href="#22314-problems">22.31.4 Problems</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#2232-the-zshzle-module">22.32 The zsh/zle Module</a></li>
|
||
<li><a href="#2233-the-zshzleparameter-module">22.33 The zsh/zleparameter Module</a></li>
|
||
<li><a href="#2234-the-zshzprof-module">22.34 The zsh/zprof Module</a></li>
|
||
<li><a href="#2235-the-zshzpty-module">22.35 The zsh/zpty Module</a></li>
|
||
<li><a href="#2236-the-zshzselect-module">22.36 The zsh/zselect Module</a></li>
|
||
<li><a href="#2237-the-zshzutil-module">22.37 The zsh/zutil Module</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||
<p><span id="Zsh-Modules"></span> <span id="Zsh-Modules-1"></span></p>
|
||
<h1 id="22-zsh-modules"><a class="header" href="#22-zsh-modules">22 Zsh Modules</a></h1>
|
||
<p><span id="index-modules"></span></p>
|
||
<hr />
|
||
<p><span id="Description-6"></span></p>
|
||
<h2 id="221-description"><a class="header" href="#221-description">22.1 Description</a></h2>
|
||
<p>Some optional parts of zsh are in modules, separate from the core of the
|
||
shell. Each of these modules may be linked in to the shell at build
|
||
time, or can be dynamically linked while the shell is running if the
|
||
installation supports this feature. Modules are linked at runtime with
|
||
the <code>zmodload</code> command, see <a href="Shell-Builtin-Commands.html#Shell-Builtin-Commands">Shell Builtin
|
||
Commands</a>.</p>
|
||
<p>The modules that are bundled with the zsh distribution are:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>zsh/attr</code><br />
|
||
Builtins for manipulating extended attributes (xattr).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/cap</code><br />
|
||
Builtins for manipulating POSIX.1e (POSIX.6) capability (privilege)
|
||
sets.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/clone</code><br />
|
||
A builtin that can clone a running shell onto another terminal.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/compctl</code><br />
|
||
The <code>compctl</code> builtin for controlling completion.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/complete</code><br />
|
||
The basic completion code.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/complist</code><br />
|
||
Completion listing extensions.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/computil</code><br />
|
||
A module with utility builtins needed for the shell function based
|
||
completion system.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/curses</code><br />
|
||
curses windowing commands</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/datetime</code><br />
|
||
Some date/time commands and parameters.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/db/gdbm</code><br />
|
||
Builtins for managing associative array parameters tied to GDBM
|
||
databases.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/deltochar</code><br />
|
||
A ZLE function duplicating EMACS’ <code>zap-to-char</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/example</code><br />
|
||
An example of how to write a module.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/files</code><br />
|
||
Some basic file manipulation commands as builtins.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/langinfo</code><br />
|
||
Interface to locale information.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/mapfile</code><br />
|
||
Access to external files via a special associative array.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/mathfunc</code><br />
|
||
Standard scientific functions for use in mathematical evaluations.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/nearcolor</code><br />
|
||
Map colours to the nearest colour in the available palette.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/newuser</code><br />
|
||
Arrange for files for new users to be installed.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/parameter</code><br />
|
||
<code>zsh/pcre</code><br />
|
||
Interface to the PCRE library.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/param/private</code><br />
|
||
Builtins for managing private-scoped parameters in function context.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/regex</code><br />
|
||
Interface to the POSIX regex library.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/sched</code><br />
|
||
A builtin that provides a timed execution facility within the shell.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/net/socket</code><br />
|
||
Manipulation of Unix domain sockets</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/stat</code><br />
|
||
A builtin command interface to the <code>stat</code> system call.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/system</code><br />
|
||
A builtin interface to various low-level system features.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/net/tcp</code><br />
|
||
Manipulation of TCP sockets</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/termcap</code><br />
|
||
Interface to the termcap database.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/terminfo</code><br />
|
||
Interface to the terminfo database.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/zftp</code><br />
|
||
A builtin FTP client.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/zle</code><br />
|
||
The Zsh Line Editor, including the <code>bindkey</code> and <code>vared</code> builtins.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/zleparameter</code><br />
|
||
Access to internals of the Zsh Line Editor via parameters.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/zprof</code><br />
|
||
A module allowing profiling for shell functions.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/zpty</code><br />
|
||
A builtin for starting a command in a pseudo-terminal.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/zselect</code><br />
|
||
Block and return when file descriptors are ready.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsh/zutil</code><br />
|
||
Some utility builtins, e.g. the one for supporting configuration via
|
||
styles.</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="The-zsh_002fattr-Module"></span>
|
||
<span id="The-zsh_002fattr-Module-1"></span></p>
|
||
<h2 id="222-the-zshattr-module"><a class="header" href="#222-the-zshattr-module">22.2 The zsh/attr Module</a></h2>
|
||
<p>The <code>zsh/attr</code> module is used for manipulating extended attributes. The
|
||
<code>-h</code> option causes all commands to operate on symbolic links instead of
|
||
their targets. The builtins in this module are:</p>
|
||
<p><span id="index-zgetattr"></span>
|
||
<span id="index-extended-attributes_002c-xattr_002c-getting-from-files"></span></p>
|
||
<p><code>zgetattr</code> [ <code>-h</code> ] <code>filename</code> <code>attribute</code> [ <code>parameter</code> ]</p>
|
||
<p>Get the extended attribute <code>attribute</code> from the specified <code>filename</code>. If
|
||
the optional argument <code>parameter</code> is given, the attribute is set on that
|
||
parameter instead of being printed to stdout.</p>
|
||
<p><span id="index-zsetattr"></span>
|
||
<span id="index-extended-attributes_002c-xattr_002c-setting-on-files"></span></p>
|
||
<p><code>zsetattr</code> [ <code>-h</code> ] <code>filename</code> <code>attribute</code> <code>value</code></p>
|
||
<p>Set the extended attribute <code>attribute</code> on the specified <code>filename</code> to
|
||
<code>value</code>.</p>
|
||
<p><span id="index-zdelattr"></span>
|
||
<span id="index-extended-attributes_002c-xattr_002c-removing_002c-deleting"></span></p>
|
||
<p><code>zdelattr</code> [ <code>-h</code> ] <code>filename</code> <code>attribute</code></p>
|
||
<p>Remove the extended attribute <code>attribute</code> from the specified <code>filename</code>.</p>
|
||
<p><span id="index-zlistattr"></span>
|
||
<span id="index-extended-attributes_002c-xattr_002c-listing"></span></p>
|
||
<p><code>zlistattr</code> [ <code>-h</code> ] <code>filename</code> [ <code>parameter</code> ]</p>
|
||
<p>List the extended attributes currently set on the specified <code>filename</code>.
|
||
If the optional argument <code>parameter</code> is given, the list of attributes is
|
||
set on that parameter instead of being printed to stdout.</p>
|
||
<p><code>zgetattr</code> and <code>zlistattr</code> allocate memory dynamically. If the attribute
|
||
or list of attributes grows between the allocation and the call to get
|
||
them, they return 2. On all other errors, 1 is returned. This allows the
|
||
calling function to check for this case and retry.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fcap-Module"></span>
|
||
<span id="The-zsh_002fcap-Module-1"></span></p>
|
||
<h2 id="223-the-zshcap-module"><a class="header" href="#223-the-zshcap-module">22.3 The zsh/cap Module</a></h2>
|
||
<p>The <code>zsh/cap</code> module is used for manipulating POSIX.1e (POSIX.6)
|
||
capability sets. If the operating system does not support this
|
||
interface, the builtins defined by this module will do nothing. The
|
||
builtins in this module are:</p>
|
||
<p><span id="index-cap"></span>
|
||
<span id="index-capabilities_002c-setting"></span></p>
|
||
<p><code>cap</code> [ <code>capabilities</code> ]</p>
|
||
<p>Change the shell’s process capability sets to the specified
|
||
<code>capabilities</code>, otherwise display the shell’s current capabilities.</p>
|
||
<p><span id="index-getcap"></span>
|
||
<span id="index-capabilities_002c-getting-from-files"></span></p>
|
||
<p><code>getcap</code> <code>filename</code> ...</p>
|
||
<p>This is a built-in implementation of the POSIX standard utility. It
|
||
displays the capability sets on each specified <code>filename</code>.</p>
|
||
<p><span id="index-setcap"></span>
|
||
<span id="index-capabilities_002c-setting-on-files"></span></p>
|
||
<p><code>setcap</code> <code>capabilities</code> <code>filename</code> ...</p>
|
||
<p>This is a built-in implementation of the POSIX standard utility. It sets
|
||
the capability sets on each specified <code>filename</code> to the specified
|
||
<code>capabilities</code>.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fclone-Module"></span>
|
||
<span id="The-zsh_002fclone-Module-1"></span></p>
|
||
<h2 id="224-the-zshclone-module"><a class="header" href="#224-the-zshclone-module">22.4 The zsh/clone Module</a></h2>
|
||
<p>The <code>zsh/clone</code> module makes available one builtin command:</p>
|
||
<p><span id="index-clone"></span>
|
||
<span id="index-shell_002c-cloning"></span>
|
||
<span id="index-cloning-the-shell"></span>
|
||
<span id="index-terminal"></span></p>
|
||
<p><code>clone</code> <code>tty</code></p>
|
||
<p>Creates a forked instance of the current shell, attached to the
|
||
specified <code>tty</code>. In the new shell, the <code>PID</code>, <code>PPID</code> and <code>TTY</code> special
|
||
parameters are changed appropriately. <code>$!</code> is set to zero in the new
|
||
shell, and to the new shell’s PID in the original shell.</p>
|
||
<p>The return status of the builtin is zero in both shells if successful,
|
||
and non-zero on error.</p>
|
||
<p>The target of <code>clone</code> should be an unused terminal, such as an unused
|
||
virtual console or a virtual terminal created by</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">xterm -e sh -c 'trap : INT QUIT TSTP; tty;
|
||
while :; do sleep 100000000; done'
|
||
</code></pre>
|
||
</div>
|
||
<p>Some words of explanation are warranted about this long xterm command
|
||
line: when doing clone on a pseudo-terminal, some other session
|
||
("session" meant as a unix session group, or SID) is already owning the
|
||
terminal. Hence the cloned zsh cannot acquire the pseudo-terminal as a
|
||
controlling tty. That means two things:</p>
|
||
<ul>
|
||
<li>the job control signals will go to the sh-started-by-xterm process
|
||
group (that’s why we disable INT QUIT and TSTP with trap; otherwise
|
||
the while loop could get suspended or killed)</li>
|
||
<li>the cloned shell will have job control disabled, and the job control
|
||
keys (control-C, control-\ and control-Z) will not work.</li>
|
||
</ul>
|
||
<p>This does not apply when cloning to an <em>unused</em> vc.</p>
|
||
<p>Cloning to a used (and unprepared) terminal will result in two processes
|
||
reading simultaneously from the same terminal, with input bytes going
|
||
randomly to either process.</p>
|
||
<p><code>clone</code> is mostly useful as a shell built-in replacement for openvt.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fcompctl-Module"></span>
|
||
<span id="The-zsh_002fcompctl-Module-1"></span></p>
|
||
<h2 id="225-the-zshcompctl-module"><a class="header" href="#225-the-zshcompctl-module">22.5 The zsh/compctl Module</a></h2>
|
||
<p>The <code>zsh/compctl</code> module makes available two builtin commands.
|
||
<code>compctl</code>, is the old, deprecated way to control completions for ZLE.
|
||
See <a href="Completion-Using-compctl.html#Completion-Using-compctl">Completion Using
|
||
compctl</a>. The
|
||
other builtin command, <code>compcall</code> can be used in user-defined completion
|
||
widgets, see <a href="Completion-Widgets.html#Completion-Widgets">Completion
|
||
Widgets</a>.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fcomplete-Module"></span>
|
||
<span id="The-zsh_002fcomplete-Module-1"></span></p>
|
||
<h2 id="226-the-zshcomplete-module"><a class="header" href="#226-the-zshcomplete-module">22.6 The zsh/complete Module</a></h2>
|
||
<p>The <code>zsh/complete</code> module makes available several builtin commands which
|
||
can be used in user-defined completion widgets, see <a href="Completion-Widgets.html#Completion-Widgets">Completion
|
||
Widgets</a>.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fcomplist-Module"></span>
|
||
<span id="The-zsh_002fcomplist-Module-1"></span></p>
|
||
<h2 id="227-the-zshcomplist-module"><a class="header" href="#227-the-zshcomplist-module">22.7 The zsh/complist Module</a></h2>
|
||
<p><span id="index-completion_002c-listing-1"></span>
|
||
<span id="index-completion_002c-coloured-listings"></span>
|
||
<span id="index-completion_002c-scroll-listings"></span></p>
|
||
<p>The <code>zsh/complist</code> module offers three extensions to completion
|
||
listings: the ability to highlight matches in such a list, the ability
|
||
to scroll through long lists and a different style of menu completion.</p>
|
||
<hr />
|
||
<p><span id="Colored-completion-listings"></span></p>
|
||
<h3 id="2271-colored-completion-listings"><a class="header" href="#2271-colored-completion-listings">22.7.1 Colored completion listings</a></h3>
|
||
<p>Whenever one of the parameters <code>ZLS_COLORS</code> or <code>ZLS_COLOURS</code> is set and
|
||
the <code>zsh/complist</code> module is loaded or linked into the shell, completion
|
||
lists will be colored. Note, however, that <code>complist</code> will not
|
||
automatically be loaded if it is not linked in: on systems with dynamic
|
||
loading, ‘<code>zmodload zsh/complist</code>’ is required.</p>
|
||
<p><span id="index-ZLS_005fCOLORS"></span>
|
||
<span id="index-ZLS_005fCOLOURS"></span></p>
|
||
<p>The parameters <code>ZLS_COLORS</code> and <code>ZLS_COLOURS</code> describe how matches are
|
||
highlighted. To turn on highlighting an empty value suffices, in which
|
||
case all the default values given below will be used. The format of the
|
||
value of these parameters is the same as used by the GNU version of the
|
||
<code>ls</code> command: a colon-separated list of specifications of the form
|
||
‘<code>name``=``value</code>’. The <code>name</code> may be one of the following strings,
|
||
most of which specify file types for which the <code>value</code> will be used. The
|
||
strings and their default values are:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>no 0</code><br />
|
||
for normal text (i.e. when displaying something other than a matched
|
||
file)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>fi 0</code><br />
|
||
for regular files</p>
|
||
</li>
|
||
<li>
|
||
<p><code>di 32</code><br />
|
||
for directories</p>
|
||
</li>
|
||
<li>
|
||
<p><code>ln 36</code><br />
|
||
for symbolic links. If this has the special value <code>target</code>, symbolic
|
||
links are dereferenced and the target file used to determine the
|
||
display format.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>pi 31</code><br />
|
||
for named pipes (FIFOs)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>so 33</code><br />
|
||
for sockets</p>
|
||
</li>
|
||
<li>
|
||
<p><code>bd 44;37</code><br />
|
||
for block devices</p>
|
||
</li>
|
||
<li>
|
||
<p><code>cd 44;37</code><br />
|
||
for character devices</p>
|
||
</li>
|
||
<li>
|
||
<p><code>or</code> <code>none</code><br />
|
||
for a symlink to nonexistent file (default is the value defined for
|
||
<code>ln</code>)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>mi</code> <code>none</code><br />
|
||
for a non-existent file (default is the value defined for <code>fi</code>);
|
||
this code is currently not used</p>
|
||
</li>
|
||
<li>
|
||
<p><code>su 37;41</code><br />
|
||
for files with setuid bit set</p>
|
||
</li>
|
||
<li>
|
||
<p><code>sg 30;43</code><br />
|
||
for files with setgid bit set</p>
|
||
</li>
|
||
<li>
|
||
<p><code>tw 30;42</code><br />
|
||
<code>ow 34;43</code><br />
|
||
<code>sa</code> <code>none</code><br />
|
||
for files with an associated suffix alias; this is only tested after
|
||
specific suffixes, as described below</p>
|
||
</li>
|
||
<li>
|
||
<p><code>st 37;44</code><br />
|
||
<code>ex 35</code><br />
|
||
<code>lc \e[</code><br />
|
||
for the left code (see below)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>rc m</code><br />
|
||
for the right code</p>
|
||
</li>
|
||
<li>
|
||
<p><code>tc 0</code><br />
|
||
for the character indicating the file type printed after filenames
|
||
if the <code>LIST_TYPES</code> option is set</p>
|
||
</li>
|
||
<li>
|
||
<p><code>sp 0</code><br />
|
||
for the spaces printed after matches to align the next column</p>
|
||
</li>
|
||
<li>
|
||
<p><code>ec</code> <code>none</code><br />
|
||
for the end code</p>
|
||
</li>
|
||
</ul>
|
||
<p>Apart from these strings, the <code>name</code> may also be an asterisk (‘<code>*</code>’)
|
||
followed by any string. The <code>value</code> given for such a string will be used
|
||
for all files whose name ends with the string. The <code>name</code> may also be an
|
||
equals sign (‘<code>=</code>’) followed by a pattern; the <code>EXTENDED_GLOB</code> option
|
||
will be turned on for evaluation of the pattern. The <code>value</code> given for
|
||
this pattern will be used for all matches (not just filenames) whose
|
||
display string are matched by the pattern. Definitions for the form with
|
||
the leading equal sign take precedence over the values defined for file
|
||
types, which in turn take precedence over the form with the leading
|
||
asterisk (file extensions).</p>
|
||
<p>The leading-equals form also allows different parts of the displayed
|
||
strings to be colored differently. For this, the pattern has to use the
|
||
‘<code>(#b)</code>’ globbing flag and pairs of parentheses surrounding the parts
|
||
of the strings that are to be colored differently. In this case the
|
||
<code>value</code> may consist of more than one color code separated by equal
|
||
signs. The first code will be used for all parts for which no explicit
|
||
code is specified and the following codes will be used for the parts
|
||
matched by the sub-patterns in parentheses. For example, the
|
||
specification ‘<code>=(#b)(?)*(?)=0=3=7</code>’ will be used for all matches which
|
||
are at least two characters long and will use the code ‘<code>3</code>’ for the
|
||
first character, ‘<code>7</code>’ for the last character and ‘<code>0</code>’ for the rest.</p>
|
||
<p>All three forms of <code>name</code> may be preceded by a pattern in parentheses.
|
||
If this is given, the <code>value</code> will be used only for matches in groups
|
||
whose names are matched by the pattern given in the parentheses. For
|
||
example, ‘<code>(g*)m*=43</code>’ highlights all matches beginning with ‘<code>m</code>’ in
|
||
groups whose names begin with ‘<code>g</code>’ using the color code ‘<code>43</code>’. In case
|
||
of the ‘<code>lc</code>’, ‘<code>rc</code>’, and ‘<code>ec</code>’ codes, the group pattern is ignored.</p>
|
||
<p>Note also that all patterns are tried in the order in which they appear
|
||
in the parameter value until the first one matches which is then used.
|
||
Patterns may be matched against completions, descriptions (possibly with
|
||
spaces appended for padding), or lines consisting of a completion
|
||
followed by a description. For consistent coloring it may be necessary
|
||
to use more than one pattern or a pattern with backreferences.</p>
|
||
<p>When printing a match, the code prints the value of <code>lc</code>, the value for
|
||
the file-type or the last matching specification with a ‘<code>*</code>’, the value
|
||
of <code>rc</code>, the string to display for the match itself, and then the value
|
||
of <code>ec</code> if that is defined or the values of <code>lc</code>, <code>no</code>, and <code>rc</code> if <code>ec</code>
|
||
is not defined.</p>
|
||
<p>The default values are ISO 6429 (ANSI) compliant and can be used on
|
||
vt100 compatible terminals such as <code>xterm</code>s. On monochrome terminals the
|
||
default values will have no visible effect. The <code>colors</code> function from
|
||
the contribution can be used to get associative arrays containing the
|
||
codes for ANSI terminals (see <a href="User-Contributions.html#Other-Functions">Other
|
||
Functions</a>). For example, after
|
||
loading <code>colors</code>, one could use ‘<code>$color[red]</code>’ to get the code for
|
||
foreground color red and ‘<code>$color[bg-green]</code>’ for the code for
|
||
background color green.</p>
|
||
<p>If the completion system invoked by compinit is used, these parameters
|
||
should not be set directly because the system controls them itself.
|
||
Instead, the <code>list-colors</code> style should be used (see <a href="Completion-System.html#Completion-System-Configuration">Completion System
|
||
Configuration</a>).</p>
|
||
<hr />
|
||
<p><span id="Scrolling-in-completion-listings"></span></p>
|
||
<h3 id="2272-scrolling-in-completion-listings"><a class="header" href="#2272-scrolling-in-completion-listings">22.7.2 Scrolling in completion listings</a></h3>
|
||
<p>To enable scrolling through a completion list, the <code>LISTPROMPT</code>
|
||
parameter must be set. Its value will be used as the prompt; if it is
|
||
the empty string, a default prompt will be used. The value may contain
|
||
escapes of the form ‘<code>%x</code>’. It supports the escapes ‘<code>%B</code>’, ‘<code>%b</code>’,
|
||
‘<code>%S</code>’, ‘<code>%s</code>’, ‘<code>%U</code>’, ‘<code>%u</code>’, ‘<code>%F</code>’, ‘<code>%f</code>’, ‘<code>%K</code>’, ‘<code>%k</code>’ and
|
||
‘<code>%{``...``%}</code>’ used also in shell prompts as well as three pairs of
|
||
additional sequences: a ‘<code>%l</code>’ or ‘<code>%L</code>’ is replaced by the number of
|
||
the last line shown and the total number of lines in the form
|
||
‘<code>number``/``total</code>’; a ‘<code>%m</code>’ or ‘<code>%M</code>’ is replaced with the number
|
||
of the last match shown and the total number of matches; and ‘<code>%p</code>’ or
|
||
‘<code>%P</code>’ is replaced with ‘<code>Top</code>’, ‘<code>Bottom</code>’ or the position of the
|
||
first line shown in percent of the total number of lines, respectively.
|
||
In each of these cases the form with the uppercase letter will be
|
||
replaced with a string of fixed width, padded to the right with spaces,
|
||
while the lowercase form will not be padded.</p>
|
||
<p>If the parameter <code>LISTPROMPT</code> is set, the completion code will not ask
|
||
if the list should be shown. Instead it immediately starts displaying
|
||
the list, stopping after the first screenful, showing the prompt at the
|
||
bottom, waiting for a keypress after temporarily switching to the
|
||
<code>listscroll</code> keymap. Some of the zle functions have a special meaning
|
||
while scrolling lists:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>send-break</code><br />
|
||
stops listing discarding the key pressed</p>
|
||
</li>
|
||
<li>
|
||
<p><code>accept-line</code>, <code>down-history</code>, <code>down-line-or-history</code><br />
|
||
<code>down-line-or-search</code>, <code>vi-down-line-or-history</code><br />
|
||
scrolls forward one line</p>
|
||
</li>
|
||
<li>
|
||
<p><code>complete-word</code>, <code>menu-complete</code>, <code>expand-or-complete</code><br />
|
||
<code>expand-or-complete-prefix</code>, <code>menu-complete-or-expand</code><br />
|
||
scrolls forward one screenful</p>
|
||
</li>
|
||
<li>
|
||
<p><code>accept-search</code><br />
|
||
stop listing but take no other action</p>
|
||
</li>
|
||
</ul>
|
||
<p>Every other character stops listing and immediately processes the key as
|
||
usual. Any key that is not bound in the <code>listscroll</code> keymap or that is
|
||
bound to <code>undefined-key</code> is looked up in the keymap currently selected.</p>
|
||
<p>As for the <code>ZLS_COLORS</code> and <code>ZLS_COLOURS</code> parameters, <code>LISTPROMPT</code>
|
||
should not be set directly when using the shell function based
|
||
completion system. Instead, the <code>list-prompt</code> style should be used.</p>
|
||
<hr />
|
||
<p><span id="Menu-selection"></span></p>
|
||
<h3 id="2273-menu-selection"><a class="header" href="#2273-menu-selection">22.7.3 Menu selection</a></h3>
|
||
<p><span id="index-completion_002c-selecting-by-cursor"></span>
|
||
<span id="index-MENUSELECT"></span>
|
||
<span id="index-menu_002dselect"></span></p>
|
||
<p>The <code>zsh/complist</code> module also offers an alternative style of selecting
|
||
matches from a list, called menu selection, which can be used if the
|
||
shell is set up to return to the last prompt after showing a completion
|
||
list (see the <code>ALWAYS_LAST_PROMPT</code> option in
|
||
<a href="Options.html#Options">Options</a>).</p>
|
||
<p>Menu selection can be invoked directly by the widget <code>menu-select</code>
|
||
defined by this module. This is a standard ZLE widget that can be bound
|
||
to a key in the usual way as described in <a href="Zsh-Line-Editor.html#Zsh-Line-Editor">Zsh Line
|
||
Editor</a>.</p>
|
||
<p>Alternatively, the parameter <code>MENUSELECT</code> can be set to an integer,
|
||
which gives the minimum number of matches that must be present before
|
||
menu selection is automatically turned on. This second method requires
|
||
that menu completion be started, either directly from a widget such as
|
||
<code>menu-complete</code>, or due to one of the options <code>MENU_COMPLETE</code> or
|
||
<code>AUTO_MENU</code> being set. If <code>MENUSELECT</code> is set, but is 0, 1 or empty,
|
||
menu selection will always be started during an ambiguous menu
|
||
completion.</p>
|
||
<p>When using the completion system based on shell functions, the
|
||
<code>MENUSELECT</code> parameter should not be used (like the <code>ZLS_COLORS</code> and
|
||
<code>ZLS_COLOURS</code> parameters described above). Instead, the <code>menu</code> style
|
||
should be used with the <code>select=``...</code> keyword.</p>
|
||
<p>After menu selection is started, the matches will be listed. If there
|
||
are more matches than fit on the screen, only the first screenful is
|
||
shown. The matches to insert into the command line can be selected from
|
||
this list. In the list one match is highlighted using the value for <code>ma</code>
|
||
from the <code>ZLS_COLORS</code> or <code>ZLS_COLOURS</code> parameter. The default value for
|
||
this is ‘<code>7</code>’ which forces the selected match to be highlighted using
|
||
standout mode on a vt100-compatible terminal. If neither <code>ZLS_COLORS</code>
|
||
nor <code>ZLS_COLOURS</code> is set, the same terminal control sequence as for the
|
||
‘<code>%S</code>’ escape in prompts is used.</p>
|
||
<p>If there are more matches than fit on the screen and the parameter
|
||
<code>MENUPROMPT</code> is set, its value will be shown below the matches. It
|
||
supports the same escape sequences as <code>LISTPROMPT</code>, but the number of
|
||
the match or line shown will be that of the one where the mark is
|
||
placed. If its value is the empty string, a default prompt will be used.</p>
|
||
<p>The <code>MENUSCROLL</code> parameter can be used to specify how the list is
|
||
scrolled. If the parameter is unset, this is done line by line, if it is
|
||
set to ‘<code>0</code>’ (zero), the list will scroll half the number of lines of
|
||
the screen. If the value is positive, it gives the number of lines to
|
||
scroll and if it is negative, the list will be scrolled the number of
|
||
lines of the screen minus the (absolute) value.</p>
|
||
<p>As for the <code>ZLS_COLORS</code>, <code>ZLS_COLOURS</code> and <code>LISTPROMPT</code> parameters,
|
||
neither <code>MENUPROMPT</code> nor <code>MENUSCROLL</code> should be set directly when using
|
||
the shell function based completion system. Instead, the <code>select-prompt</code>
|
||
and <code>select-scroll</code> styles should be used.</p>
|
||
<p>The completion code sometimes decides not to show all of the matches in
|
||
the list. These hidden matches are either matches for which the
|
||
completion function which added them explicitly requested that they not
|
||
appear in the list (using the <code>-n</code> option of the <code>compadd</code> builtin
|
||
command) or they are matches which duplicate a string already in the
|
||
list (because they differ only in things like prefixes or suffixes that
|
||
are not displayed). In the list used for menu selection, however, even
|
||
these matches are shown so that it is possible to select them. To
|
||
highlight such matches the <code>hi</code> and <code>du</code> capabilities in the
|
||
<code>ZLS_COLORS</code> and <code>ZLS_COLOURS</code> parameters are supported for hidden
|
||
matches of the first and second kind, respectively.</p>
|
||
<p>Selecting matches is done by moving the mark around using the zle
|
||
movement functions. When not all matches can be shown on the screen at
|
||
the same time, the list will scroll up and down when crossing the top or
|
||
bottom line. The following zle functions have special meaning during
|
||
menu selection. Note that the following always perform the same task
|
||
within the menu selection map and cannot be replaced by user defined
|
||
widgets, nor can the set of functions be extended:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>accept-line</code>, <code>accept-search</code><br />
|
||
accept the current match and leave menu selection (but do not cause
|
||
the command line to be accepted)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>send-break</code><br />
|
||
leaves menu selection and restores the previous contents of the
|
||
command line</p>
|
||
</li>
|
||
<li>
|
||
<p><code>redisplay</code>, <code>clear-screen</code><br />
|
||
execute their normal function without leaving menu selection</p>
|
||
</li>
|
||
<li>
|
||
<p><code>accept-and-hold</code>, <code>accept-and-menu-complete</code><br />
|
||
accept the currently inserted match and continue selection allowing
|
||
to select the next match to insert into the line</p>
|
||
</li>
|
||
<li>
|
||
<p><code>accept-and-infer-next-history</code><br />
|
||
accepts the current match and then tries completion with menu
|
||
selection again; in the case of files this allows one to select a
|
||
directory and immediately attempt to complete files in it; if there
|
||
are no matches, a message is shown and one can use <code>undo</code> to go back
|
||
to completion on the previous level, every other key leaves menu
|
||
selection (including the other zle functions which are otherwise
|
||
special during menu selection)</p>
|
||
</li>
|
||
<li>
|
||
<p><code>undo</code><br />
|
||
removes matches inserted during the menu selection by one of the
|
||
three functions before</p>
|
||
</li>
|
||
<li>
|
||
<p><code>down-history</code>, <code>down-line-or-history</code><br />
|
||
<code>vi-down-line-or-history</code>, <code>down-line-or-search</code><br />
|
||
moves the mark one line down</p>
|
||
</li>
|
||
<li>
|
||
<p><code>up-history</code>, <code>up-line-or-history</code><br />
|
||
<code>vi-up-line-or-history</code>, <code>up-line-or-search</code><br />
|
||
moves the mark one line up</p>
|
||
</li>
|
||
<li>
|
||
<p><code>forward-char</code>, <code>vi-forward-char</code><br />
|
||
moves the mark one column right</p>
|
||
</li>
|
||
<li>
|
||
<p><code>backward-char</code>, <code>vi-backward-char</code><br />
|
||
moves the mark one column left</p>
|
||
</li>
|
||
<li>
|
||
<p><code>forward-word</code>, <code>vi-forward-word</code><br />
|
||
<code>vi-forward-word-end</code>, <code>emacs-forward-word</code><br />
|
||
moves the mark one screenful down</p>
|
||
</li>
|
||
<li>
|
||
<p><code>backward-word</code>, <code>vi-backward-word</code>, <code>emacs-backward-word</code><br />
|
||
moves the mark one screenful up</p>
|
||
</li>
|
||
<li>
|
||
<p><code>vi-forward-blank-word</code>, <code>vi-forward-blank-word-end</code><br />
|
||
moves the mark to the first line of the next group of matches</p>
|
||
</li>
|
||
<li>
|
||
<p><code>vi-backward-blank-word</code><br />
|
||
moves the mark to the last line of the previous group of matches</p>
|
||
</li>
|
||
<li>
|
||
<p><code>beginning-of-history</code><br />
|
||
moves the mark to the first line</p>
|
||
</li>
|
||
<li>
|
||
<p><code>end-of-history</code><br />
|
||
moves the mark to the last line</p>
|
||
</li>
|
||
<li>
|
||
<p><code>beginning-of-buffer-or-history</code>, <code>beginning-of-line</code><br />
|
||
<code>beginning-of-line-hist</code>, <code>vi-beginning-of-line</code><br />
|
||
moves the mark to the leftmost column</p>
|
||
</li>
|
||
<li>
|
||
<p><code>end-of-buffer-or-history</code>, <code>end-of-line</code><br />
|
||
<code>end-of-line-hist</code>, <code>vi-end-of-line</code><br />
|
||
moves the mark to the rightmost column</p>
|
||
</li>
|
||
<li>
|
||
<p><code>complete-word</code>, <code>menu-complete</code>, <code>expand-or-complete</code><br />
|
||
<code>expand-or-complete-prefix</code>, <code>menu-expand-or-complete</code><br />
|
||
moves the mark to the next match</p>
|
||
</li>
|
||
<li>
|
||
<p><code>reverse-menu-complete</code><br />
|
||
moves the mark to the previous match</p>
|
||
</li>
|
||
<li>
|
||
<p><code>vi-insert</code><br />
|
||
this toggles between normal and interactive mode; in interactive
|
||
mode the keys bound to <code>self-insert</code> and <code>self-insert-unmeta</code> insert
|
||
into the command line as in normal editing mode but without leaving
|
||
menu selection; after each character completion is tried again and
|
||
the list changes to contain only the new matches; the completion
|
||
widgets make the longest unambiguous string be inserted in the
|
||
command line and <code>undo</code> and <code>backward-delete-char</code> go back to the
|
||
previous set of matches</p>
|
||
</li>
|
||
<li>
|
||
<p><code>history-incremental-search-forward</code><br />
|
||
<code>history-incremental-search-backward</code><br />
|
||
this starts incremental searches in the list of completions
|
||
displayed; in this mode, <code>accept-line</code> only leaves incremental
|
||
search, going back to the normal menu selection mode</p>
|
||
</li>
|
||
</ul>
|
||
<p>All movement functions wrap around at the edges; any other zle function
|
||
not listed leaves menu selection and executes that function. It is
|
||
possible to make widgets in the above list do the same by using the form
|
||
of the widget with a ‘<code>.</code>’ in front. For example, the widget
|
||
‘<code>.accept-line</code>’ has the effect of leaving menu selection and
|
||
accepting the entire command line.</p>
|
||
<p>During this selection the widget uses the keymap <code>menuselect</code>. Any key
|
||
that is not defined in this keymap or that is bound to <code>undefined-key</code>
|
||
is looked up in the keymap currently selected. This is used to ensure
|
||
that the most important keys used during selection (namely the cursor
|
||
keys, return, and TAB) have sensible defaults. However, keys in the
|
||
<code>menuselect</code> keymap can be modified directly using the <code>bindkey</code> builtin
|
||
command (see <a href="#The-zsh_002fzle-Module">The zsh/zle Module</a>). For
|
||
example, to make the return key leave menu selection without accepting
|
||
the match currently selected one could call</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">bindkey -M menuselect '^M' send-break
|
||
</code></pre>
|
||
</div>
|
||
<p>after loading the <code>zsh/complist</code> module.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fcomputil-Module"></span>
|
||
<span id="The-zsh_002fcomputil-Module-1"></span></p>
|
||
<h2 id="228-the-zshcomputil-module"><a class="header" href="#228-the-zshcomputil-module">22.8 The zsh/computil Module</a></h2>
|
||
<p><span id="index-completion_002c-utility"></span></p>
|
||
<p>The <code>zsh/computil</code> module adds several builtin commands that are used by
|
||
some of the completion functions in the completion system based on shell
|
||
functions (see <a href="Completion-System.html#Completion-System">Completion
|
||
System</a> ). Except for
|
||
<code>compquote</code> these builtin commands are very specialised and thus not
|
||
very interesting when writing your own completion functions. In summary,
|
||
these builtin commands are:</p>
|
||
<p><span id="index-comparguments"></span></p>
|
||
<p><code>comparguments</code></p>
|
||
<p>This is used by the <code>_arguments</code> function to do the argument and command
|
||
line parsing. Like <code>compdescribe</code> it has an option <code>-i</code> to do the
|
||
parsing and initialize some internal state and various options to access
|
||
the state information to decide what should be completed.</p>
|
||
<p><span id="index-compdescribe"></span></p>
|
||
<p><code>compdescribe</code></p>
|
||
<p>This is used by the <code>_describe</code> function to build the displays for the
|
||
matches and to get the strings to add as matches with their options. On
|
||
the first call one of the options <code>-i</code> or <code>-I</code> should be supplied as the
|
||
first argument. In the first case, display strings without the
|
||
descriptions will be generated, in the second case, the string used to
|
||
separate the matches from their descriptions must be given as the second
|
||
argument and the descriptions (if any) will be shown. All other
|
||
arguments are like the definition arguments to <code>_describe</code> itself.</p>
|
||
<p>Once <code>compdescribe</code> has been called with either the <code>-i</code> or the <code>-I</code>
|
||
option, it can be repeatedly called with the <code>-g</code> option and the names
|
||
of four parameters as its arguments. This will step through the
|
||
different sets of matches and store the value of <code>compstate[list]</code> in
|
||
the first scalar, the options for <code>compadd</code> in the second array, the
|
||
matches in the third array, and the strings to be displayed in the
|
||
completion listing in the fourth array. The arrays may then be directly
|
||
given to <code>compadd</code> to register the matches with the completion code.</p>
|
||
<p><span id="index-compfiles"></span></p>
|
||
<p><code>compfiles</code></p>
|
||
<p>Used by the <code>_path_files</code> function to optimize complex recursive
|
||
filename generation (globbing). It does three things. With the <code>-p</code> and
|
||
<code>-P</code> options it builds the glob patterns to use, including the paths
|
||
already handled and trying to optimize the patterns with respect to the
|
||
prefix and suffix from the line and the match specification currently
|
||
used. The <code>-i</code> option does the directory tests for the <code>ignore-parents</code>
|
||
style and the <code>-r</code> option tests if a component for some of the matches
|
||
are equal to the string on the line and removes all other matches if
|
||
that is true.</p>
|
||
<p><span id="index-compgroups"></span></p>
|
||
<p><code>compgroups</code></p>
|
||
<p>Used by the <code>_tags</code> function to implement the internals of the
|
||
<code>group-order</code> style. This only takes its arguments as names of
|
||
completion groups and creates the groups for it (all six types: sorted
|
||
and unsorted, both without removing duplicates, with removing all
|
||
duplicates and with removing consecutive duplicates).</p>
|
||
<p><span id="index-compquote"></span></p>
|
||
<p><code>compquote</code> [ <code>-p</code> ] <code>names</code> ...</p>
|
||
<p>There may be reasons to write completion functions that have to add the
|
||
matches using the <code>-Q</code> option to <code>compadd</code> and perform quoting
|
||
themselves. Instead of interpreting the first character of the
|
||
<code>all_quotes</code> key of the <code>compstate</code> special association and using the
|
||
<code>q</code> flag for parameter expansions, one can use this builtin command. The
|
||
arguments are the names of scalar or array parameters and the values of
|
||
these parameters are quoted as needed for the innermost quoting level.
|
||
If the <code>-p</code> option is given, quoting is done as if there is some prefix
|
||
before the values of the parameters, so that a leading equal sign will
|
||
not be quoted.</p>
|
||
<p>The return status is non-zero in case of an error and zero otherwise.</p>
|
||
<p><span id="index-comptags"></span> <span id="index-comptry"></span></p>
|
||
<p><code>comptags</code></p>
|
||
<p><code>comptry</code></p>
|
||
<p>These implement the internals of the tags mechanism.</p>
|
||
<p><span id="index-compvalues"></span></p>
|
||
<p><code>compvalues</code></p>
|
||
<p>Like <code>comparguments</code>, but for the <code>_values</code> function.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fcurses-Module"></span>
|
||
<span id="The-zsh_002fcurses-Module-1"></span></p>
|
||
<h2 id="229-the-zshcurses-module"><a class="header" href="#229-the-zshcurses-module">22.9 The zsh/curses Module</a></h2>
|
||
<p>The <code>zsh/curses</code> module makes available one builtin command and various
|
||
parameters.</p>
|
||
<hr />
|
||
<p><span id="Builtin"></span></p>
|
||
<h3 id="2291-builtin"><a class="header" href="#2291-builtin">22.9.1 Builtin</a></h3>
|
||
<p><span id="index-zcurses"></span>
|
||
<span id="index-windows_002c-curses"></span></p>
|
||
<p><code>zcurses</code> <code>init</code></p>
|
||
<p><code>zcurses</code> <code>end</code></p>
|
||
<p><code>zcurses</code> <code>addwin</code> <code>targetwin</code> <code>nlines</code> <code>ncols</code> <code>begin_y</code> <code>begin_x</code> [
|
||
<code>parentwin</code> ]</p>
|
||
<p><code>zcurses</code> <code>delwin</code> <code>targetwin</code></p>
|
||
<p><code>zcurses</code> <code>refresh</code> [ <code>targetwin</code> ... ]</p>
|
||
<p><code>zcurses</code> <code>touch</code> <code>targetwin</code> ...</p>
|
||
<p><code>zcurses</code> <code>move</code> <code>targetwin</code> <code>new_y</code> <code>new_x</code></p>
|
||
<p><code>zcurses</code> <code>clear</code> <code>targetwin</code> [ <code>redraw</code> | <code>eol</code> | <code>bot</code> ]</p>
|
||
<p><code>zcurses</code> <code>position</code> <code>targetwin</code> <code>array</code></p>
|
||
<p><code>zcurses</code> <code>char</code> <code>targetwin</code> <code>character</code></p>
|
||
<p><code>zcurses</code> <code>string</code> <code>targetwin</code> <code>string</code></p>
|
||
<p><code>zcurses</code> <code>border</code> <code>targetwin</code> <code>border</code></p>
|
||
<p><code>zcurses</code> <code>attr</code> <code>targetwin</code> [ [<code>+</code>|<code>-</code>]<code>attribute</code> |
|
||
<code>fg_col``/``bg_col</code> ] [...]</p>
|
||
<p><code>zcurses</code> <code>bg</code> <code>targetwin</code> [ [<code>+</code>|<code>-</code>]<code>attribute</code> |
|
||
<code>fg_col``/``bg_col</code> | <code>@``char</code> ] [...]</p>
|
||
<p><code>zcurses</code> <code>scroll</code> <code>targetwin</code> [ <code>on</code> | <code>off</code> | [<code>+</code>|<code>-</code>]<code>lines</code> ]</p>
|
||
<p><code>zcurses</code> <code>input</code> <code>targetwin</code> [ <code>param</code> [ <code>kparam</code> [ <code>mparam</code> ] ]
|
||
]</p>
|
||
<p><code>zcurses</code> <code>mouse</code> [ <code>delay</code> <code>num</code> | [<code>+</code>|<code>-</code>]<code>motion</code> ]</p>
|
||
<p><code>zcurses</code> <code>timeout</code> <code>targetwin</code> <code>intval</code></p>
|
||
<p><code>zcurses</code> <code>querychar</code> <code>targetwin</code> [ <code>param</code> ]</p>
|
||
<p><code>zcurses</code> <code>resize</code> <code>height</code> <code>width</code> [ <code>endwin</code> | <code>nosave</code> |
|
||
<code>endwin_nosave</code> ]</p>
|
||
<p>Manipulate curses windows. All uses of this command should be bracketed
|
||
by ‘<code>zcurses init</code>’ to initialise use of curses, and ‘<code>zcurses end</code>’ to
|
||
end it; omitting ‘<code>zcurses end</code>’ can cause the terminal to be in an
|
||
unwanted state.</p>
|
||
<p>The subcommand <code>addwin</code> creates a window with <code>nlines</code> lines and <code>ncols</code>
|
||
columns. Its upper left corner will be placed at row <code>begin_y</code> and
|
||
column <code>begin_x</code> of the screen. <code>targetwin</code> is a string and refers to
|
||
the name of a window that is not currently assigned. Note in particular
|
||
the curses convention that vertical values appear before horizontal
|
||
values.</p>
|
||
<p>If <code>addwin</code> is given an existing window as the final argument, the new
|
||
window is created as a subwindow of <code>parentwin</code>. This differs from an
|
||
ordinary new window in that the memory of the window contents is shared
|
||
with the parent’s memory. Subwindows must be deleted before their
|
||
parent. Note that the coordinates of subwindows are relative to the
|
||
screen, not the parent, as with other windows.</p>
|
||
<p>Use the subcommand <code>delwin</code> to delete a window created with <code>addwin</code>.
|
||
Note that <code>end</code> does <em>not</em> implicitly delete windows, and that <code>delwin</code>
|
||
does not erase the screen image of the window.</p>
|
||
<p>The window corresponding to the full visible screen is called <code>stdscr</code>;
|
||
it always exists after ‘<code>zcurses init</code>’ and cannot be delete with
|
||
<code>delwin</code>.</p>
|
||
<p>The subcommand <code>refresh</code> will refresh window <code>targetwin</code>; this is
|
||
necessary to make any pending changes (such as characters you have
|
||
prepared for output with <code>char</code>) visible on the screen. <code>refresh</code>
|
||
without an argument causes the screen to be cleared and redrawn. If
|
||
multiple windows are given, the screen is updated once at the end.</p>
|
||
<p>The subcommand <code>touch</code> marks the <code>targetwin</code>s listed as changed. This is
|
||
necessary before <code>refresh</code>ing windows if a window that was in front of
|
||
another window (which may be <code>stdscr</code>) is deleted.</p>
|
||
<p>The subcommand <code>move</code> moves the cursor position in <code>targetwin</code> to new
|
||
coordinates <code>new_y</code> and <code>new_x</code>. Note that the subcommand <code>string</code> (but
|
||
not the subcommand <code>char</code>) advances the cursor position over the
|
||
characters added.</p>
|
||
<p>The subcommand <code>clear</code> erases the contents of <code>targetwin</code>. One (and no
|
||
more than one) of three options may be specified. With the option
|
||
<code>redraw</code>, in addition the next <code>refresh</code> of <code>targetwin</code> will cause the
|
||
screen to be cleared and repainted. With the option <code>eol</code>, <code>targetwin</code>
|
||
is only cleared to the end of the current cursor line. With the option
|
||
<code>bot</code>, <code>targetwin</code> is cleared to the end of the window, i.e everything
|
||
to the right and below the cursor is cleared.</p>
|
||
<p>The subcommand <code>position</code> writes various positions associated with
|
||
<code>targetwin</code> into the array named <code>array</code>. These are, in order:</p>
|
||
<ul>
|
||
<li>
|
||
<p>-<br />
|
||
The y and x coordinates of the cursor relative to the top left of
|
||
<code>targetwin</code></p>
|
||
</li>
|
||
<li>
|
||
<p>-<br />
|
||
The y and x coordinates of the top left of <code>targetwin</code> on the screen</p>
|
||
</li>
|
||
<li>
|
||
<p>-<br />
|
||
The size of <code>targetwin</code> in y and x dimensions.</p>
|
||
</li>
|
||
</ul>
|
||
<p>Outputting characters and strings are achieved by <code>char</code> and <code>string</code>
|
||
respectively.</p>
|
||
<p>To draw a border around window <code>targetwin</code>, use <code>border</code>. Note that the
|
||
border is not subsequently handled specially: in other words, the border
|
||
is simply a set of characters output at the edge of the window. Hence it
|
||
can be overwritten, can scroll off the window, etc.</p>
|
||
<p>The subcommand <code>attr</code> will set <code>targetwin</code>’s attributes or
|
||
foreground/background color pair for any successive character output.
|
||
Each <code>attribute</code> given on the line may be prepended by a <code>+</code> to set or a
|
||
<code>-</code> to unset that attribute; <code>+</code> is assumed if absent. The attributes
|
||
supported are <code>blink</code>, <code>bold</code>, <code>dim</code>, <code>reverse</code>, <code>standout</code>, and
|
||
<code>underline</code>.</p>
|
||
<p>Each <code>fg_col``/``bg_col</code> attribute (to be read as ‘<code>fg_col</code> on
|
||
<code>bg_col</code>’) sets the foreground and background color for character
|
||
output. The color <code>default</code> is sometimes available (in particular if the
|
||
library is ncurses), specifying the foreground or background color with
|
||
which the terminal started. The color pair <code>default/default</code> is always
|
||
available. To use more than the 8 named colors (red, green, etc.)
|
||
construct the <code>fg_col``/``bg_col</code> pairs where <code>fg_col</code> and <code>bg_col</code> are
|
||
decimal integers, e.g <code>128/200</code>. The maximum color value is 254 if the
|
||
terminal supports 256 colors.</p>
|
||
<p><code>bg</code> overrides the color and other attributes of all characters in the
|
||
window. Its usual use is to set the background initially, but it will
|
||
overwrite the attributes of any characters at the time when it is
|
||
called. In addition to the arguments allowed with <code>attr</code>, an argument
|
||
<code>@``char</code> specifies a character to be shown in otherwise blank areas of
|
||
the window. Owing to limitations of curses this cannot be a multibyte
|
||
character (use of ASCII characters only is recommended). As the
|
||
specified set of attributes override the existing background, turning
|
||
attributes off in the arguments is not useful, though this does not
|
||
cause an error.</p>
|
||
<p>The subcommand <code>scroll</code> can be used with <code>on</code> or <code>off</code> to enabled or
|
||
disable scrolling of a window when the cursor would otherwise move below
|
||
the window due to typing or output. It can also be used with a positive
|
||
or negative integer to scroll the window up or down the given number of
|
||
lines without changing the current cursor position (which therefore
|
||
appears to move in the opposite direction relative to the window). In
|
||
the second case, if scrolling is <code>off</code> it is temporarily turned <code>on</code> to
|
||
allow the window to be scrolled.</p>
|
||
<p>The subcommand <code>input</code> reads a single character from the window without
|
||
echoing it back. If <code>param</code> is supplied the character is assigned to the
|
||
parameter <code>param</code>, else it is assigned to the parameter <code>REPLY</code>.</p>
|
||
<p>If both <code>param</code> and <code>kparam</code> are supplied, the key is read in ‘keypad’
|
||
mode. In this mode special keys such as function keys and arrow keys
|
||
return the name of the key in the parameter <code>kparam</code>. The key names are
|
||
the macros defined in the <code>curses.h</code> or <code>ncurses.h</code> with the prefix
|
||
‘<code>KEY_</code>’ removed; see also the description of the parameter
|
||
<code>zcurses_keycodes</code> below. Other keys cause a value to be set in <code>param</code>
|
||
as before. On a successful return only one of <code>param</code> or <code>kparam</code>
|
||
contains a non-empty string; the other is set to an empty string.</p>
|
||
<p>If <code>mparam</code> is also supplied, <code>input</code> attempts to handle mouse input.
|
||
This is only available with the ncurses library; mouse handling can be
|
||
detected by checking for the exit status of ‘<code>zcurses mouse</code>’ with no
|
||
arguments. If a mouse button is clicked (or double- or triple-clicked,
|
||
or pressed or released with a configurable delay from being clicked)
|
||
then <code>kparam</code> is set to the string <code>MOUSE</code>, and <code>mparam</code> is set to an
|
||
array consisting of the following elements:</p>
|
||
<ul>
|
||
<li>
|
||
<p>-<br />
|
||
An identifier to discriminate different input devices; this is only
|
||
rarely useful.</p>
|
||
</li>
|
||
<li>
|
||
<p>-<br />
|
||
The x, y and z coordinates of the mouse click relative to the full
|
||
screen, as three elements in that order (i.e. the y coordinate is,
|
||
unusually, after the x coordinate). The z coordinate is only
|
||
available for a few unusual input devices and is otherwise set to
|
||
zero.</p>
|
||
</li>
|
||
<li>
|
||
<p>-<br />
|
||
Any events that occurred as separate items; usually there will be
|
||
just one. An event consists of <code>PRESSED</code>, <code>RELEASED</code>, <code>CLICKED</code>,
|
||
<code>DOUBLE_CLICKED</code> or <code>TRIPLE_CLICKED</code> followed immediately (in the
|
||
same element) by the number of the button.</p>
|
||
</li>
|
||
<li>
|
||
<p>-<br />
|
||
If the shift key was pressed, the string <code>SHIFT</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>-<br />
|
||
If the control key was pressed, the string <code>CTRL</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p>-<br />
|
||
If the alt key was pressed, the string <code>ALT</code>.</p>
|
||
</li>
|
||
</ul>
|
||
<p>Not all mouse events may be passed through to the terminal window; most
|
||
terminal emulators handle some mouse events themselves. Note that the
|
||
ncurses manual implies that using input both with and without mouse
|
||
handling may cause the mouse cursor to appear and disappear.</p>
|
||
<p>The subcommand <code>mouse</code> can be used to configure the use of the mouse.
|
||
There is no window argument; mouse options are global. ‘<code>zcurses mouse</code>’
|
||
with no arguments returns status 0 if mouse handling is possible, else
|
||
status 1. Otherwise, the possible arguments (which may be combined on
|
||
the same command line) are as follows. <code>delay</code> <code>num</code> sets the maximum
|
||
delay in milliseconds between press and release events to be considered
|
||
as a click; the value 0 disables click resolution, and the default is
|
||
one sixth of a second. <code>motion</code> proceeded by an optional ‘<code>+</code>’ (the
|
||
default) or <code>-</code> turns on or off reporting of mouse motion in addition to
|
||
clicks, presses and releases, which are always reported. However, it
|
||
appears reports for mouse motion are not currently implemented.</p>
|
||
<p>The subcommand <code>timeout</code> specifies a timeout value for input from
|
||
<code>targetwin</code>. If <code>intval</code> is negative, ‘<code>zcurses input</code>’ waits
|
||
indefinitely for a character to be typed; this is the default. If
|
||
<code>intval</code> is zero, ‘<code>zcurses input</code>’ returns immediately; if there is
|
||
typeahead it is returned, else no input is done and status 1 is
|
||
returned. If <code>intval</code> is positive, ‘<code>zcurses input</code>’ waits <code>intval</code>
|
||
milliseconds for input and if there is none at the end of that period
|
||
returns status 1.</p>
|
||
<p>The subcommand <code>querychar</code> queries the character at the current cursor
|
||
position. The return values are stored in the array named <code>param</code> if
|
||
supplied, else in the array <code>reply</code>. The first value is the character
|
||
(which may be a multibyte character if the system supports them); the
|
||
second is the color pair in the usual <code>fg_col``/``bg_col</code> notation, or
|
||
<code>0</code> if color is not supported. Any attributes other than color that
|
||
apply to the character, as set with the subcommand <code>attr</code>, appear as
|
||
additional elements.</p>
|
||
<p>The subcommand <code>resize</code> resizes <code>stdscr</code> and all windows to given
|
||
dimensions (windows that stick out from the new dimensions are resized
|
||
down). The underlying curses extension (<code>resize_term call</code>) can be
|
||
unavailable. To verify, zeroes can be used for <code>height</code> and <code>width</code>. If
|
||
the result of the subcommand is <code>0</code>, resize_term is available (<code>2</code>
|
||
otherwise). Tests show that resizing can be normally accomplished by
|
||
calling <code>zcurses end</code> and <code>zcurses refresh</code>. The <code>resize</code> subcommand is
|
||
provided for versatility. Multiple system configurations have been
|
||
checked and <code>zcurses end</code> and <code>zcurses refresh</code> are still needed for
|
||
correct terminal state after resize. To invoke them with <code>resize</code>, use
|
||
<code>endwin</code> argument. Using <code>nosave</code> argument will cause new terminal state
|
||
to not be saved internally by <code>zcurses</code>. This is also provided for
|
||
versatility and should normally be not needed.</p>
|
||
<hr />
|
||
<p><span id="Parameters-4"></span></p>
|
||
<h3 id="2292-parameters"><a class="header" href="#2292-parameters">22.9.2 Parameters</a></h3>
|
||
<p><span id="index-ZCURSES_005fCOLORS"></span></p>
|
||
<p><code>ZCURSES_COLORS</code></p>
|
||
<p>Readonly integer. The maximum number of colors the terminal supports.
|
||
This value is initialised by the curses library and is not available
|
||
until the first time <code>zcurses init</code> is run.</p>
|
||
<p><span id="index-ZCURSES_005fCOLOR_005fPAIRS"></span></p>
|
||
<p><code>ZCURSES_COLOR_PAIRS</code></p>
|
||
<p>Readonly integer. The maximum number of color pairs <code>fg_col``/``bg_col</code>
|
||
that may be defined in ‘<code>zcurses attr</code>’ commands; note this limit
|
||
applies to all color pairs that have been used whether or not they are
|
||
currently active. This value is initialised by the curses library and is
|
||
not available until the first time <code>zcurses init</code> is run.</p>
|
||
<p><span id="index-zcurses_005fattrs"></span></p>
|
||
<p><code>zcurses_attrs</code></p>
|
||
<p>Readonly array. The attributes supported by <code>zsh/curses</code>; available as
|
||
soon as the module is loaded.</p>
|
||
<p><span id="index-zcurses_005fcolors"></span></p>
|
||
<p><code>zcurses_colors</code></p>
|
||
<p>Readonly array. The colors supported by <code>zsh/curses</code>; available as soon
|
||
as the module is loaded.</p>
|
||
<p><span id="index-zcurses_005fkeycodes"></span></p>
|
||
<p><code>zcurses_keycodes</code></p>
|
||
<p>Readonly array. The values that may be returned in the second parameter
|
||
supplied to ‘<code>zcurses input</code>’ in the order in which they are defined
|
||
internally by curses. Not all function keys are listed, only <code>F0</code>;
|
||
curses reserves space for <code>F0</code> up to <code>F63</code>.</p>
|
||
<p><span id="index-zcurses_005fwindows"></span></p>
|
||
<p><code>zcurses_windows</code></p>
|
||
<p>Readonly array. The current list of windows, i.e. all windows that have
|
||
been created with ‘<code>zcurses addwin</code>’ and not removed with ‘<code>zcurses delwin</code>’.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fdatetime-Module"></span>
|
||
<span id="The-zsh_002fdatetime-Module-1"></span></p>
|
||
<h2 id="2210-the-zshdatetime-module"><a class="header" href="#2210-the-zshdatetime-module">22.10 The zsh/datetime Module</a></h2>
|
||
<p>The <code>zsh/datetime</code> module makes available one builtin command:</p>
|
||
<p><span id="index-strftime"></span>
|
||
<span id="index-date-string_002c-printing"></span></p>
|
||
<p><code>strftime</code> [ <code>-s</code> <code>scalar</code> ] <code>format</code> [ <code>epochtime</code> [ <code>nanoseconds</code>
|
||
] ]</p>
|
||
<p><code>strftime</code> <code>-r</code> [ <code>-q</code> ] [ <code>-s</code> <code>scalar</code> ] <code>format</code> <code>timestring</code></p>
|
||
<p>Output the date in the <code>format</code> specified. With no <code>epochtime</code>, the
|
||
current system date/time is used; optionally, <code>epochtime</code> may be used to
|
||
specify the number of seconds since the epoch, and <code>nanoseconds</code> may
|
||
additionally be used to specify the number of nanoseconds past the
|
||
second (otherwise that number is assumed to be 0). See man page
|
||
strftime(3) for details. The zsh extensions described in <a href="Prompt-Expansion.html#Prompt-Expansion">Prompt
|
||
Expansion</a> are also available.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>-q</code><br />
|
||
Run quietly; suppress printing of all error messages described
|
||
below. Errors for invalid <code>epochtime</code> values are always printed.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-r</code><br />
|
||
With the option <code>-r</code> (reverse), use <code>format</code> to parse the input
|
||
string <code>timestring</code> and output the number of seconds since the epoch
|
||
at which the time occurred. The parsing is implemented by the system
|
||
function <code>strptime</code>; see man page strptime(3). This means that zsh
|
||
format extensions are not available, but for reverse lookup they are
|
||
not required.</p>
|
||
<p>In most implementations of <code>strftime</code> any timezone in the
|
||
<code>timestring</code> is ignored and the local timezone declared by the <code>TZ</code>
|
||
environment variable is used; other parameters are set to zero if
|
||
not present.</p>
|
||
<p>If <code>timestring</code> does not match <code>format</code> the command returns status 1
|
||
and prints an error message. If <code>timestring</code> matches <code>format</code> but
|
||
not all characters in <code>timestring</code> were used, the conversion
|
||
succeeds but also prints an error message.</p>
|
||
<p>If either of the system functions <code>strptime</code> or <code>mktime</code> is not
|
||
available, status 2 is returned and an error message is printed.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-s</code> <code>scalar</code><br />
|
||
Assign the date string (or epoch time in seconds if <code>-r</code> is given)
|
||
to <code>scalar</code> instead of printing it.</p>
|
||
</li>
|
||
</ul>
|
||
<p>Note that depending on the system’s declared integral time type,
|
||
<code>strftime</code> may produce incorrect results for epoch times greater than
|
||
2147483647 which corresponds to 2038-01-19 03:14:07 +0000.</p>
|
||
<p>The <code>zsh/datetime</code> module makes available several parameters; all are
|
||
readonly:</p>
|
||
<p><span id="index-EPOCHREALTIME"></span></p>
|
||
<p><code>EPOCHREALTIME</code></p>
|
||
<p>A floating point value representing the number of seconds since the
|
||
epoch. The notional accuracy is to nanoseconds if the <code>clock_gettime</code>
|
||
call is available and to microseconds otherwise, but in practice the
|
||
range of double precision floating point and shell scheduling latencies
|
||
may be significant effects.</p>
|
||
<p><span id="index-EPOCHSECONDS"></span></p>
|
||
<p><code>EPOCHSECONDS</code></p>
|
||
<p>An integer value representing the number of seconds since the epoch.</p>
|
||
<p><span id="index-epochtime"></span></p>
|
||
<p><code>epochtime</code></p>
|
||
<p>An array value containing the number of seconds since the epoch in the
|
||
first element and the remainder of the time since the epoch in
|
||
nanoseconds in the second element. To ensure the two elements are
|
||
consistent the array should be copied or otherwise referenced as a
|
||
single substitution before the values are used. The following idiom may
|
||
be used:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">for secs nsecs in $epochtime; do
|
||
...
|
||
done
|
||
</code></pre>
|
||
</div>
|
||
<hr />
|
||
<p><span id="The-zsh_002fdb_002fgdbm-Module"></span>
|
||
<span id="The-zsh_002fdb_002fgdbm-Module-1"></span></p>
|
||
<h2 id="2211-the-zshdbgdbm-module"><a class="header" href="#2211-the-zshdbgdbm-module">22.11 The zsh/db/gdbm Module</a></h2>
|
||
<p>The <code>zsh/db/gdbm</code> module is used to create "tied" associative arrays
|
||
that interface to database files. If the GDBM interface is not
|
||
available, the builtins defined by this module will report an error.
|
||
This module is also intended as a prototype for creating additional
|
||
database interfaces, so the <code>ztie</code> builtin may move to a more generic
|
||
module in the future.</p>
|
||
<p>The builtins in this module are:</p>
|
||
<p><span id="index-ztie"></span>
|
||
<span id="index-database-tied-array_002c-creating"></span></p>
|
||
<p><code>ztie -d db/gdbm -f</code> <code>filename</code> [ <code>-r</code> ] <code>arrayname</code></p>
|
||
<p>Open the GDBM database identified by <code>filename</code> and, if successful,
|
||
create the associative array <code>arrayname</code> linked to the file. To create a
|
||
local tied array, the parameter must first be declared, so commands
|
||
similar to the following would be executed inside a function scope:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">local -A sampledb
|
||
ztie -d db/gdbm -f sample.gdbm sampledb
|
||
</code></pre>
|
||
</div>
|
||
<p>The <code>-r</code> option opens the database file for reading only, creating a
|
||
parameter with the readonly attribute. Without this option, using
|
||
‘<code>ztie</code>’ on a file for which the user does not have write permission
|
||
is changed in <code>arrayname</code> are immediately written to <code>filename</code>.</p>
|
||
<p>Changes to the file modes <code>filename</code> after it has been opened do not
|
||
alter the state of <code>arrayname</code>, but ‘<code>typeset -r</code> <code>arrayname</code>’ works as
|
||
expected.</p>
|
||
<p><span id="index-zuntie"></span>
|
||
<span id="index-database-tied-array_002c-destroying"></span></p>
|
||
<p><code>zuntie</code> [ <code>-u</code> ] <code>arrayname</code> ...</p>
|
||
<p>Close the GDBM database associated with each <code>arrayname</code> and then unset
|
||
the parameter. The <code>-u</code> option forces an unset of parameters made
|
||
readonly with ‘<code>ztie -r</code>’.</p>
|
||
<p>This happens automatically if the parameter is explicitly unset or its
|
||
local scope (function) ends. Note that a readonly parameter may not be
|
||
explicitly unset, so the only way to unset a global parameter created
|
||
with ‘<code>ztie -r</code>’ is to use ‘<code>zuntie -u</code>’.</p>
|
||
<p><span id="index-zgdbmpath"></span>
|
||
<span id="index-database-file-path_002c-reading"></span></p>
|
||
<p><code>zgdbmpath</code> <code>parametername</code></p>
|
||
<p>Put path to database file assigned to <code>parametername</code> into <code>REPLY</code>
|
||
scalar.</p>
|
||
<p><span id="index-zgdbm_005ftied"></span>
|
||
<span id="index-database-tied-arrays_002c-enumerating"></span></p>
|
||
<p><code>zgdbm_tied</code></p>
|
||
<p>Array holding names of all tied parameters.</p>
|
||
<p>The fields of an associative array tied to GDBM are neither cached nor
|
||
otherwise stored in memory, they are read from or written to the
|
||
database on each reference. Thus, for example, the values in a readonly
|
||
array may be changed by a second writer of the same database file.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fdeltochar-Module"></span>
|
||
<span id="The-zsh_002fdeltochar-Module-1"></span></p>
|
||
<h2 id="2212-the-zshdeltochar-module"><a class="header" href="#2212-the-zshdeltochar-module">22.12 The zsh/deltochar Module</a></h2>
|
||
<p>The <code>zsh/deltochar</code> module makes available two ZLE functions:</p>
|
||
<p><span id="index-delete_002dto_002dchar"></span></p>
|
||
<p><code>delete-to-char</code></p>
|
||
<p>Read a character from the keyboard, and delete from the cursor position
|
||
up to and including the next (or, with repeat count <code>n</code>, the <code>n</code>th)
|
||
instance of that character. Negative repeat counts mean delete
|
||
backwards.</p>
|
||
<p><span id="index-zap_002dto_002dchar"></span></p>
|
||
<p><code>zap-to-char</code></p>
|
||
<p>This behaves like <code>delete-to-char</code>, except that the final occurrence of
|
||
the character itself is not deleted.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fexample-Module"></span>
|
||
<span id="The-zsh_002fexample-Module-1"></span></p>
|
||
<h2 id="2213-the-zshexample-module"><a class="header" href="#2213-the-zshexample-module">22.13 The zsh/example Module</a></h2>
|
||
<p>The <code>zsh/example</code> module makes available one builtin command:</p>
|
||
<p><span id="index-example"></span>
|
||
<span id="index-modules_002c-example"></span>
|
||
<span id="index-modules_002c-writing"></span>
|
||
<span id="index-writing-modules"></span></p>
|
||
<p><code>example</code> [ <code>-flags</code> ] [ <code>args</code> ... ]</p>
|
||
<p>Displays the flags and arguments it is invoked with.</p>
|
||
<p>The purpose of the module is to serve as an example of how to write a
|
||
module.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002ffiles-Module"></span>
|
||
<span id="The-zsh_002ffiles-Module-1"></span></p>
|
||
<h2 id="2214-the-zshfiles-module"><a class="header" href="#2214-the-zshfiles-module">22.14 The zsh/files Module</a></h2>
|
||
<p><span id="index-files_002c-manipulating"></span></p>
|
||
<p>The <code>zsh/files</code> module makes available some common commands for file
|
||
manipulation as builtins; these commands are probably not needed for
|
||
many normal situations but can be useful in emergency recovery
|
||
situations with constrained resources. The commands do not implement all
|
||
features now required by relevant standards committees.</p>
|
||
<p>For all commands, a variant beginning <code>zf_</code> is also available and loaded
|
||
automatically. Using the features capability of zmodload will let you
|
||
load only those names you want. Note that it’s possible to load only the
|
||
builtins with zsh-specific names using the following command:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zmodload -m -F zsh/files b:zf_\*
|
||
</code></pre>
|
||
</div>
|
||
<p>The commands loaded by default are:</p>
|
||
<p><span id="index-chgrp"></span></p>
|
||
<p><code>chgrp</code> [ <code>-hRs</code> ] <code>group</code> <code>filename</code> ...</p>
|
||
<p>Changes group of files specified. This is equivalent to <code>chown</code> with a
|
||
<code>user-spec</code> argument of ‘<code>:``group</code>’.</p>
|
||
<p><span id="index-chmod"></span></p>
|
||
<p><code>chmod</code> [ <code>-Rs</code> ] <code>mode</code> <code>filename</code> ...</p>
|
||
<p>Changes mode of files specified.</p>
|
||
<p>The specified <code>mode</code> must be in octal.</p>
|
||
<p>The <code>-R</code> option causes <code>chmod</code> to recursively descend into directories,
|
||
changing the mode of all files in the directory after changing the mode
|
||
of the directory itself.</p>
|
||
<p>The <code>-s</code> option is a zsh extension to <code>chmod</code> functionality. It enables
|
||
paranoid behaviour, intended to avoid security problems involving a
|
||
<code>chmod</code> being tricked into affecting files other than the ones intended.
|
||
It will refuse to follow symbolic links, so that (for example)
|
||
‘‘<code>chmod 600 /tmp/foo/passwd</code>’’ can’t accidentally chmod
|
||
<code>/etc/passwd</code> if <code>/tmp/foo</code> happens to be a link to <code>/etc</code>. It will also
|
||
check where it is after leaving directories, so that a recursive chmod
|
||
of a deep directory tree can’t end up recursively chmoding <code>/usr</code> as a
|
||
result of directories being moved up the tree.</p>
|
||
<p><span id="index-chown"></span></p>
|
||
<p><code>chown</code> [ <code>-hRs</code> ] <code>user-spec</code> <code>filename</code> ...</p>
|
||
<p>Changes ownership and group of files specified.</p>
|
||
<p>The <code>user-spec</code> can be in four forms:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>user</code><br />
|
||
change owner to <code>user</code>; do not change group</p>
|
||
</li>
|
||
<li>
|
||
<p><code>user``::</code><br />
|
||
change owner to <code>user</code>; do not change group</p>
|
||
</li>
|
||
<li>
|
||
<p><code>user``:</code><br />
|
||
change owner to <code>user</code>; change group to <code>user</code>’s primary group</p>
|
||
</li>
|
||
<li>
|
||
<p><code>user``:``group</code><br />
|
||
change owner to <code>user</code>; change group to <code>group</code></p>
|
||
</li>
|
||
<li>
|
||
<p><code>:``group</code><br />
|
||
do not change owner; change group to <code>group</code></p>
|
||
</li>
|
||
</ul>
|
||
<p>In each case, the ‘<code>:</code>’ may instead be a ‘<code>.</code>’. The rule is that if
|
||
there is a ‘<code>:</code>’ then the separator is ‘<code>:</code>’, otherwise if there is a
|
||
‘<code>.</code>’ then the separator is ‘<code>.</code>’, otherwise there is no separator.</p>
|
||
<p>Each of <code>user</code> and <code>group</code> may be either a username (or group name, as
|
||
appropriate) or a decimal user ID (group ID). Interpretation as a name
|
||
takes precedence, if there is an all-numeric username (or group name).</p>
|
||
<p>If the target is a symbolic link, the <code>-h</code> option causes <code>chown</code> to set
|
||
the ownership of the link instead of its target.</p>
|
||
<p>The <code>-R</code> option causes <code>chown</code> to recursively descend into directories,
|
||
changing the ownership of all files in the directory after changing the
|
||
ownership of the directory itself.</p>
|
||
<p>The <code>-s</code> option is a zsh extension to <code>chown</code> functionality. It enables
|
||
paranoid behaviour, intended to avoid security problems involving a
|
||
<code>chown</code> being tricked into affecting files other than the ones intended.
|
||
It will refuse to follow symbolic links, so that (for example) ‘‘<code>chown luser /tmp/foo/passwd</code>’’ can’t accidentally chown <code>/etc/passwd</code> if
|
||
<code>/tmp/foo</code> happens to be a link to <code>/etc</code>. It will also check where it
|
||
is after leaving directories, so that a recursive chown of a deep
|
||
directory tree can’t end up recursively chowning <code>/usr</code> as a result of
|
||
directories being moved up the tree.</p>
|
||
<p><span id="index-ln"></span></p>
|
||
<p><code>ln</code> [ <code>-dfhins</code> ] <code>filename</code> <code>dest</code></p>
|
||
<p><code>ln</code> [ <code>-dfhins</code> ] <code>filename</code> ... <code>dir</code></p>
|
||
<p>Creates hard (or, with <code>-s</code>, symbolic) links. In the first form, the
|
||
specified <code>dest</code>ination is created, as a link to the specified
|
||
<code>filename</code>. In the second form, each of the <code>filename</code>s is taken in
|
||
turn, and linked to a pathname in the specified <code>dir</code>ectory that has the
|
||
same last pathname component.</p>
|
||
<p>Normally, <code>ln</code> will not attempt to create hard links to directories.
|
||
This check can be overridden using the <code>-d</code> option. Typically only the
|
||
super-user can actually succeed in creating hard links to directories.
|
||
This does not apply to symbolic links in any case.</p>
|
||
<p>By default, existing files cannot be replaced by links. The <code>-i</code> option
|
||
causes the user to be queried about replacing existing files. The <code>-f</code>
|
||
option causes existing files to be silently deleted, without querying.
|
||
<code>-f</code> takes precedence.</p>
|
||
<p>The <code>-h</code> and <code>-n</code> options are identical and both exist for
|
||
compatibility; either one indicates that if the target is a symlink then
|
||
it should not be dereferenced. Typically this is used in combination
|
||
with <code>-sf</code> so that if an existing link points to a directory then it
|
||
will be removed, instead of followed. If this option is used with
|
||
multiple filenames and the target is a symbolic link pointing to a
|
||
directory then the result is an error.</p>
|
||
<p><span id="index-mkdir"></span></p>
|
||
<p><code>mkdir</code> [ <code>-p</code> ] [ <code>-m</code> <code>mode</code> ] <code>dir</code> ...</p>
|
||
<p>Creates directories. With the <code>-p</code> option, non-existing parent
|
||
directories are first created if necessary, and there will be no
|
||
complaint if the directory already exists. The <code>-m</code> option can be used
|
||
to specify (in octal) a set of file permissions for the created
|
||
directories, otherwise mode 777 modified by the current <code>umask</code> (see man
|
||
page umask(2)) is used.</p>
|
||
<p><span id="index-mv"></span></p>
|
||
<p><code>mv</code> [ <code>-fi</code> ] <code>filename</code> <code>dest</code></p>
|
||
<p><code>mv</code> [ <code>-fi</code> ] <code>filename</code> ... <code>dir</code></p>
|
||
<p>Moves files. In the first form, the specified <code>filename</code> is moved to the
|
||
specified <code>dest</code>ination. In the second form, each of the <code>filename</code>s is
|
||
taken in turn, and moved to a pathname in the specified <code>dir</code>ectory that
|
||
has the same last pathname component.</p>
|
||
<p>By default, the user will be queried before replacing any file removed.
|
||
The <code>-i</code> option causes the user to be queried about replacing any
|
||
existing files. The <code>-f</code> option causes any existing files to be silently
|
||
deleted, without querying. <code>-f</code> takes precedence.</p>
|
||
<p>Note that this <code>mv</code> will not move files across devices. Historical
|
||
versions of <code>mv</code>, when actual renaming is impossible, fall back on
|
||
copying and removing files; if this behaviour is desired, use <code>cp</code> and
|
||
<code>rm</code> manually. This may change in a future version.</p>
|
||
<p><span id="index-rm"></span></p>
|
||
<p><code>rm</code> [ <code>-dfiRrs</code> ] <code>filename</code> ...</p>
|
||
<p>Removes files and directories specified.</p>
|
||
<p>Normally, <code>rm</code> will not remove directories (except with the <code>-R</code> or <code>-r</code>
|
||
options). The <code>-d</code> option causes <code>rm</code> to try removing directories with
|
||
<code>unlink</code> (see man page unlink(2)), the same method used for files.
|
||
Typically only the super-user can actually succeed in unlinking
|
||
directories in this way. <code>-d</code> takes precedence over <code>-R</code> and <code>-r</code>.</p>
|
||
<p>By default, the user will be queried before removing any file removed.
|
||
The <code>-i</code> option causes the user to be queried about removing any files.
|
||
The <code>-f</code> option causes files to be silently deleted, without querying,
|
||
and suppresses all error indications. <code>-f</code> takes precedence.</p>
|
||
<p>The <code>-R</code> and <code>-r</code> options cause <code>rm</code> to recursively descend into
|
||
directories, deleting all files in the directory before removing the
|
||
directory with the <code>rmdir</code> system call (see man page rmdir(2)).</p>
|
||
<p>The <code>-s</code> option is a zsh extension to <code>rm</code> functionality. It enables
|
||
paranoid behaviour, intended to avoid common security problems involving
|
||
a root-run <code>rm</code> being tricked into removing files other than the ones
|
||
intended. It will refuse to follow symbolic links, so that (for example)
|
||
‘‘<code>rm /tmp/foo/passwd</code>’’ can’t accidentally remove <code>/etc/passwd</code> if
|
||
<code>/tmp/foo</code> happens to be a link to <code>/etc</code>. It will also check where it
|
||
is after leaving directories, so that a recursive removal of a deep
|
||
directory tree can’t end up recursively removing <code>/usr</code> as a result of
|
||
directories being moved up the tree.</p>
|
||
<p><span id="index-rmdir"></span></p>
|
||
<p><code>rmdir</code> <code>dir</code> ...</p>
|
||
<p>Removes empty directories specified.</p>
|
||
<p><span id="index-sync"></span></p>
|
||
<p><code>sync</code></p>
|
||
<p>Calls the system call of the same name (see man page sync(2)), which
|
||
flushes dirty buffers to disk. It might return before the I/O has
|
||
actually been completed.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002flanginfo-Module"></span>
|
||
<span id="The-zsh_002flanginfo-Module-1"></span></p>
|
||
<h2 id="2215-the-zshlanginfo-module"><a class="header" href="#2215-the-zshlanginfo-module">22.15 The zsh/langinfo Module</a></h2>
|
||
<p>The <code>zsh/langinfo</code> module makes available one parameter:</p>
|
||
<p><span id="index-langinfo"></span></p>
|
||
<p><code>langinfo</code></p>
|
||
<p>An associative array that maps langinfo elements to their values.</p>
|
||
<p>Your implementation may support a number of the following keys:</p>
|
||
<p><code>CODESET</code>, <code>D_T_FMT</code>, <code>D_FMT</code>, <code>T_FMT</code>, <code>RADIXCHAR</code>, <code>THOUSEP</code>,
|
||
<code>YESEXPR</code>, <code>NOEXPR</code>, <code>CRNCYSTR</code>, <code>ABDAY_{1..7}</code>, <code>DAY_{1..7}</code>,
|
||
<code>ABMON_{1..12}</code>, <code>MON_{1..12}</code>, <code>T_FMT_AMPM</code>, <code>AM_STR</code>, <code>PM_STR</code>, <code>ERA</code>,
|
||
<code>ERA_D_FMT</code>, <code>ERA_D_T_FMT</code>, <code>ERA_T_FMT</code>, <code>ALT_DIGITS</code></p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fmapfile-Module"></span>
|
||
<span id="The-zsh_002fmapfile-Module-1"></span></p>
|
||
<h2 id="2216-the-zshmapfile-module"><a class="header" href="#2216-the-zshmapfile-module">22.16 The zsh/mapfile Module</a></h2>
|
||
<p><span id="index-parameter_002c-file-access-via"></span></p>
|
||
<p>The <code>zsh/mapfile</code> module provides one special associative array
|
||
parameter of the same name.</p>
|
||
<p><span id="index-mapfile"></span></p>
|
||
<p><code>mapfile</code></p>
|
||
<p>This associative array takes as keys the names of files; the resulting
|
||
value is the content of the file. The value is treated identically to
|
||
any other text coming from a parameter. The value may also be assigned
|
||
to, in which case the file in question is written (whether or not it
|
||
originally existed); or an element may be unset, which will delete the
|
||
file in question. For example, ‘<code>vared mapfile[myfile]</code>’ works as
|
||
expected, editing the file ‘<code>myfile</code>’.</p>
|
||
<p>When the array is accessed as a whole, the keys are the names of files
|
||
in the current directory, and the values are empty (to save a huge
|
||
overhead in memory). Thus <code>${(k)mapfile}</code> has the same effect as the
|
||
glob operator <code>*(D)</code>, since files beginning with a dot are not special.
|
||
Care must be taken with expressions such as <code>rm ${(k)mapfile}</code>, which
|
||
will delete every file in the current directory without the usual ‘<code>rm *</code>’ test.</p>
|
||
<p>The parameter <code>mapfile</code> may be made read-only; in that case, files
|
||
referenced may not be written or deleted.</p>
|
||
<p>A file may conveniently be read into an array as one line per element
|
||
with the form ‘<code>array``=("${(f@)mapfile[``filename``]}")</code>’. The double
|
||
quotes and the ‘<code>@</code>’ are necessary to prevent empty lines from being
|
||
removed. Note that if the file ends with a newline, the shell will split
|
||
on the final newline, generating an additional empty field; this can be
|
||
suppressed by using
|
||
‘<code>array``=("${(f@)${mapfile[``filename``]%$’\n’}}")</code>’.</p>
|
||
<hr />
|
||
<p><span id="Limitations"></span></p>
|
||
<h3 id="22161-limitations"><a class="header" href="#22161-limitations">22.16.1 Limitations</a></h3>
|
||
<p>Although reading and writing of the file in question is efficiently
|
||
handled, zsh’s internal memory management may be arbitrarily baroque;
|
||
however, <code>mapfile</code> is usually very much more efficient than anything
|
||
involving a loop. Note in particular that the whole contents of the file
|
||
will always reside physically in memory when accessed (possibly multiple
|
||
times, due to standard parameter substitution operations). In
|
||
particular, this means handling of sufficiently long files (greater than
|
||
the machine’s swap space, or than the range of the pointer type) will be
|
||
incorrect.</p>
|
||
<p>No errors are printed or flagged for non-existent, unreadable, or
|
||
execution hierarchy to make this convenient.</p>
|
||
<p>It is unfortunate that the mechanism for loading modules does not yet
|
||
allow the user to specify the name of the shell parameter to be given
|
||
the special behaviour.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fmathfunc-Module"></span>
|
||
<span id="The-zsh_002fmathfunc-Module-1"></span></p>
|
||
<h2 id="2217-the-zshmathfunc-module"><a class="header" href="#2217-the-zshmathfunc-module">22.17 The zsh/mathfunc Module</a></h2>
|
||
<p><span id="index-functions_002c-mathematical"></span>
|
||
<span id="index-mathematical-functions"></span></p>
|
||
<p>The <code>zsh/mathfunc</code> module provides standard mathematical functions for
|
||
use when evaluating mathematical formulae. The syntax agrees with normal
|
||
C and FORTRAN conventions, for example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">(( f = sin(0.3) ))
|
||
</code></pre>
|
||
</div>
|
||
<p>assigns the sine of 0.3 to the parameter f.</p>
|
||
<p>Most functions take floating point arguments and return a floating point
|
||
value. However, any necessary conversions from or to integer type will
|
||
be performed automatically by the shell. Apart from <code>atan</code> with a second
|
||
argument and the <code>abs</code>, <code>int</code> and <code>float</code> functions, all functions
|
||
behave as noted in the manual page for the corresponding C function,
|
||
except that any arguments out of range for the function in question will
|
||
be detected by the shell and an error reported.</p>
|
||
<p>The following functions take a single floating point argument: <code>acos</code>,
|
||
<code>acosh</code>, <code>asin</code>, <code>asinh</code>, <code>atan</code>, <code>atanh</code>, <code>cbrt</code>, <code>ceil</code>, <code>cos</code>,
|
||
<code>cosh</code>, <code>erf</code>, <code>erfc</code>, <code>exp</code>, <code>expm1</code>, <code>fabs</code>, <code>floor</code>, <code>gamma</code>, <code>j0</code>,
|
||
<code>j1</code>, <code>lgamma</code>, <code>log</code>, <code>log10</code>, <code>log1p</code>, <code>log2</code>, <code>logb</code>, <code>sin</code>, <code>sinh</code>,
|
||
<code>sqrt</code>, <code>tan</code>, <code>tanh</code>, <code>y0</code>, <code>y1</code>. The <code>atan</code> function can optionally
|
||
take a second argument, in which case it behaves like the C function
|
||
<code>atan2</code>. The <code>ilogb</code> function takes a single floating point argument,
|
||
but returns an integer.</p>
|
||
<p>The function <code>signgam</code> takes no arguments, and returns an integer, which
|
||
is the C variable of the same name, as described in man page gamma(3).
|
||
Note that it is therefore only useful immediately after a call to
|
||
<code>gamma</code> or <code>lgamma</code>. Note also that ‘<code>signgam()</code>’ and ‘<code>signgam</code>’ are
|
||
distinct expressions.</p>
|
||
<p>The functions <code>min</code>, <code>max</code>, and <code>sum</code> are defined not in this module but
|
||
in the <code>zmathfunc</code> autoloadable function, described in <a href="User-Contributions.html#Mathematical-Functions">Mathematical
|
||
Functions</a>.</p>
|
||
<p>The following functions take two floating point arguments: <code>copysign</code>,
|
||
<code>fmod</code>, <code>hypot</code>, <code>nextafter</code>.</p>
|
||
<p>The following take an integer first argument and a floating point second
|
||
argument: <code>jn</code>, <code>yn</code>.</p>
|
||
<p>The following take a floating point first argument and an integer second
|
||
argument: <code>ldexp</code>, <code>scalb</code>.</p>
|
||
<p>The function <code>abs</code> does not convert the type of its single argument; it
|
||
returns the absolute value of either a floating point number or an
|
||
integer. The functions <code>float</code> and <code>int</code> convert their arguments into a
|
||
floating point or integer value (by truncation) respectively.</p>
|
||
<p>Note that the C <code>pow</code> function is available in ordinary math evaluation
|
||
as the ‘<code>**</code>’ operator and is not provided here.</p>
|
||
<p>The function <code>rand48</code> is available if your system’s mathematical library
|
||
has the function <code>erand48(3)</code>. It returns a pseudo-random floating point
|
||
number between 0 and 1. It takes a single string optional argument.</p>
|
||
<p>If the argument is not present, the random number seed is initialised by
|
||
three calls to the <code>rand(3)</code> function — this produces the same random
|
||
numbers as the next three values of <code>$RANDOM</code>.</p>
|
||
<p>If the argument is present, it gives the name of a scalar parameter
|
||
where the current random number seed will be stored. On the first call,
|
||
the value must contain at least twelve hexadecimal digits (the remainder
|
||
of the string is ignored), or the seed will be initialised in the same
|
||
manner as for a call to <code>rand48</code> with no argument. Subsequent calls to
|
||
<code>rand48</code>(<code>param</code>) will then maintain the seed in the parameter <code>param</code>
|
||
as a string of twelve hexadecimal digits, with no base signifier. The
|
||
random number sequences for different parameters are completely
|
||
independent, and are also independent from that used by calls to
|
||
<code>rand48</code> with no argument.</p>
|
||
<p>For example, consider</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">print $(( rand48(seed) ))
|
||
print $(( rand48() ))
|
||
print $(( rand48(seed) ))
|
||
</code></pre>
|
||
</div>
|
||
<p>Assuming <code>$seed</code> does not exist, it will be initialised by the first
|
||
call. In the second call, the default seed is initialised; note,
|
||
however, that because of the properties of <code>rand()</code> there is a
|
||
correlation between the seeds used for the two initialisations, so for
|
||
more secure uses, you should generate your own 12-byte seed. The third
|
||
call returns to the same sequence of random numbers used in the first
|
||
call, unaffected by the intervening <code>rand48()</code>.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fnearcolor-Module"></span>
|
||
<span id="The-zsh_002fnearcolor-Module-1"></span></p>
|
||
<h2 id="2218-the-zshnearcolor-module"><a class="header" href="#2218-the-zshnearcolor-module">22.18 The zsh/nearcolor Module</a></h2>
|
||
<p>The <code>zsh/nearcolor</code> module replaces colours specified as hex triplets
|
||
with the nearest colour in the 88 or 256 colour palettes that are widely
|
||
used by terminal emulators. By default, 24-bit true colour escape codes
|
||
are generated when colours are specified using hex triplets. These are
|
||
not supported by all terminals. The purpose of this module is to make it
|
||
easier to define colour preferences in a form that can work across a
|
||
range of terminal emulators.</p>
|
||
<p>Aside from the default colour, the ANSI standard for terminal escape
|
||
codes provides for eight colours. The bright attribute brings this to
|
||
sixteen. These basic colours are commonly used in terminal applications
|
||
due to being widely supported. Expanded 88 and 256 colour palettes are
|
||
also common and, while the first sixteen colours vary somewhat between
|
||
terminals and configurations, these add a generally consistent and</p>
|
||
<p>In order to use the <code>zsh/nearcolor</code> module, it only needs to be loaded.
|
||
Thereafter, whenever a colour is specified using a hex triplet, it will
|
||
be compared against each of the available colours and the closest will
|
||
be selected. The first sixteen colours are never matched in</p>
|
||
<p>It isn’t possible to reliably detect support for true colour in the
|
||
terminal emulator. It is therefore recommended to be selective in
|
||
loading the <code>zsh/nearcolor</code> module. For example, the following checks
|
||
the <code>COLORTERM</code> environment variable:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">[[ $COLORTERM = *(24bit|truecolor)* ]] || zmodload zsh/nearcolor
|
||
</code></pre>
|
||
</div>
|
||
<p>Note that some terminals accept the true color escape codes but map them
|
||
internally to a more limited palette in a similar manner to the
|
||
<code>zsh/nearcolor</code> module.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fnewuser-Module"></span>
|
||
<span id="The-zsh_002fnewuser-Module-1"></span></p>
|
||
<h2 id="2219-the-zshnewuser-module"><a class="header" href="#2219-the-zshnewuser-module">22.19 The zsh/newuser Module</a></h2>
|
||
<p>The <code>zsh/newuser</code> module is loaded at boot if it is available, the <code>RCS</code>
|
||
option is set, and the <code>PRIVILEGED</code> option is not set (all three are
|
||
true by default). This takes place immediately after commands in the
|
||
global <code>zshenv</code> file (typically <code>/etc/zshenv</code>), if any, have been
|
||
executed. If the module is not available it is silently ignored by the
|
||
shell; the module may safely be removed from <code>$MODULE_PATH</code> by the
|
||
administrator if it is not required.</p>
|
||
<p>On loading, the module tests if any of the start-up files <code>.zshenv</code>,
|
||
<code>.zprofile</code>, <code>.zshrc</code> or <code>.zlogin</code> exist in the directory given by the
|
||
environment variable <code>ZDOTDIR</code>, or the user’s home directory if that is
|
||
not set. The test is not performed and the module halts processing if
|
||
the shell was in an emulation mode (i.e. had been invoked as some other
|
||
shell than zsh).</p>
|
||
<p>If none of the start-up files were found, the module then looks for the
|
||
file <code>newuser</code> first in a sitewide directory, usually the parent
|
||
directory of the <code>site-functions</code> directory, and if that is not found
|
||
the module searches in a version-specific directory, usually the parent
|
||
of the <code>functions</code> directory containing version-specific functions.
|
||
(These directories can be configured when zsh is built using the
|
||
<code>–enable-site-scriptdir=``dir</code> and <code>–enable-scriptdir=``dir</code> flags to
|
||
<code>configure</code>, respectively; the defaults are <code>prefix``/share/zsh</code> and
|
||
<code>prefix``/share/zsh/$ZSH_VERSION</code> where the default <code>prefix</code> is
|
||
<code>/usr/local</code>.)</p>
|
||
<p>If the file <code>newuser</code> is found, it is then sourced in the same manner as
|
||
a start-up file. The file is expected to contain code to install
|
||
start-up files for the user, however any valid shell code will be
|
||
executed.</p>
|
||
<p>The <code>zsh/newuser</code> module is then unconditionally unloaded.</p>
|
||
<p>Note that it is possible to achieve exactly the same effect as the
|
||
<code>zsh/newuser</code> module by adding code to <code>/etc/zshenv</code>. The module exists
|
||
simply to allow the shell to make arrangements for new users without the
|
||
need for intervention by package maintainers and system administrators.</p>
|
||
<p>The script supplied with the module invokes the shell function
|
||
<code>zsh-newuser-install</code>. This may be invoked directly by the user even if
|
||
the <code>zsh/newuser</code> module is disabled. Note, however, that if the module
|
||
is not installed the function will not be installed either. The function
|
||
is documented in <a href="User-Contributions.html#User-Configuration-Functions">User Configuration
|
||
Functions</a>.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fparameter-Module"></span>
|
||
<span id="The-zsh_002fparameter-Module-1"></span></p>
|
||
<h2 id="2220-the-zshparameter-module"><a class="header" href="#2220-the-zshparameter-module">22.20 The zsh/parameter Module</a></h2>
|
||
<p><span id="index-parameters_002c-special-1"></span></p>
|
||
<p>The <code>zsh/parameter</code> module gives access to some of the internal hash</p>
|
||
<p><span id="index-options-1"></span></p>
|
||
<p><code>options</code></p>
|
||
<p>The keys for this associative array are the names of the options that
|
||
can be set and unset using the <code>setopt</code> and <code>unsetopt</code> builtins. The
|
||
value of each key is either the string <code>on</code> if the option is currently
|
||
set, or the string <code>off</code> if the option is unset. Setting a key to one of
|
||
these strings is like setting or unsetting the option, respectively.
|
||
Unsetting a key in this array is like setting it to the value <code>off</code>.</p>
|
||
<p><span id="index-commands"></span></p>
|
||
<p><code>commands</code></p>
|
||
<p>names of external commands, the values are the pathnames of the files
|
||
that would be executed when the command would be invoked. Setting a with
|
||
the <code>hash</code> builtin. Unsetting a key as in ‘<code>unset "commands[foo]"</code>’
|
||
removes the entry for the given key from the command</p>
|
||
<p><span id="index-functions-2"></span></p>
|
||
<p><code>functions</code></p>
|
||
<p>This associative array maps names of enabled functions to their
|
||
definitions. Setting a key in it is like defining a function with the
|
||
name given by the key and the body given by the value. Unsetting a key
|
||
removes the definition for the function named by the key.</p>
|
||
<p><span id="index-dis_005ffunctions"></span></p>
|
||
<p><code>dis_functions</code></p>
|
||
<p>Like <code>functions</code> but for disabled functions.</p>
|
||
<p><span id="index-functions_005fsource"></span></p>
|
||
<p><code>functions_source</code></p>
|
||
<p>This readonly associative array maps names of enabled functions to the
|
||
name of the file containing the source of the function.</p>
|
||
<p>For an autoloaded function that has already been loaded, or marked for
|
||
autoload with an absolute path, or that has had its path resolved with
|
||
‘<code>functions -r</code>’, this is the file found for autoloading, resolved to
|
||
an absolute path.</p>
|
||
<p>For a function defined within the body of a script or sourced file, this
|
||
is the name of that file. In this case, this is the exact path
|
||
originally used to that file, which may be a relative path.</p>
|
||
<p>For any other function, including any defined at an interactive prompt
|
||
or an autoload function whose path has not yet been resolved, this is
|
||
the empty string. However, the hash element is reported as defined just
|
||
so long as the function is present: the keys to this hash are the same
|
||
as those to <code>$functions</code>.</p>
|
||
<p><span id="index-dis_005ffunctions_005fsource"></span></p>
|
||
<p><code>dis_functions_source</code></p>
|
||
<p>Like <code>functions_source</code> but for disabled functions.</p>
|
||
<p><span id="index-builtins"></span></p>
|
||
<p><code>builtins</code></p>
|
||
<p>This associative array gives information about the builtin commands
|
||
currently enabled. The keys are the names of the builtin commands and
|
||
the values are either ‘<code>undefined</code>’ for builtin commands that will
|
||
automatically be loaded from a module if invoked or ‘<code>defined</code>’ for
|
||
builtin commands that are already loaded.</p>
|
||
<p><span id="index-dis_005fbuiltins"></span></p>
|
||
<p><code>dis_builtins</code></p>
|
||
<p>Like <code>builtins</code> but for disabled builtin commands.</p>
|
||
<p><span id="index-reswords"></span></p>
|
||
<p><code>reswords</code></p>
|
||
<p>This array contains the enabled reserved words.</p>
|
||
<p><span id="index-dis_005freswords"></span></p>
|
||
<p><code>dis_reswords</code></p>
|
||
<p>Like <code>reswords</code> but for disabled reserved words.</p>
|
||
<p><span id="index-patchars"></span></p>
|
||
<p><code>patchars</code></p>
|
||
<p>This array contains the enabled pattern characters.</p>
|
||
<p><span id="index-dis_005fpatchars"></span></p>
|
||
<p><code>dis_patchars</code></p>
|
||
<p>Like <code>patchars</code> but for disabled pattern characters.</p>
|
||
<p><span id="index-aliases"></span></p>
|
||
<p><code>aliases</code></p>
|
||
<p>This maps the names of the regular aliases currently enabled to their
|
||
expansions.</p>
|
||
<p><span id="index-dis_005faliases"></span></p>
|
||
<p><code>dis_aliases</code></p>
|
||
<p>Like <code>aliases</code> but for disabled regular aliases.</p>
|
||
<p><span id="index-galiases"></span></p>
|
||
<p><code>galiases</code></p>
|
||
<p>Like <code>aliases</code>, but for global aliases.</p>
|
||
<p><span id="index-dis_005fgaliases"></span></p>
|
||
<p><code>dis_galiases</code></p>
|
||
<p>Like <code>galiases</code> but for disabled global aliases.</p>
|
||
<p><span id="index-saliases"></span></p>
|
||
<p><code>saliases</code></p>
|
||
<p>Like <code>raliases</code>, but for suffix aliases.</p>
|
||
<p><span id="index-dis_005fsaliases"></span></p>
|
||
<p><code>dis_saliases</code></p>
|
||
<p>Like <code>saliases</code> but for disabled suffix aliases.</p>
|
||
<p><span id="index-parameters-1"></span></p>
|
||
<p><code>parameters</code></p>
|
||
<p>The keys in this associative array are the names of the parameters
|
||
currently defined. The values are strings describing the type of the
|
||
parameter, in the same format used by the <code>t</code> parameter flag, see
|
||
<a href="Expansion.html#Parameter-Expansion">Parameter Expansion</a> . Setting or
|
||
unsetting keys in this array is not possible.</p>
|
||
<p><span id="index-modules-1"></span></p>
|
||
<p><code>modules</code></p>
|
||
<p>An associative array giving information about modules. The keys are the
|
||
names of the modules loaded, registered to be autoloaded, or aliased.
|
||
The value says which state the named module is in and is one of the
|
||
strings ‘<code>loaded</code>’, ‘<code>autoloaded</code>’, or ‘<code>alias:``name</code>’, where <code>name</code> is
|
||
the name the module is aliased to.</p>
|
||
<p>Setting or unsetting keys in this array is not possible.</p>
|
||
<p><span id="index-dirstack"></span></p>
|
||
<p><code>dirstack</code></p>
|
||
<p>A normal array holding the elements of the directory stack. Note that
|
||
the output of the <code>dirs</code> builtin command includes one more directory,
|
||
the current working directory.</p>
|
||
<p><span id="index-history-2"></span></p>
|
||
<p><code>history</code></p>
|
||
<p>This associative array maps history event numbers to the full history
|
||
lines. Although it is presented as an associative array, the array of
|
||
all values (<code>${history[@]}</code>) is guaranteed to be returned in order from
|
||
most recent to oldest history event, that is, by decreasing history
|
||
event number.</p>
|
||
<p><span id="index-historywords"></span></p>
|
||
<p><code>historywords</code></p>
|
||
<p>A special array containing the words stored in the history. These also
|
||
appear in most to least recent order.</p>
|
||
<p><span id="index-jobdirs"></span></p>
|
||
<p><code>jobdirs</code></p>
|
||
<p>This associative array maps job numbers to the directories from which
|
||
the job was started (which may not be the current directory of the job).</p>
|
||
<p>The keys of the associative arrays are usually valid job numbers, and
|
||
these are the values output with, for example, <code>${(k)jobdirs}</code>.
|
||
Non-numeric job references may be used when looking up a value; for
|
||
example, <code>${jobdirs[%+]}</code> refers to the current job.</p>
|
||
<p><span id="index-jobtexts"></span></p>
|
||
<p><code>jobtexts</code></p>
|
||
<p>This associative array maps job numbers to the texts of the command
|
||
lines that were used to start the jobs.</p>
|
||
<p>Handling of the keys of the associative array is as described for
|
||
<code>jobdirs</code> above.</p>
|
||
<p><span id="index-jobstates"></span></p>
|
||
<p><code>jobstates</code></p>
|
||
<p>This associative array gives information about the states of the jobs
|
||
currently known. The keys are the job numbers and the values are strings
|
||
of the form ‘<code>job-state``:``mark``:``pid``=``state</code>...’. The <code>job-state</code>
|
||
gives the state the whole job is currently in, one of ‘<code>running</code>’,
|
||
‘<code>suspended</code>’, or ‘<code>done</code>’. The <code>mark</code> is ‘<code>+</code>’ for the current job,
|
||
‘<code>-</code>’ for the previous job and empty otherwise. This is followed by
|
||
one ‘<code>:``pid``=``state</code>’ for every process in the job. The <code>pid</code>s are,
|
||
of course, the process IDs and the <code>state</code> describes the state of that
|
||
process.</p>
|
||
<p>Handling of the keys of the associative array is as described for
|
||
<code>jobdirs</code> above.</p>
|
||
<p><span id="index-nameddirs"></span></p>
|
||
<p><code>nameddirs</code></p>
|
||
<p>This associative array maps the names of named directories to the
|
||
pathnames they stand for.</p>
|
||
<p><span id="index-userdirs"></span></p>
|
||
<p><code>userdirs</code></p>
|
||
<p>This associative array maps user names to the pathnames of their home
|
||
directories.</p>
|
||
<p><span id="index-usergroups"></span></p>
|
||
<p><code>usergroups</code></p>
|
||
<p>This associative array maps names of system groups of which the current
|
||
user is a member to the corresponding group identifiers. The contents
|
||
are the same as the groups output by the <code>id</code> command.</p>
|
||
<p><span id="index-funcfiletrace"></span></p>
|
||
<p><code>funcfiletrace</code></p>
|
||
<p>This array contains the absolute line numbers and corresponding file
|
||
names for the point where the current function, sourced file, or (if
|
||
<code>EVAL_LINENO</code> is set) <code>eval</code> command was called. The array is of the
|
||
same length as <code>funcsourcetrace</code> and <code>functrace</code>, but differs from
|
||
<code>funcsourcetrace</code> in that the line and file are the point of call, not
|
||
the point of definition, and differs from <code>functrace</code> in that all values
|
||
are absolute line numbers in files, rather than relative to the start of
|
||
a function, if any.</p>
|
||
<p><span id="index-funcsourcetrace"></span></p>
|
||
<p><code>funcsourcetrace</code></p>
|
||
<p>This array contains the file names and line numbers of the points where
|
||
the functions, sourced files, and (if <code>EVAL_LINENO</code> is set) <code>eval</code>
|
||
commands currently being executed were defined. The line number is the
|
||
line where the ‘<code>function</code> <code>name</code>’ or ‘<code>name</code> <code>()</code>’ started. In the case
|
||
of an autoloaded function the line number is reported as zero. The
|
||
format of each element is <code>filename``:``lineno</code>.</p>
|
||
<p>For functions autoloaded from a file in native zsh format, where only
|
||
the body of the function occurs in the file, or for files that have been
|
||
executed by the <code>source</code> or ‘<code>.</code>’ builtins, the trace information is
|
||
shown as <code>filename``:``0</code>, since the entire file is the definition. The
|
||
source file name is resolved to an absolute path when the function is
|
||
loaded or the path to it otherwise resolved.</p>
|
||
<p>Most users will be interested in the information in the <code>funcfiletrace</code>
|
||
array instead.</p>
|
||
<p><span id="index-funcstack"></span></p>
|
||
<p><code>funcstack</code></p>
|
||
<p>This array contains the names of the functions, sourced files, and (if
|
||
<code>EVAL_LINENO</code> is set) <code>eval</code> commands. currently being executed. The
|
||
first element is the name of the function using the parameter.</p>
|
||
<p>The standard shell array <code>zsh_eval_context</code> can be used to determine the
|
||
type of shell construct being executed at each depth: note, however,
|
||
that is in the opposite order, with the most recent item last, and it is
|
||
more detailed, for example including an entry for <code>toplevel</code>, the main
|
||
shell code being executed either interactively or from a script, which
|
||
is not present in <code>$funcstack</code>.</p>
|
||
<p><span id="index-functrace"></span></p>
|
||
<p><code>functrace</code></p>
|
||
<p>This array contains the names and line numbers of the callers
|
||
corresponding to the functions currently being executed. The format of
|
||
each element is <code>name``:``lineno</code>. Callers are also shown for sourced
|
||
files; the caller is the point where the <code>source</code> or ‘<code>.</code>’ command was
|
||
executed.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fpcre-Module"></span>
|
||
<span id="The-zsh_002fpcre-Module-1"></span></p>
|
||
<h2 id="2221-the-zshpcre-module"><a class="header" href="#2221-the-zshpcre-module">22.21 The zsh/pcre Module</a></h2>
|
||
<p><span id="index-regular-expressions_002c-perl_002dcompatible"></span></p>
|
||
<p>The <code>zsh/pcre</code> module makes some commands available as builtins:</p>
|
||
<p><span id="index-pcre_005fcompile"></span></p>
|
||
<p><code>pcre_compile</code> [ <code>-aimxs</code> ] <code>PCRE</code></p>
|
||
<p>Compiles a perl-compatible regular expression.</p>
|
||
<p>Option <code>-a</code> will force the pattern to be anchored. Option <code>-i</code> will
|
||
compile a case-insensitive pattern. Option <code>-m</code> will compile a
|
||
multi-line pattern; that is, <code>^</code> and <code>$</code> will match newlines within the
|
||
pattern. Option <code>-x</code> will compile an extended pattern, wherein
|
||
whitespace and <code>#</code> comments are ignored. Option <code>-s</code> makes the dot
|
||
metacharacter match all characters, including those that indicate
|
||
newline.</p>
|
||
<p><span id="index-pcre_005fstudy"></span></p>
|
||
<p><code>pcre_study</code></p>
|
||
<p>Studies the previously-compiled PCRE which may result in faster
|
||
matching.</p>
|
||
<p><span id="index-pcre_005fmatch"></span></p>
|
||
<p><code>pcre_match</code> [ <code>-v</code> <code>var</code> ] [ <code>-a</code> <code>arr</code> ] [ <code>-n</code> <code>offset</code> ] [
|
||
<code>-b</code> ] <code>string</code></p>
|
||
<p>Returns successfully if <code>string</code> matches the previously-compiled PCRE.</p>
|
||
<p>Upon successful match, if the expression captures substrings within
|
||
parentheses, <code>pcre_match</code> will set the array <code>match</code> to those
|
||
substrings, unless the <code>-a</code> option is given, in which case it will set
|
||
the array <code>arr</code>. Similarly, the variable <code>MATCH</code> will be set to the
|
||
entire matched portion of the string, unless the <code>-v</code> option is given,
|
||
in which case the variable <code>var</code> will be set. No variables are altered
|
||
if there is no successful match. A <code>-n</code> option starts searching for a
|
||
match from the byte <code>offset</code> position in <code>string</code>. If the <code>-b</code> option is
|
||
given, the variable <code>ZPCRE_OP</code> will be set to an offset pair string,
|
||
representing the byte offset positions of the entire matched portion
|
||
within the <code>string</code>. For example, a <code>ZPCRE_OP</code> set to "32 45" indicates
|
||
that the matched portion began on byte offset 32 and ended on byte
|
||
offset 44. Here, byte offset position 45 is the position directly after
|
||
the matched portion. Keep in mind that the byte position isn’t
|
||
necessarily the same as the character position when UTF-8 characters are
|
||
involved. Consequently, the byte offset positions are only to be relied
|
||
on in the context of using them for subsequent searches on <code>string</code>,
|
||
using an offset position as an argument to the <code>-n</code> option. This is
|
||
mostly used to implement the "find all non-overlapping matches"
|
||
functionality.</p>
|
||
<p>A simple example of "find all non-overlapping matches":</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">string="The following zip codes: 78884 90210 99513"
|
||
pcre_compile -m "\d{5}"
|
||
accum=()
|
||
pcre_match -b -- $string
|
||
while [[ $? -eq 0 ]] do
|
||
b=($=ZPCRE_OP)
|
||
accum+=$MATCH
|
||
pcre_match -b -n $b[2] -- $string
|
||
done
|
||
print -l $accum
|
||
</code></pre>
|
||
</div>
|
||
<p>The <code>zsh/pcre</code> module makes available the following test condition:</p>
|
||
<p><span id="index-pcre_002dmatch"></span></p>
|
||
<p><code>expr</code> <code>-pcre-match</code> <code>pcre</code></p>
|
||
<p>Matches a string against a perl-compatible regular expression.</p>
|
||
<p>For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">[[ "$text" -pcre-match ^d+$ ]] &&
|
||
print text variable contains only "d's".
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-REMATCH_005fPCRE-1"></span>
|
||
<span id="index-NO_005fCASE_005fMATCH-1"></span></p>
|
||
<p>If the <code>REMATCH_PCRE</code> option is set, the <code>=~</code> operator is equivalent to
|
||
<code>-pcre-match</code>, and the <code>NO_CASE_MATCH</code> option may be used. Note that
|
||
<code>NO_CASE_MATCH</code> never applies to the <code>pcre_match</code> builtin, instead use
|
||
the <code>-i</code> switch of <code>pcre_compile</code>.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fparam_002fprivate-Module"></span>
|
||
<span id="The-zsh_002fparam_002fprivate-Module-1"></span></p>
|
||
<h2 id="2222-the-zshparamprivate-module"><a class="header" href="#2222-the-zshparamprivate-module">22.22 The zsh/param/private Module</a></h2>
|
||
<p>The <code>zsh/param/private</code> module is used to create parameters whose scope
|
||
is limited to the current function body, and <em>not</em> to other functions
|
||
called by the current function.</p>
|
||
<p>This module provides a single autoloaded builtin:</p>
|
||
<p><span id="index-private"></span>
|
||
<span id="index-private-parameter_002c-creating"></span></p>
|
||
<p><code>private</code> [ {<code>+</code>|<code>-</code>}<code>AHUahlprtux</code> ] [ {<code>+</code>|<code>-</code>}<code>EFLRZi</code> [ <code>n</code> ] ]
|
||
[ <code>name</code>[<code>=``value</code>] ... ]</p>
|
||
<p>The <code>private</code> builtin accepts all the same options and arguments as
|
||
<code>local</code> (<a href="Shell-Builtin-Commands.html#Shell-Builtin-Commands">Shell Builtin
|
||
Commands</a>) except
|
||
for the ‘<code>-``T</code>’ option. Tied parameters may not be made private.</p>
|
||
<p>If used at the top level (outside a function scope), <code>private</code> creates a
|
||
normal parameter in the same manner as <code>declare</code> or <code>typeset</code>. A warning
|
||
about this is printed if <code>WARN_CREATE_GLOBAL</code> is set
|
||
(<a href="Options.html#Options">Options</a>). Used inside a function scope,
|
||
<code>private</code> creates a local parameter similar to one declared with
|
||
<code>local</code>, except having special properties noted below.</p>
|
||
<p>Special parameters which expose or manipulate internal shell state, such
|
||
as <code>ARGC</code>, <code>argv</code>, <code>COLUMNS</code>, <code>LINES</code>, <code>UID</code>, <code>EUID</code>, <code>IFS</code>, <code>PROMPT</code>,
|
||
<code>RANDOM</code>, <code>SECONDS</code>, etc., cannot be made private unless the ‘<code>-``h</code>’
|
||
option is used to hide the special meaning of the parameter. This may
|
||
change in the future.</p>
|
||
<p>As with other <code>typeset</code> equivalents, <code>private</code> is both a builtin and a
|
||
reserved word, so arrays may be assigned with parenthesized word list
|
||
<code>name``=(``value</code>...<code>)</code> syntax. However, the reserved word ‘<code>private</code>’
|
||
is not available until <code>zsh/param/private</code> is loaded, so care must be
|
||
taken with order of execution and parsing for function definitions which
|
||
use <code>private</code>. To compensate for this, the module also adds the option
|
||
‘<code>-P</code>’ to the ‘<code>local</code>’ builtin to declare private parameters.</p>
|
||
<p>For example, this construction fails if <code>zsh/param/private</code> has not yet
|
||
been loaded when ‘<code>bad_declaration</code>’ is defined:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">bad_declaration() {
|
||
zmodload zsh/param/private
|
||
private array=( one two three )
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
<p>This construction works because <code>local</code> is already a keyword, and the
|
||
module is loaded before the statement is executed:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">good_declaration() {
|
||
zmodload zsh/param/private
|
||
local -P array=( one two three )
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
<p>The following is usable in scripts but may have trouble with <code>autoload</code>:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zmodload zsh/param/private
|
||
iffy_declaration() {
|
||
private array=( one two three )
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
<p>The <code>private</code> builtin may always be used with scalar assignments and for
|
||
declarations without assignments.</p>
|
||
<p>Parameters declared with <code>private</code> have the following properties:</p>
|
||
<ul>
|
||
<li>Within the function body where it is declared, the parameter behaves
|
||
as a local, except as noted above for tied or special parameters.</li>
|
||
<li>The type of a parameter declared private cannot be changed in the
|
||
scope where it was declared, even if the parameter is unset. Thus an
|
||
array cannot be assigned to a private scalar, etc.</li>
|
||
<li>Within any other function called by the declaring function, the
|
||
private parameter does <em>NOT</em> hide other parameters of the same name,
|
||
so for example a global parameter of the same name is visible and
|
||
may be assigned or unset. This includes calls to anonymous
|
||
functions, although that may also change in the future.</li>
|
||
<li>An exported private remains in the environment of inner scopes but
|
||
appears unset for the current shell in those scopes. Generally,
|
||
exporting private parameters should be avoided.</li>
|
||
</ul>
|
||
<p>Note that this differs from the static scope defined by compiled
|
||
languages derived from C, in that the a new call to the same function
|
||
creates a new scope, i.e., the parameter is still associated with the
|
||
call stack rather than with the function definition. It differs from ksh
|
||
‘<code>typeset -S</code>’ because the syntax used to define the function has no
|
||
bearing on whether the parameter scope is respected.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fregex-Module"></span>
|
||
<span id="The-zsh_002fregex-Module-1"></span></p>
|
||
<h2 id="2223-the-zshregex-module"><a class="header" href="#2223-the-zshregex-module">22.23 The zsh/regex Module</a></h2>
|
||
<p><span id="index-regular-expressions"></span>
|
||
<span id="index-regex"></span></p>
|
||
<p>The <code>zsh/regex</code> module makes available the following test condition:</p>
|
||
<p><span id="index-regex_002dmatch"></span></p>
|
||
<p><code>expr</code> <code>-regex-match</code> <code>regex</code></p>
|
||
<p>Matches a string against a POSIX extended regular expression. On
|
||
successful match, matched portion of the string will normally be placed
|
||
in the <code>MATCH</code> variable. If there are any capturing parentheses within
|
||
the regex, then the <code>match</code> array variable will contain those. If the
|
||
match is not successful, then the variables will not be altered.</p>
|
||
<p>For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">[[ alphabetical -regex-match ^a([^a]+)a([^a]+)a ]] &&
|
||
print -l $MATCH X $match
|
||
</code></pre>
|
||
</div>
|
||
<p>If the option <code>REMATCH_PCRE</code> is not set, then the <code>=~</code> operator will
|
||
automatically load this module as needed and will invoke the
|
||
<code>-regex-match</code> operator.</p>
|
||
<p>If <code>BASH_REMATCH</code> is set, then the array <code>BASH_REMATCH</code> will be set
|
||
instead of <code>MATCH</code> and <code>match</code>.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fsched-Module"></span>
|
||
<span id="The-zsh_002fsched-Module-1"></span></p>
|
||
<h2 id="2224-the-zshsched-module"><a class="header" href="#2224-the-zshsched-module">22.24 The zsh/sched Module</a></h2>
|
||
<p>The <code>zsh/sched</code> module makes available one builtin command and one
|
||
parameter.</p>
|
||
<p><span id="index-sched"></span> <span id="index-timed-execution"></span>
|
||
<span id="index-execution_002c-timed"></span></p>
|
||
<p><code>sched</code> [<code>-o</code>] [<code>+</code>]<code>hh``:``mm</code>[<code>:``ss</code>] <code>command</code> ...</p>
|
||
<p><code>sched</code> [<code>-o</code>] [<code>+</code>]<code>seconds</code> <code>command</code> ...</p>
|
||
<p><code>sched</code> [ <code>-``item</code> ]</p>
|
||
<p>Make an entry in the scheduled list of commands to execute. The time may
|
||
be specified in either absolute or relative time, and either as hours,
|
||
minutes and (optionally) seconds separated by a colon, or seconds alone.
|
||
An absolute number of seconds indicates the time since the epoch
|
||
(1970/01/01 00:00); this is useful in combination with the features in
|
||
the <code>zsh/datetime</code> module, see <a href="#The-zsh_002fdatetime-Module">The zsh/datetime
|
||
Module</a>.</p>
|
||
<p>With no arguments, prints the list of scheduled commands. If the
|
||
scheduled command has the <code>-o</code> flag set, this is shown at the start of
|
||
the command.</p>
|
||
<p>With the argument ‘<code>-``item</code>’, removes the given item from the list. The
|
||
numbering of the list is continuous and entries are in time order, so
|
||
the numbering can change when entries are added or deleted.</p>
|
||
<p>Commands are executed either immediately before a prompt, or while the
|
||
shell’s line editor is waiting for input. In the latter case it is
|
||
useful to be able to produce output that does not interfere with the
|
||
line being edited. Providing the option <code>-o</code> causes the shell to clear
|
||
the command line before the event and redraw it afterwards. This should
|
||
be used with any scheduled event that produces visible output to the
|
||
terminal; it is not needed, for example, with output that updates a
|
||
terminal emulator’s title bar.</p>
|
||
<p>To effect changes to the editor buffer when an event executes, use the
|
||
‘<code>zle</code>’ command with no arguments to test whether the editor is
|
||
active, and if it is, then use ‘<code> zle ``widget</code>’ to access the editor
|
||
via the named <code>widget</code>.</p>
|
||
<p>The <code>sched</code> builtin is not made available by default when the shell
|
||
starts in a mode emulating another shell. It can be made available with
|
||
the command ‘<code>zmodload -F zsh/sched b:sched</code>’.</p>
|
||
<p><span id="index-zsh_005fscheduled_005fevents"></span></p>
|
||
<p><code>zsh_scheduled_events</code></p>
|
||
<p>A readonly array corresponding to the events scheduled by the <code>sched</code>
|
||
builtin. The indices of the array correspond to the numbers shown when
|
||
<code>sched</code> is run with no arguments (provided that the <code>KSH_ARRAYS</code> option
|
||
is not set). The value of the array consists of the scheduled time in
|
||
seconds since the epoch (see <a href="#The-zsh_002fdatetime-Module">The zsh/datetime
|
||
Module</a> for facilities for using this
|
||
number), followed by a colon, followed by any options (which may be
|
||
empty but will be preceded by a ‘<code>-</code>’ otherwise), followed by a colon,
|
||
followed by the command to be executed.</p>
|
||
<p>The <code>sched</code> builtin should be used for manipulating the events. Note
|
||
that this will have an immediate effect on the contents of the array, so
|
||
that indices may become invalid.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fnet_002fsocket-Module"></span>
|
||
<span id="The-zsh_002fnet_002fsocket-Module-1"></span></p>
|
||
<h2 id="2225-the-zshnetsocket-module"><a class="header" href="#2225-the-zshnetsocket-module">22.25 The zsh/net/socket Module</a></h2>
|
||
<p>The <code>zsh/net/socket</code> module makes available one builtin command:</p>
|
||
<p><span id="index-zsocket"></span> <span id="index-sockets"></span>
|
||
<span id="index-sockets_002c-Unix-domain"></span></p>
|
||
<p><code>zsocket</code> [ <code>-altv</code> ] [ <code>-d</code> <code>fd</code> ] [ <code>args</code> ]</p>
|
||
<p><code>zsocket</code> is implemented as a builtin to allow full use of shell command
|
||
line editing, file I/O, and job control mechanisms.</p>
|
||
<hr />
|
||
<p><span id="Outbound-Connections-1"></span></p>
|
||
<h3 id="22251-outbound-connections"><a class="header" href="#22251-outbound-connections">22.25.1 Outbound Connections</a></h3>
|
||
<p><span id="index-sockets_002c-outbound-Unix-domain"></span></p>
|
||
<ul>
|
||
<li>
|
||
<p><code>zsocket</code> [ <code>-v</code> ] [ <code>-d</code> <code>fd</code> ] <code>filename</code><br />
|
||
Open a new Unix domain connection to <code>filename</code>. The shell parameter
|
||
<code>REPLY</code> will be set to the file descriptor associated with that
|
||
connection. Currently, only stream connections are supported.</p>
|
||
<p>If <code>-d</code> is specified, its argument will be taken as the target file
|
||
descriptor for the connection.</p>
|
||
<p>In order to elicit more verbose output, use <code>-v</code>.</p>
|
||
<p>File descriptors can be closed with normal shell syntax when no
|
||
longer needed, for example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">exec {REPLY}>&-
|
||
</code></pre>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="Inbound-Connections"></span></p>
|
||
<h3 id="22252-inbound-connections"><a class="header" href="#22252-inbound-connections">22.25.2 Inbound Connections</a></h3>
|
||
<p><span id="index-sockets_002c-inbound-Unix-domain"></span></p>
|
||
<ul>
|
||
<li>
|
||
<p><code>zsocket</code> <code>-l</code> [ <code>-v</code> ] [ <code>-d</code> <code>fd</code> ] <code>filename</code><br />
|
||
<code>zsocket -l</code> will open a socket listening on <code>filename</code>. The shell
|
||
parameter <code>REPLY</code> will be set to the file descriptor associated with
|
||
that listener. The file descriptor remains open in subshells</p>
|
||
<p>If <code>-d</code> is specified, its argument will be taken as the target file
|
||
descriptor for the connection.</p>
|
||
<p>In order to elicit more verbose output, use <code>-v</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zsocket</code> <code>-a</code> [ <code>-tv</code> ] [ <code>-d</code> <code>targetfd</code> ] <code>listenfd</code><br />
|
||
<code>zsocket -a</code> will accept an incoming connection to the socket
|
||
associated with <code>listenfd</code>. The shell parameter <code>REPLY</code> will be set
|
||
to the file descriptor associated with the inbound connection. The
|
||
file descriptor remains open in subshells</p>
|
||
<p>If <code>-d</code> is specified, its argument will be taken as the target file
|
||
descriptor for the connection.</p>
|
||
<p>If <code>-t</code> is specified, <code>zsocket</code> will return if no incoming
|
||
connection is pending. Otherwise it will wait for one.</p>
|
||
<p>In order to elicit more verbose output, use <code>-v</code>.</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="The-zsh_002fstat-Module"></span>
|
||
<span id="The-zsh_002fstat-Module-1"></span></p>
|
||
<h2 id="2226-the-zshstat-module"><a class="header" href="#2226-the-zshstat-module">22.26 The zsh/stat Module</a></h2>
|
||
<p>The <code>zsh/stat</code> module makes available one builtin command under two
|
||
possible names:</p>
|
||
<p><span id="index-zstat"></span> <span id="index-stat"></span>
|
||
<span id="index-files_002c-listing"></span>
|
||
<span id="index-files_002c-examining"></span></p>
|
||
<p><code>zstat </code>[ <code>-gnNolLtTrs</code> ] [ <code>-f</code> <code>fd</code> ] [ <code>-H</code> <code>hash</code> ] [ <code>-A</code>
|
||
<code>array</code> ] [ <code>-F</code> <code>fmt</code> ]</p>
|
||
<p><code> </code>[ <code>+``element</code> ] [ <code>file</code> ... ]</p>
|
||
<p><code>stat</code> <code>...</code></p>
|
||
<p>The command acts as a front end to the <code>stat</code> system call (see man page
|
||
stat(2)). The same command is provided with two names; as the name
|
||
<code>stat</code> is often used by an external command it is recommended that only
|
||
the <code>zstat</code> form of the command is used. This can be arranged by loading
|
||
the module with the command ‘<code>zmodload -F zsh/stat b:zstat</code>’.</p>
|
||
<p>If the <code>stat</code> call fails, the appropriate system error message printed
|
||
and status 1 is returned. The fields of <code>struct stat</code> give information
|
||
about the files provided as arguments to the command. In addition to
|
||
those available from the <code>stat</code> call, an extra element ‘<code>link</code>’ is
|
||
provided. These elements are:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>device</code><br />
|
||
The number of the device on which the file resides.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>inode</code><br />
|
||
The unique number of the file on this device (‘<em>inode</em>’ number).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>mode</code><br />
|
||
The mode of the file; that is, the file’s type and access
|
||
permissions. With the <code>-s</code> option, this will be returned as a string
|
||
corresponding to the first column in the display of the <code>ls -l</code>
|
||
command.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>nlink</code><br />
|
||
The number of hard links to the file.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>uid</code><br />
|
||
The user ID of the owner of the file. With the <code>-s</code> option, this is
|
||
displayed as a user name.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>gid</code><br />
|
||
The group ID of the file. With the <code>-s</code> option, this is displayed as
|
||
a group name.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>rdev</code><br />
|
||
The raw device number. This is only useful for special devices.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>size</code><br />
|
||
The size of the file in bytes.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>atime</code><br />
|
||
<code>mtime</code><br />
|
||
<code>ctime</code><br />
|
||
The last access, modification and inode change times of the file,
|
||
respectively, as the number of seconds since midnight GMT on 1st
|
||
January, 1970. With the <code>-s</code> option, these are printed as strings
|
||
for the local time zone; the format can be altered with the <code>-F</code>
|
||
option, and with the <code>-g</code> option the times are in GMT.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>blksize</code><br />
|
||
The number of bytes in one allocation block on the device on which
|
||
the file resides.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>block</code><br />
|
||
The number of disk blocks used by the file.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>link</code><br />
|
||
If the file is a link and the <code>-L</code> option is in effect, this
|
||
contains the name of the file linked to, otherwise it is empty. Note
|
||
that if this element is selected (‘‘<code>zstat +link</code>’’) then the <code>-L</code>
|
||
option is automatically used.</p>
|
||
</li>
|
||
</ul>
|
||
<p>A particular element may be selected by including its name preceded by a
|
||
‘<code>+</code>’ in the option list; only one element is allowed. The element may
|
||
be shortened to any unique set of leading characters. Otherwise, all
|
||
elements will be shown for all files.</p>
|
||
<p>Options:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>-A</code> <code>array</code><br />
|
||
Instead of displaying the results on standard output, assign them to
|
||
an <code>array</code>, one <code>struct stat</code> element per array element for each
|
||
file in order. In this case neither the name of the element nor the
|
||
name of the files appears in <code>array</code> unless the <code>-t</code> or <code>-n</code> options
|
||
were given, respectively. If <code>-t</code> is given, the element name appears
|
||
as a prefix to the appropriate array element; if <code>-n</code> is given, the
|
||
file name appears as a separate array element preceding all the
|
||
others. Other formatting options are respected.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-H</code> <code>hash</code><br />
|
||
Similar to <code>-A</code>, but instead assign the values to <code>hash</code>. The keys
|
||
are the elements listed above. If the <code>-n</code> option is provided then
|
||
the name of the file is included in the hash with key <code>name</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-f</code> <code>fd</code><br />
|
||
Use the file on file descriptor <code>fd</code> instead of named files; no list
|
||
of file names is allowed in this case.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-F</code> <code>fmt</code><br />
|
||
Supplies a <code>strftime</code> (see man page strftime(3)) string for the
|
||
formatting of the time elements. The format string supports all of
|
||
the zsh extensions described in <a href="Prompt-Expansion.html#Prompt-Expansion">Prompt
|
||
Expansion</a>. The <code>-s</code> option
|
||
is implied.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-g</code><br />
|
||
Show the time elements in the GMT time zone. The <code>-s</code> option is
|
||
implied.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-l</code><br />
|
||
List the names of the type elements (to standard output or an array
|
||
as appropriate) and return immediately; arguments, and options other
|
||
than <code>-A</code>, are ignored.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-L</code><br />
|
||
Perform an <code>lstat</code> (see man page lstat(2)) rather than a <code>stat</code>
|
||
system call. In this case, if the file is a link, information about
|
||
the link itself rather than the target file is returned. This option
|
||
is required to make the <code>link</code> element useful. It’s important to
|
||
note that this is the exact opposite from man page ls(1), etc.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-n</code><br />
|
||
Always show the names of files. Usually these are only shown when
|
||
output is to standard output and there is more than one file in the
|
||
list.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-N</code><br />
|
||
Never show the names of files.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-o</code><br />
|
||
If a raw file mode is printed, show it in octal, which is more
|
||
useful for human consumption than the default of decimal. A leading
|
||
zero will be printed in this case. Note that this does not affect
|
||
whether a raw or formatted file mode is shown, which is controlled
|
||
by the <code>-r</code> and <code>-s</code> options, nor whether a mode is shown at all.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-r</code><br />
|
||
Print raw data (the default format) alongside string data (the <code>-s</code>
|
||
format); the string data appears in parentheses after the raw data.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-s</code><br />
|
||
Print <code>mode</code>, <code>uid</code>, <code>gid</code> and the three time elements as strings
|
||
instead of numbers. In each case the format is like that of <code>ls -l</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-t</code><br />
|
||
Always show the type names for the elements of <code>struct stat</code>.
|
||
Usually these are only shown when output is to standard output and
|
||
no individual element has been selected.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-T</code><br />
|
||
Never show the type names of the <code>struct stat</code> elements.</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="The-zsh_002fsystem-Module"></span>
|
||
<span id="The-zsh_002fsystem-Module-1"></span></p>
|
||
<h2 id="2227-the-zshsystem-module"><a class="header" href="#2227-the-zshsystem-module">22.27 The zsh/system Module</a></h2>
|
||
<p>The <code>zsh/system</code> module makes available various builtin commands and
|
||
parameters.</p>
|
||
<hr />
|
||
<p><span id="Builtins"></span></p>
|
||
<h3 id="22271-builtins"><a class="header" href="#22271-builtins">22.27.1 Builtins</a></h3>
|
||
<p><span id="index-syserror"></span></p>
|
||
<p><code>syserror</code> [ <code>-e</code> <code>errvar</code> ] [ <code>-p</code> <code>prefix</code> ] [ <code>errno</code> |
|
||
<code>errname</code> ]</p>
|
||
<p>This command prints out the error message associated with <code>errno</code>, a
|
||
system error number, followed by a newline to standard error.</p>
|
||
<p>Instead of the error number, a name <code>errname</code>, for example <code>ENOENT</code>, may
|
||
be used. The set of names is the same as the contents of the array
|
||
<code>errnos</code>, see below.</p>
|
||
<p>If the string <code>prefix</code> is given, it is printed in front of the error
|
||
message, with no intervening space.</p>
|
||
<p>If <code>errvar</code> is supplied, the entire message, without a newline, is
|
||
assigned to the parameter names <code>errvar</code> and nothing is output.</p>
|
||
<p>A return status of 0 indicates the message was successfully printed
|
||
(although it may not be useful if the error number was out of the
|
||
system’s range), a return status of 1 indicates an error in the
|
||
parameters, and a return status of 2 indicates the error name was not
|
||
recognised (no message is printed for this).</p>
|
||
<p><span id="index-sysopen"></span></p>
|
||
<p><code>sysopen</code> [ <code>-arw</code> ] [ <code>-m</code> <code>permissions</code> ] [ <code>-o</code> <code>options</code> ]</p>
|
||
<p><code> ``-u</code> <code>fd</code> <code>file</code></p>
|
||
<p>This command opens a file. The <code>-r</code>, <code>-w</code> and <code>-a</code> flags indicate
|
||
whether the file should be opened for reading, writing and appending,
|
||
respectively. The <code>-m</code> option allows the initial permissions to use when
|
||
creating a file to be specified in octal form. The file descriptor is
|
||
specified with <code>-u</code>. Either an explicit file descriptor in the range 0
|
||
to 9 can be specified or a variable name can be given to which the file
|
||
descriptor number will be assigned.</p>
|
||
<p>The <code>-o</code> option allows various system specific options to be specified
|
||
as a comma-separated list. The following is a list of possible options.
|
||
Note that, depending on the system, some may not be available.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>cloexec</code><br />
|
||
mark file to be closed when other programs are executed (else the
|
||
file descriptor remains open in subshells and forked external</p>
|
||
</li>
|
||
<li>
|
||
<p><code>create</code><br />
|
||
<code>creat</code><br />
|
||
create file if it does not exist</p>
|
||
</li>
|
||
<li>
|
||
<p><code>excl</code><br />
|
||
create file, error if it already exists</p>
|
||
</li>
|
||
<li>
|
||
<p><code>noatime</code><br />
|
||
suppress updating of the file atime</p>
|
||
</li>
|
||
<li>
|
||
<p><code>nofollow</code><br />
|
||
fail if <code>file</code> is a symbolic link</p>
|
||
</li>
|
||
<li>
|
||
<p><code>sync</code><br />
|
||
request that writes wait until data has been physically written</p>
|
||
</li>
|
||
<li>
|
||
<p><code>truncate</code><br />
|
||
<code>trunc</code><br />
|
||
truncate file to size 0</p>
|
||
</li>
|
||
</ul>
|
||
<p>To close the file, use one of the following:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">exec {fd}<&-
|
||
exec {fd}>&-
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-sysread"></span></p>
|
||
<p><code>sysread </code>[ <code>-c</code> <code>countvar</code> ] [ <code>-i</code> <code>infd</code> ] [ <code>-o</code> <code>outfd</code> ]</p>
|
||
<p><code> </code>[ <code>-s</code> <code>bufsize</code> ] [ <code>-t</code> <code>timeout</code> ] [ <code>param</code> ]</p>
|
||
<p>Perform a single system read from file descriptor <code>infd</code>, or zero if
|
||
that is not given. The result of the read is stored in <code>param</code> or
|
||
<code>REPLY</code> if that is not given. If <code>countvar</code> is given, the number of
|
||
bytes read is assigned to the parameter named by <code>countvar</code>.</p>
|
||
<p>The maximum number of bytes read is <code>bufsize</code> or 8192 if that is not
|
||
given, however the command returns as soon as any number of bytes was
|
||
successfully read.</p>
|
||
<p>If <code>timeout</code> is given, it specifies a timeout in seconds, which may be
|
||
zero to poll the file descriptor. This is handled by the <code>poll</code> system
|
||
call if available, otherwise the <code>select</code> system call if available.</p>
|
||
<p>If <code>outfd</code> is given, an attempt is made to write all the bytes just read
|
||
to the file descriptor <code>outfd</code>. If this fails, because of a system error
|
||
other than <code>EINTR</code> or because of an internal zsh error during an
|
||
interrupt, the bytes read but not written are stored in the parameter
|
||
named by <code>param</code> if supplied (no default is used in this case), and the
|
||
number of bytes read but not written is stored in the parameter named by
|
||
<code>countvar</code> if that is supplied. If it was successful, <code>countvar</code>
|
||
contains the full number of bytes transferred, as usual, and <code>param</code> is
|
||
not set.</p>
|
||
<p>The error <code>EINTR</code> (interrupted system call) is handled internally so
|
||
that shell interrupts are transparent to the caller. Any other error
|
||
causes a return.</p>
|
||
<p>The possible return statuses are</p>
|
||
<ul>
|
||
<li>
|
||
<p>0<br />
|
||
At least one byte of data was successfully read and, if appropriate,
|
||
written.</p>
|
||
</li>
|
||
<li>
|
||
<p>1<br />
|
||
There was an error in the parameters to the command. This is the
|
||
only error for which a message is printed to standard error.</p>
|
||
</li>
|
||
<li>
|
||
<p>2<br />
|
||
There was an error on the read, or on polling the input file
|
||
descriptor for a timeout. The parameter <code>ERRNO</code> gives the error.</p>
|
||
</li>
|
||
<li>
|
||
<p>3<br />
|
||
Data were successfully read, but there was an error writing them to
|
||
<code>outfd</code>. The parameter <code>ERRNO</code> gives the error.</p>
|
||
</li>
|
||
<li>
|
||
<p>4<br />
|
||
The attempt to read timed out. Note this does not set <code>ERRNO</code> as
|
||
this is not a system error.</p>
|
||
</li>
|
||
<li>
|
||
<p>5<br />
|
||
No system error occurred, but zero bytes were read. This usually
|
||
indicates end of file. The parameters are set according to the usual
|
||
rules; no write to <code>outfd</code> is attempted.</p>
|
||
</li>
|
||
</ul>
|
||
<p><code>sysseek</code> [ <code>-u</code> <code>fd</code> ] [ <code>-w</code> <code>start</code>|<code>end</code>|<code>current</code> ] <code>offset</code></p>
|
||
<p>The current file position at which future reads and writes will take
|
||
place is adjusted to the specified byte offset. The <code>offset</code> is
|
||
evaluated as a math expression. The <code>-u</code> option allows the file
|
||
descriptor to be specified. By default the offset is specified relative
|
||
to the start or the file but, with the <code>-w</code> option, it is possible to
|
||
specify that the offset should be relative to the current position or
|
||
the end of the file.</p>
|
||
<p><code>syswrite</code> [ <code>-c</code> <code>countvar</code> ] [ <code>-o</code> <code>outfd</code> ] <code>data</code></p>
|
||
<p>The data (a single string of bytes) are written to the file descriptor
|
||
<code>outfd</code>, or 1 if that is not given, using the <code>write</code> system call.
|
||
Multiple write operations may be used if the first does not write all
|
||
the data.</p>
|
||
<p>If <code>countvar</code> is given, the number of byte written is stored in the
|
||
parameter named by <code>countvar</code>; this may not be the full length of <code>data</code>
|
||
if an error occurred.</p>
|
||
<p>The error <code>EINTR</code> (interrupted system call) is handled internally by
|
||
retrying; otherwise an error causes the command to return. For example,
|
||
if the file descriptor is set to non-blocking output, an error <code>EAGAIN</code>
|
||
(on some systems, <code>EWOULDBLOCK</code>) may result in the command returning
|
||
early.</p>
|
||
<p>The return status may be 0 for success, 1 for an error in the parameters
|
||
to the command, or 2 for an error on the write; no error message is
|
||
printed in the last case, but the parameter <code>ERRNO</code> will reflect the
|
||
error that occurred.</p>
|
||
<p><code>zsystem flock</code> [ <code>-t</code> <code>timeout</code> ] [ <code>-f</code> <code>var</code> ] [<code>-er</code>] <code>file</code></p>
|
||
<p><code>zsystem flock -u</code> <code>fd_expr</code></p>
|
||
<p>The builtin <code>zsystem</code>’s subcommand <code>flock</code> performs advisory file
|
||
locking (via the man page fcntl(2) system call) over the entire contents
|
||
of the given file. This form of locking requires the processes accessing
|
||
the file to cooperate; its most obvious use is between two instances of
|
||
the shell itself.</p>
|
||
<p>In the first form the named <code>file</code>, which must already exist, is locked
|
||
by opening a file descriptor to the file and applying a lock to the file
|
||
descriptor. The lock terminates when the shell process that created the
|
||
lock exits; it is therefore often convenient to create file locks within
|
||
subshells, since the lock is automatically released when the subshell
|
||
exits. Note that use of the <code>print</code> builtin with the <code>-u</code> option will,
|
||
as a side effect, release the lock, as will redirection to the file in
|
||
the shell holding the lock. To work around this use a subshell, e.g.
|
||
‘<code> (print message) >> ``file</code>’. Status 0 is returned if the lock
|
||
succeeds, else status 1.</p>
|
||
<p>In the second form the file descriptor given by the arithmetic
|
||
expression <code>fd_expr</code> is closed, releasing a lock. The file descriptor
|
||
can be queried by using the ‘<code>-f</code> <code>var</code>’ form during the lock; on a
|
||
successful lock, the shell variable <code>var</code> is set to the file descriptor
|
||
used for locking. The lock will be released if the file descriptor is
|
||
closed by any other means, for example using ‘<code>exec {``var``}>&-</code>’;
|
||
however, the form described here performs a safety check that the file
|
||
descriptor is in use for file locking.</p>
|
||
<p>By default the shell waits indefinitely for the lock to succeed. The
|
||
option <code>-t</code> <code>timeout</code> specifies a timeout for the lock in seconds;
|
||
currently this must be an integer. The shell will attempt to lock the
|
||
file once a second during this period. If the attempt times out, status
|
||
2 is returned.</p>
|
||
<p>If the option <code>-e</code> is given, the file descriptor for the lock is
|
||
preserved when the shell uses <code>exec</code> to start a new process; otherwise
|
||
it is closed at that point and the lock released.</p>
|
||
<p>If the option <code>-r</code> is given, the lock is only for reading, otherwise it
|
||
is for reading and writing. The file descriptor is opened accordingly.</p>
|
||
<p><code>zsystem supports</code> <code>subcommand</code></p>
|
||
<p>The builtin <code>zsystem</code>’s subcommand <code>supports</code> tests whether a given
|
||
subcommand is supported. It returns status 0 if so, else status 1. It
|
||
operates silently unless there was a syntax error (i.e. the wrong number
|
||
of arguments), in which case status 255 is returned. Status 1 can
|
||
indicate one of two things: <code>subcommand</code> is known but not supported by
|
||
the current operating system, or <code>subcommand</code> is not known (possibly
|
||
because this is an older version of the shell before it was
|
||
implemented).</p>
|
||
<hr />
|
||
<p><span id="Math-Functions"></span></p>
|
||
<h3 id="22272-math-functions"><a class="header" href="#22272-math-functions">22.27.2 Math Functions</a></h3>
|
||
<ul>
|
||
<li><code>systell(fd)</code><br />
|
||
The systell math function returns the current file position for the
|
||
file descriptor passed as an argument.</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="Parameters-3"></span></p>
|
||
<h3 id="22273-parameters"><a class="header" href="#22273-parameters">22.27.3 Parameters</a></h3>
|
||
<p><span id="index-errnos"></span></p>
|
||
<p><code>errnos</code></p>
|
||
<p>A readonly array of the names of errors defined on the system. These are
|
||
typically macros defined in C by including the system header file
|
||
<code>errno.h</code>. The index of each name (assuming the option <code>KSH_ARRAYS</code> is
|
||
unset) corresponds to the error number. Error numbers <code>num</code> before the
|
||
last known error which have no name are given the name <code>E``num</code> in the
|
||
array.</p>
|
||
<p>Note that aliases for errors are not handled; only the canonical name is
|
||
used.</p>
|
||
<p><span id="index-sysparams"></span></p>
|
||
<p><code>sysparams</code></p>
|
||
<p>A readonly associative array. The keys are:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>pid</code><br />
|
||
<span id="index-pid_002c-sysparams"></span></p>
|
||
<p>Returns the process ID of the current process, even in subshells.
|
||
Compare <code>$$</code>, which returns the process ID of the main shell
|
||
process.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>ppid</code><br />
|
||
<span id="index-ppid_002c-sysparams"></span></p>
|
||
<p>Returns the process ID of the parent of the current process, even in
|
||
subshells. Compare <code>$PPID</code>, which returns the process ID of the
|
||
parent of the main shell process.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>procsubstpid</code><br />
|
||
Returns the process ID of the last process started for process
|
||
substitution, i.e. the <code><(``...``)</code> and <code>>(``...``)</code> expansions.</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="The-zsh_002fnet_002ftcp-Module"></span>
|
||
<span id="The-zsh_002fnet_002ftcp-Module-1"></span></p>
|
||
<h2 id="2228-the-zshnettcp-module"><a class="header" href="#2228-the-zshnettcp-module">22.28 The zsh/net/tcp Module</a></h2>
|
||
<p>The <code>zsh/net/tcp</code> module makes available one builtin command:</p>
|
||
<p><span id="index-ztcp"></span> <span id="index-TCP"></span>
|
||
<span id="index-sockets_002c-TCP"></span></p>
|
||
<p><code>ztcp</code> [ <code>-acflLtv</code> ] [ <code>-d</code> <code>fd</code> ] [ <code>args</code> ]</p>
|
||
<p><code>ztcp</code> is implemented as a builtin to allow full use of shell command
|
||
line editing, file I/O, and job control mechanisms.</p>
|
||
<p>If <code>ztcp</code> is run with no options, it will output</p>
|
||
<p>If it is run with only the option <code>-L</code>, it will output the contents of
|
||
is ignored if given with a command to open or close a session. The
|
||
output consists of a set of lines, one per session, each containing the
|
||
following elements separated by spaces:</p>
|
||
<ul>
|
||
<li>
|
||
<p>File descriptor<br />
|
||
The file descriptor in use for the connection. For normal inbound
|
||
(<code>I</code>) and outbound (<code>O</code>) connections this may be read and written by
|
||
the usual shell mechanisms. However, it should only be close with
|
||
‘<code>ztcp -c</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p>Connection type<br />
|
||
A letter indicating how the session was created:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>Z</code><br />
|
||
A session created with the <code>zftp</code> command.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>L</code><br />
|
||
A connection opened for listening with ‘<code>ztcp -l</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>I</code><br />
|
||
An inbound connection accepted with ‘<code>ztcp -a</code>’.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>O</code><br />
|
||
An outbound connection created with ‘<code>ztcp</code> <code>host</code> <code>...</code>’.</p>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<p>The local host<br />
|
||
This is usually set to an all-zero IP address as the address of the
|
||
localhost is irrelevant.</p>
|
||
</li>
|
||
<li>
|
||
<p>The local port<br />
|
||
This is likely to be zero unless the connection is for listening.</p>
|
||
</li>
|
||
<li>
|
||
<p>The remote host<br />
|
||
This is the fully qualified domain name of the peer, if available,
|
||
else an IP address. It is an all-zero IP address for a session
|
||
opened for listening.</p>
|
||
</li>
|
||
<li>
|
||
<p>The remote port<br />
|
||
This is zero for a connection opened for listening.</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="Outbound-Connections"></span></p>
|
||
<h3 id="22281-outbound-connections"><a class="header" href="#22281-outbound-connections">22.28.1 Outbound Connections</a></h3>
|
||
<p><span id="index-sockets_002c-outbound-TCP"></span></p>
|
||
<ul>
|
||
<li>
|
||
<p><code>ztcp</code> [ <code>-v</code> ] [ <code>-d</code> <code>fd</code> ] <code>host</code> [ <code>port</code> ]<br />
|
||
Open a new TCP connection to <code>host</code>. If the <code>port</code> is omitted, it
|
||
will default to port 23. The connection will <code>REPLY</code> will be set to
|
||
the file descriptor associated with that connection.</p>
|
||
<p>If <code>-d</code> is specified, its argument will be taken as the target file
|
||
descriptor for the connection.</p>
|
||
<p>In order to elicit more verbose output, use <code>-v</code>.</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="Inbound-Connections-1"></span></p>
|
||
<h3 id="22282-inbound-connections"><a class="header" href="#22282-inbound-connections">22.28.2 Inbound Connections</a></h3>
|
||
<p><span id="index-sockets_002c-inbound-TCP"></span></p>
|
||
<ul>
|
||
<li>
|
||
<p><code>ztcp</code> <code>-l</code> [ <code>-v</code> ] [ <code>-d</code> <code>fd</code> ] <code>port</code><br />
|
||
<code>ztcp -l</code> will open a socket listening on TCP <code>port</code>. The socket
|
||
will be added to the will be set to the file descriptor associated
|
||
with that listener.</p>
|
||
<p>If <code>-d</code> is specified, its argument will be taken as the target file
|
||
descriptor for the connection.</p>
|
||
<p>In order to elicit more verbose output, use <code>-v</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>ztcp</code> <code>-a</code> [ <code>-tv</code> ] [ <code>-d</code> <code>targetfd</code> ] <code>listenfd</code><br />
|
||
<code>ztcp -a</code> will accept an incoming connection to the port associated
|
||
with <code>listenfd</code>. The connection will be added to the session be set
|
||
to the file descriptor associated with the inbound connection.</p>
|
||
<p>If <code>-d</code> is specified, its argument will be taken as the target file
|
||
descriptor for the connection.</p>
|
||
<p>If <code>-t</code> is specified, <code>ztcp</code> will return if no incoming connection
|
||
is pending. Otherwise it will wait for one.</p>
|
||
<p>In order to elicit more verbose output, use <code>-v</code>.</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="Closing-Connections"></span></p>
|
||
<h3 id="22283-closing-connections"><a class="header" href="#22283-closing-connections">22.28.3 Closing Connections</a></h3>
|
||
<p><span id="index-sockets_002c-closing-TCP"></span></p>
|
||
<ul>
|
||
<li>
|
||
<p><code>ztcp</code> <code>-cf</code> [ <code>-v</code> ] [ <code>fd</code> ]<br />
|
||
<code>ztcp</code> <code>-c</code> [ <code>-v</code> ] [ <code>fd</code> ]<br />
|
||
<code>ztcp -c</code> will close the socket associated with <code>fd</code>. The socket
|
||
will be removed from the</p>
|
||
<p>Normally, sockets registered by zftp (see <a href="#The-zsh_002fzftp-Module">The zsh/zftp
|
||
Module</a> ) cannot be closed this way. In
|
||
order to force such a socket closed, use <code>-f</code>.</p>
|
||
<p>In order to elicit more verbose output, use <code>-v</code>.</p>
|
||
</li>
|
||
</ul>
|
||
<hr />
|
||
<p><span id="Example-1"></span></p>
|
||
<h3 id="22284-example"><a class="header" href="#22284-example">22.28.4 Example</a></h3>
|
||
<p><span id="index-TCP_002c-example"></span></p>
|
||
<p>Here is how to create a TCP connection between two instances of zsh. We
|
||
need to pick an unassigned port; here we use the randomly chosen 5123.</p>
|
||
<p>On <code>host1</code>,</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zmodload zsh/net/tcp
|
||
ztcp -l 5123
|
||
listenfd=$REPLY
|
||
ztcp -a $listenfd
|
||
fd=$REPLY
|
||
</code></pre>
|
||
</div>
|
||
<p>The second from last command blocks until there is an incoming
|
||
connection.</p>
|
||
<p>Now create a connection from <code>host2</code> (which may, of course, be the same
|
||
machine):</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zmodload zsh/net/tcp
|
||
ztcp host1 5123
|
||
fd=$REPLY
|
||
</code></pre>
|
||
</div>
|
||
<p>Now on each host, <code>$fd</code> contains a file descriptor for talking to the
|
||
other. For example, on <code>host1</code>:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">print This is a message >&$fd
|
||
</code></pre>
|
||
</div>
|
||
<p>and on <code>host2</code>:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">read -r line <&$fd; print -r - $line
|
||
</code></pre>
|
||
</div>
|
||
<p>prints ‘<code>This is a message</code>’.</p>
|
||
<p>To tidy up, on <code>host1</code>:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">ztcp -c $listenfd
|
||
ztcp -c $fd
|
||
</code></pre>
|
||
</div>
|
||
<p>and on <code>host2</code></p>
|
||
<div class="example">
|
||
<pre><code class="language-example">ztcp -c $fd
|
||
</code></pre>
|
||
</div>
|
||
<hr />
|
||
<p><span id="The-zsh_002ftermcap-Module"></span>
|
||
<span id="The-zsh_002ftermcap-Module-1"></span></p>
|
||
<h2 id="2229-the-zshtermcap-module"><a class="header" href="#2229-the-zshtermcap-module">22.29 The zsh/termcap Module</a></h2>
|
||
<p>The <code>zsh/termcap</code> module makes available one builtin command:</p>
|
||
<p><span id="index-echotc"></span>
|
||
<span id="index-termcap-value_002c-printing"></span></p>
|
||
<p><code>echotc</code> <code>cap</code> [ <code>arg</code> ... ]</p>
|
||
<p>Output the termcap value corresponding to the capability <code>cap</code>, with
|
||
optional arguments.</p>
|
||
<p>The <code>zsh/termcap</code> module makes available one parameter:</p>
|
||
<p><span id="index-termcap"></span></p>
|
||
<p><code>termcap</code></p>
|
||
<p>An associative array that maps termcap capability codes to their values.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fterminfo-Module"></span>
|
||
<span id="The-zsh_002fterminfo-Module-1"></span></p>
|
||
<h2 id="2230-the-zshterminfo-module"><a class="header" href="#2230-the-zshterminfo-module">22.30 The zsh/terminfo Module</a></h2>
|
||
<p>The <code>zsh/terminfo</code> module makes available one builtin command:</p>
|
||
<p><span id="index-echoti"></span>
|
||
<span id="index-terminfo-value_002c-printing"></span></p>
|
||
<p><code>echoti</code> <code>cap</code> [ <code>arg</code> ]</p>
|
||
<p>Output the terminfo value corresponding to the capability <code>cap</code>,
|
||
instantiated with <code>arg</code> if applicable.</p>
|
||
<p>The <code>zsh/terminfo</code> module makes available one parameter:</p>
|
||
<p><span id="index-terminfo"></span></p>
|
||
<p><code>terminfo</code></p>
|
||
<p>An associative array that maps terminfo capability names to their
|
||
values.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fzftp-Module"></span>
|
||
<span id="The-zsh_002fzftp-Module-1"></span></p>
|
||
<h2 id="2231-the-zshzftp-module"><a class="header" href="#2231-the-zshzftp-module">22.31 The zsh/zftp Module</a></h2>
|
||
<p>The <code>zsh/zftp</code> module makes available one builtin command:</p>
|
||
<p><span id="index-zftp"></span> <span id="index-FTP"></span>
|
||
<span id="index-files_002c-transferring"></span></p>
|
||
<p><code>zftp</code> <code>subcommand</code> [ <code>args</code> ]</p>
|
||
<p>The <code>zsh/zftp</code> module is a client for FTP (file transfer protocol). It
|
||
is implemented as a builtin to allow full use of shell command line
|
||
editing, file I/O, and job control mechanisms. Often, users will access
|
||
it via shell functions providing a more powerful interface; a set is
|
||
provided with the <code>zsh</code> distribution and is described in <a href="Zftp-Function-System.html#Zftp-Function-System">Zftp Function
|
||
System</a>. However, the
|
||
<code>zftp</code> command is entirely usable in its own right.</p>
|
||
<p>All commands consist of the command name <code>zftp</code> followed by the name of
|
||
a subcommand. These are listed below. The return status of each
|
||
subcommand is supposed to reflect the success or failure of the remote
|
||
operation. See a description of the variable <code>ZFTP_VERBOSE</code> for more
|
||
information on how responses from the server may be printed.</p>
|
||
<hr />
|
||
<p><span id="Subcommands"></span></p>
|
||
<h3 id="22311-subcommands"><a class="header" href="#22311-subcommands">22.31.1 Subcommands</a></h3>
|
||
<p><span id="index-zftp_002c-subcommands"></span></p>
|
||
<p><span id="index-FTP_002c-starting-a-session"></span></p>
|
||
<p><code>open</code> <code>host</code>[<code>:``port</code>] [ <code>user</code> [ <code>password</code> [ <code>account</code> ] ] ]</p>
|
||
<p>Open a new FTP session to <code>host</code>, which may be the name of a TCP/IP
|
||
connected host or an IP number in the standard dot notation. If the
|
||
argument is in the form <code>host``:``port</code>, open a connection to TCP port
|
||
<code>port</code> instead of the standard FTP port 21. This may be the name of a
|
||
TCP service or a number: see the description of <code>ZFTP_PORT</code> below for
|
||
more information.</p>
|
||
<p>If IPv6 addresses in colon format are used, the <code>host</code> should be
|
||
surrounded by quoted square brackets to distinguish it from the <code>port</code>,
|
||
for example <code>’[fe80::203:baff:fe02:8b56]’</code>. For consistency this is
|
||
allowed with all forms of <code>host</code>.</p>
|
||
<p>Remaining arguments are passed to the <code>login</code> subcommand. Note that if
|
||
no arguments beyond <code>host</code> are supplied, <code>open</code> will <em>not</em> automatically
|
||
call <code>login</code>. If no arguments at all are supplied, <code>open</code> will use the
|
||
parameters set by the <code>params</code> subcommand.</p>
|
||
<p>After a successful open, the shell variables <code>ZFTP_HOST</code>, <code>ZFTP_PORT</code>,
|
||
<code>ZFTP_IP</code> and <code>ZFTP_SYSTEM</code> are available; see ‘Variables’ below.</p>
|
||
<p><code>login</code> [ <code>name</code> [ <code>password</code> [ <code>account</code> ] ] ]</p>
|
||
<p><code>user</code> [ <code>name</code> [ <code>password</code> [ <code>account</code> ] ] ]</p>
|
||
<p>Login the user <code>name</code> with parameters <code>password</code> and <code>account</code>. Any of
|
||
the parameters can be omitted, and will be read from standard input if
|
||
needed (<code>name</code> is always needed). If standard input is a terminal, a
|
||
prompt for each one will be printed on standard error and <code>password</code>
|
||
will not be echoed. If any of the parameters are not used, a warning
|
||
message is printed.</p>
|
||
<p>After a successful login, the shell variables <code>ZFTP_USER</code>,
|
||
<code>ZFTP_ACCOUNT</code> and <code>ZFTP_PWD</code> are available; see ‘Variables’ below.</p>
|
||
<p>This command may be re-issued when a user is already logged in, and the
|
||
server will first be reinitialized for a new user.</p>
|
||
<p><code>params</code> [ <code>host</code> [ <code>user</code> [ <code>password</code> [ <code>account</code> ] ] ] ]</p>
|
||
<p><code>params</code> <code>-</code></p>
|
||
<p>Store the given parameters for a later <code>open</code> command with no arguments.
|
||
Only those given on the command line will be remembered. If no arguments
|
||
are given, the parameters currently set are printed, although the
|
||
password will appear as a line of stars; the return status is one if no
|
||
parameters were set, zero otherwise.</p>
|
||
<p>Any of the parameters may be specified as a ‘<code>?</code>’, which may need to be
|
||
quoted to protect it from shell expansion. In this case, the appropriate
|
||
parameter will be read from stdin as with the <code>login</code> subcommand,
|
||
including special handling of <code>password</code>. If the ‘<code>?</code>’ is followed by a
|
||
string, that is used as the prompt for reading the parameter instead of
|
||
the default message (any necessary punctuation and whitespace should be
|
||
included at the end of the prompt). The first letter of the parameter
|
||
(only) may be quoted with a ‘<code>\</code>’; hence an argument <code>"\\$word"</code>
|
||
guarantees that the string from the shell parameter <code>$word</code> will be
|
||
treated literally, whether or not it begins with a ‘<code>?</code>’.</p>
|
||
<p>If instead a single ‘<code>-</code>’ is given, the existing parameters, if any, are
|
||
deleted. In that case, calling <code>open</code> with no arguments will cause an
|
||
error.</p>
|
||
<p>The list of parameters is not deleted after a <code>close</code>, however it will
|
||
be deleted if the <code>zsh/zftp</code> module is unloaded.</p>
|
||
<p>For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zftp params ftp.elsewhere.xx juser '?Password for juser: '
|
||
</code></pre>
|
||
</div>
|
||
<p>will store the host <code>ftp.elsewhere.xx</code> and the user <code>juser</code> and then
|
||
prompt the user for the corresponding password with the given prompt.</p>
|
||
<p><code>test</code></p>
|
||
<p>Test the connection; if the server has reported that it has closed the
|
||
connection (maybe due to a timeout), return status 2; if no connection
|
||
was open anyway, return status 1; else return status 0. The <code>test</code>
|
||
subcommand is silent, apart from messages printed by the <code>$ZFTP_VERBOSE</code>
|
||
mechanism, or error messages if the connection closes. There is no
|
||
network overhead for this test.</p>
|
||
<p>The test is only supported on systems with either the <code>select(2)</code> or
|
||
<code>poll(2)</code> system calls; otherwise the message ‘<code>not supported on this system</code>’ is printed instead.</p>
|
||
<p>The <code>test</code> subcommand will automatically be called at the start of any
|
||
other subcommand for the current session when a connection is open.</p>
|
||
<p><code>cd</code> <code>directory</code></p>
|
||
<p>Change the remote directory to <code>directory</code>. Also alters the shell
|
||
variable <code>ZFTP_PWD</code>.</p>
|
||
<p><code>cdup</code></p>
|
||
<p>Change the remote directory to the one higher in the directory tree.
|
||
Note that <code>cd ..</code> will also work correctly on non-UNIX systems.</p>
|
||
<p><code>dir</code> [ <code>arg</code> ... ]</p>
|
||
<p>Give a (verbose) listing of the remote directory. The <code>arg</code>s are passed
|
||
directly to the server. The command’s behaviour is implementation
|
||
dependent, but a UNIX server will typically interpret <code>arg</code>s as
|
||
arguments to the <code>ls</code> command and with no arguments return the result of
|
||
‘<code>ls -l</code>’. The directory is listed to standard output.</p>
|
||
<p><code>ls</code> [ <code>arg</code> ... ]</p>
|
||
<p>Give a (short) listing of the remote directory. With no <code>arg</code>, produces
|
||
a raw list of the files in the directory, one per line. Otherwise, up to
|
||
vagaries of the server implementation, behaves similar to <code>dir</code>.</p>
|
||
<p><code>type</code> [ <code>type</code> ]</p>
|
||
<p>Change the type for the transfer to <code>type</code>, or print the current type if
|
||
<code>type</code> is absent. The allowed values are ‘<code>A</code>’ (ASCII), ‘<code>I</code>’ (Image,
|
||
i.e. binary), or ‘<code>B</code>’ (a synonym for ‘<code>I</code>’).</p>
|
||
<p>The FTP default for a transfer is ASCII. However, if <code>zftp</code> finds that
|
||
the remote host is a UNIX machine with 8-bit byes, it will automatically
|
||
switch to using binary for file transfers upon <code>open</code>. This can
|
||
subsequently be overridden.</p>
|
||
<p>The transfer type is only passed to the remote host when a data
|
||
connection is established; this command involves no network overhead.</p>
|
||
<p><code>ascii</code></p>
|
||
<p>The same as <code>type A</code>.</p>
|
||
<p><code>binary</code></p>
|
||
<p>The same as <code>type I</code>.</p>
|
||
<p><code>mode</code> [ <code>S</code> | <code>B</code> ]</p>
|
||
<p>Set the mode type to stream (<code>S</code>) or block (<code>B</code>). Stream mode is the
|
||
default; block mode is not widely supported.</p>
|
||
<p><code>remote</code> <code>file</code> ...</p>
|
||
<p><code>local</code> [ <code>file</code> ... ]</p>
|
||
<p>Print the size and last modification time of the remote or local files.
|
||
If there is more than one item on the list, the name of the file is
|
||
printed first. The first number is the file size, the second is the last
|
||
modification time of the file in the format <code>CCYYMMDDhhmmSS</code> consisting
|
||
of year, month, date, hour, minutes and seconds in GMT. Note that this
|
||
format, including the length, is guaranteed, so that time strings can be
|
||
directly compared via the <code>[[</code> builtin’s <code><</code> and <code>></code> operators, even if
|
||
they are too long to be represented as integers.</p>
|
||
<p>Not all servers support the commands for retrieving this information. In
|
||
that case, the <code>remote</code> command will print nothing and return status 2,
|
||
compared with status 1 for a file not found.</p>
|
||
<p>The <code>local</code> command (but not <code>remote</code>) may be used with no arguments, in
|
||
which case the information comes from examining file descriptor zero.
|
||
This is the same file as seen by a <code>put</code> command with no further
|
||
redirection.</p>
|
||
<p><code>get</code> <code>file</code> ...</p>
|
||
<p>Retrieve all <code>file</code>s from the server, concatenating them and sending
|
||
them to standard output.</p>
|
||
<p><code>put</code> <code>file</code> ...</p>
|
||
<p>For each <code>file</code>, read a file from standard input and send that to the
|
||
remote host with the given name.</p>
|
||
<p><code>append</code> <code>file</code> ...</p>
|
||
<p>As <code>put</code>, but if the remote <code>file</code> already exists, data is appended to
|
||
it instead of overwriting it.</p>
|
||
<p><code>getat</code> <code>file</code> <code>point</code></p>
|
||
<p><code>putat</code> <code>file</code> <code>point</code></p>
|
||
<p><code>appendat</code> <code>file</code> <code>point</code></p>
|
||
<p>Versions of <code>get</code>, <code>put</code> and <code>append</code> which will start the transfer at
|
||
the given <code>point</code> in the remote <code>file</code>. This is useful for appending to
|
||
an incomplete local file. However, note that this ability is not
|
||
universally supported by servers (and is not quite the behaviour
|
||
specified by the standard).</p>
|
||
<p><code>delete</code> <code>file</code> ...</p>
|
||
<p>Delete the list of files on the server.</p>
|
||
<p><code>mkdir</code> <code>directory</code></p>
|
||
<p>Create a new directory <code>directory</code> on the server.</p>
|
||
<p><code>rmdir</code> <code>directory</code></p>
|
||
<p>Delete the directory <code>directory</code> on the server.</p>
|
||
<p><code>rename</code> <code>old-name</code> <code>new-name</code></p>
|
||
<p>Rename file <code>old-name</code> to <code>new-name</code> on the server.</p>
|
||
<p><code>site</code> <code>arg</code> ...</p>
|
||
<p>Send a host-specific command to the server. You will probably only need
|
||
this if instructed by the server to use it.</p>
|
||
<p><code>quote</code> <code>arg</code> ...</p>
|
||
<p>Send the raw FTP command sequence to the server. You should be familiar
|
||
with the FTP command set as defined in RFC959 before doing this. Useful
|
||
commands may include <code>STAT</code> and <code>HELP</code>. Note also the mechanism for
|
||
returning messages as described for the variable <code>ZFTP_VERBOSE</code> below,
|
||
in particular that all messages from the control connection are sent to
|
||
standard error.</p>
|
||
<p><code>close</code></p>
|
||
<p><code>quit</code></p>
|
||
<p>Close the current data connection. This unsets the shell parameters
|
||
<code>ZFTP_HOST</code>, <code>ZFTP_PORT</code>, <code>ZFTP_IP</code>, <code>ZFTP_SYSTEM</code>, <code>ZFTP_USER</code>,
|
||
<code>ZFTP_ACCOUNT</code>, <code>ZFTP_PWD</code>, <code>ZFTP_TYPE</code> and <code>ZFTP_MODE</code>.</p>
|
||
<p><code>session</code> [ <code>sessname</code> ]</p>
|
||
<p>Allows multiple FTP sessions to be used at once. The name of the session
|
||
is an arbitrary string of characters; the default session is called
|
||
‘<code>default</code>’. If this command is called without an argument, it will
|
||
list all the current sessions; with an argument, it will either switch
|
||
to the existing session called <code>sessname</code>, or create a new session of
|
||
that name.</p>
|
||
<p>Each session remembers the status of the connection, the set of
|
||
connection-specific shell parameters (the same set as are unset when a
|
||
connection closes, as given in the description of <code>close</code>), and any user
|
||
parameters specified with the <code>params</code> subcommand. Changing to a
|
||
previous session restores those values; changing to a new session
|
||
initialises them in the same way as if <code>zftp</code> had just been loaded. The
|
||
name of the current session is given by the parameter <code>ZFTP_SESSION</code>.</p>
|
||
<p><code>rmsession</code> [ <code>sessname</code> ]</p>
|
||
<p>Delete a session; if a name is not given, the current session is
|
||
deleted. If the current session is deleted, the earliest existing
|
||
session becomes the new current session, otherwise the current session
|
||
is not changed. If the session being deleted is the only one, a new
|
||
session called ‘<code>default</code>’ is created and becomes the current session;
|
||
note that this is a new session even if the session being deleted is
|
||
also called ‘<code>default</code>’. It is recommended that sessions not be deleted
|
||
while background commands which use <code>zftp</code> are still active.</p>
|
||
<hr />
|
||
<p><span id="Parameters-2"></span></p>
|
||
<h3 id="22312-parameters"><a class="header" href="#22312-parameters">22.31.2 Parameters</a></h3>
|
||
<p><span id="index-zftp_002c-parameters"></span></p>
|
||
<p>The following shell parameters are used by <code>zftp</code>. Currently none of
|
||
them are special.</p>
|
||
<p><span id="index-ZFTP_005fTMOUT"></span></p>
|
||
<p><code>ZFTP_TMOUT</code></p>
|
||
<p>Integer. The time in seconds to wait for a network operation to complete
|
||
before returning an error. If this is not set when the module is loaded,
|
||
it will be given the default value 60. A value of zero turns off
|
||
timeouts. If a timeout occurs on the control connection it will be
|
||
closed. Use a larger value if this occurs too frequently.</p>
|
||
<p><span id="index-ZFTP_005fIP"></span></p>
|
||
<p><code>ZFTP_IP</code></p>
|
||
<p>Readonly. The IP address of the current connection in dot notation.</p>
|
||
<p><span id="index-ZFTP_005fHOST"></span></p>
|
||
<p><code>ZFTP_HOST</code></p>
|
||
<p>Readonly. The hostname of the current remote server. If the host was
|
||
opened as an IP number, <code>ZFTP_HOST</code> contains that instead; this saves
|
||
the overhead for a name lookup, as IP numbers are most commonly used
|
||
when a nameserver is unavailable.</p>
|
||
<p><span id="index-ZFTP_005fPORT"></span></p>
|
||
<p><code>ZFTP_PORT</code></p>
|
||
<p>Readonly. The number of the remote TCP port to which the connection is
|
||
open (even if the port was originally specified as a named service).
|
||
Usually this is the standard FTP port, 21.</p>
|
||
<p>In the unlikely event that your system does not have the appropriate
|
||
conversion functions, this appears in network byte order. If your system
|
||
is little-endian, the port then consists of two swapped bytes and the
|
||
standard port will be reported as 5376. In that case, numeric ports
|
||
passed to <code>zftp open</code> will also need to be in this format.</p>
|
||
<p><span id="index-ZFTP_005fSYSTEM"></span></p>
|
||
<p><code>ZFTP_SYSTEM</code></p>
|
||
<p>Readonly. The system type string returned by the server in response to
|
||
an FTP <code>SYST</code> request. The most interesting case is a string beginning
|
||
<code>"UNIX Type: L8"</code>, which ensures maximum compatibility with a local UNIX
|
||
host.</p>
|
||
<p><span id="index-ZFTP_005fTYPE"></span></p>
|
||
<p><code>ZFTP_TYPE</code></p>
|
||
<p>Readonly. The type to be used for data transfers , either ‘<code>A</code>’ or
|
||
‘<code>I</code>’. Use the <code>type</code> subcommand to change this.</p>
|
||
<p><span id="index-ZFTP_005fUSER"></span></p>
|
||
<p><code>ZFTP_USER</code></p>
|
||
<p>Readonly. The username currently logged in, if any.</p>
|
||
<p><span id="index-ZFTP_005fACCOUNT"></span></p>
|
||
<p><code>ZFTP_ACCOUNT</code></p>
|
||
<p>Readonly. The account name of the current user, if any. Most servers do
|
||
not require an account name.</p>
|
||
<p><span id="index-ZFTP_005fPWD"></span></p>
|
||
<p><code>ZFTP_PWD</code></p>
|
||
<p>Readonly. The current directory on the server.</p>
|
||
<p><span id="index-ZFTP_005fCODE"></span></p>
|
||
<p><code>ZFTP_CODE</code></p>
|
||
<p>Readonly. The three digit code of the last FTP reply from the server as
|
||
a string. This can still be read after the connection is closed, and is
|
||
not changed when the current session changes.</p>
|
||
<p><span id="index-ZFTP_005fREPLY"></span></p>
|
||
<p><code>ZFTP_REPLY</code></p>
|
||
<p>Readonly. The last line of the last reply sent by the server. This can
|
||
still be read after the connection is closed, and is not changed when
|
||
the current session changes.</p>
|
||
<p><span id="index-ZFTP_005fSESSION"></span></p>
|
||
<p><code>ZFTP_SESSION</code></p>
|
||
<p>Readonly. The name of the current FTP session; see the description of
|
||
the <code>session</code> subcommand.</p>
|
||
<p><span id="index-ZFTP_005fPREFS"></span></p>
|
||
<p><code>ZFTP_PREFS</code></p>
|
||
<p>A string of preferences for altering aspects of <code>zftp</code>’s behaviour. Each
|
||
preference is a single character. The following are defined:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>P</code><br />
|
||
Passive: attempt to make the remote server initiate data transfers.
|
||
This is slightly more efficient than sendport mode. If the letter
|
||
<code>S</code> occurs later in the string, <code>zftp</code> will use sendport mode if
|
||
passive mode is not available.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>S</code><br />
|
||
Sendport: initiate transfers by the FTP <code>PORT</code> command. If this
|
||
occurs before any <code>P</code> in the string, passive mode will never be
|
||
attempted.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>D</code><br />
|
||
Dumb: use only the bare minimum of FTP commands. This prevents the
|
||
variables <code>ZFTP_SYSTEM</code> and <code>ZFTP_PWD</code> from being set, and will mean
|
||
all connections default to ASCII type. It may prevent <code>ZFTP_SIZE</code>
|
||
from being set during a transfer if the server does not send it
|
||
anyway (many servers do).</p>
|
||
</li>
|
||
</ul>
|
||
<p>If <code>ZFTP_PREFS</code> is not set when <code>zftp</code> is loaded, it will be set to a
|
||
default of ‘<code>PS</code>’, i.e. use passive mode if available, otherwise fall
|
||
back to sendport mode.</p>
|
||
<p><span id="index-ZFTP_005fVERBOSE"></span></p>
|
||
<p><code>ZFTP_VERBOSE</code></p>
|
||
<p>A string of digits between 0 and 5 inclusive, specifying which responses
|
||
from the server should be printed. All responses go to standard error.
|
||
If any of the numbers 1 to 5 appear in the string, raw responses from
|
||
the server with reply codes beginning with that digit will be printed to
|
||
standard error. The first digit of the three digit reply code is defined
|
||
by RFC959 to correspond to:</p>
|
||
<ul>
|
||
<li>
|
||
<p>1.<br />
|
||
A positive preliminary reply.</p>
|
||
</li>
|
||
<li>
|
||
<p>2.<br />
|
||
A positive completion reply.</p>
|
||
</li>
|
||
<li>
|
||
<p>3.<br />
|
||
A positive intermediate reply.</p>
|
||
</li>
|
||
<li>
|
||
<p>4.<br />
|
||
A transient negative completion reply.</p>
|
||
</li>
|
||
<li>
|
||
<p>5.<br />
|
||
A permanent negative completion reply.</p>
|
||
</li>
|
||
</ul>
|
||
<p>It should be noted that, for unknown reasons, the reply ‘Service not
|
||
available’, which forces termination of a connection, is classified as
|
||
421, i.e. ‘transient negative’, an interesting interpretation of the
|
||
word ‘transient’.</p>
|
||
<p>The code 0 is special: it indicates that all but the last line of
|
||
multiline replies read from the server will be printed to standard error
|
||
in a processed format. By convention, servers use this mechanism for
|
||
sending information for the user to read. The appropriate reply code, if
|
||
it matches the same response, takes priority.</p>
|
||
<p>If <code>ZFTP_VERBOSE</code> is not set when <code>zftp</code> is loaded, it will be set to
|
||
the default value <code>450</code>, i.e., messages destined for the user and all
|
||
errors will be printed. A null string is valid and specifies that no
|
||
messages should be printed.</p>
|
||
<hr />
|
||
<p><span id="Functions-1"></span></p>
|
||
<h3 id="22313-functions"><a class="header" href="#22313-functions">22.31.3 Functions</a></h3>
|
||
<p><span id="index-zftp_002c-functions"></span></p>
|
||
<p><span id="index-zftp_005fchpwd_002c-specification"></span></p>
|
||
<p><code>zftp_chpwd</code></p>
|
||
<p>If this function is set by the user, it is called every time the
|
||
directory changes on the server, including when a user is logged in, or
|
||
when a connection is closed. In the last case, <code>$ZFTP_PWD</code> will be
|
||
unset; otherwise it will reflect the new directory.</p>
|
||
<p><span id="index-zftp_005fprogress_002c-specification"></span></p>
|
||
<p><code>zftp_progress</code></p>
|
||
<p>If this function is set by the user, it will be called during a <code>get</code>,
|
||
<code>put</code> or <code>append</code> operation each time sufficient data has been received
|
||
from the host. During a <code>get</code>, the data is sent to standard output, so
|
||
it is vital that this function should write to standard error or
|
||
directly to the terminal, <em>not</em> to standard output.</p>
|
||
<p>When it is called with a transfer in progress, the following additional
|
||
shell parameters are set:</p>
|
||
<p><span id="index-ZFTP_005fFILE"></span></p>
|
||
<p><code>ZFTP_FILE</code></p>
|
||
<p>The name of the remote file being transferred from or to.</p>
|
||
<p><span id="index-ZFTP_005fTRANSFER"></span></p>
|
||
<p><code>ZFTP_TRANSFER</code></p>
|
||
<p>A <code>G</code> for a <code>get</code> operation and a <code>P</code> for a <code>put</code> operation.</p>
|
||
<p><span id="index-ZFTP_005fSIZE"></span></p>
|
||
<p><code>ZFTP_SIZE</code></p>
|
||
<p>The total size of the complete file being transferred: the same as the
|
||
first value provided by the <code>remote</code> and <code>local</code> subcommands for a
|
||
particular file. If the server cannot supply this value for a remote
|
||
file being retrieved, it will not be set. If input is from a pipe the
|
||
value may be incorrect and correspond simply to a full pipe buffer.</p>
|
||
<p><span id="index-ZFTP_005fCOUNT"></span></p>
|
||
<p><code>ZFTP_COUNT</code></p>
|
||
<p>The amount of data so far transferred; a number between zero and
|
||
<code>$ZFTP_SIZE</code>, if that is set. This number is always available.</p>
|
||
<p>The function is initially called with <code>ZFTP_TRANSFER</code> set appropriately
|
||
and <code>ZFTP_COUNT</code> set to zero. After the transfer is finished, the
|
||
function will be called one more time with <code>ZFTP_TRANSFER</code> set to <code>GF</code>
|
||
or <code>PF</code>, in case it wishes to tidy up. It is otherwise never called
|
||
twice with the same value of <code>ZFTP_COUNT</code>.</p>
|
||
<p>Sometimes the progress meter may cause disruption. It is up to the user
|
||
to decide whether the function should be defined and to use <code>unfunction</code>
|
||
when necessary.</p>
|
||
<hr />
|
||
<p><span id="Problems"></span></p>
|
||
<h3 id="22314-problems"><a class="header" href="#22314-problems">22.31.4 Problems</a></h3>
|
||
<p><span id="index-zftp_002c-problems"></span></p>
|
||
<p>A connection may not be opened in the left hand side of a pipe as this
|
||
occurs in a subshell and the file information is not updated in the main
|
||
shell. In the case of type or mode changes or closing the connection in
|
||
a subshell, the information is returned but variables are not updated
|
||
until the next call to <code>zftp</code>. Other status changes in subshells will
|
||
not be reflected by changes to the variables (but should be otherwise
|
||
harmless).</p>
|
||
<p>Deleting sessions while a <code>zftp</code> command is active in the background can
|
||
have unexpected effects, even if it does not use the session being
|
||
deleted. This is because all shell subprocesses share information on the
|
||
state of all connections, and deleting a session changes the ordering of
|
||
that information.</p>
|
||
<p>On some operating systems, the control connection is not valid after a
|
||
fork(), so that operations in subshells, on the left hand side of a
|
||
pipeline, or in the background are not possible, as they should be. This
|
||
is presumably a bug in the operating system.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fzle-Module"></span>
|
||
<span id="The-zsh_002fzle-Module-1"></span></p>
|
||
<h2 id="2232-the-zshzle-module"><a class="header" href="#2232-the-zshzle-module">22.32 The zsh/zle Module</a></h2>
|
||
<p>The <code>zsh/zle</code> module contains the Zsh Line Editor. See <a href="Zsh-Line-Editor.html#Zsh-Line-Editor">Zsh Line
|
||
Editor</a>.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fzleparameter-Module"></span>
|
||
<span id="The-zsh_002fzleparameter-Module-1"></span></p>
|
||
<h2 id="2233-the-zshzleparameter-module"><a class="header" href="#2233-the-zshzleparameter-module">22.33 The zsh/zleparameter Module</a></h2>
|
||
<p><span id="index-parameters_002c-special-2"></span></p>
|
||
<p>The <code>zsh/zleparameter</code> module defines two special parameters that can be
|
||
used to access internal information of the Zsh Line Editor (see <a href="Zsh-Line-Editor.html#Zsh-Line-Editor">Zsh
|
||
Line Editor</a>).</p>
|
||
<p><span id="index-keymaps-2"></span></p>
|
||
<p><code>keymaps</code></p>
|
||
<p>This array contains the names of the keymaps currently defined.</p>
|
||
<p><span id="index-widgets-1"></span></p>
|
||
<p><code>widgets</code></p>
|
||
<p>This associative array contains one entry per widget. The name of the
|
||
widget is the key and the value gives information about the widget. It
|
||
is either the string ‘<code>builtin</code>’ for builtin widgets, a string of the
|
||
form ‘<code>user:``name</code>’ for user-defined widgets, where <code>name</code> is the name
|
||
of the shell function implementing the widget, a string of the form
|
||
‘<code>completion:``type``:``name</code>’ for completion widgets, or a null value
|
||
if the widget is not yet fully defined. In the penultimate case, <code>type</code>
|
||
is the name of the builtin widget the completion widget imitates in its
|
||
behavior and <code>name</code> is the name of the shell function implementing the
|
||
completion widget.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fzprof-Module"></span>
|
||
<span id="The-zsh_002fzprof-Module-1"></span></p>
|
||
<h2 id="2234-the-zshzprof-module"><a class="header" href="#2234-the-zshzprof-module">22.34 The zsh/zprof Module</a></h2>
|
||
<p><span id="index-functions_002c-profiling"></span></p>
|
||
<p>When loaded, the <code>zsh/zprof</code> causes shell functions to be profiled. The
|
||
profiling results can be obtained with the <code>zprof</code> builtin command made
|
||
available by this module. There is no way to turn profiling off other
|
||
than unloading the module.</p>
|
||
<p><span id="index-zprof"></span></p>
|
||
<p><code>zprof</code> [ <code>-c</code> ]</p>
|
||
<p>Without the <code>-c</code> option, <code>zprof</code> lists profiling results to standard
|
||
output. The format is comparable to that of commands like <code>gprof</code>.</p>
|
||
<p>At the top there is a summary listing all functions that were called at
|
||
least once. This summary is sorted in decreasing order of the amount of
|
||
time spent in each. The lines contain the number of the function in
|
||
order, which is used in other parts of the list in suffixes of the form
|
||
‘<code>[``num``]</code>’, then the number of calls made to the function. The next
|
||
three columns list the time in milliseconds spent in the function and
|
||
its descendants, the average time in milliseconds spent in the function
|
||
and its descendants per call and the percentage of time spent in all
|
||
shell functions used in this function and its descendants. The following
|
||
three columns give the same information, but counting only the time
|
||
spent in the function itself. The final column shows the name of the
|
||
function.</p>
|
||
<p>After the summary, detailed information about every function that was
|
||
invoked is listed, sorted in decreasing order of the amount of time
|
||
spent in each function and its descendants. Each of these entries
|
||
consists of descriptions for the functions that called the function
|
||
described, the function itself, and the functions that were called from
|
||
it. The description for the function itself has the same format as in
|
||
the summary (and shows the same information). The other lines don’t show
|
||
the number of the function at the beginning and have their function
|
||
named indented to make it easier to distinguish the line showing the
|
||
function described in the section from the surrounding lines.</p>
|
||
<p>The information shown in this case is almost the same as in the summary,
|
||
but only refers to the call hierarchy being displayed. For example, for
|
||
a calling function the column showing the total running time lists the
|
||
time spent in the described function and its descendants only for the
|
||
times when it was called from that particular calling function.
|
||
Likewise, for a called function, this columns lists the total time spent
|
||
in the called function and its descendants only for the times when it
|
||
was called from the function described.</p>
|
||
<p>Also in this case, the column showing the number of calls to a function
|
||
also shows a slash and then the total number of invocations made to the
|
||
called function.</p>
|
||
<p>As long as the <code>zsh/zprof</code> module is loaded, profiling will be done and
|
||
multiple invocations of the <code>zprof</code> builtin command will show the times
|
||
and numbers of calls since the module was loaded. With the <code>-c</code> option,
|
||
the <code>zprof</code> builtin command will reset its internal counters and will
|
||
not show the listing.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fzpty-Module"></span>
|
||
<span id="The-zsh_002fzpty-Module-1"></span></p>
|
||
<h2 id="2235-the-zshzpty-module"><a class="header" href="#2235-the-zshzpty-module">22.35 The zsh/zpty Module</a></h2>
|
||
<p>The <code>zsh/zpty</code> module offers one builtin:</p>
|
||
<p><span id="index-zpty"></span></p>
|
||
<p><code>zpty</code> [ <code>-e</code> ] [ <code>-b</code> ] <code>name</code> [ <code>arg</code> ... ]</p>
|
||
<p>The arguments following <code>name</code> are concatenated with spaces between,
|
||
then executed as a command, as if passed to the <code>eval</code> builtin. The
|
||
command runs under a newly assigned pseudo-terminal; this is useful for
|
||
running commands non-interactively which expect an interactive
|
||
environment. The <code>name</code> is not part of the command, but is used to refer
|
||
to this command in later calls to <code>zpty</code>.</p>
|
||
<p>With the <code>-e</code> option, the pseudo-terminal is set up so that input
|
||
characters are echoed.</p>
|
||
<p>With the <code>-b</code> option, input to and output from the pseudo-terminal are
|
||
made non-blocking.</p>
|
||
<p>The shell parameter <code>REPLY</code> is set to the file descriptor assigned to
|
||
the master side of the pseudo-terminal. This allows the terminal to be
|
||
monitored with ZLE descriptor handlers (see <a href="Zsh-Line-Editor.html#Zle-Builtins">Zle
|
||
Builtins</a>) or manipulated with
|
||
<code>sysread</code> and <code>syswrite</code> (see <a href="#The-zsh_002fsystem-Module">The zsh/system
|
||
Module</a>). <em>Warning</em>: Use of <code>sysread</code> and
|
||
<code>syswrite</code> is <em>not</em> recommended; use <code>zpty -r</code> and <code>zpty -w</code> unless you
|
||
know exactly what you are doing.</p>
|
||
<p><code>zpty</code> <code>-d</code> [ <code>name</code> ... ]</p>
|
||
<p>The second form, with the <code>-d</code> option, is used to delete commands
|
||
previously started, by supplying a list of their <code>name</code>s. If no <code>name</code>
|
||
is given, all commands are deleted. Deleting a command causes the HUP
|
||
signal to be sent to the corresponding process.</p>
|
||
<p><code>zpty</code> <code>-w</code> [ <code>-n</code> ] <code>name</code> [ <code>string</code> ... ]</p>
|
||
<p>The <code>-w</code> option can be used to send the to command <code>name</code> the given
|
||
<code>string</code>s as input (separated by spaces). If the <code>-n</code> option is <em>not</em>
|
||
given, a newline is added at the end.</p>
|
||
<p>If no <code>string</code> is provided, the standard input is copied to the
|
||
pseudo-terminal; this may stop before copying the full input if the
|
||
pseudo-terminal is non-blocking. The exact input is always copied: the
|
||
<code>-n</code> option is not applied.</p>
|
||
<p>Note that the command under the pseudo-terminal sees this input as if it
|
||
were typed, so beware when sending special tty driver characters such as
|
||
word-erase, line-kill, and end-of-file.</p>
|
||
<p><code>zpty</code> <code>-r</code> [ <code>-mt</code> ] <code>name</code> [ <code>param</code> [ <code>pattern</code> ] ]</p>
|
||
<p>The <code>-r</code> option can be used to read the output of the command <code>name</code>.
|
||
With only a <code>name</code> argument, the output read is copied to the standard
|
||
output. Unless the pseudo-terminal is non-blocking, copying continues
|
||
until the command under the pseudo-terminal exits; when non-blocking,
|
||
only as much output as is immediately available is copied. The return
|
||
status is zero if any output is copied.</p>
|
||
<p>When also given a <code>param</code> argument, at most one line is read and stored
|
||
in the parameter named <code>param</code>. Less than a full line may be read if the
|
||
pseudo-terminal is non-blocking. The return status is zero if at least
|
||
one character is stored in <code>param</code>.</p>
|
||
<p>If a <code>pattern</code> is given as well, output is read until the whole string
|
||
read matches the <code>pattern</code>, even in the non-blocking case. The return
|
||
status is zero if the string read matches the pattern, or if the command
|
||
has exited but at least one character could still be read. If the option
|
||
<code>-m</code> is present, the return status is zero only if the pattern matches.
|
||
As of this writing, a maximum of one megabyte of output can be consumed
|
||
this way; if a full megabyte is read without matching the pattern, the
|
||
return status is non-zero.</p>
|
||
<p>In all cases, the return status is non-zero if nothing could be read,
|
||
and is <code>2</code> if this is because the command has finished.</p>
|
||
<p>If the <code>-r</code> option is combined with the <code>-t</code> option, <code>zpty</code> tests
|
||
whether output is available before trying to read. If no output is
|
||
available, <code>zpty</code> immediately returns the status <code>1</code>. When used with a
|
||
<code>pattern</code>, the behaviour on a failed poll is similar to when the command
|
||
has exited: the return value is zero if at least one character could
|
||
still be read even if the pattern failed to match.</p>
|
||
<p><code>zpty</code> <code>-t</code> <code>name</code></p>
|
||
<p>The <code>-t</code> option without the <code>-r</code> option can be used to test whether the
|
||
command <code>name</code> is still running. It returns a zero status if the command
|
||
is running and a non-zero value otherwise.</p>
|
||
<p><code>zpty</code> [ <code>-L</code> ]</p>
|
||
<p>The last form, without any arguments, is used to list the commands
|
||
currently defined. If the <code>-L</code> option is given, this is done in the form
|
||
of calls to the <code>zpty</code> builtin.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fzselect-Module"></span>
|
||
<span id="The-zsh_002fzselect-Module-1"></span></p>
|
||
<h2 id="2236-the-zshzselect-module"><a class="header" href="#2236-the-zshzselect-module">22.36 The zsh/zselect Module</a></h2>
|
||
<p>The <code>zsh/zselect</code> module makes available one builtin command:</p>
|
||
<p><span id="index-zselect"></span>
|
||
<span id="index-select_002c-system-call"></span>
|
||
<span id="index-file-descriptors_002c-waiting-for"></span></p>
|
||
<p><code>zselect</code> [ <code>-rwe</code> ] [ <code>-t</code> <code>timeout</code> ] [ <code>-a</code> <code>array</code> ] [ <code>-A</code>
|
||
<code>assoc</code> ] [ <code>fd</code> ... ]</p>
|
||
<p>The <code>zselect</code> builtin is a front-end to the ‘select’ system call, which
|
||
blocks until a file descriptor is ready for reading or writing, or has
|
||
an error condition, with an optional timeout. If this is not available
|
||
on your system, the command prints an error message and returns status 2
|
||
(normal errors return status 1). For more information, see your systems
|
||
documentation for man page select(3). Note there is no connection with
|
||
the shell builtin of the same name.</p>
|
||
<p>Arguments and options may be intermingled in any order. Non-option
|
||
arguments are file descriptors, which must be decimal integers. By
|
||
default, file descriptors are to be tested for reading, i.e. <code>zselect</code>
|
||
will return when data is available to be read from the file descriptor,
|
||
or more precisely, when a read operation from the file descriptor will
|
||
not block. After a <code>-r</code>, <code>-w</code> and <code>-e</code>, the given file descriptors are
|
||
to be tested for reading, writing, or error conditions. These options
|
||
and an arbitrary list of file descriptors may be given in any order.</p>
|
||
<p>(The presence of an ‘error condition’ is not well defined in the
|
||
documentation for many implementations of the select system call.
|
||
According to recent versions of the POSIX specification, it is really an
|
||
<em>exception</em> condition, of which the only standard example is out-of-band
|
||
data received on a socket. So zsh users are unlikely to find the <code>-e</code>
|
||
option useful.)</p>
|
||
<p>The option ‘<code>-t</code> <code>timeout</code>’ specifies a timeout in hundredths of a
|
||
second. This may be zero, in which case the file descriptors will simply
|
||
be polled and <code>zselect</code> will return immediately. It is possible to call
|
||
zselect with no file descriptors and a non-zero timeout for use as a
|
||
finer-grained replacement for ‘sleep’; note, however, the return status
|
||
is always 1 for a timeout.</p>
|
||
<p>The option ‘<code>-a</code> <code>array</code>’ indicates that <code>array</code> should be set to
|
||
indicate the file descriptor(s) which are ready. If the option is not
|
||
given, the array <code>reply</code> will be used for this purpose. The array will
|
||
contain a string similar to the arguments for <code>zselect</code>. For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zselect -t 0 -r 0 -w 1
|
||
</code></pre>
|
||
</div>
|
||
<p>might return immediately with status 0 and <code>$reply</code> containing ‘<code>-r 0 -w 1</code>’ to show that both file descriptors are ready for the requested
|
||
operations.</p>
|
||
<p>The option ‘<code>-A</code> <code>assoc</code>’ indicates that the associative array <code>assoc</code>
|
||
should be set to indicate the file descriptor(s) which are ready. This
|
||
option overrides the option <code>-a</code>, nor will <code>reply</code> be modified. The keys
|
||
of <code>assoc</code> are the file descriptors, and the corresponding values are
|
||
any of the characters ‘<code>rwe</code>’ to indicate the condition.</p>
|
||
<p>The command returns status 0 if some file descriptors are ready for
|
||
reading. If the operation timed out, or a timeout of 0 was given and no
|
||
file descriptors were ready, or there was an error, it returns status 1
|
||
and the array will not be set (nor modified in any way). If there was an
|
||
error in the select operation the appropriate error message is printed.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fzutil-Module"></span>
|
||
<span id="The-zsh_002fzutil-Module-1"></span></p>
|
||
<h2 id="2237-the-zshzutil-module"><a class="header" href="#2237-the-zshzutil-module">22.37 The zsh/zutil Module</a></h2>
|
||
<p><span id="index-builtins_002c-utility"></span></p>
|
||
<p>The <code>zsh/zutil</code> module only adds some builtins:</p>
|
||
<p><span id="index-zstyle"></span></p>
|
||
<p><code>zstyle</code> [ <code>-L</code> [ <code>metapattern</code> [ <code>style</code> ] ] ]</p>
|
||
<p><code>zstyle</code> [ <code>-e</code> | <code>-</code> | <code>-``-</code> ] <code>pattern</code> <code>style</code> <code>string</code> ...</p>
|
||
<p><code>zstyle -d</code> [ <code>pattern</code> [ <code>style</code> ... ] ]</p>
|
||
<p><code>zstyle -g</code> <code>name</code> [ <code>pattern</code> [ <code>style</code> ] ]</p>
|
||
<p><code>zstyle -</code>{<code>a</code>|<code>b</code>|<code>s</code>} <code>context</code> <code>style</code> <code>name</code> [ <code>sep</code> ]</p>
|
||
<p><code>zstyle -</code>{<code>T</code>|<code>t</code>} <code>context</code> <code>style</code> [ <code>string</code> ... ]</p>
|
||
<p><code>zstyle -m</code> <code>context</code> <code>style</code> <code>pattern</code></p>
|
||
<p>This builtin command is used to define and lookup styles. Styles are
|
||
pairs of names and values, where the values consist of any number of
|
||
strings. They are stored together with patterns and lookup is done by
|
||
giving a string, called the ‘<em>context</em>’, which is matched against the
|
||
patterns. The definition stored for the most specific pattern that
|
||
matches will be returned.</p>
|
||
<p>A pattern is considered to be more specific than another if it contains
|
||
more components (substrings separated by colons) or if the patterns for
|
||
the components are more specific, where simple strings are considered to
|
||
be more specific than patterns and complex patterns are considered to be
|
||
more specific than the pattern ‘<code>*</code>’. A ‘<code>*</code>’ in the pattern will match
|
||
zero or more characters in the context; colons are not treated specially
|
||
in this regard. If two patterns are equally specific, the tie is broken
|
||
in favour of the pattern that was defined first.</p>
|
||
<p><em>Example</em></p>
|
||
<p>For example, to define your preferred form of precipitation depending on
|
||
which city you’re in, you might set the following in your <code>zshrc</code>:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle ':weather:europe:*' preferred-precipitation rain
|
||
zstyle ':weather:europe:germany:* preferred-precipitation none
|
||
zstyle ':weather:europe:germany:*:munich' preferred-precipitation snow
|
||
</code></pre>
|
||
</div>
|
||
<p>Then, the fictional ‘<code>weather</code>’ plugin might run under the hood a
|
||
command such as</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zstyle -s ":weather:${continent}:${country}:${county}:${city}" preferred-precipitation REPLY
|
||
</code></pre>
|
||
</div>
|
||
<p>in order to retrieve your preference into the scalar variable <code>$REPLY</code>.</p>
|
||
<p><em>Usage</em></p>
|
||
<p>The forms that operate on patterns are the following.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>zstyle</code> [ <code>-L</code> [ <code>metapattern</code> [ <code>style</code> ] ] ]<br />
|
||
Without arguments, lists style definitions. Styles are shown in
|
||
alphabetic order and patterns are shown in the order <code>zstyle</code> will
|
||
test them.</p>
|
||
<p>If the <code>-L</code> option is given, listing is done in the form of calls to
|
||
<code>zstyle</code>. The optional first argument, <code>metapattern</code>, is a pattern
|
||
which will be matched against the string supplied as <code>pattern</code> when
|
||
the style was defined. Note: this means, for example, ‘<code>zstyle -L ":completion:*"</code>’ will match any supplied pattern beginning
|
||
‘<code>:completion:</code>’, not just <code>":completion:*"</code>: use
|
||
<code>’:completion:\*’</code> to match that. The optional second argument
|
||
limits the output to a specific <code>style</code> (not a pattern). <code>-L</code> is not
|
||
compatible with any other options.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zstyle</code> [ <code>-</code> | <code>-``-</code> | <code>-e</code> ] <code>pattern</code> <code>style</code> <code>string</code> ...<br />
|
||
<span id="index-reply_002c-use-of-4"></span></p>
|
||
<p>Defines the given <code>style</code> for the <code>pattern</code> with the <code>string</code>s as
|
||
the value. If the <code>-e</code> option is given, the <code>string</code>s will be
|
||
concatenated (separated by spaces) and the resulting string will be
|
||
evaluated (in the same way as it is done by the <code>eval</code> builtin
|
||
command) when the style is looked up. In this case the parameter
|
||
‘<code>reply</code>’ must be assigned to set the strings returned after the
|
||
evaluation. Before evaluating the value, <code>reply</code> is unset, and if it
|
||
is still unset after the evaluation, the style is treated as if it
|
||
were not set.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zstyle -d</code> [ <code>pattern</code> [ <code>style</code> ... ] ]<br />
|
||
Delete style definitions. Without arguments all definitions are
|
||
deleted, with a <code>pattern</code> all definitions for that pattern are
|
||
deleted and if any <code>style</code>s are given, then only those styles are
|
||
deleted for the <code>pattern</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zstyle -g</code> <code>name</code> [ <code>pattern</code> [ <code>style</code> ] ]<br />
|
||
Retrieve a style definition. The <code>name</code> is used as the name of an
|
||
array in which the results are stored. Without any further
|
||
arguments, all patterns defined are returned. With a <code>pattern</code> the
|
||
styles defined for that pattern are returned and with both a
|
||
<code>pattern</code> and a <code>style</code>, the value strings of that combination is
|
||
returned.</p>
|
||
</li>
|
||
</ul>
|
||
<p>The other forms can be used to look up or test styles for a given
|
||
context.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>zstyle -s</code> <code>context</code> <code>style</code> <code>name</code> [ <code>sep</code> ]<br />
|
||
The parameter <code>name</code> is set to the value of the style interpreted as
|
||
a string. If the value contains several strings they are
|
||
concatenated with spaces (or with the <code>sep</code> string if that is given)
|
||
between them.</p>
|
||
<p>Return <code>0</code> if the style is set, <code>1</code> otherwise.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zstyle -b</code> <code>context</code> <code>style</code> <code>name</code><br />
|
||
The value is stored in <code>name</code> as a boolean, i.e. as the string
|
||
‘<code>yes</code>’ if the value has only one string and that string is equal
|
||
to one of ‘<code>yes</code>’, ‘<code>true</code>’, ‘<code>on</code>’, or ‘<code>1</code>’. If the value is any
|
||
other string or has more than one string, the parameter is set to
|
||
‘<code>no</code>’.</p>
|
||
<p>Return <code>0</code> if <code>name</code> is set to ‘<code>yes</code>’, <code>1</code> otherwise.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zstyle -a</code> <code>context</code> <code>style</code> <code>name</code><br />
|
||
The value is stored in <code>name</code> as an array. If <code>name</code> is declared as
|
||
an associative array, the first, third, etc. strings are used as the
|
||
keys and the other strings are used as the values.</p>
|
||
<p>Return <code>0</code> if the style is set, <code>1</code> otherwise.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zstyle -t</code> <code>context</code> <code>style</code> [ <code>string</code> ... ]<br />
|
||
<code>zstyle -T</code> <code>context</code> <code>style</code> [ <code>string</code> ... ]<br />
|
||
Test the value of a style, i.e. the <code>-t</code> option only returns a
|
||
status (sets <code>$?</code>). Without any <code>string</code> the return status is zero
|
||
if the style is defined for at least one matching pattern, has only
|
||
one string in its value, and that is equal to one of ‘<code>true</code>’,
|
||
‘<code>yes</code>’, ‘<code>on</code>’ or ‘<code>1</code>’. If any <code>string</code>s are given the status is
|
||
zero if and only if at least one of the <code>string</code>s is equal to at
|
||
least one of the strings in the value. If the style is defined but
|
||
doesn’t match, the return status is <code>1</code>. If the style is not
|
||
defined, the status is <code>2</code>.</p>
|
||
<p>The <code>-T</code> option tests the values of the style like <code>-t</code>, but it
|
||
returns status zero (rather than <code>2</code>) if the style is not defined
|
||
for any matching pattern.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>zstyle -m</code> <code>context</code> <code>style</code> <code>pattern</code><br />
|
||
Match a value. Returns status zero if the <code>pattern</code> matches at least
|
||
one of the strings in the value.</p>
|
||
</li>
|
||
</ul>
|
||
<p><span id="index-zformat"></span></p>
|
||
<p><code>zformat -f</code> <code>param</code> <code>format</code> <code>spec</code> ...</p>
|
||
<p><code>zformat -a</code> <code>array</code> <code>sep</code> <code>spec</code> ...</p>
|
||
<p>This builtin provides two different forms of formatting. The first form
|
||
is selected with the <code>-f</code> option. In this case the <code>format</code> string will
|
||
be modified by replacing sequences starting with a percent sign in it
|
||
with strings from the <code>spec</code>s. Each <code>spec</code> should be of the form
|
||
‘<code>char``:``string</code>’ which will cause every appearance of the sequence
|
||
‘<code>%``char</code>’ in <code>format</code> to be replaced by the <code>string</code>. The ‘<code>%</code>’
|
||
sequence may also contain optional minimum and maximum field width
|
||
specifications between the ‘<code>%</code>’ and the ‘<code>char</code>’ in the form
|
||
‘<code>%``min``.``max``c</code>’, i.e. the minimum field width is given first and
|
||
if the maximum field width is used, it has to be preceded by a dot.
|
||
Specifying a minimum field width makes the result be padded with spaces
|
||
to the right if the <code>string</code> is shorter than the requested width.
|
||
Padding to the left can be achieved by giving a negative minimum field
|
||
width. If a maximum field width is specified, the <code>string</code> will be
|
||
truncated after that many characters. After all ‘<code>%</code>’ sequences for the
|
||
given <code>spec</code>s have been processed, the resulting string is stored in the
|
||
parameter <code>param</code>.</p>
|
||
<p>The <code>%</code>-escapes also understand ternary expressions in the form used by
|
||
prompts. The <code>%</code> is followed by a ‘<code>(</code>’ and then an ordinary format
|
||
specifier character as described above. There may be a set of digits
|
||
either before or after the ‘<code>(</code>’; these specify a test number, which
|
||
defaults to zero. Negative numbers are also allowed. An arbitrary
|
||
delimiter character follows the format specifier, which is followed by a
|
||
piece of ‘true’ text, the delimiter character again, a piece of ‘false’
|
||
text, and a closing parenthesis. The complete expression (without the
|
||
digits) thus looks like ‘<code>%(``X``.``text1``.``text2``)</code>’, except that
|
||
the ‘<code>.</code>’ character is arbitrary. The value given for the format
|
||
specifier in the <code>char``:``string</code> expressions is evaluated as a
|
||
mathematical expression, and compared with the test number. If they are
|
||
the same, <code>text1</code> is output, else <code>text2</code> is output. A parenthesis may
|
||
be escaped in <code>text2</code> as <code>%)</code>. Either of <code>text1</code> or <code>text2</code> may contain
|
||
nested <code>%</code>-escapes.</p>
|
||
<p>For example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">zformat -f REPLY "The answer is '%3(c.yes.no)'." c:3
|
||
</code></pre>
|
||
</div>
|
||
<p>outputs "The answer is ’yes’." to <code>REPLY</code> since the value for the format
|
||
specifier <code>c</code> is 3, agreeing with the digit argument to the ternary
|
||
expression.</p>
|
||
<p>The second form, using the <code>-a</code> option, can be used for aligning
|
||
strings. Here, the <code>spec</code>s are of the form ‘<code>left``:``right</code>’ where
|
||
‘<code>left</code>’ and ‘<code>right</code>’ are arbitrary strings. These strings are
|
||
modified by replacing the colons by the <code>sep</code> string and padding the
|
||
<code>left</code> strings with spaces to the right so that the <code>sep</code> strings in the
|
||
result (and hence the <code>right</code> strings after them) are all aligned if the
|
||
strings are printed below each other. All strings without a colon are
|
||
left unchanged and all strings with an empty <code>right</code> string have the
|
||
trailing colon removed. In both cases the lengths of the strings are not
|
||
used to determine how the other strings are to be aligned. A colon in
|
||
the <code>left</code> string can be escaped with a backslash. The resulting strings
|
||
are stored in the <code>array</code>.</p>
|
||
<p><span id="index-zregexparse"></span></p>
|
||
<p><code>zregexparse</code></p>
|
||
<p>This implements some internals of the <code>_regex_arguments</code> function.</p>
|
||
<p><span id="index-zparseopts"></span></p>
|
||
<p><code>zparseopts</code> [ <code>-D</code> <code>-E</code> <code>-F</code> <code>-K</code> <code>-M</code> ] [ <code>-a</code> <code>array</code> ] [ <code>-A</code>
|
||
<code>assoc</code> ] [ <code>-</code> ] <code>spec</code> ...</p>
|
||
<p>This builtin simplifies the parsing of options in positional parameters,
|
||
i.e. the set of arguments given by <code>$*</code>. Each <code>spec</code> describes one
|
||
option and must be of the form ‘<code>opt</code>[<code>=``array</code>]’. If an option
|
||
described by <code>opt</code> is found in the positional parameters it is copied
|
||
into the <code>array</code> specified with the <code>-a</code> option; if the optional
|
||
‘<code>=``array</code>’ is given, it is instead copied into that array, which
|
||
should be declared as a normal array and never as an associative array.</p>
|
||
<p>Note that it is an error to give any <code>spec</code> without an ‘<code>=``array</code>’
|
||
unless one of the <code>-a</code> or <code>-A</code> options is used.</p>
|
||
<p>Unless the <code>-E</code> option is given, parsing stops at the first string that
|
||
isn’t described by one of the <code>spec</code>s. Even with <code>-E</code>, parsing always
|
||
stops at a positional parameter equal to ‘<code>-</code>’ or ‘<code>-``-</code>’. See also
|
||
<code>-F</code>.</p>
|
||
<p>The <code>opt</code> description must be one of the following. Any of the special
|
||
characters can appear in the option name provided it is preceded by a
|
||
backslash.</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>name</code><br />
|
||
<code>name``+</code><br />
|
||
The <code>name</code> is the name of the option without the leading ‘<code>-</code>’. To
|
||
specify a GNU-style long option, one of the usual two leading ‘<code>-</code>’
|
||
must be included in <code>name</code>; for example, a ‘<code>-``-file</code>’ option is
|
||
represented by a <code>name</code> of ‘<code>-file</code>’.</p>
|
||
<p>If a ‘<code>+</code>’ appears after <code>name</code>, the option is appended to <code>array</code>
|
||
each time it is found in the positional parameters; without the
|
||
‘<code>+</code>’ only the <em>last</em> occurrence of the option is preserved.</p>
|
||
<p>If one of these forms is used, the option takes no argument, so
|
||
parsing stops if the next positional parameter does not also begin
|
||
with ‘<code>-</code>’ (unless the <code>-E</code> option is used).</p>
|
||
</li>
|
||
<li>
|
||
<p><code>name``:</code><br />
|
||
<code>name``:-</code><br />
|
||
<code>name``::</code><br />
|
||
If one or two colons are given, the option takes an argument; with
|
||
one colon, the argument is mandatory and with two colons it is
|
||
optional. The argument is appended to the <code>array</code> after the option
|
||
itself.</p>
|
||
<p>An optional argument is put into the same array element as the
|
||
option name (note that this makes empty strings as arguments
|
||
indistinguishable). A mandatory argument is added as a separate
|
||
element unless the ‘<code>:-</code>’ form is used, in which case the argument
|
||
is put into the same element.</p>
|
||
<p>A ‘<code>+</code>’ as described above may appear between the <code>name</code> and the
|
||
first colon.</p>
|
||
</li>
|
||
</ul>
|
||
<p>In all cases, option-arguments must appear either immediately following
|
||
the option in the same positional parameter or in the next one. Even an
|
||
optional argument may appear in the next parameter, unless it begins
|
||
with a ‘<code>-</code>’. There is no special handling of ‘<code>=</code>’ as with GNU-style
|
||
argument parsers; given the <code>spec</code> ‘<code>-foo:</code>’, the positional parameter
|
||
‘<code>-``-foo=bar</code>’ is parsed as ‘<code>-``-foo</code>’ with an argument of ‘<code>=bar</code>’.</p>
|
||
<p>When the names of two options that take no arguments overlap, the
|
||
longest one wins, so that parsing for the <code>spec</code>s ‘<code>-foo -foobar</code>’ (for
|
||
example) is unambiguous. However, due to the aforementioned handling of
|
||
option-arguments, ambiguities may arise when at least one overlapping
|
||
<code>spec</code> takes an argument, as in ‘<code>-foo: -foobar</code>’. In that case, the
|
||
last matching <code>spec</code> wins.</p>
|
||
<p>The options of <code>zparseopts</code> itself cannot be stacked because, for
|
||
example, the stack ‘<code>-DEK</code>’ is indistinguishable from a <code>spec</code> for the
|
||
GNU-style long option ‘<code>-``-DEK</code>’. The options of <code>zparseopts</code> itself
|
||
are:</p>
|
||
<ul>
|
||
<li>
|
||
<p><code>-a</code> <code>array</code><br />
|
||
As described above, this names the default array in which to store
|
||
the recognised options.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-A</code> <code>assoc</code><br />
|
||
If this is given, the options and their values are also put into an
|
||
associative array with the option names as keys and the arguments
|
||
(if any) as the values.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-D</code><br />
|
||
If this option is given, all options found are removed from the
|
||
positional parameters of the calling shell or shell function, up to
|
||
but not including any not described by the <code>spec</code>s. If the first
|
||
such parameter is ‘<code>-</code>’ or ‘<code>-``-</code>’, it is removed as well. This is
|
||
similar to using the <code>shift</code> builtin.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-E</code><br />
|
||
This changes the parsing rules to <em>not</em> stop at the first string
|
||
that isn’t described by one of the <code>spec</code>s. It can be used to test
|
||
for or (if used together with <code>-D</code>) extract options and their
|
||
arguments, ignoring all other options and arguments that may be in
|
||
the positional parameters. As indicated above, parsing still stops
|
||
at the first ‘<code>-</code>’ or ‘<code>-``-</code>’ not described by a <code>spec</code>, but it is
|
||
not removed when used with <code>-D</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-F</code><br />
|
||
If this option is given, <code>zparseopts</code> immediately stops at the first
|
||
option-like parameter not described by one of the <code>spec</code>s, prints an
|
||
error message, and returns status 1. Removal (<code>-D</code>) and extraction
|
||
(<code>-E</code>) are not performed, and option arrays are not updated. This
|
||
provides basic validation for the given options.</p>
|
||
<p>Note that the appearance in the positional parameters of an option
|
||
without its required argument always aborts parsing and returns an
|
||
error as described above regardless of whether this option is used.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-K</code><br />
|
||
With this option, the arrays specified with the <code>-a</code> option and with
|
||
the ‘<code>=``array</code>’ forms are kept unchanged when none of the <code>spec</code>s
|
||
for them is used. Otherwise the entire array is replaced when any of
|
||
the <code>spec</code>s is used. Individual elements of associative arrays
|
||
specified with the <code>-A</code> option are preserved by <code>-K</code>. This allows
|
||
assignment of default values to arrays before calling <code>zparseopts</code>.</p>
|
||
</li>
|
||
<li>
|
||
<p><code>-M</code><br />
|
||
This changes the assignment rules to implement a map among
|
||
equivalent option names. If any <code>spec</code> uses the ‘<code>=``array</code>’ form,
|
||
the string <code>array</code> is interpreted as the name of another <code>spec</code>,
|
||
which is used to choose where to store the values. If no other
|
||
<code>spec</code> is found, the values are stored as usual. This changes only
|
||
the way the values are stored, not the way <code>$*</code> is parsed, so
|
||
results may be</p>
|
||
</li>
|
||
</ul>
|
||
<p>For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">set -- -a -bx -c y -cz baz -cend
|
||
zparseopts a=foo b:=bar c+:=bar
|
||
</code></pre>
|
||
</div>
|
||
<p>will have the effect of</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">foo=(-a)
|
||
bar=(-b x -c y -c z)
|
||
</code></pre>
|
||
</div>
|
||
<p>The arguments from ‘<code>baz</code>’ on will not be used.</p>
|
||
<p>As an example for the <code>-E</code> option, consider:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">set -- -a x -b y -c z arg1 arg2
|
||
zparseopts -E -D b:=bar
|
||
</code></pre>
|
||
</div>
|
||
<p>will have the effect of</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">bar=(-b y)
|
||
set -- -a x -c z arg1 arg2
|
||
</code></pre>
|
||
</div>
|
||
<p>I.e., the option <code>-b</code> and its arguments are taken from the positional
|
||
parameters and put into the array <code>bar</code>.</p>
|
||
<p>The <code>-M</code> option can be used like this:</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">set -- -a -bx -c y -cz baz -cend
|
||
zparseopts -A bar -M a=foo b+: c:=b
|
||
</code></pre>
|
||
</div>
|
||
<p>to have the effect of</p>
|
||
<div class="example">
|
||
<pre><code class="language-example">foo=(-a)
|
||
bar=(-a '' -b xyz)
|
||
</code></pre>
|
||
</div>
|
||
<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="Completion-Using-compctl.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="Calendar-Function-System.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="Completion-Using-compctl.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="Calendar-Function-System.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>
|