3678 lines
206 KiB
HTML
3678 lines
206 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 -->
|
||
<link rel="stylesheet" href="./theme/catppuccin.css">
|
||
<link rel="stylesheet" href="./theme/catppuccin-highlight.css">
|
||
|
||
</head>
|
||
<body>
|
||
<!-- Provide site root to javascript -->
|
||
<script type="text/javascript">
|
||
var path_to_root = "";
|
||
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
|
||
</script>
|
||
|
||
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
||
<script type="text/javascript">
|
||
try {
|
||
var theme = localStorage.getItem('mdbook-theme');
|
||
var sidebar = localStorage.getItem('mdbook-sidebar');
|
||
|
||
if (theme.startsWith('"') && theme.endsWith('"')) {
|
||
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
||
}
|
||
|
||
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
||
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
||
}
|
||
} catch (e) { }
|
||
</script>
|
||
|
||
<!-- Set the theme before any content is loaded, prevents flash -->
|
||
<script type="text/javascript">
|
||
var theme;
|
||
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
||
if (theme === null || theme === undefined) { theme = default_theme; }
|
||
var html = document.querySelector('html');
|
||
html.classList.remove('no-js')
|
||
html.classList.remove('light')
|
||
html.classList.add(theme);
|
||
html.classList.add('js');
|
||
</script>
|
||
|
||
<!-- Hide / unhide sidebar before it is displayed -->
|
||
<script type="text/javascript">
|
||
var html = document.querySelector('html');
|
||
var sidebar = 'hidden';
|
||
if (document.body.clientWidth >= 1080) {
|
||
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
||
sidebar = sidebar || 'visible';
|
||
}
|
||
html.classList.remove('sidebar-visible');
|
||
html.classList.add("sidebar-" + sidebar);
|
||
</script>
|
||
|
||
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
||
<div class="sidebar-scrollbox">
|
||
<ol class="chapter"><li class="chapter-item expanded "><a href="The-Z-Shell-Manual.html"><strong aria-hidden="true">1.</strong> The Z Shell Manual</a></li><li class="chapter-item expanded "><a href="Introduction.html"><strong aria-hidden="true">2.</strong> Introduction</a></li><li class="chapter-item expanded "><a href="Roadmap.html"><strong aria-hidden="true">3.</strong> Roadmap</a></li><li class="chapter-item expanded "><a href="Invocation.html"><strong aria-hidden="true">4.</strong> Invocation</a></li><li class="chapter-item expanded "><a href="Files.html"><strong aria-hidden="true">5.</strong> Files</a></li><li class="chapter-item expanded "><a href="Shell-Grammar.html"><strong aria-hidden="true">6.</strong> Shell Grammar</a></li><li class="chapter-item expanded "><a href="Redirection.html"><strong aria-hidden="true">7.</strong> Redirection</a></li><li class="chapter-item expanded "><a href="Command-Execution.html"><strong aria-hidden="true">8.</strong> Command Execution</a></li><li class="chapter-item expanded "><a href="Functions.html"><strong aria-hidden="true">9.</strong> Functions</a></li><li class="chapter-item expanded "><a href="Jobs-&-Signals.html"><strong aria-hidden="true">10.</strong> Jobs & Signals</a></li><li class="chapter-item expanded "><a href="Arithmetic-Evaluation.html"><strong aria-hidden="true">11.</strong> Arithmetic Evaluation</a></li><li class="chapter-item expanded "><a href="Conditional-Expressions.html"><strong aria-hidden="true">12.</strong> Conditional Expressions</a></li><li class="chapter-item expanded "><a href="Prompt-Expansion.html"><strong aria-hidden="true">13.</strong> Prompt Expansion</a></li><li class="chapter-item expanded "><a href="Expansion.html"><strong aria-hidden="true">14.</strong> Expansion</a></li><li class="chapter-item expanded "><a href="Parameters.html"><strong aria-hidden="true">15.</strong> Parameters</a></li><li class="chapter-item expanded "><a href="Options.html"><strong aria-hidden="true">16.</strong> Options</a></li><li class="chapter-item expanded "><a href="Shell-Builtin-Commands.html"><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>
|
||
<li role="none"><button role="menuitem" class="theme" id="latte">Latte</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="frappe">Frappé</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="macchiato">Macchiato</button></li>
|
||
<li role="none"><button role="menuitem" class="theme" id="mocha">Mocha</button></li>
|
||
</ul>
|
||
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
|
||
<i class="fa fa-search"></i>
|
||
</button>
|
||
</div>
|
||
|
||
<h1 class="menu-title">Zsh Manual</h1>
|
||
|
||
<div class="right-buttons">
|
||
<a href="print.html" title="Print this book" aria-label="Print this book">
|
||
<i id="print-button" class="fa fa-print"></i>
|
||
</a>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
<div id="search-wrapper" class="hidden">
|
||
<form id="searchbar-outer" class="searchbar-outer">
|
||
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
||
</form>
|
||
<div id="searchresults-outer" class="searchresults-outer hidden">
|
||
<div id="searchresults-header" class="searchresults-header"></div>
|
||
<ul id="searchresults">
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
|
||
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
||
<script type="text/javascript">
|
||
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
||
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
||
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
||
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
||
});
|
||
</script>
|
||
|
||
<div id="content" class="content">
|
||
<main>
|
||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||
<p><strong>Table of Contents</strong> <em>generated with <a href="https://github.com/thlorenz/doctoc">DocToc</a></em></p>
|
||
<ul>
|
||
<li><a href="#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-zshwatch-module">22.31 The zsh/watch Module</a></li>
|
||
<li><a href="#2232-the-zshzftp-module">22.32 The zsh/zftp Module</a>
|
||
<ul>
|
||
<li><a href="#22321-subcommands">22.32.1 Subcommands</a></li>
|
||
<li><a href="#22322-parameters">22.32.2 Parameters</a></li>
|
||
<li><a href="#22323-functions">22.32.3 Functions</a></li>
|
||
<li><a href="#22324-problems">22.32.4 Problems</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#2233-the-zshzle-module">22.33 The zsh/zle Module</a></li>
|
||
<li><a href="#2234-the-zshzleparameter-module">22.34 The zsh/zleparameter Module</a></li>
|
||
<li><a href="#2235-the-zshzprof-module">22.35 The zsh/zprof Module</a></li>
|
||
<li><a href="#2236-the-zshzpty-module">22.36 The zsh/zpty Module</a></li>
|
||
<li><a href="#2237-the-zshzselect-module">22.37 The zsh/zselect Module</a></li>
|
||
<li><a href="#2238-the-zshzutil-module">22.38 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-4"></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 zmodload 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>
|
||
<p>zsh/attr<br />
|
||
Builtins for manipulating extended attributes (xattr).</p>
|
||
<p>zsh/cap<br />
|
||
Builtins for manipulating POSIX.1e (POSIX.6) capability (privilege)
|
||
sets.</p>
|
||
<p>zsh/clone<br />
|
||
A builtin that can clone a running shell onto another terminal.</p>
|
||
<p>zsh/compctl<br />
|
||
The compctl builtin for controlling completion.</p>
|
||
<p>zsh/complete<br />
|
||
The basic completion code.</p>
|
||
<p>zsh/complist<br />
|
||
Completion listing extensions.</p>
|
||
<p>zsh/computil<br />
|
||
A module with utility builtins needed for the shell function based
|
||
completion system.</p>
|
||
<p>zsh/curses<br />
|
||
curses windowing commands</p>
|
||
<p>zsh/datetime<br />
|
||
Some date/time commands and parameters.</p>
|
||
<p>zsh/db/gdbm<br />
|
||
Builtins for managing associative array parameters tied to GDBM
|
||
databases.</p>
|
||
<p>zsh/deltochar<br />
|
||
A ZLE function duplicating EMACS’ zap-to-char.</p>
|
||
<p>zsh/example<br />
|
||
An example of how to write a module.</p>
|
||
<p>zsh/files<br />
|
||
Some basic file manipulation commands as builtins.</p>
|
||
<p>zsh/langinfo<br />
|
||
Interface to locale information.</p>
|
||
<p>zsh/mapfile<br />
|
||
Access to external files via a special associative array.</p>
|
||
<p>zsh/mathfunc<br />
|
||
Standard scientific functions for use in mathematical evaluations.</p>
|
||
<p>zsh/nearcolor<br />
|
||
Map colours to the nearest colour in the available palette.</p>
|
||
<p>zsh/newuser<br />
|
||
Arrange for files for new users to be installed.</p>
|
||
<p>zsh/parameter<br />
|
||
zsh/pcre<br />
|
||
Interface to the PCRE library.</p>
|
||
<p>zsh/param/private<br />
|
||
Builtins for managing private-scoped parameters in function context.</p>
|
||
<p>zsh/regex<br />
|
||
Interface to the POSIX regex library.</p>
|
||
<p>zsh/sched<br />
|
||
A builtin that provides a timed execution facility within the shell.</p>
|
||
<p>zsh/net/socket<br />
|
||
Manipulation of Unix domain sockets</p>
|
||
<p>zsh/stat<br />
|
||
A builtin command interface to the stat system call.</p>
|
||
<p>zsh/system<br />
|
||
A builtin interface to various low-level system features.</p>
|
||
<p>zsh/net/tcp<br />
|
||
Manipulation of TCP sockets</p>
|
||
<p>zsh/termcap<br />
|
||
Interface to the termcap database.</p>
|
||
<p>zsh/terminfo<br />
|
||
Interface to the terminfo database.</p>
|
||
<p>zsh/watch<br />
|
||
Reporting of login and logout events.</p>
|
||
<p>zsh/zftp<br />
|
||
A builtin FTP client.</p>
|
||
<p>zsh/zle<br />
|
||
The Zsh Line Editor, including the bindkey and vared builtins.</p>
|
||
<p>zsh/zleparameter<br />
|
||
Access to internals of the Zsh Line Editor via parameters.</p>
|
||
<p>zsh/zprof<br />
|
||
A module allowing profiling for shell functions.</p>
|
||
<p>zsh/zpty<br />
|
||
A builtin for starting a command in a pseudo-terminal.</p>
|
||
<p>zsh/zselect<br />
|
||
Block and return when file descriptors are ready.</p>
|
||
<p>zsh/zutil<br />
|
||
Some utility builtins, e.g. the one for supporting configuration via
|
||
styles.</p>
|
||
<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 zsh/attr module is used for manipulating extended attributes. The -h
|
||
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>zgetattr [ -h ] <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>zsetattr [ -h ] <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>zdelattr [ -h ] <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>zlistattr [ -h ] <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>zgetattr and zlistattr 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 zsh/cap 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>cap [ <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>getcap <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>setcap <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 zsh/clone 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>clone <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 PID, PPID and TTY special
|
||
parameters are changed appropriately. $! 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 clone 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-zsh">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>clone 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 zsh/compctl module makes available two builtin commands. compctl, 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, compcall 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 zsh/complete 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 zsh/complist 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 ZLS_COLORS or ZLS_COLOURS is set and the
|
||
zsh/complist module is loaded or linked into the shell, completion lists
|
||
will be colored. Note, however, that complist will not automatically be
|
||
loaded if it is not linked in: on systems with dynamic loading,
|
||
‘zmodload zsh/complist’ is required.</p>
|
||
<p><span id="index-ZLS_005fCOLORS"></span> <span
|
||
id="index-ZLS_005fCOLOURS"></span></p>
|
||
<p>The parameters ZLS_COLORS and ZLS_COLOURS 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
|
||
ls command: a colon-separated list of specifications of the form
|
||
‘<code>name</code>=<code>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>
|
||
<p>no 0<br />
|
||
for normal text (i.e. when displaying something other than a matched
|
||
file)</p>
|
||
<p>fi 0<br />
|
||
for regular files</p>
|
||
<p>di 32<br />
|
||
for directories</p>
|
||
<p>ln 36<br />
|
||
for symbolic links. If this has the special value target, symbolic links
|
||
are dereferenced and the target file used to determine the display
|
||
format.</p>
|
||
<p>pi 31<br />
|
||
for named pipes (FIFOs)</p>
|
||
<p>so 33<br />
|
||
for sockets</p>
|
||
<p>bd 44;37<br />
|
||
for block devices</p>
|
||
<p>cd 44;37<br />
|
||
for character devices</p>
|
||
<p>or <code>none</code><br />
|
||
for a symlink to nonexistent file (default is the value defined for ln)</p>
|
||
<p>mi <code>none</code><br />
|
||
for a non-existent file (default is the value defined for fi); this code
|
||
is currently not used</p>
|
||
<p>su 37;41<br />
|
||
for files with setuid bit set</p>
|
||
<p>sg 30;43<br />
|
||
for files with setgid bit set</p>
|
||
<p>tw 30;42<br />
|
||
ow 34;43<br />
|
||
sa <code>none</code><br />
|
||
for files with an associated suffix alias; this is only tested after
|
||
specific suffixes, as described below</p>
|
||
<p>st 37;44<br />
|
||
ex 35<br />
|
||
lc \e[<br />
|
||
for the left code (see below)</p>
|
||
<p>rc m<br />
|
||
for the right code</p>
|
||
<p>tc 0<br />
|
||
for the character indicating the file type printed after filenames if
|
||
the LIST_TYPES option is set</p>
|
||
<p>sp 0<br />
|
||
for the spaces printed after matches to align the next column</p>
|
||
<p>ec <code>none</code><br />
|
||
for the end code</p>
|
||
<p>Apart from these strings, the <code>name</code> may also be an asterisk (‘*’)
|
||
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 (‘=’) followed by a pattern; the EXTENDED_GLOB 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
|
||
‘(#b)’ 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
|
||
‘=(#b)(?)*(?)=0=3=7’ will be used for all matches which are at least
|
||
two characters long and will use the code ‘3’ for the first character,
|
||
‘7’ for the last character and ‘0’ 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, ‘(g*)m*=43’ highlights all matches beginning with ‘m’ in
|
||
groups whose names begin with ‘g’ using the color code ‘43’. In case of
|
||
the ‘lc’, ‘rc’, and ‘ec’ 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 lc, the value for
|
||
the file-type or the last matching specification with a ‘*’, the value
|
||
of rc, the string to display for the match itself, and then the value of
|
||
ec if that is defined or the values of lc, no, and rc if ec is not
|
||
defined.</p>
|
||
<p>The default values are ISO 6429 (ANSI) compliant and can be used on
|
||
vt100 compatible terminals such as xterms. On monochrome terminals the
|
||
default values will have no visible effect. The colors 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 colors, one could use ‘$color[red]’ to get the code for
|
||
foreground color red and ‘$color[bg-green]’ 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 list-colors 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 LISTPROMPT 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 ‘%x’. It supports the escapes ‘%B’, ‘%b’, ‘%S’, ‘%s’, ‘%U’,
|
||
‘%u’, ‘%F’, ‘%f’, ‘%K’, ‘%k’ and ‘%{<code>...</code>%}’ used also in shell prompts
|
||
as well as three pairs of additional sequences: a ‘%l’ or ‘%L’ is
|
||
replaced by the number of the last line shown and the total number of
|
||
lines in the form ‘<code>number</code>/<code>total</code>’; a ‘%m’ or ‘%M’ is replaced with
|
||
the number of the last match shown and the total number of matches; and
|
||
‘%p’ or ‘%P’ is replaced with ‘Top’, ‘Bottom’ 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 LISTPROMPT 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
|
||
listscroll keymap. Some of the zle functions have a special meaning
|
||
while scrolling lists:</p>
|
||
<p>send-break<br />
|
||
stops listing discarding the key pressed</p>
|
||
<p>accept-line, down-history, down-line-or-history<br />
|
||
down-line-or-search, vi-down-line-or-history<br />
|
||
scrolls forward one line</p>
|
||
<p>complete-word, menu-complete, expand-or-complete<br />
|
||
expand-or-complete-prefix, menu-complete-or-expand<br />
|
||
scrolls forward one screenful</p>
|
||
<p>accept-search<br />
|
||
stop listing but take no other action</p>
|
||
<p>Every other character stops listing and immediately processes the key as
|
||
usual. Any key that is not bound in the listscroll keymap or that is
|
||
bound to undefined-key is looked up in the keymap currently selected.</p>
|
||
<p>As for the ZLS_COLORS and ZLS_COLOURS parameters, LISTPROMPT should not
|
||
be set directly when using the shell function based completion system.
|
||
Instead, the list-prompt 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 zsh/complist 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 ALWAYS_LAST_PROMPT option in
|
||
<a href="Options.html#Options">Options</a>).</p>
|
||
<p>Menu selection can be invoked directly by the widget menu-select 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 MENUSELECT 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
|
||
menu-complete, or due to one of the options MENU_COMPLETE or AUTO_MENU
|
||
being set. If MENUSELECT 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
|
||
MENUSELECT parameter should not be used (like the ZLS_COLORS and
|
||
ZLS_COLOURS parameters described above). Instead, the menu style should
|
||
be used with the select=<code>...</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 ma
|
||
from the ZLS_COLORS or ZLS_COLOURS parameter. The default value for this
|
||
is ‘7’ which forces the selected match to be highlighted using standout
|
||
mode on a vt100-compatible terminal. If neither ZLS_COLORS nor
|
||
ZLS_COLOURS is set, the same terminal control sequence as for the ‘%S’
|
||
escape in prompts is used.</p>
|
||
<p>If there are more matches than fit on the screen and the parameter
|
||
MENUPROMPT is set, its value will be shown below the matches. It
|
||
supports the same escape sequences as LISTPROMPT, 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 MENUSCROLL 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 ‘0’ (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 ZLS_COLORS, ZLS_COLOURS and LISTPROMPT parameters, neither
|
||
MENUPROMPT nor MENUSCROLL should be set directly when using the shell
|
||
function based completion system. Instead, the select-prompt and
|
||
select-scroll 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 -n option of the compadd 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 hi and du capabilities in the ZLS_COLORS and
|
||
ZLS_COLOURS 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>
|
||
<p>accept-line, accept-search<br />
|
||
accept the current match and leave menu selection (but do not cause the
|
||
command line to be accepted)</p>
|
||
<p>send-break<br />
|
||
leaves menu selection and restores the previous contents of the command
|
||
line</p>
|
||
<p>redisplay, clear-screen<br />
|
||
execute their normal function without leaving menu selection</p>
|
||
<p>accept-and-hold, accept-and-menu-complete<br />
|
||
accept the currently inserted match and continue selection allowing to
|
||
select the next match to insert into the line</p>
|
||
<p>accept-and-infer-next-history<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 undo 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>
|
||
<p>undo<br />
|
||
removes matches inserted during the menu selection by one of the three
|
||
functions before</p>
|
||
<p>down-history, down-line-or-history<br />
|
||
vi-down-line-or-history, down-line-or-search<br />
|
||
moves the mark one line down</p>
|
||
<p>up-history, up-line-or-history<br />
|
||
vi-up-line-or-history, up-line-or-search<br />
|
||
moves the mark one line up</p>
|
||
<p>forward-char, vi-forward-char<br />
|
||
moves the mark one column right</p>
|
||
<p>backward-char, vi-backward-char<br />
|
||
moves the mark one column left</p>
|
||
<p>forward-word, vi-forward-word<br />
|
||
vi-forward-word-end, emacs-forward-word<br />
|
||
moves the mark one screenful down</p>
|
||
<p>backward-word, vi-backward-word, emacs-backward-word<br />
|
||
moves the mark one screenful up</p>
|
||
<p>vi-forward-blank-word, vi-forward-blank-word-end<br />
|
||
moves the mark to the first line of the next group of matches</p>
|
||
<p>vi-backward-blank-word<br />
|
||
moves the mark to the last line of the previous group of matches</p>
|
||
<p>beginning-of-history<br />
|
||
moves the mark to the first line</p>
|
||
<p>end-of-history<br />
|
||
moves the mark to the last line</p>
|
||
<p>beginning-of-buffer-or-history, beginning-of-line<br />
|
||
beginning-of-line-hist, vi-beginning-of-line<br />
|
||
moves the mark to the leftmost column</p>
|
||
<p>end-of-buffer-or-history, end-of-line<br />
|
||
end-of-line-hist, vi-end-of-line<br />
|
||
moves the mark to the rightmost column</p>
|
||
<p>complete-word, menu-complete, expand-or-complete<br />
|
||
expand-or-complete-prefix, menu-expand-or-complete<br />
|
||
moves the mark to the next match</p>
|
||
<p>reverse-menu-complete<br />
|
||
moves the mark to the previous match</p>
|
||
<p>vi-insert<br />
|
||
this toggles between normal and interactive mode; in interactive mode
|
||
the keys bound to self-insert and self-insert-unmeta 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 undo and
|
||
backward-delete-char go back to the previous set of matches</p>
|
||
<p>history-incremental-search-forward<br />
|
||
history-incremental-search-backward<br />
|
||
this starts incremental searches in the list of completions displayed;
|
||
in this mode, accept-line only leaves incremental search, going back to
|
||
the normal menu selection mode</p>
|
||
<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 ‘.’ in front. For example, the widget
|
||
‘.accept-line’ has the effect of leaving menu selection and accepting
|
||
the entire command line.</p>
|
||
<p>During this selection the widget uses the keymap menuselect. Any key
|
||
that is not defined in this keymap or that is bound to undefined-key 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 menuselect
|
||
keymap can be modified directly using the bindkey 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-zsh">bindkey -M menuselect '^M' send-break
|
||
</code></pre>
|
||
</div>
|
||
<p>after loading the zsh/complist 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 zsh/computil 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
|
||
compquote 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>comparguments</p>
|
||
<p>This is used by the _arguments function to do the argument and command
|
||
line parsing. Like compdescribe it has an option -i 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>compdescribe</p>
|
||
<p>This is used by the _describe 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 -i or -I 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 _describe itself.</p>
|
||
<p>Once compdescribe has been called with either the -i or the -I option,
|
||
it can be repeatedly called with the -g option and the names of four
|
||
parameters as its arguments. This will step through the different sets
|
||
of matches and store the value of compstate[list] in the first scalar,
|
||
the options for compadd 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 compadd to
|
||
register the matches with the completion code.</p>
|
||
<p><span id="index-compfiles"></span></p>
|
||
<p>compfiles</p>
|
||
<p>Used by the _path_files function to optimize complex recursive filename
|
||
generation (globbing). It does three things. With the -p and -P 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 -i
|
||
option does the directory tests for the ignore-parents style and the -r
|
||
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>compgroups</p>
|
||
<p>Used by the _tags function to implement the internals of the
|
||
group-order 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>compquote [ -p ] <code>names</code> ...</p>
|
||
<p>There may be reasons to write completion functions that have to add the
|
||
matches using the -Q option to compadd and perform quoting themselves.
|
||
Instead of interpreting the first character of the all_quotes key of the
|
||
compstate special association and using the q 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 -p 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>comptags</p>
|
||
<p>comptry</p>
|
||
<p>These implement the internals of the tags mechanism.</p>
|
||
<p><span id="index-compvalues"></span></p>
|
||
<p>compvalues</p>
|
||
<p>Like comparguments, but for the _values 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 zsh/curses 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>zcurses init</p>
|
||
<p>zcurses end</p>
|
||
<p>zcurses addwin <code>targetwin</code> <code>nlines</code> <code>ncols</code> <code>begin_y</code> <code>begin_x</code> [
|
||
<code>parentwin</code> ]</p>
|
||
<p>zcurses delwin <code>targetwin</code></p>
|
||
<p>zcurses refresh [ <code>targetwin</code> ... ]</p>
|
||
<p>zcurses touch <code>targetwin</code> ...</p>
|
||
<p>zcurses move <code>targetwin</code> <code>new_y</code> <code>new_x</code></p>
|
||
<p>zcurses clear <code>targetwin</code> [ redraw | eol | bot ]</p>
|
||
<p>zcurses position <code>targetwin</code> <code>array</code></p>
|
||
<p>zcurses char <code>targetwin</code> <code>character</code></p>
|
||
<p>zcurses string <code>targetwin</code> <code>string</code></p>
|
||
<p>zcurses border <code>targetwin</code> <code>border</code></p>
|
||
<p>zcurses attr <code>targetwin</code> [ [+|-]<code>attribute</code> | <code>fg_col</code>/<code>bg_col</code> ]
|
||
[...]</p>
|
||
<p>zcurses bg <code>targetwin</code> [ [+|-]<code>attribute</code> | <code>fg_col</code>/<code>bg_col</code> |
|
||
@<code>char</code> ] [...]</p>
|
||
<p>zcurses scroll <code>targetwin</code> [ on | off | [+|-]<code>lines</code> ]</p>
|
||
<p>zcurses input <code>targetwin</code> [ <code>param</code> [ <code>kparam</code> [ <code>mparam</code> ] ] ]</p>
|
||
<p>zcurses mouse [ delay <code>num</code> | [+|-]motion ]</p>
|
||
<p>zcurses timeout <code>targetwin</code> <code>intval</code></p>
|
||
<p>zcurses querychar <code>targetwin</code> [ <code>param</code> ]</p>
|
||
<p>zcurses resize <code>height</code> <code>width</code> [ endwin | nosave | endwin_nosave ]</p>
|
||
<p>Manipulate curses windows. All uses of this command should be bracketed
|
||
by ‘zcurses init’ to initialise use of curses, and ‘zcurses end’ to end
|
||
it; omitting ‘zcurses end’ can cause the terminal to be in an unwanted
|
||
state.</p>
|
||
<p>The subcommand addwin 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 addwin 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 delwin to delete a window created with addwin. Note
|
||
that end does <em>not</em> implicitly delete windows, and that delwin does not
|
||
erase the screen image of the window.</p>
|
||
<p>The window corresponding to the full visible screen is called stdscr; it
|
||
always exists after ‘zcurses init’ and cannot be delete with delwin.</p>
|
||
<p>The subcommand refresh will refresh window <code>targetwin</code>; this is
|
||
necessary to make any pending changes (such as characters you have
|
||
prepared for output with char) visible on the screen. refresh 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 touch marks the <code>targetwin</code>s listed as changed. This is
|
||
necessary before refreshing windows if a window that was in front of
|
||
another window (which may be stdscr) is deleted.</p>
|
||
<p>The subcommand move moves the cursor position in <code>targetwin</code> to new
|
||
coordinates <code>new_y</code> and <code>new_x</code>. Note that the subcommand string (but
|
||
not the subcommand char) advances the cursor position over the
|
||
characters added.</p>
|
||
<p>The subcommand clear erases the contents of <code>targetwin</code>. One (and no
|
||
more than one) of three options may be specified. With the option
|
||
redraw, in addition the next refresh of <code>targetwin</code> will cause the
|
||
screen to be cleared and repainted. With the option eol, <code>targetwin</code> is
|
||
only cleared to the end of the current cursor line. With the option bot,
|
||
<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 position writes various positions associated with
|
||
<code>targetwin</code> into the array named <code>array</code>. These are, in order:</p>
|
||
<p>-<br />
|
||
The y and x coordinates of the cursor relative to the top left of
|
||
<code>targetwin</code></p>
|
||
<p>-<br />
|
||
The y and x coordinates of the top left of <code>targetwin</code> on the screen</p>
|
||
<p>-<br />
|
||
The size of <code>targetwin</code> in y and x dimensions.</p>
|
||
<p>Outputting characters and strings are achieved by char and string
|
||
respectively.</p>
|
||
<p>To draw a border around window <code>targetwin</code>, use border. 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 attr 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 + to set or a -
|
||
to unset that attribute; + is assumed if absent. The attributes
|
||
supported are blink, bold, dim, reverse, standout, and underline.</p>
|
||
<p>Each <code>fg_col</code>/<code>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
|
||
default is sometimes available (in particular if the library is
|
||
ncurses), specifying the foreground or background color with which the
|
||
terminal started. The color pair default/default is always available. To
|
||
use more than the 8 named colors (red, green, etc.) construct the
|
||
<code>fg_col</code>/<code>bg_col</code> pairs where <code>fg_col</code> and <code>bg_col</code> are decimal
|
||
integers, e.g 128/200. The maximum color value is 254 if the terminal
|
||
supports 256 colors.</p>
|
||
<p>bg 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 attr, 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 scroll can be used with on or off 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 off it is temporarily turned on to
|
||
allow the window to be scrolled.</p>
|
||
<p>The subcommand input 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 REPLY.</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 curses.h or ncurses.h with the prefix ‘KEY_’
|
||
removed; see also the description of the parameter zcurses_keycodes
|
||
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, input 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 ‘zcurses mouse’ 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 MOUSE, and <code>mparam</code> is set to an
|
||
array consisting of the following elements:</p>
|
||
<p>-<br />
|
||
An identifier to discriminate different input devices; this is only
|
||
rarely useful.</p>
|
||
<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>
|
||
<p>-<br />
|
||
Any events that occurred as separate items; usually there will be just
|
||
one. An event consists of PRESSED, RELEASED, CLICKED, DOUBLE_CLICKED or
|
||
TRIPLE_CLICKED followed immediately (in the same element) by the number
|
||
of the button.</p>
|
||
<p>-<br />
|
||
If the shift key was pressed, the string SHIFT.</p>
|
||
<p>-<br />
|
||
If the control key was pressed, the string CTRL.</p>
|
||
<p>-<br />
|
||
If the alt key was pressed, the string ALT.</p>
|
||
<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 mouse can be used to configure the use of the mouse.
|
||
There is no window argument; mouse options are global. ‘zcurses mouse’
|
||
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. delay <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. motion proceeded by an optional ‘+’ (the default)
|
||
or - 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 timeout specifies a timeout value for input from
|
||
<code>targetwin</code>. If <code>intval</code> is negative, ‘zcurses input’ waits indefinitely
|
||
for a character to be typed; this is the default. If <code>intval</code> is zero,
|
||
‘zcurses input’ 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, ‘zcurses input’ 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 querychar 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 reply. 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</code>/<code>bg_col</code> notation, or 0
|
||
if color is not supported. Any attributes other than color that apply to
|
||
the character, as set with the subcommand attr, appear as additional
|
||
elements.</p>
|
||
<p>The subcommand resize resizes stdscr and all windows to given dimensions
|
||
(windows that stick out from the new dimensions are resized down). The
|
||
underlying curses extension (resize_term call) can be unavailable. To
|
||
verify, zeroes can be used for <code>height</code> and <code>width</code>. If the result of
|
||
the subcommand is 0, resize_term is available (2 otherwise). Tests show
|
||
that resizing can be normally accomplished by calling zcurses end and
|
||
zcurses refresh. The resize subcommand is provided for versatility.
|
||
Multiple system configurations have been checked and zcurses end and
|
||
zcurses refresh are still needed for correct terminal state after
|
||
resize. To invoke them with resize, use <code>endwin</code> argument. Using
|
||
<code>nosave</code> argument will cause new terminal state to not be saved
|
||
internally by zcurses. This is also provided for versatility and should
|
||
normally be not needed.</p>
|
||
<hr />
|
||
<p><span id="Parameters-2"></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>ZCURSES_COLORS</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 zcurses init is run.</p>
|
||
<p><span id="index-ZCURSES_005fCOLOR_005fPAIRS"></span></p>
|
||
<p>ZCURSES_COLOR_PAIRS</p>
|
||
<p>Readonly integer. The maximum number of color pairs <code>fg_col</code>/<code>bg_col</code>
|
||
that may be defined in ‘zcurses attr’ 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 zcurses init is run.</p>
|
||
<p><span id="index-zcurses_005fattrs"></span></p>
|
||
<p>zcurses_attrs</p>
|
||
<p>Readonly array. The attributes supported by zsh/curses; available as
|
||
soon as the module is loaded.</p>
|
||
<p><span id="index-zcurses_005fcolors"></span></p>
|
||
<p>zcurses_colors</p>
|
||
<p>Readonly array. The colors supported by zsh/curses; available as soon as
|
||
the module is loaded.</p>
|
||
<p><span id="index-zcurses_005fkeycodes"></span></p>
|
||
<p>zcurses_keycodes</p>
|
||
<p>Readonly array. The values that may be returned in the second parameter
|
||
supplied to ‘zcurses input’ in the order in which they are defined
|
||
internally by curses. Not all function keys are listed, only F0; curses
|
||
reserves space for F0 up to F63.</p>
|
||
<p><span id="index-zcurses_005fwindows"></span></p>
|
||
<p>zcurses_windows</p>
|
||
<p>Readonly array. The current list of windows, i.e. all windows that have
|
||
been created with ‘zcurses addwin’ and not removed with ‘zcurses
|
||
delwin’.</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 zsh/datetime module makes available one builtin command:</p>
|
||
<p><span id="index-strftime"></span> <span
|
||
id="index-date-string_002c-printing"></span></p>
|
||
<p>strftime [ -s <code>scalar</code> | -n ] <code>format</code> [ <code>epochtime</code> [
|
||
<code>nanoseconds</code> ] ]</p>
|
||
<p>strftime -r [ -q ] [ -s <code>scalar</code> | -n ] <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 strftime(3) for
|
||
details. The zsh extensions described in <a href="Prompt-Expansion.html#Prompt-Expansion">Prompt
|
||
Expansion</a> are also available.</p>
|
||
<p>-n<br />
|
||
Suppress printing a newline after the formatted string.</p>
|
||
<p>-q<br />
|
||
Run quietly; suppress printing of all error messages described below.
|
||
Errors for invalid <code>epochtime</code> values are always printed.</p>
|
||
<p>-r<br />
|
||
With the option -r (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
|
||
strptime; see 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 strftime any timezone in the <code>timestring</code> is
|
||
ignored and the local timezone declared by the TZ 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 strptime or mktime is not available,
|
||
status 2 is returned and an error message is printed.</p>
|
||
<p>-s <code>scalar</code><br />
|
||
Assign the date string (or epoch time in seconds if -r is given) to
|
||
<code>scalar</code> instead of printing it.</p>
|
||
<p>Note that depending on the system’s declared integral time type,
|
||
strftime may produce incorrect results for epoch times greater than
|
||
2147483647 which corresponds to 2038-01-19 03:14:07 +0000.</p>
|
||
<p>The zsh/datetime module makes available several parameters; all are
|
||
readonly:</p>
|
||
<p><span id="index-EPOCHREALTIME"></span></p>
|
||
<p>EPOCHREALTIME</p>
|
||
<p>A floating point value representing the number of seconds since the
|
||
epoch. The notional accuracy is to nanoseconds if the clock_gettime 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>EPOCHSECONDS</p>
|
||
<p>An integer value representing the number of seconds since the epoch.</p>
|
||
<p><span id="index-epochtime"></span></p>
|
||
<p>epochtime</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-zsh">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 zsh/db/gdbm 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 ztie 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>ztie -d db/gdbm -f <code>filename</code> [ -r ] <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-zsh">local -A sampledb
|
||
ztie -d db/gdbm -f sample.gdbm sampledb
|
||
</code></pre>
|
||
</div>
|
||
<p>The -r option opens the database file for reading only, creating a
|
||
parameter with the readonly attribute. Without this option, using ‘ztie’
|
||
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 ‘typeset -r <code>arrayname</code>’ works as
|
||
expected.</p>
|
||
<p><span id="index-zuntie"></span> <span
|
||
id="index-database-tied-array_002c-destroying"></span></p>
|
||
<p>zuntie [ -u ] <code>arrayname</code> ...</p>
|
||
<p>Close the GDBM database associated with each <code>arrayname</code> and then unset
|
||
the parameter. The -u option forces an unset of parameters made readonly
|
||
with ‘ztie -r’.</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 ‘ztie -r’ is to use ‘zuntie -u’.</p>
|
||
<p><span id="index-zgdbmpath"></span> <span
|
||
id="index-database-file-path_002c-reading"></span></p>
|
||
<p>zgdbmpath <code>parametername</code></p>
|
||
<p>Put path to database file assigned to <code>parametername</code> into REPLY scalar.</p>
|
||
<p><span id="index-zgdbm_005ftied"></span> <span
|
||
id="index-database-tied-arrays_002c-enumerating"></span></p>
|
||
<p>zgdbm_tied</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 zsh/deltochar module makes available two ZLE functions:</p>
|
||
<p><span id="index-delete_002dto_002dchar"></span></p>
|
||
<p>delete-to-char</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>zap-to-char</p>
|
||
<p>This behaves like delete-to-char, 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 zsh/example 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>example [ -flags ] [ <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 zsh/files 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 zf_ 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-zsh">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>chgrp [ -hRs ] <code>group</code> <code>filename</code> ...</p>
|
||
<p>Changes group of files specified. This is equivalent to chown with a
|
||
<code>user-spec</code> argument of ‘:<code>group</code>’.</p>
|
||
<p><span id="index-chmod"></span></p>
|
||
<p>chmod [ -Rs ] <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 -R option causes chmod 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 -s option is a zsh extension to chmod functionality. It enables
|
||
paranoid behaviour, intended to avoid security problems involving a
|
||
chmod being tricked into affecting files other than the ones intended.
|
||
It will refuse to follow symbolic links, so that (for example) ‘‘chmod
|
||
600 /tmp/foo/passwd’’ can’t accidentally chmod /etc/passwd if /tmp/foo
|
||
happens to be a link to /etc. 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 /usr as a result of directories being
|
||
moved up the tree.</p>
|
||
<p><span id="index-chown"></span></p>
|
||
<p>chown [ -hRs ] <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>
|
||
<p><code>user</code><br />
|
||
change owner to <code>user</code>; do not change group</p>
|
||
<p><code>user</code>::<br />
|
||
change owner to <code>user</code>; do not change group</p>
|
||
<p><code>user</code>:<br />
|
||
change owner to <code>user</code>; change group to <code>user</code>’s primary group</p>
|
||
<p><code>user</code>:<code>group</code><br />
|
||
change owner to <code>user</code>; change group to <code>group</code></p>
|
||
<p>:<code>group</code><br />
|
||
do not change owner; change group to <code>group</code></p>
|
||
<p>In each case, the ‘:’ may instead be a ‘.’. The rule is that if there is
|
||
a ‘:’ then the separator is ‘:’, otherwise if there is a ‘.’ then the
|
||
separator is ‘.’, 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 -h option causes chown to set the
|
||
ownership of the link instead of its target.</p>
|
||
<p>The -R option causes chown 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 -s option is a zsh extension to chown functionality. It enables
|
||
paranoid behaviour, intended to avoid security problems involving a
|
||
chown being tricked into affecting files other than the ones intended.
|
||
It will refuse to follow symbolic links, so that (for example) ‘‘chown
|
||
luser /tmp/foo/passwd’’ can’t accidentally chown /etc/passwd if /tmp/foo
|
||
happens to be a link to /etc. 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 /usr as a result of directories being
|
||
moved up the tree.</p>
|
||
<p><span id="index-ln"></span></p>
|
||
<p>ln [ -dfhins ] <code>filename</code> <code>dest</code></p>
|
||
<p>ln [ -dfhins ] <code>filename</code> ... <code>dir</code></p>
|
||
<p>Creates hard (or, with -s, 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, ln will not attempt to create hard links to directories. This
|
||
check can be overridden using the -d 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 -i option
|
||
causes the user to be queried about replacing existing files. The -f
|
||
option causes existing files to be silently deleted, without querying.
|
||
-f takes precedence.</p>
|
||
<p>The -h and -n 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 -sf 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>mkdir [ -p ] [ -m <code>mode</code> ] <code>dir</code> ...</p>
|
||
<p>Creates directories. With the -p option, non-existing parent directories
|
||
are first created if necessary, and there will be no complaint if the
|
||
directory already exists. The -m option can be used to specify (in
|
||
octal) a set of file permissions for the created directories, otherwise
|
||
mode 777 modified by the current umask (see umask(2)) is used.</p>
|
||
<p><span id="index-mv"></span></p>
|
||
<p>mv [ -fi ] <code>filename</code> <code>dest</code></p>
|
||
<p>mv [ -fi ] <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 -i option causes the user to be queried about replacing any existing
|
||
files. The -f option causes any existing files to be silently deleted,
|
||
without querying. -f takes precedence.</p>
|
||
<p>Note that this mv will not move files across devices. Historical
|
||
versions of mv, when actual renaming is impossible, fall back on copying
|
||
and removing files; if this behaviour is desired, use cp and rm
|
||
manually. This may change in a future version.</p>
|
||
<p><span id="index-rm"></span></p>
|
||
<p>rm [ -dfiRrs ] <code>filename</code> ...</p>
|
||
<p>Removes files and directories specified.</p>
|
||
<p>Normally, rm will not remove directories (except with the -R or -r
|
||
options). The -d option causes rm to try removing directories with
|
||
unlink (see unlink(2)), the same method used for files. Typically only
|
||
the super-user can actually succeed in unlinking directories in this
|
||
way. -d takes precedence over -R and -r.</p>
|
||
<p>By default, the user will be queried before removing any file removed.
|
||
The -i option causes the user to be queried about removing any files.
|
||
The -f option causes files to be silently deleted, without querying, and
|
||
suppresses all error indications. -f takes precedence.</p>
|
||
<p>The -R and -r options cause rm to recursively descend into directories,
|
||
deleting all files in the directory before removing the directory with
|
||
the rmdir system call (see rmdir(2)).</p>
|
||
<p>The -s option is a zsh extension to rm functionality. It enables
|
||
paranoid behaviour, intended to avoid common security problems involving
|
||
a root-run rm being tricked into removing files other than the ones
|
||
intended. It will refuse to follow symbolic links, so that (for example)
|
||
‘‘rm /tmp/foo/passwd’’ can’t accidentally remove /etc/passwd if /tmp/foo
|
||
happens to be a link to /etc. 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 /usr as a result of directories
|
||
being moved up the tree.</p>
|
||
<p><span id="index-rmdir"></span></p>
|
||
<p>rmdir <code>dir</code> ...</p>
|
||
<p>Removes empty directories specified.</p>
|
||
<p><span id="index-sync"></span></p>
|
||
<p>sync</p>
|
||
<p>Calls the system call of the same name (see 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 zsh/langinfo module makes available one parameter:</p>
|
||
<p><span id="index-langinfo"></span></p>
|
||
<p>langinfo</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>CODESET, D_T_FMT, D_FMT, T_FMT, RADIXCHAR, THOUSEP, YESEXPR, NOEXPR,
|
||
CRNCYSTR, ABDAY_{1..7}, DAY_{1..7}, ABMON_{1..12}, MON_{1..12},
|
||
T_FMT_AMPM, AM_STR, PM_STR, ERA, ERA_D_FMT, ERA_D_T_FMT, ERA_T_FMT,
|
||
ALT_DIGITS</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 zsh/mapfile module provides one special associative array parameter
|
||
of the same name.</p>
|
||
<p><span id="index-mapfile"></span></p>
|
||
<p>mapfile</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, ‘vared ’mapfile[myfile]’’ works as
|
||
expected, editing the file ‘myfile’.</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 ${(k)mapfile} has the same effect as the glob
|
||
operator *(D), since files beginning with a dot are not special. Care
|
||
must be taken with expressions such as rm ${(k)mapfile}, which will
|
||
delete every file in the current directory without the usual ‘rm *’
|
||
test.</p>
|
||
<p>The parameter mapfile 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</code>=("${(f@)mapfile[<code>filename</code>]}")’. The double
|
||
quotes and the ‘@’ 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</code>=("${(f@)${mapfile[<code>filename</code>]%$’\n’}}")’.</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, mapfile 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 zsh/mathfunc 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-zsh">(( 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 atan with a second
|
||
argument and the abs, int and float 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: acos,
|
||
acosh, asin, asinh, atan, atanh, cbrt, ceil, cos, cosh, erf, erfc, exp,
|
||
expm1, fabs, floor, gamma, j0, j1, lgamma, log, log10, log1p, log2,
|
||
logb, sin, sinh, sqrt, tan, tanh, y0, y1. The atan function can
|
||
optionally take a second argument, in which case it behaves like the C
|
||
function atan2. The ilogb function takes a single floating point
|
||
argument, but returns an integer.</p>
|
||
<p>The function signgam takes no arguments, and returns an integer, which
|
||
is the C variable of the same name, as described in gamma(3). Note that
|
||
it is therefore only useful immediately after a call to gamma or lgamma.
|
||
Note also that ‘signgam()’ and ‘signgam’ are distinct expressions.</p>
|
||
<p>The functions min, max, and sum are defined not in this module but in
|
||
the zmathfunc autoloadable function, described in <a href="User-Contributions.html#Mathematical-Functions">Mathematical
|
||
Functions</a>.</p>
|
||
<p>The following functions take two floating point arguments: copysign,
|
||
fmod, hypot, nextafter.</p>
|
||
<p>The following take an integer first argument and a floating point second
|
||
argument: jn, yn.</p>
|
||
<p>The following take a floating point first argument and an integer second
|
||
argument: ldexp, scalb.</p>
|
||
<p>The function abs 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 float and int convert their arguments into a
|
||
floating point or integer value (by truncation) respectively.</p>
|
||
<p>Note that the C pow function is available in ordinary math evaluation as
|
||
the ‘**’ operator and is not provided here.</p>
|
||
<p>The function rand48 is available if your system’s mathematical library
|
||
has the function erand48(3). 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 rand(3) function — this produces the same random
|
||
numbers as the next three values of $RANDOM.</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 rand48 with no argument. Subsequent calls to
|
||
rand48(<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 rand48
|
||
with no argument.</p>
|
||
<p>For example, consider</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">print $(( rand48(seed) ))
|
||
print $(( rand48() ))
|
||
print $(( rand48(seed) ))
|
||
</code></pre>
|
||
</div>
|
||
<p>Assuming $seed 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 rand() 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 rand48().</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 zsh/nearcolor 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 zsh/nearcolor 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 zsh/nearcolor module. For example, the following checks the
|
||
COLORTERM environment variable:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">[[ $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
|
||
zsh/nearcolor 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 zsh/newuser module is loaded at boot if it is available, the RCS
|
||
option is set, and the PRIVILEGED option is not set (all three are true
|
||
by default). This takes place immediately after commands in the global
|
||
zshenv file (typically /etc/zshenv), 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 $MODULE_PATH by the administrator if it is
|
||
not required.</p>
|
||
<p>On loading, the module tests if any of the start-up files .zshenv,
|
||
.zprofile, .zshrc or .zlogin exist in the directory given by the
|
||
environment variable ZDOTDIR, 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 newuser first in a sitewide directory, usually the parent directory
|
||
of the site-functions directory, and if that is not found the module
|
||
searches in a version-specific directory, usually the parent of the
|
||
functions directory containing version-specific functions. (These
|
||
directories can be configured when zsh is built using the
|
||
–enable-site-scriptdir=<code>dir</code> and –enable-scriptdir=<code>dir</code> flags to
|
||
configure, respectively; the defaults are <code>prefix</code>/share/zsh and
|
||
<code>prefix</code>/share/zsh/$ZSH_VERSION where the default <code>prefix</code> is
|
||
/usr/local.)</p>
|
||
<p>If the file newuser 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 zsh/newuser module is then unconditionally unloaded.</p>
|
||
<p>Note that it is possible to achieve exactly the same effect as the
|
||
zsh/newuser module by adding code to /etc/zshenv. 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
|
||
zsh-newuser-install. This may be invoked directly by the user even if
|
||
the zsh/newuser 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 zsh/parameter module gives access to some of the internal hash</p>
|
||
<p><span id="index-options-1"></span></p>
|
||
<p>options</p>
|
||
<p>The keys for this associative array are the names of the options that
|
||
can be set and unset using the setopt and unsetopt builtins. The value
|
||
of each key is either the string on if the option is currently set, or
|
||
the string off 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 off.</p>
|
||
<p><span id="index-commands"></span></p>
|
||
<p>commands</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 hash builtin. Unsetting a key as in ‘unset "commands[foo]"’
|
||
removes the entry for the given key from the command</p>
|
||
<p><span id="index-functions-2"></span></p>
|
||
<p>functions</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>dis_functions</p>
|
||
<p>Like functions but for disabled functions.</p>
|
||
<p><span id="index-functions_005fsource"></span></p>
|
||
<p>functions_source</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
|
||
‘functions -r’, 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 $functions.</p>
|
||
<p><span id="index-dis_005ffunctions_005fsource"></span></p>
|
||
<p>dis_functions_source</p>
|
||
<p>Like functions_source but for disabled functions.</p>
|
||
<p><span id="index-builtins"></span></p>
|
||
<p>builtins</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 ‘undefined’ for builtin commands that will
|
||
automatically be loaded from a module if invoked or ‘defined’ for
|
||
builtin commands that are already loaded.</p>
|
||
<p><span id="index-dis_005fbuiltins"></span></p>
|
||
<p>dis_builtins</p>
|
||
<p>Like builtins but for disabled builtin commands.</p>
|
||
<p><span id="index-reswords"></span></p>
|
||
<p>reswords</p>
|
||
<p>This array contains the enabled reserved words.</p>
|
||
<p><span id="index-dis_005freswords"></span></p>
|
||
<p>dis_reswords</p>
|
||
<p>Like reswords but for disabled reserved words.</p>
|
||
<p><span id="index-patchars"></span></p>
|
||
<p>patchars</p>
|
||
<p>This array contains the enabled pattern characters.</p>
|
||
<p><span id="index-dis_005fpatchars"></span></p>
|
||
<p>dis_patchars</p>
|
||
<p>Like patchars but for disabled pattern characters.</p>
|
||
<p><span id="index-aliases"></span></p>
|
||
<p>aliases</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>dis_aliases</p>
|
||
<p>Like aliases but for disabled regular aliases.</p>
|
||
<p><span id="index-galiases"></span></p>
|
||
<p>galiases</p>
|
||
<p>Like aliases, but for global aliases.</p>
|
||
<p><span id="index-dis_005fgaliases"></span></p>
|
||
<p>dis_galiases</p>
|
||
<p>Like galiases but for disabled global aliases.</p>
|
||
<p><span id="index-saliases"></span></p>
|
||
<p>saliases</p>
|
||
<p>Like raliases, but for suffix aliases.</p>
|
||
<p><span id="index-dis_005fsaliases"></span></p>
|
||
<p>dis_saliases</p>
|
||
<p>Like saliases but for disabled suffix aliases.</p>
|
||
<p><span id="index-parameters-1"></span></p>
|
||
<p>parameters</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 t 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>modules</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 ‘loaded’, ‘autoloaded’, or ‘alias:<code>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>dirstack</p>
|
||
<p>A normal array holding the elements of the directory stack. Note that
|
||
the output of the dirs builtin command includes one more directory, the
|
||
current working directory.</p>
|
||
<p><span id="index-history-2"></span></p>
|
||
<p>history</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 (${history[@]}) 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>historywords</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>jobdirs</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, ${(k)jobdirs}.
|
||
Non-numeric job references may be used when looking up a value; for
|
||
example, ${jobdirs[%+]} refers to the current job.</p>
|
||
<p>See the jobs builtin for how job information is provided in a subshell.</p>
|
||
<p><span id="index-jobtexts"></span></p>
|
||
<p>jobtexts</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
|
||
jobdirs above.</p>
|
||
<p>See the jobs builtin for how job information is provided in a subshell.</p>
|
||
<p><span id="index-jobstates"></span></p>
|
||
<p>jobstates</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</code>:<code>mark</code>:<code>pid</code>=<code>state</code>...’. The <code>job-state</code> gives
|
||
the state the whole job is currently in, one of ‘running’, ‘suspended’,
|
||
or ‘done’. The <code>mark</code> is ‘+’ for the current job, ‘-’ for the previous
|
||
job and empty otherwise. This is followed by one ‘:<code>pid</code>=<code>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
|
||
jobdirs above.</p>
|
||
<p>See the jobs builtin for how job information is provided in a subshell.</p>
|
||
<p><span id="index-nameddirs"></span></p>
|
||
<p>nameddirs</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>userdirs</p>
|
||
<p>This associative array maps user names to the pathnames of their home
|
||
directories.</p>
|
||
<p><span id="index-usergroups"></span></p>
|
||
<p>usergroups</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 id command.</p>
|
||
<p><span id="index-funcfiletrace"></span></p>
|
||
<p>funcfiletrace</p>
|
||
<p>This array contains the absolute line numbers and corresponding file
|
||
names for the point where the current function, sourced file, or (if
|
||
EVAL_LINENO is set) eval command was called. The array is of the same
|
||
length as funcsourcetrace and functrace, but differs from
|
||
funcsourcetrace in that the line and file are the point of call, not the
|
||
point of definition, and differs from functrace 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>funcsourcetrace</p>
|
||
<p>This array contains the file names and line numbers of the points where
|
||
the functions, sourced files, and (if EVAL_LINENO is set) eval commands
|
||
currently being executed were defined. The line number is the line where
|
||
the ‘function <code>name</code>’ or ‘<code>name</code> ()’ started. In the case of an
|
||
autoloaded function the line number is reported as zero. The format of
|
||
each element is <code>filename</code>:<code>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 source or ‘.’ builtins, the trace information is shown
|
||
as <code>filename</code>:<code>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 funcfiletrace
|
||
array instead.</p>
|
||
<p><span id="index-funcstack"></span></p>
|
||
<p>funcstack</p>
|
||
<p>This array contains the names of the functions, sourced files, and (if
|
||
EVAL_LINENO is set) eval commands. currently being executed. The first
|
||
element is the name of the function using the parameter.</p>
|
||
<p>The standard shell array zsh_eval_context 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 toplevel, the main
|
||
shell code being executed either interactively or from a script, which
|
||
is not present in $funcstack.</p>
|
||
<p><span id="index-functrace"></span></p>
|
||
<p>functrace</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</code>:<code>lineno</code>. Callers are also shown for sourced
|
||
files; the caller is the point where the source or ‘.’ 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 zsh/pcre module makes some commands available as builtins:</p>
|
||
<p><span id="index-pcre_005fcompile"></span></p>
|
||
<p>pcre_compile [ -aimxs ] <code>PCRE</code></p>
|
||
<p>Compiles a perl-compatible regular expression.</p>
|
||
<p>Option -a will force the pattern to be anchored. Option -i will compile
|
||
a case-insensitive pattern. Option -m will compile a multi-line pattern;
|
||
that is, ^ and $ will match newlines within the pattern. Option -x will
|
||
compile an extended pattern, wherein whitespace and # comments are
|
||
ignored. Option -s makes the dot metacharacter match all characters,
|
||
including those that indicate newline.</p>
|
||
<p><span id="index-pcre_005fstudy"></span></p>
|
||
<p>pcre_study</p>
|
||
<p>Studies the previously-compiled PCRE which may result in faster
|
||
matching.</p>
|
||
<p><span id="index-pcre_005fmatch"></span></p>
|
||
<p>pcre_match [ -v <code>var</code> ] [ -a <code>arr</code> ] [ -n <code>offset</code> ] [ -b ]
|
||
<code>string</code></p>
|
||
<p>Returns successfully if string matches the previously-compiled PCRE.</p>
|
||
<p>Upon successful match, if the expression captures substrings within
|
||
parentheses, pcre_match will set the array match to those substrings,
|
||
unless the -a option is given, in which case it will set the array
|
||
<code>arr</code>. Similarly, the variable MATCH will be set to the entire matched
|
||
portion of the string, unless the -v 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 -n option starts searching for a match from the byte
|
||
<code>offset</code> position in <code>string</code>. If the -b option is given, the variable
|
||
ZPCRE_OP 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 ZPCRE_OP 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 -n 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-zsh">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 zsh/pcre module makes available the following test condition:</p>
|
||
<p><span id="index-pcre_002dmatch"></span></p>
|
||
<p><code>expr</code> -pcre-match <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-zsh">[[ "$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 REMATCH_PCRE option is set, the =~ operator is equivalent to
|
||
-pcre-match, and the NO_CASE_MATCH option may be used. Note that
|
||
NO_CASE_MATCH never applies to the pcre_match builtin, instead use the
|
||
-i switch of pcre_compile.</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 zsh/param/private 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>private [ {+|-}AHUahlmrtux ] [ {+|-}EFLRZi [ <code>n</code> ] ] [
|
||
<code>name</code>[=<code>value</code>] ... ]</p>
|
||
<p>The private builtin accepts all the same options and arguments as local
|
||
(<a href="Shell-Builtin-Commands.html#Shell-Builtin-Commands">Shell Builtin
|
||
Commands</a>) except
|
||
for the ‘-T’ option. Tied parameters may not be made private.</p>
|
||
<p>The ‘-p’ option is presently a no-op because the state of private
|
||
parameters cannot reliably be reloaded. This also applies to printing
|
||
private parameters with ‘typeset -p’.</p>
|
||
<p>If used at the top level (outside a function scope), private creates a
|
||
normal parameter in the same manner as declare or typeset. A warning
|
||
about this is printed if WARN_CREATE_GLOBAL is set
|
||
(<a href="Options.html#Options">Options</a>). Used inside a function scope, private
|
||
creates a local parameter similar to one declared with local, except
|
||
having special properties noted below.</p>
|
||
<p>Special parameters which expose or manipulate internal shell state, such
|
||
as ARGC, argv, COLUMNS, LINES, UID, EUID, IFS, PROMPT, RANDOM, SECONDS,
|
||
etc., cannot be made private unless the ‘-h’ option is used to hide the
|
||
special meaning of the parameter. This may change in the future.</p>
|
||
<p>As with other typeset equivalents, private is both a builtin and a
|
||
reserved word, so arrays may be assigned with parenthesized word list
|
||
<code>name</code>=(<code>value</code>...) syntax. However, the reserved word ‘private’ is not
|
||
available until zsh/param/private is loaded, so care must be taken with
|
||
order of execution and parsing for function definitions which use
|
||
private. To compensate for this, the module also adds the option ‘-P’ to
|
||
the ‘local’ builtin to declare private parameters.</p>
|
||
<p>For example, this construction fails if zsh/param/private has not yet
|
||
been loaded when ‘bad_declaration’ is defined:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">bad_declaration() {
|
||
zmodload zsh/param/private
|
||
private array=( one two three )
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
<p>This construction works because local is already a keyword, and the
|
||
module is loaded before the statement is executed:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">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 autoload:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zmodload zsh/param/private
|
||
iffy_declaration() {
|
||
private array=( one two three )
|
||
}
|
||
</code></pre>
|
||
</div>
|
||
<p>The private builtin may always be used with scalar assignments and for
|
||
declarations without assignments.</p>
|
||
<p>Parameters declared with private 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. However, the
|
||
private name may not be created outside the local scope when it was
|
||
not previously declared.</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
|
||
‘typeset -S’ 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 zsh/regex module makes available the following test condition:</p>
|
||
<p><span id="index-regex_002dmatch"></span></p>
|
||
<p><code>expr</code> -regex-match <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 MATCH variable. If there are any capturing parentheses within the
|
||
regex, then the match 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-zsh">[[ alphabetical -regex-match ^a([^a]+)a([^a]+)a ]] &&
|
||
print -l $MATCH X $match
|
||
</code></pre>
|
||
</div>
|
||
<p>If the option REMATCH_PCRE is not set, then the =~ operator will
|
||
automatically load this module as needed and will invoke the
|
||
-regex-match operator.</p>
|
||
<p>If BASH_REMATCH is set, then the array BASH_REMATCH will be set instead
|
||
of MATCH and match.</p>
|
||
<p>Note that the zsh/regex module logic relies on the host system. The same
|
||
<code>expr</code> and <code>regex</code> pair could produce different results on different
|
||
platforms if a <code>regex</code> with non-standard syntax is given.</p>
|
||
<p>For example, no syntax for matching a word boundary is defined in the
|
||
POSIX extended regular expression standard. GNU libc and BSD libc both
|
||
provide such syntaxes as extensions (\b and [[:<:]]/[[:>:]]
|
||
respectively), but neither of these syntaxes is supported by both of
|
||
these implementations.</p>
|
||
<p>Refer to the regcomp(3) and re_format(7) manual pages on your system for
|
||
locally-supported syntax.</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 zsh/sched 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>sched [-o] [+]<code>hh</code>:<code>mm</code>[:<code>ss</code>] <code>command</code> ...</p>
|
||
<p>sched [-o] [+]<code>seconds</code> <code>command</code> ...</p>
|
||
<p>sched [ -<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 zsh/datetime 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 -o 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 -o 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
|
||
‘zle’ command with no arguments to test whether the editor is active,
|
||
and if it is, then use ‘zle <code>widget</code>’ to access the editor via the named
|
||
<code>widget</code>.</p>
|
||
<p>The sched 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 ‘zmodload -F zsh/sched b:sched’.</p>
|
||
<p><span id="index-zsh_005fscheduled_005fevents"></span></p>
|
||
<p>zsh_scheduled_events</p>
|
||
<p>A readonly array corresponding to the events scheduled by the sched
|
||
builtin. The indices of the array correspond to the numbers shown when
|
||
sched is run with no arguments (provided that the KSH_ARRAYS 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 ‘-’ otherwise), followed by a colon,
|
||
followed by the command to be executed.</p>
|
||
<p>The sched 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 zsh/net/socket 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>zsocket [ -altv ] [ -d <code>fd</code> ] [ <code>args</code> ]</p>
|
||
<p>zsocket 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>
|
||
<p>zsocket [ -v ] [ -d <code>fd</code> ] <code>filename</code><br />
|
||
Open a new Unix domain connection to <code>filename</code>. The shell parameter
|
||
REPLY will be set to the file descriptor associated with that
|
||
connection. Currently, only stream connections are supported.</p>
|
||
<p>If -d 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 -v.</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-zsh">exec {REPLY}>&-
|
||
</code></pre>
|
||
</div>
|
||
<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>
|
||
<p>zsocket -l [ -v ] [ -d <code>fd</code> ] <code>filename</code><br />
|
||
zsocket -l will open a socket listening on <code>filename</code>. The shell
|
||
parameter REPLY will be set to the file descriptor associated with that
|
||
listener. The file descriptor remains open in subshells</p>
|
||
<p>If -d 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 -v.</p>
|
||
<p>zsocket -a [ -tv ] [ -d <code>targetfd</code> ] <code>listenfd</code><br />
|
||
zsocket -a will accept an incoming connection to the socket associated
|
||
with <code>listenfd</code>. The shell parameter REPLY will be set to the file
|
||
descriptor associated with the inbound connection. The file descriptor
|
||
remains open in subshells</p>
|
||
<p>If -d is specified, its argument will be taken as the target file
|
||
descriptor for the connection.</p>
|
||
<p>If -t is specified, zsocket will return if no incoming connection is
|
||
pending. Otherwise it will wait for one.</p>
|
||
<p>In order to elicit more verbose output, use -v.</p>
|
||
<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 zsh/stat 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>zstat [ -gnNolLtTrs ] [ -f <code>fd</code> ] [ -H <code>hash</code> ] [ -A <code>array</code> ]
|
||
[ -F <code>fmt</code> ]</p>
|
||
<p> [ +<code>element</code> ] [ <code>file</code> ... ]</p>
|
||
<p>stat <code>...</code></p>
|
||
<p>The command acts as a front end to the stat system call (see stat(2)).
|
||
The same command is provided with two names; as the name stat is often
|
||
used by an external command it is recommended that only the zstat form
|
||
of the command is used. This can be arranged by loading the module with
|
||
the command ‘zmodload -F zsh/stat b:zstat’.</p>
|
||
<p>If the stat call fails, the appropriate system error message printed and
|
||
status 1 is returned. The fields of struct stat give information about
|
||
the files provided as arguments to the command. In addition to those
|
||
available from the stat call, an extra element ‘link’ is provided. These
|
||
elements are:</p>
|
||
<p>device<br />
|
||
The number of the device on which the file resides.</p>
|
||
<p>inode<br />
|
||
The unique number of the file on this device (‘<em>inode</em>’ number).</p>
|
||
<p>mode<br />
|
||
The mode of the file; that is, the file’s type and access permissions.
|
||
With the -s option, this will be returned as a string corresponding to
|
||
the first column in the display of the ls -l command.</p>
|
||
<p>nlink<br />
|
||
The number of hard links to the file.</p>
|
||
<p>uid<br />
|
||
The user ID of the owner of the file. With the -s option, this is
|
||
displayed as a user name.</p>
|
||
<p>gid<br />
|
||
The group ID of the file. With the -s option, this is displayed as a
|
||
group name.</p>
|
||
<p>rdev<br />
|
||
The raw device number. This is only useful for special devices.</p>
|
||
<p>size<br />
|
||
The size of the file in bytes.</p>
|
||
<p>atime<br />
|
||
mtime<br />
|
||
ctime<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 -s option, these are printed as strings for the
|
||
local time zone; the format can be altered with the -F option, and with
|
||
the -g option the times are in GMT.</p>
|
||
<p>blksize<br />
|
||
The number of bytes in one allocation block on the device on which the
|
||
file resides.</p>
|
||
<p>block<br />
|
||
The number of disk blocks used by the file.</p>
|
||
<p>link<br />
|
||
If the file is a link and the -L option is in effect, this contains the
|
||
name of the file linked to, otherwise it is empty. Note that if this
|
||
element is selected (‘‘zstat +link’’) then the -L option is
|
||
automatically used.</p>
|
||
<p>A particular element may be selected by including its name preceded by a
|
||
‘+’ 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>
|
||
<p>-A <code>array</code><br />
|
||
Instead of displaying the results on standard output, assign them to an
|
||
<code>array</code>, one struct stat 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 -t or -n options were given,
|
||
respectively. If -t is given, the element name appears as a prefix to
|
||
the appropriate array element; if -n is given, the file name appears as
|
||
a separate array element preceding all the others. Other formatting
|
||
options are respected.</p>
|
||
<p>-H <code>hash</code><br />
|
||
Similar to -A, but instead assign the values to <code>hash</code>. The keys are the
|
||
elements listed above. If the -n option is provided then the name of the
|
||
file is included in the hash with key name.</p>
|
||
<p>-f <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>
|
||
<p>-F <code>fmt</code><br />
|
||
Supplies a strftime (see 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>.
|
||
In particular, -F %s.%N can be used to show timestamps with nanosecond
|
||
precision if supported by the system. The -s option is implied.</p>
|
||
<p>-g<br />
|
||
Show the time elements in the GMT time zone. The -s option is implied.</p>
|
||
<p>-l<br />
|
||
List the names of the type elements (to standard output or an array as
|
||
appropriate) and return immediately; arguments, and options other than
|
||
-A, are ignored.</p>
|
||
<p>-L<br />
|
||
Perform an lstat (see lstat(2)) rather than a stat 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
|
||
link element useful. It’s important to note that this is the exact
|
||
opposite from ls(1), etc.</p>
|
||
<p>-n<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>
|
||
<p>-N<br />
|
||
Never show the names of files.</p>
|
||
<p>-o<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 -r and -s
|
||
options, nor whether a mode is shown at all.</p>
|
||
<p>-r<br />
|
||
Print raw data (the default format) alongside string data (the -s
|
||
format); the string data appears in parentheses after the raw data.</p>
|
||
<p>-s<br />
|
||
Print mode, uid, gid and the three time elements as strings instead of
|
||
numbers. In each case the format is like that of ls -l.</p>
|
||
<p>-t<br />
|
||
Always show the type names for the elements of struct stat. Usually
|
||
these are only shown when output is to standard output and no individual
|
||
element has been selected.</p>
|
||
<p>-T<br />
|
||
Never show the type names of the struct stat elements.</p>
|
||
<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 zsh/system 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>syserror [ -e <code>errvar</code> ] [ -p <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 ENOENT, may
|
||
be used. The set of names is the same as the contents of the array
|
||
errnos, 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>sysopen [ -arw ] [ -m <code>permissions</code> ] [ -o <code>options</code> ]</p>
|
||
<p> -u <code>fd</code> <code>file</code></p>
|
||
<p>This command opens a file. The -r, -w and -a flags indicate whether the
|
||
file should be opened for reading, writing and appending, respectively.
|
||
The -m option allows the initial permissions to use when creating a file
|
||
to be specified in octal form. The file descriptor is specified with -u.
|
||
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 -o 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>
|
||
<p>cloexec<br />
|
||
mark file to be closed when other programs are executed (else the file
|
||
descriptor remains open in subshells and forked external</p>
|
||
<p>create<br />
|
||
creat<br />
|
||
create file if it does not exist</p>
|
||
<p>excl<br />
|
||
create file, error if it already exists</p>
|
||
<p>noatime<br />
|
||
suppress updating of the file atime</p>
|
||
<p>nofollow<br />
|
||
fail if <code>file</code> is a symbolic link</p>
|
||
<p>nonblock<br />
|
||
the file is opened in nonblocking mode</p>
|
||
<p>sync<br />
|
||
request that writes wait until data has been physically written</p>
|
||
<p>truncate<br />
|
||
trunc<br />
|
||
truncate file to size 0</p>
|
||
<p>To close the file, use one of the following:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">exec {fd}<&-
|
||
exec {fd}>&-
|
||
</code></pre>
|
||
</div>
|
||
<p><span id="index-sysread"></span></p>
|
||
<p>sysread [ -c <code>countvar</code> ] [ -i <code>infd</code> ] [ -o <code>outfd</code> ]</p>
|
||
<p> [ -s <code>bufsize</code> ] [ -t <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 REPLY
|
||
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 poll system
|
||
call if available, otherwise the select 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 EINTR 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 EINTR (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>
|
||
<p>0<br />
|
||
At least one byte of data was successfully read and, if appropriate,
|
||
written.</p>
|
||
<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>
|
||
<p>2<br />
|
||
There was an error on the read, or on polling the input file descriptor
|
||
for a timeout. The parameter ERRNO gives the error.</p>
|
||
<p>3<br />
|
||
Data were successfully read, but there was an error writing them to
|
||
<code>outfd</code>. The parameter ERRNO gives the error.</p>
|
||
<p>4<br />
|
||
The attempt to read timed out. Note this does not set ERRNO as this is
|
||
not a system error.</p>
|
||
<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>
|
||
<p>sysseek [ -u <code>fd</code> ] [ -w start|end|current ] <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 -u option allows the file descriptor
|
||
to be specified. By default the offset is specified relative to the
|
||
start or the file but, with the -w option, it is possible to specify
|
||
that the offset should be relative to the current position or the end of
|
||
the file.</p>
|
||
<p>syswrite [ -c <code>countvar</code> ] [ -o <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 write 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 EINTR (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 EAGAIN
|
||
(on some systems, EWOULDBLOCK) 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 ERRNO will reflect the error
|
||
that occurred.</p>
|
||
<p>zsystem flock [ -t <code>timeout</code> ] [ -i <code>interval</code> ] [ -f <code>var</code> ]
|
||
[-er] <code>file</code></p>
|
||
<p>zsystem flock -u <code>fd_expr</code></p>
|
||
<p>The builtin zsystem’s subcommand flock performs advisory file locking
|
||
(via the 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 print builtin with the -u 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. ‘(print
|
||
message) >> <code>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 ‘-f <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 ‘exec {<code>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 -t <code>timeout</code> specifies a timeout for the lock in seconds;
|
||
fractional seconds are allowed. During this period, the shell will
|
||
attempt to lock the file every <code>interval</code> seconds if the -i <code>interval</code>
|
||
option is given, otherwise once a second. (This <code>interval</code> is shortened
|
||
before the last attempt if needed, so that the shell waits only until
|
||
the <code>timeout</code> and not longer.) If the attempt times out, status 2 is
|
||
returned.</p>
|
||
<p>(Note: <code>timeout</code> is limited to 2^30-1 seconds (about 34 years), and
|
||
<code>interval</code> to 0.999 * LONG_MAX microseconds (only about 35 minutes on
|
||
32-bit systems).)</p>
|
||
<p>If the option -e is given, the file descriptor for the lock is preserved
|
||
when the shell uses exec to start a new process; otherwise it is closed
|
||
at that point and the lock released.</p>
|
||
<p>If the option -r is given, the lock is only for reading, otherwise it is
|
||
for reading and writing. The file descriptor is opened accordingly.</p>
|
||
<p>zsystem supports <code>subcommand</code></p>
|
||
<p>The builtin zsystem’s subcommand supports 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>
|
||
<p>systell(<code>fd</code>)<br />
|
||
The systell math function returns the current file position for the file
|
||
descriptor passed as an argument.</p>
|
||
<hr />
|
||
<p><span id="Parameters-1"></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>errnos</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
|
||
errno.h. The index of each name (assuming the option KSH_ARRAYS 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 E<code>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>sysparams</p>
|
||
<p>A readonly associative array. The keys are:</p>
|
||
<p>pid<br />
|
||
<span id="index-pid_002c-sysparams"></span></p>
|
||
<p>Returns the process ID of the current process, even in subshells.
|
||
Compare $$, which returns the process ID of the main shell process.</p>
|
||
<p>ppid<br />
|
||
<span id="index-ppid_002c-sysparams"></span></p>
|
||
<p>Returns the current process ID of the parent of the current process,
|
||
even in subshells. Compare $PPID, which returns the process ID of the
|
||
initial parent of the main shell process.</p>
|
||
<p>procsubstpid<br />
|
||
Returns the process ID of the last process started for process
|
||
substitution, i.e. the <(<code>...</code>) and >(<code>...</code>) expansions.</p>
|
||
<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 zsh/net/tcp 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>ztcp [ -acflLtv ] [ -d <code>fd</code> ] [ <code>args</code> ]</p>
|
||
<p>ztcp is implemented as a builtin to allow full use of shell command line
|
||
editing, file I/O, and job control mechanisms.</p>
|
||
<p>If ztcp is run with no options, it will output</p>
|
||
<p>If it is run with only the option -L, 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>
|
||
<p>File descriptor<br />
|
||
The file descriptor in use for the connection. For normal inbound (I)
|
||
and outbound (O) connections this may be read and written by the usual
|
||
shell mechanisms. However, it should only be close with ‘ztcp -c’.</p>
|
||
<p>Connection type<br />
|
||
A letter indicating how the session was created:</p>
|
||
<p>Z<br />
|
||
A session created with the zftp command.</p>
|
||
<p>L<br />
|
||
A connection opened for listening with ‘ztcp -l’.</p>
|
||
<p>I<br />
|
||
An inbound connection accepted with ‘ztcp -a’.</p>
|
||
<p>O<br />
|
||
An outbound connection created with ‘ztcp <code>host</code> <code>...</code>’.</p>
|
||
<p>The local host<br />
|
||
This is usually set to an all-zero IP address as the address of the
|
||
localhost is irrelevant.</p>
|
||
<p>The local port<br />
|
||
This is likely to be zero unless the connection is for listening.</p>
|
||
<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>
|
||
<p>The remote port<br />
|
||
This is zero for a connection opened for listening.</p>
|
||
<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>
|
||
<p>ztcp [ -v ] [ -d <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 REPLY will be set to the file
|
||
descriptor associated with that connection.</p>
|
||
<p>If -d 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 -v.</p>
|
||
<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>
|
||
<p>ztcp -l [ -v ] [ -d <code>fd</code> ] <code>port</code><br />
|
||
ztcp -l 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 -d 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 -v.</p>
|
||
<p>ztcp -a [ -tv ] [ -d <code>targetfd</code> ] <code>listenfd</code><br />
|
||
ztcp -a 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 -d is specified, its argument will be taken as the target file
|
||
descriptor for the connection.</p>
|
||
<p>If -t is specified, ztcp will return if no incoming connection is
|
||
pending. Otherwise it will wait for one.</p>
|
||
<p>In order to elicit more verbose output, use -v.</p>
|
||
<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>
|
||
<p>ztcp -cf [ -v ] [ <code>fd</code> ]<br />
|
||
ztcp -c [ -v ] [ <code>fd</code> ]<br />
|
||
ztcp -c 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 -f.</p>
|
||
<p>In order to elicit more verbose output, use -v.</p>
|
||
<hr />
|
||
<p><span id="Example-2"></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 host1,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">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 host2 (which may, of course, be the same
|
||
machine):</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zmodload zsh/net/tcp
|
||
ztcp host1 5123
|
||
fd=$REPLY
|
||
</code></pre>
|
||
</div>
|
||
<p>Now on each host, $fd contains a file descriptor for talking to the
|
||
other. For example, on host1:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">print This is a message >&$fd
|
||
</code></pre>
|
||
</div>
|
||
<p>and on host2:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">read -r line <&$fd; print -r - $line
|
||
</code></pre>
|
||
</div>
|
||
<p>prints ‘This is a message’.</p>
|
||
<p>To tidy up, on host1:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">ztcp -c $listenfd
|
||
ztcp -c $fd
|
||
</code></pre>
|
||
</div>
|
||
<p>and on host2</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">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 zsh/termcap module makes available one builtin command:</p>
|
||
<p><span id="index-echotc"></span> <span
|
||
id="index-termcap-value_002c-printing"></span></p>
|
||
<p>echotc <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 zsh/termcap module makes available one parameter:</p>
|
||
<p><span id="index-termcap"></span></p>
|
||
<p>termcap</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 zsh/terminfo module makes available one builtin command:</p>
|
||
<p><span id="index-echoti"></span> <span
|
||
id="index-terminfo-value_002c-printing"></span></p>
|
||
<p>echoti <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 zsh/terminfo module makes available one parameter:</p>
|
||
<p><span id="index-terminfo"></span></p>
|
||
<p>terminfo</p>
|
||
<p>An associative array that maps terminfo capability names to their
|
||
values.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fwatch-Module"></span> <span
|
||
id="The-zsh_002fwatch-Module-1"></span></p>
|
||
<h2 id="2231-the-zshwatch-module"><a class="header" href="#2231-the-zshwatch-module">22.31 The zsh/watch Module</a></h2>
|
||
<p>The zsh/watch module can be used to report when specific users log in or
|
||
out. This is controlled via the following parameters.</p>
|
||
<p><span id="index-LOGCHECK"></span></p>
|
||
<p>LOGCHECK</p>
|
||
<p>The interval in seconds between checks for login/logout activity using
|
||
the watch parameter.</p>
|
||
<p><span id="index-watch"></span> <span id="index-WATCH"></span></p>
|
||
<p>watch <S> <Z> (WATCH <S>)</p>
|
||
<p>An array (colon-separated list) of login/logout events to report.</p>
|
||
<p>If it contains the single word ‘all’, then all login/logout events are
|
||
reported. If it contains the single word ‘notme’, then all events are
|
||
reported as with ‘all’ except $USERNAME.</p>
|
||
<p>An entry in this list may consist of a username, an ‘@’ followed by a
|
||
remote hostname, and a ‘%’ followed by a line (tty). Any of these may be
|
||
a pattern (be sure to quote this during the assignment to watch so that
|
||
it does not immediately perform file generation); the setting of the
|
||
EXTENDED_GLOB option is respected. Any or all of these components may be
|
||
present in an entry; if a login/logout event matches all of them, it is
|
||
reported.</p>
|
||
<p>For example, with the EXTENDED_GLOB option set, the following:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">watch=('^(pws|barts)')
|
||
</code></pre>
|
||
</div>
|
||
<p>causes reports for activity associated with any user other than pws or
|
||
barts.</p>
|
||
<p><span id="index-WATCHFMT"></span></p>
|
||
<p>WATCHFMT</p>
|
||
<p>The format of login/logout reports if the watch parameter is set.
|
||
Default is ‘%n has %a %l from %m’. Recognizes the following escape
|
||
sequences:</p>
|
||
<p>%n<br />
|
||
The name of the user that logged in/out.</p>
|
||
<p>%a<br />
|
||
The observed action, i.e. "logged on" or "logged off".</p>
|
||
<p>%l<br />
|
||
The line (tty) the user is logged in on.</p>
|
||
<p>%M<br />
|
||
The full hostname of the remote host.</p>
|
||
<p>%m<br />
|
||
The hostname up to the first ‘.’. If only the IP address is available or
|
||
the utmp field contains the name of an X-windows display, the whole name
|
||
is printed.</p>
|
||
<p><em>NOTE:</em> The ‘%m’ and ‘%M’ escapes will work only if there is a host name
|
||
field in the utmp on your machine. Otherwise they are treated as
|
||
ordinary strings.</p>
|
||
<p>%F{<code>color</code>} (%f)<br />
|
||
Start (stop) using a different foreground color.</p>
|
||
<p>%K{<code>color</code>} (%k)<br />
|
||
Start (stop) using a different background color.</p>
|
||
<p>%S (%s)<br />
|
||
Start (stop) standout mode.</p>
|
||
<p>%U (%u)<br />
|
||
Start (stop) underline mode.</p>
|
||
<p>%B (%b)<br />
|
||
Start (stop) boldface mode.</p>
|
||
<p>%t<br />
|
||
%@<br />
|
||
The time, in 12-hour, am/pm format.</p>
|
||
<p>%T<br />
|
||
The time, in 24-hour format.</p>
|
||
<p>%w<br />
|
||
The date in ‘<code>day</code>-<code>dd</code>’ format.</p>
|
||
<p>%W<br />
|
||
The date in ‘<code>mm</code>/<code>dd</code>/<code>yy</code>’ format.</p>
|
||
<p>%D<br />
|
||
The date in ‘<code>yy</code>-<code>mm</code>-<code>dd</code>’ format.</p>
|
||
<p>%D{<code>string</code>}<br />
|
||
The date formatted as <code>string</code> using the strftime function, with zsh
|
||
extensions as described by <a href="Prompt-Expansion.html#Prompt-Expansion">Prompt
|
||
Expansion</a>.</p>
|
||
<p>%(<code>x</code>:<code>true-text</code>:<code>false-text</code>)<br />
|
||
Specifies a ternary expression. The character following the <code>x</code> is
|
||
arbitrary; the same character is used to separate the text for the
|
||
"true" result from that for the "false" result. Both the separator and
|
||
the right parenthesis may be escaped with a backslash. Ternary
|
||
expressions may be nested.</p>
|
||
<p>The test character <code>x</code> may be any one of ‘l’, ‘n’, ‘m’ or ‘M’, which
|
||
indicate a ‘true’ result if the corresponding escape sequence would
|
||
return a non-empty value; or it may be ‘a’, which indicates a ‘true’
|
||
result if the watched user has logged in, or ‘false’ if he has logged
|
||
out. Other characters evaluate to neither true nor false; the entire
|
||
expression is omitted in this case.</p>
|
||
<p>If the result is ‘true’, then the <code>true-text</code> is formatted according to
|
||
the rules above and printed, and the <code>false-text</code> is skipped. If
|
||
‘false’, the <code>true-text</code> is skipped and the <code>false-text</code> is formatted
|
||
and printed. Either or both of the branches may be empty, but both
|
||
separators must be present in any case.</p>
|
||
<p>Furthermore, the zsh/watch module makes available one builtin command:</p>
|
||
<p><span id="index-log"></span> <span id="index-watch_002c-use-of"></span>
|
||
<span id="index-watching-users"></span> <span
|
||
id="index-users_002c-watching"></span></p>
|
||
<p>log</p>
|
||
<p>List all users currently logged in who are affected by the current
|
||
setting of the watch parameter.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fzftp-Module"></span> <span
|
||
id="The-zsh_002fzftp-Module-1"></span></p>
|
||
<h2 id="2232-the-zshzftp-module"><a class="header" href="#2232-the-zshzftp-module">22.32 The zsh/zftp Module</a></h2>
|
||
<p>The zsh/zftp 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>zftp <code>subcommand</code> [ <code>args</code> ]</p>
|
||
<p>The zsh/zftp 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 zsh distribution and is described in <a href="Zftp-Function-System.html#Zftp-Function-System">Zftp Function
|
||
System</a>. However, the
|
||
zftp command is entirely usable in its own right.</p>
|
||
<p>All commands consist of the command name zftp 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 ZFTP_VERBOSE for more information on
|
||
how responses from the server may be printed.</p>
|
||
<hr />
|
||
<p><span id="Subcommands"></span></p>
|
||
<h3 id="22321-subcommands"><a class="header" href="#22321-subcommands">22.32.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>open <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</code>:<code>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 ZFTP_PORT 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 ’[fe80::203:baff:fe02:8b56]’. For consistency this is
|
||
allowed with all forms of <code>host</code>.</p>
|
||
<p>Remaining arguments are passed to the login subcommand. Note that if no
|
||
arguments beyond <code>host</code> are supplied, open will <em>not</em> automatically call
|
||
login. If no arguments at all are supplied, open will use the parameters
|
||
set by the params subcommand.</p>
|
||
<p>After a successful open, the shell variables ZFTP_HOST, ZFTP_PORT,
|
||
ZFTP_IP and ZFTP_SYSTEM are available; see ‘Variables’ below.</p>
|
||
<p>login [ <code>name</code> [ <code>password</code> [ <code>account</code> ] ] ]</p>
|
||
<p>user [ <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 ZFTP_USER, ZFTP_ACCOUNT
|
||
and ZFTP_PWD 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>params [ <code>host</code> [ <code>user</code> [ <code>password</code> [ <code>account</code> ] ] ] ]</p>
|
||
<p>params -</p>
|
||
<p>Store the given parameters for a later open 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 ‘?’, 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 login subcommand,
|
||
including special handling of <code>password</code>. If the ‘?’ 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 ‘\’; hence an argument "\\$word"
|
||
guarantees that the string from the shell parameter $word will be
|
||
treated literally, whether or not it begins with a ‘?’.</p>
|
||
<p>If instead a single ‘-’ is given, the existing parameters, if any, are
|
||
deleted. In that case, calling open with no arguments will cause an
|
||
error.</p>
|
||
<p>The list of parameters is not deleted after a close, however it will be
|
||
deleted if the zsh/zftp module is unloaded.</p>
|
||
<p>For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zftp params ftp.elsewhere.xx juser '?Password for juser: '
|
||
</code></pre>
|
||
</div>
|
||
<p>will store the host ftp.elsewhere.xx and the user juser and then prompt
|
||
the user for the corresponding password with the given prompt.</p>
|
||
<p>test</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 test
|
||
subcommand is silent, apart from messages printed by the $ZFTP_VERBOSE
|
||
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 select(2) or
|
||
poll(2) system calls; otherwise the message ‘not supported on this
|
||
system’ is printed instead.</p>
|
||
<p>The test subcommand will automatically be called at the start of any
|
||
other subcommand for the current session when a connection is open.</p>
|
||
<p>cd <code>directory</code></p>
|
||
<p>Change the remote directory to <code>directory</code>. Also alters the shell
|
||
variable ZFTP_PWD.</p>
|
||
<p>cdup</p>
|
||
<p>Change the remote directory to the one higher in the directory tree.
|
||
Note that cd .. will also work correctly on non-UNIX systems.</p>
|
||
<p>dir [ <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 ls command and with no arguments return the result of
|
||
‘ls -l’. The directory is listed to standard output.</p>
|
||
<p>ls [ <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 dir.</p>
|
||
<p>type [ <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 ‘A’ (ASCII), ‘I’ (Image, i.e.
|
||
binary), or ‘B’ (a synonym for ‘I’).</p>
|
||
<p>The FTP default for a transfer is ASCII. However, if zftp finds that the
|
||
remote host is a UNIX machine with 8-bit byes, it will automatically
|
||
switch to using binary for file transfers upon open. 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>ascii</p>
|
||
<p>The same as type A.</p>
|
||
<p>binary</p>
|
||
<p>The same as type I.</p>
|
||
<p>mode [ S | B ]</p>
|
||
<p>Set the mode type to stream (S) or block (B). Stream mode is the
|
||
default; block mode is not widely supported.</p>
|
||
<p>remote <code>file</code> ...</p>
|
||
<p>local [ <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 CCYYMMDDhhmmSS 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 [[ builtin’s < and > 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 remote command will print nothing and return status 2,
|
||
compared with status 1 for a file not found.</p>
|
||
<p>The local command (but not remote) 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 put command with no further
|
||
redirection.</p>
|
||
<p>get <code>file</code> ...</p>
|
||
<p>Retrieve all <code>file</code>s from the server, concatenating them and sending
|
||
them to standard output.</p>
|
||
<p>put <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>append <code>file</code> ...</p>
|
||
<p>As put, but if the remote <code>file</code> already exists, data is appended to it
|
||
instead of overwriting it.</p>
|
||
<p>getat <code>file</code> <code>point</code></p>
|
||
<p>putat <code>file</code> <code>point</code></p>
|
||
<p>appendat <code>file</code> <code>point</code></p>
|
||
<p>Versions of get, put and append 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>delete <code>file</code> ...</p>
|
||
<p>Delete the list of files on the server.</p>
|
||
<p>mkdir <code>directory</code></p>
|
||
<p>Create a new directory <code>directory</code> on the server.</p>
|
||
<p>rmdir <code>directory</code></p>
|
||
<p>Delete the directory <code>directory</code> on the server.</p>
|
||
<p>rename <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>site <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>quote <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 STAT and HELP. Note also the mechanism for
|
||
returning messages as described for the variable ZFTP_VERBOSE below, in
|
||
particular that all messages from the control connection are sent to
|
||
standard error.</p>
|
||
<p>close</p>
|
||
<p>quit</p>
|
||
<p>Close the current data connection. This unsets the shell parameters
|
||
ZFTP_HOST, ZFTP_PORT, ZFTP_IP, ZFTP_SYSTEM, ZFTP_USER, ZFTP_ACCOUNT,
|
||
ZFTP_PWD, ZFTP_TYPE and ZFTP_MODE.</p>
|
||
<p>session [ <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
|
||
‘default’. 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 close), and any user
|
||
parameters specified with the params subcommand. Changing to a previous
|
||
session restores those values; changing to a new session initialises
|
||
them in the same way as if zftp had just been loaded. The name of the
|
||
current session is given by the parameter ZFTP_SESSION.</p>
|
||
<p>rmsession [ <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 ‘default’ is created and becomes the current session;
|
||
note that this is a new session even if the session being deleted is
|
||
also called ‘default’. It is recommended that sessions not be deleted
|
||
while background commands which use zftp are still active.</p>
|
||
<hr />
|
||
<p><span id="Parameters-4"></span></p>
|
||
<h3 id="22322-parameters"><a class="header" href="#22322-parameters">22.32.2 Parameters</a></h3>
|
||
<p><span id="index-zftp_002c-parameters"></span></p>
|
||
<p>The following shell parameters are used by zftp. Currently none of them
|
||
are special.</p>
|
||
<p><span id="index-ZFTP_005fTMOUT"></span></p>
|
||
<p>ZFTP_TMOUT</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>ZFTP_IP</p>
|
||
<p>Readonly. The IP address of the current connection in dot notation.</p>
|
||
<p><span id="index-ZFTP_005fHOST"></span></p>
|
||
<p>ZFTP_HOST</p>
|
||
<p>Readonly. The hostname of the current remote server. If the host was
|
||
opened as an IP number, ZFTP_HOST 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>ZFTP_PORT</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 zftp open will also need to be in this format.</p>
|
||
<p><span id="index-ZFTP_005fSYSTEM"></span></p>
|
||
<p>ZFTP_SYSTEM</p>
|
||
<p>Readonly. The system type string returned by the server in response to
|
||
an FTP SYST request. The most interesting case is a string beginning
|
||
"UNIX Type: L8", which ensures maximum compatibility with a local UNIX
|
||
host.</p>
|
||
<p><span id="index-ZFTP_005fTYPE"></span></p>
|
||
<p>ZFTP_TYPE</p>
|
||
<p>Readonly. The type to be used for data transfers , either ‘A’ or ‘I’.
|
||
Use the type subcommand to change this.</p>
|
||
<p><span id="index-ZFTP_005fUSER"></span></p>
|
||
<p>ZFTP_USER</p>
|
||
<p>Readonly. The username currently logged in, if any.</p>
|
||
<p><span id="index-ZFTP_005fACCOUNT"></span></p>
|
||
<p>ZFTP_ACCOUNT</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>ZFTP_PWD</p>
|
||
<p>Readonly. The current directory on the server.</p>
|
||
<p><span id="index-ZFTP_005fCODE"></span></p>
|
||
<p>ZFTP_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>ZFTP_REPLY</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>ZFTP_SESSION</p>
|
||
<p>Readonly. The name of the current FTP session; see the description of
|
||
the session subcommand.</p>
|
||
<p><span id="index-ZFTP_005fPREFS"></span></p>
|
||
<p>ZFTP_PREFS</p>
|
||
<p>A string of preferences for altering aspects of zftp’s behaviour. Each
|
||
preference is a single character. The following are defined:</p>
|
||
<p>P<br />
|
||
Passive: attempt to make the remote server initiate data transfers. This
|
||
is slightly more efficient than sendport mode. If the letter S occurs
|
||
later in the string, zftp will use sendport mode if passive mode is not
|
||
available.</p>
|
||
<p>S<br />
|
||
Sendport: initiate transfers by the FTP PORT command. If this occurs
|
||
before any P in the string, passive mode will never be attempted.</p>
|
||
<p>D<br />
|
||
Dumb: use only the bare minimum of FTP commands. This prevents the
|
||
variables ZFTP_SYSTEM and ZFTP_PWD from being set, and will mean all
|
||
connections default to ASCII type. It may prevent ZFTP_SIZE from being
|
||
set during a transfer if the server does not send it anyway (many
|
||
servers do).</p>
|
||
<p>If ZFTP_PREFS is not set when zftp is loaded, it will be set to a
|
||
default of ‘PS’, i.e. use passive mode if available, otherwise fall back
|
||
to sendport mode.</p>
|
||
<p><span id="index-ZFTP_005fVERBOSE"></span></p>
|
||
<p>ZFTP_VERBOSE</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>
|
||
<p>1.<br />
|
||
A positive preliminary reply.</p>
|
||
<p>2.<br />
|
||
A positive completion reply.</p>
|
||
<p>3.<br />
|
||
A positive intermediate reply.</p>
|
||
<p>4.<br />
|
||
A transient negative completion reply.</p>
|
||
<p>5.<br />
|
||
A permanent negative completion reply.</p>
|
||
<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 ZFTP_VERBOSE is not set when zftp is loaded, it will be set to the
|
||
default value 450, 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="22323-functions"><a class="header" href="#22323-functions">22.32.3 Functions</a></h3>
|
||
<p><span id="index-zftp_002c-functions"></span></p>
|
||
<p><span id="index-zftp_005fchpwd_002c-specification"></span></p>
|
||
<p>zftp_chpwd</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, $ZFTP_PWD will be unset;
|
||
otherwise it will reflect the new directory.</p>
|
||
<p><span id="index-zftp_005fprogress_002c-specification"></span></p>
|
||
<p>zftp_progress</p>
|
||
<p>If this function is set by the user, it will be called during a get, put
|
||
or append operation each time sufficient data has been received from the
|
||
host. During a get, 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>ZFTP_FILE</p>
|
||
<p>The name of the remote file being transferred from or to.</p>
|
||
<p><span id="index-ZFTP_005fTRANSFER"></span></p>
|
||
<p>ZFTP_TRANSFER</p>
|
||
<p>A G for a get operation and a P for a put operation.</p>
|
||
<p><span id="index-ZFTP_005fSIZE"></span></p>
|
||
<p>ZFTP_SIZE</p>
|
||
<p>The total size of the complete file being transferred: the same as the
|
||
first value provided by the remote and local 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>ZFTP_COUNT</p>
|
||
<p>The amount of data so far transferred; a number between zero and
|
||
$ZFTP_SIZE, if that is set. This number is always available.</p>
|
||
<p>The function is initially called with ZFTP_TRANSFER set appropriately
|
||
and ZFTP_COUNT set to zero. After the transfer is finished, the function
|
||
will be called one more time with ZFTP_TRANSFER set to GF or PF, in case
|
||
it wishes to tidy up. It is otherwise never called twice with the same
|
||
value of ZFTP_COUNT.</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 unfunction
|
||
when necessary.</p>
|
||
<hr />
|
||
<p><span id="Problems"></span></p>
|
||
<h3 id="22324-problems"><a class="header" href="#22324-problems">22.32.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 zftp. 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 zftp 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="2233-the-zshzle-module"><a class="header" href="#2233-the-zshzle-module">22.33 The zsh/zle Module</a></h2>
|
||
<p>The zsh/zle 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="2234-the-zshzleparameter-module"><a class="header" href="#2234-the-zshzleparameter-module">22.34 The zsh/zleparameter Module</a></h2>
|
||
<p><span id="index-parameters_002c-special-2"></span></p>
|
||
<p>The zsh/zleparameter 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>keymaps</p>
|
||
<p>This array contains the names of the keymaps currently defined.</p>
|
||
<p><span id="index-widgets-1"></span></p>
|
||
<p>widgets</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 ‘builtin’ for builtin widgets, a string of the form
|
||
‘user:<code>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
|
||
‘completion:<code>type</code>:<code>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="2235-the-zshzprof-module"><a class="header" href="#2235-the-zshzprof-module">22.35 The zsh/zprof Module</a></h2>
|
||
<p><span id="index-functions_002c-profiling"></span></p>
|
||
<p>When loaded, the zsh/zprof causes shell functions to be profiled. The
|
||
profiling results can be obtained with the zprof 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>zprof [ -c ]</p>
|
||
<p>Without the -c option, zprof lists profiling results to standard output.
|
||
The format is comparable to that of commands like gprof.</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 zsh/zprof module is loaded, profiling will be done and
|
||
multiple invocations of the zprof builtin command will show the times
|
||
and numbers of calls since the module was loaded. With the -c option,
|
||
the zprof 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="2236-the-zshzpty-module"><a class="header" href="#2236-the-zshzpty-module">22.36 The zsh/zpty Module</a></h2>
|
||
<p>The zsh/zpty module offers one builtin:</p>
|
||
<p><span id="index-zpty"></span></p>
|
||
<p>zpty [ -e ] [ -b ] <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 eval 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 zpty.</p>
|
||
<p>With the -e option, the pseudo-terminal is set up so that input
|
||
characters are echoed.</p>
|
||
<p>With the -b option, input to and output from the pseudo-terminal are
|
||
made non-blocking.</p>
|
||
<p>The shell parameter REPLY 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
|
||
sysread and syswrite (see <a href="#The-zsh_002fsystem-Module">The zsh/system
|
||
Module</a>). <em>Warning</em>: Use of sysread and
|
||
syswrite is <em>not</em> recommended; use zpty -r and zpty -w unless you know
|
||
exactly what you are doing.</p>
|
||
<p>zpty -d [ <code>name</code> ... ]</p>
|
||
<p>The second form, with the -d 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>zpty -w [ -n ] <code>name</code> [ <code>string</code> ... ]</p>
|
||
<p>The -w 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 -n 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
|
||
-n 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>zpty -r [ -mt ] <code>name</code> [ <code>param</code> [ <code>pattern</code> ] ]</p>
|
||
<p>The -r 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
|
||
-m 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 2 if this is because the command has finished.</p>
|
||
<p>If the -r option is combined with the -t option, zpty tests whether
|
||
output is available before trying to read. If no output is available,
|
||
zpty immediately returns the status 1. 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>zpty -t <code>name</code></p>
|
||
<p>The -t option without the -r 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>zpty [ -L ]</p>
|
||
<p>The last form, without any arguments, is used to list the commands
|
||
currently defined. If the -L option is given, this is done in the form
|
||
of calls to the zpty builtin.</p>
|
||
<hr />
|
||
<p><span id="The-zsh_002fzselect-Module"></span> <span
|
||
id="The-zsh_002fzselect-Module-1"></span></p>
|
||
<h2 id="2237-the-zshzselect-module"><a class="header" href="#2237-the-zshzselect-module">22.37 The zsh/zselect Module</a></h2>
|
||
<p>The zsh/zselect 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>zselect [ -rwe ] [ -t <code>timeout</code> ] [ -a <code>array</code> ] [ -A <code>assoc</code> ]
|
||
[ <code>fd</code> ... ]</p>
|
||
<p>The zselect 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 system’s
|
||
documentation for 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. zselect
|
||
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 -r, -w and -e, 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 -e
|
||
option useful.)</p>
|
||
<p>The option ‘-t <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 zselect 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 ‘-a <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 reply will be used for this purpose. The array will contain a
|
||
string similar to the arguments for zselect. For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zselect -t 0 -r 0 -w 1
|
||
</code></pre>
|
||
</div>
|
||
<p>might return immediately with status 0 and $reply containing ‘-r 0 -w 1’
|
||
to show that both file descriptors are ready for the requested
|
||
operations.</p>
|
||
<p>The option ‘-A <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 -a, nor will reply be modified. The keys of
|
||
assoc are the file descriptors, and the corresponding values are any of
|
||
the characters ‘rwe’ 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="2238-the-zshzutil-module"><a class="header" href="#2238-the-zshzutil-module">22.38 The zsh/zutil Module</a></h2>
|
||
<p><span id="index-builtins_002c-utility"></span></p>
|
||
<p>The zsh/zutil module only adds some builtins:</p>
|
||
<p><span id="index-zstyle"></span></p>
|
||
<p>zstyle [ -L [ <code>metapattern</code> [ <code>style</code> ] ] ]</p>
|
||
<p>zstyle [ -e | - | -- ] <code>pattern</code> <code>style</code> <code>string</code> ...</p>
|
||
<p>zstyle -d [ <code>pattern</code> [ <code>style</code> ... ] ]</p>
|
||
<p>zstyle -g <code>name</code> [ <code>pattern</code> [ <code>style</code> ] ]</p>
|
||
<p>zstyle -{a|b|s} <code>context</code> <code>style</code> <code>name</code> [ <code>sep</code> ]</p>
|
||
<p>zstyle -{T|t} <code>context</code> <code>style</code> [ <code>string</code> ... ]</p>
|
||
<p>zstyle -m <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 ‘*’. A ‘*’ 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> <span
|
||
id="index-preferred_002dprecipitation_002c-example-style"></span> <span
|
||
id="index-weather_002c-example-function"></span></p>
|
||
<p>For example, a fictional ‘weather’ plugin might state in its
|
||
documentation that it looks up the preferred-precipitation style under
|
||
the ‘:weather:<code>continent</code>:<code>day-of-the-week</code>:<code>phase-of-the-moon</code>’
|
||
context. According to this, you might set the following in your zshrc:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle ':weather:europe:*' preferred-precipitation rain
|
||
zstyle ':weather:*:Sunday:*' preferred-precipitation snow
|
||
</code></pre>
|
||
</div>
|
||
<p>Then the plugin would run under the hood a command such as</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zstyle -s ":weather:${continent}:${day_of_week}:${moon_phase}" preferred-precipitation REPLY
|
||
</code></pre>
|
||
</div>
|
||
<p>in order to retrieve your preference into the scalar variable $REPLY. On
|
||
Sundays $REPLY would be set to ‘snow’; in Europe it would be set to
|
||
‘rain’; and on Sundays in Europe it would be set to ‘snow’ again,
|
||
because the patterns ‘:weather:europe:*’ and ‘:weather:*:Sunday:*’
|
||
both match the <code>context</code> argument to zstyle -s, are equally specific,
|
||
and the latter is more specific (because it has more colon-separated
|
||
components).</p>
|
||
<p><em>Usage</em></p>
|
||
<p>The forms that operate on patterns are the following.</p>
|
||
<p>zstyle [ -L [ <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 zstyle will test
|
||
them.</p>
|
||
<p>If the -L option is given, listing is done in the form of calls to
|
||
zstyle. 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, ‘zstyle -L ":completion:*"’
|
||
will match any supplied pattern beginning ‘:completion:’, not just
|
||
":completion:*": use ’:completion:\*’ to match that. The optional
|
||
second argument limits the output to a specific <code>style</code> (not a pattern).
|
||
-L is not compatible with any other options.</p>
|
||
<p>zstyle [ - | -- | -e ] <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 -e 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 eval builtin command) when the style is
|
||
looked up. In this case the parameter ‘reply’ must be assigned to set
|
||
the strings returned after the evaluation. Before evaluating the value,
|
||
reply is unset, and if it is still unset after the evaluation, the style
|
||
is treated as if it were not set.</p>
|
||
<p>zstyle -d [ <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>
|
||
<p>zstyle -g <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>
|
||
<p>The other forms can be used to look up or test styles for a given
|
||
context.</p>
|
||
<p>zstyle -s <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 0 if the style is set, 1 otherwise.</p>
|
||
<p>zstyle -b <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 ‘yes’ if
|
||
the value has only one string and that string is equal to one of ‘yes’,
|
||
‘true’, ‘on’, or ‘1’. If the value is any other string or has more than
|
||
one string, the parameter is set to ‘no’.</p>
|
||
<p>Return 0 if <code>name</code> is set to ‘yes’, 1 otherwise.</p>
|
||
<p>zstyle -a <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 0 if the style is set, 1 otherwise.</p>
|
||
<p>zstyle -t <code>context</code> <code>style</code> [ <code>string</code> ... ]<br />
|
||
zstyle -T <code>context</code> <code>style</code> [ <code>string</code> ... ]<br />
|
||
Test the value of a style, i.e. the -t option only returns a status
|
||
(sets $?). 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 ‘true’, ‘yes’, ‘on’ or ‘1’. 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 1. If the
|
||
style is not defined, the status is 2.</p>
|
||
<p>The -T option tests the values of the style like -t, but it returns
|
||
status zero (rather than 2) if the style is not defined for any matching
|
||
pattern.</p>
|
||
<p>zstyle -m <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>
|
||
<p><span id="index-zformat"></span></p>
|
||
<p>zformat -f <code>param</code> <code>format</code> <code>spec</code> ...</p>
|
||
<p>zformat -F <code>param</code> <code>format</code> <code>spec</code> ...</p>
|
||
<p>zformat -a <code>array</code> <code>sep</code> <code>spec</code> ...</p>
|
||
<p>This builtin provides different forms of formatting. The first form is
|
||
selected with the -f 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</code>:<code>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 ‘%’ sequence
|
||
may also contain optional minimum and maximum field width specifications
|
||
between the ‘%’ and the ‘<code>char</code>’ in the form ‘%<code>min</code>.<code>max</code>c’, 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 ‘%’ 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 %-escapes also understand ternary expressions in the form used by
|
||
prompts. The % is followed by a ‘(’ and then an ordinary format
|
||
specifier character as described above. There may be a set of digits
|
||
either before or after the ‘(’; 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</code>.<code>text1</code>.<code>text2</code>)’, except that the ‘.’
|
||
character is arbitrary. The value given for the format specifier in the
|
||
<code>char</code>:<code>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 %). Either of <code>text1</code> or <code>text2</code> may contain nested %-escapes.</p>
|
||
<p>For example:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">zformat -f REPLY "The answer is '%3(c.yes.no)'." c:3
|
||
</code></pre>
|
||
</div>
|
||
<p>outputs "The answer is ’yes’." to REPLY since the value for the format
|
||
specifier c is 3, agreeing with the digit argument to the ternary
|
||
expression.</p>
|
||
<p>With -F instead of -f, ternary expressions choose between the ‘true’ or
|
||
‘false’ text on the basis of whether the format specifier is present and
|
||
non-empty. A test number indicates a minimum width for the value given
|
||
in the format specifier. Negative numbers reverse this, so the test is
|
||
for whether the value exceeds a maximum width.</p>
|
||
<p>The form, using the -a option, can be used for aligning strings. Here,
|
||
the <code>spec</code>s are of the form ‘<code>left</code>:<code>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>zregexparse</p>
|
||
<p>This implements some internals of the _regex_arguments function.</p>
|
||
<p><span id="index-zparseopts"></span></p>
|
||
<p>zparseopts [ -D -E -F -K -M ] [ -a <code>array</code> ] [ -A <code>assoc</code> ] [ -
|
||
] <code>spec</code> ...</p>
|
||
<p>This builtin simplifies the parsing of options in positional parameters,
|
||
i.e. the set of arguments given by $*. 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 -a 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 -a or -A options is used.</p>
|
||
<p>Unless the -E option is given, parsing stops at the first string that
|
||
isn’t described by one of the <code>spec</code>s. Even with -E, parsing always
|
||
stops at a positional parameter equal to ‘-’ or ‘--’. See also -F.</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>
|
||
<p><code>name</code><br />
|
||
<code>name</code>+<br />
|
||
The <code>name</code> is the name of the option without the leading ‘-’. To specify
|
||
a GNU-style long option, one of the usual two leading ‘-’ must be
|
||
included in <code>name</code>; for example, a ‘--file’ option is represented by a
|
||
<code>name</code> of ‘-file’.</p>
|
||
<p>If a ‘+’ appears after <code>name</code>, the option is appended to <code>array</code> each
|
||
time it is found in the positional parameters; without the ‘+’ 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 ‘-’
|
||
(unless the -E option is used).</p>
|
||
<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 ‘:-’ form is used, in which case the argument is put into the
|
||
same element.</p>
|
||
<p>A ‘+’ as described above may appear between the <code>name</code> and the first
|
||
colon.</p>
|
||
<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 ‘-’. There is no special handling of ‘=’ as with GNU-style
|
||
argument parsers; given the <code>spec</code> ‘-foo:’, the positional parameter
|
||
‘--foo=bar’ is parsed as ‘--foo’ with an argument of ‘=bar’.</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 ‘-foo -foobar’ (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 ‘-foo: -foobar’. In that case, the last
|
||
matching <code>spec</code> wins.</p>
|
||
<p>The options of zparseopts itself cannot be stacked because, for example,
|
||
the stack ‘-DEK’ is indistinguishable from a <code>spec</code> for the GNU-style
|
||
long option ‘--DEK’. The options of zparseopts itself are:</p>
|
||
<p>-a <code>array</code><br />
|
||
As described above, this names the default array in which to store the
|
||
recognised options.</p>
|
||
<p>-A <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>
|
||
<p>-D<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 ‘-’ or ‘--’, it is removed as well. This is similar to
|
||
using the shift builtin.</p>
|
||
<p>-E<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 -D) 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 ‘-’ or ‘--’ not
|
||
described by a <code>spec</code>, but it is not removed when used with -D.</p>
|
||
<p>-F<br />
|
||
If this option is given, zparseopts 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 (-D) and extraction (-E)
|
||
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>
|
||
<p>-K<br />
|
||
With this option, the arrays specified with the -a 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 -A
|
||
option are preserved by -K. This allows assignment of default values to
|
||
arrays before calling zparseopts.</p>
|
||
<p>-M<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 $* is parsed, so results may be</p>
|
||
<p>For example,</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">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-zsh">foo=(-a)
|
||
bar=(-b x -c y -c z)
|
||
</code></pre>
|
||
</div>
|
||
<p>The arguments from ‘baz’ on will not be used.</p>
|
||
<p>As an example for the -E option, consider:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">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-zsh">bar=(-b y)
|
||
set -- -a x -c z arg1 arg2
|
||
</code></pre>
|
||
</div>
|
||
<p>I.e., the option -b and its arguments are taken from the positional
|
||
parameters and put into the array bar.</p>
|
||
<p>The -M option can be used like this:</p>
|
||
<div class="example">
|
||
<pre><code class="language-zsh">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-zsh">foo=(-a)
|
||
bar=(-a '' -b xyz)
|
||
</code></pre>
|
||
</div>
|
||
<hr />
|
||
<p>This document was generated on <em>May 14, 2022</em> using <a href="http://www.nongnu.org/texi2html/"><em>texi2html
|
||
5.0</em></a>.<br />
|
||
Zsh version 5.9, released on May 14, 2022.</p>
|
||
|
||
</main>
|
||
|
||
<nav class="nav-wrapper" aria-label="Page navigation">
|
||
<!-- Mobile navigation buttons -->
|
||
<a rel="prev" href="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">
|
||
const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
|
||
const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload";
|
||
const socket = new WebSocket(wsAddress);
|
||
socket.onmessage = function (event) {
|
||
if (event.data === "reload") {
|
||
socket.close();
|
||
location.reload();
|
||
}
|
||
};
|
||
|
||
window.onbeforeunload = function() {
|
||
socket.close();
|
||
}
|
||
</script>
|
||
|
||
|
||
|
||
<script type="text/javascript">
|
||
window.playground_copyable = true;
|
||
</script>
|
||
|
||
|
||
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
|
||
|
||
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
|
||
<script src="book.js" type="text/javascript" charset="utf-8"></script>
|
||
|
||
<!-- Custom JS scripts -->
|
||
|
||
|
||
</body>
|
||
</html>
|