\input texinfo.tex @c -*- texinfo -*-
@c %**start of header
@setfilename zsh.info
@settitle    zsh
@c %**end of header

@ifinfo
@c Note to RedHat: Do NOT change this to @{@}.  It really should be @'@'.
@set dsq @'@'
@end ifinfo
@iftex
@c The sequence {} disappears completely in TeX, leaving only the quotes.
@set dsq '{}'
@end iftex

@setchapternewpage odd
@iftex
@finalout
@afourpaper
@end iftex

@set EDITION 3.0
@set VERSION 3.0.6
@set UPDATED 31 July 1999

@ifinfo
@noindent
This is a texinfo version of the man page for the Z Shell, originally by 
Paul Falstad.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end ifinfo

@titlepage
@title The Z Shell Guide
@subtitle Document Edition @value{EDITION} 
@subtitle @value{UPDATED}
@author Original documentation by Paul Falstad
@page
@vskip 0pt plus 1filll
@noindent
Document Edition @value{EDITION}, last updated @value{UPDATED},
of @cite{The Z Shell Guide}, for zsh, Version @value{VERSION}.

This is a texinfo version of the man page for the Z Shell, originally by 
Paul Falstad.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.
@end titlepage

@ifinfo
@node Top, The Z Shell Guide, (dir), (dir)
@top The Z Shell Guide

@noindent
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.

@noindent
Document Edition @value{EDITION}, last updated @value{UPDATED},
of @cite{The Z Shell Guide}, for zsh, Version @value{VERSION}.
@end ifinfo

@menu
* The Z Shell Guide::			
* Introduction::			
* Invocation::				
* Startup/Shutdown Files::			
* Shell Grammar::			
* Expansion::				 
* Redirection::				
* Command Execution::			
* Functions::				 
* Jobs & Signals::			 				
* Arithmetic Evaluation::		
* Conditional Expressions::		
* Compatibility::			
* Zsh Line Editor::			 
* Parameters::				
* Options::				
* Shell Builtin Commands::		 
* Programmable Completion::		

 --- Indices ---

* Concept Index::		
* Variables Index::             
* Options Index::               
* Functions Index::             
* Editor Functions Index::      
* Keystroke Index::             

 --- The Detailed Node Listing ---

Introduction

* Author::				
* Availability::			
* Undocumented Features::
* Mailing Lists::			
* Further Information::			

Shell Grammar

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

Expansion

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

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

Parameters

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

Options

* Description of Options::
* Single Letter Options::

Programmable Completion

* Command Flags::
* Options Flags::
* Alternative Completion::
* Extended Completion::
* Example::
@end menu


@node The Z Shell Guide, Introduction, Top, Top
@chapter The Z Shell Guide

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

@section Origins

@noindent
The texinfo guide was originally put together by Jonathan Hardwick,
@code{jch@@cs.cmu.edu}, who converted the @file{zsh.1} file distributed
with zsh v2.5.0.  After a period of neglect it was updated by Clive Messer,
@code{clive@@epos.demon.co.uk} to reflect the many changes made to both the
shell, the original @file{zsh.1}, (which due to its size and ever
increasing number of options has since been split into several man-pages:@:
@file{zsh.1}, @file{zshall.1}, @file{zshbuiltins.1}, @file{zshcompctl.1},
@file{zshcompctl.1}, @file{zshexpn.1}, @file{zshmisc.1}, @file{zshoptions.1},
@file{zshparam.1}, @file{zshzle.1}), and also now includes other useful
information from the @code{META-FAQ}.

@section Producing documentation from zsh.texi.

@noindent
Whilst this guide for the most part duplicates the man-pages,
(suitably marked-up into texinfo), and is not intended to replace them, it 
does offer several advantages over them, not least that the texinfo source 
may be converted into several formats, e.g.,

@table @asis
@item The Info guide.
The Info format allows searching for topics, commands, functions, etc.@:
from the many Indices. The command @code{makeinfo zsh.texi} is used to
produce the Info documentation.

@item The printed guide.
The command @code{texi2dvi zsh.texi} will output @file{zsh.dvi} which can 
then be processed with @code{dvips} and optionally @code{gs} (Ghostscript) to 
produce a nicely formatted printed guide.

@item The html guide.
An HTML version of this guide is available at the Zsh web site via
@code{http://sunsite.auc.dk/zsh/Doc/index.html}.  Note that the on-line
guide may describe a different (usually more recent) version of Zsh.
(The HTML version is produced with @cite{texi2html}, which may be obtained
from @code{http://wwwcn.cern.ch/dci/texi2html/}. The command is
`@code{texi2html -split_chapter -expandinfo zsh.texi}'.)

@end table

@noindent
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, 
@file{zsh-doc.tar.gz}. (@xref{Availability}, for a list of sites.)

@node Introduction, Invocation, The Z Shell Guide, Top
@chapter Introduction

@noindent
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::
* Undocumented Features::
* Mailing Lists::
* Further Information::
@end menu


@node Author, Availability,  , Introduction
@section Author
@cindex author
@noindent
Zsh was originally written by Paul Falstad @code{<pf@@zsh.org>}.  Zsh is
now maintained by the members of the zsh-workers mailing list
@code{<zsh-workers@@sunsite.auc.dk>}.  New development is currently
coordinated by Peter Stephenson @code{<pws@@zsh.org>}.  The
coordinator can be contacted at @code{<coordinator@@zsh.org>}, but
matters relating to the code should generally go to the mailing list.


@node Availability, Undocumented Features, Author, Introduction
@section Availability

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

@noindent
@cindex FTP sites for zsh
@cindex acquiring zsh by FTP
@cindex availability of zsh
@table @asis
@item Primary site
@t{ftp://ftp.zsh.org/pub/zsh/}@*
@t{http://www.zsh.org/pub/zsh/}

@item Australia
@t{ftp://ftp.zsh.org/pub/zsh/}@*
@t{http://www.zsh.org/pub/zsh/}@*
@t{ftp://ftp.ips.gov.au/pub/packages/zsh/}  @emph{(H)}

@item Denmark
@t{ftp://sunsite.auc.dk/pub/unix/shells/zsh/}

@item Finland
@t{ftp://ftp.funet.fi/pub/unix/shells/zsh/}

@item France
@t{ftp://ftp.cenatls.cena.dgac.fr/pub/shells/zsh/}

@item Germany
@t{ftp://ftp.fu-berlin.de/pub/unix/shells/zsh/}  @emph{(H)}@*
@t{ftp://ftp.gmd.de/packages/zsh/}@*
@t{ftp://ftp.uni-trier.de/pub/unix/shell/zsh/}

@item Hungary
@t{ftp://ftp.cs.elte.hu/pub/zsh/}@*
@t{http://www.cs.elte.hu/pub/zsh/}@*
@t{ftp://ftp.kfki.hu/pub/packages/zsh/}

@item Israel
@t{ftp://ftp.math.technion.ac.il/mirror/ftp.zsh.org/pub/zsh/}@*
@t{http://www.math.technion.ac.il/mirror/ftp.zsh.org/pub/zsh/}

@item Italy
@t{ftp://ftp.unina.it/pub/Unix/pkgs/shell/zsh/}

@item Japan
@t{ftp://ftp.nisiq.net/pub/shells/zsh/}  @emph{(H)}@*
@t{ftp://ftp.win.ne.jp/pub/shell/zsh/}

@item Norway
@t{ftp://ftp.uit.no/pub/unix/shells/zsh/}

@item Poland
@t{ftp://sunsite.icm.edu.pl/pub/unix/shells/zsh/}

@item Romania
@t{ftp://ftp.roedu.net/pub/mirrors/ftp.zsh.org/pub/zsh/}

@item Slovenia
@t{ftp://ftp.siol.net/mirrors/zsh/}

@item Sweden
@t{ftp://ftp.lysator.liu.se/pub/unix/zsh/}

@item UK
@t{ftp://ftp.net.lut.ac.uk/zsh/}@*
@t{ftp://sunsite.org.uk/packages/zsh/}

@item USA
@t{ftp://uiarchive.uiuc.edu/pub/packages/shells/zsh/}@*
@t{ftp://ftp.rge.com/pub/shells/zsh/}@*
@t{ftp://foad.org/pub/zsh/}@*
@t{http://foad.org/zsh/}

@end table

@node Undocumented Features, Mailing Lists, Availability, Introduction
@section Undocumented Features
@cindex features, undocumented

@noindent
Known only to the recipients of the @code{zsh-workers} mailing list.@*
To join the mailing lists, see @ref{Mailing Lists}.


@node Mailing Lists, Further Information, Undocumented Features, Introduction
@section Mailing Lists
@cindex mailing lists

@noindent
Zsh has 3 mailing lists:

@noindent
@table @asis
@item @code{<zsh-announce@@sunsite.auc.dk>}
Announcements about releases, major changes in the shell and the
monthly posting of the Zsh FAQ.  (moderated)

@item @code{<zsh-users@@sunsite.auc.dk>}
User discussions.

@item @code{<zsh-workers@@sunsite.auc.dk>}
Hacking, development, bug reports and patches.

@end table

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

@noindent
@table @asis
@item @code{<zsh-announce-subscribe@@sunsite.auc.dk>}
@item @code{<zsh-users-subscribe@@sunsite.auc.dk>}
@item @code{<zsh-workers-subscribe@@sunsite.auc.dk>}

@noindent
@item @code{<zsh-announce-unsubscribe@@sunsite.auc.dk>}
@item @code{<zsh-users-unsubscribe@@sunsite.auc.dk>}
@item @code{<zsh-workers-unsubscribe@@sunsite.auc.dk>}
@end table

@noindent
YOU ONLY NEED TO JOIN ONE OF THE MAILING LISTS AS THEY ARE NESTED.
All submissions to @cite{zsh-announce} are automatically forwarded to
@cite{zsh-users}.  All submissions to @cite{zsh-users} are automatically
forwarded to @cite{zsh-workers}.

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

@noindent
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 @code{<gcw@@zsh.org>}, available at
@code{http://www.zsh.org/mla/}.
@node Further Information,  , Mailing Lists, Introduction
@section Further Information

@menu
* The Zsh FAQ::
* The Zsh Web Page::
* See Also::
@end menu

@node The Zsh FAQ,  The Zsh Web Page,  , Further Information
@subsection The Zsh FAQ

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


@node The Zsh Web Page, See Also, The Zsh FAQ, Further Information
@subsection The Zsh Web Page

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


@node See Also,  , The Zsh Web Page, Further Information
@subsection See Also

@noindent
sh(1), csh(1), tcsh(1), rc(1), bash(1), ksh(1), zshbuiltins(1),  
zshcompctl(1), zshexpn(1), zshparam(1), zshzle(1), zshoptions(1), 
zshmisc(1)

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


@node Invocation, Startup/Shutdown Files, Introduction, Top
@chapter Invocation
@cindex invocation

@noindent
If the @samp{-s} flag is not present and an argument is given, the first 
argument is taken to be the pathname of a script to execute.  The remaining 
arguments are assigned to the positional parameters.  The following flags 
are interpreted by the shell when invoked:

@table @code
@item -c @var{string}
@cindex flags, shell
@cindex shell flags
Read commands from @var{string}.

@item -i
Force shell to be interactive.

@item -s
Read command from the standard input.
@end table


@node Startup/Shutdown Files, Shell Grammar, Invocation, Top
@chapter Startup/Shutdown Files
@cindex files, startup
@cindex files, shutdown

@noindent
Commands are first read from @file{/etc/zshenv}.  If the @code{RCS} 
@cindex files, startup
@cindex startup files
option is unset within
@file{/etc/zshenv}, all other initialization files are skipped.
Otherwise, commands are read from @file{$ZDOTDIR/.zshenv} (if
@code{ZDOTDIR} is unset, @code{HOME} is used instead).  If the first
character of argument zero passed to the shell is @code{-}, or if the
@samp{-l} flag is present, then the shell is assumed to be a login
shell, and commands are read from @file{/etc/zprofile} and then
@file{$ZDOTDIR/.zprofile}.  Then, if the shell is interactive and the
@code{NO_RCS} option is unset, commands are read from @file{/etc/zshrc}
@pindex NO_RCS, use of
and then @file{$ZDOTDIR/.zshrc}.  Finally, if the shell is a login
shell, @file{/etc/zlogin} and @file{$ZDOTDIR/.zlogin} are read.

@section Files
@cindex files used

@noindent
$ZDOTDIR/.zshenv@*
@noindent
$ZDOTDIR/.zprofile@*
@noindent
$ZDOTDIR/.zshrc@*
@noindent
$ZDOTDIR/.zlogin@*
@noindent
$ZDOTDIR/.zlogout@*
@noindent
$@{TMPPREFIX@}*  (default is /tmp/zsh*)@*
@noindent
/etc/zshenv@*
@noindent
/etc/zprofile@*
@noindent
/etc/zshrc@*
@noindent
/etc/zlogin@*
@noindent
/etc/zlogout


@node Shell Grammar, Expansion, Startup/Shutdown Files, Top
@chapter Shell Grammar
@cindex shell grammar
@cindex grammar, shell

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


@node Simple Commands & Pipelines, Precommand Modifiers,  , Shell Grammar
@section Simple Commands
@cindex simple commands
@cindex commands, simple

@noindent
A @dfn{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.

@noindent
A @dfn{pipeline} is a sequence of one or more commands separated by
@cindex pipeline
@code{|} or @code{|&}.  @code{|&} is shorthand for @w{@code{2>&1 |}}.  The
standard output of each command is connected to the standard input of
the next command in the pipeline.
If a pipeline is preceded by @code{coproc}, it is executed as a
@findex coproc
coprocess; a two-way pipe is established between it and the parent
@cindex coprocesses 
shell.  The shell can read from or write to the 
coprocess by means of the @code{>&p} and @code{<&p} redirection operators.  
The value of a pipeline is the value of the last command.  If a pipeline 
is not preceded by @code{!}, the value of that pipeline is the logical 
@code{NOT} of the value of the last command.

@noindent
A @dfn{sublist} is a sequence of one or more pipelines separated by
@cindex sublist
@code{&&} or @code{||}.  If two pipelines are separated by @code{&&},
the second pipeline is executed only if the first is successful (returns
a zero value).  If two pipelines are separated by @code{||}, the second
is executed only if the first is unsuccessful (returns a nonzero
value).  Both operators have equal precedence and are left 
associative.

@noindent
A @dfn{list} is a sequence of zero or more sublists separated by, and
@cindex list
optionally terminated by, @code{;}, @code{&}, @code{&|}, @code{&!}, 
or a newline.  Normally the shell waits for each list to finish before 
executing the next one.  If a list is terminated by a @code{&}, @code{&|}, 
or @code{&!}, the shell executes it in the background, and does not wait 
for it to finish.

@node Precommand Modifiers, Complex Commands, Simple Commands & Pipelines, Shell Grammar
@section Precommand Modifiers
@cindex precommand modifiers
@cindex modifiers, precommand

@noindent
A simple command may be preceded by a @dfn{precommand} modifier which will 
alter how the command is interpreted.  These modifiers are shell builtin 
commands with the exception of @code{nocorrect} which is a reserved word.

@table @code
@item -
The command is executed with a @code{-} prepended to its @code{argv[0]} 
string.
@item noglob
Filename generation (globbing) is not performed on any of the words.
@item nocorrect
Spelling correction is not done on any of the words.
@item exec
The command is executed in the parent shell without forking.
@item command
The command word is taken to be the name of an external command, rather than 
a shell function or builtin.
@end table

@node Complex Commands, Alternate Forms For Complex Commands, Precommand Modifiers, Shell Grammar
@section Complex Commands
@cindex complex commands
@cindex commands, complex

@noindent
A @dfn{complex command} in zsh is one of the following:

@table @code
@item if @var{list} then @var{list} [ elif @var{list} then @var{list} ] @dots{} [ else @var{list} ] fi
@findex if
@cindex if construct
The @code{if @var{list}} is executed, and, if it returns a zero exit
status, the @code{then @var{list}} is executed.  Otherwise, the
@code{elif @var{list}} is executed and, if its value is zero, the
@code{then @var{list}} is executed.  If each @code{elif @var{list}}
returns nonzero, the @code{else @var{list}} is executed.

@item for @var{name} [ in @var{word} @dots{} @var{term} ] do @var{list} done
@cindex for loops
@cindex loops, for
@findex for
Where @var{term} is one or more newline or @code{;}.  Expand the list of  
@var{word}s, and set the parameter @var{name} to each of them in turn, 
executing @var{list} each time.  If the @code{in @var{word}} is omitted, use
the positional parameters instead of the @var{words}.

@item while @var{list} do @var{list} done
@findex while
@cindex while loops
@cindex loops, while
Execute the @code{do @var{list}} as long as the @code{while @var{list}} 
returns a zero exit status.

@item until @var{list} do @var{list} done
@findex until
@cindex until loops
@cindex loops, until
Execute the @code{do @var{list}} as long as @code{until @var{list}} returns a
nonzero exit status.

@item repeat @var{word} do @var{list} done
@findex repeat
@cindex repeat loops
@cindex loops, repeat
@var{word} is expanded and treated as an arithmetic expression, which
must evaluate to a number @var{n}.  @var{list} is then executed @var{n}
times.

@item case @var{word} in [ [(] @var{pattern} [ | @var{pattern} ] @dots{} ) @var{list} ;; ] @dots{} esac
@findex case
@cindex case selection
@cindex selection, case
Execute the @var{list} associated with the first @var{pattern} that
matches @var{word}, if any.  The form of the patterns is the same as
that used for filename generation.  @xref{Filename Generation}.

@item select @var{name} [ in @var{word} @dots{} @var{term} ] do @var{list} done
@cindex selection, user
@cindex user selection
@findex select
Where @var{term} is one ore more newline or @code{;}.
Print the set of @var{word}s, each preceded by a number.  If the
@code{in @var{word}} is omitted, use the positional parameters.  The
@code{PROMPT3} prompt is printed and a line is read from standard input.
If this line consists of the number of one of the listed @var{word}s,
then the parameter @var{name} is set to the @var{word} corresponding to
this number.  If this line is empty, the selection list is printed
again.  Otherwise, the value of the parameter @var{name} is set to null.
The contents of the line read from standard input is saved in the
parameter @code{REPLY}.  @var{list} is executed for each selection until
a break or end-of-file is encountered.

@item ( @var{list} )
@cindex subshells
Execute @var{list} in a subshell.  Traps set by the @code{trap} builtin
are reset to their default values while executing @code{list}.

@item @{ @var{list} @}
Execute @var{list}.

@item function @var{word} @dots{} [ () ] [ @var{term} ] @{ @var{list} @}
@itemx @var{word} @dots{} () [ @var{term} ] @{ @var{list} @}
@itemx @var{word} @dots{} () [ @var{term} ] @var{command}
Where @var{term} is one or more newline or @code{;}.
Define a function which is referenced by any one of @var{word}.
Normally, only one @var{word} is provided; multiple @var{word}s are
usually only useful for setting traps.  The body of the function is the
@var{list} between the @code{@{} and @code{@}}.

If the option @code{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 @var{word}; otherwise, the parentheses will be treated as
forming a globbing pattern in that case.
@xref{Functions}.

@item time [ @var{pipeline} ]
@cindex timing
The @var{pipeline} is executed, and timing statistics are reported on
the standard error in the form specified by the @code{TIMEFMT}
parameter.  If @var{pipeline} is omitted, print statistics about the
shell process and its children.

@item [[ @var{exp} ]]
@cindex testing conditional expression
Evaluates the conditional expression @var{exp} and return a zero exit
status if it is true.  @xref{Conditional Expressions}, for a description
of @var{exp}.
@end table

@node Alternate Forms For Complex Commands, Reserved Words, Complex Commands, Shell Grammar
@section Alternate Forms For Complex Commands
@cindex alternate forms for complex commands
@cindex commands, alternate forms for complex

@noindent
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
@code{@var{sublist}} is of the form @code{@{ @var{list} @}} or if the 
@code{NO_SHORT_LOOPS} option is not set.

@table @code
@item if @var{list} @{ @var{list} @} [ elif @var{list} @{ @var{list} @} ] @dots{} [ else @{ @var{list} @} ]
An alternate form of @code{if}.  

@item if @var{list} @var{sublist}
A short form of previous one.

@item for @var{name} ( @var{word} @dots{} ) @var{sublist}
A short form of @code{for}.

@item for @var{name} [ in @var{word} @dots{} @var{term} ] @var{sublist}
Where @var{term} is one or more newline or @code{;}.  Another short form of 
@code{for}.

@item foreach @var{name} ( @var{word} @dots{} ) @var{list} end
Another form of @code{for}.

@item while @var{list} @{ @var{list} @}
An alternative form of @code{while}. 

@item until @var{list} @{ @var{list} @}
An alternative form of @code{until}.

@item repeat @var{word} @var{sublist}
This is a short form of @code{repeat}.

@item case @var{word} @{ [ [(] @var{pattern} [ | @var{pattern} ] @dots{} ) @var{list} ;; ] @dots{} @}
An alternative form of @code{case}.

@item select @var{name} [ in @var{word} @var{term} ] @var{sublist}
Where @var{term} is one or more newline or @code{;}.  A short form of
@code{select}.
@end table


@node Reserved Words, Comments, Alternate Forms For Complex Commands, Shell Grammar
@section Reserved Words
@cindex reserved words

@noindent
The following words are recognized as @dfn{reserved words} when used as the
first word of a command unless quoted or disabled using @code{disable -r}:
@findex disable, use of

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

@noindent
Additionally @code{@}} is recognized in any position if the
@code{IGNORE_BRACES} option is not set.

@node Comments, Aliasing, Reserved Words, Shell Grammar
@section Comments
@cindex comments

@noindent
In non-interactive shells, or in interactive shells with the
@code{INTERACTIVE_COMMENTS} option set, a word beginning with the third
@pindex INTERACTIVE_COMMENTS, use of
character of the @code{histchars} parameter (@code{#} by default) causes
@vindex histchars, use of
that word and all the following characters up to a newline to be
ignored.

@node Aliasing, Quoting, Comments, Shell Grammar
@section Aliasing
@cindex aliasing

@noindent
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 @code{alias}
@findex alias, use of
@cindex aliases, global
builtin; global aliases may be defined using the @samp{-g} option to
that builtin.

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

@node Quoting,  , Aliasing, Shell Grammar
@section Quoting
@cindex quoting

@noindent
A character may be @dfn{quoted} (that is, made to stand for itself) by
preceding it with a @code{\}.  @code{\} followed by a newline is
ignored.  All characters enclosed between a pair of single quotes
(@t{@value{dsq}}) are quoted, except the first character of @code{histchars}
(@code{!} by default).  A single quote cannot appear within single
quotes.  Inside double quotes (@code{""}), parameter and command
substitution occurs, and @code{\} quotes the characters @code{\},
@code{`}, @code{"}, and @code{$}. 


@node Expansion, Redirection, Shell Grammar, Top
@chapter Expansion
@cindex expansion

@noindent
The types of expansions performed are @dfn{history expansion}, 
@dfn{alias expansion}, @dfn{process substitution}, 
@dfn{parameter expansion}, @dfn{command substitution}, 
@dfn{arithmetic expansion}, @dfn{brace expansion},
@dfn{filename expansion}, and @dfn{filename generation}.

@noindent
Expansion is done in the above specified order in five steps.  The first is 
@dfn{history expansion} which is only performed in interactive shells.  The
next step is @dfn{alias expansion} which is done right before the command 
line is parsed.  They are followed by @dfn{process substitution}, 
@dfn{parameter expansion}, @dfn{command substitution}, 
@dfn{arithmetic expansion}, and @dfn{brace expansion} which are performed in
one step in @w{left-to-right} fashion.  After these expansions, all
unquoted occurrences of the characters @code{\}, @code{'}, and @code{"} are
removed and the result is subjected to @dfn{filename expansion}
followed by @dfn{filename generation}.

@noindent
If the @code{SH_FILE_EXPANSION} option is set, the order of expansion is modified
for compatibility with @code{sh} and @code{ksh}.  @dfn{Filename expansion} is
performed immediately after @dfn{alias substitution}, preceding the set of 
five substitutions mentioned above.

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

@node Filename Expansion, Process Substitution,  , Expansion
@section Filename Expansion
@cindex filename expansion
@cindex expansion, filename

@noindent
Each word is checked to see if it begins with an unquoted @code{~}.  If
it does, then the word up to a @code{/}, or the end of the word if there is
no @code{/}, is checked to see if it can be substituted in one of the ways
described here.  If so, then the @code{~} and the checked
portion are replaced with the appropriate substitute value.

@noindent
A @code{~} by itself is replaced by the value of the
@code{HOME} parameter.  A @code{~} followed by a @code{+} or a @code{-}
is replaced by the value of @code{PWD} or @code{OLDPWD},
respectively.

@noindent
@pindex PUSHD_MINUS, use of
A @code{~} followed by a number is replaced by the directory at that 
position in the directory stack.  @code{~0} is equivalent to @code{~+}, and 
@code{~1} is the top of the stack.  @code{~+} followed by a number is replaced
by the directory at that position in the directory stack.  @code{~+0} is 
equivalent to @code{~+}, and @code{~+1} is the top of the stack.  @code{~-} 
followed by a number is replaced by the directory that many positions from 
the bottom of the stack.  @code{~-0} is the bottom of the stack.  The
@code{PUSHD_MINUS} option exchanges the effects of @code{~+} and @code{~-} 
where they are followed by a number.

@noindent
@cindex directories, named
@cindex named directories
A @code{~} followed by anything not already covered is looked up
as a named directory, and replaced by the value of that named directory if 
found.  Named directories are typically home directories for users on the 
system.  They may also be defined if the text after the @code{~} is the name 
of a string shell parameter whose value begins with a @code{/}.  It is also
possible to define directory names using the @samp{-d} option to the 
@code{hash} builtin.

@noindent
In  certain circumstances (in prompts, for instance), when the shell prints 
a path, the path is checked to see if it has a named directory as its 
prefix.  If so, then the prefix portion is replaced with a @code{~} followed 
by the name of the directory.  The shortest way of referring to the directory 
is used, with ties broken in favour of using a named directory, except when 
the directory is @code{/}.

@noindent
If a word begins with an unquoted @code{=} and the @code{EQUALS}
option is set, the remainder of the word is taken as the name of a
command or alias.  If a command exists by that name, the word is
replaced by the full pathname of the command.  If an alias exists by
that name, the word is replaced with the text of the alias.  

@noindent
Filename expansion is performed on the right hand side of a parameter 
assignment, including those appearing after commands of the @code{typeset} 
family.  In this case, the right hand side will be treated as a 
@w{colon-separated} list in the manner of @code{PATH} so that a @code{~} or 
an @code{=} following a @code{:} is eligible  for expansion.  All such 
behavior can be disabled by quoting the @code{~}, the @code{=}, or the whole  
expression (but not simply the colon); the @code{EQUALS} option is also 
respected.

@noindent
If the option @code{MAGIC_EQUAL_SUBST} is set, any unquoted shell argument in 
the form @code{@var{identifier}=@var{expression}} becomes eligible for 
file expansion as described in the previous  paragraph.  Quoting the first 
@code{=} also inhibits this.


@node Process Substitution, Parameter Expansion, Filename Expansion, Expansion
@section Process Substitution
@cindex process substitution
@cindex substitution, process

@noindent
Each command argument of the form @code{<(@var{list})},
@code{>(@var{list})} or @code{=(@var{list})} is subject to process
substitution.  In the case of the @code{<} and @code{>} forms, the shell
will run process @var{list} asynchronously, connected to a named pipe
(FIFO).  The name of this pipe will become the argument to the command.
If the form with @code{>} is selected then writing to this file will
provide input for @var{list}.  If @code{<} is used, then the file passed
as an argument will be a named pipe connected to the output of the
@var{list} process.  For example,

@code{paste <(cut -f1 @var{file1}) <(cut -f3 @var{file2}) | tee >(@var{process1}) >(@var{process2}) >/dev/null}

@noindent
@code{cut}s fields 1 and 3 from the files @var{file1} and @var{file2}
respectively, @code{paste}s the results together, and sends it to the
processes @var{process1} and @var{process2}.  Note that the file, which
is passed as an argument to the command, is a system pipe so programs
that expect to @code{lseek(2)} on the file will not work.  Also note
that the previous example can be more compactly and efficiently written
as:

@code{paste <(cut -f1 @var{file1}) <(cut -f3 @var{file2}) >>(@var{process1}) >>(@var{process2})}

@noindent
The shell uses pipes instead of FIFOs to implement the latter two
process substitutions in the above example.

@noindent
If @code{=} is used, then the file passed as an argument will be the name
of a temporary file containing the output of the @var{list} process.
@cindex temporary files
@cindex files, temporary
This may be used instead of the @code{<} form for a program that expects
to @code{lseek(2)} on the input file.

@node Parameter Expansion, Command Substitution, Process Substitution, Expansion
@section Parameter Expansion
@cindex parameter expansion
@cindex expansion, parameter

@noindent
The character @code{$} is used to introduce parameter expansions.
@xref{Parameters}, for a description of parameters.  In the expansions 
discussed below that require a pattern, the form of the pattern is the same 
as that used for filename generation; @xref{Filename Generation}.

@table @code
@item $@{@var{name}@}
The value, if any, of the parameter @var{name} is substituted.  The
braces are required if @var{name} is followed by a letter, digit, or
underscore that is not to be interpreted as part of its name.
If @var{name} is an array parameter, then the value of each
element of @var{name} is substituted, one element per word.
Otherwise, the expansion results in one word only; no field
splitting is done on the result unless the @code{SH_WORD_SPLIT}
option is set.

@item $@{+@var{name}@}
If @var{name} is the name of a set parameter, @code{1} is substituted,
otherwise @code{0} is substituted.

@item $@{@var{name}:-@var{word}@}
If @var{name} is set and is non-null then substitute its value;
otherwise substitute @var{word}. If @var{name} is missing, substitute
@var{word}.

@item $@{@var{name}:=@var{word}@}
If @var{name} is unset or is null then set it to @var{word}; the value
of the parameter is then substituted.

@item $@{@var{name}::=@var{word}@}
Set @var{name} to @var{word}; the value of the parameter is then substituted.

@item $@{@var{name}:?@var{word}@}
If @var{name} is set and is non-null, then substitute its value;
otherwise, print @var{word} and exit from the shell.  Interactive shells
do not exit.  If @var{word} is omitted, then a standard message is
printed.

@item $@{@var{name}:+@var{word}@}
If @var{name} is set and is non-null then substitute @var{word};
otherwise substitute nothing.

@item $@{@var{name}#@var{pattern}@}
@itemx $@{@var{name}##@var{pattern}@}
If the @var{pattern} matches the beginning of the value of @var{name},
then substitute the value of @var{name} with the matched portion
deleted; otherwise, just substitute the value of @var{name}.  In the
first form, the smallest matching pattern is preferred; in the second
form, the largest matching pattern is preferred.  If name is an array and
the substitution is not quoted or the @code{@@} flag or the
@code{@var{name}[@@]} syntax is used, matching is performed on each
array elements separately.

@item $@{@var{name}%@var{pattern}@}
@itemx $@{@var{name}%%@var{pattern}@}
If the @var{pattern} matches the end of the value of @var{name}, then
substitute the value of @var{name} with the matched portion deleted;
otherwise, just substitute the value of @var{name}.  In the first form,
the smallest matching pattern is preferred; in the second form, the
largest matching pattern is preferred.  If name is an
array and the substitution is not quoted or the @code{@@} flag or the 
@code{@var{name}[@@]} syntax is used, matching is performed on each array 
elements separately.

@item $@{@var{name}:#@var{pattern}@}
If the pattern matches the value of @var{name}, then substitute the empty 
string; otherwise, just substitute the value of @var{name}.  If @var{name} 
is an array and the substitution is not quoted or the @code{@@} flag or the 
@code{@var{name}[@@]} syntax is used, matching is performed on each array
elements separately, and the matched array elements are removed (use the 
@code{M} flag to remove the non-matched elements).

@item $@{#@var{spec}@}
If @var{spec} is one of the above substitutions, substitute the length
in characters of the result instead of the result itself.  If @var{spec}
is an array expression, substitute the number of elements of the
result.

@item $@{^@var{spec}@}
Turn on the value of the @code{RC_EXPAND_PARAM} option for the evaluation
@pindex RC_EXPAND_PARAM, use of
of @var{spec}; if the @code{^} is doubled, turn it off.  When this option is 
set, array expansions of the form
@cindex rc, array expansion style
@cindex array expansion, rc style
@samp{foo$@{xx@}bar}, where the parameter @samp{xx} is set to @samp{(a b c)}, 
are substituted with @samp{fooabar foobbar foocbar} instead of the
default @samp{fooa b cbar}.

@item $@{=@var{spec}@}
Turn on the value of the @code{SH_WORD_SPLIT} option for the evaluation
@pindex SH_WORD_SPLIT, use of
of @var{spec}; if the @code{=} is doubled, turn it off.  When this option is 
set, parameter values are split into
separate words using @code{IFS} as a delimiter before substitution.
@cindex word splitting, sh style
@cindex sh, word splitting style
@vindex IFS, use of
This is done by default in most other shells.

@item $@{~@var{spec}@}
@cindex csh, tilde expansion
@cindex tilde expansion, csh
@pindex CSH_JUNKIE_LOOPS
Turn on the value of the @code{GLOB_SUBST} option for the evaluation of
@var{spec}; if the @code{~} is doubled, turn it off.  When this option is set,
any pattern characters resulting from the substitution become eligible for 
file expansion and filename generation.
@end table

@noindent
If the colon is omitted from one of the above expressions containing a
colon, then the shell only checks whether @var{name} is set or not, not
whether it is null.

@noindent
If a @code{$@{@dots{}@}} type parameter expression or a @code{$(@dots{})}  
type command substitution is used in place of @var{name} above, it is
substituted first and the result is used as it were the value of @var{name}.

@noindent
Note that double quotes may appear around nested expansions, in which
case only the part inside is treated as quoted; for example,
@code{$@{(f)"$(foo)"@}} quotes the result of @code{$(foo)}, but the flag
`@code{(f)}' (see below) is applied using the rules for unquoted
substitutions.  Note further that quotes are themselves nested in this
context; for example, in @code{"$@{(f)"$(foo)"@}"}, there are two sets
of quotes, one surrounding the whole expression, the other (redundant)
surrounding the @code{$(foo)} as before.

@noindent
If the opening brace is directly followed by an opening parenthesis
the string up to the matching closing parenthesis will be taken as a
list of flags.  Where arguments are valid, any character, or the
matching pairs @code{(@dots{})}, @code{@{@dots{}@}}, @code{[@dots{}]},
or @code{<@dots{}>}, may be used in place of the colon as delimiters.
The following flags are supported:

@table @code
@item A
Create an array parameter with @code{$@{@dots{}:=@dots{}@}}
or @code{$@{@dots{}::=@dots{}@}}.  Assignment is made before
sorting or padding.

@item @@
In double quotes, array elements are put into separate words. Eg@. 
@code{$@{(@@)@var{foo}@}} is equivalent to @code{$@{@var{foo}[@@]@}} and
@code{$@{(@@)@var{foo}[1,2]@}} is the same as 
@w{@code{$@var{foo}[1]} @code{$@var{foo}[2]}}.

@item e
Perform @dfn{parameter expansion}, @dfn{command substitution} and  
@dfn{arithmetic expansion} on the result.  Such expansions can be nested but
too deep recursion may have unpredictable effects.

@item o
Sort the resulting words in ascending order.

@item O
Sort the resulting words in descending order.

@item i
With @code{o} or @code{O}, makes the sort case-insensitive.

@item L
Converts all letters in the result to lowercase.

@item U
Converts all letters in the result to uppercase.

@item C
Capitalizes the resulting words

@item c
With @code{$@{#@var{name}@}}, count the total number of characters in an
array, as if the elements were concatenated with spaces between
them.

@item w
With @code{$@{#@var{name}@}}, count words in arrays or strings; the
@code{s} flag may be used to set a word delimiter.

@item W
Similar to @code{w} with the difference that empty words between repeated 
delimiters are also counted.

@item  p      
Recognize the same escape sequences as the @code{print} builtin in string 
arguments to subsequent flags.

@item l:@var{expr}::@var{string1}::@var{string2}:
Pad the resulting words on the left.  Each word will be truncated if
required and placed in a field @var{expr} characters wide.  The space to
the left will be filled with @var{string1} (concatenated as often as
needed), or spaces if @var{string1} is not given.  If both @var{string1}
and @var{string2} are given, this string is inserted once directly to
the left of each word, before padding.

@item r:@var{expr}::@var{string1}::@var{string2}:
As @code{l}, but pad the words on the right and insert @var{string2} on
the right.

@item j:@var{string}:
@pindex SH_WORD_SPLIT, use of
Join the words or arrays together using @var{string} as a separator.
Note that this occurs before word splitting by the @code{SH_WORD_SPLIT}
option.

@item F
Join the words of arrays together using newline as a separator.  This is a 
shorthand for @code{pj:\n:}.

@item s:@var{string}:
Force word splitting (see the option @code{SH_WORD_SPLIT}) at the
separator @var{string}.  Splitting only occurs in places where an array
value is valid, and joining always occurs before splitting.

@item f
Split the result of the expansion to lines.  This is a shorthand for 
@code{ps:\n:}.

@noindent
(All remaining flags are useful only with the
@code{$@{@dots{}#@dots{}@}} and @code{$@{@dots{}%@dots{}@}} forms.)

@item S
Search substrings as well as beginnings or ends.

@item I:@var{expr}:
Search the @var{expr}'th match (where @var{expr} evaluates to a number).

@item M
Include the matched portion in the result.

@item R
Include the unmatched portion in the result (the @var{R}est).

@item B
Include the index of the beginning of the match in the result.

@item E
Include the index of the end of the match in the result.

@item N
Include the length of the match in the result.
@end table

@node Command Substitution, Arithmetic Expansion, Parameter Expansion, Expansion
@section Command Substitution
@cindex command substitution
@cindex substitution, command

@noindent
A command enclosed in parentheses preceded by a dollar sign, like so: 
@code{$(@dots{})} or quoted with grave accents: @code{`@dots{}`} is replaced 
with its standard output, with any trailing newlines deleted.  If the 
substitution is not enclosed in double quotes, the output is broken into 
words using the @code{IFS}
@vindex IFS, use of
parameter.  The substitution @code{$(cat @var{foo})} may be replaced 
by the equivalent but faster @code{$(<@var{foo})}.  In either case, if the 
option @code{GLOB_SUBST} is set the output is eligible for filename
generation.

@node Arithmetic Expansion, Brace Expansion, Command Substitution, Expansion
@section Arithmetic Expansion
@cindex arithmetic expansion
@cindex expansion, arithmetic

@noindent
A string of the form @code{$[@var{exp}]} is substituted with the value
of the arithmetic expression @var{exp}.  @var{exp} is subjected to 
@dfn{parameter expansion}, @dfn{command substitution} and
@dfn{arithmetic expansion} before it is evaluated.  @xref{Arithmetic Evaluation}.

@node Brace Expansion, Filename Generation, Arithmetic Expansion, Expansion
@section Brace Expansion
@cindex brace expansion
@cindex expansion, brace

@noindent
A string of the form @samp{foo@{xx,yy,zz@}bar} is expanded to the
individual words @samp{fooxxbar}, @samp{fooyybar}, and @samp{foozzbar}.
@w{Left-to-right} order is preserved.  This construct may be nested.
Commas may be quoted in order to include them literally in a word.

@noindent
An expression of the form @code{@{@var{n1}..@var{n2}@}}, where @var{n1} and 
@var{n2} are integers, is expanded to every number between @var{n1} and 
@var{n2}, inclusive.  If either number begins with a zero, all the resulting 
numbers will be padded with leading zeroes to that minimum width.  If the 
numbers are in decreasing order the resulting sequence will also be in 
decreasing order.

@noindent
@pindex BRACE_CCL, use of
If a brace expression matches none of the above forms, it is left unchanged, 
unless the @code{BRACE_CCL} option is set.  In that case, it is expanded to a 
sorted list of the individual characters between the braces, in the manner of
a search set.  @code{-} is treated specially as in a search set,
but @code{^} or @code{!} as the first character is treated normally.

@node Filename Generation, History Expansion, Brace Expansion, Expansion
@section Filename Generation
@cindex filename generation
@noindent
If a word contains an unquoted instance of one of the characters
@cindex globbing
@code{*}, @code{|}, @code{<}, @code{[}, or @code{?}, it is regarded as a
pattern for filename generation, unless the @code{GLOB} option is
@pindex GLOB, use of
unset.  If the @code{EXTENDED_GLOB} option is set, the @code{^}, @code{~}, and
@pindex EXTENDED_GLOB, use of
@code{#} characters also denote a pattern; they are not otherwise
treated specially by the shell, except for an initial @code{~}
(@pxref{Filename Expansion}).  The word is replaced with a list of
sorted filenames that match the pattern.  If no matching pattern is
found, the shell gives an error message, unless the @code{NULL_GLOB}
@pindex NULL_GLOB, use of
option is set, in which case the word is deleted; or unless the
@code{NOMATCH} option is unset, in which case the word is left
@pindex NOMATCH, use of
unchanged.  In filename generation, the character @code{/} must be
matched explicitly; also, a @code{.} must be matched explicitly at the
beginning of a pattern or after a @code{/}, unless the @code{GLOB_DOTS}
@pindex GLOB_DOTS, use of
option is set.  No filename generation pattern matches the files
@file{.} or @file{..}.  In other instances of pattern matching, the
@code{/} and @code{.} are not treated specially.

@table @code
@item *
Matches any string, including the null string.

@item ?
Matches any character.

@item [@dots{}]
Matches any of the enclosed characters. Ranges of characters can be specified 
by separating two characters by a @code{-}.  A @code{-} or @code{]} may be 
matched by including it as the first character in the list.

@item [^@dots{}]
@itemx [!@dots{}]
Like @code{[@dots{}]}, except that it matches any character which is not in 
the given set.

@item <x-y>
Matches any number in the range @code{x} to @code{y}, inclusive.  If
@code{x} is omitted, the number must be less than or equal to @code{y}.  If 
@code{y} is omitted, the number must be greater than or equal to
@code{x}.  A pattern of the form @code{<->} matches any number.

@item ^x
Matches anything except the pattern @code{x}.

@item x|y
Matches either @code{x} or @code{y}.

@item x#
Matches zero or more occurrences of the pattern @code{x}.

@item x##
Matches one or more occurrences of the pattern @code{x}.
@end table

@noindent
Parentheses may be used for grouping.  Note that the @code{|} character
must be within parentheses, so that the lexical analyzer does not think
it is a pipe character.  Also note that @code{/} has a higher precedence
than @code{^}; that is:

@code{ls ^foo/bar}

@noindent
will search directories in @file{.} except @file{./foo} for a file named
@file{bar}.

@noindent
A pathname component of the form @code{(@var{foo}/)#} matches a path
consisting of zero or more directories matching the pattern @var{foo}.
As a shorthand, @code{**/} is equivalent to @code{(*/)#}.  Thus:

@code{ls (*/)#@var{bar}}

@noindent
or

@code{ls **/@var{bar}}

@noindent
does a recursive directory search for files named @var{bar}, not following 
symbolic links.  To follow symbolic links, use the form @code{***/}.

@noindent
If used for filename generation, a pattern may contain an exclusion
@cindex exclusion, globbing
@cindex globbing, excluding patterns
specifier.  Such patterns are of the form @code{@var{pat1}~@var{pat2}}.
This pattern will generate all files matching @var{pat1}, but which do
not match @var{pat2}.  For example, @samp{*.c~lex.c} will match all
files ending in @file{.c}, except the file @file{lex.c}.  This may
appear inside parentheses.  Note that @code{~} has higher precedence
than @code{|}, so that @samp{pat1|pat2~pat3} matches any time that
@var{pat1} matches, or if @var{pat2} matches while @var{pat3} does not.
Note also that any @code{/} characters are not treated specially in the
exclusion specifier, so that a @code{*} will match multiple path
segments if they appear in the pattern to the left of the
@code{~}. 

@noindent
Patterns used for filename generation may also end in a list of
@cindex qualifiers, globbing
@cindex globbing, qualifiers
qualifiers enclosed in parentheses.  The qualifiers specify which
filenames that otherwise match the given pattern will be inserted in the
argument list.  A qualifier may be any one of the following:

@table @code
@item /
Directories

@item .
Plain files

@item @@
Symbolic links

@item =
Sockets

@item p
Named pipes (FIFOs)

@item *
Executable plain files (0100)

@item %
Device files (character or block special)

@item %b
Block special files

@item %c
Character special files

@item r
owner-readable files (0400)

@item w
owner-writable files (0200)

@item x
owner-executable files (0100)

@item A
group-readable files (0040)

@item I
group-writable files (0020)

@item E
group-executable files (0010)

@item R
world-readable files (0004)

@item W
world-writable files (0002)

@item X
world-executable files (0001)

@item s
Setuid files (04000)

@item S
Setgid files (02000)

@item t
files with the sticky bit (01000)

@item d@var{dev}
Files on the device @var{dev}

@item l[+|-]@var{ct}
Files having a link count less than @code{@var{ct} (-)}, greater than 
@code{@var{ct} (+)}, or is equal to @code{@var{ct}}.

@item U
Files owned by the effective user id.

@item G
Files owned by the effective group id.

@item u@var{id}
Files owned by user @var{id} if @var{id} is a number.  If not, the
character after the @code{u} will be used as a separator and the string
between it and the next matching separator (@code{(}, @code{[},
@code{@{}, and @code{<} match @code{)}, @code{]}, @code{@}}, and
@code{>} respectively; any other character matches itself) will be taken
as a user name and translated into the corresponding user id (e.g.@:
@code{u:foo:} or @code{u[foo]} for user @code{foo}).

@item g@var{id}
Like @code{u@var{id}} but with group ids or names.

@item a[Mwhms][-|+]@var{n}
Files accessed exactly @var{n} days ago.  Files accessed within the last
@var{n} days are selected using a negative value for @var{n}
(@samp{-n}).  Files accessed more than @var{n} days ago are selected by
a positive @var{n} value (@code{+n}).  Optional unit specifiers
@code{M}, @code{w}, @code{h}, @code{m}, or @code{s} (e.g. @code{ah5})
cause the check to be performed with months (of 30 days), weeks, hours,
minutes, or seconds instead of days, respectively.  For instance,
@code{echo *(ah-5)} would echo files accessed within the last five
hours.

@item m[Mwhms][-|+]@var{n}
Like the file access qualifier, except that it uses the file modification 
time.

@item c[Mwhms][-|+]@var{n}
Like the file access qualifier, except that it uses the file inode change 
time.

@item L[+-]@var{n}
Files less than @var{n} bytes (@code{-}), more than @var{n} bytes
(@code{+}), or exactly @var{n} bytes in length.  If this flag is directly 
followed by a @code{k} (@code{K}), @code{m} (@code{M}), or @code{p} 
(@code{P}) (e.g. @code{Lk+50}) the check is performed with kilobytes, 
megabytes, or blocks (of 512 bytes) instead.

@item ^
Negates all qualifiers following it.

@item -
Toggles between making the qualifiers work on symbolic links (the
default), and the files they point to.

@item M
Sets the @code{MARK_DIRS} option for the current pattern.
@pindex MARK_DIRS, setting in pattern

@item T
Appends a trailing qualifier mark to the file names, analogous to the
@code{LIST_TYPES}, for the current pattern (overrides @code{M}).

@item N
Sets the @code{NULL_GLOB} option for the current pattern.
@pindex NULL_GLOB, setting in pattern

@item D
Sets the @code{GLOB_DOTS} option for the current pattern.
@pindex GLOB_DOTS, setting in pattern
@end table

@noindent
More than one of these lists can be combined, separated by commas; the
whole list matches if at least one of the sublists matches (they are
@code{or}'ed, the qualifiers in the sublists are @code{and}'ed). 

@noindent
If a @code{:} appears in a qualifier list, the remainder of the
expression in parentheses is interpreted as a modifier
(@pxref{Modifiers}).  Note that each modifier must be introduced by a
separate @code{:}.  Note also that the result after modification does
not have to be an existing file.  The name of any existing file can be
followed by a modifier of the form @code{(:@dots{})} even if no filename
generation is performed.

@noindent
Thus:

@code{ls *(-/)}

@noindent
lists all directories and symbolic links that point to directories, and

@code{ls *(%W)}

@noindent
lists all world-writable device files in the current directory, and

@code{ls *(W,X)}

@noindent
lists all files in the current directory that are world-writable or
world-executable, and

@code{echo /tmp/foo*(u0^@@:t)}

@noindent
outputs the basename of all root-owned files beginning with the string
@code{foo} in @file{/tmp}, ignoring symlinks, and

@code{ls *.*~(lex|parse).[ch](^D^l1)}

@noindent
lists all files having a link count of one whose names contain a dot
(but not those starting with a dot, since @code{GLOB_DOTS} is explicitly
switched off) except for @file{lex.c}, @file{lex.h}, @file{parse.c}, and
@file{parse.h}.

@node History Expansion,  ,  Filename Generation, Expansion
@section History Expansion
@cindex history
@cindex history expansion
@cindex expansion, history

@noindent
History substitution allows you to use words from previous command lines 
in the command line you are typing.  This simplifies spelling corrections 
and the repetition of complicated commands or arguments.  Command lines are 
saved in the history list, the size of which is controlled by the 
@code{HISTSIZE} variable.  The most recent command is retained in any 
@vindex HISTSIZE, use of
case.  A history substitution begins with the first character of the 
@code{histchars} parameter which is @code{!} by default and may occur 
anywhere on the command line; history substitutions do not nest.  The 
@code{!} can be escaped with @code{\} or can be enclosed between a pair of 
single quotes (@t{@value{dsq}}) 
to suppress its special meaning. Double quotes will not work for this.

@noindent
Input lines containing history substitutions are echoed on the terminal 
after being expanded, but before any other substitutions take place or the 
command gets executed.

@menu
* Event Designators::
* Word Designators::
* Modifiers::
@end menu

@node Event Designators, Word Designators,  , History Expansion
@subsection Event Designators
@cindex history event designators
@cindex event designators, history

@noindent
An event designator is a reference to a command-line entry in the history 
list.

@table @code
@item !
Start a history substitution, except when followed by a blank, newline, 
@code{=}, or @code{(}.

@item !!
Refer to the previous command.  By itself, this substitution repeats the 
previous command.

@item !@var{n}
Refer to command-line @var{n}.

@item !-@var{n}
Refer to the current command-line minus @var{n}.

@item !@var{str}
Refer to the most recent command starting with @var{str}.

@item !?@var{str}[?]
Refer to the most recent command containing @var{str}.

@item !#
Refer to the current command line typed in so far.  The line is treated as if 
it were complete up to and including the word before the one with the 
@code{!#} reference.

@item !@{@dots{}@}
Insulate a history reference from adjacent characters (if necessary).
@end table


@node Word Designators, Modifiers, Event Designators, History Expansion
@subsection Word Designators
@cindex history word designators
@cindex word designators, history

@noindent
A word designator indicates which word or words of a given command line will 
be included in a history reference.  A @code{:} separates the event 
specification from the word designator.  It can be omitted if the word 
designator begins with a @code{^}, @code{$}, @code{*}, @code{-} or 
@code{%}.  Word designators include:

@table @code
@item 0
The first input word (command).

@item @var{n}
The @var{n}'th argument.

@item ^
The first argument, that is, @code{1}.

@item $
The last argument.

@item %
The word matched by (the most recent) @code{?@var{str}} search.

@item x-y
A range of words; @samp{-y} abbreviates @code{0-y}.

@item *
All the arguments, or a null value if there is just one word in the event.

@item x*
Abbreviates @code{x-$}.

@item x-
Like @code{x*} but omitting word @code{$}.
@end table

@noindent
Note that a @code{%} word designator will only work when used as @code{!%}, 
@code{!:%}, @code{!?str?:%} and only when used after a @code{!?} 
substitution.  Anything else will result in an error, although the error may 
not be the most obvious one.


@node Modifiers,  , Word Designators, History Expansion
@subsection Modifiers
@cindex modifiers, history
@cindex history modifiers

@noindent
After the optional word designator, you can add a sequence of one or more of 
the following modifiers, each preceded by a @code{:}.  These modifiers also 
work on the result of filename and parameter expansion.

@table @code
@item h
Remove a trailing pathname component,  leaving the head.

@item r
Remove a trailing suffix of the form @code{.xxx}, leaving the basename.

@item e
Remove all but the suffix.

@item t
Remove all leading pathname components, leaving the tail.

@item &
Repeat the previous substitution.

@item g
Apply the change to the first occurrence of a match in each word, by 
prefixing the above (for example, @code{g&}).

@item p
Print the new command but do not execute it.

@item q
Quote the substituted words, escaping further substitutions.

@item x
Like @code{q}, but break into words at each blank.

@item l
Convert the words to all lowercase.

@item u
Convert the words to all uppercase.

@item f
Repeats the immediately (without a colon) following modifier until the 
resulting word doesn't change any more.  This and the following  @code{F},  
@code{w} and @code{W} modifier only work with parameter and filename expansion.

@item F:@var{expr}:
Like @code{f}, but repeats only @code{n} times if the expression @var{expr} 
evaluates to @code{n}. Any character can be used instead of the @code{:},  
if any of @code{(}, @code{[}, or @code{@{} is used as the opening delimiter 
the second one has to be @code{)}, @code{]}, or @code{@}} respectively.

@item w
Makes the immediately following modifier work on each word in the string.

@item W:@var{sep}:
Like @code{w} but words are considered to be the parts of the string that are
separated by @var{sep}.  Any character can be used instead of the @code{:},  
opening parentheses are handled specially, see above.

@item s/@var{l}/@var{r}[/]
Substitute @var{r} for @var{l}.
@end table

@noindent
Unless preceded by a @code{g}, the substitution is done only  for
the first string that matches @code{l}.

@noindent
The left-hand side of substitutions are not regular expressions, but 
character strings.  Any character can be used as the delimiter in place of 
@code{/}.  A backslash quotes the delimiter character.  The character 
@code{&}, in the right hand side, is replaced by the text from the 
left-hand-side.  The @code{&} can be quoted with a backslash.   A null 
@code{l} uses the previous string either from a @code{l} or from a 
contextual scan string @code{s} from @code{!?s}.  You can omit the rightmost
delimiter if a newline immediately follows @code{r}; the right-most @code{?}
in a context scan can similarly be omitted.

@noindent
By default, a history reference with no event specification refers to the 
same line as the last history reference on that command line, unless it is 
the first history reference in a command.  In that case, a history reference
with no event specification always refers to the previous command.   However,
if the option @code{CSH_JUNKIE_HISTORY} is set, then history reference with  
no event specification will always refer to the previous command.  For example,
@code{!!:1} will always refer to the first word of the previous command and 
@code{!!$} will always refer to the last word of the previous command.  And 
with @code{CSH_JUNKIE_HISTORY} set, then @code{!:1} and @code{!$} will 
function in the same manner as @code{!!:1} and @code{!!$}, 
respectively.   However, if @code{CSH_JUNKIE_HISTORY} is unset, then 
@code{!:1} and @code{!$} will refer to the first and last words respectively, 
of the last command referenced on the current command line.  However, if they
are the first history reference on the command line, then they refer to the
previous command.

@noindent
The character sequence @code{^@var{foo}^@var{bar}} repeats the last command,
replacing the string @var{foo} with the string @var{bar}.

@noindent
If the shell encounters the character sequence @code{!"} in the input, the 
history mechanism is temporarily disabled until the current list is fully 
parsed.  The @code{!"} is removed from the input, and any subsequent 
@code{!} characters have no special significance.

@noindent
A less convenient but more comprehensible form of command history support 
is provided by the @code{fc} builtin 
@findex fc, use of
(@pxref{Shell Builtin Commands}).


@node Redirection, Command Execution, Expansion, Top
@chapter Redirection
@cindex redirection

@noindent
Before a command is executed, its input and output may be redirected.
@cindex file descriptors
@cindex descriptors, file
The following may appear anywhere in a simple command or may precede or
follow a complex command.  Substitution occurs before @var{word} or
@var{digit} is used except as noted below.  If the result of substitution on 
@var{word} produces more than one filename, redirection occurs for each 
separate filename in turn.

@table @code
@item <@var{word}
Open file @var{word} as standard input.

@item <>@var{word}
Open file @var{word} for reading and writing as standard input.  If the file 
does not exist then it is created.

@item >@var{word}
Open file @var{word} as standard output.  If the file does not exist
then it is created.  If the file exists, and the @code{CLOBBER}
@pindex CLOBBER, use of
option is unset, this causes an error; otherwise, it is truncated to zero
length.

@item >|@var{word}
@itemx >!@var{word}
Same as @code{>}, except that the file is truncated to zero length if it
exists, even if @code{CLOBBER} is unset.

@item >>@var{word}
Open file @var{word} as standard output.  If the file exists then output
is appended to it.  If the file does not exist, and the
@code{CLOBBER} option is unset, this causes an error; otherwise, the
file is created.

@item >>|@var{word}
@itemx >>!@var{word}
Same as @code{>>}, except that the file is created if it does not exist,
even if @code{CLOBBER} is unset.

@item <<[-]@var{word}
The shell input is read up to a line that is the same as @var{word}, or
to an end-of-file.  No parameter substitution, command substitution or
filename generation is performed on @var{word}.  The resulting document,
called a @dfn{here-document}, becomes the standard input.  If any
character of @var{word} is quoted with single or double quotes or a
@code{\}, no interpretation is placed upon the characters of the
document.  Otherwise, parameter and command substitution occurs,
@code{\} followed by a newline is removed, and @code{\} must be used to
quote the characters @code{\}, @code{$}, @code{`}, and the first
character of @var{word}.  If @code{<<-} is used, then all leading tabs
are stripped from @var{word} and from the document.

@item <<<@var{word}
Perform shell expansion on @var{word} and pass the result to 
standard input.

@item <&@var{digit}
The standard input is duplicated from file descriptor @var{digit} (see
@code{dup(2)}).  Similarly for standard output using
@code{>&@var{digit}}.

@item >&@var{word}
Same as @code{>@var{word} 2>&1}.

@item >>&@var{word}
Same as @code{>>@var{word} 2>&1}.

@item <&-
Close the standard input.

@item >&-
Close the standard output.

@item <&p
The input from the coprocess is moved to the standard input.

@item >&p
The output to the coprocess is moved to the standard output.
@end table

@noindent
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 (@var{file descriptor},
@var{file}) association at the time of evaluation.  For example:

@code{@dots{} 1>@var{fname} 2>&1}

@noindent
first associates file descriptor 1 with file @var{fname}.  It then
associates file descriptor 2 with the file associated with file
descriptor 1 (that is, @var{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 @var{fname}.

@noindent
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 @code{tee(1)}, 
@pindex MULTIOS, use of
provided the @code{MULTIOS} option is set.  Thus:

@code{date >foo >bar}

@noindent
writes the date to two files, named @file{foo} and @file{bar}.  Note
that a pipe is an implicit indirection; thus

@code{date >foo | cat}

@noindent
writes the date to the file @file{foo}, and also pipes it to @code{cat}.

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

@code{: > *}

@noindent
will truncate all files in the current directory, assuming there's at least 
one.  (Without the @code{MULTIOS} option, it would create an empty file called
@file{*}.)

@noindent
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 @code{cat(1)}, provided the @code{MULTIOS} option is set.  Thus

@code{sort <foo <fubar}

@noindent
or even

@code{sort <f@{oo,ubar@}}

@noindent
is equivalent to @samp{cat foo fubar | sort}.  Similarly, you can do

@code{echo exit 0 >> *.sh}

Note that a pipe is an implicit indirection; thus

@code{cat bar | sort <foo}

@noindent
is equivalent to @samp{cat bar foo | sort} (note the order of the inputs).

@noindent
If the @code{MULTIOS} option is unset, each redirection replaces the previous
redirection for that file descriptor.  However, all files redirected to are 
actually opened, so

@code{echo foo > bar > baz}

when @code{MULTIOS} is unset will truncate @code{bar}, and write @code{foo}
into @code{baz}.

@noindent
If a simple command consists of one or more redirection operators and
zero or more parameter assignments, but no command name, the command
@code{cat} is assumed.  Thus

@code{< file}

@noindent
copies the contents of @code{file} to the standard output.

@noindent
If a command is followed by @code{&} and job control is not active, then
the default standard input for the command is the empty file
@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.

@node Command Execution, Functions, Redirection, Top
@chapter Command Execution
@cindex command execution
@cindex execution, of commands

@noindent
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 below (@pxref{Functions}).  If there exists a shell builtin
by that name, the builtin is invoked.

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

@noindent
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.
@code{/bin/sh} is spawned to execute it.  If the program is a file
beginning with @code{#!}, 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.

@node Functions, Jobs & Signals, Command Execution, Top
@chapter Functions
@cindex functions

@noindent
@findex function
Shell functions are defined with the @code{function} reserved word or the
special syntax `@var{funcname} @code{()}'.
Shell functions are read in and stored internally.  Alias names are
resolved when the function is read.  Functions are executed like
commands with the arguments passed as positional parameters.

@noindent
Functions execute in the same process as the caller and share all files
and the present working directory with the caller.  A trap on
@code{EXIT} set inside a function is executed after the function
completes in the environment of the caller.

@noindent
The @code{return} builtin is used to return from function calls.
@findex return, use of

@noindent
Function identifiers can be listed with the @code{functions} builtin.
@findex functions, use of
@findex unfunction, use of
Functions can be undefined with the @code{unfunction} builtin.

@noindent
The following functions, if defined, have special meaning to the shell:

@table @code
@item chpwd
Executed whenever the current working directory is changed.
@findex chpwd

@item precmd
Executed before each prompt.
@findex precmd

@item preexec
Executed just after a command has been read and is about to be
executed.  If the history mechanism is active, the string to be
executed is passed as an argument.
@findex preexec

@item periodic
If the parameter @code{PERIOD} is set, this function is executed every
@vindex PERIOD
@findex periodic
@code{PERIOD} seconds, just before a prompt.

@cindex signals, trapping
@cindex trapping signals
@item TRAP@var{xxx}
If defined and non-null, this function will be executed whenever the
shell catches a signal @code{SIG@var{xxx}}, where @var{xxx} is a signal
name as specified for the @code{kill} builtin (@pxref{Shell Builtin
Commands}).  In addition, @code{TRAPZERR} is executed whenever a command
@findex TRAPZERR
has a non-zero exit status, @code{TRAPDEBUG} is executed after each
@findex TRAPDEBUG
command, and @code{TRAPEXIT} is executed when the shell exits, or when
@findex TRAPEXIT
the current function exits if defined inside a function.  If a function
of this form is defined and null, the shell and processes spawned by it
will ignore @code{SIG@var{xxx}}.
@end table

@node Jobs & Signals, Arithmetic Evaluation, Functions, Top
@chapter Jobs & Signals
@cindex jobs

@noindent
If the @code{MONITOR} option is set, an interactive shell associates a
@pindex MONITOR, use of
@dfn{job} with each pipeline.  It keeps a table of current jobs,
@findex jobs, use of
printed by the @code{jobs} command, and assigns them small integer
numbers.  When a job is started asynchronously with @code{&}, the shell
prints a line which looks like:

@code{[1] 1234}

@noindent
indicating that the job which was started asynchronously was job number
1 and had one (top-level) process, whose process id was 1234.

@noindent
If a job is started with @code{&|} or @code{&!}, then that job is
immediately disowned.  After startup, it does not have a place in the job
table, and is not subject to the job control features described here.

@noindent
If you are running a job and wish to do something else you may hit the
key @kbd{^Z} (control-Z) which sends a @code{TSTP} signal to the current
@cindex jobs, suspending
@cindex suspending jobs
@kindex CTRL-Z
job.  The shell will then normally indicate that the job has been
@dfn{suspended}, and print another prompt.  You can then manipulate the
state of this job, putting it into the background with the @code{bg}
@findex bg, use of
command, or run some other commands and then eventually bring the job
back into the foreground with the foreground command @code{fg}.  A
@findex fg, use of
@kbd{^Z} takes effect immediately and is like an interrupt in that
pending output and unread input are discarded when it is typed.

@noindent
A job being run in the background will suspend if it tries to read from
@cindex jobs, background, IO
@cindex background jobs, IO
the terminal.  Background jobs are normally allowed to produce output,
but this can be disabled by giving the command @code{stty tostop}.  If
you set this tty option, then background jobs will suspend when they try
to produce output, like they do when they try to read input.

@noindent
There are several ways to refer to jobs in the shell.  A job can be
@cindex jobs, referring to
@cindex referring to jobs
referred to by the process id of any process of the job or by one of the
following:

@table @code
@item %@var{number}
The job with the given number.

@item %@var{string}
Any job whose command line begins with @var{string}.

@item %?@var{string}
Any job whose command line contains @var{string}.

@item %%
Current job.

@item %+
Equivalent to @code{%%}.

@item %-
Previous job.
@end table

@noindent
The shell learns immediately whenever a process changes state.  It
normally informs you whenever a job becomes blocked so that no further
progress is possible.  If @code{notify} is not set, it waits until just
@findex notify, use of
before it prints a prompt before it informs you.

@noindent
When the monitor mode is on, each background job that completes triggers
any trap set for @code{CHLD}.

@noindent
When you try to leave the shell while jobs are running or suspended, you
will be warned that @samp{You have suspended (running) jobs}.  You may
use the @code{jobs} command to see what they are.  If you do this or
immediately try to exit again, the shell will not warn you a second
time; the suspended jobs will be terminated, and the running jobs will
be sent a @code{SIGHUP} signal.  To avoid having the shell terminate the
running jobs, either use the @code{nohup(1)} command or the
@code{disown} builtin (@pxref{Shell Builtin Commands}).
@cindex jobs, disowning
@findex disown, use of
@cindex disowning jobs

@noindent
The @code{INT} and @code{QUIT} signals for an invoked command are
@cindex signals
ignored if the command is followed by @code{&} and the job @code{monitor}
option is not active.  Otherwise, signals have the values inherited by
the shell from its parent (but @xref{Functions}, for the
@code{TRAP@var{xxx}} special functions).


@node Arithmetic Evaluation, Conditional Expressions, Jobs & Signals, Top
@chapter Arithmetic Evaluation
@cindex arithmetic evaluation
@cindex evaluation, arithmetic

@noindent
An ability to perform integer arithmetic is provided with the builtin
@code{let}.  Evaluations are performed using @emph{long} arithmetic.  A
leading @code{0x} or @code{0X} denotes hexadecimal.  Otherwise, numbers are
of the form @code{[@var{base}#]@var{n}} where @var{base} is a decimal number 
between two and thirty-six representing the arithmetic base and @var{n} is a 
number in that base (for example, @code{16#ff} is 255 in hexadecimal).  If 
@var{base} is omitted then base 10 is used.  For backwards compatibility 
the form @code{[16]ff} is also accepted.

@noindent
An arithmetic expression uses nearly the same syntax, precedence, and
@cindex arithmetic operators
@cindex operators, arithmetic
associativity of expressions in C.  The following operators are
supported (listed in decreasing order of precedence):

@table @code
@item + - ! ~ ++ --
Unary plus/minus, logical NOT, complement, @{pre,post@}@{in,de@}crement

@item << >>
Bitwise shift left, right.

@item &
Bitwise AND

@item ^
Bitwise XOR

@item |
Bitwise OR

@item **
Exponentiation

@item * / %
Multiplication, division, modulus (remainder)

@item + -
Addition, subtraction

@item < > <= >=
Comparison

@item == !=
Equality and inequality

@item &&
Logical AND

@item || ^^
Logical OR, XOR

@item ? :
Ternary operator

@item = += -= *= /= %= &= ^= |= <<= >>= &&= ||= ^^= **=
Assignment

@item ,
Comma operator
@end table

@noindent
The operators @code{&&}, @code{||}, @code{&&=}, and @code{||=} are
short-circuiting, and only one of the latter two expressions in a
ternary operator is evaluated.  Note the precedence of the bitwise AND,
OR, and XOR operators.

@noindent
An expression of the form @code{#\x} where @code{x} is any character
gives the ASCII value of this character.  An expression of the form
@code{#foo} gives the ASCII value of the first character of the value of
the parameter @code{foo}.

@noindent
Named parameters and subscripted arrays can be referenced by name within an 
arithmetic expression without using the parameter substitution syntax.

@noindent
An internal integer representation of a named parameter can be specified
with the @code{integer} builtin.  Arithmetic evaluation is performed on
@cindex parameters, integer
@cindex integer parameters
@findex integer, use of
the value of each assignment to a named parameter declared integer in
this manner.

@noindent
Since many of the arithmetic operators require quoting, an alternative
form of the @code{let} command is provided.  For any command which
@findex let, use of
begins with a @code{((}, all the characters until a matching @code{))}
are treated as a quoted expression.  More precisely, @code{(( @dots{} ))} is
equivalent to @code{let "@dots{}"}.

@node Conditional Expressions, Compatibility, Arithmetic Evaluation, Top
@chapter Conditional Expressions
@cindex conditional expressions
@cindex expressions, conditional

@noindent
A @dfn{conditional expression} is used with the @code{[[} compound
command to test attributes of files and to compare strings.  Each
expression can be constructed from one or more of the following unary or
binary expressions:

@table @code
@item -a @var{file}
True if @var{file} exists.

@item -b @var{file}
True if @var{file} exists and is a block special file.

@item -c @var{file}
True if @var{file} exists and is a character special file.

@item -d @var{file}
True if @var{file} exists and is a directory.

@item -e @var{file}
True if @var{file} exists.

@item -f @var{file}
True if @var{file} exists and is an ordinary file.

@item -g @var{file}
True if @var{file} exists and has its setgid bit set.

@item -h @var{file}
True if @var{file} exists and is a symbolic link.

@item -k @var{file}
True if @var{file} exists and has its sticky bit set.

@item -n @var{string}
True if length of @var{string} is non-zero.

@item -o @var{option}
True if option named @var{option} is on.  @var{option} may be a
single character, in which case it is a single letter option name.  
@xref{Specifying Options}.

@item -p @var{file}
True if @var{file} exists and is a FIFO special file or a pipe.

@item -r @var{file}
True if @var{file} exists and is readable by the current process.

@item -s @var{file}
True if @var{file} exists and has size greater than zero.

@item -t @var{fd}
True if file descriptor number @var{fd} is open and associated with a
terminal device (note: @var{fd} is not optional).

@item -u @var{file}
True if @var{file} exists and has its setuid bit set.

@item -w @var{file}
True if @var{file} exists and is writable by current process.

@item -x @var{file}
True if @var{file} exists and is executable by current process.  If
@var{file} exists and is a directory, then the current process has
permission to search in the directory.

@item -z @var{string}
True if length of @var{string} is zero.

@item -L @var{file}
True if @var{file} exists and is a symbolic link.

@item -O @var{file}
True if @var{file} exists and is owned by the effective user id of this
process.

@item -G @var{file}
True if @var{file} exists and its group matches the effective group id
of this process.

@item -S @var{file}
True if @var{file} exists and is a socket.

@item -N @var{file}
True if @var{file} exists and its access time is not newer than its
modification time.

@item @var{file1} -nt @var{file2}
True if @var{file1} exists and is newer than @var{file2}.

@item @var{file1} -ot @var{file2}
True if @var{file1} exists and is older than @var{file2}.

@item @var{file1} -ef @var{file2}
True if @var{file1} and @var{file2} exist and refer to the same file.

@item @var{string} == @var{pattern}
@itemx @var{string} = @var{pattern}
True if @var{string} matches @var{pattern}.  The first form is the 
preferred one.  The other form is for backward compatibility and should 
be considered obsolete.

@item @var{string} != @var{pattern}
True if @var{string} does not match @var{pattern}.

@item @var{string1} < @var{string2}
True if @var{string1} comes before @var{string2} based on ASCII value of
their characters.

@item @var{string1} > @var{string2}
True if @var{string1} comes after @var{string2} based on ASCII value of
their characters.

@item @var{exp1} -eq @var{exp2}
True if @var{exp1} is equal to @var{exp2}.

@item @var{exp1} -ne @var{exp2}
True if @var{exp1} is not equal to @var{exp2}.

@item @var{exp1} -lt @var{exp2}
True if @var{exp1} is less than @var{exp2}.

@item @var{exp1} -gt @var{exp2}
True if @var{exp1} is greater than @var{exp2}.

@item @var{exp1} -le @var{exp2}
True if @var{exp1} is less than or equal to @var{exp2}.

@item @var{exp1} -ge @var{exp2}
True if @var{exp1} is greater than or equal to @var{exp2}.

@item ( @var{exp} )
True if @var{exp} is true.

@item ! @var{exp}
True if @var{exp} is false.

@item @var{exp1} && @var{exp2}
True if @var{exp1} and @var{exp2} are both true.

@item @var{exp1} || @var{exp2}
True if either @var{exp1} or @var{exp2} is true.
@end table

@noindent
In each of the above expressions, if @var{file} is of the form
@samp{/dev/fd/@var{n}}, where @var{n} is an integer, then the test is
applied to the open file whose descriptor number is @var{n}, even if
the underlying system does not support the @file{/dev/fd}
directory.


@node Compatibility, Zsh Line Editor, Conditional Expressions, Top
@chapter Compatibility
@cindex compatibility
@cindex sh, compatibility
@cindex ksh, compatibility

@noindent
@code{zsh} tries to emulate @code{sh} or @code{ksh} when it is invoked
as @code{sh} or @code{ksh} respectively.  In this mode the following
parameters are not special: @code{ARGC}, @code{argv}, @code{cdpath},
@code{fignore}, @code{fpath}, @code{HISTCHARS}, @code{mailpath},
@code{MANPATH}, @code{manpath}, @code{path}, @code{prompt},
@code{PROMPT}, @code{PROMPT2}, @code{PROMPT3}, @code{PROMPT4},
@code{psvar}, @code{status}, @code{watch}.

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

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


@node Zsh Line Editor, Parameters, Compatibility, Top
@chapter Zsh Line Editor
@cindex line editor
@cindex editor, line

@noindent
If the @code{ZLE} option is set (it is by default) and the shell input is
@pindex ZLE, use of
attached to the terminal, the user is allowed to edit command lines.

@noindent
There are two display modes.  The first, multi-line mode, is the default.
It only works if the @code{TERM} parameter is set to a valid terminal
@vindex TERM
type that can move the cursor up.  The second, single line mode, is used
if @code{TERM} is invalid or incapable of moving the cursor up, or if
the @code{SINGLE_LINE_ZLE} option is set.  This mode is similar to ksh,
@pindex SINGLE_LINE_ZLE, use of
@cindex ksh, editor mode
@cindex editor, modes
and uses no termcap sequences.  If @code{TERM} is @samp{emacs}, the
@code{ZLE} option will be unset by the shell.

@section Bindings
@noindent
Command bindings may be set using the @code{bindkey} builtin.  There are
@cindex bindings, key
@cindex key bindings
two keymaps; the main keymap and the alternate keymap.  The alternate
keymap is bound to vi command mode.  The main keymap is bound to emacs
mode by default.  To bind the main keymap to vi insert mode, use
@code{bindkey -v}.  However, if either of
@findex bindkey, use of
the @code{VISUAL} or @code{EDITOR} environment variables contains the
@vindex VISUAL
@vindex EDITOR
string @samp{vi} when the shell starts up the main keymap will be bound
to vi insert mode by default.

@noindent
The following is a list of all the key commands and their default
bindings in emacs mode, vi command mode and vi insert mode.

@menu
* Movement::			
* History Control::		
* Modifying Text::		
* Arguments::			
* Completion::			
* Miscellaneous::		
@end menu

@node Movement, History Control,  , Zsh Line Editor
@section Movement

@table @code
@item vi-backward-blank-word (unbound) (@kbd{B}) (unbound)
@kindex B
Move backward one word, where a word is defined as a series of non-blank
characters.
@tindex vi-backward-blank-word

@item backward-char (@kbd{^B} @kbd{ESC-[D}) (unbound)
@tindex backward-char
@kindex CTRL-B
@kindex ESC-[D
Move backward one character.

@item vi-backward-char (unbound) (@kbd{^H} @kbd{h} @kbd{^?}) (unbound)
@tindex vi-backward-char
@kindex CTRL-H
@kindex h
@kindex CTRL-?
Move backward one character, without changing lines.

@item backward-word (@kbd{ESC-B} @kbd{ESC-b}) (unbound) (unbound)
@tindex backward-word
@kindex ESC-B
@kindex ESC-b
Move to the beginning of the previous word.

@item emacs-backward-word
@tindex emacs-backward-word
Move to the beginning of the previous word.

@item vi-backward-word (unbound) (@kbd{b}) (unbound)
@tindex vi-backward-word
@kindex b
Move to the beginning of the previous word, vi-style.

@item beginning-of-line (@kbd{^A}) (unbound) (unbound)
@tindex beginning-of-line
@kindex CTRL-A
Move to the beginning of the line.  If already at the beginning of the
line, move to the beginning of the previous line, if any.

@item vi-beginning-of-line
@tindex vi-beginning-of-line
Move to the beginning of the line, without changing lines.

@item end-of-line (@kbd{^E}) (unbound) (unbound)
@tindex end-of-line
@kindex CTRL-E
Move to the end of the line.  If already at the end of the line, move to
the end of the next line, if any.

@item vi-end-of-line (unbound) (@kbd{$}) (unbound)
@tindex vi-end-of-line
@kindex $
Move to the end of the line.  If an argument is given to this command,
the cursor will be moved to the end of the line (argument - 1) lines down.

@item vi-forward-blank-word (unbound) (@kbd{W}) (unbound)
@tindex vi-forward-blank-word
@kindex W
Move forward one word, where a word is defined as a series of non-blank
characters.

@item vi-forward-blank-word-end (unbound) (@kbd{E}) (unbound)
@tindex vi-forward-blank-word-end
@kindex E
Move to the end of the current word, or, if at the end of the current
word, to the end of the next word, where a word is defined as a series
of non-blank characters.

@item forward-char (@kbd{^F} @kbd{ESC-[C}) (unbound) (unbound)
@tindex forward-char
@kindex CTRL-F
@kindex ESC-[C
Move forward one character.

@item vi-forward-char (unbound) (@key{SPACE} @kbd{l}) (unbound)
@tindex vi-forward-char
@kindex l
@kindex SPACE
Move forward one character.

@item vi-find-next-char (@kbd{^X^F}) (@kbd{f}) (unbound)
@tindex vi-find-next-char
@kindex CTRL-X CTRL-F
@kindex f
Read a character from the keyboard, and move to the next occurrence of
it in the line.

@item vi-find-next-char-skip (unbound) (@kbd{t}) (unbound)
@tindex vi-find-next-char-skip
@kindex t
Read a character from the keyboard, and move to the position just before
the next occurrence of it in the line.

@item vi-find-prev-char (unbound) (@kbd{F}) (unbound)
@tindex vi-find-prev-char
@kindex F
Read a character from the keyboard, and move to the previous occurrence
of it in the line.

@item vi-find-prev-char-skip (unbound) (@kbd{T}) (unbound)
@tindex vi-find-prev-char-skip
@kindex T
Read a character from the keyboard, and move to the position just after
the previous occurrence of it in the line.

@item vi-first-non-blank (unbound) (@kbd{^}) (unbound)
@tindex vi-first-non-blank
@kindex ^
Move to the first non-blank character in the line.

@item vi-forward-word (unbound) (@kbd{w}) (unbound)
@tindex vi-forward-word
@kindex w
Move forward one word, vi-style.

@item forward-word (@kbd{ESC-F} @kbd{ESC-f}) (unbound) (unbound)
@tindex forward-word
@kindex ESC-F
@kindex ESC-f
Move to the beginning of the next word.  The editor's idea of a word is
specified with the @code{WORDCHARS} parameter.

@item emacs-forward-word
@tindex emacs-forward-word
Move to the end of the next word.

@item vi-forward-word-end (unbound) (@kbd{e}) (unbound)
@tindex vi-forward-word-end
@kindex e
Move to the end of the next word.

@item vi-goto-column (@kbd{ESC-|}) (@kbd{|}) (unbound)
@tindex vi-goto-column
@kindex ESC-|
@kindex |
Move to the column specified by the numeric argument.

@item vi-goto-mark (unbound) (@kbd{`}) (unbound)
@tindex vi-goto-mark
@kindex `
Move to the specified mark.

@item vi-goto-mark-line (unbound) (@kbd{'}) (unbound)
@tindex vi-goto-mark-line
@kindex '
Move to the beginning of the line containing the specified mark.

@item vi-repeat-find (unbound) (@kbd{;}) (unbound)
@tindex vi-repeat-find
@kindex ;
Repeat the last @code{vi-find} command.

@item vi-rev-repeat-find (unbound) (@kbd{,}) (unbound)
@tindex vi-rev-repeat-find
@kindex ,
Repeat the last @code{vi-find} command in the opposite direction.
@end table

@node History Control, Modifying Text, Movement, Zsh Line Editor
@section History Control

@table @code
@item beginning-of-buffer-or-history (@kbd{ESC-<}) (unbound) (unbound)
@tindex beginning-of-buffer-or-history
@kindex ESC-<
Move to the beginning of the buffer, or if already there, move to the
first event in the history list.

@item beginning-of-line-hist
@tindex beginning-of-line-hist
Move to the beginning of the line.  If already at the beginning of the
buffer, move to the previous history line.

@item beginning-of-history
@tindex beginning-of-history
Move to the first event in the history list.

@item down-line-or-history (@kbd{^N} @kbd{ESC-[B}) (@kbd{j}) (unbound)
@tindex down-line-or-history
@kindex CTRL-N
@kindex ESC-[B
@kindex j
Move down a line in the buffer, or if already at the bottom line, move
to the next event in the history list.

@item vi-down-line-or-history (unbound) (@kbd{+}) (unbound)
@tindex vi-down-line-or-history
@kindex +
Move down a line in the buffer, or if already at the bottom line, move to 
the next event in the history list.  Then move to the first non-blank 
character on the line.

@item down-line-or-search
@tindex down-line-or-search
Move down a line in the buffer, or if already at the bottom line,
search forward in the history for a line beginning with the first
word in the buffer.

@item down-history (unbound) (@kbd{^N}) (unbound)
@tindex down-history
@kindex CTRL-N
Move to the next event in the history list.

@item history-beginning-search-backward
@tindex history-beginning-search-backward
Search backward in the history for a line beginning with the current
line up to the cursor.  This leaves the cursor in its original position.

@item end-of-buffer-or-history (@kbd{ESC->}) (unbound) (unbound)
@kindex ESC->
@tindex end-of-buffer-or-history
Move to the end of the buffer, or if already there, move to the last
event in the history list.

@item end-of-line-hist
@tindex end-of-line-hist
Move to the end of the line.  If already at the end of the buffer, move
to the next history line.

@item end-of-history
@tindex end-of-history
Move to the last event in the history list.

@item vi-fetch-history (unbound) (@kbd{G}) (unbound)
@tindex vi-fetch-history
Fetch the history line specified by the numeric argument.
This defaults to the current history line (i.e. the one that isn't history 
yet).
@kindex G

@item history-incremental-search-backward (@kbd{^R} @kbd{^Xr}) (unbound) (unbound)
@tindex history-incremental-search-backward
@kindex CTRL-R
@kindex CTRL-X r
Search backward incrementally for a specified string.  The string may
begin with @code{^} to anchor the search to the beginning of the line.
A restricted set of editing functions is available in the mini-buffer.
An interrupt signal, as defined by the stty setting, will stop the
search and go back to the original line.  An undefined key will have the
same effect.  The supported functions are: @code{backward-delete-char},
@code{vi-backward-delete-character}, @code{clearscreen}, @code{redisplay},
@code{quoted-insert}, @code{vi-quoted-insert}, @code{accept-and-hold},
@code{accept-and-infer-next-history}, @code{accept-line} and
@code{accept-line-and-down-history}; @code{magic-space} just inserts a
space.  @code{vi-cmd-mode} toggles between the main and alternate key
bindings; the main key bindings (insert mode) will be selected initially.
Any string that is bound to an out-string (via @code{bindkey -s}) 
will behave as if out-string were typed directly.  Typing the
binding of @code{history-incremental-search-backward} will get the next
occurrence of the contents of the mini-buffer.  Typing the binding of
@code{history-incremental-search-forward} inverts the sense of the
search.  The direction of the search is indicated in the mini-buffer.
Any single character that is not bound to one of the above functions,
or @code{self-insert} or @code{self-insert-unmeta} will have the same 
effect but the function will be executed.

@item history-incremental-search-forward (@kbd{^S} @kbd{^Xs}) (unbound) (unbound)
@tindex history-incremental-search-forward
@kindex CTRL-S
@kindex CTRL-X s
Search forward incrementally for a specified string.  The string may
begin with @code{^} to anchor the search to the beginning of the line.
The functions available in the mini-buffer are the same as for
@code{history-incremental-search-backward}.

@item history-search-backward (@kbd{ESC-P} @kbd{ESC-p}) (unbound) (unbound)
@tindex history-search-backward
@kindex ESC-P
@kindex ESC-p
Search backward in the history for a line beginning with the first word
in the buffer.  

@item vi-history-search-backward (unbound) (@kbd{/}) (unbound)
@tindex vi-history-search-backward
@kindex ?
Search backward in the history for a specified string.  The string may
begin with @code{^} to anchor the search to the beginning of the line.
A restricted set of editing functions is available in the mini-buffer.
An interrupt signal, as defined by the stty setting, will stop the
search.  The functions available in the mini-buffer are: @code{accept-line},
@code{vi-cmd-mode} (treated the same as @code{acceptline}), 
@code{backward-delete-char}, @code{vi-backward-delete-char},
@code{backward-kill-word}, @code{vi-backward-kill-word}, @code{clear-screen},
@code{redisplay}, @code{magic-space} (treated as a space),
@code{quoted-insert} and @code{vi-quoted-insert}.  Any string that is not
bound to an out-string (via @code{bindkey -s}) will behave as if out-string
were typed directly. Any other character that is not bound to 
@code{self-insert} or @code{self-insert-unmeta} will beep and be ignored.  If 
the function is called from vi command mode, the bindings of the current 
insert mode will be used.

@item history-search-forward (@kbd{ESC-N} @kbd{ESC-n}) (unbound) (unbound)
@tindex history-search-forward
@kindex ESC-N
@kindex ESC-n
Search forward in the history for a line beginning with the first word
in the buffer.

@item vi-history-search-forward (unbound) (@kbd{?}) (unbound)
@tindex vi-history-search-forward
@kindex /
Search forward in the history for a specified string.  The string may
begin with @code{^} to anchor the search to the beginning of the line.
The functions available in the mini-buffer are the same as for
@code{vi-history-search-backward}.

@item infer-next-history (@kbd{^X^N}) (unbound) (unbound)
@tindex infer-next-history
@kindex CTRL-X CTRL-N
Search in the history for a line matching the current one and fetch the
event following it.

@item insert-last-word (@kbd{ESC-_} @kbd{ESC-.}) (unbound) (unbound)
@tindex insert-last-word
@kindex ESC-_
@kindex ESC-.
Insert the last word from the previous history event at the cursor
position.  If a positive numeric argument is given, insert that word
from the end of the previous history event.  If the argument is zero
or negative insert that word from the left (zero inserts the previous
command word).

@item vi-repeat-search (unbound) (@kbd{n}) (unbound)
@tindex vi-repeat-search
@kindex n
Repeat the last vi history search.

@item vi-rev-repeat-search (unbound) (@kbd{N}) (unbound)
@tindex vi-rev-repeat-search
@kindex N
Repeat the last vi history search, but in reverse.

@item up-line-or-history (@kbd{^P} @kbd{ESC-[A}) (@kbd{k}) (unbound)
@tindex up-line-or-history
@kindex CTRL-P
@kindex ESC-[A
@kindex k
Move up a line in the buffer, or if already at the top line, move to the
previous event in the history list.

@item up-line-or-search
@tindex up-line-or-search
Move up a line in the buffer, or if already at the top line, search
backward in the history for a line beginning with the first word in the
buffer.

@item up-history (unbound) (@kbd{^P}) (unbound)
@tindex up-history
@kindex CTRL-P
Move to the previous event in the history list.

@item history-beginning-search-forward
@tindex history-beginning-search-forward
Search forward in the history for a line beginning with the current line
up to the cursor.  This leaves the cursor at its original position.
@end table


@node Modifying Text, Arguments, History Control, Zsh Line Editor
@section Modifying Text

@table @code
@item vi-add-eol (unbound) (@kbd{A}) (unbound)
@tindex vi-add-eol
@kindex A
Move to the end of the line and enter insert mode.

@item vi-add-next (unbound) (@kbd{a}) (unbound)
@tindex vi-add-next
@kindex a
Enter insert mode after the current cursor position, without changing lines.

@item backward-delete-char (@kbd{^H} @kbd{^?}) (unbound) (unbound)
@tindex backward-delete-char
@kindex CTRL-H
@kindex CTRL-?
Delete the character behind the cursor.

@item vi-backward-delete-char (unbound) (@kbd{X}) (@kbd{^H})
@tindex vi-backward-delete-char
@kindex X
Delete the character behind the cursor, without changing lines.  If in
insert mode this won't delete past the point where insert mode was last
entered.

@item backward-delete-word
@tindex backward-delete-word
Delete the word behind the cursor.

@item backward-kill-line
@tindex backward-kill-line
Kill from the beginning of the line to the cursor position.

@item backward-kill-word (@kbd{^W} @kbd{ESC-^H} @kbd{ESC-^?}) (unbound) (unbound)
@tindex backward-kill-word
@kindex CTRL-W
@kindex ESC-CTRL-H
@kindex ESC-CTRL-?
Kill the word behind the cursor.

@item vi-backward-kill-word (unbound) (unbound) (@kbd{^W})
@tindex vi-backward-kill-word
@kindex CTRL-W
Kill the word behind the cursor, without going past the point where insert
mode was last entered.

@item capitalize-word (@kbd{ESC-C} @kbd{ESC-c}) (unbound) (unbound)
@tindex capitalize-word
@kindex ESC-C
@kindex ESC-c
Capitalize the current word and move past it.

@item vi-change (unbound) (@kbd{c}) (unbound)
@tindex vi-change
@kindex c
Read a movement command from the keyboard, and kill from the cursor
position to the endpoint of the movement.  Then enter insert mode.  If
the command is @code{vi-change}, kill the current line.

@item vi-change-eol (unbound) (@kbd{C}) (unbound)
@tindex vi-change-eol
@kindex C
Kill to the end of the line and enter insert mode.

@item vi-change-whole-line (unbound) (@kbd{S}) (unbound)
@tindex vi-change-whole-line
@kindex S
Kill the current line and enter insert mode.

@item copy-region-as-kill (@kbd{ESC-W} @kbd{ESC-w}) (unbound) (unbound)
@tindex copy-region-as-kill
@kindex ESC-W
@kindex ESC-w
Copy the area from the cursor to the mark to the kill buffer.

@item copy-prev-word (@kbd{ESC-^_}) (unbound) (unbound)
@tindex copy-prev-word
@kindex ESC-CTRL-_
Duplicate the word behind the cursor.

@item vi-delete (unbound) (@kbd{d}) (unbound)
@tindex vi-delete
@kindex d
Read a movement command from the keyboard, and kill from the cursor
position to the endpoint of the movement.  If the command is
@code{vi-delete}, kill the current line.

@item delete-char
@tindex delete-char
Delete the character under the cursor.

@item vi-delete-char (unbound) (@kbd{x}) (unbound)
@tindex vi-delete-char
Delete the character under the cursor, without going past the end of the
line.

@item delete-word
@tindex delete-word
Delete the current word.

@item down-case-word (@kbd{ESC-L} @kbd{ESC-l}) (unbound) (unbound)
@tindex down-case-word
@kindex ESC-L
@kindex ESC-l
Convert the current word to all lowercase and move past it.

@item kill-word (@kbd{ESC-D} @kbd{ESC-d}) (unbound) (unbound)
@tindex kill-word
@kindex ESC-D
@kindex ESC-d
Kill the current word.

@item gosmacs-transpose-chars
@tindex gosmacs-transpose-chars
Exchange the two characters behind the cursor.

@item vi-indent (unbound) (@kbd{>}) (unbound)
@tindex vi-indent
@kindex >
Indent a number of lines.

@item vi-insert (unbound) (@kbd{i}) (unbound)
@tindex vi-insert
@kindex i
Enter insert mode.

@item vi-insert-bol (unbound) (@kbd{I}) (unbound)
@tindex vi-insert-bol
@kindex I
Move to the beginning of the line and enter insert mode.

@item vi-join (@kbd{^X^J}) (@kbd{J}) (unbound)
@tindex vi-join
@kindex CTRL-X CTRL-J
@kindex J
Join the current line with the next one.

@item kill-line (@kbd{^K}) (unbound) (unbound)
@tindex kill-line
@kindex CTRL-K
Kill from the cursor to the end of the line.

@item vi-kill-line (unbound) (unbound) (@kbd{^U})
@tindex vi-kill-line
@kindex CTRL-U
Kill from the cursor back to wherever insert mode was last entered.

@item vi-kill-eol (unbound) (@kbd{D}) (unbound)
@tindex vi-kill-eol
@kindex D
Kill from the cursor to the end of the line.

@item kill-region
@tindex kill-region
Kill from the cursor to the mark.

@item kill-buffer (@kbd{^X^K}) (unbound) (unbound)
@tindex kill-buffer
@kindex CTRL-X CTRL-K
Kill the entire buffer.

@item kill-whole-line (@kbd{^U}) (unbound) (unbound)
@tindex kill-whole-line
@kindex CTRL-U
Kill the current line.

@item vi-match-bracket (@kbd{^X^B}) (@kbd{%}) (unbound)
@tindex vi-match-bracket
@kindex CTRL-X CTRL-B
@kindex %
Move to the bracket character (one of @code{@{@}}, @code{()}, or
@code{[]}) that matches the one under the cursor.  If the cursor is not on a
bracket character, move forward without going past the end of the line to
find one, and then go to the matching bracket.

@item vi-open-line-above (unbound) (@kbd{O}) (unbound)
@tindex vi-open-line-above
@kindex O
Open a line above the cursor and enter insert mode.

@item vi-open-line-below (unbound) (@kbd{o}) (unbound)
@tindex vi-open-line-below
@kindex o
Open a line below the cursor and enter insert mode.

@item vi-oper-swap-case
@tindex vi-oper-swap-case
Read a movement command from the keyboard, and swap the case of all
characters from the cursor position to the endpoint of the movement.  If
the movement command is @code{vi-oper-swap-case}, swap the case of all
characters on the current line.

@item overwrite-mode (@kbd{^X^O}) (unbound) (unbound)
@tindex overwrite-mode
@kindex CTRL-X CTRL-O
Toggle between overwrite mode and insert mode.

@item vi-put-before (unbound) (@kbd{P}) (unbound)
@tindex vi-put-before
@kindex P
Insert the contents of the kill buffer before the cursor.  If the kill
buffer contains a sequence of lines (as opposed to characters), paste it
above the current line.

@item vi-put-after (unbound) (@kbd{p}) (unbound)
@tindex vi-put-after
@kindex p
Insert the contents of the kill buffer after the cursor.  If the kill
buffer contains a sequence of lines (as opposed to characters), paste it
below the current line.

@item quoted-insert (@kbd{^V}) (unbound) (unbound)
@tindex quoted-insert
@kindex CTRL-V
Insert the next character typed into the buffer literally.  An interrupt
character will not be inserted.

@item vi-quoted-insert (unbound) (unbound) (@kbd{^Q} @kbd{^V})
@tindex vi-quoted-insert
@kindex CTRL-Q CTRL-V
Display a @code{^} at the current position, and insert the next character
typed into the buffer literally.  An interrupt character will not be inserted.

@item quote-line (@kbd{ESC-'}) (unbound) (unbound)
@tindex quote-line
@kindex ESC-'
Quote the current line; that is, put a @code{'} character at the
beginning and the end, and convert all @code{'} characters to
@code{\'}.

@item quote-region (@kbd{ESC-"}) (unbound) (unbound)
@tindex quote-region
@kindex ESC-"
Quote the region from the cursor to the mark.

@item vi-replace (unbound) (@kbd{R}) (unbound)
@tindex vi-replace
@kindex R
Enter overwrite mode.

@item vi-repeat-change (unbound) (@kbd{.}) (unbound)
@tindex vi-repeat-change
@kindex .
Repeat the last vi mode text modification.  If a count was used with the
modification, it is remembered.  If a count is given to this command, it
overrides the remembered count, and is remembered for future uses of this
command.  The cut buffer specification is similarly remembered.

@item vi-replace-chars (unbound) (@kbd{r}) (unbound)
@tindex vi-replace-chars
@kindex r
Replace the character under the cursor with a character read from the
keyboard.

@item self-insert (printable characters) (unbound) (printable characters and some control characters)
@tindex self-insert
Put a character in the buffer at the cursor position.

@item self-insert-unmeta (@kbd{ESC-^I} @kbd{ESC-^J} @kbd{ESC-^M}) (unbound) (unbound)
@tindex self-insert-unmeta
@kindex ESC-CTRL-I
@kindex ESC-CTRL-J
@kindex ESC-CTRL-M
Put a character in the buffer after stripping the meta bit and
converting @code{^M} to @code{^J}.

@item vi-substitute (unbound) (@kbd{s}) (unbound)
@tindex vi-substitute
@kindex s
Substitute the next character(s).

@item vi-swap-case (unbound) (@kbd{~}) (unbound)
@tindex vi-swap-case
@kindex ~
Swap the case of the character under the cursor and move past it.

@item transpose-chars (@kbd{^T}) (unbound) (unbound)
@tindex transpose-chars
@kindex CTRL-T
Exchange the two characters to the left of the cursor if at end of line,
else exchange the character under the cursor with the character to the
left.

@item transpose-words (@kbd{ESC-T} @kbd{ESC-t})  (unbound) (unbound)
@tindex transpose-words
@kindex ESC-T
@kindex ESC-t
Exchange the current word with the one before it.

@item vi-unindent (unbound) (@kbd{<}) (unbound)
@tindex vi-unindent
@kindex <
Unindent a number of lines.

@item up-case-word (@kbd{ESC-U} @kbd{ESC-u}) (unbound) (unbound)
@tindex up-case-word
@kindex ESC-U
@kindex ESC-u
Convert the current word to all caps and move past it.

@item yank (@kbd{^Y}) (unbound) (unbound) 
@tindex yank
@kindex CTRL-Y
Insert the contents of the kill buffer at the cursor position.

@item yank-pop (@kbd{ESC-y}) (unbound) (unbound)
@tindex yank-pop
@kindex ESC-y
Remove the text just yanked, rotate the kill-ring, and yank the new top.
Only works following @code{yank} or @code{yank-pop}.

@item vi-yank (unbound) (@kbd{y}) (unbound)
@tindex vi-yank
@kindex y
Read a movement command from the keyboard, and copy the region from the
cursor position to the endpoint of the movement into the kill buffer.
If the command is @code{vi-yank}, copy the current line.

@item vi-yank-whole-line (unbound) (@kbd{Y}) (unbound)
@tindex vi-yank-whole-line
@kindex Y
Copy the current line into the kill buffer.

@item vi-yank-eol
@tindex vi-yank-eol
Copy the region from the cursor position to the end of the line into the
kill buffer.  Arguably, this is what @kbd{Y} should do in vi, but it isn't
what it actually does.
@end table

@node Arguments, Completion, Modifying Text, Zsh Line Editor
@section Arguments

@table @code
@item digit-argument (@kbd{ESC-0}@dots{}@kbd{ESC-9}) (1-9) (unbound)
@tindex digit-argument
@kindex ESC-0
@kindex ESC-9
@kindex 1
@kindex 9
Start a new numeric argument, or add to the current one.  See also
@code{vi-digit-or-beginning-of-line}.

@item neg-argument (@kbd{ESC--}) (unbound) (unbound)
@tindex neg-argument
@kindex ESC--
Changes the sign of the following argument.

@item universal-argument
@tindex universal-argument
Multiply the argument of the next command by 4.
@end table

@node Completion, Miscellaneous, Arguments, Zsh Line Editor
@section Completion

@table @code
@item accept-and-menu-complete
@tindex accept-and-menu-complete
In a menu completion, insert the current completion into the buffer, and
advance to the next possible completion.

@item complete-word
@tindex complete-word
Attempt completion on the current word.

@item delete-char-or-list (@kbd{^D}) (unbound) (unbound)
@tindex delete-char-or-list
@kindex CTRL-D
Delete the character under the cursor.  If the cursor is at the end of
the line, list possible completions for the current word.

@item expand-cmd-path
@tindex expand-cmd-path
Expand the current command to its full pathname.

@item expand-or-complete (@key{TAB}) (unbound) (@key{TAB})
@tindex expand-or-complete
@kindex TAB
Attempt shell expansion on the current word.  If that fails, attempt
completion.

@item expand-or-complete-prefix
@tindex expand-or-complete-prefix
Attempt shell expansion on the current word up to cursor.

@item expand-history (@kbd{ESC-SPACE} @kbd{ESC-!}) (unbound) (unbound)
@tindex expand-history
@kindex ESC-SPACE
@kindex ESC-!
Perform history expansion on the edit buffer.

@item expand-word (@kbd{^X*}) (unbound) (unbound)
@tindex expand-word
@kindex CTRL-X *
Attempt shell expansion on the current word.

@item list-choices (@kbd{ESC-^D}) (@kbd{^D=}) (@kbd{^D})
@tindex list-choices
@kindex ESC-CTRL-D
@kindex CTRL-D
@kindex =
List possible completions for the current word.

@item list-expand (@kbd{^Xg} @kbd{^XG}) (@kbd{^G}) (@kbd{^G})
@tindex list-expand
@kindex CTRL-X g
@kindex CTRL-X G
@kindex CTRL-G
List the expansion of the current word.

@item magic-space
@tindex magic-space
Perform history expansion and insert a space into the buffer.  This is
intended to be bound to @key{SPACE}.

@item menu-complete
@tindex menu-complete
@pindex MENU_COMPLETE, use of
Like @code{complete-word}, except that menu completion is used.
@xref{Options}, for the @code{MENU_COMPLETE} option.

@item menu-expand-or-complete
@tindex menu-expand-or-complete
Like @code{expand-or-complete}, except that menu completion is used.

@item reverse-menu-complete
@tindex reverse-menu-complete
@xref{Options}, for the @code{MENU_COMPLETE} option.
@end table

@node Miscellaneous,  , Completion, Zsh Line Editor
@section Miscellaneous

@table @code
@item accept-and-hold (@kbd{ESC-A} @kbd{ESC-a}) (unbound) (unbound)
@tindex accept-and-hold
@kindex ESC-A
@kindex ESC-a
Push the contents of the buffer on the buffer stack and execute it.

@item accept-and-infer-next-history
@tindex accept-and-infer-next-history
Execute the contents of the buffer.  Then search the history list for a
line matching the current one and push the event following onto the
buffer stack.

@item accept-line (@kbd{^J} @kbd{^M}) (@kbd{^J} @kbd{^M}) (@kbd{^J} @kbd{^M})
@tindex accept-line
@kindex CTRL-J
@kindex CTRL-M
Execute the contents of the buffer.

@item accept-line-and-down-history (@kbd{^O}) (unbound) (unbound)
@tindex accept-line-and-down-history
@kindex CTRL-O
Execute the current line, and push the next history event on the the
buffer stack.

@item vi-cmd-mode (@kbd{^X^V}) (unbound) (@kbd{^[})
@tindex vi-cmd-mode
@kindex CTRL-X CTRL-V
@kindex CTRL-[
Enter command mode; that is, use the alternate keymap.  Yes, this is
bound by default in emacs mode.

@item vi-caps-lock-panic
@tindex vi-caps-lock-panic
Hang until any lowercase key is pressed.  This is for vi users without
the mental capacity to keep track of their caps lock key (like the
author).

@item clear-screen (@kbd{^L} @kbd{ESC-^L}) (@kbd{^L}) (@kbd{^L})
@tindex clear-screen
@kindex CTRL-L
@kindex ESC-CTRL-L
Clear the screen and redraw the prompt.

@item describe-key-briefly
@tindex describe-key-briefly
Waits for keypress, then prints the function bound to the pressed key.

@item exchange-point-and-mark (@kbd{^X^X}) (unbound) (unbound)
@tindex exchange-point-and-mark
@kindex CTRL-X CTRL-X
Exchange the cursor position with the position of the mark.

@item execute-named-cmd (@kbd{ESC-x}) (unbound) (unbound)
@tindex execute-named-cmd
@kindex ESC-x
Read the name of a editor command and execute it.  A restricted set of
editing functions is available in the mini-buffer.  An interrupt signal,
as defined by the stty setting, will abort the function.  The allowed
functions are: @code{backward-delete-char},
@code{vi-backward-delete-char}, @code{clear-screen}, 
@code{redisplay}, @code{quoted-insert}, @code{vi-quoted-insert},
@code{kill-region} (kills the last word), @code{backward-kill-word}, 
@code{vi-backward-kill-word}, @code{kill-whole-line}, @code{vi-kill-line}, 
@code{backward-kill-line}, @code{list-choices}, @code{delete-char-or-list},
@code{complete-word}, @code{expand-or-complete}, 
@code{expand-or-complete-prefix}, @code{accept-line}, and @code{vi-cmd-mode}
(treated the same as accept line).  The @key{SPC} and @key{TAB} characters,
if not bound to one of these functions, will complete the name and then list
the possibilities if the @code{AUTO_LIST} option is set.  Any string that is
bound to an out-string (via @code{bindkey -s}) will behave as if out-string
were typed directly.  Any other character that is not bound to 
@code{self-insert} or @code{self-insert-unmeta} will beep and be 
ignored.  If the function is called from vi command mode, the bindings of
the current insert mode will be used.  

@item execute-last-named-cmd (@kbd{ESC-z}) (unbound) (unbound)
@tindex execute-last-named-cmd
@kindex ESC-z
Redo the last function executed with @code{execute-named-cmd}.

@item get-line (@kbd{ESC-G} @kbd{ESC-g}) (unbound) (unbound)
@tindex get-line
@kindex ESC-G
@kindex ESC-g
Pop the top line off the buffer stack and insert it at the cursor
position.

@item pound-insert (unbound) (@kbd{#}) (unbound)
@tindex pound-insert
@kindex #
@pindex INTERACTIVE_COMMENTS, use of
If there is no @code{#} character at the beginning of the buffer,
add one to the beginning of each line.  If there is one, remove a @code{#}
from each line that has one.  In either case, accept the
current line.  The @code{INTERACTIVE_COMMENTS} option must be set for
this to have any usefulness.

@item vi-pound-insert 
@tindex vi-pound-insert
@pindex INTERACTIVE_COMMENTS, use of
If there is no @code{#} character at the beginning of the current line, add 
one.  If there is one, remove it.  The @code{INTERACTIVE_COMMENTS} option 
must be set for this to have any usefulness.

@item push-input
@tindex push-input
Push the entire current multi-line construct onto the buffer stack and
return to the top-level (@code{PS1}) prompt.  If the current parser
construct is only a single line, this is exactly like @code{push-line}.
Next time the editor starts up or is popped with @code{get-line}, the
construct will be popped off the top of the buffer stack and loaded into
the editing buffer.

@item push-line (@kbd{^Q} @kbd{ESC-Q} @kbd{ESC-q}) (unbound) (unbound)
@tindex push-line
@kindex CTRL-Q
@kindex ESC-Q
@kindex ESC-q
Push the current buffer onto the buffer stack and clear the buffer.
Next time the editor starts up, the buffer will be popped off the top of
the buffer stack and loaded into the editing buffer.

@item push-line-or-edit
@tindex push-line-or-edit
At the top-level (@code{PS1}) prompt, equivalent to @code{push-line}.
At a secondary (@code{PS2}) prompt, move the entire current multi-line
construct into the editor buffer.  The latter is equivalent to
@code{push-line} followed by @code{get-line}.

@item redisplay (unbound) (@kbd{^R}) (@kbd{^R})
@tindex redisplay
@kindex CTRL-R
Redisplays the edit buffer.

@item send-break (@kbd{^G} @kbd{ESC-^G}) (unbound) (unbound)
@tindex send-break
@kindex CTRL-G
@kindex ESC CTRL-G
Abort the current editor function, e.g.@: @code{execute-named-command}, or
the editor itself, e.g.@: if you are in @code{vared}.  Otherwise abort the
parsing of the current line.

@item run-help (@kbd{ESC-H} @kbd{ESC-h}) (unbound) (unbound)
@tindex run-help
@kindex ESC-H
@kindex ESC-h
Push the buffer onto the buffer stack, and execute the command
@code{run-help @var{cmd}}, where @var{cmd} is the current command.
@code{run-help} is normally aliased to @code{man}.

@item vi-set-buffer (unbound) (@kbd{"}) (unbound)
@tindex vi-set-buffer
@kindex "
Specify a buffer to be used in the following command.
There are 35 buffers that can be  specified: the  26  @dfn{named} buffers 
@code{"a}  to  @code{"z}  and the nine @dfn{queued} buffers "1 to "9.  The 
named buffers can also be specified as @code{"A} to @code{"Z}.  When a buffer
is specified for a cut command, the text being cut replaces the previous 
contents of the specified buffer.  If a named buffer is specified using a 
capital, the newly cut text is appended to the buffer instead of overwriting 
it.  If no buffer is specified for a cut command, @code{"1} is used, and the 
contents of @code{"1} to @code{"8} are each shifted along one buffer; the 
contents of @code{"9} is lost.

@item vi-set-mark (unbound) (@kbd{m}) (unbound)
@tindex vi-set-mark
@kindex m
Set the specified mark at the cursor position.

@item set-mark-command (@kbd{^@@}) (unbound) (unbound)
@tindex set-mark-command
@kindex CTRL-@@
Set the mark at the cursor position.

@item spell-word (@kbd{ESC-$} @kbd{ESC-S} @kbd{ESC-s}) (unbound) (unbound)
@tindex spell-word
@kindex ESC-$
@kindex ESC-S
@kindex ESC-s
Attempt spelling correction on the current word.

@item undefined-key (lots o' keys) (lots o' keys) (unbound)
@tindex undefined-key
Beep.

@item undo (@kbd{^_} @kbd{^Xu} @kbd{^X^U}) (unbound) (unbound)
@tindex undo
@kindex CTRL-_
@kindex CTRL-X CTRL-U
@kindex CTRL-X u
Incrementally undo the last text modification.

@item vi-undo-change (unbound) (@kbd{u}) (unbound)
@tindex vi-undo-change
@kindex u
Undo the last text modification.  If repeated, redo the modification.

@item where-is
@tindex where-is
Read the name of an editor command and and print the listing of key sequences
that invoke the specified command.

@item which-command (@kbd{ESC-?}) (unbound) (unbound)
@tindex which-command
@kindex ESC-?
Push the buffer onto the buffer stack, and execute the command
@code{which-command @var{cmd}}, where @var{cmd} is the current command.
@code{which-command} is normally aliased to @code{whence}.

@item vi-digit-or-beginning-of-line(unbound) (@kbd{0}) (unbound)
@tindex vi-digit-or-beginning-of-line
@kindex 0
If the last command executed was a digit as part of an argument, continue
the argument.  Otherwise, execute @code{vi-beginning-of-line}.
@end table

@node Parameters, Options, Zsh Line Editor, Top
@chapter Parameters
@cindex parameters

@noindent
A parameter has a name, a value, and a number of attributes.  A name may
be any sequence of alphanumeric characters and @code{_}'s, or the single
characters @code{*}, @code{@@}, @code{#}, @code{?}, @code{-}, @code{$},
or @code{!}.  The value may be either a scalar (a string), an
integer, or an array.  To assign a scalar or integer value to a
parameter, use the @code{typeset} builtin.  To assign an array value,
@findex typeset, use of
use @samp{set -A @var{name} @var{value} @dots{}}.  The value of a
@findex set, use of
parameter may also be assigned by writing:

@code{@var{name}=@var{value} @dots{}}

@noindent
If the integer attribute, @samp{-i}, is set for @var{name}, the
@var{value} is subject to arithmetic evaluation.

@menu
* Array Parameters::		
* Positional Parameters::	
* Parameters Set By The Shell::	 
* Parameters Used By The Shell::  
@end menu

@node Array Parameters, Positional Parameters,  , Parameters
@section Array Parameters

@noindent
The value of an array parameter may be assigned by writing:

@var{name}=(@var{value} @dots{}) @dots{}

@noindent
Individual elements of an array may be selected using a subscript.  A
@cindex array elements
subscript of the form @code{[@var{exp}]} selects the single element
@var{exp}, where @var{exp} is an arithmetic expression which will be subject
to arithmetic expansion as if it were surrounded by @code{$((@dots{}))}.  The 
elements are numbered beginning with 1 unless the @code{KSH_ARRAYS} option
is set when they are numbered from zero.
@cindex subscripts
@pindex KSH_ARRAYS, use of

@noindent
A subscript of the form @code{[*]} or @code{[@@]} evaluates to all elements of
an array; there is no difference between the two except when they appear 
within double quotes.  @code{"$foo[*]"} evaluates to @code{"$foo[1] $foo[2] 
@dots{}"}, while @code{"$foo[@@]"} evaluates to @code{"$foo[1]"} 
@code{"$foo[2]"}, etc.  

@noindent
A subscript of the form @code{[@var{exp1},@var{exp2}]}
selects all elements in the range @var{exp1} to @var{exp2}, inclusive.  If 
one of the subscripts evaluates to a negative number, say @code{-@var{n}}, then
the @var{n}'th element from the end of the array is used.  Thus
@code{$foo[-3]} is the third element from the end of the array
@code{foo}, and @code{$foo[1,-1]} is the same as @code{$foo[*]}.

@noindent
Subscripting may also be performed on non-array values, in which case
@cindex substrings
the subscripts specify a substring to be extracted.  For example, if
@code{FOO} is set to @code{foobar}, then @code{echo $@var{FOO}[2,5]} prints
@code{ooba}.

@noindent
Subscripts may be used inside braces used to delimit a parameter name, thus 
@code{$@{foo[2]@}} is equivalent to @code{$foo[2]}.  If the @code{KSH_ARRAYS} 
option is set, the braced form is the only one that will work, the subscript 
otherwise not being treated specially.

@noindent
If a subscript is used on the left side of an assignment the selected
range is replaced by the expression on the right side.

@noindent
If the opening bracket or the comma is directly followed by an opening
parenthesis the string up to the matching closing parenthesis is
considered to be a list of flags.  The flags currently understood are:

@table @code
@item e
This option has no effect and retained for backward compatibility only.

@item w
If the parameter subscripted is a scalar, then this flag makes
subscription work on a per-word basis instead of characters.

@item s:@var{string}:
Defines the @var{string} that separates words (for use with the @code{w}
flag).

@item p
Recognize the same escape sequences as the @code{print} builtin in the 
string argument of a subsequent @code{s} flag.

@item f
If the parameter subscripted is a scalar than this flag makes subscription 
work on a per-line basis instead of characters.   This is a shorthand for 
@code{pws:\n:}.

@item r
If this flag is given the exp is taken as a pattern and the result is the 
first matching array element, substring or word (if the parameter is an array,
if it is a scalar, or if it is a scalar and the @code{w} flag is given,
respectively); note that this is like giving a number: @code{$foo[(r)??,3]} 
and @code{$foo[(r)??,(r)f*]} work.

@item R
Like @code{r}, but gives the last match.

@item i
Like @code{r}, but gives the index of the match instead; this may not be
combined with a second argument.

@item I
Like @code{i}, but gives the index of the last match.

@item n:@var{expr}:
If combined with @code{r}, @code{R}, @code{i}, or @code{I}, makes them
return the @var{n}'th or @var{n}'th last match (if @var{expr}
evaluates to @var{n}).
@end table

@node Positional Parameters, Parameters Set By The Shell, Array Parameters, Parameters
@section Positional Parameters

@noindent
Positional parameters are set by the shell on invocation, by the
@code{set} builtin, or by direct assignment.  The parameter @var{n},
where @var{n} is a number, is the @var{n}'th positional parameter.  The
parameters @code{*}, @code{@@}, and @code{argv} are arrays containing
all the positional parameters; thus @code{argv[@var{n}]}, is equivalent
to simply @var{n}.

@node Parameters Set By The Shell, Parameters Used By The Shell, Positional Parameters, Parameters
@section Parameters Set By The Shell

@noindent
The following parameters are automatically set by the shell:

@table @code
@item !
@vindex !
The process id of the last background command invoked.

@item #
@vindex #
The number of positional parameters in decimal.

@item ARGC
@vindex ARGC
Same as @code{#}.  It has no special meaning in sh/ksh compatibility mode.

@item $
@vindex $
The process id of this shell.

@item -
@vindex -
Flags supplied to the shell on invocation or by the @code{set} or
@code{setopt} commands.

@item *
@vindex *
An array containing the positional parameters.

@item argv
@vindex argv
Same as @code{*}.  It has no special meaning in sh/ksh compatibility mode.

@item @@
@vindex @@
Same as @code{argv[@@]} but it can be used in sh/ksh compatibility mode.

@item ?
@vindex ?
The exit value returned by the last command.

@item status
@vindex status
Same as @code{?}.  It has no special meaning in sh/ksh compatibility mode.

@item _
@vindex _
The last argument of the previous command.  Also, this parameter is set
in the environment of every command executed to the full pathname of the
command.

@item EGID
@vindex EGID
The effective group id of the shell process.  If you have sufficient
privileges, you may change the effective group id of the shell process by
assigning to this parameter.  Also (assuming sufficient privileges), you
may start a single command with a different effective group id by:
@code{(EGID=egid ; command)}

@item EUID
@vindex EUID
The effective user id of the shell process.  If you have sufficient
privileges, you may change the effective user id of the shell process by
assigning to this parameter.  Also (assuming sufficient privileges), you
may start a single command with a different effective user id by:
@code{(EUID=euid ; command)}

@item ERRNO
@vindex ERRNO
The value of @code{errno} as set by the most recently failed system
call.  This value is system dependent and is intended for debugging
purposes.

@item GID
@vindex GID
The group id of the shell process.  If you have sufficient privileges, you 
may change the group id of the shell process by assigning to this 
parameter.  Also (assuming sufficient privileges), you may start a single
command under a different group id by:
@code{(GID=gid ; command)}

@item HOST
@vindex HOST
The current hostname.

@item LINENO
@vindex LINENO
The line number of the current line within the current script being
executed.

@item LOGNAME
@vindex LOGNAME
If the corresponding variable is not set in the environment of the shell, it 
is initialized to the login name corresponding to the current login 
session.  This parameter is exported by default but this can be disabled
using the @code{typeset} builtin.

@item MACHTYPE
@vindex MACHTYPE
The machine type (microprocessor class or machine model), as determined at 
compile time.

@item OLDPWD
@vindex OLDPWD
The previous working directory.

@item OPTARG
@vindex OPTARG
The value of the last option argument processed by the @code{getopts}
command.

@item OPTIND
@vindex OPTIND
The index of the last option argument processed by the @code{getopts}
command.

@item OSTYPE
@vindex OSTYPE
The operating system, as determined at compile time.

@item PPID
@vindex PPID
The process id of the parent of the shell.

@item PWD
@vindex PWD
The present working directory.

@item RANDOM
@vindex RANDOM
A random integer from 0 to 32767, newly generated each time this
parameter is referenced.  The random number generator can be seeded by
assigning a numeric value to @code{RANDOM}.

@item SECONDS
@vindex SECONDS
The number of seconds since shell invocation.  If this parameter is
assigned a value, then the value returned upon reference will be the
value that was assigned plus the number of seconds since the assignment.

@item SHLVL
@vindex SHLVL
Incremented by one each time a new shell is started.

@item signals
@vindex signals
An array containing the names of the signals.

@item TTY
@vindex TTY
The name of the tty associated with the shell, if any.

@item TTYIDLE
@vindex TTYIDLE
The idle time of the tty associated with the shell in seconds or -1 if there 
is no such tty.

@item UID
@vindex UID
The user id of the shell process.  If you have sufficient privileges, you 
may change the user id of the shell by assigning to this parameter.  Also  
(assuming sufficient privileges), you may start a single command under a 
different user id by: @code{(UID=uid ; command)}

@item USERNAME
@vindex USERNAME
The username corresponding to the user id of the shell process.  If you have
sufficient privileges, you may change the username (and also the user id and 
group id) of the shell by assigning to this parameter.  Also (assuming 
sufficient privileges), you may start a single command under a different
username (and user id and group id) by: @code{(USERNAME=username ; command)}

@item VENDOR
@vindex VENDOR
The vendor, as determined at compile time.

@item ZSHNAME
@itemx ZSH_NAME
@vindex ZSHNAME
@vindex ZSH_NAME
Expands to the basename of the command used to invoke this instance of zsh.

@item ZSH_VERSION
@vindex ZSH_VERSION
The version number of this zsh.
@end table

@node Parameters Used By The Shell,  , Parameters Set By The Shell, Parameters
@section Parameters Used By The Shell

@noindent
The following parameters are used by the shell:

@table @code
@item ARGV0
@vindex ARGV0
If exported, its value is used as argv[0] of external commands.  Usually
used in constructs like @samp{ARGV0=emacs nethack}.

@item BAUD
@vindex BAUD
The baud rate of the current connection.  Used by the line editor update
mechanism to compensate for a slow terminal by delaying updates until
necessary.  This may be profitably set to a lower value in some
circumstances, e.g.@: for slow modems dialing into a communications server
which is connected to a host via a fast link; in this case, this
variable would be set by default to the speed of the fast link, and not
the modem.  This parameter should be set to the baud rate of the slowest
part of the link for best performance.  The compensation mechanism can
be turned off by setting the variable to zero.

@item cdpath (CDPATH)
@vindex cdpath
@vindex CDPATH
An array (colon-separated list) of directories specifying the search
path for the @code{cd} command.

@item COLUMNS
@vindex COLUMNS
The number of columns for this terminal session.  Used for printing
select lists and for the line editor.

@item DIRSTACKSIZE
@vindex DIRSTACKSIZE
@pindex AUTO_PUSHD, use of
The maximum size of the directory stack.  If the stack gets larger than
this, it will be truncated automatically.  This is useful with the
@code{AUTO_PUSHD} option.

@item FCEDIT
@vindex FCEDIT
The default editor for the @code{fc} builtin.

@item fignore (FIGNORE)
@vindex fignore
@vindex FIGNORE
An array (colon-separated list) containing the suffixes of files to be
ignored during filename completion.  However, if the completion generates
only files which would match if this variable would be ignored, than these
files are completed anyway.

@item fpath (FPATH)
@vindex fpath
@vindex FPATH
An array (colon-separated list) of directories specifying the search
path for function definitions.  This path is searched when a function
with the @samp{-u} attribute is referenced.  If an executable file is
found, then it is read and executed in the current environment.

@item histchars
@vindex histchars
Three characters used by the shell's history and lexical analysis
mechanism.  The first character signals the start of a history
substitution (default @code{!}).  The second character signals the start
of a quick history substitution (default @code{^}).  The third character
is the comment character (default @code{#}).

@item HISTCHARS
@vindex HISTCHARS
Depreciated. Use @code{histchars}.

@item HISTFILE
@vindex HISTFILE
The file to save the history in when an interactive shell exits.  If
unset, the history is not saved.

@item HISTSIZE
@vindex HISTSIZE
The maximum size of the history list.

@item HOME
@vindex HOME
The default argument for the @code{cd} command.

@item IFS
@vindex IFS
Internal field separators, normally space, tab, and newline, that are used to
separate words which result from command or parameter substitution and words
read by the @code{read} builtin.  Any characters from the set space, tab and 
newline that appear in the @code{IFS} are called @dfn{IFS white space}.  One 
or more IFS white space characters or one non-IFS white space character 
together with any adjacent IFS white space character delimit a field.  If an 
IFS white space character appears twice consecutively in the @code{IFS}, this 
character is treated as if it were not an IFS white space character.

@item KEYTIMEOUT
@vindex KEYTIMEOUT
The time the shell waits, in hundredths of seconds, for another key to
be pressed when reading bound multi-character sequences.

@item LANG
@vindex LANG
This variable determines the locale category for any category not
specifically selected via a variable starting with @code{LC_}.

@item LC_ALL
@vindex LC_ALL
This variable overrides the value of the @code{LANG} variable and the
value of any of the other variables starting with @code{LC_}.

@item LC_COLLATE
@vindex LC_COLLATE
This variable determines the locale category for character collation
information within ranges in glob brackets and for sorting.

@item LC_CTYPE
@vindex LC_CTYPE
This variable determines the locale category for character handling
functions.

@item LC_MESSAGES
@vindex LC_MESSAGES
This variable determines the language in which messages should be
written.  Note that zsh does not use message catalogs.

@item LC_TIME
@vindex LC_TIME
This variable determines the locale category for date and time
formatting in promt escape sequences.

@item LINES
@vindex LINES
The number of lines for this terminal session.  Used for printing select
lists and for the line editor.

@item LISTMAX
@vindex LISTMAX
In the line editor, the number of filenames to list without asking
first.  If set to zero, the shell asks only if the listing would scroll
off the screen.

@item LOGCHECK
@vindex LOGCHECK
The interval in seconds between checks for login/logout activity using
the @code{watch} parameter.

@item MAIL
@vindex MAIL
If this parameter is set and @code{mailpath} is not set, the shell looks
for mail in the specified file.

@item MAILCHECK
@vindex MAILCHECK
The interval in seconds between checks for new mail.

@item mailpath (MAILPATH)
@vindex mailpath
@vindex MAILPATH
An array (colon-separated list) of filenames to check for new mail.  Each 
filename can be followed by a @code{?} and a message that will be 
printed.  The message will undergo parameter expansion, command substitution 
and arithmetic substitution with the variable @code{$_} defined as the name 
of the file that has changed.  The default message is @samp{You have
new mail}.  If an element is a directory instead of a file the shell will 
recursively check every file in every subdirectory of the element.


@item manpath (MANPATH)
@vindex manpath
@vindex MANPATH
An array (colon-separated list) whose value is not used by the shell.
The @code{manpath} array can be useful, however, since setting it also
sets @code{MANPATH}, and vice versa.

@item NULLCMD
@vindex NULLCMD
@cindex null command, setting
@cindex csh, null command style
@cindex ksh, null command style
The command name to assume if a redirection is specified with no
command.  Defaults to @code{cat}.  For sh/ksh-like behaviour, change this
to @code{:}.  For csh-like behaviour, unset this parameter; the shell will
print an error message if null commands are entered.

@item path (PATH)
@vindex path
@vindex PATH
An array (colon-separated list) of directories to search for commands.
When this parameter is set, each directory is scanned and all files
found are put in a hash table.

@item POSTEDIT
@vindex POSTEDIT
This string is output whenever the line editor exits.  It usually
contains termcap strings to reset the terminal.

@item PS1
@vindex PS1
The primary prompt string, printed before a command is read; the default
is @samp{%m%# }.  If the escape sequence takes an optional integer, it
should appear between the @code{%} and the next character of the
sequence.  The following escape sequences are recognized:

@table @code
@item %%
A @code{%}.

@item %)
A @code{)}.

@item %d
@itemx %/
Present working directory (@code{$PWD}).

@item %~
@code{$PWD}.  If it has a named directory as its prefix, that part is
replaced by a @code{~} followed by the name of the directory.  If it
starts with @code{$HOME}, that part is replaced by a @code{~}.

@item %c
@itemx %.
@itemx %C
Trailing component of @code{$PWD}.  An integer may follow the @code{%}
to get more than one component.  Unless @code{%C} is used, tilde
expansion is performed first.

@item !
@itemx %h
@itemx %!
Current history event number.

@item %M
The full machine hostname.

@item %m
The hostname up to the first @samp{.}.  An integer may follow the @code{%} to
specify how many components of the hostname are desired.

@item %S (%s)
Start (stop) standout mode.

@item %U (%u)
Start (stop) underline mode.

@item %B (%b)
Start (stop) boldface mode.

@item %t
@itemx %@@
Current time of day, in 12-hour, am/pm format.

@item %T
Current time of day, in 24-hour format.

@item %*
Current time of day in 24-hour format, with seconds.

@item %n
@code{$USERNAME}.

@item %w
The date in day-dd format.

@item %W
The date in mm/dd/yy format.

@item %D
The date in yy-mm-dd format.

@item %D@{@var{string}@}
@var{string} is formatted using the @code{strftime} function.  See
@code{strftime(3)} for more details, if your system has it.

@item %l
The line (tty) the user is logged in on.

@item %?
The return code of the last command executed just before the
prompt. 

@item %_
The status of the parser, i.e. the shell constructs (like @code{if} and
@code{for}) that have been started on the command line.  If given an
integer number, that many strings will be printed; zero or no integer
means print as many as there are.

@item %E
Clears to end of line.

@item %#
A @code{#} if the shell is running as root, a @code{%} if not.
Equivalent to @code{%(#.#.%%)}

@item %v
The value of the first element of the @code{psvar} array parameter.
Following the @code{%} with an integer gives that element of the
array.

@item %@{@dots{}%@}
Include a string as a literal escape sequence.  The string within the
braces should not change the cursor position.

@item %(x.@var{true-text}.@var{false-text})
Specifies a ternary expression.  The character following the @code{x} is
arbitrary; the same character is used to separate the text for the true
result from that for the false result.  The separator may not appear in the
@code{true-text}, except as part of a @code{%} sequence.  A @code{)} may
appear in the @code{false-text} as a @code{%)}.  @code{true-text} and
@code{false-text} may both contain contain arbitrarily-nested escape
sequences, including further ternary expressions.  The left parenthesis
may be preceded or followed by a positive integer @code{n}, which defaults
to zero.  The test character @code{x} may be any of the following:

@table @code
@item c
@itemx .
@itemx ~
True if the current path, with prefix replacement, has at least @var{n}
elements.
@item /
@itemx C
True if the current absolute path has at least @var{n} elements.
@item t
True if the time in minutes is equal to @var{n}.
@item T
True if the time in hours is equal to @var{n}.
@item d
True if the day of the month is equal to @var{n}.
@item D
True if the month is equal to @var{n} (January = 0).
@item w
True if the day of the week is equal to @var{n} (Sunday = 0).
@item ?
True if the exit status of the last command was @var{n}.
@item # 
True if the effective uid of the current process is @var{n}.
@item g
True if the effective gid of the current process is @var{n}.
@item L
True if the @code{SHLVL} parameter is at least @var{n}.
@item S
True if the @code{SECONDS} parameter is at least @var{n}.
@item v
True if the array @code{psvar} has at least @var{n} elements.
@item _
True if at least @var{n} shell constructs were started.
@item %<@var{string}<
@itemx %>@var{string}>
@itemx %[@var{x}@var{string}]
Specifies truncation behaviour.  The third form is equivalent to 
@code{%@var{x}@var{string}@var{x}}, i.e@. @code{@var{x}} may be @code{<}
or @code{>}.  The numeric argument, which in the third form may appear 
immediately after the @code{[}, specifies the maximum permitted length of 
the various strings that can be displayed in the prompt.  If this integer is
zero, or missing, truncation is disabled.  Truncation is initially 
disabled.  The forms with @code{<} truncate at the left of the string, and the
forms with @code{>} truncate at the right of the string.  For example, if the
current directory is @file{/home/pike}, the prompt @code{%8<..<%/} will expand
to @file{..e/pike}.  The @code{string} will be displayed in place of the 
truncated portion of any string.  In this string, the terminating character
(@code{<}, @code{>} or @code{]}), or in fact any character, may be quoted by
a preceding @code{\}.  @code{%} sequences are not treated specially.  If the 
@code{string} is longer than the specified truncation length, it will appear
in full, completely replacing the truncated string.
@end table
@end table

@item PS2
@vindex PS2
The secondary prompt, printed when the shell needs more information to
complete a command.  Recognizes the same escape sequences as
@code{$PS1}.  The default is @samp{%_> }.

@item PS3
@vindex PS3
Selection prompt used within a @code{select} loop.  Recognizes the same
escape sequences as @code{PS1}.  The default is @samp{?# }.

@item PS4
@vindex PS4
The execution trace prompt.  Default is @samp{+ }.

@item PROMPT
@itemx PROMPT2
@itemx PROMPT3
@itemx PROMPT4
@vindex PROMPT
@vindex PROMPT2
@vindex PROMPT3
@vindex PROMPT4
Same as @code{PS1}, @code{PS2}, @code{PS3}, and @code{PS4},
respectively.  These parameters do not have any special meaning in sh/ksh
compatibility mode.

@item psvar (PSVAR)
@vindex psvar
@vindex PSVAR
An array (colon-separated list) whose first nine values can be used in
@code{PROMPT} strings.  Setting @code{psvar} also sets @code{PSVAR}, and
vice versa.

@item prompt
@vindex prompt
Same as @code{PS1}.  It has no special meaning in sh/ksh compatibility
mode.

@item READNULLCMD
@vindex READNULLCMD
The command name to assume if a single input redirection is specified
with no command.  Defaults to @code{more}.

@item REPORTTIME
@vindex REPORTTIME
If nonzero, commands whose combined user and system execution times
(measured in seconds) are greater than this value have timing statistics
printed for them.

@item RPROMPT
@itemx RPS1
@vindex RPROMPT
@vindex RPS1
This prompt is displayed on the right-hand side of the screen when the
primary prompt is being displayed on the left.  This does not work if
the @code{SINGLELINEZLE} option is set.  Recognizes the same escape
sequences as @code{PROMPT}.

@item SAVEHIST
@vindex SAVEHIST
The maximum number of history events to save in the history file.

@item SPROMPT
@vindex SPROMPT
The prompt used for spelling correction.  The sequence @code{%R} expands
to the string which presumably needs spelling correction, and @code{%r}
expands to the proposed correction.  All other @code{PROMPT} escapes are
also allowed.

@item STTY
@vindex STTY
If this parameter is set in a command's environment, the shell runs the
@code{stty} command with the value of this parameter as arguments in
order to set up the terminal before executing the command.  The modes
apply only to the command, and are reset when it finishes or is
suspended.  If the command is suspended and continued later with the
@code{fg} or @code{wait} builtins it will see the modes specified by
@code{STTY}, as if it were not suspended.  This (intentionally) does not 
apply if the command is continued via @code{kill -CONT}.  @code{STTY} is
ignored if the command is run in the background, or if it is in the
environment of the shell but not explicitly assigned to in the input
line.  This avoids running @code{stty} at every external command by
accidentally exporting it.  Also note that @code{STTY} should not be
used for window size specifications; these will not be local to the
command.
  
@item TIMEFMT
@vindex TIMEFMT
The format of process time reports with the @code{time} keyword.  The
default is @samp{%E real  %U user  %S system  %P %J}.  Recognizes the
following escape sequences:

@table @code
@item %
A @code{%}.

@item %U
CPU seconds spent in user mode.

@item %S
CPU seconds spent in kernel mode.

@item %E
Elapsed time in seconds.

@item %P
The CPU percentage, computed as (%U+%S)/%E.

@item %J
The name of this job.
@end table

A star may be inserted between the percent sign and flags printing time.  This
cause the time to be printed in @code{hh:mm:ss.ttt} format (hours and minutes
are only printed if they are not zero).

@item TMOUT
@vindex TMOUT
If this parameter is nonzero, the shell will receive an @code{ALRM} signal
if a command is not entered within the specified number of seconds after
issuing a prompt.  If there is a trap on @code{SIGALRM}, it will be executed
and a new alarm is scheduled using the value of the @code{TMOUT} parameter
after executing the trap.  If no trap is set, and the idle time of the 
terminal is not less than the value of the @code{TMOUT} parameter, zsh 
terminates.  Otherwise a new alarm is scheduled to @code{TMOUT} seconds after
the last keypress.

@item TMPPREFIX
@vindex TMPPREFIX
A pathname prefix which the shell will use for all temporary files.
Note that this should include an initial part for the file name as well
as any directory names.  The default is @file{/tmp/zsh}.

@item watch (WATCH)
@vindex watch
@vindex WATCH
An array (colon-separated list) of login/logout events to report.  If it
contains the single word @samp{all}, then all login/logout events are
reported.  If it contains the single word @samp{notme}, then all
login/logout events are reported except for those originating from
@code{$USERNAME}.  An entry in this list may consist of a username, an
@code{@@} followed by a remote hostname, and a @code{%} followed by a
line (tty).  Any or all of these components may be present in an entry;
if a login/logout event matches all of them, it is reported.

@item WATCHFMT
@vindex WATCHFMT
The format of login/logout reports if the @code{watch} parameter is set.
Default is @samp{%n has %a %l from %m}.  Recognizes the following escape
sequences:

@table @code
@item %n
The name of the user that logged in/out.

@item %a
The observed action, i.e. @samp{logged on} or @samp{logged off}.

@item %l
The line (tty) the user is logged in on.

@item %M
The full hostname of the remote host.

@item %m
The hostname up to the first @samp{.}.  If only the IP address is
available or the utmp field contains the name of an X-windows display,
the whole name is printed.

@noindent
NOTE: The @code{%m} and @code{%M} escapes will work only if there is a
host name field in the @code{utmp} on your machine.  Otherwise they are
treated as ordinary strings.

@item %S (%s)
Start (stop) standout mode.

@item %U (%u)
Start (stop) underline mode.

@item %B (%b)
Start (stop) boldface mode.

@item %t
@itemx %@@
The time, in 12-hour, am/pm format.

@item %T
The time, in 24-hour format.

@item %w
The date in day-dd format.

@item %W
The date in mm/dd/yy format.

@item %D
The date in yy-mm-dd format.

@item %(x:@var{true-text}:@var{false-text})
Specifies a ternary expression.  The character following the @code{x} 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.

@noindent
The test character @code{x} may be any one of @code{l}, @code{n},
@code{m}, or @code{M}, which indicate a true result if the corresponding
escape sequence would return a non-empty value; or it may be @code{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.

@noindent
If the result is true, then the @var{true-text} is formatted according
to the result above and printed, and the @var{false-text} is skipped.
If false, the @var{true-text} is skipped, and the @var{false-text} is
formatted and printed.  Either or both of the branches may be empty, but
both separators must always be present.
@end table

@item WORDCHARS
@vindex WORDCHARS
A list of non-alphanumeric characters considered part of a word by the
line editor.

@item ZDOTDIR
@vindex ZDOTDIR
The directory to search for shell startup files (@file{.zshrc}, etc), if
not @code{$HOME}.
@end table


@node Options, Shell Builtin Commands, Parameters, Top
@chapter Options
@cindex options

@menu
* Specifying Options::
* Description of Options::
* Single Letter Options::
@end menu


@node Specifying Options, Description of Options, , Options
@section Specifying Options
@cindex options, specifying

@noindent
Options are primarily referred to by name.  These names are case insensitive 
and underscores are ignored.  For example, @code{allexport} is equivalent to 
@code{A__lleXP_ort}.

@noindent
The sense of an option name may be inverted by preceding it with @code{no}, 
so @code{setopt No_Beep} is equivalent to @code{unsetopt beep}.  This
inversion can only be done once, so @code{nonobeep} is @emph{not} a synonym
for @code{beep}.  Similarly, @code{tify} is @emph{not} a synonym for 
@code{nonotify} (the inversion of @code{notify}).

@noindent
Some options also have one or more single letter names.  There are two sets 
of single letter options: one used by default, and another when the shell is 
emulating @code{sh} or @code{ksh}.  The single letter options can be used on 
the shell command line, or with the @code{set}, @code{setopt} and 
@code{unsetopt} builtins, as normal Unix options preceded by @code{-}.

@noindent
The  sense of the single letter options may be inverted by using @code{+} 
instead of @code{-}.  Some of the single letter option names refer to an 
option being off, in which case the inversion of that name refers to the 
option being on.  For example, @code{+n} is the short name of @code{exec}, 
and @code{-n} is the short name of its inversion, @code{noexec}.


@node Description of Options, Single Letter Options, Specifying Options, Options
@section Description of Options
@cindex options, description

@table @code
@item ALL_EXPORT (-a, ksh: -a)
@cindex export, automatic
@pindex ALL_EXPORT
All parameters subsequently defined are automatically exported.

@item ALWAYS_LAST_PROMPT
@cindex history, appending to file
@pindex ALWAYS_LAST_PROMPT
If unset, key functions that list completions try to return to the last
prompt if given a numeric argument.  If set, these functions try to
return to the last prompt if given no numeric argument.

@item ALWAYS_TO_END
@pindex ALWAYS_TO_END
If a completion with the cursor in the word was started and it results
in only one match, the cursor is placed at the end of the word.

@item APPEND_HISTORY
@pindex APPEND_HISTORY
If this is set, zsh sessions will append their history list to the
history file, rather than overwrite it.  Thus, multiple parallel zsh
sessions will all have their history lists added to the history file, in
the order they are killed.  @xref{Shell Builtin Commands}, for the
@code{fc} command.

@item AUTO_CD (-J)
@cindex cd, automatic
@pindex AUTO_CD
If a command is not in the hash table, and there exists an executable
directory by that name, perform the @code{cd} command to that directory.

@item AUTO_LIST (-9)
@cindex completion, listing choices
@pindex AUTO_LIST
Automatically list choices on an ambiguous completion.

@item AUTO_MENU
@cindex completion, menu, on TAB
@pindex AUTO_MENU
Automatically use menu completion after the second consecutive request
for completion, for example by pressing the @key{TAB} key repeatedly.
This option is overridden by @code{MENU_COMPLETE}.

@item AUTO_NAME_DIRS
@cindex directories, named
@pindex AUTO_NAME_DIRS
Any parameter that is set to the absolute name of a directory
immediately becomes a name for that directory in the usual form
@code{~param}.  If this option is not set, the parameter must be used in
that form for it to become a name (a command-line completion is
sufficient for this).

@item AUTO_PARAM_KEYS
@pindex AUTO_PARAM_KEYS
If a parameter name was completed and the next character typed is one of
those that have to come directly after the name (like @code{@}},
@code{:}, etc.), they are placed there automatically.

@item AUTO_PARAM_SLASH
@pindex AUTO_PARAM_SLASH
If a parameter is completed whose content is the name of a directory, then 
add a trailing slash.

@item AUTO_PUSHD (-N)
@cindex cd, behaving like pushd
@cindex pushd, making cd behave like
@pindex AUTO_PUSHD
Make @code{cd} push the old directory onto the directory stack.

@item AUTO_REMOVE_SLASH
@cindex slash, removing trailing
@pindex AUTO_REMOVE_SLASH
When the last character resulting from a completion is a slash and the next
character typed is a word delimiter, remove the slash.

@item AUTO_RESUME (-W)
@cindex jobs, resuming automatically
@cindex resuming jobs automatically
@pindex AUTO_RESUME
Treat single word simple commands without redirection as candidates for
resumption of an existing job.

@item BAD_PATTERN (+2)
@cindex globbing, malformed pattern
@cindex filename generation, bad pattern
@pindex BAD_PATTERN
If a pattern for filename generation is badly formed, print an error. 
If this option is unset, the pattern will be left unchanged.

@item BANG_HIST (+K)
@cindex history, enable substitution
@cindex enable history substitution
@pindex BANG_HIST
Perform textual history substitution, treating the character @code{!} 
specially.

@item BEEP (+B)
@cindex beep, enable
@cindex enable the beep
@pindex BEEP
Beep.

@item BG_NICE (-6)
@cindex jobs, background priority
@cindex background jobs, priority of
@pindex BG_NICE
Run all background jobs at a lower priority.  This option is set by
default.

@item BRACE_CCL
@cindex brace expansion, extending
@cindex expansion, brace, extended
@pindex BRACE_CCL
Expand expressions in braces which would not otherwise undergo brace 
expansion to a lexically ordered list of all the characters.
@xref{Brace Expansion}.

@item BSD_ECHO
@cindex echo, BSD compatible
@pindex BSD_ECHO
Make the echo builtin compatible with the BSD @code{echo(1)} command.  This 
disables backslashed escape sequences in echo strings unless the @samp{-e} 
option is specified.

@item CDABLE_VARS (-T)
@cindex cd, to parameter
@pindex CDABLE_VARS
If the argument to a @code{cd} command (or an implied @code{cd} with the
@code{AUTO_CD} option set) is not a directory, and does not begin with a
slash, try to expand the expression as if it were preceded by a
@code{~} (@pxref{Filename Expansion}). 

@item CHASE_LINKS (-w)
@cindex links, symbolic
@cindex symbolic links
@pindex CHASE_LINKS
Resolve symbolic links to their true values.

@item CLOBBER (+C, ksh: +C)
@cindex file clobbering, allowing
@cindex clobbering, of files
@pindex CLOBBER
Allows @code{>} redirection to truncate existing files, and @code{>>} to 
create files.  Otherwise @code{>!} must be used to truncate a file, and 
@code{>>!} to create a file.

@item COMPLETE_ALIASES
@cindex aliases, completion of
@pindex COMPLETE_ALIASES
If set, aliases on the command line are not internally substituted
before completion is attempted.

@item COMPLETE_IN_WORD
@pindex COMPLETE_IN_WORD
If unset, the cursor is moved to the end of the word if completion is
started.  Otherwise it stays where it is and completion is done from
both ends.

@item CORRECT (-0)
@cindex correction, spelling
@cindex spelling correction
@pindex CORRECT
Try to correct the spelling of commands.

@item CORRECT_ALL (-O)
@pindex CORRECT_ALL
Try to correct the spelling of all arguments in a line.

@item CSH_JUNKIE_HISTORY
@cindex csh, history style
@pindex CSH_JUNKIE_HISTORY
A history reference without an event specifier will always refer to the
previous command.

@item CSH_JUNKIE_LOOPS
@cindex csh, loop style
@cindex loop style, csh
@pindex CSH_JUNKIE_LOOPS
Allow loop bodies to take the form @samp{@var{list}; end} instead of
@samp{do @var{list}; done}.

@item CSH_JUNKIE_QUOTES
@cindex csh, quoting style
@cindex quoting style, csh
@pindex CSH_JUNKIE_QUOTES
Complain if a quoted expression runs off the end of a line; prevent
quoted expressions from containing un-escaped newlines.

@item CSH_NULL_GLOB
@cindex csh, null globbing style
@cindex null globbing, csh style
@cindex globbing, null, csh style
@pindex CSH_NULL_GLOB
If a pattern for filename generation has no matches, delete the pattern
from the argument list; do not report an error unless all the patterns
in a command have no matches.  Overrides @code{NULL_GLOB}.

@item EQUALS 
@cindex filename substitution, =
@pindex EQUALS
Perform @code{=} filename substitution.

@item ERR_EXIT (-e, ksh: -e)
@cindex exit status, trapping
@pindex ERR_EXIT
If a command has a non-zero exit status, execute the @code{ZERR} trap, 
if set, and exit.  This is disabled while running initialization 
scripts.

@item EXEC (+n, ksh: +n)
@cindex command execution, enabling
@pindex EXEC
Do execute commands.  Without this option, commands are read and checked for 
syntax errors, but not executed.

@item EXTENDED_GLOB
@cindex globbing, extended
@pindex EXTENDED_GLOB
Treat the @code{#}, @code{~} and @code{^} characters as part of patterns 
for filename generation, etc.  (An initial unquoted @code{~} always 
produces named directory expansion (@pxref{Filename Expansion}).)

@item EXTENDED_HISTORY
@cindex history, timestamping
@pindex EXTENDED_HISTORY
Save beginning and ending timestamps to the history file.  The format of
these timestamps is @code{:@var{<beginning time>}:@var{<ending
time>}:@var{<command>}}.

@item FLOW_CONTROL
@cindex flow control
@pindex FLOW_CONTROL
If this option is unset, output flow control via start/stop characters 
(usually assigned to @kbd{^S}/@kbd{^Q}) is disabled in the shell's editor.

@item FUNCTION_ARGZERO
@cindex $0, setting
@pindex FUNCTION_ARGZERO
When executing a shell function or sourcing a script, set @code{$0} 
temporarily to the name of the function/script.

@item GLOB (+F, ksh: +f)
@cindex globbing, enabling
@cindex enabling globbing
@pindex GLOB
Perform filename generation.

@item GLOB_ASSIGN
@pindex GLOB_ASSIGN
If this option is set, filename generation (globbing) is
performed on the right hand side of scalar parameter assignments of
the form @code{@var{name}=@var{pattern}} (e.g. `@code{param=*}').  If
the result has more than one word the parameter will become an array
with those words as arguments. This option is provided for backwards
compatibility only: globbing is always performed on the right hand side
of array assignments of the form `@code{@var{name}=( @var{value} )}'
(e.g. `@code{param=(*)}') and this form is recommended for clarity;
with this option set, it is not possible to predict whether the result
will be an array or a scalar.

@item GLOB_COMPLETE
@pindex GLOB_COMPLETE
When the current word has a glob pattern, do not insert all the words
resulting from the expansion but generate matches as for completion and
cycle through them like @code{MENU_COMPLETE}. The matches are generated
as if a `@code{*}' was added to the end of the word, or inserted at the
cursor when @code{COMPLETE_IN_WORD} is set.  This actually uses pattern
matching, not globbing, so it works not only for files but for any
completion, such as options, user names, etc.

@item GLOB_DOTS (-4)
@cindex globbing, of . files
@pindex GLOB_DOTS
Do not require a leading @code{.} in a filename to be matched
explicitly.

@item GLOB_SUBST
@pindex GLOB_SUBST
Treat any characters resulting from parameter substitution as being
eligible for file expansion and filename generation, and any characters
resulting from command substitution as being eligible for filename
generation.

@item HASH_CMDS
@cindex hashing, of commands
@cindex command hashing
@pindex HASH_CMDS
Place the location of each command in the hash table the first time it
is executed.  If this option is unset, no path hashing will be done at
all.

@item HASH_DIRS
@cindex hashing, of directories
@cindex directories, hashing
@pindex HASH_DIRS
Whenever a command is executed, hash the directory containing it, as
well as all directories that occur earlier in the path.  Has no effect
if @code{HASH_CMDS} is unset.

@item HASH_LIST_ALL
@pindex HASH_LIST_ALL
Whenever a command completion is attempted, make sure the entire command
path is hashed first.  This makes the first completion slower.

@item HIST_ALLOW_CLOBBER
@pindex HIST_ALLOW_CLOBBER
Add @code{|} to output redirections in the history.  This allows history 
references to clobber files even when @code{CLOBBER} is unset.

@item HIST_BEEP
@cindex beep, history
@cindex history beeping
@pindex HIST_BEEP
Beep when an attempt is made to access a history entry which isn't there.

@item HIST_IGNORE_DUPS (-h)
@cindex history, ignoring duplicates
@pindex HIST_IGNORE_DUPS
Do not enter command lines into the history list if they are duplicates
of the previous event.

@item HIST_IGNORE_SPACE (-g)
@cindex history, ignoring spaces
@pindex HIST_IGNORE_SPACE
Do not enter command lines into the history list if they begin with a
blank.

@item HIST_NO_STORE
@pindex HIST_NO_STORE
Remove the @code{history} (@code{fc -l}) command from the history
when invoked.

@item HIST_REDUCE_BLANKS
@pindex HIST_REDUCE_BLANKS
Remove superfluous whitespace from each command line
being added to the history list.

@item HIST_VERIFY
@cindex history, verifying substitution
@pindex HIST_VERIFY
Whenever the user enters a line with history substitution, don't execute
the line directly; instead, perform history substitution and reload the
line into the editing buffer.

@item HUP
@cindex jobs, hup
@pindex HUP
Send the @code{HUP} signal to running jobs when the shell exits.

@item IGNORE_BRACES (-I)
@cindex brace expansion, disabling
@cindex expansion, brace, disabling
@cindex disabling brace expansion
@pindex IGNORE_BRACES
Do not perform brace expansion.

@item IGNORE_EOF (-7)
@cindex EOF, ignoring
@pindex IGNORE_EOF
Do not exit on end-of-file.  Require the use of @code{exit} or
@code{logout} instead.

@item INTERACTIVE (-i, ksh: -i)
@pindex INTERACTIVE
This is an interactive shell.  This option is set upon initialisation if 
the standard input is a tty and commands are being read from standard 
input.  (See the discussion of @code{SHIN_STDIN}.)  This heuristic may be 
overridden by specifying a state for this option on the command line.  The 
value of this option cannot be changed anywhere other than the command line.

@item INTERACTIVE_COMMENTS (-k)
@cindex comments, in interactive shells
@pindex INTERACTIVE_COMMENTS
Allow comments even in interactive shells.

@item KSH_ARRAYS
@pindex KSH_ARRAYS
@cindex ksh, style arrays
@cindex arrays, ksh style
Emulate ksh array handling as closely as possible.  If this option is set, 
array elements are numbered from zero, an array parameter without subscript 
refers to the first element instead of the whole array, and braces are 
required to delimit a subscript ( @code{$@{path[2]@}} rather than just
@code{$path[2]} ).

@item KSH_OPTION_PRINT
@cindex ksh, option printing style
@cindex option printing, ksh style
@pindex KSH_OPTION_PRINT
Alters the way options settings are printed.

@item LIST_AMBIGUOUS
@cindex completions, ambiguous
@cindex ambiguous completions
@pindex LIST_AMBIGUOUS
If this option is set completions are shown only if the completions
don't have an unambiguous prefix or suffix that could be inserted in the
command line.

@item LIST_BEEP
@cindex completion, beep on ambiguous
@cindex beep, ambiguous completion
@pindex LIST_BEEP
Beep on an ambiguous completion.

@item LIST_TYPES (-X)
@cindex files, marking type of
@cindex marking file types
@pindex LIST_TYPES
When listing files that are possible completions, show the type of each
file with a trailing identifying mark.

@item LOCAL_OPTIONS
@pindex LOCAL_OPTIONS
If this option is set at the point of return from a shell function, all the
options (including this one) which were in force upon entry to the function
are restored.  Otherwise, only this option and the @code{XTRACE} and 
@code{PRINT_EXIT_VALUE} options are restored.  Hence if this is explicitly 
unset by a shell function the other options in force at the point of return 
will remain so.

@item LOGIN (-l, ksh: -l)
@pindex LOGIN
This is a login shell.

@item LONG_LIST_JOBS (-R)
@cindex jobs, list format
@cindex list format, of jobs
@pindex LONG_LIST_JOBS
List jobs in the long format by default.

@item MAGIC_EQUAL_SUBST
@pindex MAGIC_EQUAL_SUBST
All unquoted arguments of the form
@code{@var{identifier}=@var{expression}} appearing after the command
name have file expansion (that is, where @var{expression} has a leading
`@code{~}' or `@code{=}') performed on @var{expression} as if it were a
parameter assignment.  The argument is not otherwise treated specially:
in other words, it is subsequently treated as a single word, not as an
assignment.

@item MAIL_WARNING (-U)
@cindex mail, warning of arrival
@pindex MAIL_WARNING
Print a warning message if a mail file has been accessed since the shell
last checked.

@item MARK_DIRS (-8, ksh: -X)
@cindex directories, marking
@cindex marking directories
@pindex MARK_DIRS
Append a trailing @code{/} to all directory names resulting from filename
generation (globbing).

@item MENU_COMPLETE (-Y)
@cindex completion, menu
@pindex MENU_COMPLETE
On an ambiguous completion, instead of listing possibilities or beeping,
insert the first match immediately.  Then when completion is requested
again, remove the first match and insert the second match, etc.  When
there are no more matches, go back to the first one again.
@code{reverse-menu-complete} may be used to loop through the list in the
other direction.  This option overrides @code{AUTO_MENU}.

@item MONITOR (-m, ksh: -m)
@cindex job control, allowing
@pindex MONITOR
Allow job control.  Set by default in interactive shells.

@item MULTIOS
@pindex MULTIOS
Perform implicit @code{tee}s or @code{cat}s when multiple redirections 
are attempted. @xref{Redirection}.

@item NOMATCH (-3)
@cindex globbing, no matches
@pindex NO_NOMATCH
If a pattern for filename generation has no matches, print an error, instead 
of leaving it unchanged in the argument list.  This also applies to file 
expansion of an initial @code{~} or @code{=}.

@item NOTIFY (-5, ksh: -b)
@cindex background jobs, notification
@cindex notification of background jobs
@pindex NOTIFY
Report the status of background jobs immediately, rather than waiting
until just before printing a prompt.

@item NULL_GLOB (-G)
@cindex globbing, no matches
@pindex NULL_GLOB
If a pattern for filename generation has no matches, delete the pattern
from the argument list instead of reporting an error.  Overrides
@code{NOMATCH}.

@item NUMERIC_GLOB_SORT
@cindex sorting, numerically
@pindex NUMERIC_GLOB_SORT
If numeric filenames are matched by a filename generation pattern, sort
the filenames numerically rather than lexicographically.

@item OVER_STRIKE
@cindex editor, overstrike mode
@cindex overstrike mode, of editor
@pindex OVER_STRIKE
Start up the line editor in overstrike mode.

@item PATH_DIRS (-Q)
@cindex path search, extended
@pindex PATH_DIRS
Perform a path search even on command names with slashes in them.
Thus if
@display
@samp{/usr/local/bin}
@end display
is in the user's path, and he types @samp{X11/xinit}, the command
@display
@samp{/usr/local/bin/X11/xinit}
@end display
will be executed (assuming it exists).
This applies to the @code{.} builtin as well as to command execution.
Commands explicitly beginning with
@samp{./} or @samp{../} are not subject to path search.

@item POSIX_BUILTINS
@pindex POSIX_BUILTINS
When this option is set the @code{command} builtin can be used to execute
shell builtin commands.  Parameter assignments specified before shell
functions and special builtins are kept after the command completes unless
the special builtin is prefixed with the @code{command} builtin.  Special
builtins are @code{.}, @code{:}, @code{break}, @code{continue},
@code{declare}, @code{eval}, @code{exit}, @code{export}, @code{integer},
@code{local}, @code{readonly}, @code{return}, @code{set}, @code{shift},
@code{source}, @code{times}, @code{trap} and @code{unset}.

@item PRINT_EIGHT_BIT
@cindex eight bit characters, printing
@pindex PRINT_EIGHT_BIT
Print eight bit characters literally in completion lists, etc.
This option is not necessary if your system correctly returns the
printability of eight bit characters (see @code{ctype(3)}).

@item PRINT_EXIT_VALUE (-1)
@cindex exit status, printing
@pindex PRINT_EXIT_VALUE
Print the exit value of programs with non-zero exit status.

@item PRIVILEGED (-p, ksh: -p)
@pindex PRIVILEGED
@cindex privileged mode
@cindex mode, privileged
Turn on privileged mode.  This is enabled automatically on startup if the 
effective user (group) id is not equal to the real user (group) id.  Turning
this option off causes the effective user and group ids to be set to the 
real user and group ids.  This option disables sourcing user startup 
files.  If zsh is invoked as sh or ksh with this option set, 
@file{/etc/suid_profile} is sourced (after @file{/etc/profile} on 
interactive shells).  Sourcing @file{~/.profile} is disabled and the 
contents of the @code{ENV} variable is ignored.  This option cannot be 
changed using the @samp{-m} option of @code{setopt} and @code{unsetopt} 
and changing it inside a function always changes it globally regardless of 
the @code{LOCAL_OPTIONS} option.

@item PROMPT_CR (+V)
@cindex prompt, with CR
@pindex PROMPT_CR
Print a carriage return just before printing a prompt in the line editor.

@item PROMPT_SUBST
@pindex PROMPT_SUBST
If set, @dfn{parameter expansion}, @dfn{command substitution} and 
@dfn{arithmetic expansion} is performed in prompts.

@item PUSHD_IGNORE_DUPS
@cindex directory stack, ignoring dups
@pindex PUSHD_IGNORE_DUPS
Don't push multiple copies of the same directory onto the directory
stack.

@item PUSHD_MINUS
@cindex popd, controlling syntax
@pindex PUSHD_MINUS
@xref{Shell Builtin Commands}, for the @code{popd} command.

@item PUSHD_SILENT (-E)
@cindex directory stack, silencing
@pindex PUSHD_SILENT
Do not print the directory stack after @code{pushd} or @code{popd}.

@item PUSHD_TO_HOME (-D)
@cindex pushd, to home
@pindex PUSHD_TO_HOME
Have @code{pushd} with no arguments act like @code{pushd $HOME}.

@item RC_EXPAND_PARAM (-P)
@pindex RC_EXPAND_PARAM
Array expansions of the form @code{foo$@{xx@}bar}, where the parameter
@code{xx} is set to @code{(a b c)}, are substituted with 
@code{fooabar foobbar foocbar} instead of the default 
@code{fooa b cbar}.

@item RC_QUOTES
@cindex rc, quoting style
@cindex quoting style, rc
@pindex RC_QUOTES
Allow the character sequence @t{@value{dsq}} to signify a single quote within
singly quoted strings.

@item RCS (+f)
@cindex startup files, sourcing
@pindex RCS
After @file{/etc/zshenv} is sourced on startup, source the @file{/etc/zshrc}, 
@file{.zshrc},  @file{/etc/zlogin}, @file{.zlogin}, and @file{.zlogout} files,
as described in @ref{Startup/Shutdown Files}.  If this option is unset, only 
the @file{/etc/zshenv} file is sourced.

@item REC_EXACT (-S)
@cindex completion, exact matches
@pindex REC_EXACT
In completion, recognize exact matches even if they are ambiguous.

@item RM_STAR_SILENT (-H)
@cindex rm *, querying before
@cindex querying before rm *
@pindex RM_STAR_SILENT
Do not query the user before executing @code{rm *} or @code{rm path/*}.

@item SH_FILE_EXPANSION
@cindex sh, expansion style
@cindex expansion style, sh
@pindex SH_FILE_EXPANSION
Perform filename expansion (e.g., @code{~} expansion) before parameter 
expansion, command substitution, arithmetic expansion and brace expansion.
If this option is unset, it is performed after brace expansion, so things
like @code{~$USERNAME} and @code{~@{pfalstad,rc@}} will work.

@item SH_GLOB
@pindex SH_GLOB
@cindex globbing, sh style
@cindex sh, globbing style
Disables the special meaning of @code{(}, @code{|}, @code{)} and @code{<} for 
globbing the result of parameter and command substitutions, and in some other
places where the shell accepts patterns.  This option is set if @code{zsh} is
invoked as @code{sh} or @code{ksh}.

@item SHIN_STDIN (-s, ksh: -s)
@pindex SHIN_STDIN
Commands are being read from the standard input.  Commands are read from 
standard input if no command is specified with @samp{-c} and no file of 
commands is specified.  If @code{SHIN_STDIN} is set explicitly on the command
line, any argument that would otherwise have been taken as a file to run will
instead be treated as a normal positional parameter.  Note that setting or 
un-setting this option on the command line does not necessarily affect the 
state the option will have while the shell is running; that is purely an
indicator of whether or not commands are actually being read from standard 
input.  The value of this option cannot be changed anywhere other than the 
command line.

@item SH_OPTION_LETTERS
@cindex ksh, single letter options style
@cindex single letter options, ksh style
@pindex SH_OPTION_LETTERS
If this option is set the shell tries to interpret single letter options 
(which are used with @code{set} and @code{setopt}) like @code{ksh} does.
This also affects the value of the @code{-} special parameter.

@item SHORT_LOOPS
@pindex SHORT_LOOPS
Allow the short forms of @code{for}, @code{select}, @code{if}, and 
@code{function} constructs.

@item SH_WORD_SPLIT (-y)
@cindex sh, word splitting style
@cindex word splitting, sh style
@pindex SH_WORD_SPLIT
@xref{Parameter Expansion}.

@item SINGLE_COMMAND (-t, ksh: -t)
@cindex single command
@pindex SINGLE_COMMAND
@pindex INTERACTIVE, use of
If the shell is reading from standard input, it exits after a single command 
has been executed.  This also makes the shell non-interactive, unless the 
@code{INTERACTIVE} option is explicitly set on the command line.  The
value of this option cannot be changed anywhere other than the command line.

@pindex SINGLE_LINE_ZLE
@cindex editor, single line mode
@item SINGLE_LINE_ZLE (-M)
Use single-line command line editing instead of multi-line.

@item SUN_KEYBOARD_HACK (-L)
@cindex sun keyboard, annoying
@cindex annoying keyboard, sun
@pindex SUN_KEYBOARD_HACK
If a line ends with a back-quote, and there are an odd number of
back-quotes on the line, ignore the trailing back-quote.  This is useful
on some keyboards where the return key is too small, and the back-quote
key lies annoyingly close to it.

@item UNSET (+u, ksh: +u)
@cindex parameters, substituting unset
@cindex unset parameters, substituting
@pindex UNSET
Treat unset parameters as if they were empty when substituting.  Otherwise 
they are treated as an error.

@item VERBOSE (-v, ksh: -v)
@cindex tracing, of input lines
@pindex VERBOSE
Print shell input lines as they are read.

@item XTRACE (-x, ksh: -x)
@cindex tracing, of commands
@pindex XTRACE
Print commands and their arguments as they are executed.

@item ZLE (-Z)
@cindex editor, disabling
@cindex disabling the editor
@pindex ZLE
Use the zsh line editor.
@end table


@node Single Letter Options, , Description of Options, Options
@section Single Letter Options
@cindex options, single letter


@subsection Default Set

@table @code
@item -0 
@code{CORRECT}

@item -1 
@code{PRINT_EXIT_VALUE}

@item +2 
@code{BAD_PATTERN}

@item +3 
@code{NOMATCH}

@item -4 
@code{GLOB_DOTS}

@item -5 
@code{NOTIFY}

@item -6 
@code{BG_NICE}

@item -7 
@code{IGNORE_EOF}

@item -8 
@code{MARK_DIRS}

@item -9 
@code{AUTO_LIST}

@item +B 
@code{BEEP}
       
@item +C 
@code{CLOBBER}

@item -D 
@code{PUSHD_TO_HOME}
       
@item -E 
@code{PUSHD_SILENT}
       
@item +F 
@code{GLOB}
       
@item -G 
@code{NULL_GLOB}
       
@item -H 
@code{RM_STAR_SILENT}
       
@item -I 
@code{IGNORE_BRACES}
       
@item -J 
@code{AUTO_CD}
       
@item +K 
@code{BANG_HIST}
       
@item -L 
@code{SUN_KEYBOARD_HACK}

@item -M 
@code{SINGLE_LINE_ZLE}
     
@item -N 
@code{AUTO_PUSHD}

@item -O 
@code{CORRECT_ALL}

@item -P 
@code{RC_EXPAND_PARAM}
     
@item -Q 
@code{PATH_DIRS}
     
@item -R 
@code{LONG_LIST_JOBS}
     
@item -S 
@code{REC_EXACT}
     
@item -T 
@code{CDABLE_VARS}
     
@item -U 
@code{MAIL_WARNING}
     
@item +V 
@code{PROMPT_CR}
     
@item -W 
@code{AUTO_RESUME}
     
@item -X 
@code{LIST_TYPES}
     
@item -Y 
@code{MENU_COMPLETE}
     
@item -Z 
@code{ZLE}
     
@item -a 
@code{ALL_EXPORT}

@item -e 
@code{ERR_EXIT}
      
@item +f 
@code{RCS}
     
@item -g 
@code{HIST_IGNORE_SPACE}
     
@item -h 
@code{HIST_IGNORE_DUPS}
     
@item -i 
@code{INTERACTIVE}
     
@item -k 
@code{INTERACTIVE_COMMENTS}
     
@item -l 
@code{LOGIN}
     
@item -m 
@code{MONITOR}
     
@item +n 
@code{EXEC}
     
@item -p 
@code{PRIVILEGED}
     
@item -s 
@code{SHIN_STDIN}
     
@item -t 
@code{SINGLE_COMMAND}
     
@item +u 
@code{UNSET}
     
@item -v 
@code{VERBOSE}
     
@item -w 
@code{CHASE_LINKS}
     
@item -x 
@code{XTRACE}
     
@item -y 
@code{SH_WORD_SPLIT}
@end table


@subsection sh/ksh Emulation Set

@table @code
@item +C 
@code{CLOBBER}
     
@item -X 
@code{MARK_DIRS}
     
@item -a 
@code{ALL_EXPORT}
     
@item -b 
@code{NOTIFY}
     
@item -e 
@code{ERR_EXIT}
     
@item +f 
@code{GLOB}
     
@item -i 
@code{INTERACTIVE}
     
@item -l 
@code{LOGIN}
     
@item -m 
@code{MONITOR}
     
@item +n 
@code{EXEC}
     
@item -p 
@code{PRIVILEGED}
     
@item -s 
@code{SHIN_STDIN}
     
@item -t 
@code{SINGLE_COMMAND}
     
@item +u 
@code{UNSET}
     
@item -v 
@code{VERBOSE}
     
@item -x 
@code{XTRACE}
@end table

@subsection Also Note

@table @code
@item -A 
Used by set for setting arrays

@item -c 
Used on the command line to specify a single command

@item -m 
Used by setopt for pattern-matching option setting

@item -o 
Used in all places to allow use of long option names
@end table
       
@noindent
Note that the use of @samp{-m} in @code{setopt} and @code{unsetopt}, allowing
the specification of option names by glob patterns, clashes with the use of 
@samp{-m} for setting the @code{MONITOR} option.


@node Shell Builtin Commands, Programmable Completion, Options, Top
@chapter Shell Builtin Commands
@cindex builtin commands

@table @code
@item - simple command
@findex -
@xref{Precommand Modifiers}.

@item . @var{file} [ @var{arg} @dots{} ]
@findex .
Read and execute commands from @var{file} and execute them in the 
current shell environment.  If @var{file} does not contain a slash, or if
@code{PATH_DIRS} is set, the shell looks in the components of
@code{path} to find the directory containing @var{file}.  Files in the
current directory are not read unless @samp{.} appears somewhere in
@code{path}.  If any arguments @var{arg} are given, they become the
positional parameters; the old positional parameters are restored when
the @var{file} is done executing.  The exit status is the exit status of
the last command executed.

@item : [ @var{arg} @dots{} ]
@cindex parameters, expanding
@cindex expanding parameters
This command only expands parameters.  A zero exit code is returned.

@item alias [ -grmL ] [ @var{name}[=@var{value}] ] @dots{}
@cindex alias
@findex alias
For each
@var{name} with a corresponding @var{value}, define an alias with that
value.  A trailing space in @var{value} causes the next word to be
checked for alias substitution.  If the @samp{-g} flag is present, define
a global alias; global aliases are expanded even if they do not occur in
command position.  For each @var{name} with no @var{value}, print the
value of @var{name}, if any.  With no arguments, print all currently defined
aliases.  If the @samp{-m} flag is given the arguments are taken as patterns 
(they should be quoted to preserve them from being interpreted as glob 
patterns) and the aliases matching these patterns are printed.  When printing
aliases and the @samp{-g} or @samp{-r} flags are present, then restrict the 
printing to global or regular aliases, respectively.  If the @samp{-L} flag 
is present, then print each alias in a manner suitable for putting in a 
startup script.  The exit status is nonzero if a @var{name} (with no 
@var{value}) is given for which no alias has been defined.

@item autoload [ @var{name} @dots{} ]
@cindex functions, autoloading
@cindex autoloading functions
@findex autoload
For each of the @var{name}s (which are names of functions), create a
function marked undefined.  The @code{fpath} variable will be searched
to find the actual function definition when the function is first 
referenced.  The definition is contained in a file of the same name as 
the function.  If the file found contains a standard definition for the
function, that is stored as the function; otherwise, the contents of the 
entire file are stored as the function.  The latter format allows functions
to be used directly as scripts.

@item bg [ @var{job} @dots{} ]
@itemx @var{job} @dots{} &
@findex bg
Put each specified @var{job} in the background, or the current job if
none is specified. @xref{Jobs & Signals}.

@item bindkey -mevd
@itemx bindkey -r @var{in-string} @dots{}
@itemx bindkey [ -a ] @var{in-string} [ @var{command} ] @dots{}
@itemx bindkey -s [ -a ] @var{in-string} @var{out-string} @dots{}
@cindex rebinding the keys
@cindex keys, rebinding
@findex bindkey
The @samp{-e} and @samp{-v} options put the keymaps in emacs mode and vi
mode respectively; they cannot be used simultaneously.  The @samp{-d}
option resets all bindings to the compiled-in settings.  If not used
with options @samp{-e} or @samp{-v}, the maps will be left in emacs
mode, or in vi mode if the @code{VISUAL} or @code{EDITOR} variables
contain the string @samp{vi}.  Metafied characters are bound to
self-insert by default.  The @samp{-m} option loads the compiled-in
bindings of these characters for the mode determined by the preceding
options, or the current mode if used alone.  Any previous binding done
by the user will be preserved.  If the @samp{-r} option is given, remove
any binding for each @var{in-string}.  If the @samp{-s} option is not
specified, bind each @var{in-string} to a specified @var{command}.  If
no @var{command} is specified, print the binding of @var{in-string} if
it is bound, or return a nonzero exit code if it is not bound.  If the
@samp{-s} option is specified, bind each @var{in-string} to each
specified @var{out-string}.  When @var{in-string} is typed,
@var{out-string} will be pushed back and treated as input to the line
editor.  The process is recursive, but to avoid infinite loops the shell
will report an error if more than 20 consecutive replacements happen.
If the @samp{-a} option is specified, bind the @var{in-string}s in the
alternative keymap instead of the standard one.  The alternative keymap
is used in vi command mode.

@noindent
It's possible for an @var{in-string} to be bound to something and also
be the beginning of a longer bound string.  In this case the shell will
wait a certain time to see if more characters are typed, and if not it
will execute the binding.  This timeout is defined by the
@code{KEYTIMEOUT} parameter; the default is 0.4 seconds.  No timeout is
done if the prefix string is not bound.

@noindent
For either @var{in-string} or @var{out-string}, control characters may
be specified in the form @code{^X}, and the backslash may be used to
introduce one of the following escape sequences:

@table @code
@item \a
Bell character
@item \n
Linefeed (newline)
@item \b
Backspace
@item \t
Horizontal tab
@item \v
Vertical tab
@item \f
Form feed
@item \r
Carriage return
@item \e
@itemx \E
Escape
@item \@var{NNN}
Character code in octal
@item \x@var{NN}
Character code in hexadecimal
@item \M-@var{xxx}
Character or escape sequence with meta bit set.  The @code{-} after the
@code{M} is optional.
@item \C-X
Control character.  The @samp{-} after the @code{M} is optional.
@end table

In all other cases, @code{\} escapes the following character.  Delete is
written as @code{^?}.  Note that @code{\M^?} and @code{^\M?} are not the
same.

@noindent
Multi-character @var{in-strings} cannot contain the null character
(@code{^@@} or @code{^ }).  If they appear in a bindkey command, they
will be silently translated to @code{\M-^@@}.  This restriction does not
apply to @var{out-strings}, single-character @var{in-strings} and the
first character of a multi-char @var{in-string}.

@item break [ @var{n} ]
@cindex loops, exiting
@cindex exiting loops
@findex break
Exit from an enclosing @code{for}, @code{while}, @code{until},
@code{select}, or @code{repeat} loop.  If @var{n} is specified, then
break @var{n} levels instead of just one.

@item builtin @var{name} [ @var{args} ] @dots{}
@findex builtin
Executes the builtin @var{name}, with the given @var{args}.

@item bye
@findex bye
Same as @code{exit}.

@item cd [ @var{arg} ]
@itemx cd @var{old} @var{new}
@itemx cd [+-]n
@cindex directories, changing
@findex cd
Change the current directory.  In the first form, change the current
directory to @var{arg}, or to the value of @code{HOME} if @var{arg} is
not specified.  If @var{arg} is @code{-}, change to the value of
@code{OLDPWD}, the previous directory.  If a directory named @var{arg}
is not found in the current directory and @var{arg} does not begin with
a slash, search each component of the shell parameter @code{cdpath}.  If
the option @code{CDABLEVARS} is set, and a parameter named @var{arg}
exists whose value begins with a slash, treat its value as the
directory.

@noindent
The second form of @code{cd} substitutes the string @var{new} for the
string @var{old} in the name of the current directory, and tries to
change to this new directory.

@noindent
The third form of @code{cd} extracts an entry from the directory stack, 
and changes to that directory.  An argument of the form @code{+@var{n}} 
identifies a stack entry by counting from the left of the list shown by the
@code{dirs} command, starting with zero.  An argument of the form 
@code{-@var{n}} counts from the right.  If the @code{PUSHD_MINUS} option 
is set, the meanings of @code{+} and @code{-} in this context are swapped.

@item chdir
@findex chdir
Same as @code{cd}.

@item command simple command
@findex command
@xref{Precommand Modifiers}.

@item compctl
@xref{Programmable Completion}.

@item continue [ @var{num} ]
@cindex loops, continuing
@cindex continuing loops
@findex continue
Resume the next iteration of the enclosing @code{for}, @code{while},
@code{until}, @code{select}, or @code{repeat} loop.  If @var{n} is
specified, break out of @var{n}-1 loops and resume at the @var{n}'th
enclosing loop.

@item declare [ @var{arg} @dots{} ]
@findex declare
Same as @code{typeset}.

@item dirs [ -v ] [ @var{arg} @dots{} ]
@cindex directory stack, printing
@findex dirs
With no arguments, print the contents of the directory stack.  If the
@samp{-v} option is given, number the directories in the stack when
printing.  Directories are added to this stack with the @code{pushd}
command, and removed with the @code{cd} or @code{popd} commands.  If
arguments are specified, load them onto the directory stack, replacing
anything that was there, and push the current directory onto the
stack.

@item disable [ -afmr ] @var{arg} @dots{}
@cindex disabling commands
@cindex commands, disabling
@findex disable
Disable the hash table element named @var{arg} temporarily.  The default is
to disable builtin commands.  
This allows you to use an external command with the same name as a builtin
command.  The @samp{-a} option causes @code{disable} to act on aliases.  The
@samp{-f} option causes @code{disable} to act on shell functions.  The
@samp{-r} option causes @code{disable} to act on reserved words.  Without
arguments all disabled hash table elements from the corresponding hash table
are printed.  With the @samp{-m} flag the arguments are taken as patterns 
(which should be quoted to preserve them from being taken as glob patterns)
and all hash table elements from the corresponding hash table matching these 
patterns are disabled.  Disabled objects can be enabled with the 
@code{enable} command.

@item disown [ @var{job} @dots{} ]
@itemx job @dots{} &|
@itemx job @dots{} &!
@findex disown
@findex job
Remove the specified jobs from the job table; the shell will no longer
report their status, and will not complain if you try to exit an
interactive shell with them running or stopped.  If no @code{job} is
specified use the current @code{job}.

@item echo [ -neE ] [ @var{arg} @dots{} ]
@findex echo
Write each @var{arg} on the standard output, with a space separating
each one.  If the @samp{-n} flag is not present, print a newline at the
end.  @code{echo} recognizes the following escape sequences:

@table @code
@item \a
Bell
@item \b
Backspace
@item \c
Don't print an ending newline
@item \e
Escape
@item \f
Form feed
@item \n
Newline
@item \r
Carriage return
@item \t
Horizontal tab
@item \v
Vertical tab
@item \\
Backslash
@item \0NNN
Character code in octal, with a maximum of three digits after the zero.
A non-octal digit terminates the number.
@item \xNN
Character code in hexadecimal, with a maximum of two digits after the
@code{x}.  A non-hexadecimal digit terminates the number.
@end table

@noindent
@pindex BSD_ECHO, use of
The @samp{-E} flag or the @code{BSD_ECHO} option can be used to
disable these escape sequences.  In the later case @samp{-e} flag can be 
used to enable them.

@item echotc @var{cap} [ @var{arg} @dots{} ]
@cindex termcap string, printing
@findex echotc
Output the termcap string corresponding to the capability @var{cap},
with optional arguments.

@item emulate [ -LR ] [ zsh | sh | ksh | csh ]
@findex emulate
@cindex compatibility, sh
@cindex compatibility, ksh
@cindex compatibility, csh
@cindex sh, compatibility
@cindex ksh, compatibility
@cindex csh, compatibility
Set up zsh options to emulate the specified shell as much as possible.  
@code{csh} will never be fully emulated.  If the argument is not one of the 
shells listed above, @code{zsh} will be used as a default.  If the @samp{-R}
option is given, all options are reset to their default value corresponding 
to the specified emulation
mode, except for certain options describing the interactive
environment; otherwise, only those options likely to cause portability
problems in scripts and functions are altered.  If the @samp{-L} option
is given, the option @code{LOCAL_OPTIONS} will be set as well, causing
the effect of the @code{emulate} command to be local to the immediately
surrounding shell function, if any; normally this is turned off in all
emulation modes except @code{ksh}.

@item enable [ -afmr ] @var{arg} @dots{}
@findex enable
Enable the hash table element named @var{arg}, presumably disabled earlier
with @code{disable}.  The default is to enable builtin commands.  The 
@samp{-a} option causes @code{enable} to act on aliases.  The @samp{-f} 
option causes @code{enable} to act on shell functions.  The @samp{-r} option
causes @code{enable} to act on reserved words.  Without arguments all enable 
hash table elements from the corresponding hash table are printed.  With 
the @samp{-m} flag the arguments are taken as patterns (should be quoted) 
and all hash table elements from the corresponding hash table matching these
patterns are enabled.  Enabled objects can be disabled with the @code{disable}
builtin command.

@item eval [ @var{arg} @dots{} ]
@cindex evaluating arguments as commands
@findex eval
Read the arguments as input to the shell and execute the resulting
command(s) in the current shell process.

@item exec simple command
@findex exec
@xref{Precommand Modifiers}.

@item exit [ @var{n} ]
@pindex IGNORE_EOF, use of
@findex exit
Exit the shell with the exit code specified by @var{n}; if none is
specified, use the exit code from the last command executed.  An
@code{EOF} condition will also cause the shell to exit, unless the
@code{IGNORE_EOF} option is set.

@item export [ @var{name}[=@var{value}] @dots{} ]
@findex export
The specified @var{name}s are marked for automatic export to the
environment of subsequently executed commands.  @code{export} is equivalent
to @code{typeset -x}.

@item false
@findex false
Do nothing and return an exit code of 1.

@item fc [ -e @var{ename} ] [ -nlrdDfEim ] [ @var{old}=@var{new} @dots{} ] [ @var{first} [ @var{last} ]]
@itemx fc -ARWI [ @var{filename} ]
@cindex history, editing
@cindex editing the history
@findex fc
Select a range of commands from @var{first} to @var{last} from the
history list.  The arguments @var{first} and @var{last} may be specified
as a number or as a string.  A negative number is used as an offset to
the current history event number.  A string specifies the most recent
event beginning with the given string.  All substitutions
@var{old}=@var{new}, if any, are then performed on the commands.  If the
@samp{-l} flag is given, the resulting commands are listed on standard
output.  If the @samp{-m} flag is also given the first argument is taken
as a pattern (which should be quoted), and only the history events
matching this pattern will be shown.  Otherwise the editor program
@var{ename} is invoked on a file containing these history events.  If
@var{ename} is not given, the value of the parameter @code{FCEDIT} is
used.  If @var{ename} is @code{-}, no editor is invoked.  When editing
is complete, the edited command(s) is executed.  If @var{first} is not
specified, it will be set to -1 (the most recent event), or to -16 if
the @samp{-l} flag is given.  If @var{last} is not specified, it will be
set to @var{first}, or to -1 if the @samp{-l} flag is given.  The flag
@samp{-r} reverses the order of the commands and the flag @samp{-n}
suppresses command numbers when listing.  Also when listing, @samp{-d}
prints timestamps for each command, @samp{-f} prints full time and date
stamps. Adding the @samp{-E} flag causes the dates to be printed as 
(@code{dd.mm.yyyy}), instead of the default, @code{mm/dd/yyyy}.  Adding the
@samp{-i} flag causes the dates to be printed as @code{yyyy-mm-dd}, in a
fixed format.  With the @samp{-D} flag, @code{fc} prints elapsed times.

@noindent
@code{fc -R} reads the history from the given file, @code{fc -W} writes the
@cindex history, file
@cindex file, history
history out to the given file, and @code{fc -A} appends the history out to
the given file. @code{fc -AI} (@code{WI}) appends (writes) only those events
that are new since the last incremental append (write) to the history 
file.  In any case the file will have no more than @code{SAVEHIST} entries. 

@item fg [ @var{job} @dots{} ]
@itemx @var{job} @dots{}
@findex fg
Bring the specified @var{job}s to the foreground.  If no @var{job} is
specified, use the current job.

@item functions [ +-tum ] [ @var{name} @dots{} ]
@findex functions
Equivalent to @code{typeset -f}.

@item getln @var{name} @dots{}
@cindex line, reading
@cindex reading a line
@findex getln
Read the top value from the buffer stack and put it in the shell
parameter @var{name}.  Equivalent to @code{read -zr}.  The flags
@samp{-c}, @samp{-l}, @samp{-A}, @samp{-e}, @samp{-E}, and @samp{-n} are
also supported.

@item getopts @var{optstring} @var{name} [ @var{arg} @dots{} ]
@cindex options, processing
@findex getopts
Checks @var{arg} for legal options.  If @var{arg} is omitted, use the
positional parameters.  A valid option argument begins with a @code{+}
or a @code{-}.  An argument not beginning with a @code{+} or a @code{-},
or the argument @code{--}, ends the options.  @var{optstring} contains
the letters that @code{getopts} recognizes.  If a letter is followed by
a @code{:}, that option is expected to have an argument.  The options
can be separated from the argument by blanks.

@noindent
Each time it is invoked, @code{getopts} places the option letter it
finds in the shell parameter @var{name}, prepended with a @code{+} when
@var{arg} begins with a @code{+}.  The index of the next @var{arg} is
stored in @code{OPTIND}.  The option argument, if any, is stored in
@vindex OPTIND, use of
@code{OPTARG}.
@vindex OPTARG, use of

@noindent
A leading @code{:} in @var{optstring} causes @code{getopts} to store the
letter of the invalid option in @code{OPTARG}, and to set @var{name} to
@code{?} for an unknown option and to @code{:} when a required option is
missing.  Otherwise, @code{getopts} prints an error message.  The exit
status is nonzero when there are no more options.

@item hash [ -dfmr ] [ @var{name}[=@var{value} ] ] @dots{}
@findex hash
With no arguments or options, @code{hash} will list the entire command 
hash table.

@noindent
The @samp{-m} option causes the arguments to be taken as patterns 
(they should be quoted) and the elements of the command hash table matching 
these patterns are printed.

@noindent
The @samp{-r} option causes the command hash table to be thrown out and 
restarted.  The @samp{-f} option causes the entire path to be searched, and
all the commands found are added to the hash table.  These options cannot be 
used with any arguments.

@noindent
For each @var{name} with a corresponding @var{value}, put @var{name} in the 
command hash table, associating it with the pathname @var{value}.  Whenever 
@var{name} is used as a command argument, the shell will try to execute the 
file given by @var{value}.  For each @var{name} with no corresponding 
@var{value}, search for @var{name} in the path, and add it to the command 
hash table, and associating it with the discovered path, if it is found.

@noindent
Adding the @samp{-d} option causes @code{hash} to act on the named directory 
table instead of the command hash table.  The remaining discussion of
@code{hash} will assume that the @samp{-d} is given.

@noindent
If invoked without any arguments, and without any other options, 
@code{hash -d} lists the entire named directory table.

@noindent
The @samp{-m} option causes the arguments to be taken as patterns (they 
should be quoted) and the elements of the named directory table matching
these patterns are printed.

@noindent
The @samp{-r} option causes the named directory table to be thrown out and 
restarted so that it only contains  @code{~}.  The @samp{-f} option causes 
all usernames to be added to the named directory table.  These options cannot
be used with any arguments.

@noindent
For each @var{name} with a corresponding @var{value}, put @var{name}
in the named directory table.  The directory name @var{name} is then
associated with the specified path @var{value}, so that @var{value} may 
be referred to as @code{~@var{name}}.  For each @var{name} with no 
corresponding @var{value}, search for as a username and as a parameter.  If
it is found, it is added to the named directory hash table.

@item history [ -nrdDfEim ] [ @var{first} [ @var{last} ]]
@findex history
Same as @code{fc -l}.

@item integer [ +-lrtux ] [ @var{name}[=@var{value}] ]
@findex integer
Same as @code{typeset -i}, except that options irrelevant to integers
are not permitted.

@item jobs [ -lprs ] [ @var{job} @dots{} ]
@findex jobs
Lists information about each given job, or all jobs if @var{job} is
omitted.  The @samp{-l} flag lists process ids, and the @samp{-p} flag
lists process groups.  If the @samp{-r} flag is given only running jobs
will be listed; if the @samp{-s} flag is given only stopped jobs are
shown.

@item kill [ -s @var{signal_name} ] @var{job} @dots{}
@itemx kill [ -@var{sig} ] @var{job} @dots{}
@itemx kill -l [ @var{sig} @dots{} ]
@cindex jobs, killing
@cindex killing jobs
@findex kill
Sends either @code{SIGTERM} or the specified signal to the given jobs or
processes.  Signals are given by number or by names, without the @code{SIG} 
prefix.  If the signal being sent is not @code{KILL} or @code{CONT}, then the 
job will be sent a @code{CONT} signal if it is stopped.  The argument 
@var{job} can be the process id of a job not in the job list.  In the third 
form, @code{kill -l}, if @var{sig} is not specified the signal names are 
listed.  Otherwise, for each @var{sig} that is a name, the corresponding 
signal number is listed.  For each @var{sig} that is a signal number or a 
number representing the exit status of a process which was terminated or 
stopped by a signal the name of the signal is printed.

@item let @var{arg} @dots{}
@findex let
Evaluate each @var{arg} as an arithmetic expression.
@c
@c Why does the next line cause Info-validate to say "invalid reference"?
@c
@xref{Arithmetic Evaluation}, for a description of arithmetic
expressions.  The exit status is 0 if the value of the last expression
is nonzero, and 1 otherwise.

@item limit [ -hs ] [ @var{resource} [ @var{limit} ] ] @dots{}
@cindex resource limits
@cindex limits, resource
@findex limit
Set or display resource limits.  Unless the @samp{-s} flag is given the limit 
applies only the children of the shell.  If @samp{-s} is given without other 
arguments, the resource limits of the current shell is set to the previously 
set resource limits of the children.  If @var{limit} is not specified, print 
the current limit placed on @var{resource}; otherwise set the limit to the 
specified value.  If the @samp{-h} flag is given, use hard limits instead of 
soft limits.  If no @var{resource} is given, print all limits.@*
@var{resource} is one of:

@table @code
@item cputime
Maximum CPU seconds per process.
@item filesize
Largest single file allowed.
@item datasize
Maximum data size (including stack) for each process.
@item stacksize
Maximum stack size for each process.
@item coredumpsize
Maximum size of a core dump.
@item resident
@itemx memoryuse
Maximum resident set size.
@item memorylocked
Maximum amount of memory locked in RAM.
@item descriptors
Maximum value for a file descriptor.
@item openfiles
Maximum number of open files.
@item vmemorysize
Maximum amount of virtual memory.
@end table

Which of these resource limits are available depends on the system.
@var{limit} is a number, with an optional scaling factor, as
follows:

@table @code
@item @var{n}h
Hours.
@item @var{n}k
Kilobytes.  This is the default for all but cputime.
@item @var{n}m
Megabytes or minutes.
@item @var{mm}:@var{ss}
Minutes and seconds.
@end table

@item local [ +-LRZilrtu [@var{n}]] [ @var{name}[=@var{value}] ]
@findex local
Same as @code{typeset}, except that the options @samp{-x} and @samp{-f}
are not permitted.

@item log
@cindex users, watching
@cindex watching users
@vindex watch, use of
@findex log
List all users currently logged in who are affected by the current
setting of the @code{watch} parameter.

@item logout
@findex logout
Exit the shell, if this is a login shell.

@item noglob simple command
@findex noglob
@xref{Precommand Modifiers}.

@item popd [ +-@var{n} ]
@pindex PUSHD_MINUS, use of
@findex popd
Removes a entry from the directory stack and, performs a @code{cd} to the 
new top directory.  With no argument, the current top entry is removed.  An
argument of the form @code{+@var{n}} identifies a stack entry by counting 
from the left of the list shown by the @code{dirs} command, starting with
zero.  An argument of the form @samp{-n} counts from the right.  If the
@code{PUSHD_MINUS} option is set, the meanings of @code{+} and @code{-}
in this context are swapped.

@item print [ -nrslzpNDPoOicm ] [ -u@var{n} ] [ -R [ -en ]] [ @var{arg} @dots{} ]
@findex print
With no flags or with flag @code{-}, the arguments are printed on the
standard output as described by @code{echo}, with the following
differences: the escape sequence @code{\M-x} metafies the character
@code{x} (sets the highest bit), @code{\C-x} produces a control
character (@code{\C-@@} and @code{\C-?} give the characters NULL and
delete) and @code{\E} is a synonym for @code{\e}.  Finally, if not in an
escape sequence, @code{\} escapes the following character and is not
printed.

@table @code
@item -r
Ignore the escape conventions of @code{echo}.
@item -R
Emulate the BSD @code{echo} command which does not process escape sequences 
unless the @samp{-e} flag is given.  The @samp{-n} flag suppresses the 
trailing newline.  Only the @samp{-e} and @samp{-n} flags are recognized 
after @samp{-R}, all other arguments and options are printed.
@item -m
Take the fist argument as a pattern (should be  quoted) and remove it from 
the argument list together with subsequent arguments that do not match this 
pattern.
@item -s
Place the results in the history list instead of on the standard
output.
@item -n
Do not add a newline to the output.
@item -l
Print the arguments separated by newlines instead of spaces.
@item -N
Print the arguments separated and terminated by nulls.
@item -o
Print the arguments sorted in ascending order.
@item -O
Print the arguments sorted in descending order.
@item -i
If given together with @samp{-o} or @samp{-O}, makes the sort be
case-insensitive.
@item -c
Print the arguments in columns.
@item -u@var{n}
Print the arguments to file descriptor @var{n}.
@item -p
Print the arguments to the input of the coprocess.
@item -z
Push the arguments onto the editing buffer stack, separated by spaces;
no escape sequences are recognized.
@item -D
Treat the arguments as directory names, replacing prefixes with @code{~}
expressions, as appropriate.
@item -P
Recognize the same escape sequences as in the @code{PROMPT}
parameter.
@end table

@item pushd [ @var{arg} ]
@itemx pushd @var{old} @var{new}
@itemx pushd +-@var{n}
@findex pushd
@pindex PUSHD_TO_HOME, use of
@pindex PUSHD_MINUS, use of
@pindex CDABLEVARS, use of
@pindex PUSHD_SILENT, use of
Change the current directory, and push the old current directory onto
the directory stack.  In the first form, change the current directory to
@var{arg}.  If @var{arg} is not specified, change to the second
directory on the stack (that is, exchange the top two entries), or
change to the value of @code{HOME} if the @code{PUSHD_TO_HOME} option is
set or if there is only one entry on the stack.  If @var{arg} is
@code{-}, change to the value of @code{OLDPWD}, the previous directory.
If a directory named @var{arg} is not found in the current directory and
@var{arg} does not contain a slash, search each component of the shell
parameter @code{cdpath}.  If the option @code{CDABLEVARS} is set, and a
parameter named @var{arg} exists whose value begins with a slash, treat
its value as the directory.  If the option @code{PUSHD_SILENT} is not
set, the directory stack will be printed after a @code{pushd} is
performed.

@noindent
The second form of @code{pushd} substitutes the string @var{new} for the
string @var{old} in the name of the current directory, and tries to
change to this new directory.

@noindent
The third form of @code{pushd} changes directory by rotating the directory 
list.  An argument of the form @code{+n} identifies a stack entry by counting
from the left of the list shown by the @code{dirs} command, starting with 
zero.  An argument of the form @code{-n} counts from the right.  If the 
@code{PUSHD_MINUS} option is set, the meanings of @code{+} and @code{-} in 
this context are swapped.

@item pushln
@findex pushln
Equivalent to @code{print -nz}.

@item pwd [ -r ]
@findex pwd
@pindex CHASE_LINKS, use of
Print the absolute pathname of the current working directory.  If the 
@samp{-r} flag is specified or the @code{CHASE_LINKS} option is set, the 
printed path will not contain symbolic links.

@item r
@findex r
Equivalent to @code{fc -e -}.

@item read [ -rzpqAclneE ] [ -k [@var{num}] ] [ -u@var{n} ] [ @var{name}?@var{prompt} ] [ @var{name} @dots{} ] 
@vindex IFS
@findex read
Read one line and break it into fields using the characters in
@code{IFS} as separators.  

@table @code
@item -r
Raw mode: a @code{\} at the end of a line does not signify line continuation.

@item -q
Read only one character from the terminal and set @var{name} to @samp{y} if
this character was @samp{y} or @samp{Y} and to @samp{n} otherwise.  With this
flag set the return value is zero only if the character was @samp{y} or 
@samp{Y}.

@item -k [ @var{num} ]
Read only one (or @var{num}) characters from the terminal.

@item -z
Read from the editor buffer stack.  The first field is assigned to the first 
@var{name}, the second field to the second @var{name},  etc., with leftover 
fields assigned to the last @var{name}.

@item -e
@itemx -E
The words read are printed after the whole line is read.  If the @samp{-e} 
flag is set, the words are not assigned to the parameters.

@item -A
The first @var{name} is taken as the name of an array and all words are 
assigned to it.

@item -c
@itemx -l
These flags are allowed only if called inside a function used for completion 
(specified with the @samp{-K} flag to @code{compctl}).  If the @samp{-c} flag 
is given, the words of  the  current command  are  read. If the @samp{-l} flag
is given, the whole line is assigned as a scalar.  If @code{name} is omitted 
then @code{REPLY} is used for scalars and @code{reply} for arrays.

@item -n
Together with either of the previous flags, this option gives the number of 
the word the cursor is on or the index of the character the cursor is on 
respectively. 

@item -u@var{n}
Input is read from file descriptor @var{n}.

@item -p
Input is read from the coprocess.
@end table

@noindent
If the first argument contains a @code{?}, the remainder of this word is 
used as a @code{prompt} on standard error when the shell is interactive.  The
exit status is @code{0} unless an end-of-file is encountered.

@item readonly [ @var{name}[=@var{value}]] @dots{}
@cindex parameters, marking readonly
@findex readonly
The given @var{names} are marked readonly; these names cannot be changed
by subsequent assignment.

@item rehash [ -df ]
@findex rehash
Throw out the command hash table and start over.  If the @samp{-f}
option is set, rescan the command path immediately, instead of
rebuilding the hash table incrementally.

@noindent
The @samp{-d} option causes @code{rehash} to act on the named directory table
instead of the command hash table.  This reduces the named directory table to
only the @code{~} entry.  If the @samp{-f} option is also used, the named 
directory table is rebuilt immediately.

@noindent
@code{rehash} is equivalent to @code{hash -r}.

@item return [ @var{n} ]
@cindex functions, returning from
@findex return
Causes a shell function or @code{.} script to return to the invoking
script with the return status specified by @var{n}.  If @var{n} is
omitted then the return status is that of the last command
executed.

@noindent
If @code{return} was executed from a trap in a @samp{TRAPxxx} function, the 
effect is different for zero and nonzero return status.  With zero status 
(or after an implicit return at the end of the trap), the shell will return 
to whatever it was previously processing;  with a non-zero status, the shell
will behave as interrupted except that the return status of the trap is 
retained.  Note that the signal which caused the trap is passed as the first 
argument, so the statement @samp{return $((128+$1))} will return the same 
status as if the signal had not been trapped.

@item sched [+]@var{hh}:@var{mm} @var{command} @dots{}
@itemx sched [ -@var{item} ]
@cindex timed execution
@cindex execution, timed
@findex sched
Make an entry in the scheduled list of commands to execute.  The time
may be specified in either absolute or relative time.  With no
arguments, prints the list of scheduled commands.  With the argument
@code{-@var{item}}, removes the given item from the list.

@item set [ +-@var{options} ] [ +-o @var{option name} ] @dots{} [ +-A [ @var{name} ] ] [ @var{arg} @dots{} ]
@cindex parameters, positional
@cindex parameters, array
@cindex array parameter, declaring
@findex set
Set the options for the shell and/or set the positional parameters, or
declare an array.  If the @samp{-s} option is given it causes the
specified arguments to be sorted before assigning them to the positional
parameters (or to the array @var{name} if @samp{-A} is used).  With
@samp{+s} sort arguments in descending order.  @xref{Options}, for the
meaning of the other flags.  Flags may be specified by name using the
@samp{-o} option.  If the @samp{-A} flag is specified, @var{name} is set
to an array containing the given @var{arg}s; if @samp{+A} is used and
@var{name} is an array, the given arguments will replace the initial
elements of that array; if no @var{name} is specified, all arrays are
printed.  Otherwise the positional parameters are set.  If no arguments
are given, then the names and values of all parameters are printed on
the standard output.  If the only argument is @code{+}, the names of all
parameters are printed.

@item setopt [ -m ] [ +-@var{options} ] [ @var{name} @dots{} ]
@cindex options, setting
@findex setopt
Set the options for the shell.  All options specified either with flags
or by name are set.  If no arguments are supplied, the names of all
options currently set are printed.  In option names, case is
insignificant, and all underscore characters are ignored.  If the
@samp{-m} flag is given the arguments are taken as patterns (which
should be quoted to preserve them from being interpreted as glob
patterns), and all options with names matching these patterns are set.

@item shift [ @var{n} ] [ @var{name} @dots{} ]
@cindex parameters, positional
@findex shift
The positional parameters from @code{$@var{n}+1} @dots{} are renamed
@code{$1}, where @var{n} is an arithmetic expression that defaults to 1.
If any @var{name}s are given then the arrays with these names are
shifted, instead of the positional parameters.

@item source
@findex source
Same as @samp{.}, except that the current directory is always searched
and is always searched first, before directories in @code{path}.

@item suspend [ -f ]
@cindex shell, suspending
@findex suspend
Suspend the execution of the shell (send it a @code{SIGTSTP}) until it
receives a @code{SIGCONT}.  If the @samp{-f} option is not given,
complain if this is a login shell.

@item test @var{arg} @dots{}
@itemx [ @var{arg} @dots{} ]
@findex test
Like the system version of @code{test}.  Added for compatibility; use
conditional expressions instead.

@item times
@cindex shell, timing
@cindex timing the shell
@findex times
Print the accumulated user and system times for the shell and for
processes run from the shell.

@item trap [ @var{arg} ] [ @var{sig} ] @dots{}
@cindex signals, trapping
@cindex trapping signals
@findex trap
@var{arg} is a command to be read and executed when the shell receives
@var{sig}.  Each @var{sig} can be given as a number or as the name of a
signal.  If @var{arg} is @code{-}, then all traps @var{sig} are reset to
their default values.  If @var{arg} is the null string, then this signal
is ignored by the shell and by the commands it invokes.  If @var{sig} is
@code{ZERR} then @var{arg} will be executed after each command with a
nonzero exit status.  If @var{sig} is @code{DEBUG} then @var{arg} will
be executed after each command. If @var{sig} is @code{0} or @code{EXIT}
and the @code{trap} statement is executed inside the body of a function,
then the command @var{arg} is executed after the function completes.  If
@var{sig} is @code{0} or @code{EXIT} and the @code{trap} statement is
not executed inside the body of a function, then the command @var{arg}
is executed when the shell terminates.  The @code{trap} command with no
arguments prints a list of commands associated with each signal.

Note that traps defined with the @code{trap} builtin are slightly
different from those defined as `@code{TRAP}@var{NAL} () @{ @dots{} @}',
as the latter have their own function environment (line numbers, local
variables, etc.) while the former use the environment of the command in
which they were called.  For example,

@code{trap 'print $LINENO' DEBUG}

will print the line number of command executed after it has run, while

@code{TRAPDEBUG() @{ print $LINENO; @}}

will always print the number zero.

@item true
@findex true
Do nothing and return an exit code of 0.

@item ttyctl [ -fu ]
@cindex tty, freezing
@findex ttyctl
The @samp{-f} option freezes the tty, and @samp{-u} un-freezes it.  When
the tty is frozen, no changes made to the tty settings by external
programs will be honoured by the shell, except for changes in the size of
the screen; the shell will simply reset the
settings to their previous values as soon as each command exits.  Thus,
@code{stty} and similar programs have no effect when the tty is
frozen.  Without options it reports whether the terminal is frozen or
not.

@item type [ -fpam ] @var{name} @dots{}
@findex type
Same as @code{whence -v}.

@item typeset [ +-LRUZfilrtuxm [@var{n}]] [ @var{name}[=@var{value}]] @dots{}
@cindex parameters, setting
@findex typeset
Set attributes and values for shell parameters.  When invoked inside a
function, a new parameter is created which will be unset when the
function completes.  The new parameter will not be exported unless
@code{ALL_EXPORT} is set, in which case the parameter will be exported
provided no parameter of that name already exists.  The following
attributes are valid:

@table @code
@item -L
Left justify and remove leading blanks from @var{value}.  If @var{n} is
nonzero, it defines the width of the field; otherwise it is determined
by the width of the value of the first assignment.  When the parameter
is printed, it is filled on the right with blanks or truncated if
necessary to fit the field.  Leading zeros are removed if the @samp{-Z}
flag is also set.

@item -R
Right justify and fill with leading blanks.  If @var{n} is nonzero it
defines the width of the field; otherwise it is determined by the width
of the value of the first assignment.  When the parameter is printed,
the field is left filled with blanks or truncated from the end.

@item -U
For arrays keep only the first element of each duplications.  It can also be
set for colon separated special parameters like @code{PATH} or @code{FIGNORE},
etc.

@item -Z
Right justify and fill with leading zeros if the first non-blank
character is a digit and the @samp{-L} flag has not been set.  If
@var{n} is nonzero it defines the width of the field; otherwise it is
determined by the width of the value of the first assignment.

@item -f
The names refer to functions rather than parameters.  No assignments can
be made, and the only other valid flags are @samp{-t} and @samp{-u}.
The flag @samp{-t} turns on execution tracing for this function.  The
flag @samp{-u} causes this function to be marked for autoloading.  The
@code{fpath} parameter will be searched to find the function definition
when the function is first referenced.; see @code{autoload}.

@item -i
Use an internal integer representation.  If @var{n} is nonzero it
defines the output arithmetic base, otherwise it is determined by the
first assignment.

@item -l
Convert to lower case.

@item -r
The given @var{name}s are marked read-only.

@item -t
Tags the named parameters.  Tags have no special meaning to the
shell.

@item -u
Convert to upper case.

@item -x
Mark for automatic export to the environment of subsequently executed
commands.
@end table

@noindent
Using @code{+} rather than @code{-} causes these flags to be turned off.
If no arguments are given but flags are specified, a list of named
parameters which have these flags set is printed.  Using @code{+}
instead of @code{-} keeps their values from being printed.  If no
arguments or options are given, the names and attributes of all
parameters are printed.  If only the @samp{-m} flag is given the
arguments are taken as patterns (which should be quoted), and all
parameters or functions (with the @samp{-f} flag) with matching names
are printed.

@item ulimit [ -SHacdflmnpstv ] [ @var{limit} ] @dots{}
@cindex resource limits
@cindex limits, resource
@findex ulimit
Set or display resource limits of the shell and the processes started by the 
shell.  The value of @var{limit} can be a number in the unit specified below
or the value @code{unlimited}.  If the @samp{-H} flag is given use hard limits
instead of soft limits.  If the @samp{-S} flag is given together with the
@samp{-H} flag set both hard and soft limits.  If no options are used, the
file size limit (@samp{-f}) is assumed.  If @var{limit} is omitted the current
value of the specified resources are printed.  When more than one resource
values are printed the limit name and unit is printed before each value.

@table @code
@item -a
Lists all of the current resource limits.
@item -c
Maximum size of core dumps, in 512-byte blocks.
@item -d
Maximum size of the data segment, in Kbytes.
@item -f
Maximum size of individual files written, in 512-byte blocks.
@item -l
Maximum size of locked-in memory, in Kbytes.
@item -m
Maximum size of physical memory, in Kbytes.
@item -n
Maximum number of open file descriptors.
@item -s
Maximum size of stack, in Kbytes.
@item -t
Maximum number of CPU seconds.
@item -u
The number of processes available to the user.
@item -v
Maximum size of virtual memory, in Kbytes.
@end table

@item umask [ -S] [ @var{mask} ]
@cindex umask
@findex umask
The umask is set to @var{mask}.  @var{mask} can be either an octal
number or a symbolic value as described in @code{chmod(1)}.  If @var{mask} 
is omitted, the current value is printed.  The @samp{-S} option causes the 
mask to be printed as a symbolic value.  Otherwise, the mask is printed as an 
octal number.  Note that in the symbolic form the permissions you specify are
those which are to be allowed (not denied) to the users specified).

@item unalias [ -m ] @var{name} @dots{}
@cindex aliases, removing
@findex unalias
The alias definition, if any, for each @var{name} is removed.  With the
@samp{-m} flag, the arguments are taken as patterns (which should be
quoted), and all aliases with matching names are removed.  @code{unalias}
is equivalent to @code{unhash -a}.

@item unfunction [ -m ] @var{name} @dots{}
@cindex functions, removing
@findex unfunction
The function definition, if any, for each @var{name} is removed.  With
the @samp{-m} flag, the arguments are taken as patterns (which should be
quoted), and all function with matching names are removed.  @code{unfunction}
is equivalent to @code{unhash -f}.

@item unhash [ -adfm ] @var{name} @dots{}
@findex unhash
Remove the element named @var{name} from an internal hash table.  The default
is remove elements from the command hash table.  The @samp{-a} option causes 
@code{unhash} to remove aliases.  The @samp{-f} option causes @code{unhash} 
to remove shell functions.  The @samp{-d} options causes @code{unhash} to 
remove named directories.  If the @samp{-m} flag is given the arguments are  
taken as patterns (should be quoted) and all elements of the corresponding  
hash table with matching names will be removed.

@item unlimit [ -hs ] @var{resource} @dots{}
@cindex limits, resource
@cindex resource limits
@findex unlimit
The resource limit for each @var{resource} is set to the hard limit.  If the 
@samp{-h} flag is given and the shell is running as root, the hard resource 
limit for each @var{resource} is removed.  The resources of the shell process 
are only changed if the @samp{-s} flag is given.

@item unset [ -fm ] @var{name} @dots{}
@cindex parameters, unsetting
@findex unset
Each named parameter is unset.  If the @samp{-m} flag is set, the arguments
are taken as patterns (which should be quoted), and all parameters with
matching names are unset.  @code{Unset -f} is equivalent to
@code{unfunction}.

@item unsetopt [ -m ]  [ +-@var{options} ] [ @var{name} @dots{} ]
@cindex options, unsetting
@findex unsetopt
Unset the options for the shell.  All options specified either with
flags or by name are unset.  If the @samp{-m} flag is given, the arguments 
are taken as patterns (which should be quoted), and all options with
names matching these patterns are unset.

@item vared [ -c ] [ -h ] [ -p @var{prompt}] [ -r @var{rprompt} ] @var{name}
@cindex parameters, editing
@cindex editing parameters
@findex vared
The value of the parameter @var{name} is loaded into the edit buffer,
and the line editor is invoked.  When the editor exits, @var{name} is
set to the string value returned by the editor.  If the @samp{-c} flag
is given, the parameter is created if it doesn't already exist.  If the
@samp{-p} flag is given, @var{prompt} will be taken as the prompt to
display at the left and if the @samp{-r} flag is given, the following string
gives the prompt to display at the right.  If the @samp{-h} flag is 
specified, the history can be accessed from @code{zle}.

@item wait [ @var{job} @dots{} ]
@cindex jobs, waiting for
@cindex waiting for jobs
@findex wait
Wait for the specified jobs or processes.  If @var{job} is not given
then all currently active child processes are waited for.  Each
@var{job} can be either a job specification or the process-id of a job
in the job table.  The exit status from this command is that of the job
waited for.

@item whence [ -vcfpam ] @var{name} @dots{}
@findex whence
For each name, indicate how it would be interpreted if used as a command
name.  The @samp{-v} flag produces a more verbose report.  The @samp{-c} 
flag prints the results in a csh-like format and takes precedence over
@samp{-v}.  The @samp{-f} flag causes the contents of a shell function to be
displayed, which would otherwise not happen unless the @samp{-c} flag were
used.  The @samp{-p} flag does a path search for @var{name} even if it is 
an alias, reserved word, shell function or builtin.  The @samp{-a} flag does 
a search for all occurrences of @var{name} throughout the command path.  With 
the @samp{-m} flag, the arguments are taken as patterns (which should be 
quoted), and the information is displayed for each command matching one of 
these patterns.

@item where
@findex where
Same as @code{whence -ca}.

@item which [ -pam ] @var{name} @dots{}
@findex which
Same as @code{whence -c}.
@end table

@node Programmable Completion, Concept Index, Shell Builtin Commands, Top
@chapter Programmable Completion
@cindex completion, programmable
@cindex completion, controlling
@findex compctl

@noindent
@code{compctl [ -CDT ] @var{options} [ @var{command} @dots{} ]}

@noindent
@code{compctl [ -CDT ] @var{options}}@*
@code{        [  -x  @var{pattern}  @var{options} - @dots{} -- ] [ + @var{options} [ -x @dots{} -- ] @dots{} [+] ]}@*
@code{        [ @var{command} @dots{} ]}

@noindent
@code{compctl -L [ -CDT ] [ @var{command} @dots{} ]}

@noindent
@code{compctl + @var{command} @dots{}}

@noindent
Control the editor's completion behaviour according to the supplied set
of @var{options}.  Various editing commands, notably 
@code{expand-or-complete-word}, usually bound to @key{TAB}, will attempt to 
complete a word typed by the user, while others, notably 
@code{delete-char-or-list}, usually bound to @kbd{^D} in emacs editing mode,
list the possibilities; @code{compctl} controls what those possibilities 
are.  They may for example be filenames (the most common case, and hence the
default), shell variables, or words from a user-specified list.

@menu
* Command Flags::
* Options Flags::
* Alternative Completion::
* Extended Completion::
* Example::
@end menu


@node Command Flags, Options Flags,  , Programmable Completion
@section Command Flags

@noindent
Completion of the arguments of a command may be different for each command 
or may use the default.  The behaviour when completing the command word itself
may also be separately specified.  These correspond to the following flags
and arguments, all of which (except for @samp{-L}) may be combined with any
combination of the options described subsequently in @ref{Options Flags}.

@table @code
@item @var{command} @dots{}
controls completion for the named commands, which must be listed last on the
command line.  If completion is attempted for a command with a pathname 
containing slashes and no completion definition is found, the  search is 
retried with the last pathname component.  Note that aliases are expanded
before the command name is determined unless the @code{COMPLETE_ALIASES}
option is set.  Commands should not be combined with the @samp{-D}, 
@samp{-C} or @samp{-T} flags.

@item -D
controls default completion behavior for the arguments of commands not
assigned any special behavior.  If no @code{compctl -D} command has
been issued, filenames are completed.

@item -C
controls completion when the command word itself is being completed.
If no @code{compctl -C} command has been issued,  the names of any
executable command (whether in the path or specific to the shell, such
as aliases or functions) are completed.

@item  -T
supplies completion flags to be used  before any other processing is done,
even those given to specific commands with other @code{compctl} 
definitions.  This works only when combined with the @samp{-x} flag
(@pxref{Extended Completion}).
Using the @samp{-T} flag you can define default behaviour which will apply 
to all commands without exception, or you can alter the standard behaviour 
for all commands.  For example, if your access to the user database is too
slow  and/or it contains too many users (so that completion after @code{~}
is too slow to be usable), you can use

@code{compctl -Tx  'C[0,*/*]' -f - 's[~]' -k @var{friends} -S/}

to complete the strings in the array @var{friends} after a @code{~}.  The 
first argument is necessary so that this form of @code{~}-completion is not
tried after the directory name is finished.

@item -L
lists the existing completion behaviour in a manner suitable for putting 
into a start-up script; the existing behaviour is not changed.  Any 
combination of the above forms may be specified, otherwise all defined 
completions are listed.  Any other flags supplied are ignored.

@item no argument
If no argument is given, @code{compctl} lists all defined completions in an 
abbreviated form; with a list of @var{options}, all completions with those 
flags set (not counting extended completion) are listed.

If the @code{+} flag is alone and followed immediately by the @var{command}
list, the completion behaviour for all the commands in the list is reset to 
the default.  In other words, completion will subsequently use the options 
specified by the @samp{-D} flag.
@end table


@node Options Flags, Alternative Completion, Command Flags, Programmable Completion
@section Options Flags

@noindent
@code{[ -fcFBdeaRGovNAIOPZEnbjrzu ]}@*
@code{[ -k @var{array} ] [ -g @var{globstring} ] [ -s @var{subststring} ]}@*
@code{[ -K @var{function} ] [ -H @var{num} @var{pattern} ]}@*
@code{[ -Q ] [ -P @var{prefix} ] [ -S @var{suffix} ]}@*
@code{[ -q ] [ -X @var{explanation} ]}@*
@code{[ -l @var{cmd} ] [ -U ]}

@noindent
The remaining options specify the type of command arguments to look for 
during completion.  Any combination of these flags may be specified; 
the result is a sorted list of all the possibilities.  The options are 
described in the following sections.

@menu
* Simple Flags::
* Flags with arguments::
* Control Flags::
@end menu

@node Simple Flags, Flags with arguments,  , Options Flags
@subsection Simple Flags

@noindent
These produce completion lists made up by the shell itself:

@table @code
@item -f
Filenames and file-system paths.

@item -c
Command names, including aliases, shell functions, builtins and reserved 
words.

@item -F
Function names.

@item -B
Names of builtin commands.

@item -m
Names of external commands.

@item -w
Reserved words.

@item -a
Alias names.

@item -R
Names of regular (non-global) aliases.

@item -G
Names of global aliases.

@item -d
This can be combined with @samp{-F}, @samp{-B}, @samp{-w}, @samp{-a},
@samp{-R} and @samp{-G} to get names of disabled functions, builtins, reserved
words or aliases.

@item -e
This option (to show enabled commands) is in effect by default, but
may be combined with @samp{-d}; @samp{-de} in combination with
@samp{-F}, @samp{-B}, @samp{-w}, @samp{-a}, @samp{-R} and @samp{-G}
will complete names of functions, builtins, reserved words or aliases
whether or not they are disabled.

@item -o
Names of shell options. @xref{Options}.
 
@item -v
Names of any variable defined in the shell.

@item -N
Names of scalar (non-array) parameters.

@item -A
Array names.

@item -I
Names of integer variables.

@item -O
Names of read-only variables.

@item -p
Names of parameters used by the shell (including special parameters).

@item -Z
Names of shell special parameters.

@item -E
Names of environment variables.

@item -n
Named directories.

@item -b
Key binding names.

@item -j
Job names: the first word of the job leader's command line.  This is useful 
with the kill builtin.

@item -r
Names of running jobs.

@item -z
Names of suspended jobs.

@item -u
User names.
@end table


@node Flags with arguments, Control Flags, Simple Flags, Options Flags
@subsection Flags with arguments

@noindent
These have user supplied arguments to determine how the list of completions
is to be made up:

@table @code
@item -k @var{array}
Names taken from the elements of @code{$@var{array}} (note that the @code{$}
does not appear on the command  line).   Alternatively, the argument 
@code{@var{array}} itself may be a set of space or comma separated values
in parentheses, in which any delimiter may be escaped with a backslash;
in this case the argument should be quoted.  For example,
@samp{compctl -k "(cputime filesize datasize stacksize coredumpsize
resident descriptors)" limit}.

@item -g @var{globstring}
The @var{globstring} is expanded using filename globbing; it should 
be quoted to protect it from immediate expansion.  The resulting filenames
are taken as possible completions.  Use @code{*(/)} instead of @code{*/} 
for directories.  The @code{fignore} special parameter is not applied to 
the resulting files.  More than one pattern may be given separated by 
blanks. (Note that brace expansion is not part of globbing.  Use the syntax
(@code{either|or}) to match alternatives.)

@item -s @var{subststring}
The @var{subststring} is split into words and these words are than
expanded using all shell expansion mechanisms (see the @code{zshexpn}
manual page). The resulting words are taken as possible
completions. The @code{fignore} special parameter is not applied to the
resulting files.  Note that @samp{-g} is faster for filenames.

@item -K @var{function}
Call the given function to get the completions.  The function is passed
two arguments: the prefix and the suffix of the word on which completion is
to be attempted, in other words those characters before the cursor position,
and those from the cursor position onwards.  The function should set the 
variable @code{reply} to an array containing the completions (one completion 
per element); note that @code{reply} should not be made local to the
function.  From such a function the command line can be accessed with the
@samp{-c} and @samp{-l} flags to the @code{read} builtin.  For example, 

@noindent
@code{function whoson @{ reply=(`users`); @}}@*
@code{compctl -K whoson talk}

completes only logged-on users after @samp{talk}.  Note that @code{whoson} 
must return an array so that just @code{reply=`users`} is incorrect.

@item -H @var{num pattern}
The possible completions are taken from the last @var{num} history
lines.  Only words matching @var{pattern} are taken.  If @var{num} is
zero or negative the whole history is searched and if @var{pattern} is
the empty string all words are taken (as with @code{*}).  A typical
use is

@example
compctl -D -f + -H 0 @value{dsq} -X '(No file found; using history)'
@end example

which forces completion to look back in the history list for a word if no
filename matches.  The explanation string is useful as it tells the user
that no file of that name exists, which is otherwise ambiguous.  (See the
next section for @samp{-X}.)
@end table


@node Control Flags,  , Flags with arguments, Options Flags
@subsection Control Flags

@noindent
These do not directly specify types of name to be completed, but manipulate
the options that do:

@table @code
@item -Q
This instructs the shell not to quote any metacharacters in the possible 
completions.  Normally the results of a completion are inserted into the 
command line with any metacharacters quoted so that they  are interpreted
as  normal characters.  This is appropriate for filenames and ordinary
strings.  However, for special effects, such as inserting a backquoted 
expression from a completion array (@samp{-k}) so that the expression will 
not be evaluated until the complete line is executed, this option must be 
used.

@item -P @var{prefix}
The @var{prefix} is inserted just before the completed string; any initial 
part already typed will be completed and the whole @var{prefix} ignored for 
completion purposes.  For example, 

@code{compctl -j -P "%" kill} 

inserts a @code{%} after the @code{kill} command and then completes job 
names.

@item -S @var{suffix}
When a completion is found the @var{suffix} is inserted after the completed
string.  In the case of menu completion the @var{suffix} is inserted 
immediately, but it is still possible to cycle through the list of 
completions by repeatedly hitting the same key.

@item -q
If used with a suffix as specified by the previous option, this causes the 
suffix to be removed if the next character typed is a blank or does not 
insert anything (the same rule as used for the @code{AUTO_REMOVE_SLASH}
option).  The option is most useful for list separators (comma, colon, etc.).

@item -l @var{cmd}
This option cannot be combined with any other option.  It
restricts the range of command line words that are considered to be
arguments.  If combined with one of the extended completion patterns
@samp{p[@dots{}]}, @samp{r[@dots{}]}, or @samp{R[@dots{}]} 
(@pxref{Extended Completion}).
the range is restricted to the arguments specified in the brackets.
Completion is then performed as if these had been given as arguments to the
@var{cmd} supplied with the option.  If the @var{cmd} string is empty the
first word in the range is instead taken as the command name, and command
name completion performed on the first word in the range.  For example,

@example
compctl -x 'r[-exec,;]' -l @value{dsq} -- find
@end example

completes arguments between @code{-exec} and the following @code{;} (or the
end of the command line if there is no such string) as if they were a separate
command line.

@item -U
Use the whole list of possible completions, whether or not they actually
match the word on the command line.  The word typed so far will be
deleted.  This is most useful with a function (given by the @samp{-K} option)
which can examine the word components passed to it (or via the @code{read} 
builtin's @samp{-c} and @samp{-l} flags) and use its own criteria to decide 
what matches.  If there is no completion, the original word is retained.

@item -X @var{explanation}
Print @var{explanation} when trying completion on the current set of 
options.  A @code{%n} in this string is replaced by the number of 
matches.
@end table

@node Alternative Completion, Extended Completion, Options Flags, Programmable Completion
@section Alternative Completion

@noindent
@code{compctl [ -CDT ] @var{options} + @var{options} [ + @dots{} ] [ + ] @var{command} @dots{}}

@noindent
The form with @code{+} specifies alternative @var{options}.  Completion is
tried with the @var{options} before the first @code{+}.  If this produces no
matches completion is tried with the flags after the @code{+} and so on.  If
there are no flags after the last @code{+} and a match has not been found up
to that point, default completion is tried.


@node Extended Completion, Example, Alternative Completion, Programmable Completion
@section Extended Completion

@noindent
@code{compctl  [  -CDT  ]  @var{options} -x @var{pattern} @var{options} - @dots{} -- [ @var{command} @dots{} ]}

@noindent
@code{compctl [ -CDT ] @var{options} [ -x @var{pattern} @var{options} - @dots{} -- ]}@*
@code{        [ + @var{options} [ -x @dots{} -- ] @dots{} [+] ] [ @var{command} @dots{} ]}

@noindent
The form with @samp{-x} specifies extended completion for the commands 
given; as shown, it may be combined with alternative completion using
@code{+}.  Each @var{pattern} is examined in turn; when a match is
found, the corresponding @var{options}, as described in
@ref{Options Flags}, are used to generate possible completions.  If no
@var{pattern} matches, the @var{options} given before the 
@samp{-x} are used.

@noindent
Note that each pattern should be supplied as a single argument and should be
quoted to prevent expansion of meta-characters by the shell.

@noindent
A @var{pattern} is built of sub-patterns separated by commas; it
matches if at least one of these sub-patterns matches (they are 
@code{or}'ed).  
These sub-patterns are in turn composed of other sub-patterns separated by
white spaces which match if all of the sub-patterns match (they are 
@code{and}'ed).  An element of the sub-patterns is of the  form 
@code{c[@dots{}][@dots{}]}, where the pairs of brackets may be repeated as
often as necessary, and matches if any of the sets of brackets match 
(an @code{or}).  The example below makes this clearer.

@noindent
The elements may be any of the following:

@table @code
@item @var{s}[@var{string}] @dots{}
Matches if the current word on the command line starts with one
of the strings given in brackets.  The @var{string} is not removed and is not
part of the completion.

@item @var{S}[@var{string}] @dots{}
Like @var{s}[@var{string}] except that the @var{string} is part of the 
completion.

@item @var{p}[@var{from},@var{to}] @dots{}
Matches if the number of the current word is between one of
the @var{from} and @var{to} pairs inclusive.  The comma and @var{to} are 
optional; @var{to} defaults to the same value as @var{from}.  The numbers 
may be negative: @samp{-n} refers to the @code{n}'th last word on the 
line.

@item @var{c}[@var{offset},@var{string}] @dots{}
Matches if the @var{string} matches the word offset by
@var{offset} from the current word position.  Usually @var{offset} will 
be negative.

@item @var{C}[@var{offset},@var{pattern}] @dots{}
Like @var{c} but using pattern matching instead.

@item @var{w}[@var{index},@var{string}] @dots{}
Matches if the word in position @var{index} is equal to the 
corresponding  @var{string}.  Note that the word count is made after any
alias expansion.

@item @var{W}[@var{index},@var{pattern}] @dots{}
Like @var{w} but using pattern matching instead.

@item @var{n}[@var{index},@var{string}] @dots{}
Matches if the current word contains @var{string}.  Anything up to and 
including the @var{index}'th occurrence of this @var{string} will not be
considered part of the completion, but the rest will.  @var{index} may be
negative to count from the end: in most cases, @var{index} will be 1 or 
-1.

@item @var{N}[@var{index},@var{string}] @dots{}
Like @var{n}[@var{index},@var{string}] except that the @var{string}
will be taken as a character class.  Anything up to and including the 
@var{index}'th occurrence of any of the characters in @var{string} will not
be considered part of the completion.

@item @var{m}[@var{min},@var{max}] @dots{}
Matches if the total number of words lies between @var{min} and @var{max} 
inclusive.

@item @var{r}[@var{str1},@var{str2}] @dots{}
Matches if the cursor is after a word with prefix @var{str1}.  If there is 
also a word with prefix @var{str2} on the command line it matches only if 
the cursor is before this word.

@item @var{R}[@var{str1},@var{str2}] @dots{}
Like @var{r} but using pattern matching instead.
@end table

@node Example,  , Extended Completion, Programmable Completion
@section Example

@noindent
@code{compctl -u -x 's[+] c[-1,-f],s[-f+]' -g '~/Mail/*(:t)' - 's[-f],c[-1,-f]' -f -- mail}

@noindent
This is to be interpreted as follows:

@noindent
If the current command is @code{mail}, then

@noindent
if  ((the current word begins with @code{+} and the previous word is 
@code{-f}) or (the current word begins with @code{-f+})), then complete the 
non-directory part (the @code{:t} glob modifier) of files in the directory  
@file{~/Mail};
else

@noindent
if the current word begins with @samp{-f} or the previous word was 
@samp{-f}, then complete any file; else

@noindent
complete user names.


@node Concept Index, Variables Index, Programmable Completion, Top
@unnumbered Concept Index

@printindex cp

@node Variables Index, Options Index, Concept Index, Top
@unnumbered Variables Index

@printindex vr

@node Options Index, Functions Index, Variables Index, Top
@unnumbered Options Index

@printindex pg

@node Functions Index, Editor Functions Index, Options Index, Top
@unnumbered Functions Index

@printindex fn

@node Editor Functions Index, Keystroke Index, Functions Index, Top
@unnumbered Editor Functions Index

@printindex tp

@node Keystroke Index,  , Editor Functions Index, Top
@unnumbered Keystroke Index

@printindex ky


@setchapternewpage odd
@contents
@bye

@c v0.1, July 8th 1992.  Added documentation for Rick's
@c (pclink@@qld.tne.oz.au) four new glob qualifiers (a/m/c/L)
@c v0.2, August 11th 1992.  Added documentation for the new PSVAR
@c variable, the f E and I flags for the fc command, and the
@c appendhistory and extendedhistory options.  Also corrected a typo in
@c the description of the ${ := } modifier.  Now current to zsh2.3beta
@c (patch level 28).
@c v0.3, August 21 1992.  Unified to the zsh.1 (patchlevel 30) patches
@c supplied by Hans Albertsson.  This meant rewriting most of the extra
@c text I added in v0.1 and v0.2, in order to match Hans'.  Corrected
@c some more typos ("is has" in several places). 
@c       [ added to the archive sometime around here ]
@c v0.4, November 1 1992.  Added up-line-or-search to complement
@c down-line-or-search.  Moved information about availability and the
@c mailing list to the end of the file, to match zsh.1.  Should now be
@c current to patchlevel 65.
@c v0.5, February 5 1993.  Has been kept mostly up-do-date by denizens
@c of the mailing list.  Final clean-up to conform to the new release
@c of zsh version 2.3 (man page dated 1 February 1993), and to the new
@c Texinfo standards (but should remain compatible with old Texinfo).
Eventually I want to rewrite to use the new features of Texinfo v2.0
and above, but we'll have to wait for the rest of the world to catch
up first.  <sigh>
v0.6, June 20th 1993.  Now matches zsh.1 from zsh2.4 patchlevel 158.
Also fixed a few typographical niceties (blank lines between items,
added some more refills, capitalized item descriptions).  Todo: more
cross-referencing, more indexing of new features, and separate vi
and emacs keystroke indices.
v0.7, September 29th 1993.  Now matches zsh.1 from zsh2.4 patchlevel
162, as supplied with 2.4.264.  Also separated out multiple table
entries, compressed secondary tables, and used the new @kbd construct
where possible.
v0.8, December 30th 1993.  Now matches zsh.1 as supplied with zsh
2.4.291.  Changed occurrences of @code{..} @var{..} into @code{..
@var{..}} to make info version cleaner, removed extraneous @code in
@item lines, escaped occurrences of '', other minor bugfixes.
v0.9. June 20th 1994.  Final (I hope) revision before 2.5 is released.
v1.0. June 20th 1994.  Add latest manpage additions and update zsh
version numbers throughout the document. (by Bas)
v2.0. June 06th 1996.  Complete update, modifications re-format. 
(by Clive Messer)
v2.0.1. June 11th 1996. Spelling corrections. Changed single shell flags 
eg. "-f" to @samp, rather than @code.
v2.0.2. June 13th 1996. Several fixes to Programmable Completion. 
v2.0.3. June 20th 1996. Updated to include changes from 2.6.20 to 2.6.21.
v2.0.4. June 21st 1996. Changed occurrences of HISTCHARS to histchars.
Changed mail address for Paul Falstad to pf@software.com.
'Edition' -> 'Document Edition' to save confusion with zsh version.
v2.0.5. June 21st 1996. Fixed compctl -d and -e. Added ref to ***/.
HISTCHARS deprecated, use histchars.
v2.0.5a. June 21st 1996. Speeling(sic) corrections <mdb>.
v2.0.6. June 22nd 1996. Several fixes based on comments by Bart Schaefer 
v2.0.7. June 27th 1996. Re-writes of several sections ..... Shell Grammar
and Expansion.
v2.1.0. July 5th 1996. Deprecated is _not_ depreciated. ;-)
Backed out my re-written sections. Updated to include recent changes to
manual pages and is now in sync with 3.0-pre2.
v2.1.1. July 7th 1996. Add accents to my name fix a typo and improve
ulimit documentation (Zoltan).
v2.1.2. July 8th 1996. Removed the chapter "History" as it was duplicated
as "History Expansion" in chapter "Expansion".
v2.1.3. July 21st 1996. A couple of small fixes from Anthony Heading
<aheading@jpmorgan.com> & Vinnie Shelton <shelton@icd.teradyne.com>. 
Updated URL for mdb's online documentation.
Updated to include changes made to man-pages pre2 -> pre3.
FIXME: URL for ps & dvi.
v2.1.4. July 29th 1996. Updated from man-pages 3.0pre3 -> pre4.
v2.1.5. July 30th 1996. Fixed a couple of @xref's.
v2.1.6. July 31st 1996. Updated to zsh-3.0-pre5 (Zoltan).
v2.1.6a. August 1st 1996. A couple more spelling corrections <mdb>.
v2.1.7. August 1st 1996. Added reference to obtaining precompiled
documentation, zsh-doc.tar.gz.
v2.1.8. August 4th 1996. New special parameters: LANG, LC_ALL,
LC_COLLATE, LC_CTYPE, LC_MESSAGES and LC_TIME (Zoltan).
v2.1.9. August 15th 1996. Final version for zsh-3.0 (Zoltan).
v2.1.10. October 15th 1996. Changes for zsh-3.0.1.  Clarify conditions
for copying. (Zoltan)
