This is zsh.info, produced by makeinfo version 4.2 from tzsh.texi.

INFO-DIR-SECTION Shells
START-INFO-DIR-ENTRY
* Zsh: (zsh).                  The Z shell.
END-INFO-DIR-ENTRY

INFO-DIR-SECTION Utilities
START-INFO-DIR-ENTRY
* ZSH: (zsh).                     The Z Shell Manual.
END-INFO-DIR-ENTRY


File: zsh.info,  Node: Top,  Next: The Z Shell Manual,  Prev: (dir),  Up: (dir)

The Z Shell Manual
******************

This Info file documents Zsh, a freely available UNIX command
interpreter (shell), which of the standard shells most closely
resembles the Korn shell (ksh), although it is not completely
compatible.

Version 4.2.4, last updated February 2, 2005.

* Menu:

* The Z Shell Manual::
* Introduction::
* Invocation::
* Files::
* Shell Grammar::
* Redirection::
* Command Execution::
* Functions::
* Jobs & Signals::
* Arithmetic Evaluation::
* Conditional Expressions::
* Prompt Expansion::
* Expansion::
* Parameters::
* Options::
* Shell Builtin Commands::
* Zsh Line Editor::
* Completion Widgets::
* Completion System::
* Completion Using compctl::
* Zsh Modules::
* TCP Function System::
* Zftp Function System::
* User Contributions::


--- Indices ---


* Concept Index::
* Variables Index::
* Options Index::
* Functions Index::
* Editor Functions Index::
* Style and Tag Index::


--- The Detailed Node Listing ---


Introduction


* Author::
* Availability::
* Mailing Lists::
* The Zsh FAQ::
* The Zsh Web Page::
* The Zsh Userguide::
* See Also::


Invocation


* Compatibility::
* Restricted Shell::


Shell Grammar


* Simple Commands & Pipelines::
* Precommand Modifiers::
* Complex Commands::
* Alternate Forms For Complex Commands::
* Reserved Words::
* Comments::
* Aliasing::
* Quoting::


Expansion


* History Expansion::
* Process Substitution::
* Parameter Expansion::
* Command Substitution::
* Arithmetic Expansion::
* Brace Expansion::
* Filename Expansion::
* Filename Generation::


Parameters


* Array Parameters::
* Positional Parameters::
* Local Parameters::
* Parameters Set By The Shell::
* Parameters Used By The Shell::


Options


* Specifying Options::
* Description of Options::
* Option Aliases::
* Single Letter Options::


Zsh Line Editor


* Movement::
* History Control::
* Modifying Text::
* Arguments::
* Completion::
* Miscellaneous::


Completion Widgets


* Special Parameters::
* Builtin Commands::
* Condition Codes::
* Matching Control::
* Completion Widget Example::


Completion System


* Initialization::
* Completion System Configuration::
* Control Functions::
* Bindable Commands::
* Completion Functions::
* Completion Directories::


Completion Using compctl


* Command Flags::
* Option Flags::
* Alternative Completion::
* Extended Completion::
* Example::


Zsh Modules


* The zsh/cap Module::
* The zsh/clone Module::
* The zsh/compctl Module::
* The zsh/complete Module::
* The zsh/complist Module::
* The zsh/computil Module::
* The zsh/datetime Module::
* The zsh/deltochar Module::
* The zsh/example Module::
* The zsh/files Module::
* The zsh/mapfile Module::
* The zsh/mathfunc Module::
* The zsh/parameter Module::
* The zsh/pcre Module::
* The zsh/sched Module::
* The zsh/net/socket Module::
* The zsh/stat Module::
* The zsh/system Module::
* The zsh/net/tcp Module::
* The zsh/termcap Module::
* The zsh/terminfo Module::
* The zsh/zftp Module::
* The zsh/zle Module::
* The zsh/zleparameter Module::
* The zsh/zprof Module::
* The zsh/zpty Module::
* The zsh/zselect Module::
* The zsh/zutil Module::


TCP Function System


* TCP Functions::
* TCP Parameters::
* TCP Examples::
* TCP Bugs::


Zftp Function System


* Installation::
* Zftp Functions::
* Miscellaneous Features::


User Contributions


* Utilities::
* Prompt Themes::
* ZLE Functions::
* Other Functions::


File: zsh.info,  Node: The Z Shell Manual,  Next: Introduction,  Prev: Top,  Up: Top

The Z Shell Manual
******************

This document has been produced from the texinfo file zsh.texi,
included in the Doc sub-directory of the Zsh distribution.

Producing documentation from zsh.texi
=====================================

The texinfo source may be converted into several formats:

The Info manual
     The Info format allows searching for topics, commands, functions,
     etc.  from the many Indices. The command `makeinfo zsh.texi' is
     used to produce the Info documentation.

The printed manual
     The command `texi2dvi zsh.texi' will output zsh.dvi which can then
     be processed with `dvips' and optionally `gs' (Ghostscript) to
     produce a nicely formatted printed manual.

The HTML manual
     An HTML version of this manual is available at the Zsh web site
     via:

     http://zsh.sunsite.dk/Doc/.

     (The HTML version is produced with `texi2html', which may be
     obtained from
     http://www.mathematik.uni-kl.de/~obachman/Texi2html/. The command
     is `texi2html -split chapter -expand info zsh.texi'.  If necessary,
     upgrade to version 1.64 of texi2html.)

For those who do not have the necessary tools to process texinfo,
precompiled documentation (PostScript, dvi, info and HTML formats) is
available from the zsh archive site or its mirrors, in the file
zsh-doc.tar.gz. (See *Note Availability:: for a list of sites.)


File: zsh.info,  Node: Introduction,  Next: Invocation,  Prev: The Z Shell Manual,  Up: Top

Introduction
************

Zsh is a UNIX command interpreter (shell) usable as an interactive
login shell and as a shell script command processor.  Of the standard
shells, zsh most closely resembles `ksh' but includes many
enhancements.  Zsh has command line editing, builtin spelling
correction, programmable command completion, shell functions (with
autoloading), a history mechanism, and a host of other features.

* Menu:

* Author::
* Availability::
* Mailing Lists::
* The Zsh FAQ::
* The Zsh Web Page::
* The Zsh Userguide::
* See Also::


File: zsh.info,  Node: Author,  Next: Availability,  Up: Introduction

Author
======

Zsh was originally written by Paul Falstad <pf@zsh.org>.  Zsh is now
maintained by the members of the zsh-workers mailing list
<zsh-workers@sunsite.dk>.  The development is currently coordinated by
Peter Stephenson <pws@zsh.org>.  The coordinator can be contacted at
<coordinator@zsh.org>, but matters relating to the code should
generally go to the mailing list.


File: zsh.info,  Node: Availability,  Next: Mailing Lists,  Prev: Author,  Up: Introduction

Availability
============

Zsh is available from the following anonymous FTP sites.  These mirror
sites are kept frequently up to date.  The sites marked with _(H)_ may
be mirroring ftp.cs.elte.hu instead of the primary site.

Primary site
     ftp://ftp.zsh.org/pub/zsh/
     http://www.zsh.org/pub/zsh/

Australia
     ftp://ftp.zsh.org/pub/zsh/
     http://www.zsh.org/pub/zsh/

Denmark
     ftp://sunsite.dk/pub/unix/shells/zsh/

Finland
     ftp://ftp.funet.fi/pub/unix/shells/zsh/

Germany
     ftp://ftp.fu-berlin.de/pub/unix/shells/zsh/  _(H)_
     ftp://ftp.gmd.de/packages/zsh/
     ftp://ftp.uni-trier.de/pub/unix/shell/zsh/

Hungary
     ftp://ftp.cs.elte.hu/pub/zsh/
     http://www.cs.elte.hu/pub/zsh/
     ftp://ftp.kfki.hu/pub/packages/zsh/

Israel
     ftp://ftp.math.technion.ac.il/pub/zsh/
     http://www.math.technion.ac.il/pub/zsh/

Japan
     ftp://ftp.win.ne.jp/pub/shell/zsh/
     ftp://ftp.ayamura.org/pub/zsh/

Korea
     ftp://linux.sarang.net/mirror/system/shell/zsh/

Netherlands
     ftp://ftp.demon.nl/pub/mirrors/zsh/

Norway
     ftp://ftp.uit.no/pub/unix/shells/zsh/

Poland
     ftp://sunsite.icm.edu.pl/pub/unix/shells/zsh/

Romania
     ftp://ftp.roedu.net/pub/mirrors/ftp.zsh.org/pub/zsh/
     ftp://ftp.kappa.ro/pub/mirrors/ftp.zsh.org/pub/zsh/

Slovenia
     ftp://ftp.siol.net/mirrors/zsh/

Sweden
     ftp://ftp.lysator.liu.se/pub/unix/zsh/

UK
     ftp://ftp.net.lut.ac.uk/zsh/
     ftp://sunsite.org.uk/packages/zsh/

USA
     ftp://uiarchive.uiuc.edu/mirrors/ftp/ftp.zsh.org/pub/
     ftp://ftp.rge.com/pub/shells/zsh/
     http://zsh.disillusion.org/
     http://foad.org/zsh/

The up-to-date source code is available via anonymous CVS from
Sourceforge.  See http://sourceforge.net/projects/zsh/ for details.


File: zsh.info,  Node: Mailing Lists,  Next: The Zsh FAQ,  Prev: Availability,  Up: Introduction

Mailing Lists
=============

Zsh has 3 mailing lists:

<zsh-announce@sunsite.dk>
     Announcements about releases, major changes in the shell and the
     monthly posting of the Zsh FAQ.  (moderated)

<zsh-users@sunsite.dk>
     User discussions.

<zsh-workers@sunsite.dk>
     Hacking, development, bug reports and patches.

To subscribe or unsubscribe, send mail to the associated administrative
address for the mailing list.

<zsh-announce-subscribe@sunsite.dk>

<zsh-users-subscribe@sunsite.dk>

<zsh-workers-subscribe@sunsite.dk>

<zsh-announce-unsubscribe@sunsite.dk>

<zsh-users-unsubscribe@sunsite.dk>

<zsh-workers-unsubscribe@sunsite.dk>

YOU ONLY NEED TO JOIN ONE OF THE MAILING LISTS AS THEY ARE NESTED.  All
submissions to `zsh-announce' are automatically forwarded to
`zsh-users'.  All submissions to `zsh-users' are automatically
forwarded to `zsh-workers'.

If you have problems subscribing/unsubscribing to any of the mailing
lists, send mail to <listmaster@zsh.org>.  The mailing lists are
maintained by Karsten Thygesen <karthy@kom.auc.dk>.

The mailing lists are archived; the archives can be accessed via the
administrative addresses listed above.  There is also a hypertext
archive, maintained by Geoff Wing <gcw@zsh.org>, available at
http://www.zsh.org/mla/.


File: zsh.info,  Node: The Zsh FAQ,  Next: The Zsh Web Page,  Prev: Mailing Lists,  Up: Introduction

The Zsh FAQ
===========

Zsh has a list of Frequently Asked Questions (FAQ), maintained by Peter
Stephenson <pws@zsh.org>.  It is regularly posted to the newsgroup
`comp.unix.shell' and the `zsh-announce' mailing list.  The latest
version can be found at any of the Zsh FTP sites, or at
http://www.zsh.org/FAQ/.  The contact address for FAQ-related matters
is <faqmaster@zsh.org>.


File: zsh.info,  Node: The Zsh Web Page,  Next: The Zsh Userguide,  Prev: The Zsh FAQ,  Up: Introduction

The Zsh Web Page
================

Zsh has a web page which is located at http://www.zsh.org/.  This is
maintained by Karsten Thygesen <karthy@zsh.org>, of SunSITE Denmark.
The contact address for web-related matters is <webmaster@zsh.org>.


File: zsh.info,  Node: The Zsh Userguide,  Next: See Also,  Prev: The Zsh Web Page,  Up: Introduction

The Zsh Userguide
=================

A userguide is currently in preparation.  It is intended to complement
the manual, with explanations and hints on issues where the manual can
be cabbalistic, hierographic, or downright mystifying (for example, the
word `hierographic' does not exist).  It can be viewed in its current
state at http://zsh.sunsite.dk/Guide/.  At the time of writing, chapters
dealing with startup files and their contents and the new completion
system were essentially complete.

The Zsh Wiki
============

A `wiki' website for zsh has been created at http://www.zshwiki.org/.
This is a site which can be added to and modified directly by users
without any special permission.  You can add your own zsh tips and
configurations.


File: zsh.info,  Node: See Also,  Prev: The Zsh Userguide,  Up: Introduction

See Also
========

man page sh(1), man page csh(1), man page tcsh(1), man page rc(1), man
page bash(1), man page ksh(1)

`IEEE Standard for information Technology - Portable Operating System
Interface (POSIX) - Part 2: Shell and Utilities', IEEE Inc, 1993, ISBN
1-55937-255-9.


File: zsh.info,  Node: Invocation,  Next: Files,  Prev: Introduction,  Up: Top

Invocation
**********

Invocation Options
==================

The following flags are interpreted by the shell when invoked to
determine where the shell will read commands from:

-c
     Take the first argument as a command to execute, rather than
     reading commands from a script or standard input.  If any further
     arguments are given, the first one is assigned to $0, rather than
     being used as a positional parameter.

-i
     Force shell to be interactive.

-s
     Force shell to read commands from the standard input.  If the -s
     flag is not present and an argument is given, the first argument
     is taken to be the pathname of a script to execute.

After the first one or two arguments have been appropriated as
described above, the remaining arguments are assigned to the positional
parameters.

For further options, which are common to invocation and the set
builtin, see *Note Options::.

Options may be specified by name using the -o option.  -o acts like a
single-letter option, but takes a following string as the option name.
For example,

     zsh -x -o shwordsplit scr

runs the script scr, setting the XTRACE option by the corresponding
letter `-x' and the SH_WORD_SPLIT option by name.  Options may be
turned _off_ by name by using +o instead of -o.  -o can be stacked up
with preceding single-letter options, so for example `-xo shwordsplit'
or `-xoshwordsplit' is equivalent to `-x -o shwordsplit'.

Options may also be specified by name in GNU long option style,
`-OPTION-NAME'.  When this is done, `-' characters in the option name
are permitted: they are translated into `_', and thus ignored.  So, for
example, `zsh -sh-word-split' invokes zsh with the SH_WORD_SPLIT option
turned on.  Like other option syntaxes, options can be turned off by
replacing the initial `-' with a `+'; thus `+-sh-word-split' is
equivalent to `-no-sh-word-split'.  Unlike other option syntaxes,
GNU-style long options cannot be stacked with any other options, so for
example `-x-shwordsplit' is an error, rather than being treated like
`-x -shwordsplit'.

The special GNU-style option `-version' is handled; it sends to standard
output the shell's version information, then exits successfully.
`-help' is also handled; it sends to standard output a list of options
that can be used when invoking the shell, then exits successfully.

Option processing may be finished, allowing following arguments that
start with `-' or `+' to be treated as normal arguments, in two ways.
Firstly, a lone `-' (or `+') as an argument by itself ends option
processing.  Secondly, a special option `-' (or `+-'), which may be
specified on its own (which is the standard POSIX usage) or may be
stacked with preceding options (so `-x-' is equivalent to `-x -').
Options are not permitted to be stacked after `-' (so `-x-f' is an
error), but note the GNU-style option form discussed above, where
`-shwordsplit' is permitted and does not end option processing.

Except when the `sh'/`ksh' emulation single-letter options are in
effect, the option `-b' (or `+b') ends option processing.  `-b' is like
`--', except that further single-letter options can be stacked after
the `-b' and will take effect as normal.

* Menu:

* Compatibility::
* Restricted Shell::


File: zsh.info,  Node: Compatibility,  Next: Restricted Shell,  Up: Invocation

Compatibility
=============

Zsh tries to emulate `sh' or `ksh' when it is invoked as sh or ksh
respectively; more precisely, it looks at the first letter of the name
by which it was invoked, excluding any initial `r' (assumed to stand
for `restricted'), and if that is `s' or `k' it will emulate `sh' or
`ksh'.  Furthermore, if invoked as su (which happens on certain systems
when the shell is executed by the su command), the shell will try to
find an alternative name from the SHELL environment variable and
perform emulation based on that.

In `sh' and `ksh' compatibility modes the following parameters are not
special and not initialized by the shell: ARGC, argv, cdpath, fignore,
fpath, HISTCHARS, mailpath, MANPATH, manpath, path, prompt, PROMPT,
PROMPT2, PROMPT3, PROMPT4, psvar, status, watch.

The usual zsh startup/shutdown scripts are not executed.  Login shells
source /etc/profile followed by $HOME/.profile.  If the ENV environment
variable is set on invocation, $ENV is sourced after the profile
scripts.  The value of ENV is subjected to parameter expansion, command
substitution, and arithmetic expansion before being interpreted as a
pathname.  Note that the PRIVILEGED option also affects the execution
of startup files.

The following options are set if the shell is invoked as sh or ksh:
NO_BAD_PATTERN, NO_BANG_HIST, NO_BG_NICE, NO_EQUALS,
NO_FUNCTION_ARGZERO, GLOB_SUBST, NO_GLOBAL_EXPORT, NO_HUP,
INTERACTIVE_COMMENTS, KSH_ARRAYS, NO_MULTIOS, NO_NOMATCH, NO_NOTIFY,
POSIX_BUILTINS, NO_PROMPT_PERCENT, RM_STAR_SILENT, SH_FILE_EXPANSION,
SH_GLOB, SH_OPTION_LETTERS, SH_WORD_SPLIT.  Additionally the BSD_ECHO
and IGNORE_BRACES options are set if zsh is invoked as sh.  Also, the
KSH_OPTION_PRINT, LOCAL_OPTIONS, PROMPT_BANG, PROMPT_SUBST and
SINGLE_LINE_ZLE options are set if zsh is invoked as ksh.


File: zsh.info,  Node: Restricted Shell,  Prev: Compatibility,  Up: Invocation

Restricted Shell
================

When the basename of the command used to invoke zsh starts with the
letter `r' or the `-r' command line option is supplied at invocation,
the shell becomes restricted.  Emulation mode is determined after
stripping the letter `r' from the invocation name.  The following are
disabled in restricted mode:

   * changing directories with the cd builtin

   * changing or unsetting the PATH, path, MODULE_PATH, module_path,
     SHELL, HISTFILE, HISTSIZE, GID, EGID, UID, EUID, USERNAME,
     LD_LIBRARY_PATH, LD_AOUT_LIBRARY_PATH, LD_PRELOAD and
     LD_AOUT_PRELOAD parameters

   * specifying command names containing /

   * specifying command pathnames using hash

   * redirecting output to files

   * using the exec builtin command to replace the shell with another
     command

   * using jobs -Z to overwrite the shell process' argument and
     environment space

   * using the ARGV0 parameter to override argv[0] for external commands

   * turning off restricted mode with set +r or unsetopt RESTRICTED

These restrictions are enforced after processing the startup files.  The
startup files should set up PATH to point to a directory of commands
which can be safely invoked in the restricted environment.  They may
also add further restrictions by disabling selected builtins.

Restricted mode can also be activated any time by setting the
RESTRICTED option.  This immediately enables all the restrictions
described above even if the shell still has not processed all startup
files.


File: zsh.info,  Node: Files,  Next: Shell Grammar,  Prev: Invocation,  Up: Top

Files
*****

Startup/Shutdown Files
======================

Commands are first read from /etc/zshenv; this cannot be overridden.
Subsequent behaviour is modified by the RCS and GLOBAL_RCS options; the
former affects all startup files, while the second only affects those
in the /etc directory.  If one of the options is unset at any point,
any subsequent startup file(s) of the corresponding type will not be
read.  It is also possible for a file in $ZDOTDIR to re-enable
GLOBAL_RCS. Both RCS and GLOBAL_RCS are set by default.

Commands are then read from $ZDOTDIR/.zshenv.  If the shell is a login
shell, commands are read from /etc/zprofile and then $ZDOTDIR/.zprofile.
Then, if the shell is interactive, commands are read from /etc/zshrc
and then $ZDOTDIR/.zshrc.  Finally, if the shell is a login shell,
/etc/zlogin and $ZDOTDIR/.zlogin are read.

When a login shell exits, the files $ZDOTDIR/.zlogout and then
/etc/zlogout are read.  This happens with either an explicit exit via
the exit or logout commands, or an implicit exit by reading end-of-file
from the terminal.  However, if the shell terminates due to exec'ing
another process, the logout files are not read.  These are also
affected by the RCS and GLOBAL_RCS options.  Note also that the RCS
option affects the saving of history files, i.e. if RCS is unset when
the shell exits, no history file will be saved.

If ZDOTDIR is unset, HOME is used instead.  Those files listed above as
being in /etc may be in another directory, depending on the
installation.

As /etc/zshenv is run for all instances of zsh, it is important that it
be kept as small as possible.  In particular, it is a good idea to put
code that does not need to be run for every single shell behind a test
of the form `if [[ -o rcs ]]; then ...' so that it will not be executed
when zsh is invoked with the `-f' option.

Files
=====

$ZDOTDIR/.zshenv

$ZDOTDIR/.zprofile

$ZDOTDIR/.zshrc

$ZDOTDIR/.zlogin

$ZDOTDIR/.zlogout

${TMPPREFIX}*   (default is /tmp/zsh*)

/etc/zshenv

/etc/zprofile

/etc/zshrc

/etc/zlogin

/etc/zlogout    (installation-specific - /etc is the default)

Any of these files may be pre-compiled with the zcompile builtin
command (*Note Shell Builtin Commands::).  If a compiled file exists
(named for the original file plus the .zwc extension) and it is newer
than the original file, the compiled file will be used instead.


File: zsh.info,  Node: Shell Grammar,  Next: Redirection,  Prev: Files,  Up: Top

Shell Grammar
*************

* Menu:

* Simple Commands & Pipelines::
* Precommand Modifiers::
* Complex Commands::
* Alternate Forms For Complex Commands::
* Reserved Words::
* Comments::
* Aliasing::
* Quoting::


File: zsh.info,  Node: Simple Commands & Pipelines,  Next: Precommand Modifiers,  Up: Shell Grammar

Simple Commands & Pipelines
===========================

A _simple command_ is a sequence of optional parameter assignments
followed by blank-separated words, with optional redirections
interspersed.  The first word is the command to be executed, and the
remaining words, if any, are arguments to the command.  If a command
name is given, the parameter assignments modify the environment of the
command when it is executed.  The value of a simple command is its exit
status, or 128 plus the signal number if terminated by a signal.  For
example,

     echo foo

is a simple command with arguments.

A _pipeline_ is either a simple command, or a sequence of two or more
simple commands where each command is separated from the next by `|' or
`|&'.  Where commands are separated by `|', the standard output of the
first command is connected to the standard input of the next.  `|&' is
shorthand for `2>&1 |', which connects both the standard output and the
standard error of the command to the standard input of the next.  The
value of a pipeline is the value of the last command, unless the
pipeline is preceded by `!' in which case the value is the logical
inverse of the value of the last command.  For example,

     echo foo | sed 's/foo/bar/'

is a pipeline, where the output (`foo' plus a newline) of the first
command will be passed to the input of the second.

If a pipeline is preceded by `coproc', it is executed as a coprocess; a
two-way pipe is established between it and the parent shell.  The shell
can read from or write to the coprocess by means of the `>&p' and `<&p'
redirection operators or with `print -p' and `read -p'.  A pipeline
cannot be preceded by both `coproc' and `!'.  If job control is active,
the coprocess can be treated in other than input and output as an
ordinary background job.

A _sublist_ is either a single pipeline, or a sequence of two or more
pipelines separated by `&&' or `||'.  If two pipelines are separated by
`&&', the second pipeline is executed only if the first succeeds
(returns a zero value).  If two pipelines are separated by `||', the
second is executed only if the first fails (returns a nonzero value).
Both operators have equal precedence and are left associative.  The
value of the sublist is the value of the last pipeline executed.  For
example,

     dmesg | grep panic && print yes

is a sublist consisting of two pipelines, the second just a simple
command which will be executed if and only if the grep command returns
a zero value.  If it does not, the value of the sublist is that return
value, else it is the value returned by the print (almost certainly
zero).

A _list_ is a sequence of zero or more sublists, in which each sublist
is terminated by `;', `&', `&|', `&!', or a newline.  This terminator
may optionally be omitted from the last sublist in the list when the
list appears as a complex command inside `(...)'  or `{...}'.  When a
sublist is terminated by `;' or newline, the shell waits for it to
finish before executing the next sublist.  If a sublist is terminated
by a `&', `&|', or `&!', the shell executes the last pipeline in it in
the background, and does not wait for it to finish (note the difference
from other shells which execute the whole sublist in the background).
A backgrounded pipeline returns a status of zero.

More generally, a list can be seen as a set of any shell commands
whatsoever, including the complex commands below; this is implied
wherever the word `list' appears in later descriptions.  For example,
the commands in a shell function form a special sort of list.


File: zsh.info,  Node: Precommand Modifiers,  Next: Complex Commands,  Prev: Simple Commands & Pipelines,  Up: Shell Grammar

Precommand Modifiers
====================

A simple command may be preceded by a _precommand modifier_, which will
alter how the command is interpreted.  These modifiers are shell
builtin commands with the exception of nocorrect which is a reserved
word.

-
     The command is executed with a `-' prepended to its argv[0] string.

noglob
     Filename generation (globbing) is not performed on any of the
     words.

nocorrect
     Spelling correction is not done on any of the words.  This must
     appear before any other precommand modifier, as it is interpreted
     immediately, before any parsing is done.  It has no effect in
     non-interactive shells.

exec
     The command is executed in the parent shell without forking.

command
     The command word is taken to be the name of an external command,
     rather than a shell function or builtin.

builtin
     The command word is taken to be the name of a builtin command,
     rather than a shell function or external command.


File: zsh.info,  Node: Complex Commands,  Next: Alternate Forms For Complex Commands,  Prev: Precommand Modifiers,  Up: Shell Grammar

Complex Commands
================

A _complex command_ in zsh is one of the following:

if LIST then LIST [ elif LIST then LIST ] ... [ else LIST ] fi
     The if LIST is executed, and if it returns a zero exit status, the
     then LIST is executed.  Otherwise, the elif LIST is executed and
     if its value is zero, the then LIST is executed.  If each elif
     LIST returns nonzero, the else LIST is executed.

for NAME ... [ in WORD ... ] TERM do LIST done
     where TERM is at least one newline or ;.  Expand the list of
     WORDs, and set the parameter NAME to each of them in turn,
     executing LIST each time.  If the in WORD is omitted, use the
     positional parameters instead of the WORDs.

     More than one parameter NAME can appear before the list of WORDs.
     If N NAMEs are given, then on each execution of the loop the next
     N WORDs are assigned to the corresponding parameters.  If there
     are more NAMEs than remaining WORDs, the remaining parameters are
     each set to the empty string.  Execution of the loop ends when
     there is no remaining WORD to assign to the first NAME.  It is
     only possible for in to appear as the first NAME in the list, else
     it will be treated as marking the end of the list.

for (( [EXPR1] ; [EXPR2] ; [EXPR3] )) do LIST done
     The arithmetic expression EXPR1 is evaluated first (see *Note
     Arithmetic Evaluation::).  The arithmetic expression EXPR2 is
     repeatedly evaluated until it evaluates to zero and when non-zero,
     LIST is executed and the arithmetic expression EXPR3 evaluated.
     If any expression is omitted, then it behaves as if it evaluated
     to 1.

while LIST do LIST done
     Execute the do LIST as long as the while LIST returns a zero exit
     status.

until LIST do LIST done
     Execute the do LIST as long as until LIST returns a nonzero exit
     status.

repeat WORD do LIST done
     WORD is expanded and treated as an arithmetic expression, which
     must evaluate to a number N.  LIST is then executed N times.

case WORD in [ [(] PATTERN [ | PATTERN ] ... ) LIST (;;|;&) ] ... esac
     Execute the LIST associated with the first PATTERN that matches
     WORD, if any.  The form of the patterns is the same as that used
     for filename generation.  See *Note Filename Generation::.  If the
     LIST that is executed is terminated with ;& rather than ;;, the
     following list is also executed.  This continues until either a
     list is terminated with ;; or the esac is reached.

select NAME [ in WORD ... TERM ] do LIST done
     where TERM is one or more newline or ; to terminate the WORDs.
     Print the set of WORDs, each preceded by a number.  If the in WORD
     is omitted, use the positional parameters.  The PROMPT3 prompt is
     printed and a line is read from the line editor if the shell is
     interactive and that is active, or else standard input.  If this
     line consists of the number of one of the listed WORDs, then the
     parameter NAME is set to the WORD corresponding to this number.
     If this line is empty, the selection list is printed again.
     Otherwise, the value of the parameter NAME is set to null.  The
     contents of the line read from standard input is saved in the
     parameter REPLY.  LIST is executed for each selection until a
     break or end-of-file is encountered.

( LIST )
     Execute LIST in a subshell.  Traps set by the trap builtin are
     reset to their default values while executing LIST.

{ LIST }
     Execute LIST.

{ TRY-LIST } always { ALWAYS-LIST }
     First execute TRY-LIST.  Regardless of errors, or break, continue,
     or return commands encountered within TRY-LIST, execute
     ALWAYS-LIST.  Execution then continues from the result of the
     execution of TRY-LIST; in other words, any error, or break,
     continue, or return command is treated in the normal way, as if
     ALWAYS-LIST were not present.  The two chunks of code are referred
     to as the `try block' and the `always block'.

     Optional newlines or semicolons may appear after the always; note,
     however, that they may _not_ appear between the preceeding closing
     brace and the always.

     An `error' in this context is a condition such as a syntax error
     which causes the shell to abort execution of the current function,
     script, or list.  Syntax errors encountered while the shell is
     parsing the code do not cause the ALWAYS-LIST to be executed.  For
     example, an erroneously constructed if block in try-list would
     cause the shell to abort during parsing, so that always-list would
     not be executed, while an erroneous substitution such as ${*foo*}
     would cause a run-time error, after which always-list would be
     executed.

     An error condition can be tested and reset with the special integer
     variable TRY_BLOCK_ERROR.  Outside an always-list the value is
     irrelevant, but it is initialised to -1.  Inside always-list, the
     value is 1 if an error occurred in the try-list, else 0.  If
     TRY_BLOCK_ERROR is set to 0 during the always-list, the error
     condition caused by the try-list is reset, and shell execution
     continues normally after the end of always-list.  Altering the
     value during the try-list is not useful (unless this forms part of
     an enclosing always block).

     Regardless of TRY_BLOCK_ERROR, after the end of always-list the
     normal shell status $? is the value returned from always-list.
     This will be non-zero if there was an error, even if
     TRY_BLOCK_ERROR was set to zero.

     The following executes the given code, ignoring any errors it
     causes.  This is an alternative to the usual convention of
     protecting code by executing it in a subshell.

          {
              # code which may cause an error
            } always {
              # This code is executed regardless of the error.
              (( TRY_BLOCK_ERROR = 0 ))
          }
          # The error condition has been reset.

     An exit command encountered in try-list does _not_ cause the
     execution of ALWAYS-LIST.  Instead, the shell exits immediately
     after any EXIT trap has been executed.

function WORD ... [ () ] [ TERM ] { LIST }
WORD ... () [ TERM ] { LIST }
WORD ... () [ TERM ] COMMAND
     where TERM is one or more newline or ;.  Define a function which
     is referenced by any one of WORD.  Normally, only one WORD is
     provided; multiple WORDs are usually only useful for setting traps.
     The body of the function is the LIST between the { and }.  See
     *Note Functions::.

     If the option SH_GLOB is set for compatibility with other shells,
     then whitespace may appear between between the left and right
     parentheses when there is a single WORD;  otherwise, the
     parentheses will be treated as forming a globbing pattern in that
     case.

time [ PIPELINE ]
     The PIPELINE is executed, and timing statistics are reported on
     the standard error in the form specified by the TIMEFMT parameter.
     If PIPELINE is omitted, print statistics about the shell process
     and its children.

[[ EXP ]]
     Evaluates the conditional expression EXP and return a zero exit
     status if it is true.  See *Note Conditional Expressions:: for a
     description of EXP.


File: zsh.info,  Node: Alternate Forms For Complex Commands,  Next: Reserved Words,  Prev: Complex Commands,  Up: Shell Grammar

Alternate Forms For Complex Commands
====================================

Many of zsh's complex commands have alternate forms.  These particular
versions of complex commands should be considered deprecated and may be
removed in the future.  The versions in the previous section should be
preferred instead.

The short versions below only work if SUBLIST is of the form `{ LIST }'
or if the SHORT_LOOPS option is set.  For the if, while and until
commands, in both these cases the test part of the loop must also be
suitably delimited, such as by `[[ ... ]]' or `(( ... ))', else the end
of the test will not be recognized.  For the for, repeat, case and
select commands no such special form for the arguments is necessary,
but the other condition (the special form of SUBLIST or use of the
SHORT_LOOPS option) still applies.

if LIST { LIST } [ elif LIST { LIST } ] ... [ else { LIST } ]
     An alternate form of if.  The rules mean that

          if [[ -o ignorebraces ]] {
            print yes
          }

     works, but

          if true {  # Does not work!
            print yes
          }

     does _not_, since the test is not suitably delimited.

if LIST SUBLIST
     A short form of the alternate `if'.  The same limitations on the
     form of LIST apply as for the previous form.

for NAME ... ( WORD ... ) SUBLIST
     A short form of for.

for NAME ... [ in WORD ... ] TERM SUBLIST
     where TERM is at least one newline or ;.  Another short form of
     for.

for (( [EXPR1] ; [EXPR2] ; [EXPR3] )) SUBLIST
     A short form of the arithmetic for command.

foreach NAME ... ( WORD ... ) LIST end
     Another form of for.

while LIST { LIST }
     An alternative form of while.  Note the limitations on the form of
     LIST mentioned above.

until LIST { LIST }
     An alternative form of until.  Note the limitations on the form of
     LIST mentioned above.

repeat WORD SUBLIST
     This is a short form of repeat.

case WORD { [ [(] PATTERN [ | PATTERN ] ... ) LIST (;;|;&) ] ... }
     An alternative form of case.

select NAME [ in WORD TERM ] SUBLIST
     where TERM is at least one newline or ;.  A short form of select.


File: zsh.info,  Node: Reserved Words,  Next: Comments,  Prev: Alternate Forms For Complex Commands,  Up: Shell Grammar

Reserved Words
==============

The following words are recognized as reserved words when used as the
first word of a command unless quoted or disabled using disable -r:

do done esac then elif else fi for case if while function repeat time
until select coproc nocorrect foreach end ! [[ { }

Additionally, `}' is recognized in any position if the IGNORE_BRACES
option is not set.


File: zsh.info,  Node: Comments,  Next: Aliasing,  Prev: Reserved Words,  Up: Shell Grammar

Comments
========

In noninteractive shells, or in interactive shells with the
INTERACTIVE_COMMENTS option set, a word beginning with the third
character of the histchars parameter (`#' by default) causes that word
and all the following characters up to a newline to be ignored.


File: zsh.info,  Node: Aliasing,  Next: Quoting,  Prev: Comments,  Up: Shell Grammar

Aliasing
========

Every token in the shell input is checked to see if there is an alias
defined for it.  If so, it is replaced by the text of the alias if it
is in command position (if it could be the first word of a simple
command), or if the alias is global.  If the text ends with a space,
the next word in the shell input is treated as though it were in
command position for purposes of alias expansion.  An alias is defined
using the alias builtin; global aliases may be defined using the -g
option to that builtin.

Alias expansion is done on the shell input before any other expansion
except history expansion.  Therefore, if an alias is defined for the
word foo, alias expansion may be avoided by quoting part of the word,
e.g. \foo.  But there is nothing to prevent an alias being defined for
\foo as well.


File: zsh.info,  Node: Quoting,  Prev: Aliasing,  Up: Shell Grammar

Quoting
=======

A character may be QUOTED (that is, made to stand for itself) by
preceding it with a `\'.  `\' followed by a newline is ignored.

A string enclosed between `$'' and `'' is processed the same way as the
string arguments of the print builtin, and the resulting string is
considered to be entirely quoted.  A literal `'' character can be
included in the string by using the `\'' escape.

All characters enclosed between a pair of single quotes ('') that is
not preceded by a `$' are quoted.  A single quote cannot appear within
single quotes unless the option RC_QUOTES is set, in which case a pair
of single quotes are turned into a single quote.  For example,

     print ''''

outputs nothing apart from a newline if RC_QUOTES is not set, but one
single quote if it is set.

Inside double quotes (""), parameter and command substitution occur,
and `\' quotes the characters `\', ``', `"', and `$'.


File: zsh.info,  Node: Redirection,  Next: Command Execution,  Prev: Shell Grammar,  Up: Top

Redirection
***********

If a command is followed by & and job control is not active, then the
default standard input for the command is the empty file /dev/null.
Otherwise, the environment for the execution of a command contains the
file descriptors of the invoking shell as modified by input/output
specifications.

The following may appear anywhere in a simple command or may precede or
follow a complex command.  Expansion occurs before WORD or DIGIT is
used except as noted below.  If the result of substitution on WORD
produces more than one filename, redirection occurs for each separate
filename in turn.

< WORD
     Open file WORD for reading as standard input.

<> WORD
     Open file WORD for reading and writing as standard input.  If the
     file does not exist then it is created.

> WORD
     Open file WORD for writing as standard output.  If the file does
     not exist then it is created.  If the file exists, and the CLOBBER
     option is unset, this causes an error; otherwise, it is truncated
     to zero length.

>| WORD
>! WORD
     Same as >, except that the file is truncated to zero length if it
     exists, even if CLOBBER is unset.

>> WORD
     Open file WORD for writing in append mode as standard output.  If
     the file does not exist, and the CLOBBER option is unset, this
     causes an error; otherwise, the file is created.

>>| WORD
>>! WORD
     Same as >>, except that the file is created if it does not exist,
     even if CLOBBER is unset.

<<[-] WORD
     The shell input is read up to a line that is the same as WORD, or
     to an end-of-file.  No parameter expansion, command substitution or
     filename generation is performed on WORD.  The resulting document,
     called a _here-document_, becomes the standard input.

     If any character of WORD is quoted with single or double quotes or
     a `\', no interpretation is placed upon the characters of the
     document.  Otherwise, parameter and command substitution occurs,
     `\' followed by a newline is removed, and `\' must be used to
     quote the characters `\', `$', ``' and the first character of WORD.

     Note that WORD itself does not undergo shell expansion.  Backquotes
     in WORD do not have their usual effect; instead they behave
     similarly to double quotes, except that the backquotes themselves
     are passed through unchanged.  (This information is given for
     completeness and it is not recommended that backquotes be used.)
     Quotes in the form $'...' have their standard effect of expanding
     backslashed references to special characters.

     If <<- is used, then all leading tabs are stripped from WORD and
     from the document.

<<< WORD
     Perform shell expansion on WORD and pass the result to standard
     input.  This is known as a _here-string_.  Compare the use of WORD
     in here-documents above, where WORD does not undergo shell
     expansion.

<& NUMBER
>& NUMBER
     The standard input/output is duplicated from file descriptor
     NUMBER (see man page dup2(2)).

<& -
>& -
     Close the standard input/output.

<& p
>& p
     The input/output from/to the coprocess is moved to the standard
     input/output.

>& WORD
&> WORD
     (Except where `>& WORD' matches one of the above syntaxes; `&>'
     can always be used to avoid this ambiguity.)  Redirects both
     standard output and standard error (file descriptor 2) in the
     manner of `> WORD'.  Note that this does _not_ have the same
     effect as `> WORD 2>&1' in the presence of multios (see the
     section below).

>&| WORD
>&! WORD
&>| WORD
&>! WORD
     Redirects both standard output and standard error (file descriptor
     2) in the manner of `>| WORD'.

>>& WORD
&>> WORD
     Redirects both standard output and standard error (file descriptor
     2) in the manner of `>> WORD'.

>>&| WORD
>>&! WORD
&>>| WORD
&>>! WORD
     Redirects both standard output and standard error (file descriptor
     2) in the manner of `>>| WORD'.

If one of the above is preceded by a digit, then the file descriptor
referred to is that specified by the digit instead of the default 0 or
1.  The order in which redirections are specified is significant.  The
shell evaluates each redirection in terms of the (_file descriptor_,
_file_) association at the time of evaluation.  For example:

     ... 1>FNAME 2>&1

first associates file descriptor 1 with file FNAME.  It then associates
file descriptor 2 with the file associated with file descriptor 1 (that
is, FNAME).  If the order of redirections were reversed, file
descriptor 2 would be associated with the terminal (assuming file
descriptor 1 had been) and then file descriptor 1 would be associated
with file FNAME.

The `|&' command separator described in *Note Simple Commands &
Pipelines:: is a shorthand for `2>&1 |'.

For output redirections only, if WORD is of the form `>(LIST)' then the
output is piped to the command represented by LIST.  See *Note Process
Substitution::.

Multios
=======

If the user tries to open a file descriptor for writing more than once,
the shell opens the file descriptor as a pipe to a process that copies
its input to all the specified outputs, similar to `tee', provided the
MULTIOS option is set, as it is by default.  Thus:

     date >foo >bar

writes the date to two files, named `foo' and `bar'.  Note that a pipe
is an implicit redirection; thus

     date >foo | cat

writes the date to the file `foo', and also pipes it to cat.

If the MULTIOS option is set, the word after a redirection operator is
also subjected to filename generation (globbing).  Thus

     : > *

will truncate all files in the current directory, assuming there's at
least one.  (Without the MULTIOS option, it would create an empty file
called `*'.)  Similarly, you can do

     echo exit 0 >> *.sh

If the user tries to open a file descriptor for reading more than once,
the shell opens the file descriptor as a pipe to a process that copies
all the specified inputs to its output in the order specified, similar
to `cat', provided the MULTIOS option is set.  Thus

     sort <foo <fubar

or even

     sort <f{oo,ubar}

is equivalent to `cat foo fubar | sort'.

Note that a pipe is an implicit redirection; thus

     cat bar | sort <foo

is equivalent to `cat bar foo | sort' (note the order of the inputs).

If the MULTIOS option is _un_set, each redirection replaces the
previous redirection for that file descriptor.  However, all files
redirected to are actually opened, so

     echo foo > bar > baz

when MULTIOS is unset will truncate bar, and write `foo' into baz.

There is a problem when an output multio is attached to an external
program.  A simple example shows this:

     cat file >file1 >file2
     cat file1 file2

Here, it is possible that the second `cat' will not display the full
contents of file1 and file2 (i.e. the original contents of file
repeated twice).

The reason for this is that the multios are spawned after the cat
process is forked from the parent shell, so the parent shell does not
wait for the multios to finish writing data.  This means the command as
shown can exit before file1 and file2 are completely written.  As a
workaround, it is possible to run the cat process as part of a job in
the current shell:

     { cat file } >file >file2

Here, the {...} job will pause to wait for both files to be written.

Redirections with no command
============================

When a simple command consists of one or more redirection operators and
zero or more parameter assignments, but no command name, zsh can behave
in several ways.

If the parameter NULLCMD is not set or the option CSH_NULLCMD is set,
an error is caused.  This is the `csh' behavior and CSH_NULLCMD is set
by default when emulating `csh'.

If the option SH_NULLCMD is set, the builtin `:' is inserted as a
command with the given redirections.  This is the default when emulating
`sh' or `ksh'.

Otherwise, if the parameter NULLCMD is set, its value will be used as a
command with the given redirections.  If both NULLCMD and READNULLCMD
are set, then the value of the latter will be used instead of that of
the former when the redirection is an input.  The default for NULLCMD
is `cat' and for READNULLCMD is `more'. Thus

     < file

shows the contents of file on standard output, with paging if that is a
terminal.  NULLCMD and READNULLCMD may refer to shell functions.


File: zsh.info,  Node: Command Execution,  Next: Functions,  Prev: Redirection,  Up: Top

Command Execution
*****************

If a command name contains no slashes, the shell attempts to locate it.
If there exists a shell function by that name, the function is invoked
as described in *Note Functions::.  If there exists a shell builtin by
that name, the builtin is invoked.

Otherwise, the shell searches each element of $path for a directory
containing an executable file by that name.  If the search is
unsuccessful, the shell prints an error message and returns a nonzero
exit status.

If execution fails because the file is not in executable format, and
the file is not a directory, it is assumed to be a shell script.
/bin/sh is spawned to execute it.  If the program is a file beginning
with `#!', the remainder of the first line specifies an interpreter for
the program.  The shell will execute the specified interpreter on
operating systems that do not handle this executable format in the
kernel.

