Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ZSHALL(1)		    General Commands Manual		     ZSHALL(1)

NAME
       zshall -	the Z shell meta-man page

OVERVIEW
       Because	zsh contains many features, the	zsh manual has been split into
       a number	of sections.  This manual page includes	all the	separate  man-
       ual pages in the	following order:

       zshroadmap   Informal introduction to the manual
       zshmisc	    Anything not fitting into the other	sections
       zshexpn	    Zsh	command	and parameter expansion
       zshparam	    Zsh	parameters
       zshoptions   Zsh	options
       zshbuiltins  Zsh	built-in functions
       zshzle	    Zsh	command	line editing
       zshcompwid   Zsh	completion widgets
       zshcompsys   Zsh	completion system
       zshcompctl   Zsh	completion control
       zshmodules   Zsh	loadable modules
       zshcalsys    Zsh	built-in calendar functions
       zshtcpsys    Zsh	built-in TCP functions
       zshzftpsys   Zsh	built-in FTP client
       zshcontrib   Additional zsh functions and utilities

DESCRIPTION
       Zsh  is a UNIX command interpreter (shell) usable as an interactive lo-
       gin 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 mech-
       anism, and a host of other features.

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

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

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

       Australia
	      ftp://ftp.zsh.org/pub/
	      http://www.zsh.org/pub/
	      http://mirror.dejanseo.com.au/pub/zsh/

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

       The  up-to-date source code is available	via Git	from Sourceforge.  See
       http://sourceforge.net/projects/zsh/ for	details.   A  summary  of  in-
       structions for the archive can be found at http://zsh.sourceforge.net/.

MAILING	LISTS
       Zsh has 3 mailing lists:

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

       <zsh-users@zsh.org>
	      User discussions.

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

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

       <zsh-announce-subscribe@zsh.org>
       <zsh-users-subscribe@zsh.org>
       <zsh-workers-subscribe@zsh.org>
       <zsh-announce-unsubscribe@zsh.org>
       <zsh-users-unsubscribe@zsh.org>
       <zsh-workers-unsubscribe@zsh.org>

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

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

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

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

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

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

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

INVOCATION
       The following flags are interpreted by the shell	when invoked to	deter-
       mine where the shell will read commands from:

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

       -i     Force  shell to be interactive.  It is still possible to specify
	      a	script to execute.

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

       If there	are any	remaining arguments after option processing, and  nei-
       ther  of	the options -c or -s was supplied, the first argument is taken
       as the file name	of a script containing shell commands to be  executed.
       If  the option PATH_SCRIPT is set, and the file name does not contain a
       directory path (i.e. there is no	`/' in the name),  first  the  current
       directory  and  then  the  command  path	given by the variable PATH are
       searched	for the	script.	 If the	option is not set  or  the  file  name
       contains	a `/' it is used directly.

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

       For  further  options,  which  are  common  to  invocation  and the set
       builtin,	see zshoptions(1).

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

	      zsh -x -o	shwordsplit scr

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

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

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

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

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

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

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

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

       The  following  options	are  set if the	shell is invoked as sh or ksh:
       NO_BAD_PATTERN,	 NO_BANG_HIST,	 NO_BG_NICE,	NO_EQUALS,    NO_FUNC-
       TION_ARGZERO,  GLOB_SUBST,  NO_GLOBAL_EXPORT,  NO_HUP, INTERACTIVE_COM-
       MENTS, KSH_ARRAYS, NO_MULTIOS, NO_NOMATCH,  NO_NOTIFY,  POSIX_BUILTINS,
       NO_PROMPT_PERCENT,  RM_STAR_SILENT,  SH_FILE_EXPANSION, SH_GLOB,	SH_OP-
       TION_LETTERS,  SH_WORD_SPLIT.   Additionally  the  BSD_ECHO   and   IG-
       NORE_BRACES options are set if zsh is invoked as	sh.  Also, the KSH_OP-
       TION_PRINT,   LOCAL_OPTIONS,   PROMPT_BANG,   PROMPT_SUBST   and	  SIN-
       GLE_LINE_ZLE options are	set if zsh is invoked as ksh.

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

       o      changing directories with	the cd builtin

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

       o      specifying command names containing /

       o      specifying command pathnames using hash

       o      redirecting output to files

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

       o      using jobs -Z to overwrite the shell process' argument and envi-
	      ronment space

       o      using the	ARGV0 parameter	to override argv[0] for	external  com-
	      mands

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

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

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

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

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

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

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

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

       Any of these files may be pre-compiled with the zcompile	 builtin  com-
       mand  (see  zshbuiltins(1)).   If a compiled file exists	(named for the
       original	file plus the .zwc extension) and it is	newer than the	origi-
       nal file, the compiled file will	be used	instead.

ZSHROADMAP(1)		    General Commands Manual		 ZSHROADMAP(1)

NAME
       zshroadmap  -  informal	introduction to	the zsh	manual The Zsh Manual,
       like the	shell itself, is large and often complicated.  This section of
       the manual provides some	pointers to areas of the shell that are	likely
       to be of	particular interest to new users, and indicates	where  in  the
       rest of the manual the documentation is to be found.

WHEN THE SHELL STARTS
       When it starts, the shell reads commands	from various files.  These can
       be  created  or	edited	to  customize  the  shell.   See  the  section
       Startup/Shutdown	Files in zsh(1).

       If no personal initialization files exist for the current user, a func-
       tion is run to help you change some of the most	common	settings.   It
       won't appear if your administrator has disabled the zsh/newuser module.
       The function is designed	to be self-explanatory.	 You  can  run	it  by
       hand  with  `autoload -Uz zsh-newuser-install; zsh-newuser-install -f'.
       See also	the section User Configuration Functions in zshcontrib(1).

INTERACTIVE USE
       Interaction with	the shell uses the builtin Zsh Line Editor, ZLE.  This
       is described in detail in zshzle(1).

       The  first  decision a user must	make is	whether	to use the Emacs or Vi
       editing mode as the  keys  for  editing	are  substantially  different.
       Emacs  editing  mode  is	probably more natural for beginners and	can be
       selected	explicitly with	the command bindkey -e.

       A history mechanism for retrieving previously typed lines (most	simply
       with  the  Up or	Down arrow keys) is available; note that, unlike other
       shells, zsh will	not save these lines when the shell exits  unless  you
       set  appropriate	variables, and the number of history lines retained by
       default is quite	small (30 lines).  See the description	of  the	 shell
       variables  (referred  to	 in the	documentation as parameters) HISTFILE,
       HISTSIZE	and SAVEHIST in	zshparam(1).  Note that	 it's  currently  only
       possible	 to  read and write files saving history when the shell	is in-
       teractive, i.e. it does not work	from scripts.

       The shell now supports the UTF-8	character set (and also	others if sup-
       ported  by  the	operating system).  This is (mostly) handled transpar-
       ently by	the shell, but the degree of support in	terminal emulators  is
       variable.   There  is  some  discussion	of  this  in  the  shell  FAQ,
       http://www.zsh.org/FAQ/.	 Note in particular that for combining charac-
       ters to be handled the option COMBINING_CHARS needs to be set.  Because
       the shell is now	more sensitive to the definition of the	character set,
       note  that  if you are upgrading	from an	older version of the shell you
       should ensure that the appropriate variable, either LANG	(to affect all
       aspects	of the shell's operation) or LC_CTYPE (to affect only the han-
       dling of	character sets)	is set to an appropriate value.	 This is  true
       even  if	you are	using a	single-byte character set including extensions
       of ASCII	such as	ISO-8859-1 or ISO-8859-15.   See  the  description  of
       LC_CTYPE	in zshparam(1).

   Completion
       Completion  is  a feature present in many shells. It allows the user to
       type only a part	(usually the prefix) of	a word and have	the shell fill
       in  the rest.  The completion system in zsh is programmable.  For exam-
       ple, the	shell can be set to complete email addresses in	 arguments  to
       the  mail command from your ~/.abook/addressbook; usernames, hostnames,
       and even	remote paths in	arguments to scp, and so  on.	Anything  that
       can  be written in or glued together with zsh can be the	source of what
       the line	editor offers as possible completions.

       Zsh has two completion systems, an old, so  called  compctl  completion
       (named  after  the builtin command that serves as its complete and only
       user interface),	and a new one, referred	to as  compsys,	 organized  as
       library	of builtin and user-defined functions.	The two	systems	differ
       in their	interface for specifying the  completion  behavior.   The  new
       system  is  more	customizable and is supplied with completions for many
       commonly	used commands; it is therefore to be preferred.

       The completion system must be enabled explicitly	when the shell starts.
       For more	information see	zshcompsys(1).

   Extending the line editor
       Apart from completion, the line editor is highly	extensible by means of
       shell functions.	 Some useful functions are provided  with  the	shell;
       they provide facilities such as:

       insert-composed-char
	      composing	characters not found on	the keyboard

       match-words-by-style
	      configuring what the line	editor considers a word	when moving or
	      deleting by word

       history-beginning-search-backward-end, etc.
	      alternative ways of searching the	shell history

       replace-string, replace-pattern
	      functions	for replacing strings or patterns globally in the com-
	      mand line

       edit-command-line
	      edit the command line with an external editor.

       See  the	 section  `ZLE Functions' in zshcontrib(1) for descriptions of
       these.

OPTIONS
       The shell has a large number of options	for  changing  its  behaviour.
       These  cover  all aspects of the	shell; browsing	the full documentation
       is the only good	way to become acquainted with the many	possibilities.
       See zshoptions(1).

PATTERN	MATCHING
       The  shell  has	a  rich	 set  of patterns which	are available for file
       matching	(described in the documentation	as `filename  generation'  and
       also  known for historical reasons as `globbing') and for use when pro-
       gramming.  These	are described in the section `Filename Generation'  in
       zshexpn(1).

       Of particular interest are the following	patterns that are not commonly
       supported by other systems of pattern matching:

       **     for matching over	multiple directories

       ~, ^   the ability to exclude  patterns	from  matching	when  the  EX-
	      TENDED_GLOB option is set

       (...)  glob  qualifiers,	included in parentheses	at the end of the pat-
	      tern, which select files by type (such as	directories) or	attri-
	      bute (such as size).

GENERAL	COMMENTS ON SYNTAX
       Although	 the  syntax  of zsh is	in ways	similar	to the Korn shell, and
       therefore more remotely to the original UNIX shell, the	Bourne	shell,
       its  default  behaviour	does  not entirely correspond to those shells.
       General shell syntax is introduced in the section  `Shell  Grammar'  in
       zshmisc(1).

       One  commonly encountered difference is that variables substituted onto
       the command line	are not	split into words.  See the description of  the
       shell option SH_WORD_SPLIT in the section `Parameter Expansion' in zsh-
       expn(1).	 In zsh, you can either	explicitly request the splitting (e.g.
       ${=foo})	 or  use  an  array when you want a variable to	expand to more
       than one	word.  See the section `Array Parameters' in zshparam(1).

PROGRAMMING
       The most	convenient way of adding enhancements to the  shell  is	 typi-
       cally  by  writing  a  shell  function  and  arranging for it to	be au-
       toloaded.  Functions are	described in the section `Functions'  in  zsh-
       misc(1).	  Users	changing from the C shell and its relatives should no-
       tice that aliases are less used in zsh as they don't  perform  argument
       substitution, only simple text replacement.

       A few general functions,	other than those for the line editor described
       above, are provided with	the shell and are described in	zshcontrib(1).
       Features	include:

       promptinit
	      a	 prompt	theme system for changing prompts easily, see the sec-
	      tion `Prompt Themes'

       zsh-mime-setup
	      a	MIME-handling system which dispatches  commands	 according  to
	      the suffix of a file as done by graphical	file managers

       zcalc  a	calculator

       zargs  a	version	of xargs that makes the	find command redundant

       zmv    a	command	for renaming files by means of shell patterns.

ZSHMISC(1)		    General Commands Manual		    ZSHMISC(1)

NAME
       zshmisc - everything and	then some

SIMPLE COMMANDS	& PIPELINES
       A  simple  command is a sequence	of optional parameter assignments fol-
       lowed by	 blank-separated  words,  with	optional  redirections	inter-
       spersed.	  For  a  description of assignment, see the beginning of zsh-
       param(1).

       The first word is the command to	be executed, and the remaining	words,
       if  any,	are arguments to the command.  If a command name is given, the
       parameter assignments modify the	environment of the command when	it  is
       executed.   The	value  of  a simple command is its exit	status,	or 128
       plus the	signal number if terminated by a signal.  For example,

	      echo foo

       is a simple command with	arguments.

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

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

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

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

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

	      dmesg | grep panic && print yes

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

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

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

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

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

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

       command [ -pvV ]
	      The command word is taken	to be the name of an external command,
	      rather than a shell function or builtin.	 If the	POSIX_BUILTINS
	      option  is  set, builtins	will also be executed but certain spe-
	      cial properties of them are suppressed. The -p flag causes a de-
	      fault  path to be	searched instead of that in $path. With	the -v
	      flag, command is similar to whence and with -V, it is equivalent
	      to whence	-v.

       exec [ -cl ] [ -a argv0 ]
	      The  following  command  together	 with  any arguments is	run in
	      place of the current process, rather than	as a sub-process.  The
	      shell  does not fork and is replaced.  The shell does not	invoke
	      TRAPEXIT,	nor does it source zlogout  files.   The  options  are
	      provided for compatibility with other shells.

	      The -c option clears the environment.

	      The  -l  option  is  equivalent to the - precommand modifier, to
	      treat the	replacement command as a login shell; the  command  is
	      executed	with  a	 - prepended to	its argv[0] string.  This flag
	      has no effect if used together with the -a option.

	      The -a option is used to specify explicitly the  argv[0]	string
	      (the  name  of  the command as seen by the process itself) to be
	      used by the replacement command and is  directly	equivalent  to
	      setting a	value for the ARGV0 environment	variable.

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

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

COMPLEX	COMMANDS
       A complex command in zsh	is one of the following:

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

       for name	... [ in word ... ] term do list done
	      where term is at least one newline or ;.	 Expand	 the  list  of
	      words,  and set the parameter name to each of them in turn, exe-
	      cuting list each time.  If the in	word is	omitted, use the posi-
	      tional parameters	instead	of the words.

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

       for (( [expr1] ;	[expr2]	; [expr3] )) do	list done
	      The arithmetic expression	expr1 is evaluated first (see the sec-
	      tion `Arithmetic Evaluation').  The arithmetic expression	 expr2
	      is  repeatedly  evaluated	 until	it  evaluates to zero and when
	      non-zero,	list is	executed and the arithmetic  expression	 expr3
	      evaluated.   If any expression is	omitted, then it behaves as if
	      it evaluated to 1.

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

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

       repeat word do list done
	      word is expanded and treated as an arithmetic expression,	 which
	      must evaluate to a number	n.  list is then executed n times.

	      The  repeat  syntax is disabled by default when the shell	starts
	      in a mode	emulating another shell.  It can be enabled  with  the
	      command `enable -r repeat'

       case  word  in  [ [(] pattern [ | pattern ] ... ) list (;;|;&|;|) ] ...
       esac
	      Execute the list associated with the first pattern that  matches
	      word, if any.  The form of the patterns is the same as that used
	      for filename generation.	See the	section	`Filename Generation'.

	      Note further that, unless	the SH_GLOB option is set,  the	 whole
	      pattern  with alternatives is treated by the shell as equivalent
	      to a group of patterns within parentheses, although white	 space
	      may  appear  about the parentheses and the vertical bar and will
	      be stripped from the pattern at those points.  White  space  may
	      appear  elsewhere	 in the	pattern; this is not stripped.	If the
	      SH_GLOB option is	set, so	that an	opening	parenthesis can	be un-
	      ambiguously  treated  as part of the case	syntax,	the expression
	      is parsed	into separate words and	these are  treated  as	strict
	      alternatives (as in other	shells).

	      If  the  list that is executed is	terminated with	;& rather than
	      ;;, the following	list is	also executed.	The rule for the  ter-
	      minator of the following list ;;,	;& or ;| is applied unless the
	      esac is reached.

	      If the list that is executed is terminated  with	;|  the	 shell
	      continues	 to scan the patterns looking for the next match, exe-
	      cuting the corresponding list, and applying  the	rule  for  the
	      corresponding  terminator	 ;;,  ;& or ;|.	 Note that word	is not
	      re-expanded; all applicable patterns are tested  with  the  same
	      word.

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

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

       { list }
	      Execute list.

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

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

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

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

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

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

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

	      An exit command (or a return command executed at	the  outermost
	      function	level  of  a  script) encountered in try-list does not
	      cause the	execution of always-list.  Instead,  the  shell	 exits
	      immediately after	any EXIT trap has been executed.

       function	word ... [ () ]	[ term ] { list	}
       word ...	() [ term ] { list }
       word ...	() [ term ] command
	      where term is one	or more	newline	or ;.  Define a	function which
	      is referenced by any one of word.	 Normally, only	 one  word  is
	      provided;	 multiple  words  are  usually only useful for setting
	      traps.  The body of the function is the list between the	{  and
	      }.  See the section `Functions'.

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

	      In  any of the forms above, a redirection	may appear outside the
	      function body, for example

		     func() { ... } 2>&1

	      The redirection is stored	with the function and applied whenever
	      the  function is executed.  Any variables	in the redirection are
	      expanded at the point the	function is executed, but outside  the
	      function scope.

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

       [[ exp ]]
	      Evaluates	the conditional	expression exp and return a zero  exit
	      status if	it is true.  See the section `Conditional Expressions'
	      for a description	of exp.

ALTERNATE FORMS	FOR COMPLEX COMMANDS
       Many of	zsh's  complex	commands  have	alternate  forms.   These  are
       non-standard  and  are  likely not to be	obvious	even to	seasoned shell
       programmers; they should	not be used anywhere that portability of shell
       code is a concern.

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

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

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

	      works, but

		     if	true {	# Does not work!
		       print yes
		     }

	      does not,	since the test is not suitably delimited.

       if list sublist
	      A	short form of the alternate if.	 The same limitations  on  the
	      form of list apply as for	the previous form.

       for name	... ( word ... ) sublist
	      A	short form of for.

       for name	... [ in word ... ] term sublist
	      where  term is at	least one newline or ;.	 Another short form of
	      for.

       for (( [expr1] ;	[expr2]	; [expr3] )) sublist
	      A	short form of the arithmetic for command.

       foreach name ...	( word ... ) list end
	      Another form of for.

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

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

       repeat word sublist
	      This is a	short form of repeat.

       case word { [ [(] pattern [ | pattern ] ... ) list (;;|;&|;|) ] ... }
	      An alternative form of case.

       select name [ in	word ... term ]	sublist
	      where term is at least one newline or ;.	A short	 form  of  se-
	      lect.

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

       do done esac then elif else fi for case if while	function  repeat  time
       until select coproc nocorrect foreach end ! [[ {	} declare export float
       integer local readonly typeset

       Additionally, `}' is recognized in any  position	 if  neither  the  IG-
       NORE_BRACES option nor the IGNORE_CLOSE_BRACES option is	set.

ERRORS
       Certain	errors	are  treated  as fatal by the shell: in	an interactive
       shell, they cause control to return to  the  command  line,  and	 in  a
       non-interactive	shell  they  cause  the	shell to be aborted.  In older
       versions	of zsh,	a non-interactive shell	running	 a  script  would  not
       abort  completely, but would resume execution at	the next command to be
       read from the script, skipping the remainder of any functions or	 shell
       constructs  such	as loops or conditions;	this somewhat illogical	behav-
       iour can	be recovered by	setting	the option CONTINUE_ON_ERROR.

       Fatal errors found in non-interactive shells include:

       o      Failure to parse shell options passed when invoking the shell

       o      Failure to change	options	with the set builtin

       o      Parse errors of all sorts, including failures to parse mathemat-
	      ical expressions

       o      Failures	to  set	or modify variable behaviour with typeset, lo-
	      cal, declare, export, integer, float

       o      Execution	of  incorrectly	 positioned  loop  control  structures
	      (continue, break)

       o      Attempts	to  use	 regular expression with no regular expression
	      module available

       o      Disallowed operations when the RESTRICTED	options	is set

       o      Failure to create	a pipe needed for a pipeline

       o      Failure to create	a multio

       o      Failure to autoload a module needed for a	declared shell feature

       o      Errors creating command or process substitutions

       o      Syntax errors in glob qualifiers

       o      File generation errors where not caught by the  option  BAD_PAT-
	      TERN

       o      All bad patterns used for	matching within	case statements

       o      File generation failures where not caused	by NO_MATCH or similar
	      options

       o      All file generation errors where the pattern was used to	create
	      a	multio

       o      Memory errors where detected by the shell

       o      Invalid subscripts to shell variables

       o      Attempts to assign read-only variables

       o      Logical  errors  with  variables such as assignment to the wrong
	      type

       o      Use of invalid variable names

       o      Errors in	variable substitution syntax

       o      Failure to convert characters in $'...' expressions

       If the POSIX_BUILTINS option is set, more errors	associated with	 shell
       builtin	commands are treated as	fatal, as specified by the POSIX stan-
       dard.

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

ALIASING
       Every eligible word 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 replacement	text ends with
       a  space,  the next word	in the shell input is always eligible for pur-
       poses of	alias expansion.  An alias is defined using the	alias builtin;
       global aliases may be defined using the -g option to that builtin.

       A word is defined as:

       o      Any plain	string or glob pattern

       o      Any  quoted  string,  using  any	quoting	 method	(note that the
	      quotes must be part of the alias definition for this to be  eli-
	      gible)

       o      Any parameter reference or command substitution

       o      Any  series of the foregoing, concatenated without whitespace or
	      other tokens between them

       o      Any reserved word	(case, do, else, etc.)

       o      With global aliasing, any	command	separator, any redirection op-
	      erator, and `(' or `)' when not part of a	glob pattern

       It  is  not  presently possible to alias	the `((' token that introduces
       arithmetic expressions, because until a full statement has been parsed,
       it  cannot be distinguished from	two consecutive	`(' tokens introducing
       nested subshells.

       When POSIX_ALIASES is set, only plain unquoted strings are eligible for
       aliasing.   The	alias  builtin does not	reject ineligible aliases, but
       they are	not expanded.

       Alias expansion is done on the shell input before any  other  expansion
       except  history	expansion.   Therefore,	if an alias is defined for the
       word foo, alias expansion may be	avoided	by quoting part	of  the	 word,
       e.g.  \foo.   Any  form	of quoting works, although there is nothing to
       prevent an alias	being defined for the quoted  form  such  as  \foo  as
       well.   Also,  if a separator such as &&	is aliased, \&&	turns into the
       two tokens \& and &, each of which may have  been  aliased  separately.
       Similarly for \<<, \>|, etc.

       For  use	 with completion, which	would remove an	initial	backslash fol-
       lowed by	a character that isn't special,	it may be more	convenient  to
       quote  the  word	by starting with a single quote, i.e. 'foo; completion
       will automatically add the trailing single quote.

       There is	a commonly encountered problem with aliases illustrated	by the
       following code:

	      alias echobar='echo bar';	echobar

       This  prints  a	message	 that  the command echobar could not be	found.
       This happens because aliases are	expanded when the code is read in; the
       entire  line  is	read in	one go,	so that	when echobar is	executed it is
       too late	to expand the newly defined alias.  This is often a problem in
       shell scripts, functions, and code executed with	`source' or `.'.  Con-
       sequently, use of functions  rather  than  aliases  is  recommended  in
       non-interactive code.

       Note  also  the	unhelpful  interaction of aliases and function defini-
       tions:

	      alias func='noglob func'
	      func() {
		  echo Do something with $*
	      }

       Because aliases are expanded in function	definitions, this  causes  the
       following command to be executed:

	      noglob func() {
		  echo Do something with $*
	      }

       which  defines noglob as	well as	func as	functions with the body	given.
       To avoid	this, either quote the name func or use	the alternative	 func-
       tion  definition	 form  `function func'.	 Ensuring the alias is defined
       after the function works	but is problematic if the code fragment	 might
       be re-executed.

QUOTING
       A  character  may be quoted (that is, made to stand for itself) by pre-
       ceding it with a	`\'.  `\' followed by a	newline	is ignored.

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

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

	      print ''''

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

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

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

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

       < word Open file	word for reading as standard input.

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

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

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

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

       >>| word
       >>! word
	      Same  as	>>, except that	the file is created if it does not ex-
	      ist, even	if CLOBBER is unset.

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

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

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

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

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

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

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

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

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

       >&| word
       >&! word
       &>| word
       &>! word
	      Redirects	both standard output and standard error	(file descrip-
	      tor 2) in	the manner of `>| word'.

       >>& word
       &>> word
	      Redirects	both standard output and standard error	(file descrip-
	      tor 2) in	the manner of `>> word'.

       >>&| word
       >>&! word
       &>>| word
       &>>! word
	      Redirects	both standard output and standard error	(file descrip-
	      tor 2) in	the manner of `>>| word'.

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

	      ... 1>fname 2>&1

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

       The  `|&' command separator described in	Simple Commands	_ Pipelines in
       zshmisc(1) is a shorthand for `2>&1 |'.

       The various forms of process substitution, `<(list)', and `=(list)' for
       input  and `>(list)' for	output,	are often used together	with redirect-
       ion.  For example, if word in an	output	redirection  is	 of  the  form
       `>(list)'  then the output is piped to the command represented by list.
       See Process Substitution	in zshexpn(1).

OPENING	FILE DESCRIPTORS USING PARAMETERS
       When the	shell is parsing arguments to a	command, and the shell	option
       IGNORE_BRACES  is  not set, a different form of redirection is allowed:
       instead of a digit before the operator there is a valid	shell  identi-
       fier  enclosed  in  braces.   The shell will open a new file descriptor
       that is guaranteed to be	at least 10 and	set the	parameter named	by the
       identifier to the file descriptor opened.  No whitespace	is allowed be-
       tween the closing brace and the redirection character.  For example:

	      ... {myfd}>&1

       This opens a new	file descriptor	that is	a duplicate of file descriptor
       1  and  sets  the  parameter myfd to the	number of the file descriptor,
       which will be at	least 10.  The new file	descriptor can be  written  to
       using the syntax	>&$myfd.

       The  syntax  {varid}>&-,	 for example {myfd}>&-,	may be used to close a
       file descriptor opened in this fashion.	Note that the parameter	 given
       by varid	must previously	be set to a file descriptor in this case.

       It  is an error to open or close	a file descriptor in this fashion when
       the parameter is	readonly.  However, it is not  an  error  to  read  or
       write  a	 file  descriptor using	<&$param or >&$param if	param is read-
       only.

       If the option CLOBBER is	unset, it is an	error to open a	file  descrip-
       tor  using  a  parameter	that is	already	set to an open file descriptor
       previously allocated by this mechanism.	Unsetting the parameter	before
       using it	for allocating a file descriptor avoids	the error.

       Note  that this mechanism merely	allocates or closes a file descriptor;
       it does not perform any redirections from or to it.  It is usually con-
       venient	to  allocate  a	file descriptor	prior to use as	an argument to
       exec.  The syntax does not in any case work when	 used  around  complex
       commands	 such  as  parenthesised subshells or loops, where the opening
       brace is	interpreted as part of a command list to be  executed  in  the
       current shell.

       The  following shows a typical sequence of allocation, use, and closing
       of a file descriptor:

	      integer myfd
	      exec {myfd}>~/logs/mylogfile.txt
	      print This is a log message. >&$myfd
	      exec {myfd}>&-

       Note that the expansion of the variable in the expression  >&$myfd  oc-
       curs  at	the point the redirection is opened.  This is after the	expan-
       sion of command arguments and after any redirections to the left	on the
       command line have been processed.

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

	      date >foo	>bar

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

	      date >foo	| cat

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

       Note also that redirections are always expanded in order.  This happens
       regardless of the setting of the	MULTIOS	option,	but with the option in
       effect  there  are additional consequences. For example,	the meaning of
       the expression >&1 will change after a previous redirection:

	      date >&1 >output

       In the case above, the >&1 refers to the	standard output	at  the	 start
       of  the	line; the result is similar to the tee command.	 However, con-
       sider:

	      date >output >&1

       As redirections are evaluated in	order, when the	>&1 is encountered the
       standard	 output	is set to the file output and another copy of the out-
       put is therefore	sent to	that file.  This is unlikely to	be what	is in-
       tended.

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

	      :	> *

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

	      echo exit	0 >> *.sh

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

	      sort <foo	<fubar

       or even

	      sort <f{oo,ubar}

       is equivalent to	`cat foo fubar | sort'.

       Expansion of the	redirection argument occurs at the point the redirect-
       ion is opened, at the point described above for the  expansion  of  the
       variable	in >&$myfd.

       Note that a pipe	is an implicit redirection; thus

	      cat bar |	sort <foo

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

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

	      echo Hello > bar > baz

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

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

	      cat file >file1 >file2
	      cat file1	file2

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

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

	      {	cat file } >file >file2

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

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

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

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

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

	      <	file

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

COMMAND	EXECUTION
       If a command name contains no slashes, the shell	attempts to locate it.
       If there	exists a shell function	by that	name, the function is  invoked
       as  described  in  the  section	`Functions'.   If there	exists a shell
       builtin by that name, the builtin is invoked.

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

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

       If no external command is found but a  function	command_not_found_han-
       dler  exists the	shell executes this function with all command line ar-
       guments.	 The return status of the function becomes the status  of  the
       command.	  If  the  function wishes to mimic the	behaviour of the shell
       when the	command	is not found, it should	print the message `command not
       found:  cmd'  to	 standard  error and return status 127.	 Note that the
       handler is executed in a	subshell forked	to execute  an	external  com-
       mand,  hence changes to directories, shell parameters, etc. have	no ef-
       fect on the main	shell.

FUNCTIONS
       Shell functions are defined with	the function reserved word or the spe-
       cial  syntax `funcname ()'.  Shell functions are	read in	and stored in-
       ternally.  Alias	names are resolved when	the function is	 read.	 Func-
       tions  are  executed  like  commands with the arguments passed as posi-
       tional parameters.  (See	the section `Command Execution'.)

       Functions execute in the	same process as	the caller and share all files
       and  present working directory with the caller.	A trap on EXIT set in-
       side a function is executed after the function completes	in  the	 envi-
       ronment of the caller.

       The return builtin is used to return from function calls.

       Function	 identifiers  can be listed with the functions builtin.	 Func-
       tions can be undefined with the unfunction builtin.

AUTOLOADING FUNCTIONS
       A function can be marked	as undefined using the	autoload  builtin  (or
       `functions  -u'	or `typeset -fu').  Such a function has	no body.  When
       the function is first executed, the shell searches for  its  definition
       using the elements of the fpath variable.  Thus to define functions for
       autoloading, a typical sequence is:

	      fpath=(~/myfuncs $fpath)
	      autoload myfunc1 myfunc2 ...

       The usual alias expansion during	reading	will be	suppressed if the  au-
       toload builtin or its equivalent	is given the option -U.	This is	recom-
       mended for the use of functions supplied	 with  the  zsh	 distribution.
       Note  that  for functions precompiled with the zcompile builtin command
       the flag	-U must	be provided when the .zwc file is created, as the cor-
       responding information is compiled into the latter.

       For  each  element  in fpath, the shell looks for three possible	files,
       the newest of which is used to load the definition for the function:

       element.zwc
	      A	file created with the zcompile builtin command,	which  is  ex-
	      pected  to  contain the definitions for all functions in the di-
	      rectory named element.  The file is treated in the  same	manner
	      as  a  directory	containing files for functions and is searched
	      for the definition of the	function.   If the definition  is  not
	      found,  the  search for a	definition proceeds with the other two
	      possibilities described below.

	      If element already includes a .zwc extension (i.e. the extension
	      was  explicitly  given by	the user), element is searched for the
	      definition of the	function without comparing its age to that  of
	      other  files;  in	 fact, there does not need to be any directory
	      named element without the	suffix.	  Thus	including  an  element
	      such as `/usr/local/funcs.zwc' in	fpath will speed up the	search
	      for functions, with the  disadvantage  that  functions  included
	      must  be	explicitly recompiled by hand before the shell notices
	      any changes.

       element/function.zwc
	      A	file created with zcompile, which is expected to  contain  the
	      definition  for function.	 It may	include	other function defini-
	      tions as well, but those are neither loaded nor executed;	a file
	      found  in	 this way is searched only for the definition of func-
	      tion.

       element/function
	      A	file of	zsh command text, taken	to be the definition for func-
	      tion.

       In  summary, the	order of searching is, first, in the parents of	direc-
       tories in fpath for the newer of	either a compiled directory or	a  di-
       rectory	in fpath; second, if more than one of these contains a defini-
       tion for	the function that is sought, the leftmost in the fpath is cho-
       sen;  and  third,  within  a  directory,	the newer of either a compiled
       function	or an ordinary function	definition is used.

       If the KSH_AUTOLOAD option is set, or the file contains only  a	simple
       definition of the function, the file's contents will be executed.  This
       will normally define the	function in question,  but  may	 also  perform
       initialization, which is	executed in the	context	of the function	execu-
       tion, and may therefore define local parameters.	 It is an error	if the
       function	is not defined by loading the file.

       Otherwise,  the	function body (with no surrounding `funcname() {...}')
       is taken	to be the complete contents of the file.  This form allows the
       file  to	be used	directly as an executable shell	script.	 If processing
       of the file results in the function being re-defined, the function  it-
       self  is	not re-executed.  To force the shell to	perform	initialization
       and then	call the function defined, the file should contain initializa-
       tion code (which	will be	executed then discarded) in addition to	a com-
       plete function definition (which	will be	retained for subsequent	 calls
       to the function), and a call to the shell function, including any argu-
       ments, at the end.

       For example, suppose the	autoload file func contains

	      func() { print This is func; }
	      print func is initialized

       then `func; func' with KSH_AUTOLOAD set will produce both  messages  on
       the  first  call, but only the message `This is func' on	the second and
       subsequent calls.  Without KSH_AUTOLOAD set, it will produce  the  ini-
       tialization  message  on	 the  first call, and the other	message	on the
       second and subsequent calls.

       It is also possible to create a function	that  is  not  marked  as  au-
       toloaded, but which loads its own definition by searching fpath,	by us-
       ing `autoload -X' within	a shell	function.  For example,	the  following
       are equivalent:

	      myfunc() {
		autoload -X
	      }
	      myfunc args...

       and

	      unfunction myfunc	  # if myfunc was defined
	      autoload myfunc
	      myfunc args...

       In  fact,  the  functions  command outputs `builtin autoload -X'	as the
       body of an autoloaded function.	This is	done so	that

	      eval "$(functions)"

       produces	a reasonable result.  A	true autoloaded	function can be	 iden-
       tified  by  the	presence of the	comment	`# undefined' in the body, be-
       cause all comments are discarded	from defined functions.

       To load the definition of an autoloaded function	myfunc without execut-
       ing myfunc, use:

	      autoload +X myfunc

ANONYMOUS FUNCTIONS
       If  no  name  is	given for a function, it is `anonymous'	and is handled
       specially.  Either form of function definition may be used: a `()' with
       no  preceding  name, or a `function' with an immediately	following open
       brace.  The function is executed	immediately at the point of definition
       and  is	not  stored  for  future  use.	 The  function	name is	set to
       `(anon)'.

       Arguments to the	function may be	specified as words following the clos-
       ing  brace  defining the	function, hence	if there are none no arguments
       (other than $0) are set.	 This is a difference from the way other func-
       tions  are  parsed: normal function definitions may be followed by cer-
       tain keywords such as `else' or `fi', which will	be  treated  as	 argu-
       ments  to anonymous functions, so that a	newline	or semicolon is	needed
       to force	keyword	interpretation.

       Note also that the argument list	of any enclosing script	or function is
       hidden  (as  would  be  the  case for any other function	called at this
       point).

       Redirections may	be applied to the anonymous function in	the same  man-
       ner  as	to a current-shell structure enclosed in braces.  The main use
       of anonymous functions is to provide a scope for	local variables.  This
       is  particularly	 convenient  in	start-up files as these	do not provide
       their own local variable	scope.

       For example,

	      variable=outside
	      function {
		local variable=inside
		print "I am $variable with arguments $*"
	      }	this and that
	      print "I am $variable"

       outputs the following:

	      I	am inside with arguments this and that
	      I	am outside

       Note that function definitions with arguments that expand  to  nothing,
       for  example `name=; function $name { ... }', are not treated as	anony-
       mous functions.	Instead, they are treated as normal  function  defini-
       tions where the definition is silently discarded.

SPECIAL	FUNCTIONS
       Certain functions, if defined, have special meaning to the shell.

   Hook	Functions
       For the functions below,	it is possible to define an array that has the
       same name as the	function with `_functions' appended.  Any  element  in
       such an array is	taken as the name of a function	to execute; it is exe-
       cuted in	the same context and with the  same  arguments	as  the	 basic
       function.   For example,	if $chpwd_functions is an array	containing the
       values `mychpwd', `chpwd_save_dirstack',	then the shell attempts	to ex-
       ecute  the  functions  `chpwd', `mychpwd' and `chpwd_save_dirstack', in
       that order.  Any	function that does not exist is	silently  ignored.   A
       function	 found	by  this mechanism is referred to elsewhere as a `hook
       function'.  An error in any function causes subsequent functions	not to
       be  run.	 Note further that an error in a precmd	hook causes an immedi-
       ately following periodic	function not to	run (though it may run at  the
       next opportunity).

       chpwd  Executed whenever	the current working directory is changed.

       periodic
	      If  the parameter	PERIOD is set, this function is	executed every
	      $PERIOD seconds, just before a prompt.  Note  that  if  multiple
	      functions	 are  defined  using the array periodic_functions only
	      one period is applied to the complete set	of functions, and  the
	      scheduled	time is	not reset if the list of functions is altered.
	      Hence the	set of functions is always called together.

       precmd Executed before each prompt.  Note that precommand functions are
	      not  re-executed	simply because the command line	is redrawn, as
	      happens, for example, when a notification	about an  exiting  job
	      is displayed.

       preexec
	      Executed	just  after a command has been read and	is about to be
	      executed.	 If the	history	mechanism  is  active  (regardless  of
	      whether  the  line  was  discarded from the history buffer), the
	      string that the user typed is passed as the first	argument, oth-
	      erwise  it  is an	empty string.  The actual command that will be
	      executed (including expanded aliases) is passed in two different
	      forms:  the  second argument is a	single-line, size-limited ver-
	      sion of the command (with	things like function  bodies  elided);
	      the  third  argument  contains  the full text that is being exe-
	      cuted.

       zshaddhistory
	      Executed when a history line has been  read  interactively,  but
	      before  it  is executed.	The sole argument is the complete his-
	      tory line	 (so  that  any	 terminating  newline  will  still  be
	      present).

	      If  any  of the hook functions returns status 1 (or any non-zero
	      value other than 2, though this is  not  guaranteed  for	future
	      versions	of  the	shell) the history line	will not be saved, al-
	      though it	lingers	in the history until the  next	line  is  exe-
	      cuted, allowing you to reuse or edit it immediately.

	      If  any  of the hook functions returns status 2 the history line
	      will be saved on the internal history list, but not  written  to
	      the  history  file.   In	case of	a conflict, the	first non-zero
	      status value is taken.

	      A	hook function may call `fc -p ...' to switch the history  con-
	      text  so	that the history is saved in a different file from the
	      that in the global HISTFILE parameter.   This  is	 handled  spe-
	      cially:  the history context is automatically restored after the
	      processing of the	history	line is	finished.

	      The following example function works with	 one  of  the  options
	      INC_APPEND_HISTORY  or SHARE_HISTORY set,	in order that the line
	      is written out immediately after the history entry is added.  It
	      first  adds the history line to the normal history with the new-
	      line stripped, which is usually the correct behaviour.  Then  it
	      switches the history context so that the line will be written to
	      a	history	file in	the current directory.

		     zshaddhistory() {
		       print -sr -- ${1%%$'\n'}
		       fc -p .zsh_local_history
		     }

       zshexit
	      Executed at the point where the main shell is about to exit nor-
	      mally.   This  is	 not called by exiting subshells, nor when the
	      exec precommand modifier is used	before	an  external  command.
	      Also, unlike TRAPEXIT, it	is not called when functions exit.

   Trap	Functions
       The functions below are treated specially but do	not have corresponding
       hook arrays.

       TRAPNAL
	      If defined and non-null, this function will be executed whenever
	      the shell	catches	a signal SIGNAL, where NAL is a	signal name as
	      specified	for the	kill  builtin.	 The  signal  number  will  be
	      passed as	the first parameter to the function.

	      If  a  function  of this form is defined and null, the shell and
	      processes	spawned	by it will ignore SIGNAL.

	      The return status	from the function is handled specially.	 If it
	      is  zero,	the signal is assumed to have been handled, and	execu-
	      tion continues normally.	Otherwise, the shell  will  behave  as
	      interrupted  except  that	 the  return status of the trap	is re-
	      tained.

	      Programs terminated by uncaught  signals	typically  return  the
	      status  128  plus	the signal number.  Hence the following	causes
	      the handler for SIGINT to	print a	message, then mimic the	 usual
	      effect of	the signal.

		     TRAPINT() {
		       print "Caught SIGINT, aborting."
		       return $(( 128 +	$1 ))
		     }

	      The  functions  TRAPZERR,	 TRAPDEBUG and TRAPEXIT	are never exe-
	      cuted inside other traps.

       TRAPDEBUG
	      If the option DEBUG_BEFORE_CMD is	set (as	it is by default), ex-
	      ecuted  before  each command; otherwise executed after each com-
	      mand.  See the description of the	trap builtin in	zshbuiltins(1)
	      for details of additional	features provided in debug traps.

       TRAPEXIT
	      Executed	when the shell exits, or when the current function ex-
	      its if defined inside a function.	 The value of $? at the	 start
	      of  execution is the exit	status of the shell or the return sta-
	      tus of the function exiting.

       TRAPZERR
	      Executed whenever	a command has a	non-zero  exit	status.	  How-
	      ever,  the function is not executed if the command occurred in a
	      sublist followed by `&&' or `||';	only the final	command	 in  a
	      sublist  of this type causes the trap to be executed.  The func-
	      tion TRAPERR acts	the same as TRAPZERR on	systems	where there is
	      no SIGERR	(this is the usual case).

       The  functions  beginning  `TRAP' may alternatively be defined with the
       trap builtin:  this may be preferable for some uses.   Setting  a  trap
       with  one  form removes any trap	of the other form for the same signal;
       removing	a trap in either form removes all traps	for the	 same  signal.
       The forms

	      TRAPNAL()	{
	       # code
	      }

       ('function traps') and

	      trap '
	       # code
	      '	NAL

       ('list  traps')	are  equivalent	in most	ways, the exceptions being the
       following:

       o      Function traps have all the properties of	normal functions,  ap-
	      pearing in the list of functions and being called	with their own
	      function context rather than the	context	 where	the  trap  was
	      triggered.

       o      The  return status from function traps is	special, whereas a re-
	      turn from	a list trap causes the surrounding context  to	return
	      with the given status.

       o      Function	traps  are  not	 reset within subshells, in accordance
	      with zsh behaviour; list traps are  reset,  in  accordance  with
	      POSIX behaviour.

JOBS
       If  the	MONITOR	 option	 is set, an interactive	shell associates a job
       with each pipeline.  It keeps a table of	current	jobs, printed  by  the
       jobs  command,  and  assigns them small integer numbers.	 When a	job is
       started asynchronously with `&',	the shell prints a  line  to  standard
       error which looks like:

	      [1] 1234

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

       If a job	is started with	`&|' or	`&!', 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.

       If you are running a job	and wish to do something else you may hit  the
       key  ^Z (control-Z) which sends a TSTP signal to	the current job:  this
       key may be redefined by the susp	option of the external	stty  command.
       The  shell  will	 then  normally	 indicate  that	the job	has been `sus-
       pended',	and print another prompt.  You can then	manipulate  the	 state
       of  this	 job, putting it in the	background with	the bg command,	or run
       some other commands and then eventually bring the  job  back  into  the
       foreground  with	 the foreground	command	fg.  A ^Z takes	effect immedi-
       ately and is like an interrupt in that pending output and unread	 input
       are discarded when it is	typed.

       A job being run in the background will suspend if it tries to read from
       the terminal.

       Note that if the	job running in the foreground  is  a  shell  function,
       then  suspending	 it will have the effect of causing the	shell to fork.
       This is necessary to separate the function's state  from	 that  of  the
       parent  shell performing	the job	control, so that the latter can	return
       to the command line prompt.  As a result, even if fg is	used  to  con-
       tinue  the job the function will	no longer be part of the parent	shell,
       and any variables set by	the function will not be visible in the	parent
       shell.	Thus  the behaviour is different from the case where the func-
       tion was	never suspended.  Zsh is different from	many other  shells  in
       this regard.

       The  same  behaviour  is	 found when the	shell is executing code	as the
       right hand side of a pipeline or	any complex shell  construct  such  as
       if, for,	etc., in order that the	entire block of	code can be managed as
       a single	job.  Background jobs are normally allowed to produce  output,
       but  this  can be disabled by giving the	command	`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.

       When  a	command	 is  suspended and continued later with	the fg or wait
       builtins, zsh restores tty modes	that were in effect when it  was  sus-
       pended.	 This (intentionally) does not apply if	the command is contin-
       ued via `kill -CONT', nor when it is continued with bg.

       There are several ways to refer to jobs in the shell.  A	job can	be re-
       ferred  to by the process ID of any process of the job or by one	of the
       following:

       %number
	      The job with the given number.
       %string
	      The last job whose command line begins with string.
       %?string
	      The last job whose command line contains string.
       %%     Current job.
       %+     Equivalent to `%%'.
       %-     Previous job.

       The shell learns	immediately whenever a process changes state.  It nor-
       mally  informs  you  whenever  a	job becomes blocked so that no further
       progress	is possible.  If the NOTIFY option is not set, it waits	 until
       just before it prints a prompt before it	informs	you.  All such notifi-
       cations are sent	directly to the	terminal, not to the  standard	output
       or standard error.

       When  the  monitor mode is on, each background job that completes trig-
       gers any	trap set for CHLD.

       When you	try to leave the shell while jobs are  running	or  suspended,
       you  will  be warned that `You have suspended (running) jobs'.  You may
       use the jobs command to see what	they are.  If you do this  or  immedi-
       ately 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
       SIGHUP signal, if the HUP option	is set.

       To  avoid  having  the shell terminate the running jobs,	either use the
       nohup command (see nohup(1)) or the disown builtin.

SIGNALS
       The INT and QUIT	signals	for an invoked command are ignored if the com-
       mand  is	 followed  by  `&'  and	the MONITOR option is not active.  The
       shell itself always ignores the QUIT signal.  Otherwise,	 signals  have
       the  values inherited by	the shell from its parent (but see the TRAPNAL
       special functions in the	section	`Functions').

       Certain jobs are	run asynchronously by the shell	other than  those  ex-
       plicitly	 put  into the background; even	in cases where the shell would
       usually wait for	such jobs, an explicit exit command or exit due	to the
       option ERR_EXIT will cause the shell to exit without waiting.  Examples
       of such asynchronous jobs are process  substitution,  see  the  section
       PROCESS	SUBSTITUTION  in  the  zshexpn(1) manual page, and the handler
       processes for multios, see the section MULTIOS in the zshmisc(1)	manual
       page.

ARITHMETIC EVALUATION
       The shell can perform integer and floating point	arithmetic, either us-
       ing the builtin let, or via a substitution of the form  $((...)).   For
       integers,  the  shell is	usually	compiled to use	8-byte precision where
       this is available, otherwise precision is 4 bytes.  This	can be tested,
       for example, by giving the command `print - $(( 12345678901 ))';	if the
       number appears unchanged, the precision is at least 8 bytes.   Floating
       point  arithmetic  always  uses	the `double' type with whatever	corre-
       sponding	precision is provided by the compiler and the library.

       The let builtin command takes arithmetic	expressions as arguments; each
       is  evaluated  separately.   Since many of the arithmetic operators, as
       well as spaces, require quoting,	an alternative form is	provided:  for
       any command which begins	with a `((', all the characters	until a	match-
       ing `))'	are treated as a quoted	expression  and	 arithmetic  expansion
       performed  as  for  an  argument	 of let.  More precisely, `((...))' is
       equivalent to `let "..."'.  The return status is	0  if  the  arithmetic
       value of	the expression is non-zero, 1 if it is zero, and 2 if an error
       occurred.

       For example, the	following statement

	      (( val = 2 + 1 ))

       is equivalent to

	      let "val = 2 + 1"

       both assigning the value	3 to the shell variable	val  and  returning  a
       zero status.

       Integers	can be in bases	other than 10.	A leading `0x' or `0X' denotes
       hexadecimal and a leading `0b' or `0B' binary.  Integers	may also be of
       the  form  `base#n',  where  base  is  a	decimal	number between two and
       thirty-six representing the arithmetic base and n is a number  in  that
       base  (for example, `16#ff' is 255 in hexadecimal).  The	base# may also
       be omitted, in which case base 10 is used.  For backwards compatibility
       the form	`[base]n' is also accepted.

       An  integer expression or a base	given in the form `base#n' may contain
       underscores (`_') after the leading digit for  visual  guidance;	 these
       are  ignored  in	 computation.	Examples  are 1_000_000	or 0xffff_ffff
       which are equivalent to 1000000 and 0xffffffff respectively.

       It is also possible to specify a	base to	be used	for output in the form
       `[#base]',  for	example	 `[#16]'.  This	is used	when outputting	arith-
       metical substitutions or	when assigning to scalar  parameters,  but  an
       explicitly  defined integer or floating point parameter will not	be af-
       fected.	If an integer variable is implicitly defined by	an  arithmetic
       expression,  any	 base  specified  in this way will be set as the vari-
       able's output arithmetic	base as	if the option `-i base'	to the typeset
       builtin	had been used.	The expression has no precedence and if	it oc-
       curs more than once in a	mathematical expression, the last  encountered
       is used.	 For clarity it	is recommended that it appear at the beginning
       of an expression.  As an	example:

	      typeset -i 16 y
	      print $((	[#8] x = 32, y = 32 ))
	      print $x $y

       outputs first `8#40', the rightmost value in the	given output base, and
       then  `8#40 16#20', because y has been explicitly declared to have out-
       put base	16, while x (assuming it does not already exist) is implicitly
       typed  by  the arithmetic evaluation, where it acquires the output base
       8.

       The base	may be replaced	or followed by an underscore, which may	itself
       be  followed  by	 a  positive  integer (if it is	missing	the value 3 is
       used).  This indicates that underscores should  be  inserted  into  the
       output  string,	grouping the number for	visual clarity.	 The following
       integer specifies the number of digits to group together.  For example:

	      setopt cbases
	      print $((	[#16_4]	65536 ** 2 ))

       outputs `0x1_0000_0000'.

       The feature can be used with floating point numbers, in which case  the
       base must be omitted; grouping is away from the decimal point.  For ex-
       ample,

	      zmodload zsh/mathfunc
	      print $((	[#_] sqrt(1e7) ))

       outputs `3_162.277_660_168_379_5' (the number of	decimal	 places	 shown
       may vary).

       If  the	C_BASES	 option	 is set, hexadecimal numbers are output	in the
       standard	C format, for example `0xFF' instead of	the usual `16#FF'.  If
       the  option OCTAL_ZEROES	is also	set (it	is not by default), octal num-
       bers will be treated similarly and hence	appear	as  `077'  instead  of
       `8#77'.	 This  option  has no effect on	the output of bases other than
       hexadecimal and octal, and these	formats	are always understood  on  in-
       put.

       When  an	output base is specified using the `[#base]' syntax, an	appro-
       priate base prefix will be output if necessary, so that the value  out-
       put  is	valid  syntax  for  input.   If	 the # is doubled, for example
       `[##16]', then no base prefix is	output.

       Floating	point constants	are recognized by the presence	of  a  decimal
       point  or an exponent.  The decimal point may be	the first character of
       the constant, but the exponent character	e or E may not,	as it will  be
       taken  for  a  parameter	name.  All numeric parts (before and after the
       decimal point and in the	exponent) may contain  underscores  after  the
       leading digit for visual	guidance; these	are ignored in computation.

       An  arithmetic expression uses nearly the same syntax and associativity
       of expressions as in C.

       In the native mode of operation,	the following operators	are  supported
       (listed in decreasing order of precedence):

       + - ! ~ ++ --
	      unary plus/minus,	logical	NOT, complement, {pre,post}{in,de}cre-
	      ment
       << >>  bitwise shift left, right
       &      bitwise AND
       ^      bitwise XOR
       |      bitwise OR
       **     exponentiation
       * / %  multiplication, division,	modulus	(remainder)
       + -    addition,	subtraction
       < > <= >=
	      comparison
       == !=  equality and inequality
       &&     logical AND
       || ^^  logical OR, XOR
       ? :    ternary operator
       = += -= *= /= %=	&= ^= |= <<= >>= &&= ||= ^^= **=
	      assignment
       ,      comma operator

       The operators `&&', `||', `&&=',	and `||='  are	short-circuiting,  and
       only  one of the	latter two expressions in a ternary operator is	evalu-
       ated.  Note the precedence of the bitwise AND, OR, and XOR operators.

       With the	option C_PRECEDENCES the precedences (but no other properties)
       of the operators	are altered to be the same as those in most other lan-
       guages that support the relevant	operators:

       + - ! ~ ++ --
	      unary plus/minus,	logical	NOT, complement, {pre,post}{in,de}cre-
	      ment
       **     exponentiation
       * / %  multiplication, division,	modulus	(remainder)
       + -    addition,	subtraction
       << >>  bitwise shift left, right
       < > <= >=
	      comparison
       == !=  equality and inequality
       &      bitwise AND
       ^      bitwise XOR
       |      bitwise OR
       &&     logical AND
       ^^     logical XOR
       ||     logical OR
       ? :    ternary operator
       = += -= *= /= %=	&= ^= |= <<= >>= &&= ||= ^^= **=
	      assignment
       ,      comma operator

       Note  the  precedence  of exponentiation	in both	cases is below that of
       unary operators,	hence `-3**2' evaluates	as `9',	not `-9'.  Use	paren-
       theses  where  necessary:  `-(3**2)'.   This  is	for compatibility with
       other shells.

       Mathematical functions can be  called  with  the	 syntax	 `func(args)',
       where  the  function  decides  if  the  args  is	 used as a string or a
       comma-separated list of arithmetic expressions. The shell currently de-
       fines no	mathematical functions by default, but the module zsh/mathfunc
       may be loaded with the zmodload builtin to  provide  standard  floating
       point mathematical functions.

       An  expression of the form `##x'	where x	is any character sequence such
       as `a', `^A', or	`\M-\C-x' gives	the value of this character and	an ex-
       pression	 of the	form `#name' gives the value of	the first character of
       the contents of the parameter name.  Character values are according  to
       the  character  set used	in the current locale; for multibyte character
       handling	the option MULTIBYTE must be set.  Note	that this form is dif-
       ferent from `$#name', a standard	parameter substitution which gives the
       length of the parameter name.  `#\' is accepted instead	of  `##',  but
       its use is deprecated.

       Named  parameters  and  subscripted  arrays  can	 be referenced by name
       within an arithmetic expression without using the  parameter  expansion
       syntax.	For example,

	      ((val2 = val1 * 2))

       assigns twice the value of $val1	to the parameter named val2.

       An  internal  integer representation of a named parameter can be	speci-
       fied with the integer builtin.  Arithmetic evaluation is	 performed  on
       the  value  of each assignment to a named parameter declared integer in
       this manner.  Assigning a floating point	number to an  integer  results
       in rounding towards zero.

       Likewise,  floating  point  numbers  can	 be  declared  with  the float
       builtin;	there are two types, differing only in their output format, as
       described  for  the typeset builtin.  The output	format can be bypassed
       by using	arithmetic substitution	instead	of the parameter substitution,
       i.e.  `${float}'	 uses  the  defined  format,  but  `$((float))'	uses a
       generic floating	point format.

       Promotion of integer to floating	point values is	performed where	neces-
       sary.   In  addition,  if  any operator which requires an integer (`&',
       `|', `^', `<<', `>>' and	their equivalents with assignment) is given  a
       floating	 point	argument, it will be silently rounded towards zero ex-
       cept for	`~' which rounds down.

       Users should beware that, in common with	many  other  programming  lan-
       guages  but not software	designed for calculation, the evaluation of an
       expression in zsh is taken a term at a time and promotion  of  integers
       to  floating point does not occur in terms only containing integers.  A
       typical result of this is that a	division such as 6/8 is	truncated,  in
       this being rounded towards 0.  The FORCE_FLOAT shell option can be used
       in scripts or functions where floating  point  evaluation  is  required
       throughout.

       Scalar variables	can hold integer or floating point values at different
       times; there is no memory of the	numeric	type in	this case.

       If a variable is	first assigned in a numeric context without previously
       being declared, it will be implicitly typed as integer or float and re-
       tain that type either until the type is explicitly changed or until the
       end of the scope.  This can have	unforeseen consequences.  For example,
       in the loop

	      for (( f = 0; f <	1; f +=	0.1 ));	do
	      #	use $f
	      done

       if f has	not already been declared, the first assignment	will cause  it
       to  be created as an integer, and consequently the operation `f += 0.1'
       will always cause the result to be truncated to zero, so	that the  loop
       will  fail.  A simple fix would be to turn the initialization into `f =
       0.0'.  It is therefore best to declare numeric variables	with  explicit
       types.

CONDITIONAL EXPRESSIONS
       A  conditional  expression is used with the [[ 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 expres-
       sions:

       -a file
	      true if file exists.

       -b file
	      true if file exists and is a block special file.

       -c file
	      true if file exists and is a character special file.

       -d file
	      true if file exists and is a directory.

       -e file
	      true if file exists.

       -f file
	      true if file exists and is a regular file.

       -g file
	      true if file exists and has its setgid bit set.

       -h file
	      true if file exists and is a symbolic link.

       -k file
	      true if file exists and has its sticky bit set.

       -n string
	      true if length of	string is non-zero.

       -o option
	      true if option named option is on.  option may be	a single char-
	      acter,  in  which	 case it is a single letter option name.  (See
	      the section `Specifying Options'.)

       -p file
	      true if file exists and is a FIFO	special	file (named pipe).

       -r file
	      true if file exists and is readable by current process.

       -s file
	      true if file exists and has size greater than zero.

       -t fd  true if file descriptor number fd	is open	and associated with  a
	      terminal device.	(note: fd is not optional)

       -u file
	      true if file exists and has its setuid bit set.

       -v varname
	      true if shell variable varname is	set.

       -w file
	      true if file exists and is writable by current process.

       -x file
	      true  if	file  exists and is executable by current process.  If
	      file exists and is a directory, then  the	 current  process  has
	      permission to search in the directory.

       -z string
	      true if length of	string is zero.

       -L file
	      true if file exists and is a symbolic link.

       -O file
	      true  if	file  exists  and is owned by the effective user ID of
	      this process.

       -G file
	      true if file exists and its group	matches	the effective group ID
	      of this process.

       -S file
	      true if file exists and is a socket.

       -N file
	      true  if	file  exists and its access time is not	newer than its
	      modification time.

       file1 -nt file2
	      true if file1 exists and is newer	than file2.

       file1 -ot file2
	      true if file1 exists and is older	than file2.

       file1 -ef file2
	      true if file1 and	file2 exist and	refer to the same file.

       string =	pattern
       string == pattern
	      true if string matches  pattern.	 The  two  forms  are  exactly
	      equivalent.   The	 `=' form is the traditional shell syntax (and
	      hence the	only one generally used	with the test and [ builtins);
	      the  `=='	 form  provides	compatibility with other sorts of com-
	      puter language.

       string != pattern
	      true if string does not match pattern.

       string =~ regexp
	      true if string matches the regular expression  regexp.   If  the
	      option  RE_MATCH_PCRE  is	set regexp is tested as	a PCRE regular
	      expression using the zsh/pcre module, else it  is	 tested	 as  a
	      POSIX  extended  regular	expression using the zsh/regex module.
	      Upon successful match, some variables will be updated; no	 vari-
	      ables are	changed	if the matching	fails.

	      If the option BASH_REMATCH is not	set the	scalar parameter MATCH
	      is set to	the substring that matched the pattern and the integer
	      parameters  MBEGIN  and  MEND to the index of the	start and end,
	      respectively, of the match in string, such  that	if  string  is
	      contained	in variable var	the expression `${var[$MBEGIN,$MEND]}'
	      is identical to `$MATCH'.	 The setting of	the option  KSH_ARRAYS
	      is  respected.   Likewise,  the  array  match is set to the sub-
	      strings that matched parenthesised subexpressions	and the	arrays
	      mbegin  and  mend	to the indices of the start and	end positions,
	      respectively, of the substrings within string.  The  arrays  are
	      not set if there were no parenthesised subexpresssions.  For ex-
	      ample, if	the string `a short string'  is	 matched  against  the
	      regular  expression `s(...)t', then (assuming the	option KSH_AR-
	      RAYS is not set) MATCH, MBEGIN and MEND are `short',  3  and  7,
	      respectively,  while match, mbegin and mend are single entry ar-
	      rays containing the strings `hor', `4' and `6', respectively.

	      If the option BASH_REMATCH is set	the array BASH_REMATCH is  set
	      to  the  substring that matched the pattern followed by the sub-
	      strings that matched  parenthesised  subexpressions  within  the
	      pattern.

       string1 < string2
	      true  if	string1	 comes	before string2 based on	ASCII value of
	      their characters.

       string1 > string2
	      true if string1 comes after string2  based  on  ASCII  value  of
	      their characters.

       exp1 -eq	exp2
	      true if exp1 is numerically equal	to exp2.  Note that for	purely
	      numeric comparisons use of the ((...)) builtin described in  the
	      section  `ARITHMETIC  EVALUATION'	is more	convenient than	condi-
	      tional expressions.

       exp1 -ne	exp2
	      true if exp1 is numerically not equal to exp2.

       exp1 -lt	exp2
	      true if exp1 is numerically less than exp2.

       exp1 -gt	exp2
	      true if exp1 is numerically greater than exp2.

       exp1 -le	exp2
	      true if exp1 is numerically less than or equal to	exp2.

       exp1 -ge	exp2
	      true if exp1 is numerically greater than or equal	to exp2.

       ( exp )
	      true if exp is true.

       ! exp  true if exp is false.

       exp1 && exp2
	      true if exp1 and exp2 are	both true.

       exp1 || exp2
	      true if either exp1 or exp2 is true.

       For compatibility, if there is a	single argument	that is	not  syntacti-
       cally  significant, typically a variable, the condition is treated as a
       test for	whether	the expression expands as a string of non-zero length.
       In  other words,	[[ $var	]] is the same as [[ -n	$var ]].  It is	recom-
       mended that the second, explicit, form be used where possible.

       Normal shell expansion is performed on the file,	string and pattern ar-
       guments,	but the	result of each expansion is constrained	to be a	single
       word, similar to	the effect of double quotes.

       Filename	generation is not performed on any form	of argument to	condi-
       tions.  However,	it can be forced in any	case where normal shell	expan-
       sion is valid and when the option EXTENDED_GLOB is in effect  by	 using
       an  explicit  glob qualifier of the form	(#q) at	the end	of the string.
       A normal	glob qualifier expression may appear between the `q'  and  the
       closing	parenthesis;  if none appears the expression has no effect be-
       yond causing filename generation.  The results of  filename  generation
       are joined together to form a single word, as with the results of other
       forms of	expansion.

       This special use	of filename generation is only available with  the  [[
       syntax.	 If the	condition occurs within	the [ or test builtin commands
       then globbing occurs instead as part of normal command  line  expansion
       before the condition is evaluated.  In this case	it may generate	multi-
       ple words which are likely to confuse the syntax	of the test command.

       For example,

	      [[ -n file*(#qN) ]]

       produces	status zero if and only	if there is at least one file  in  the
       current directory beginning with	the string `file'.  The	globbing qual-
       ifier N ensures that the	expression is empty if there  is  no  matching
       file.

       Pattern	metacharacters	are active for the pattern arguments; the pat-
       terns are the same as those used	 for  filename	generation,  see  zsh-
       expn(1),	but there is no	special	behaviour of `/' nor initial dots, and
       no glob qualifiers are allowed.

       In each of the above expressions, if file is of the  form  `/dev/fd/n',
       where n is an integer, then the test applied to the open	file whose de-
       scriptor	number is n, even if the underlying system  does  not  support
       the /dev/fd directory.

       In  the	forms which do numeric comparison, the expressions exp undergo
       arithmetic expansion as if they were enclosed in	$((...)).

       For example, the	following:

	      [[ ( -f foo || -f	bar ) && $report = y* ]] && print File exists.

       tests if	either file foo	or file	bar exists, and	if so, if the value of
       the  parameter  report  begins  with  `y'; if the complete condition is
       true, the message `File exists.'	is printed.

EXPANSION OF PROMPT SEQUENCES
       Prompt sequences	undergo	a special form of expansion.  This type	of ex-
       pansion is also available using the -P option to	the print builtin.

       If the PROMPT_SUBST option is set, the prompt string is first subjected
       to parameter expansion, command substitution and	arithmetic  expansion.
       See zshexpn(1).

       Certain escape sequences	may be recognised in the prompt	string.

       If  the	PROMPT_BANG  option is set, a `!' in the prompt	is replaced by
       the current history event number.  A literal `!'	 may  then  be	repre-
       sented as `!!'.

       If  the	PROMPT_PERCENT	option	is  set, certain escape	sequences that
       start with `%' are expanded.  Many escapes are  followed	 by  a	single
       character,  although  some  of  these take an optional integer argument
       that should appear between the `%' and the next character  of  the  se-
       quence.	 More  complicated  escape  sequences are available to provide
       conditional expansion.

SIMPLE PROMPT ESCAPES
   Special characters
       %%     A	`%'.

       %)     A	`)'.

   Login information
       %l     The line (tty) the user is logged	in on, without `/dev/' prefix.
	      If the name starts with `/dev/tty', that prefix is stripped.

       %M     The full machine hostname.

       %m     The hostname up to the first `.'.	 An integer may	follow the `%'
	      to specify how many components  of  the  hostname	 are  desired.
	      With a negative integer, trailing	components of the hostname are
	      shown.

       %n     $USERNAME.

       %y     The line (tty) the user is logged	in on, without `/dev/' prefix.
	      This does	not treat `/dev/tty' names specially.

   Shell state
       %#     A	 `#'  if  the  shell is	running	with privileges, a `%' if not.
	      Equivalent to `%(!.#.%%)'.  The definition of `privileged',  for
	      these  purposes,	is  that either	the effective user ID is zero,
	      or, if POSIX.1e capabilities are supported, that	at  least  one
	      capability  is raised in either the Effective or Inheritable ca-
	      pability vectors.

       %?     The return status	of the last command executed just  before  the
	      prompt.

       %_     The  status  of the parser, i.e. the shell constructs (like `if'
	      and `for') that have been	started	on the command line. If	 given
	      an  integer  number  that	 many strings will be printed; zero or
	      negative or no integer means print as many as there  are.	  This
	      is most useful in	prompts	PS2 for	continuation lines and PS4 for
	      debugging	with the XTRACE	option;	in the	latter	case  it  will
	      also work	non-interactively.

       %^     The  status  of  the parser in reverse. This is the same as `%_'
	      other than the order of strings.	It is often used in RPS2.

       %d
       %/     Current working directory.  If an	integer	follows	 the  `%',  it
	      specifies	a number of trailing components	of the current working
	      directory	to show; zero means the	whole path.  A negative	 inte-
	      ger  specifies leading components, i.e. %-1d specifies the first
	      component.

       %~     As %d and	%/, but	if the current working directory  starts  with
	      $HOME,  that part	is replaced by a `~'. Furthermore, if it has a
	      named directory as its prefix, that part is replaced  by	a  `~'
	      followed by the name of the directory, but only if the result is
	      shorter than the full path; see Dynamic and Static named	direc-
	      tories in	zshexpn(1).

       %e     Evaluation depth of the current sourced file, shell function, or
	      eval.  This is incremented or decremented	every time  the	 value
	      of  %N  is  set  or  reverted to a previous value, respectively.
	      This is most useful for debugging	as part	of $PS4.

       %h
       %!     Current history event number.

       %i     The line number currently	being executed in the script,  sourced
	      file,  or	 shell	function given by %N.  This is most useful for
	      debugging	as part	of $PS4.

       %I     The line number currently	being executed in the file  %x.	  This
	      is similar to %i,	but the	line number is always a	line number in
	      the file where the code was defined, even	if the code is a shell
	      function.

       %j     The number of jobs.

       %L     The current value	of $SHLVL.

       %N     The name of the script, sourced file, or shell function that zsh
	      is currently executing, whichever	was started most recently.  If
	      there is none, this is equivalent	to the parameter $0.  An inte-
	      ger may follow the `%' to	specify	a number of trailing path com-
	      ponents  to  show; zero means the	full path.  A negative integer
	      specifies	leading	components.

       %x     The name of the file containing the source code currently	 being
	      executed.	 This behaves as %N except that	function and eval com-
	      mand names are not shown,	instead	the file where they  were  de-
	      fined.

       %c
       %.
       %C     Trailing component of the	current	working	directory.  An integer
	      may follow the `%' to get	more than one component.  Unless  `%C'
	      is used, tilde contraction is performed first.  These are	depre-
	      cated as %c and %C are equivalent	to %1~ and %1/,	 respectively,
	      while explicit positive integers have the	same effect as for the
	      latter two sequences.

   Date	and time
       %D     The date in yy-mm-dd format.

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

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

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

       %w     The date in day-dd format.

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

       %D{string}
	      string is	formatted using	 the  strftime	function.   See	 strf-
	      time(3)  for  more details.  Various zsh extensions provide num-
	      bers with	no leading zero	or space if the	 number	 is  a	single
	      digit:

	      %f     a day of the month
	      %K     the hour of the day on the	24-hour	clock
	      %L     the hour of the day on the	12-hour	clock

	      In  addition, if the system supports the POSIX gettimeofday sys-
	      tem call,	%. provides decimal fractions of a  second  since  the
	      epoch  with leading zeroes.  By default three decimal places are
	      provided,	but a number of	digits up to 6 may be given  following
	      the  %;  hence  %6.  outputs microseconds.  A typical example of
	      this is the format `%D{%H:%M:%S.%.}'.

	      The GNU extension	that a `-' between the % and the format	 char-
	      acter  causes  a leading zero or space to	be stripped is handled
	      directly by the shell for	the format characters d, f, H,	k,  l,
	      m,  M,  S	and y; any other format	characters are provided	to the
	      system's strftime(3) with	any leading `-'	present, so  the  han-
	      dling  is	 system	 dependent.  Further GNU (or other) extensions
	      are also passed to strftime(3) and may work if the  system  sup-
	      ports them.

   Visual effects
       %B (%b)
	      Start (stop) boldface mode.

       %E     Clear to end of line.

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

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

       %F (%f)
	      Start  (stop)  using a different foreground colour, if supported
	      by the terminal.	The colour may be specified two	 ways:	either
	      as  a  numeric  argument,	 as normal, or by a sequence in	braces
	      following	the %F,	for example %F{red}.  In the latter  case  the
	      values  allowed are as described for the fg zle_highlight	attri-
	      bute; see	Character Highlighting in zshzle(1).  This means  that
	      numeric colours are allowed in the second	format also.

       %K (%k)
	      Start (stop) using a different bacKground	colour.	 The syntax is
	      identical	to that	for %F and %f.

       %{...%}
	      Include a	string as  a  literal  escape  sequence.   The	string
	      within  the braces should	not change the cursor position.	 Brace
	      pairs can	nest.

	      A	positive numeric argument between the %	and the	{  is  treated
	      as described for %G below.

       %G     Within  a	 %{...%} sequence, include a `glitch': that is,	assume
	      that a single character width will be output.   This  is	useful
	      when  outputting	characters  that otherwise cannot be correctly
	      handled by the shell, such as the	 alternate  character  set  on
	      some  terminals.	 The  characters  in  question can be included
	      within a %{...%} sequence	together with the  appropriate	number
	      of  %G  sequences	to indicate the	correct	width.	An integer be-
	      tween the	`%' and	`G' indicates a	 character  width  other  than
	      one.   Hence  %{seq%2G%} outputs seq and assumes it takes	up the
	      width of two standard characters.

	      Multiple uses of %G accumulate in	the obvious fashion; the posi-
	      tion  of	the %G is unimportant.	Negative integers are not han-
	      dled.

	      Note that	when prompt truncation is in use it  is	 advisable  to
	      divide  up  output  into	single	characters within each %{...%}
	      group so that the	correct	truncation point can be	found.

CONDITIONAL SUBSTRINGS IN PROMPTS
       %v     The value	of the first element of	 the  psvar  array  parameter.
	      Following	 the `%' with an integer gives that element of the ar-
	      ray.  Negative integers count from the end of the	array.

       %(x.true-text.false-text)
	      Specifies	a ternary expression.  The character following	the  x
	      is  arbitrary;  the  same	character is used to separate the text
	      for the `true' result from that for the  `false'	result.	  This
	      separator	 may  not appear in the	true-text, except as part of a
	      %-escape sequence.  A `)'	may appear in the false-text as	 `%)'.
	      true-text	and false-text may both	contain	arbitrarily-nested es-
	      cape sequences, including	further	ternary	expressions.

	      The left parenthesis may be preceded or followed by  a  positive
	      integer  n,  which defaults to zero.  A negative integer will be
	      multiplied by -1,	except as noted	below for `l'.	The test char-
	      acter x may be any of the	following:

	      !	     True if the shell is running with privileges.
	      #	     True if the effective uid of the current process is n.
	      ?	     True if the exit status of	the last command was n.
	      _	     True if at	least n	shell constructs were started.
	      C
	      /	     True if the current absolute path has at least n elements
		     relative to the root directory, hence / is	counted	 as  0
		     elements.
	      c
	      .
	      ~	     True if the current path, with prefix replacement,	has at
		     least n elements relative to the root directory, hence  /
		     is	counted	as 0 elements.
	      D	     True if the month is equal	to n (January =	0).
	      d	     True if the day of	the month is equal to n.
	      e	     True if the evaluation depth is at	least n.
	      g	     True if the effective gid of the current process is n.
	      j	     True if the number	of jobs	is at least n.
	      L	     True if the SHLVL parameter is at least n.
	      l	     True  if  at least	n characters have already been printed
		     on	the current line.  When	n  is  negative,  true	if  at
		     least abs(n) characters remain before the opposite	margin
		     (thus the left margin for RPROMPT).
	      S	     True if the SECONDS parameter is at least n.
	      T	     True if the time in hours is equal	to n.
	      t	     True if the time in minutes is equal to n.
	      v	     True if the array psvar has at least n elements.
	      V	     True  if  element	n  of  the  array  psvar  is  set  and
		     non-empty.
	      w	     True if the day of	the week is equal to n (Sunday = 0).

       %<string<
       %>string>
       %[xstring]
	      Specifies	 truncation  behaviour for the remainder of the	prompt
	      string.	The  third,  deprecated,   form	  is   equivalent   to
	      `%xstringx',  i.e. x may be `<' or `>'.  The string will be dis-
	      played in	place of the truncated portion	of  any	 string;  note
	      this does	not undergo prompt expansion.

	      The numeric argument, which in the third form may	appear immedi-
	      ately after the `[', specifies the maximum permitted  length  of
	      the various strings that can be displayed	in the prompt.	In the
	      first two	forms, this numeric argument may be negative, in which
	      case  the	truncation length is determined	by subtracting the ab-
	      solute value of the numeric argument from	the number of  charac-
	      ter positions remaining on the current prompt line.  If this re-
	      sults in a zero or negative length, a length of 1	is  used.   In
	      other  words, a negative argument	arranges that after truncation
	      at least n characters remain before the right margin (left  mar-
	      gin for RPROMPT).

	      The  forms  with `<' truncate at the left	of the string, and the
	      forms with `>' truncate at the right of the string.   For	 exam-
	      ple,  if	the  current  directory	 is  `/home/pike',  the	prompt
	      `%8<..<%/' will expand to	`..e/pike'.  In	this string, the  ter-
	      minating	character (`<',	`>' or `]'), or	in fact	any character,
	      may be quoted by a preceding `\';	note when using	print -P, how-
	      ever, that this must be doubled as the string is also subject to
	      standard print processing, in addition to	 any  backslashes  re-
	      moved  by	 a  double quoted string:  the worst case is therefore
	      `print -P	"%<\\\\<<..."'.

	      If the string is longer than the specified truncation length, it
	      will appear in full, completely replacing	the truncated string.

	      The part of the prompt string to be truncated runs to the	end of
	      the string, or to	the end	of the next  enclosing	group  of  the
	      `%('  construct,	or  to	the next truncation encountered	at the
	      same grouping level (i.e.	truncations inside a  `%('  are	 sepa-
	      rate), which ever	comes first.  In particular, a truncation with
	      argument zero (e.g., `%<<') marks	the end	of the	range  of  the
	      string  to  be truncated while turning off truncation from there
	      on. For example, the prompt  `%10<...<%~%<<%#  '	will  print  a
	      truncated	representation of the current directory, followed by a
	      `%' or `#', followed by a	space.	Without	the `%<<',  those  two
	      characters  would	 be  included  in  the string to be truncated.
	      Note that	`%-0<<'	is not equivalent to `%<<' but specifies  that
	      the prompt is truncated at the right margin.

	      Truncation  applies  only	 within	 each  individual  line	of the
	      prompt, as delimited by embedded newlines	(if any).  If the  to-
	      tal length of any	line of	the prompt after truncation is greater
	      than the terminal	width, or if the part to be truncated contains
	      embedded	newlines,  truncation  behavior	 is  undefined and may
	      change   in   a	future	 version   of	 the	shell.	   Use
	      `%-n(l.true-text.false-text)' to remove parts of the prompt when
	      the available space is less than n.

ZSHEXPN(1)		    General Commands Manual		    ZSHEXPN(1)

NAME
       zshexpn - zsh expansion and substitution

DESCRIPTION
       The following types of expansions are performed in the indicated	 order
       in five steps:

       History Expansion
	      This is performed	only in	interactive shells.

       Alias Expansion
	      Aliases  are  expanded  immediately  before  the command line is
	      parsed as	explained under	Aliasing in zshmisc(1).

       Process Substitution
       Parameter Expansion
       Command Substitution
       Arithmetic Expansion
       Brace Expansion
	      These five are performed in one step in  left-to-right  fashion.
	      After  these expansions, all unquoted occurrences	of the charac-
	      ters `\',	`'' and	`"' are	removed.

       Filename	Expansion
	      If the SH_FILE_EXPANSION option is set, the order	 of  expansion
	      is  modified  for	 compatibility	with sh	and ksh.  In that case
	      filename expansion is performed immediately after	 alias	expan-
	      sion, preceding the set of five expansions mentioned above.

       Filename	Generation
	      This expansion, commonly referred	to as globbing,	is always done
	      last.

       The following sections explain the types	of expansion in	detail.

HISTORY	EXPANSION
       History expansion allows	you to use words from previous	command	 lines
       in  the	command	line you are typing.  This simplifies spelling correc-
       tions and the repetition	of complicated commands	or arguments.

       Immediately before execution, each command  is  saved  in  the  history
       list,  the  size	of which is controlled by the HISTSIZE parameter.  The
       one most	recent command is always retained in  any  case.   Each	 saved
       command in the history list is called a history event and is assigned a
       number, beginning with 1	(one) when the shell starts up.	  The  history
       number  that  you  may  see in your prompt (see EXPANSION OF PROMPT SE-
       QUENCES in zshmisc(1)) is the number that is to be assigned to the next
       command.

   Overview
       A  history  expansion  begins with the first character of the histchars
       parameter, which	is `!' by default, and may occur anywhere on the  com-
       mand line; history expansions do	not nest.  The `!' can be escaped with
       `\' or can be enclosed between a	pair of	single quotes ('') to suppress
       its  special meaning.  Double quotes will not work for this.  Following
       this history character is an optional event designator (see the section
       `Event  Designators') and then an optional word designator (the section
       `Word Designators'); if neither of these	 designators  is  present,  no
       history expansion occurs.

       Input  lines  containing	 history expansions are	echoed after being ex-
       panded, but before any other expansions take place and before the  com-
       mand  is	 executed.   It	 is this expanded form that is recorded	as the
       history event for later references.

       By default, a history reference with no event designator	refers to  the
       same  event as any preceding history reference on that command line; if
       it is the only history reference	in a command, it refers	to the	previ-
       ous  command.   However,	 if the	option CSH_JUNKIE_HISTORY is set, then
       every history reference with no event specification  always  refers  to
       the previous command.

       For  example,  `!' is the event designator for the previous command, so
       `!!:1' always refers to the first word of  the  previous	 command,  and
       `!!$'  always  refers  to  the last word	of the previous	command.  With
       CSH_JUNKIE_HISTORY set, then `!:1' and `!$' function in the same	manner
       as  `!!:1'  and `!!$', respectively.  Conversely, if CSH_JUNKIE_HISTORY
       is unset, then `!:1' and	`!$' refer to the first	and  last  words,  re-
       spectively,  of	the same event referenced by the nearest other history
       reference preceding them	on the current command line, or	to the	previ-
       ous command if there is no preceding reference.

       The  character  sequence	 `^foo^bar'  (where `^'	is actually the	second
       character of the	histchars parameter) repeats the last command, replac-
       ing  the	string foo with	bar.  More precisely, the sequence `^foo^bar^'
       is synonymous with `!!:s^foo^bar^', hence other modifiers (see the sec-
       tion   `Modifiers')   may   follow   the	 final	`^'.   In  particular,
       `^foo^bar^:G' performs a	global substitution.

       If the shell encounters the character sequence `!"' in the  input,  the
       history	mechanism  is temporarily disabled until the current list (see
       zshmisc(1)) is fully parsed.  The `!"' is removed from the  input,  and
       any subsequent `!' characters have no special significance.

       A  less convenient but more comprehensible form of command history sup-
       port is provided	by the fc builtin.

   Event Designators
       An event	designator is a	reference to a command-line entry in the  his-
       tory  list.   In	 the list below, remember that the initial `!' in each
       item may	be changed to another character	by setting the	histchars  pa-
       rameter.

       !      Start a history expansion, except	when followed by a blank, new-
	      line, `='	or `('.	 If followed immediately by a word  designator
	      (see  the	section	`Word Designators'), this forms	a history ref-
	      erence with no event designator (see the section `Overview').

       !!     Refer to the previous command.  By itself,  this	expansion  re-
	      peats the	previous command.

       !n     Refer to command-line n.

       !-n    Refer to the current command-line	minus n.

       !str   Refer to the most	recent command starting	with str.

       !?str[?]
	      Refer  to	 the most recent command containing str.  The trailing
	      `?' is necessary if this reference is to be followed by a	 modi-
	      fier  or	followed by any	text that is not to be considered part
	      of str.

       !#     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 be-
	      fore the one with	the `!#' reference.

       !{...} Insulate a history reference from	adjacent characters (if	neces-
	      sary).

   Word	Designators
       A word designator indicates which word or words of a given command line
       are to be included in a history reference.  A `:' usually separates the
       event  specification  from the word designator.	It may be omitted only
       if the word designator begins with a `^', `$', `*', `-' or  `%'.	  Word
       designators include:

       0      The first	input word (command).
       n      The nth argument.
       ^      The first	argument.  That	is, 1.
       $      The last argument.
       %      The word matched by (the most recent) ?str search.
       x-y    A	range of words;	x defaults to 0.
       *      All the arguments, or a null value if there are none.
       x*     Abbreviates `x-$'.
       x-     Like `x*'	but omitting word $.

       Note  that  a  `%' word designator works	only when used in one of `!%',
       `!:%' or	`!?str?:%', and	only when used after a !? expansion  (possibly
       in  an  earlier	command).  Anything else results in an error, although
       the error may not be the	most obvious one.

   Modifiers
       After the optional word designator, you can add a sequence  of  one  or
       more  of	 the following modifiers, each preceded	by a `:'.  These modi-
       fiers also work on the result of	filename generation and	parameter  ex-
       pansion,	except where noted.

       a      Turn  a  file  name into an absolute path:  prepends the current
	      directory, if necessary; remove `.' path	segments;  and	remove
	      `..'  path  segments  and	 the segments that immediately precede
	      them.

	      This transformation is agnostic about what is in the filesystem,
	      i.e.  is	on  the	logical, not the physical directory.  It takes
	      place in the same	manner as when changing	directories when  nei-
	      ther of the options CHASE_DOTS or	CHASE_LINKS is set.  For exam-
	      ple, `/before/here/../after'  is	always	transformed  to	 `/be-
	      fore/after', regardless of whether `/before/here'	exists or what
	      kind of object (dir, file, symlink, etc.)	it is.

       A      Turn a file name into an absolute	path as	the `a'	modifier does,
	      and  then	 pass the result through the realpath(3) library func-
	      tion to resolve symbolic links.

	      Note: on systems that do not have	a  realpath(3)	library	 func-
	      tion,  symbolic  links are not resolved, so on those systems `a'
	      and `A' are equivalent.

	      Note: foo:A and realpath(foo) are	different on some inputs.  For
	      realpath(foo) semantics, see the `P` modifier.

       c      Resolve  a  command  name	into an	absolute path by searching the
	      command path given by the	PATH variable.	This does not work for
	      commands	containing  directory parts.  Note also	that this does
	      not usually work as a glob qualifier unless a file of  the  same
	      name is found in the current directory.

       e      Remove  all but the part of the filename extension following the
	      `.'; see the definition of the filename  extension  in  the  de-
	      scription	 of the	r modifier below.  Note	that according to that
	      definition the result will be empty if the string	 ends  with  a
	      `.'.

       h      Remove  a	 trailing  pathname component, leaving the head.  This
	      works like `dirname'.

       l      Convert the words	to all lowercase.

       p      Print the	new command but	do not execute it.   Only  works  with
	      history expansion.

       P      Turn  a  file name into an absolute path,	like realpath(3).  The
	      resulting	path will be absolute, have neither `.'	nor `..'  com-
	      ponents,	and  refer  to	the  same directory entry as the input
	      filename.

	      Unlike realpath(3), non-existent trailing	components are permit-
	      ted and preserved.

       q      Quote  the  substituted  words,  escaping	further	substitutions.
	      Works with history expansion and parameter expansion, though for
	      parameters  it  is  only	useful	if the resulting text is to be
	      re-evaluated such	as by eval.

       Q      Remove one level of quotes from the substituted words.

       r      Remove a filename	extension leaving the root name.  Strings with
	      no  filename extension are not altered.  A filename extension is
	      a	`.' followed by	any number of characters (including zero) that
	      are  neither  `.'	 nor  `/'  and that continue to	the end	of the
	      string.  For example, the	extension of `foo.orig.c' is `.c', and
	      `dir.c/foo' has no extension.

       s/l/r[/]
	      Substitute r for l as described below.  The substitution is done
	      only for the first string	that matches l.	 For  arrays  and  for
	      filename	generation,  this applies to each word of the expanded
	      text.  See below for further notes on substitutions.

	      The forms	`gs/l/r' and `s/l/r/:G'	perform	 global	 substitution,
	      i.e. substitute every occurrence of r for	l.  Note that the g or
	      :G must appear in	exactly	the position shown.

	      See further notes	on this	form of	substitution below.

       &      Repeat the previous s substitution.  Like	s, may be preceded im-
	      mediately	 by a g.  In parameter expansion the & must appear in-
	      side braces, and in filename generation it must be quoted	with a
	      backslash.

       t      Remove  all leading pathname components, leaving the tail.  This
	      works like `basename'.

       u      Convert the words	to all uppercase.

       x      Like q, but break	into words at whitespace.  Does	not work  with
	      parameter	expansion.

       The  s/l/r/  substitution  works	 as follows.  By default the left-hand
       side of substitutions are not patterns,	but  character	strings.   Any
       character  can  be  used	as the delimiter in place of `/'.  A backslash
       quotes  the  delimiter  character.    The   character   `&',   in   the
       right-hand-side	r,  is replaced	by the text from the left-hand-side l.
       The `&' can be quoted with a backslash.	A null	l  uses	 the  previous
       string  either from the previous	l or from the contextual scan string s
       from `!?s'.  You	can omit the rightmost delimiter if a newline  immedi-
       ately  follows  r; the rightmost	`?' in a context scan can similarly be
       omitted.	 Note the same record of the last l and	r is maintained	across
       all forms of expansion.

       Note that if a `&' is used within glob qualifiers an extra backslash is
       needed as a & is	a special character in this case.

       Also note that the order	of expansions affects the interpretation of  l
       and r.  When used in a history expansion, which occurs before any other
       expansions, l and r are treated as literal strings (except as explained
       for  HIST_SUBST_PATTERN	below).	 When used in parameter	expansion, the
       replacement of r	into the parameter's value is done first, and then any
       additional process, parameter, command, arithmetic, or brace references
       are applied, which may evaluate those substitutions and expansions more
       than once if l appears more than	once in	the starting value.  When used
       in a glob qualifier, any	substitutions or expansions are	performed once
       at  the	time  the qualifier is parsed, even before the `:s' expression
       itself is divided into l	and r sides.

       If the option HIST_SUBST_PATTERN	is set,	l is treated as	a  pattern  of
       the  usual  form	 described  in	the section FILENAME GENERATION	below.
       This can	be used	in all the places where	modifiers are available; note,
       however,	that in	globbing qualifiers parameter substitution has already
       taken place, so parameters in the replacement string should  be	quoted
       to  ensure  they	are replaced at	the correct time.  Note	also that com-
       plicated	patterns used in globbing qualifiers  may  need	 the  extended
       glob  qualifier notation	(#q:s/.../.../)	in order for the shell to rec-
       ognize the expression as	a glob qualifier.  Further, note that bad pat-
       terns  in the substitution are not subject to the NO_BAD_PATTERN	option
       so will cause an	error.

       When HIST_SUBST_PATTERN is set, l may start with	a # to	indicate  that
       the  pattern  must  match at the	start of the string to be substituted,
       and a % may appear at the start or after	an # to	indicate that the pat-
       tern must match at the end of the string	to be substituted.  The	% or #
       may be quoted with two backslashes.

       For example, the	following piece	of filename generation code  with  the
       EXTENDED_GLOB option:

	      print *.c(#q:s/#%(#b)s(*).c/'S${match[1]}.C'/)

       takes  the  expansion  of  *.c  and  applies the	glob qualifiers	in the
       (#q...) expression, which consists of a substitution modifier  anchored
       to  the	start and end of each word (#%).  This turns on	backreferences
       ((#b)), so that the parenthesised subexpression is available in the re-
       placement  string  as ${match[1]}.  The replacement string is quoted so
       that the	parameter is not substituted before the	start of filename gen-
       eration.

       The  following  f, F, w and W modifiers work only with parameter	expan-
       sion and	filename generation.  They are listed here to provide a	single
       point of	reference for all modifiers.

       f      Repeats the immediately (without a colon)	following modifier un-
	      til the resulting	word doesn't change any	more.

       F:expr:
	      Like f, but repeats only n times if the expression  expr	evalu-
	      ates  to	n.   Any  character can	be used	instead	of the `:'; if
	      `(', `[',	or `{' is used as the opening delimiter,  the  closing
	      delimiter	should be ')', `]', or `}', respectively.

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

       W:sep: Like w but words are considered to be the	parts  of  the	string
	      that  are	separated by sep. Any character	can be used instead of
	      the `:'; opening parentheses are handled specially, see above.

PROCESS	SUBSTITUTION
       Each part  of  a	 command  argument  that  takes	 the  form  `<(list)',
       `>(list)' or `=(list)' is subject to process substitution.  The expres-
       sion may	be preceded or followed	by other strings except	that, to  pre-
       vent  clashes  with  commonly  occurring	strings	and patterns, the last
       form must occur at the start of a command argument, and the  forms  are
       only  expanded  when  first  parsing  command  or assignment arguments.
       Process substitutions may be used following redirection	operators;  in
       this case, the substitution must	appear with no trailing	string.

       Note  that  `<<(list)'  is not a	special	syntax;	it is equivalent to `<
       <(list)', redirecting standard input from the result of process substi-
       tution.	 Hence	all  the  following documentation applies.  The	second
       form (with the space) is	recommended for	clarity.

       In the case of the < or > forms,	the shell runs the commands in list as
       a  subprocess of	the job	executing the shell command line.  If the sys-
       tem supports the	/dev/fd	mechanism, the command argument	is the name of
       the  device  file corresponding to a file descriptor; otherwise,	if the
       system supports named pipes (FIFOs), the	command	 argument  will	 be  a
       named  pipe.   If the form with > is selected then writing on this spe-
       cial file will provide input for	list.  If < is	used,  then  the  file
       passed  as  an  argument	 will  be  connected to	the output of the list
       process.	 For example,

	      paste <(cut -f1 file1) <(cut -f3 file2) |
	      tee >(process1) >(process2) >/dev/null

       cuts fields 1 and 3 from	the files file1	and file2 respectively,	pastes
       the  results  together,	and  sends  it	to  the	processes process1 and
       process2.

       If =(...) is used instead of <(...), then the file passed as  an	 argu-
       ment  will be the name of a temporary file containing the output	of the
       list process.  This may be used instead of the <	 form  for  a  program
       that expects to lseek (see lseek(2)) on the input file.

       There is	an optimisation	for substitutions of the form =(<<<arg), where
       arg is a	single-word argument to	the here-string	redirection <<<.  This
       form produces a file name containing the	value of arg after any substi-
       tutions have been performed.  This is handled entirely within the  cur-
       rent  shell.   This  is	effectively  the  reverse  of the special form
       $(<arg) which treats arg	as a file name and replaces it with the	file's
       contents.

       The = form is useful as both the	/dev/fd	and the	named pipe implementa-
       tion of <(...) have drawbacks.  In the former case, some	programmes may
       automatically  close  the  file descriptor in question before examining
       the file	on the command line, particularly if this is necessary for se-
       curity  reasons	such  as when the programme is running setuid.	In the
       second case, if the programme does not actually open the	file, the sub-
       shell  attempting  to read from or write	to the pipe will (in a typical
       implementation, different operating systems may have  different	behav-
       iour)  block for	ever and have to be killed explicitly.	In both	cases,
       the shell actually supplies the information using a pipe, so that  pro-
       grammes that expect to lseek (see lseek(2)) on the file will not	work.

       Also  note  that	 the  previous example can be more compactly and effi-
       ciently written (provided the MULTIOS option is set) as:

	      paste <(cut -f1 file1) <(cut -f3 file2) \
	      >	>(process1) > >(process2)

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

       There  is  an additional	problem	with >(process); when this is attached
       to an external command, the parent shell	does not wait for  process  to
       finish  and  hence  an immediately following command cannot rely	on the
       results being complete.	The problem and	solution are the same  as  de-
       scribed	in  the	 section MULTIOS in zshmisc(1).	 Hence in a simplified
       version of the example above:

	      paste <(cut -f1 file1) <(cut -f3 file2) >	>(process)

       (note that no MULTIOS are involved), process will be run	asynchronously
       as far as the parent shell is concerned.	 The workaround	is:

	      {	paste <(cut -f1	file1) <(cut -f3 file2)	} > >(process)

       The  extra  processes here are spawned from the parent shell which will
       wait for	their completion.

       Another problem arises any time a job with a substitution that requires
       a  temporary  file  is  disowned	by the shell, including	the case where
       `&!' or `&|' appears at the end of a command containing a substitution.
       In  that	case the temporary file	will not be cleaned up as the shell no
       longer has any memory of	the job.  A workaround is to use  a  subshell,
       for example,

	      (mycmd =(myoutput)) &!

       as  the forked subshell will wait for the command to finish then	remove
       the temporary file.

       A general workaround to ensure a	process	substitution  endures  for  an
       appropriate length of time is to	pass it	as a parameter to an anonymous
       shell function (a piece of shell	code  that  is	run  immediately  with
       function	scope).	 For example, this code:

	      () {
		 print File $1:
		 cat $1
	      }	=(print	This be	the verse)

       outputs something resembling the	following

	      File /tmp/zsh6nU0kS:
	      This be the verse

       The  temporary file created by the process substitution will be deleted
       when the	function exits.

PARAMETER EXPANSION
       The character `$' is used to introduce parameter	expansions.  See  zsh-
       param(1)	for a description of parameters, including arrays, associative
       arrays, and subscript notation to access	individual array elements.

       Note in particular the fact that	words of unquoted parameters  are  not
       automatically  split  on	 whitespace unless the option SH_WORD_SPLIT is
       set; see	references to this option below	for more details.  This	is  an
       important difference from other shells.

       In  the	expansions discussed below that	require	a pattern, the form of
       the pattern is the same as that used for	filename generation;  see  the
       section	`Filename  Generation'.	  Note that these patterns, along with
       the replacement text of any substitutions, are  themselves  subject  to
       parameter  expansion,  command  substitution, and arithmetic expansion.
       In addition to the following operations,	the colon modifiers  described
       in  the	section	 `Modifiers' in	the section `History Expansion'	can be
       applied:	 for example, ${i:s/foo/bar/} performs string substitution  on
       the expansion of	parameter $i.

       In  the	following descriptions,	`word' refers to a single word substi-
       tuted on	the command line, not  necessarily  a  space  delimited	 word.
       With default options, after the assignments:

	      array=("first word" "second word")
	      scalar="only word"

       then  $array substitutes	two words, `first word'	and `second word', and
       $scalar substitutes a single word `only word'.  This may	be modified by
       explicit	 or implicit word-splitting, however.  The full	rules are com-
       plicated	and are	noted at the end.

       ${name}
	      The value, if any, of the	parameter name	is  substituted.   The
	      braces are required if the expansion is to be followed by	a let-
	      ter, digit, or underscore	that is	not to be interpreted as  part
	      of  name.	  In  addition,	more complicated forms of substitution
	      usually require the braces to be present;	exceptions, which only
	      apply  if	 the  option  KSH_ARRAYS is not	set, are a single sub-
	      script or	any colon modifiers appearing after the	name,  or  any
	      of the characters	`^', `=', `~', `#' or `+' appearing before the
	      name, all	of which work with or without braces.

	      If name is an array parameter, and the KSH_ARRAYS	option is  not
	      set,  then the value of each element of name is substituted, one
	      element per word.	 Otherwise, the	expansion results in one  word
	      only;  with  KSH_ARRAYS,	this is	the first element of an	array.
	      No  field	 splitting  is	done  on   the	 result	  unless   the
	      SH_WORD_SPLIT   option  is  set.	 See  also  the	 flags	=  and
	      s:string:.

       ${+name}
	      If name is the name of a set parameter `1' is substituted,  oth-
	      erwise `0' is substituted.

       ${name-word}
       ${name:-word}
	      If  name is set, or in the second	form is	non-null, then substi-
	      tute its value; otherwise	substitute word.  In the  second  form
	      name may be omitted, in which case word is always	substituted.

       ${name+word}
       ${name:+word}
	      If  name is set, or in the second	form is	non-null, then substi-
	      tute word; otherwise substitute nothing.

       ${name=word}
       ${name:=word}
       ${name::=word}
	      In the first form, if name is unset then set it to word; in  the
	      second  form,  if	name is	unset or null then set it to word; and
	      in the third form, unconditionally set name  to  word.   In  all
	      forms, the value of the parameter	is then	substituted.

       ${name?word}
       ${name:?word}
	      In the first form, if name is set, or in the second form if name
	      is both set and non-null,	then substitute	its value;  otherwise,
	      print  word and exit from	the shell.  Interactive	shells instead
	      return to	the prompt.  If	word is	omitted, then a	standard  mes-
	      sage is printed.

       In  any of the above expressions	that test a variable and substitute an
       alternate word, note that you can use standard  shell  quoting  in  the
       word   value   to  selectively  override	 the  splitting	 done  by  the
       SH_WORD_SPLIT option and	the = flag, but	not splitting by the s:string:
       flag.

       In  the	following expressions, when name is an array and the substitu-
       tion is not quoted, or if the `(@)' flag	or the name[@] syntax is used,
       matching	and replacement	is performed on	each array element separately.

       ${name#pattern}
       ${name##pattern}
	      If  the pattern matches the beginning of the value of name, then
	      substitute the value of name with	the matched  portion  deleted;
	      otherwise,  just	substitute  the	 value	of name.  In the first
	      form, the	smallest matching pattern is preferred;	in the	second
	      form, the	largest	matching pattern is preferred.

       ${name%pattern}
       ${name%%pattern}
	      If  the  pattern matches the end of the value of name, then sub-
	      stitute the value	of name	with the matched portion deleted; oth-
	      erwise,  just  substitute	the value of name.  In the first form,
	      the smallest matching pattern is preferred; in the second	 form,
	      the largest matching pattern is preferred.

       ${name:#pattern}
	      If  the  pattern	matches	the value of name, then	substitute the
	      empty string; otherwise, just substitute the value of name.   If
	      name  is	an  array the matching array elements are removed (use
	      the `(M)'	flag to	remove the non-matched elements).

       ${name:|arrayname}
	      If arrayname is the name (N.B., not contents) of an array	 vari-
	      able,  then any elements contained in arrayname are removed from
	      the substitution of name.	 If the	substitution is	scalar,	either
	      because  name  is	a scalar variable or the expression is quoted,
	      the elements of arrayname	are instead tested against the	entire
	      expression.

       ${name:*arrayname}
	      Similar  to  the	preceding  substitution,  but  in the opposite
	      sense, so	that entries present in	both the original substitution
	      and as elements of arrayname are retained	and others removed.

       ${name:^arrayname}
       ${name:^^arrayname}
	      Zips  two	arrays,	such that the output array is twice as long as
	      the shortest (longest for	`:^^') of name and arrayname, with the
	      elements	alternatingly being picked from	them. For `:^',	if one
	      of the input arrays is longer, the output	will stop when the end
	      of the shorter array is reached.	Thus,

		     a=(1 2 3 4); b=(a b); print ${a:^b}

	      will  output  `1	a 2 b'.	 For `:^^', then the input is repeated
	      until all	of the longer array has	been used  up  and  the	 above
	      will output `1 a 2 b 3 a 4 b'.

	      Either  or  both inputs may be a scalar, they will be treated as
	      an array of length 1 with	the scalar as the only element.	If ei-
	      ther array is empty, the other array is output with no extra el-
	      ements inserted.

	      Currently	the following code will	output `a b' and  `1'  as  two
	      separate	elements,  which  can  be unexpected. The second print
	      provides a workaround which should continue to work if  this  is
	      changed.

		     a=(a b); b=(1 2); print -l	"${a:^b}"; print -l "${${a:^b}}"

       ${name:offset}
       ${name:offset:length}
	      This  syntax  gives effects similar to parameter subscripting in
	      the form $name[start,end], but is	compatible with	other  shells;
	      note  that  both	offset	and length are interpreted differently
	      from the components of a subscript.

	      If offset	is non-negative, then if the variable name is a	scalar
	      substitute  the  contents	 starting  offset  characters from the
	      first character of the string, and if name is an	array  substi-
	      tute  elements  starting offset elements from the	first element.
	      If length	is given, substitute that many characters or elements,
	      otherwise	the entire rest	of the scalar or array.

	      A	positive offset	is always treated as the offset	of a character
	      or element in name from the first	character or  element  of  the
	      array  (this  is	different from native zsh subscript notation).
	      Hence 0 refers to	the first character or element	regardless  of
	      the setting of the option	KSH_ARRAYS.

	      A	negative offset	counts backwards from the end of the scalar or
	      array, so	that -1	corresponds to the last	character or  element,
	      and so on.

	      When positive, length counts from	the offset position toward the
	      end of the scalar	or array.  When	negative, length  counts  back
	      from  the	 end.  If this results in a position smaller than off-
	      set, a diagnostic	is printed and nothing is substituted.

	      The option MULTIBYTE is obeyed, i.e. the offset and length count
	      multibyte	characters where appropriate.

	      offset and length	undergo	the same set of	shell substitutions as
	      for scalar assignment; in	addition, they	are  then  subject  to
	      arithmetic evaluation.  Hence, for example

		     print ${foo:3}
		     print ${foo: 1 + 2}
		     print ${foo:$(( 1 + 2))}
		     print ${foo:$(echo	1 + 2)}

	      all  have	the same effect, extracting the	string starting	at the
	      fourth character of $foo if the substitution would otherwise re-
	      turn  a  scalar,	or the array starting at the fourth element if
	      $foo would return	an array.  Note	that with the  option  KSH_AR-
	      RAYS  $foo always	returns	a scalar (regardless of	the use	of the
	      offset syntax) and a form	such as	${foo[*]:3} is required	to ex-
	      tract elements of	an array named foo.

	      If  offset  is  negative,	the - may not appear immediately after
	      the : as this indicates the ${name:-word}	form of	 substitution.
	      Instead,	a  space  may  be inserted before the -.  Furthermore,
	      neither offset nor length	may begin with an alphabetic character
	      or  & as these are used to indicate history-style	modifiers.  To
	      substitute a value from a	variable, the recommended approach  is
	      to  precede it with a $ as this signifies	the intention (parame-
	      ter substitution can easily be rendered unreadable); however, as
	      arithmetic  substitution	is  performed,	the  expression	${var:
	      offs} does work, retrieving the offset from $offs.

	      For further compatibility	with other shells there	is  a  special
	      case  for	 array offset 0.  This usually accesses	the first ele-
	      ment of the array.  However, if the substitution refers  to  the
	      positional parameter array, e.g. $@ or $*, then offset 0 instead
	      refers to	$0, offset 1 refers to $1, and so on.  In other	words,
	      the  positional  parameter  array	 is  effectively  extended  by
	      prepending $0.  Hence ${*:0:1} substitutes $0 and	${*:1:1}  sub-
	      stitutes $1.

       ${name/pattern/repl}
       ${name//pattern/repl}
       ${name:/pattern/repl}
	      Replace  the  longest possible match of pattern in the expansion
	      of parameter name	by string repl.	 The first form	replaces  just
	      the  first  occurrence, the second form all occurrences, and the
	      third form replaces only if pattern matches the  entire  string.
	      Both pattern and repl are	subject	to double-quoted substitution,
	      so that expressions like ${name/$opat/$npat} will	work, but obey
	      the  usual rule that pattern characters in $opat are not treated
	      specially	unless either the option GLOB_SUBST is set,  or	 $opat
	      is instead substituted as	${~opat}.

	      The pattern may begin with a `#',	in which case the pattern must
	      match at the start of the	string,	or `%',	in which case it  must
	      match  at	 the end of the	string,	or `#%'	in which case the pat-
	      tern must	match the entire string.  The repl  may	 be  an	 empty
	      string,  in  which  case	the final `/' may also be omitted.  To
	      quote the	final `/' in other cases it should be  preceded	 by  a
	      single backslash;	this is	not necessary if the `/' occurs	inside
	      a	substituted parameter.	Note also that the `#',	 `%'  and  `#%
	      are  not	active	if  they occur inside a	substituted parameter,
	      even at the start.

	      If, after	quoting	rules apply, ${name} expands to	an array,  the
	      replacements  act	 on  each element individually.	 Note also the
	      effect of	the I and S parameter expansion	flags below;  however,
	      the flags	M, R, B, E and N are not useful.

	      For example,

		     foo="twinkle twinkle little star" sub="t*e" rep="spy"
		     print ${foo//${~sub}/$rep}
		     print ${(S)foo//${~sub}/$rep}

	      Here, the	`~' ensures that the text of $sub is treated as	a pat-
	      tern rather than a plain string.	In the first case, the longest
	      match for	t*e is substituted and the result is `spy star', while
	      in the second case, the shortest matches are taken and  the  re-
	      sult is `spy spy lispy star'.

       ${#spec}
	      If spec is one of	the above substitutions, substitute the	length
	      in characters of the result instead of the  result  itself.   If
	      spec  is	an array expression, substitute	the number of elements
	      of the result.  This has the side-effect that joining is skipped
	      even  in quoted forms, which may affect other sub-expressions in
	      spec.  Note that `^', `=', and `~', below, must  appear  to  the
	      left of `#' when these forms are combined.

	      If the option POSIX_IDENTIFIERS is not set, and spec is a	simple
	      name, then the braces are	optional; this is true even  for  spe-
	      cial  parameters	so  e.g.  $#-  and  $#*	take the length	of the
	      string $-	and the	array $* respectively.	 If  POSIX_IDENTIFIERS
	      is set, then braces are required for the # to be treated in this
	      fashion.

       ${^spec}
	      Turn on the RC_EXPAND_PARAM option for the evaluation  of	 spec;
	      if  the  `^'  is doubled,	turn it	off.  When this	option is set,
	      array expansions of the form foo${xx}bar,	where the parameter xx
	      is  set  to  (a  b  c),  are  substituted	 with `fooabar foobbar
	      foocbar' instead of the default `fooa b  cbar'.	Note  that  an
	      empty array will therefore cause all arguments to	be removed.

	      Internally, each such expansion is converted into	the equivalent
	      list   for   brace    expansion.	   E.g.,    ${^var}    becomes
	      {$var[1],$var[2],...}, and is processed as described in the sec-
	      tion `Brace Expansion' below.  If	word splitting is also in  ef-
	      fect the $var[N] may themselves be split into different list el-
	      ements.

       ${=spec}
	      Perform word splitting using the rules for SH_WORD_SPLIT	during
	      the  evaluation of spec, but regardless of whether the parameter
	      appears in double	quotes;	if the `=' is doubled,	turn  it  off.
	      This forces parameter expansions to be split into	separate words
	      before substitution, using IFS as	a delimiter.  This is done  by
	      default in most other shells.

	      Note  that  splitting is applied to word in the assignment forms
	      of spec before the assignment to name is	performed.   This  af-
	      fects the	result of array	assignments with the A flag.

       ${~spec}
	      Turn on the GLOB_SUBST option for	the evaluation of spec;	if the
	      `~' is doubled, turn it off.   When  this	 option	 is  set,  the
	      string  resulting	 from  the  expansion will be interpreted as a
	      pattern anywhere that is possible, such as in filename expansion
	      and  filename  generation	and pattern-matching contexts like the
	      right hand side of the `=' and `!=' operators in conditions.

	      In nested	substitutions, note that the effect of the  ~  applies
	      to the result of the current level of substitution.  A surround-
	      ing pattern operation on the result may cancel it.   Hence,  for
	      example,	if  the	 parameter foo is set to *, ${~foo//\*/*.c} is
	      substituted by the pattern *.c, which may	be expanded  by	 file-
	      name  generation,	 but  ${${~foo}//\*/*.c}  substitutes  to  the
	      string *.c, which	will not be further expanded.

       If a ${...} type	parameter expression or	a $(...) type command  substi-
       tution is used in place of name above, it is expanded first and the re-
       sult is used as if it were the value of name.  Thus it is  possible  to
       perform	nested	operations:  ${${foo#head}%tail} substitutes the value
       of $foo with both `head'	and `tail' deleted.  The form with  $(...)  is
       often  useful in	combination with the flags described next; see the ex-
       amples below.  Each name	or nested ${...} in a parameter	expansion  may
       also be followed	by a subscript expression as described in Array	Param-
       eters in	zshparam(1).

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

   Parameter Expansion Flags
       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.  In cases	where repeating	a flag is meaningful, the rep-
       etitions	need not be consecutive; for example, `(q%q%q)'	means the same
       thing  as  the  more  readable `(%%qqq)'.  The following	flags are sup-
       ported:

       #      Evaluate the resulting words as numeric expressions  and	output
	      the  characters  corresponding  to  the resulting	integer.  Note
	      that this	form is	entirely distinct from use of  the  #  without
	      parentheses.

	      If  the  MULTIBYTE  option is set	and the	number is greater than
	      127 (i.e.	not an ASCII character)	it is  treated	as  a  Unicode
	      character.

       %      Expand  all  % escapes in	the resulting words in the same	way as
	      in prompts (see EXPANSION	OF PROMPT SEQUENCES in zshmisc(1)). If
	      this  flag  is given twice, full prompt expansion	is done	on the
	      resulting	words, depending on the	setting	of the PROMPT_PERCENT,
	      PROMPT_SUBST and PROMPT_BANG options.

       @      In  double  quotes,  array elements are put into separate	words.
	      E.g.,  `"${(@)foo}"'  is	 equivalent   to   `"${foo[@]}"'   and
	      `"${(@)foo[1,2]}"'  is  the same as `"$foo[1]" "$foo[2]"'.  This
	      is distinct from field splitting by the f, s or z	 flags,	 which
	      still applies within each	array element.

       A      Create  an  array	 parameter with	`${...=...}', `${...:=...}' or
	      `${...::=...}'.  If this flag is repeated	(as in	`AA'),	create
	      an associative array parameter.  Assignment is made before sort-
	      ing or padding; if field splitting is active, the	word  part  is
	      split  before  assignment.   The	name part may be a subscripted
	      range for	ordinary arrays; the word part must be converted to an
	      array, for example by using `${(AA)=name=...}' to	activate field
	      splitting, when creating an associative array.

       a      Sort in array index order; when combined with `O'	 sort  in  re-
	      verse  array index order.	 Note that `a' is therefore equivalent
	      to the default but `Oa' is useful	for obtaining an array's  ele-
	      ments in reverse order.

       b      Quote  with backslashes only characters that are special to pat-
	      tern matching. This is useful when the contents of the  variable
	      are to be	tested using GLOB_SUBST, including the ${~...} switch.

	      Quoting  using  one  of  the q family of flags does not work for
	      this purpose since quotes	 are  not  stripped  from  non-pattern
	      characters by GLOB_SUBST.	 In other words,

		     pattern=${(q)str}
		     [[	$str = ${~pattern} ]]

	      works if $str is `a*b' but not if	it is `a b', whereas

		     pattern=${(b)str}
		     [[	$str = ${~pattern} ]]

	      is always	true for any possible value of $str.

       c      With ${#name}, count the total number of characters in an	array,
	      as if the	elements were concatenated with	spaces	between	 them.
	      This  is not a true join of the array, so	other expressions used
	      with this	flag may have an effect	on the elements	of  the	 array
	      before it	is counted.

       C      Capitalize  the resulting	words.	`Words'	in this	case refers to
	      sequences	of alphanumeric	characters separated  by  non-alphanu-
	      merics, not to words that	result from field splitting.

       D      Assume  the string or array elements contain directories and at-
	      tempt to substitute the leading part of these by names.  The re-
	      mainder of the path (the whole of	it if the leading part was not
	      substituted) is then quoted so that the whole string can be used
	      as  a  shell argument.  This is the reverse of `~' substitution:
	      see the section FILENAME EXPANSION below.

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

       f      Split the	result of the expansion	at newlines. This is a	short-
	      hand for `ps:\n:'.

       F      Join  the	words of arrays	together using newline as a separator.
	      This is a	shorthand for `pj:\n:'.

       g:opts:
	      Process escape sequences like the	echo builtin when  no  options
	      are  given (g::).	 With the o option, octal escapes don't	take a
	      leading zero.  With the c	option,	sequences like `^X'  are  also
	      processed.   With	the e option, processes	`\M-t' and similar se-
	      quences like the print builtin.  With both of the	o  and	e  op-
	      tions,  behaves  like  the  print	builtin	except that in none of
	      these modes is `\c' interpreted.

       i      Sort case-insensitively.	May be combined	with `n' or `O'.

       k      If name refers to	an associative array, substitute the keys (el-
	      ement  names) rather than	the values of the elements.  Used with
	      subscripts (including ordinary arrays), force indices or keys to
	      be  substituted  even  if	 the  subscript	form refers to values.
	      However, this flag may not be combined with subscript ranges.

       L      Convert all letters in the result	to lower case.

       n      Sort decimal integers numerically; if the	first differing	 char-
	      acters  of  two test strings are not digits, sorting is lexical.
	      Integers with more initial zeroes	are sorted before  those  with
	      fewer  or	 none.	 Hence	the  array `foo1 foo02 foo2 foo3 foo20
	      foo23' is	sorted into the	order shown.  May be combined with `i'
	      or `O'.

       o      Sort  the	resulting words	in ascending order; if this appears on
	      its own the sorting is lexical and  case-sensitive  (unless  the
	      locale renders it	case-insensitive).  Sorting in ascending order
	      is the default for other forms of	sorting, so this is ignored if
	      combined with `a', `i' or	`n'.

       O      Sort  the	 resulting words in descending order; `O' without `a',
	      `i' or `n' sorts in reverse lexical order.  May be combined with
	      `a', `i' or `n' to reverse the order of sorting.

       P      This forces the value of the parameter name to be	interpreted as
	      a	further	parameter name,	whose value will be used where	appro-
	      priate.	Note  that flags set with one of the typeset family of
	      commands (in particular case transformations) are	not applied to
	      the value	of name	used in	this fashion.

	      If used with a nested parameter or command substitution, the re-
	      sult of that will	be taken as a parameter	name in	the same  way.
	      For  example,  if	 you have `foo=bar' and	`bar=baz', the strings
	      ${(P)foo}, ${(P)${foo}}, and ${(P)$(echo bar)} will be  expanded
	      to `baz'.

	      Likewise,	if the reference is itself nested, the expression with
	      the flag is treated as if	it were	directly replaced by  the  pa-
	      rameter  name.   It is an	error if this nested substitution pro-
	      duces an array  with  more  than	one  word.   For  example,  if
	      `name=assoc'  where the parameter	assoc is an associative	array,
	      then `${${(P)name}[elt]}'	refers to the element of the  associa-
	      tive subscripted `elt'.

       q      Quote  characters	that are special to the	shell in the resulting
	      words with backslashes; unprintable or  invalid  characters  are
	      quoted  using  the  $'\NNN'  form, with separate quotes for each
	      octet.

	      If this flag is given twice, the resulting words are  quoted  in
	      single  quotes  and  if  it  is given three times, the words are
	      quoted in	double quotes; in these	forms no special  handling  of
	      unprintable  or invalid characters is attempted.	If the flag is
	      given four times,	the words are quoted in	single quotes preceded
	      by  a  $.	 Note that in all three	of these forms quoting is done
	      unconditionally, even if this does not change the	 way  the  re-
	      sulting string would be interpreted by the shell.

	      If a q- is given (only a single q	may appear), a minimal form of
	      single quoting is	used that only quotes the string if needed  to
	      protect  special characters.  Typically this form	gives the most
	      readable output.

	      If a q+ is given,	an extended form of  minmal  quoting  is  used
	      that  causes unprintable characters to be	rendered using $'...'.
	      This quoting is similar to that used by the output of values  by
	      the typeset family of commands.

       Q      Remove one level of quotes from the resulting words.

       t      Use  a  string  describing  the  type of the parameter where the
	      value of the parameter would usually appear.  This  string  con-
	      sists  of	keywords separated by hyphens (`-'). The first keyword
	      in the string  describes	the  main  type,  it  can  be  one  of
	      `scalar',	 `array',  `integer',  `float'	or  `association'. The
	      other keywords describe the type in more detail:

	      local  for local parameters

	      left   for left justified	parameters

	      right_blanks
		     for right justified parameters with leading blanks

	      right_zeros
		     for right justified parameters with leading zeros

	      lower  for parameters whose value	is converted to	all lower case
		     when it is	expanded

	      upper  for parameters whose value	is converted to	all upper case
		     when it is	expanded

	      readonly
		     for readonly parameters

	      tag    for tagged	parameters

	      export for exported parameters

	      unique for arrays	which keep only	the first occurrence of	dupli-
		     cated values

	      hide   for parameters with the `hide' flag

	      hideval
		     for parameters with the `hideval' flag

	      special
		     for special parameters defined by the shell

       u      Expand only the first occurrence of each unique word.

       U      Convert all letters in the result	to upper case.

       v      Used  with k, substitute (as two consecutive words) both the key
	      and the value of each associative	array element.	Used with sub-
	      scripts,	force  values  to be substituted even if the subscript
	      form refers to indices or	keys.

       V      Make any special characters in the resulting words visible.

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

       W      Similar  to  w  with the difference that empty words between re-
	      peated delimiters	are also counted.

       X      With this	flag, parsing errors occurring with the	 Q,  e	and  #
	      flags  or	 the  pattern matching forms such as `${name#pattern}'
	      are reported.  Without the flag, errors are silently ignored.

       z      Split the	result of the expansion	into words using shell parsing
	      to  find	the words, i.e.	taking into account any	quoting	in the
	      value.  Comments are  not	 treated  specially  but  as  ordinary
	      strings, similar to interactive shells with the INTERACTIVE_COM-
	      MENTS option unset (however, see the Z flag  below  for  related
	      options)

	      Note  that  this	is  done  very late, even later	than the `(s)'
	      flag. So to access single	words in the result use	nested	expan-
	      sions as in `${${(z)foo}[2]}'. Likewise, to remove the quotes in
	      the resulting words use `${(Q)${(z)foo}}'.

       0      Split the	result of the expansion	on  null  bytes.   This	 is  a
	      shorthand	for `ps:\0:'.

       The following flags (except p) are followed by one or more arguments as
       shown.  Any character, or the matching pairs `(...)', `{...}', `[...]',
       or  `<...>',  may  be  used in place of a colon as delimiters, but note
       that when a flag	takes more than	one argument, a	matched	pair of	delim-
       iters must surround each	argument.

       p      Recognize	 the  same  escape  sequences  as the print builtin in
	      string arguments to any of the flags described below that	follow
	      this argument.

	      Alternatively,  with  this option	string arguments may be	in the
	      form $var	in which case the value	of  the	 variable  is  substi-
	      tuted.   Note  this form is strict; the string argument does not
	      undergo general parameter	expansion.

	      For example,

		     sep=:
		     val=a:b:c
		     print ${(ps.$sep.)val}

	      splits the variable on a :.

       ~      Strings inserted into the	expansion by any of  the  flags	 below
	      are to be	treated	as patterns.  This applies to the string argu-
	      ments of flags that follow ~ within the same set of parentheses.
	      Compare with ~ outside parentheses, which	forces the entire sub-
	      stituted string to be treated as a pattern.  Hence, for example,

		     [[	"?" = ${(~j.|.)array} ]]

	      treats `|' as a pattern and succeeds if and only if $array  con-
	      tains  the  string  `?' as an element.  The ~ may	be repeated to
	      toggle the behaviour; its	effect only lasts to the  end  of  the
	      parenthesised group.

       j:string:
	      Join  the	 words of arrays together using	string as a separator.
	      Note that	this occurs before field splitting  by	the  s:string:
	      flag or the SH_WORD_SPLIT	option.

       l:expr::string1::string2:
	      Pad  the	resulting  words on the	left.  Each word will be trun-
	      cated if required	and placed in a	field expr characters wide.

	      The arguments :string1: and :string2: are	optional; neither, the
	      first, or	both may be given.  Note that the same pairs of	delim-
	      iters must be used for each of the three arguments.   The	 space
	      to  the  left will be filled with	string1	(concatenated as often
	      as needed) or spaces if string1 is not given.  If	 both  string1
	      and  string2 are given, string2 is inserted once directly	to the
	      left of each word, truncated if  necessary,  before  string1  is
	      used to produce any remaining padding.

	      If either	of string1 or string2 is present but empty, i.e. there
	      are two delimiters together at that point, the  first  character
	      of $IFS is used instead.

	      If  the  MULTIBYTE  option  is in	effect,	the flag m may also be
	      given, in	which case widths will be used for the calculation  of
	      padding;	otherwise  individual multibyte	characters are treated
	      as occupying one unit of width.

	      If the MULTIBYTE option is not  in  effect,  each	 byte  in  the
	      string is	treated	as occupying one unit of width.

	      Control  characters are always assumed to	be one unit wide; this
	      allows the mechanism to be used for  generating  repetitions  of
	      control characters.

       m      Only  useful together with one of	the flags l or r or with the #
	      length operator when the MULTIBYTE option	is in effect.  Use the
	      character	 width	reported by the	system in calculating how much
	      of the string it occupies	or the overall length of  the  string.
	      Most printable characters	have a width of	one unit, however cer-
	      tain Asian character sets	and certain special effects use	 wider
	      characters; combining characters have zero width.	 Non-printable
	      characters are arbitrarily counted as zero width;	how they would
	      actually be displayed will vary.

	      If  the  m  is repeated, the character either counts zero	(if it
	      has zero width), else one.  For printable	character strings this
	      has  the	effect of counting the number of glyphs	(visibly sepa-
	      rate characters),	except for the case where combining characters
	      themselves have non-zero width (true in certain alphabets).

       r:expr::string1::string2:
	      As  l, but pad the words on the right and	insert string2 immedi-
	      ately to the right of the	string to be padded.

	      Left and right padding may be used together.  In this  case  the
	      strategy	is  to	apply  left padding to the first half width of
	      each of the resulting words, and right  padding  to  the	second
	      half.   If  the string to	be padded has odd width	the extra pad-
	      ding is applied on the left.

       s:string:
	      Force field splitting at the  separator  string.	 Note  that  a
	      string  of  two  or  more	characters means that all of them must
	      match in sequence; this differs from the	treatment  of  two  or
	      more  characters	in the IFS parameter.  See also	the = flag and
	      the SH_WORD_SPLIT	option.	 An empty string may also be given  in
	      which case every character will be a separate element.

	      For historical reasons, the usual	behaviour that empty array el-
	      ements are retained inside double	quotes is disabled for	arrays
	      generated	by splitting; hence the	following:

		     line="one::three"
		     print -l "${(s.:.)line}"

	      produces	two  lines  of output for one and three	and elides the
	      empty field.  To override	this behaviour,	supply the `(@)'  flag
	      as well, i.e.  "${(@s.:.)line}".

       Z:opts:
	      As z but takes a combination of option letters between a follow-
	      ing pair of delimiter characters.	 With no options the effect is
	      identical	to z.  (Z+c+) causes comments to be parsed as a	string
	      and retained; any	field in the resulting array beginning with an
	      unquoted comment character is a comment.	(Z+C+) causes comments
	      to be parsed and removed.	 The rule for  comments	 is  standard:
	      anything	between	 a  word  starting with	the third character of
	      $HISTCHARS, default #, up	to the	next  newline  is  a  comment.
	      (Z+n+) causes unquoted newlines to be treated as ordinary	white-
	      space, else they are treated as if they are  shell  code	delim-
	      iters  and converted to semicolons.  Options are combined	within
	      the same set of delimiters, e.g. (Z+Cn+).

       _:flags:
	      The underscore (_) flag is reserved for future use.  As of  this
	      revision of zsh, there are no valid flags; anything following an
	      underscore, other	than an	empty pair of delimiters,  is  treated
	      as an error, and the flag	itself has no effect.

       The  following  flags  are meaningful with the ${...#...} or ${...%...}
       forms.  The S and I flags may also be used with the ${.../...} forms.

       S      Search substrings	as well	as beginnings or ends;	with  #	 start
	      from  the	beginning and with % start from	the end	of the string.
	      With  substitution  via  ${.../...}  or  ${...//...},  specifies
	      non-greedy matching, i.e.	that the shortest instead of the long-
	      est match	should be replaced.

       I:expr:
	      Search the exprth	match (where  expr  evaluates  to  a  number).
	      This only	applies	when searching for substrings, either with the
	      S	flag, or with ${.../...} (only the  exprth  match  is  substi-
	      tuted)  or  ${...//...} (all matches from	the exprth on are sub-
	      stituted).  The default is to take the first match.

	      The exprth match is counted such that there  is  either  one  or
	      zero matches from	each starting position in the string, although
	      for global substitution matches  overlapping  previous  replace-
	      ments  are  ignored.  With the ${...%...}	and ${...%%...}	forms,
	      the starting position for	the match moves	backwards from the end
	      as the index increases, while with the other forms it moves for-
	      ward from	the start.

	      Hence with the string
		     which switch is the right switch for Ipswich?
	      substitutions of the form	${(SI:N:)string#w*ch} as  N  increases
	      from  1  will  match  and	 remove	 `which', `witch', `witch' and
	      `wich'; the form using `##' will match and remove	`which	switch
	      is the right switch for Ipswich',	`witch is the right switch for
	      Ipswich',	`witch for Ipswich' and	`wich'.	 The  form  using  `%'
	      will  remove  the	same matches as	for `#', but in	reverse	order,
	      and the form using `%%' will remove the same matches as for `##'
	      in reverse order.

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

       E      Include the index	one character past the end of the match	in the
	      result (note this	is inconsistent	with other uses	 of  parameter
	      index).

       M      Include the matched portion in the result.

       N      Include the length of the	match in the result.

       R      Include the unmatched portion in the result (the Rest).

   Rules
       Here  is	 a  summary  of	 the rules for substitution; this assumes that
       braces are present around the substitution, i.e.	${...}.	 Some particu-
       lar  examples are given below.  Note that the Zsh Development Group ac-
       cepts no	responsibility for any brain damage which may occur during the
       reading of the following	rules.

       1. Nested substitution
	      If  multiple  nested  ${...}  forms are present, substitution is
	      performed	from the inside	outwards.  At each level, the  substi-
	      tution takes account of whether the current value	is a scalar or
	      an array,	whether	the whole substitution is  in  double  quotes,
	      and  what	 flags	are supplied to	the current level of substitu-
	      tion, just as if the nested  substitution	 were  the  outermost.
	      The  flags are not propagated up to enclosing substitutions; the
	      nested substitution will return either a scalar or an  array  as
	      determined by the	flags, possibly	adjusted for quoting.  All the
	      following	steps take place where applicable  at  all  levels  of
	      substitution.

	      Note  that,  unless the `(P)' flag is present, the flags and any
	      subscripts apply directly	to the value of	the  nested  substitu-
	      tion;  for  example, the expansion ${${foo}} behaves exactly the
	      same as ${foo}.  When the	`(P)' flag is present in a nested sub-
	      stitution, the other substitution	rules are applied to the value
	      before it	is interpreted as a name, so ${${(P)foo}}  may	differ
	      from ${(P)foo}.

	      At  each nested level of substitution, the substituted words un-
	      dergo all	forms of single-word substitution (i.e.	 not  filename
	      generation),  including  command substitution, arithmetic	expan-
	      sion and filename	expansion (i.e.	leading	~ and =).   Thus,  for
	      example,	${${:-=cat}:h}	expands	to the directory where the cat
	      program resides.	(Explanation: the internal substitution	has no
	      parameter	 but  a	default	value =cat, which is expanded by file-
	      name expansion to	a full path; the outer substitution  then  ap-
	      plies the	modifier :h and	takes the directory part of the	path.)

       2. Internal parameter flags
	      Any  parameter  flags  set  by one of the	typeset	family of com-
	      mands, in	particular the -L, -R, -Z, -u and -l options for  pad-
	      ding  and	 capitalization, are applied directly to the parameter
	      value.  Note these flags are options to the command, e.g.	`type-
	      set  -Z';	they are not the same as the flags used	within parame-
	      ter substitutions.

	      At the outermost level of	substitution, the `(P)'	flag (rule 4.)
	      ignores  these  transformations and uses the unmodified value of
	      the parameter as the name	to be replaced.	 This is  usually  the
	      desired  behavior	 because  padding may make the value syntacti-
	      cally illegal as a parameter name, but if	capitalization changes
	      are desired, use the ${${(P)foo}}	form (rule 25.).

       3. Parameter subscripting
	      If the value is a	raw parameter reference	with a subscript, such
	      as ${var[3]}, the	effect of subscripting is applied directly  to
	      the  parameter.	Subscripts are evaluated left to right;	subse-
	      quent subscripts apply to	the scalar or array value  yielded  by
	      the  previous  subscript.	 Thus if var is	an array, ${var[1][2]}
	      is the second character of the first word, but ${var[2,4][2]} is
	      the entire third word (the second	word of	the range of words two
	      through four of the original array).  Any	number	of  subscripts
	      may  appear.   Flags such	as `(k)' and `(v)' which alter the re-
	      sult of subscripting are applied.

       4. Parameter name replacement
	      At the outermost level of	nesting	only, the `(P)'	 flag  is  ap-
	      plied.   This treats the value so	far as a parameter name	(which
	      may include a subscript expression) and replaces that  with  the
	      corresponding value.  This replacement occurs later if the `(P)'
	      flag appears in a	nested substitution.

	      If the value so far names	a parameter that  has  internal	 flags
	      (rule 2.), those internal	flags are applied to the new value af-
	      ter replacement.

       5. Double-quoted	joining
	      If the value after this process is an array, and	the  substitu-
	      tion  appears  in	double quotes, and neither an `(@)' flag nor a
	      `#' length operator is present at	the current level, then	 words
	      of  the value are	joined with the	first character	of the parame-
	      ter $IFS,	by default a space, between each word (single word ar-
	      rays  are	 not modified).	 If the	`(j)' flag is present, that is
	      used for joining instead of $IFS.

       6. Nested subscripting
	      Any remaining subscripts (i.e. of	 a  nested  substitution)  are
	      evaluated	 at this point,	based on whether the value is an array
	      or a scalar.  As with 3.,	multiple subscripts can	appear.	  Note
	      that  ${foo[2,4][2]} is thus equivalent to ${${foo[2,4]}[2]} and
	      also to "${${(@)foo[2,4]}[2]}" (the nested substitution  returns
	      an  array	 in  both  cases), but not to "${${foo[2,4]}[2]}" (the
	      nested substitution returns a scalar because of the quotes).

       7. Modifiers
	      Any modifiers, as	specified by a trailing	`#', `%', `/'  (possi-
	      bly  doubled)  or	 by a set of modifiers of the form `:...' (see
	      the section `Modifiers' in the section `History Expansion'), are
	      applied to the words of the value	at this	level.

       8. Character evaluation
	      Any  `(#)' flag is applied, evaluating the result	so far numeri-
	      cally as a character.

       9. Length
	      Any initial `#' modifier,	i.e. in	the form ${#var}, is  used  to
	      evaluate the length of the expression so far.

       10. Forced joining
	      If  the  `(j)'  flag is present, or no `(j)' flag	is present but
	      the string is to be split	as given by rule 11., and joining  did
	      not take place at	rule 5., any words in the value	are joined to-
	      gether using the given string or the first character of $IFS  if
	      none.  Note that the `(F)' flag implicitly supplies a string for
	      joining in this manner.

       11. Simple word splitting
	      If one of	the `(s)' or `(f)' flags are present, or the `=' spec-
	      ifier  was  present  (e.g. ${=var}), the word is split on	occur-
	      rences of	the specified string, or (for =	with  neither  of  the
	      two flags	present) any of	the characters in $IFS.

	      If  no `(s)', `(f)' or `=' was given, but	the word is not	quoted
	      and the option SH_WORD_SPLIT is set, the word is split on	occur-
	      rences  of  any of the characters	in $IFS.  Note this step, too,
	      takes place at all levels	of a nested substitution.

       12. Case	modification
	      Any case modification from one of	 the  flags  `(L)',  `(U)'  or
	      `(C)' is applied.

       13. Escape sequence replacement
	      First  any  replacements from the	`(g)' flag are performed, then
	      any prompt-style formatting from the `(%)' family	 of  flags  is
	      applied.

       14. Quote application
	      Any quoting or unquoting using `(q)' and `(Q)' and related flags
	      is applied.

       15. Directory naming
	      Any directory name substitution using `(D)' flag is applied.

       16. Visibility enhancement
	      Any modifications	to make	characters  visible  using  the	 `(V)'
	      flag are applied.

       17. Lexical word	splitting
	      If  the  '(z)'  flag  or	one  of	the forms of the '(Z)' flag is
	      present, the word	is split as if it were a shell	command	 line,
	      so that quotation	marks and other	metacharacters are used	to de-
	      cide what	constitutes a word.  Note this form  of	 splitting  is
	      entirely	distinct  from that described by rule 11.: it does not
	      use $IFS,	and does not cause forced joining.

       18. Uniqueness
	      If the result is an array	and the	`(u)' flag was present,	dupli-
	      cate elements are	removed	from the array.

       19. Ordering
	      If  the  result  is still	an array and one of the	`(o)' or `(O)'
	      flags was	present, the array is reordered.

       20. RC_EXPAND_PARAM
	      At this point the	decision is made whether any  resulting	 array
	      elements	are to be combined element by element with surrounding
	      text, as given by	either the RC_EXPAND_PARAM option or  the  `^'
	      flag.

       21. Re-evaluation
	      Any  `(e)' flag is applied to the	value, forcing it to be	re-ex-
	      amined for new parameter substitutions, but also for command and
	      arithmetic substitutions.

       22. Padding
	      Any padding of the value by the `(l.fill.)' or `(r.fill.)' flags
	      is applied.

       23. Semantic joining
	      In contexts where	expansion semantics requires a single word  to
	      result,  all  words are rejoined with the	first character	of IFS
	      between.	So in `${(P)${(f)lines}}' the  value  of  ${lines}  is
	      split  at	 newlines,  but	 then  must be joined again before the
	      `(P)' flag can be	applied.

	      If a single word is not required,	this rule is skipped.

       24. Empty argument removal
	      If the substitution does not appear in double  quotes,  any  re-
	      sulting  zero-length  argument, whether from a scalar or an ele-
	      ment of an array,	is elided from the list	of arguments  inserted
	      into the command line.

	      Strictly speaking, the removal happens later as the same happens
	      with other forms of substitution;	the point to note here is sim-
	      ply that it occurs after any of the above	parameter operations.

       25. Nested parameter name replacement
	      If  the  `(P)'  flag is present and rule 4. has not applied, the
	      value so far is treated as a parameter name (which may include a
	      subscript	expression) and	replaced with the corresponding	value,
	      with internal flags (rule	2.) applied to the new value.

   Examples
       The flag	f is useful to split  a	 double-quoted	substitution  line  by
       line.   For  example, ${(f)"$(<file)"} substitutes the contents of file
       divided so that each line is an element of the resulting	 array.	  Com-
       pare  this with the effect of $(<file) alone, which divides the file up
       by words, or the	same inside double quotes, which makes the entire con-
       tent of the file	a single string.

       The  following  illustrates  the	rules for nested parameter expansions.
       Suppose that $foo contains the array (bar baz):

       "${(@)${foo}[1]}"
	      This produces the	 result	 b.   First,  the  inner  substitution
	      "${foo}",	 which	has  no	array (@) flag,	produces a single word
	      result "bar baz".	 The outer substitution	"${(@)...[1]}" detects
	      that this	is a scalar, so	that (despite the `(@)'	flag) the sub-
	      script picks the first character.

       "${${(@)foo}[1]}"
	      This produces the	result `bar'.  In this case, the inner substi-
	      tution  "${(@)foo}"  produces  the array `(bar baz)'.  The outer
	      substitution "${...[1]}" detects that this is an array and picks
	      the first	word.  This is similar to the simple case "${foo[1]}".

       As an example of	the rules for word splitting and joining, suppose $foo
       contains	the array `(ax1	bx1)'.	Then

       ${(s/x/)foo}
	      produces the words `a', `1 b' and	`1'.

       ${(j/x/s/x/)foo}
	      produces `a', `1', `b' and `1'.

       ${(s/x/)foo%%1*}
	      produces `a' and ` b' (note the extra space).   As  substitution
	      occurs  before either joining or splitting, the operation	 first
	      generates	the modified array (ax bx), which is  joined  to  give
	      "ax  bx",	 and  then  split to give `a', ` b' and	`'.  The final
	      empty string will	then be	elided,	as it is not in	double quotes.

COMMAND	SUBSTITUTION
       A command enclosed in parentheses  preceded  by	a  dollar  sign,  like
       `$(...)',  or quoted with grave accents,	like ``...`', is replaced with
       its standard output, with any trailing newlines deleted.	 If  the  sub-
       stitution  is  not enclosed in double quotes, the output	is broken into
       words using the IFS parameter.  The substitution	`$(cat	foo)'  may  be
       replaced	 by  the  equivalent but faster	`$(<foo)'.  In either case, if
       the option GLOB_SUBST is	set, the output	is eligible for	filename  gen-
       eration.

ARITHMETIC EXPANSION
       A  string  of  the  form	`$[exp]' or `$((exp))' is substituted with the
       value of	the arithmetic expression exp.	exp is subjected to  parameter
       expansion,  command  substitution and arithmetic	expansion before it is
       evaluated.  See the section `Arithmetic Evaluation'.

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

       An  expression of the form `{n1..n2}', where n1 and n2 are integers, is
       expanded	to every number	between	n1 and n2 inclusive.  If either	number
       begins with a zero, all the resulting numbers will be padded with lead-
       ing zeroes to that minimum width, but for negative numbers the -	 char-
       acter  is also included in the width.  If the numbers are in decreasing
       order the resulting sequence will also be in decreasing order.

       An expression of	the form `{n1..n2..n3}', where n1, n2, and n3 are  in-
       tegers,	is expanded as above, but only every n3th number starting from
       n1 is output.  If n3 is negative	the numbers are	output in reverse  or-
       der,  this  is slightly different from simply swapping n1 and n2	in the
       case that the step n3 doesn't evenly divide the	range.	 Zero  padding
       can  be	specified  in  any  of the three numbers, specifying it	in the
       third can be useful to pad for example `{-99..100..01}'	which  is  not
       possible	 to  specify by	putting	a 0 on either of the first two numbers
       (i.e. pad to two	characters).

       An expression of	the form `{c1..c2}', where c1 and c2 are single	 char-
       acters  (which may be multibyte characters), is expanded	to every char-
       acter in	the range from c1 to c2	in whatever character sequence is used
       internally.  For	characters with	code points below 128 this is US ASCII
       (this is	the only case most users will need).  If any intervening char-
       acter  is  not  printable,  appropriate	quotation is used to render it
       printable.  If the character sequence is	reversed, the output is	in re-
       verse order, e.g. `{d..a}' is substituted as `d c b a'.

       If  a  brace expression matches none of the above forms,	it is left un-
       changed,	unless the option BRACE_CCL (an	abbreviation for `brace	 char-
       acter  class')  is  set.	 In that case, it is expanded to a list	of the
       individual characters between the braces	sorted into the	order  of  the
       characters  in  the  ASCII  character set (multibyte characters are not
       currently handled).  The	syntax is similar to  a	 [...]	expression  in
       filename	 generation:  `-'  is  treated	specially to denote a range of
       characters, but `^' or `!' as the first character is treated  normally.
       For  example, `{abcdef0-9}' expands to 16 words 0 1 2 3 4 5 6 7 8 9 a b
       c d e f.

       Note that brace expansion is not	part  of  filename  generation	(glob-
       bing);  an  expression  such  as	*/{foo,bar} is split into two separate
       words */foo and */bar before filename generation	takes place.  In  par-
       ticular,	 note that this	is liable to produce a `no match' error	if ei-
       ther of the two expressions does	not match; this	is  to	be  contrasted
       with  */(foo|bar),  which  is treated as	a single pattern but otherwise
       has similar effects.

       To combine brace	expansion with array expansion,	see the	${^spec}  form
       described in the	section	Parameter Expansion above.

FILENAME EXPANSION
       Each  word  is checked to see if	it begins with an unquoted `~'.	 If it
       does, then the word up to a `/',	or the end of the word if there	is  no
       `/',  is	checked	to see if it can be substituted	in one of the ways de-
       scribed here.  If so, then the `~' and the checked portion are replaced
       with the	appropriate substitute value.

       A `~' by	itself is replaced by the value	of $HOME.  A `~' followed by a
       `+' or a	`-' is replaced	by current or previous working directory,  re-
       spectively.

       A  `~'  followed	by a number is replaced	by the directory at that posi-
       tion in the directory stack.  `~0' is equivalent	to `~+', and  `~1'  is
       the top of the stack.  `~+' followed by a number	is replaced by the di-
       rectory at that position	in the directory stack.	 `~+0'	is  equivalent
       to  `~+', and `~+1' is the top of the stack.  `~-' followed by a	number
       is replaced by the directory that many positions	from the bottom	of the
       stack.	`~-0'  is the bottom of	the stack.  The	PUSHD_MINUS option ex-
       changes the effects of `~+' and `~-' where they are followed by a  num-
       ber.

   Dynamic named directories
       If  the	function  zsh_directory_name  exists,  or  the	shell variable
       zsh_directory_name_functions exists and contains	an array  of  function
       names,  then the	functions are used to implement	dynamic	directory nam-
       ing.  The functions are tried in	order until one	returns	 status	 zero,
       so it is	important that functions test whether they can handle the case
       in question and return an appropriate status.

       A `~' followed by a  string  namstr  in	unquoted  square  brackets  is
       treated specially as a dynamic directory	name.  Note that the first un-
       quoted closing square bracket  always  terminates  namstr.   The	 shell
       function	 is  passed two	arguments: the string n	(for name) and namstr.
       It should either	set the	array reply to a single	element	which  is  the
       directory  corresponding	 to the	name and return	status zero (executing
       an assignment as	the last  statement  is	 usually  sufficient),	or  it
       should return status non-zero.  In the former case the element of reply
       is used as the directory; in the	latter case the	substitution is	deemed
       to  have	 failed.  If all functions fail	and the	option NOMATCH is set,
       an error	results.

       The functions defined as	above are also used to see if a	directory  can
       be turned into a	name, for example when printing	the directory stack or
       when expanding %~ in prompts.  In this case each	function is passed two
       arguments:  the	string d (for directory) and the candidate for dynamic
       naming.	The function should either return non-zero status, if the  di-
       rectory cannot be named by the function,	or it should set the array re-
       ply to consist of two elements: the first is the	dynamic	name  for  the
       directory (as would appear within `~[...]'), and	the second is the pre-
       fix length of the directory to be replaced.  For	example, if the	 trial
       directory  is  /home/myname/src/zsh  and	the dynamic name for /home/my-
       name/src	(which has 16 characters) is s,	then the function sets

	      reply=(s 16)

       The directory name so returned is compared with possible	 static	 names
       for  parts of the directory path, as described below; it	is used	if the
       prefix length matched (16 in the	example) is longer than	 that  matched
       by any static name.

       It  is not a requirement	that a function	implements both	n and d	calls;
       for example, it might be	appropriate for	certain	dynamic	forms  of  ex-
       pansion	not to be contracted to	names.	In that	case any call with the
       first argument d	should cause a non-zero	status to be returned.

       The completion system calls `zsh_directory_name c' followed by  equiva-
       lent calls to elements of the array zsh_directory_name_functions, if it
       exists, in order	to complete dynamic names for directories.   The  code
       for this	should be as for any other completion function as described in
       zshcompsys(1).

       As a working example, here is a function	that expands any dynamic names
       beginning  with	the string p: to directories below /home/pws/perforce.
       In this simple case a static name for the directory would  be  just  as
       effective.

	      zsh_directory_name() {
		emulate	-L zsh
		setopt extendedglob
		local -a match mbegin mend
		if [[ $1 = d ]]; then
		  # turn the directory into a name
		  if [[	$2 = (#b)(/home/pws/perforce/)([^/]##)*	]]; then
		    typeset -ga	reply
		    reply=(p:$match[2] $(( ${#match[1]}	+ ${#match[2]} )) )
		  else
		    return 1
		  fi
		elif [[	$1 = n ]]; then
		  # turn the name into a directory
		  [[ $2	!= (#b)p:(?*) ]] && return 1
		  typeset -ga reply
		  reply=(/home/pws/perforce/$match[1])
		elif [[	$1 = c ]]; then
		  # complete names
		  local	expl
		  local	-a dirs
		  dirs=(/home/pws/perforce/*(/:t))
		  dirs=(p:${^dirs})
		  _wanted dynamic-dirs expl 'dynamic directory'	compadd	-S\] -a	dirs
		  return
		else
		  return 1
		fi
		return 0
	      }

   Static named	directories
       A `~' followed by anything not already covered consisting of any	number
       of alphanumeric characters or underscore	(`_'), hyphen  (`-'),  or  dot
       (`.')  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 `~' is the name of a string shell	parameter whose	 value
       begins with a `/'.  Note	that trailing slashes will be removed from the
       path to the directory (though the original parameter is not modified).

       It is also possible to define directory names using the	-d  option  to
       the hash	builtin.

       When the	shell prints a path (e.g. when expanding %~ in prompts or when
       printing	the directory stack), the path is checked to see if it	has  a
       named  directory	 as its	prefix.	 If so,	then the prefix	portion	is re-
       placed with a `~' followed by the name of the directory.	  The  shorter
       of  the two ways	of referring to	the directory is used, i.e. either the
       directory name or the full path;	the name is used if they are the  same
       length.	 The parameters	$PWD and $OLDPWD are never abbreviated in this
       fashion.

   `=' expansion
       If a word begins	with an	unquoted `=' and the EQUALS option is set, the
       remainder  of the word is taken as the name of a	command.  If a command
       exists by that name, the	word is	replaced by the	full pathname  of  the
       command.

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

       If  the option MAGIC_EQUAL_SUBST	is set,	any unquoted shell argument in
       the form	`identifier=expression'	becomes	eligible for file expansion as
       described  in  the  previous paragraph.	Quoting	the first `=' also in-
       hibits this.

FILENAME GENERATION
       If a word contains an unquoted instance of one of the  characters  `*',
       `(',  `|',  `<',	 `[', or `?', it is regarded as	a pattern for filename
       generation, unless the GLOB option is unset.  If	the EXTENDED_GLOB  op-
       tion  is	 set, the `^' and `#' characters also denote a pattern;	other-
       wise they are not treated specially by the shell.

       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 NULL_GLOB option is set, in which case the word  is
       deleted;	 or unless the NOMATCH option is unset,	in which case the word
       is left unchanged.

       In filename generation, the character `/' must be  matched  explicitly;
       also, a `.' must	be matched explicitly at the beginning of a pattern or
       after a `/', unless the GLOB_DOTS option	is set.	 No  filename  genera-
       tion pattern matches the	files `.' or `..'.  In other instances of pat-
       tern matching, the `/' and `.' are not treated specially.

   Glob	Operators
       *      Matches any string, including the	null string.

       ?      Matches any character.

       [...]  Matches any of the enclosed characters.	Ranges	of  characters
	      can  be  specified by separating two characters by a `-'.	 A `-'
	      or `]' may be matched by including it as the first character  in
	      the  list.   There are also several named	classes	of characters,
	      in the form `[:name:]' with the following	meanings.   The	 first
	      set  use the macros provided by the operating system to test for
	      the given	character combinations,	 including  any	 modifications
	      due to local language settings, see ctype(3):

	      [:alnum:]
		     The character is alphanumeric

	      [:alpha:]
		     The character is alphabetic

	      [:ascii:]
		     The  character  is	7-bit, i.e. is a single-byte character
		     without the top bit set.

	      [:blank:]
		     The character is either space or tab

	      [:cntrl:]
		     The character is a	control	character

	      [:digit:]
		     The character is a	decimal	digit

	      [:graph:]
		     The character is a	printable character other than	white-
		     space

	      [:lower:]
		     The character is a	lowercase letter

	      [:print:]
		     The character is printable

	      [:punct:]
		     The  character  is	printable but neither alphanumeric nor
		     whitespace

	      [:space:]
		     The character is whitespace

	      [:upper:]
		     The character is an uppercase letter

	      [:xdigit:]
		     The character is a	hexadecimal digit

	      Another set of named classes is handled internally by the	 shell
	      and is not sensitive to the locale:

	      [:IDENT:]
		     The  character is allowed to form part of a shell identi-
		     fier, such	as a parameter name

	      [:IFS:]
		     The character is used as an input field  separator,  i.e.
		     is	contained in the IFS parameter

	      [:IFSSPACE:]
		     The  character  is	 an IFS	white space character; see the
		     documentation for IFS in the zshparam(1) manual page.

	      [:INCOMPLETE:]
		     Matches a byte that starts	an incomplete multibyte	 char-
		     acter.   Note  that  there	may be a sequence of more than
		     one bytes that taken together form	the prefix of a	multi-
		     byte  character.	To  test  for a	potentially incomplete
		     byte sequence, use	the pattern `[[:INCOMPLETE:]]*'.  This
		     will  never match a sequence starting with	a valid	multi-
		     byte character.

	      [:INVALID:]
		     Matches a byte that does  not  start  a  valid  multibyte
		     character.	  Note	this  may be a continuation byte of an
		     incomplete	multibyte character as any part	of a multibyte
		     string  consisting	 of  invalid  and incomplete multibyte
		     characters	is treated as single bytes.

	      [:WORD:]
		     The character is treated as part of a word; this test  is
		     sensitive to the value of the WORDCHARS parameter

	      Note  that the square brackets are additional to those enclosing
	      the whole	set of characters, so to test for  a  single  alphanu-
	      meric  character	you  need `[[:alnum:]]'.  Named	character sets
	      can be used alongside other types, e.g. `[[:alpha:]0-9]'.

       [^...]
       [!...] Like [...], except that it matches any character which is	not in
	      the given	set.

       <[x]-[y]>
	      Matches  any  number  in the range x to y, inclusive.  Either of
	      the numbers may be omitted to make the range  open-ended;	 hence
	      `<->' matches any	number.	 To match individual digits, the [...]
	      form is more efficient.

	      Be careful when using other wildcards adjacent  to  patterns  of
	      this  form;  for	example, <0-9>*	will actually match any	number
	      whatsoever at the	start of the string, since  the	 `<0-9>'  will
	      match  the first digit, and the `*' will match any others.  This
	      is a trap	for the	unwary,	but is in fact	an  inevitable	conse-
	      quence  of  the rule that	the longest possible match always suc-
	      ceeds.  Expressions such as `<0-9>[^[:digit:]]*' can be used in-
	      stead.

       (...)  Matches  the  enclosed  pattern.	This is	used for grouping.  If
	      the KSH_GLOB option is set, then a `@', `*', `+',	`?' or `!' im-
	      mediately	 preceding  the	 `(' is	treated	specially, as detailed
	      below. The option	SH_GLOB	prevents bare parentheses  from	 being
	      used in this way,	though the KSH_GLOB option is still available.

	      Note  that  grouping cannot extend over multiple directories: it
	      is an error to have a `/'	within a group (this only applies  for
	      patterns	used in	filename generation).  There is	one exception:
	      a	group of the form (pat/)# appearing as a complete path segment
	      can match	a sequence of directories.  For	example, foo/(a*/)#bar
	      matches foo/bar, foo/any/bar, foo/any/anyother/bar, and so on.

       x|y    Matches either x or y.  This operator has	lower precedence  than
	      any  other.   The	 `|'  character	must be	within parentheses, to
	      avoid interpretation as a	pipeline.

       ^x     (Requires	EXTENDED_GLOB to be set.)  Matches anything except the
	      pattern x.  This has a higher precedence than `/', so `^foo/bar'
	      will search directories in `.' except `./foo' for	a  file	 named
	      `bar'.

       x~y    (Requires	EXTENDED_GLOB to be set.)  Match anything that matches
	      the pattern x but	does not match y.  This	has  lower  precedence
	      than  any	 operator except `|', so `*/*~foo/bar' will search for
	      all files	in all directories in `.'  and then exclude  `foo/bar'
	      if there was such	a match.  Multiple patterns can	be excluded by
	      `foo~bar~baz'.  In the exclusion pattern (y), `/'	 and  `.'  are
	      not treated specially the	way they usually are in	globbing.

       x#     (Requires	EXTENDED_GLOB to be set.)  Matches zero	or more	occur-
	      rences of	the pattern x.	This  operator	has  high  precedence;
	      `12#'  is	 equivalent to `1(2#)',	rather than `(12)#'.  It is an
	      error for	an unquoted `#'	to follow something  which  cannot  be
	      repeated;	 this includes an empty	string,	a pattern already fol-
	      lowed by `##', or	parentheses when part of  a  KSH_GLOB  pattern
	      (for  example,  `!(foo)#'	 is  invalid  and  must	be replaced by
	      `*(!(foo))').

       x##    (Requires	EXTENDED_GLOB to be set.)  Matches one or more	occur-
	      rences  of  the  pattern	x.  This operator has high precedence;
	      `12##' is	equivalent to `1(2##)',	rather than `(12)##'.  No more
	      than  two	 active	`#' characters may appear together.  (Note the
	      potential	clash with glob	qualifiers in the form `1(2##)'	 which
	      should therefore be avoided.)

   ksh-like Glob Operators
       If  the KSH_GLOB	option is set, the effects of parentheses can be modi-
       fied by a preceding `@',	`*', `+', `?' or `!'.  This character need not
       be unquoted to have special effects, but	the `('	must be.

       @(...) Match the	pattern	in the parentheses.  (Like `(...)'.)

       *(...) Match  any  number  of occurrences.  (Like `(...)#', except that
	      recursive	directory searching is not supported.)

       +(...) Match at least one occurrence.  (Like `(...)##', except that re-
	      cursive directory	searching is not supported.)

       ?(...) Match zero or one	occurrence.  (Like `(|...)'.)

       !(...) Match   anything	but  the  expression  in  parentheses.	 (Like
	      `(^(...))'.)

   Precedence
       The precedence of the operators given above is (highest)	`^', `/', `~',
       `|'  (lowest);  the remaining operators are simply treated from left to
       right as	part of	a string, with `#' and `##' applying to	 the  shortest
       possible	 preceding unit	(i.e. a	character, `?',	`[...]', `<...>', or a
       parenthesised expression).  As mentioned	above, a `/' used as a	direc-
       tory  separator	may not	appear inside parentheses, while a `|' must do
       so; in patterns used in other contexts than  filename  generation  (for
       example,	 in  case statements and tests within `[[...]]'), a `/'	is not
       special;	and `/'	is also	not special  after  a  `~'  appearing  outside
       parentheses in a	filename pattern.

   Globbing Flags
       There  are various flags	which affect any text to their right up	to the
       end of the enclosing group or to	the end	of the pattern;	 they  require
       the  EXTENDED_GLOB  option. All take the	form (#X) where	X may have one
       of the following	forms:

       i      Case insensitive:	 upper or lower	case characters	in the pattern
	      match upper or lower case	characters.

       l      Lower  case  characters in the pattern match upper or lower case
	      characters; upper	case characters	 in  the  pattern  still  only
	      match upper case characters.

       I      Case  sensitive:	locally	negates	the effect of i	or l from that
	      point on.

       b      Activate backreferences for parenthesised	groups in the pattern;
	      this  does not work in filename generation.  When	a pattern with
	      a	set of active parentheses is matched, the strings  matched  by
	      the  groups  are	stored in the array $match, the	indices	of the
	      beginning	of the matched parentheses in the array	 $mbegin,  and
	      the  indices  of the end in the array $mend, with	the first ele-
	      ment of each array  corresponding	 to  the  first	 parenthesised
	      group, and so on.	 These arrays are not otherwise	special	to the
	      shell.  The indices use the same convention  as  does  parameter
	      substitution,  so	that elements of $mend and $mbegin may be used
	      in subscripts; the KSH_ARRAYS  option  is	 respected.   Sets  of
	      globbing flags are not considered	parenthesised groups; only the
	      first nine active	parentheses can	be referenced.

	      For example,

		     foo="a string with	a message"
		     if	[[ $foo	= (a|an)' '(#b)(*)' '* ]]; then
		       print ${foo[$mbegin[1],$mend[1]]}
		     fi

	      prints `string with a'.  Note that the first parenthesis is  be-
	      fore the (#b) and	does not create	a backreference.

	      Backreferences  work  with  all  forms of	pattern	matching other
	      than filename generation,	but note that when performing  matches
	      on  an  entire array, such as ${array#pattern}, or a global sub-
	      stitution, such as ${param//pat/repl}, only  the	data  for  the
	      last  match  remains  available.	In the case of global replace-
	      ments this may still be useful.  See the example for the m  flag
	      below.

	      The  numbering  of  backreferences strictly follows the order of
	      the opening parentheses  from  left  to  right  in  the  pattern
	      string,  although	 sets of parentheses may be nested.  There are
	      special rules for	parentheses followed by	`#' or `##'.  Only the
	      last match of the	parenthesis is remembered: for example,	in `[[
	      abab =  (#b)([ab])#  ]]',	 only  the  final  `b'	is  stored  in
	      match[1].	  Thus extra parentheses may be	necessary to match the
	      complete segment:	for example, use  `X((ab|cd)#)Y'  to  match  a
	      whole  string  of	either `ab' or `cd' between `X'	and `Y', using
	      the value	of $match[1] rather than $match[2].

	      If the match fails none of the parameters	is altered, so in some
	      cases  it	 may  be  necessary to initialise them beforehand.  If
	      some of the backreferences fail to match	--  which  happens  if
	      they are in an alternate branch which fails to match, or if they
	      are followed by #	and matched zero times	--  then  the  matched
	      string is	set to the empty string, and the start and end indices
	      are set to -1.

	      Pattern matching with backreferences  is	slightly  slower  than
	      without.

       B      Deactivate  backreferences,  negating  the  effect of the	b flag
	      from that	point on.

       cN,M   The flag (#cN,M) can be used anywhere that the # or ## operators
	      can  be  used  except in the expressions `(*/)#' and `(*/)##' in
	      filename generation, where `/' has special meaning; it cannot be
	      combined	with  other globbing flags and a bad pattern error oc-
	      curs if it is misplaced.	It is equivalent to the	form {N,M}  in
	      regular  expressions.   The  previous  character or group	is re-
	      quired to	match between N	and  M	times,	inclusive.   The  form
	      (#cN) requires exactly N matches;	(#c,M) is equivalent to	speci-
	      fying N as 0; (#cN,) specifies that there	is no maximum limit on
	      the number of matches.

       m      Set  references to the match data	for the	entire string matched;
	      this is similar to backreferencing and does not work in filename
	      generation.   The	 flag must be in effect	at the end of the pat-
	      tern, i.e. not local to a	group. The parameters $MATCH,  $MBEGIN
	      and  $MEND  will be set to the string matched and	to the indices
	      of the beginning and end of the string, respectively.   This  is
	      most  useful in parameter	substitutions, as otherwise the	string
	      matched is obvious.

	      For example,

		     arr=(veldt	jynx grimps waqf zho buck)
		     print ${arr//(#m)[aeiou]/${(U)MATCH}}

	      forces all the matches (i.e. all vowels) into uppercase,	print-
	      ing `vEldt jynx grImps wAqf zhO bUck'.

	      Unlike backreferences, there is no speed penalty for using match
	      references, other	than the extra substitutions required for  the
	      replacement strings in cases such	as the example shown.

       M      Deactivate the m flag, hence no references to match data will be
	      created.

       anum   Approximate matching: num	 errors	 are  allowed  in  the	string
	      matched by the pattern.  The rules for this are described	in the
	      next subsection.

       s, e   Unlike the other flags, these have only a	local effect, and each
	      must  appear  on	its own:  `(#s)' and `(#e)' are	the only valid
	      forms.  The `(#s)' flag succeeds only at the start of  the  test
	      string, and the `(#e)' flag succeeds only	at the end of the test
	      string; they correspond to `^' and `$' in	standard  regular  ex-
	      pressions.   They	 are useful for	matching path segments in pat-
	      terns other than those in	filename generation (where  path  seg-
	      ments  are  in  any  case	 treated  separately).	 For  example,
	      `*((#s)|/)test((#e)|/)*' matches a path segment `test' in	any of
	      the   following	strings:   test,  test/at/start,  at/end/test,
	      in/test/middle.

	      Another use is in	parameter  substitution;  for  example	`${ar-
	      ray/(#s)A*Z(#e)}'	 will  remove  only elements of	an array which
	      match the	complete pattern `A*Z'.	 There are other ways of  per-
	      forming many operations of this type, however the	combination of
	      the substitution operations `/' and `//'	with  the  `(#s)'  and
	      `(#e)' flags provides a single simple and	memorable method.

	      Note that	assertions of the form `(^(#s))' also work, i.e. match
	      anywhere except at the start of the string, although this	 actu-
	      ally  means  `anything except a zero-length portion at the start
	      of  the  string';	 you  need  to	use  `(""~(#s))'  to  match  a
	      zero-length portion of the string	not at the start.

       q      A	 `q' and everything up to the closing parenthesis of the glob-
	      bing flags are ignored by	the pattern matching  code.   This  is
	      intended	to support the use of glob qualifiers, see below.  The
	      result is	that the pattern `(#b)(*).c(#q.)' can be used both for
	      globbing and for matching	against	a string.  In the former case,
	      the `(#q.)' will be treated as a glob qualifier and  the	`(#b)'
	      will  not	be useful, while in the	latter case the	`(#b)' is use-
	      ful for backreferences and the `(#q.)' will  be  ignored.	  Note
	      that colon modifiers in the glob qualifiers are also not applied
	      in ordinary pattern matching.

       u      Respect the current locale in determining	the presence of	multi-
	      byte  characters	in  a pattern, provided	the shell was compiled
	      with MULTIBYTE_SUPPORT.  This overrides  the  MULTIBYTE  option;
	      the  default  behaviour  is  taken  from the option.  Compare U.
	      (Mnemonic: typically multibyte characters	are  from  Unicode  in
	      the UTF-8	encoding, although any extension of ASCII supported by
	      the system library may be	used.)

       U      All characters are considered to be a single byte	long.  The op-
	      posite of	u.  This overrides the MULTIBYTE option.

       For  example,  the  test	 string	 fooxx	can  be	matched	by the pattern
       (#i)FOOXX, but not by (#l)FOOXX,	 (#i)FOO(#I)XX	or  ((#i)FOOX)X.   The
       string  (#ia2)readme specifies case-insensitive matching	of readme with
       up to two errors.

       When using the ksh syntax for grouping both KSH_GLOB and	 EXTENDED_GLOB
       must  be	 set  and  the left parenthesis	should be preceded by @.  Note
       also that the flags do not affect letters inside	[...] groups, in other
       words  (#i)[a-z]	 still	matches	only lowercase letters.	 Finally, note
       that when examining whole paths case-insensitively every	directory must
       be  searched  for  all files which match, so that a pattern of the form
       (#i)/foo/bar/...	is potentially slow.

   Approximate Matching
       When matching approximately, the	shell keeps  a	count  of  the	errors
       found,  which  cannot exceed the	number specified in the	(#anum)	flags.
       Four types of error are recognised:

       1.     Different	characters, as in fooxbar and fooybar.

       2.     Transposition of characters, as in banana	and abnana.

       3.     A	character missing in the target	string,	as  with  the  pattern
	      road and target string rod.

       4.     An extra character appearing in the target string, as with stove
	      and strove.

       Thus, the pattern (#a3)abcd matches dcba, with the errors occurring  by
       using  the first	rule twice and the second once,	grouping the string as
       [d][cb][a] and [a][bc][d].

       Non-literal parts of the	pattern	must match exactly, including  charac-
       ters  in	 character  ranges:  hence (#a1)???  matches strings of	length
       four, by	applying rule 4	to an empty  part  of  the  pattern,  but  not
       strings	of  length  two, since all the ? must match.  Other characters
       which must match	exactly	are initial  dots  in  filenames  (unless  the
       GLOB_DOTS option	is set), and all slashes in filenames, so that a/bc is
       two errors from ab/c (the slash cannot be transposed with another char-
       acter).	 Similarly,  errors  are counted separately for	non-contiguous
       strings in the pattern, so that (ab|cd)ef is two	errors from aebf.

       When using exclusion  via  the  ~  operator,  approximate  matching  is
       treated entirely	separately for the excluded part and must be activated
       separately.  Thus, (#a1)README~READ_ME matches READ.ME but not READ_ME,
       as  the	trailing  READ_ME  is matched without approximation.  However,
       (#a1)README~(#a1)READ_ME	does not match any pattern of the form READ?ME
       as all such forms are now excluded.

       Apart  from exclusions, there is	only one overall error count; however,
       the maximum errors allowed may be altered locally, and this can be  de-
       limited by grouping.  For example, (#a1)cat((#a0)dog)fox	allows one er-
       ror in total, which may not occur in the	dog section, and  the  pattern
       (#a1)cat(#a0)dog(#a1)fox	 is  equivalent.  Note that the	point at which
       an error	is first found is the crucial one for establishing whether  to
       use   approximation;  for  example,  (#a1)abc(#a0)xyz  will  not	 match
       abcdxyz,	because	the error occurs at the	`x',  where  approximation  is
       turned off.

       Entire	path   segments	  may	be   matched  approximately,  so  that
       `(#a1)/foo/d/is/available/at/the/bar' allows one	error in any path seg-
       ment.   This  is	 much  less efficient than without the (#a1), however,
       since every directory in	the path must be scanned for  a	 possible  ap-
       proximate match.	 It is best to place the (#a1) after any path segments
       which are known to be correct.

   Recursive Globbing
       A pathname component of the form	`(foo/)#' matches a path consisting of
       zero or more directories	matching the pattern foo.

       As  a  shorthand, `**/' is equivalent to	`(*/)#'; note that this	there-
       fore matches files in the current directory as well as  subdirectories.
       Thus:

	      ls (*/)#bar

       or

	      ls **/bar

       does  a	recursive  directory search for	files named `bar' (potentially
       including the file `bar'	in the current directory).  This form does not
       follow  symbolic	links; the alternative form `***/' does, but is	other-
       wise identical.	Neither	of these can be	combined with other  forms  of
       globbing	 within	the same path segment; in that case, the `*' operators
       revert to their usual effect.

       Even shorter forms are available	when  the  option  GLOB_STAR_SHORT  is
       set.   In  that	case  if no / immediately follows a ** or *** they are
       treated as if both a / plus a further * are present.  Hence:

	      setopt GLOBSTARSHORT
	      ls **.c

       is equivalent to

	      ls **/*.c

   Glob	Qualifiers
       Patterns	used for filename generation may end in	a list	of  qualifiers
       enclosed	 in  parentheses.  The qualifiers specify which	filenames that
       otherwise match the given pattern will  be  inserted  in	 the  argument
       list.

       If the option BARE_GLOB_QUAL is set, then a trailing set	of parentheses
       containing no `|' or `('	characters (or `~' if it is special) is	 taken
       as  a set of glob qualifiers.  A	glob subexpression that	would normally
       be taken	as glob	qualifiers, for	example	`(^x)',	can be	forced	to  be
       treated	as  part  of  the glob pattern by doubling the parentheses, in
       this case producing `((^x))'.

       If the option EXTENDED_GLOB is set, a different syntax for glob	quali-
       fiers  is  available,  namely  `(#qx)'  where x is any of the same glob
       qualifiers used in the other format.  The qualifiers must still	appear
       at  the	end  of	 the pattern.  However,	with this syntax multiple glob
       qualifiers may be chained together.  They are treated as	a logical  AND
       of  the	individual sets	of flags.  Also, as the	syntax is unambiguous,
       the expression will be treated as glob  qualifiers  just	 as  long  any
       parentheses contained within it are balanced; appearance	of `|',	`(' or
       `~' does	not negate the effect.	Note that qualifiers  will  be	recog-
       nised  in  this form even if a bare glob	qualifier exists at the	end of
       the pattern, for	example	`*(#q*)(.)' will recognise executable  regular
       files if	both options are set; however, mixed syntax should probably be
       avoided for the sake of clarity.	 Note that within conditions using the
       `[[' form the presence of a parenthesised expression (#q...) at the end
       of a string indicates that globbing should be performed;	the expression
       may include glob	qualifiers, but	it is also valid if it is simply (#q).
       This does not apply to the right	hand side of pattern  match  operators
       as the syntax already has special significance.

       A qualifier may be any one of the following:

       /      directories

       F      `full'  (i.e.  non-empty)	 directories.	Note that the opposite
	      sense (^F) expands to empty directories and all non-directories.
	      Use (/^F)	for empty directories.

       .      plain files

       @      symbolic links

       =      sockets

       p      named pipes (FIFOs)

       *      executable plain files (0100 or 0010 or 0001)

       %      device files (character or block special)

       %b     block special files

       %c     character	special	files

       r      owner-readable files (0400)

       w      owner-writable files (0200)

       x      owner-executable files (0100)

       A      group-readable files (0040)

       I      group-writable files (0020)

       E      group-executable files (0010)

       R      world-readable files (0004)

       W      world-writable files (0002)

       X      world-executable files (0001)

       s      setuid files (04000)

       S      setgid files (02000)

       t      files with the sticky bit	(01000)

       fspec  files with access	rights matching	spec. This spec	may be a octal
	      number optionally	preceded by a `=', a `+', or a `-'. If none of
	      these  characters	is given, the behavior is the same as for `='.
	      The octal	number describes the mode bits to be expected, if com-
	      bined  with a `=', the value given must match the	file-modes ex-
	      actly, with a `+', at least the bits in the given	number must be
	      set  in  the  file-modes,	and with a `-',	the bits in the	number
	      must not be set. Giving a	`?' instead of a octal digit  anywhere
	      in  the  number  ensures	that  the  corresponding  bits	in the
	      file-modes are not checked, this is only useful  in  combination
	      with `='.

	      If the qualifier `f' is followed by any other character anything
	      up to the	next matching character	(`[', `{', and `<' match  `]',
	      `}',  and	 `>' respectively, any other character matches itself)
	      is taken as a list of comma-separated sub-specs.	Each  sub-spec
	      may  be  either  an octal	number as described above or a list of
	      any of the characters `u', `g', `o', and `a', followed by	a `=',
	      a	 `+',  or  a  `-', followed by a list of any of	the characters
	      `r', `w',	`x', `s', and `t', or an octal digit. The  first  list
	      of  characters specify which access rights are to	be checked. If
	      a	`u' is given, those for	the owner of the file are used,	 if  a
	      `g'  is  given,  those  of the group are checked,	a `o' means to
	      test those of other users, and the `a' says to  test  all	 three
	      groups. The `=', `+', and	`-' again says how the modes are to be
	      checked and have the same	meaning	as  described  for  the	 first
	      form above. The second list of characters	finally	says which ac-
	      cess rights are to be expected: `r' for  read  access,  `w'  for
	      write  access,  `x'  for	the  right  to execute the file	(or to
	      search a directory), `s' for the setuid and setgid bits, and `t'
	      for the sticky bit.

	      Thus,  `*(f70?)'	gives  the files for which the owner has read,
	      write, and execute permission, and for which other group members
	      have  no rights, independent of the permissions for other	users.
	      The pattern `*(f-100)' gives all files for which the owner  does
	      not  have	 execute  permission,  and `*(f:gu+w,o-rx:)' gives the
	      files for	which the owner	and the	other  members	of  the	 group
	      have  at least write permission, and for which other users don't
	      have read	or execute permission.

       estring
       +cmd   The string will be executed as shell code.  The filename will be
	      included in the list if and only if the code returns a zero sta-
	      tus (usually the status of the last command).

	      In the first form, the first character after  the	 `e'  will  be
	      used as a	separator and anything up to the next matching separa-
	      tor will be taken	 as the	string;	`[', `{', and `<'  match  `]',
	      `}',  and	 `>',  respectively, while any other character matches
	      itself. Note that	expansions must	be quoted  in  the  string  to
	      prevent  them  from  being  expanded  before  globbing  is done.
	      string is	then executed as shell code.  The string  globqual  is
	      appended	to  the	 array zsh_eval_context	the duration of	execu-
	      tion.

	      During the execution of  string  the  filename  currently	 being
	      tested is	available in the parameter REPLY; the parameter	may be
	      altered to a string to be	inserted into the list instead of  the
	      original	filename.  In addition,	the parameter reply may	be set
	      to an array or a string, which overrides the value of REPLY.  If
	      set  to  an  array, the latter is	inserted into the command line
	      word by word.

	      For  example,  suppose  a	 directory  contains  a	 single	  file
	      `lonely'.	  Then	the expression `*(e:'reply=(${REPLY}{1,2})':)'
	      will cause the words `lonely1' and `lonely2' to be inserted into
	      the command line.	 Note the quoting of string.

	      The  form	 +cmd  has  the	 same effect, but no delimiters	appear
	      around cmd.  Instead, cmd	is taken as the	 longest  sequence  of
	      characters  following the	+ that are alphanumeric	or underscore.
	      Typically	cmd will be the	name of	a shell	function that contains
	      the appropriate test.  For example,

		     nt() { [[ $REPLY -nt $NTREF ]] }
		     NTREF=reffile
		     ls	-l *(+nt)

	      lists  all  files	 in the	directory that have been modified more
	      recently than reffile.

       ddev   files on the device dev

       l[-|+]ct
	      files having a link count	less than ct (-), greater than ct (+),
	      or equal to ct

       U      files owned by the effective user	ID

       G      files owned by the effective group ID

       uid    files  owned  by	user ID	id if that is a	number.	 Otherwise, id
	      specifies	a user name: the character after the `u' will be taken
	      as  a  separator and the string between it and the next matching
	      separator	will be	taken as a user	name.  The starting separators
	      `[',  `{', and `<' match the final separators `]', `}', and `>',
	      respectively; any	other character	matches	itself.	 The  selected
	      files  are  those	 owned by this user.  For example, `u:foo:' or
	      `u[foo]' selects files owned by user `foo'.

       gid    like uid but with	group IDs or names

       a[Mwhms][-|+]n
	      files accessed exactly n days ago.  Files	 accessed  within  the
	      last  n  days  are  selected  using a negative value for n (-n).
	      Files accessed more than n days ago are selected by a positive n
	      value  (+n).  Optional unit specifiers `M', `w', `h', `m'	or `s'
	      (e.g. `ah5') cause the check to be performed with	months (of  30
	      days), weeks, hours, minutes or seconds instead of days, respec-
	      tively.  An explicit `d' for days	is also	allowed.

	      Any fractional part of the difference between  the  access  time
	      and  the current part in the appropriate units is	ignored	in the
	      comparison.  For instance, `echo *(ah-5)'	would echo  files  ac-
	      cessed  within  the  last	five hours, while `echo	*(ah+5)' would
	      echo files accessed at least six hours ago,  as  times  strictly
	      between five and six hours are treated as	five hours.

       m[Mwhms][-|+]n
	      like  the	 file  access  qualifier, except that it uses the file
	      modification time.

       c[Mwhms][-|+]n
	      like the file access qualifier, except that it uses the file in-
	      ode change time.

       L[+|-]n
	      files less than n	bytes (-), more	than n bytes (+), or exactly n
	      bytes in length.

	      If this flag is directly followed	by a size specifier `k'	(`K'),
	      `m'  (`M'),  or  `p' (`P') (e.g. `Lk-50')	the check is performed
	      with kilobytes, megabytes, or blocks  (of	 512  bytes)  instead.
	      (On  some	 systems additional specifiers are available for giga-
	      bytes, `g' or `G', and terabytes,	`t' or `T'.) If	a size	speci-
	      fier  is	used  a	 file is regarded as "exactly" the size	if the
	      file size	rounded	up to the next unit is equal to	the test size.
	      Hence `*(Lm1)' matches files from	1 byte up to 1 Megabyte	inclu-
	      sive.  Note also that the	set of files "less than" the test size
	      only  includes  files  that  would  not match the	equality test;
	      hence `*(Lm-1)' only matches files of zero size.

       ^      negates all qualifiers following it

       -      toggles between making the qualifiers  work  on  symbolic	 links
	      (the default) and	the files they point to

       M      sets the MARK_DIRS option	for the	current	pattern

       T      appends a	trailing qualifier mark	to the filenames, analogous to
	      the LIST_TYPES option, for the current pattern (overrides	M)

       N      sets the NULL_GLOB option	for the	current	pattern

       D      sets the GLOB_DOTS option	for the	current	pattern

       n      sets the NUMERIC_GLOB_SORT option	for the	current	pattern

       Yn     enables short-circuit mode: the pattern will expand to at	most n
	      filenames.   If  more  than  n  matches  exist, only the first n
	      matches in directory traversal order will	be considered.

	      Implies oN when no oc qualifier is used.

       oc     specifies	how the	names of the files should be sorted. If	c is n
	      they are sorted by name; if it is	L they are sorted depending on
	      the size (length)	of the files; if l they	are sorted by the num-
	      ber  of  links; if a, m, or c they are sorted by the time	of the
	      last access, modification, or inode change respectively;	if  d,
	      files  in	 subdirectories	appear before those in the current di-
	      rectory at each level of the search --  this  is	best  combined
	      with  other  criteria,  for  example `odon' to sort on names for
	      files within the same directory; if N, no	sorting	is  performed.
	      Note  that a, m, and c compare the age against the current time,
	      hence the	first name in the list is the youngest file. Also note
	      that  the	 modifiers ^ and - are used, so	`*(^-oL)' gives	a list
	      of all files sorted by file size in descending order,  following
	      any  symbolic  links.   Unless oN	is used, multiple order	speci-
	      fiers may	occur to resolve ties.

	      The default sorting is n (by name) unless	the Y  glob  qualifier
	      is used, in which	case it	is N (unsorted).

	      oe  and  o+  are	special	cases; they are	each followed by shell
	      code, delimited as for the e glob	qualifier and the + glob qual-
	      ifier  respectively  (see	above).	 The code is executed for each
	      matched file with	the parameter REPLY set	to  the	 name  of  the
	      file  on	entry  and globsort appended to	zsh_eval_context.  The
	      code should modify the parameter REPLY in	some fashion.  On  re-
	      turn,  the  value	 of  the parameter is used instead of the file
	      name as the string on which to sort.  Unlike other  sort	opera-
	      tors,  oe	and o+ may be repeated,	but note that the maximum num-
	      ber of sort operators of any kind	that may appear	 in  any  glob
	      expression is 12.

       Oc     like  `o',  but  sorts in	descending order; i.e. `*(^oc)'	is the
	      same as `*(Oc)' and `*(^Oc)' is the same as `*(oc)';  `Od'  puts
	      files in the current directory before those in subdirectories at
	      each level of the	search.

       [beg[,end]]
	      specifies	which of the matched filenames should be  included  in
	      the  returned  list.  The	 syntax	 is the	same as	for array sub-
	      scripts. beg and the optional end	may  be	 mathematical  expres-
	      sions. As	in parameter subscripting they may be negative to make
	      them count from the last	match  backward.  E.g.:	 `*(-OL[1,3])'
	      gives a list of the names	of the three largest files.

       Pstring
	      The  string  will	 be prepended to each glob match as a separate
	      word.  string is delimited in the	same way as arguments to the e
	      glob  qualifier described	above.	The qualifier can be repeated;
	      the words	are prepended separately so that the resulting command
	      line contains the	words in the same order	they were given	in the
	      list of glob qualifiers.

	      A	typical	use for	this is	to prepend an option before all	occur-
	      rences  of a file	name; for example, the pattern `*(P:-f:)' pro-
	      duces the	command	line arguments `-f file1 -f file2 ...'

	      If the modifier ^	is active, then	string will  be	 appended  in-
	      stead  of	 prepended.  Prepending	and appending is done indepen-
	      dently so	both can be used on the	same glob expression; for  ex-
	      ample  by	 writing  `*(P:foo:^P:bar:^P:baz:)' which produces the
	      command line arguments `foo baz file1 bar	...'

       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
       `or'ed, the qualifiers in the sublists are `and'ed).  Some  qualifiers,
       however,	 affect	 all  matches generated, independent of	the sublist in
       which they are given.  These are	the qualifiers	`M',  `T',  `N',  `D',
       `n', `o', `O' and the subscripts	given in brackets (`[...]').

       If  a  `:' appears in a qualifier list, the remainder of	the expression
       in parenthesis is interpreted as	a modifier  (see  the  section	`Modi-
       fiers'  in the section `History Expansion').  Each modifier must	be in-
       troduced	by a separate `:'.  Note also that the result after  modifica-
       tion  does  not	have to	be an existing file.  The name of any existing
       file can	be followed by a modifier of the form `(:...)' even if no  ac-
       tual  filename generation is performed, although	note that the presence
       of the parentheses causes the entire expression to be subjected to  any
       global pattern matching options such as NULL_GLOB. Thus:

	      ls *(-/)

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

	      ls *(-@)

       lists all broken	symbolic links,	and

	      ls *(%W)

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

	      ls *(W,X)

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

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

       outputs the basename of all root-owned files beginning with the	string
       `foo' in	/tmp, ignoring symlinks, and

	      ls *.*~(lex|parse).[ch](^D^l1)

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

	      print b*.pro(#q:s/pro/shmo/)(#q.:s/builtin/shmiltin/)

       demonstrates  how  colon	 modifiers and other qualifiers	may be chained
       together.  The ordinary qualifier `.' is	applied	first, then the	 colon
       modifiers  in order from	left to	right.	So if EXTENDED_GLOB is set and
       the base	pattern	matches	the regular file builtin.pro, the  shell  will
       print `shmiltin.shmo'.

ZSHPARAM(1)		    General Commands Manual		   ZSHPARAM(1)

NAME
       zshparam	- zsh parameters

DESCRIPTION
       A  parameter  has  a name, a value, and a number	of attributes.	A name
       may be any sequence of alphanumeric characters and underscores, or  the
       single  characters  `*',	 `@', `#', `?',	`-', `$', or `!'.  A parameter
       whose name begins with an alphanumeric or underscore is	also  referred
       to as a variable.

       The  attributes	of  a parameter	determine the type of its value, often
       referred	to as the parameter type or variable type,  and	 also  control
       other  processing  that	may  be	applied	to the value when it is	refer-
       enced.  The value type may be a scalar (a  string,  an  integer,	 or  a
       floating	 point number),	an array (indexed numerically),	or an associa-
       tive array (an unordered	set of name-value pairs, indexed by name, also
       referred	to as a	hash).

       Named  scalar  parameters may have the exported,	-x, attribute, to copy
       them into the process environment, which	is then	passed from the	 shell
       to  any	new  processes that it starts.	Exported parameters are	called
       environment variables. The shell	also imports environment variables  at
       startup	time  and  automatically marks the corresponding parameters as
       exported.  Some environment variables are not imported for  reasons  of
       security	 or because they would interfere with the correct operation of
       other shell features.

       Parameters may also be special, that  is,  they	have  a	 predetermined
       meaning	to  the	 shell.	  Special  parameters  cannot  have their type
       changed or their	readonly attribute turned off, and if a	special	param-
       eter is unset, then later recreated, the	special	properties will	be re-
       tained.

       To declare the type of a	parameter, or to assign	a  string  or  numeric
       value to	a scalar parameter, use	the typeset builtin.

       The value of a scalar parameter may also	be assigned by writing:

	      name=value

       In  scalar  assignment,	value is expanded as a single string, in which
       the elements of arrays are joined together; filename expansion  is  not
       performed unless	the option GLOB_ASSIGN is set.

       When  the  integer  attribute, -i, or a floating	point attribute, -E or
       -F, is set for name, the	value is  subject  to  arithmetic  evaluation.
       Furthermore, by replacing `=' with `+=',	a parameter can	be incremented
       or appended to.	See the	 section  `Array  Parameters'  and  Arithmetic
       Evaluation (in zshmisc(1)) for additional forms of assignment.

       Note  that assignment may implicitly change the attributes of a parame-
       ter.  For example, assigning a number to	a variable in arithmetic eval-
       uation  may  change  its	type to	integer	or float, and with GLOB_ASSIGN
       assigning a pattern to a	variable may change its	type to	an array.

       To reference the	value of a parameter, write `$name' or `${name}'.  See
       Parameter  Expansion  in	zshexpn(1) for complete	details.  That section
       also explains the effect	of the difference between scalar and array as-
       signment	on parameter expansion.

ARRAY PARAMETERS
       To assign an array value, write one of:

	      set -A name value	...
	      name=(value ...)

       If  no  parameter  name exists, an ordinary array parameter is created.
       If the parameter	name exists and	is a scalar, it	is replaced by	a  new
       array.  To append to an array without changing the existing values, use
       the syntax:

	      name+=(value ...)

       Within the parentheses on the right hand	side of	either form of the as-
       signment,  newlines and semicolons are treated the same as white	space,
       separating individual values.  Any consecutive sequence of such charac-
       ters has	the same effect.

       Ordinary	array parameters may also be explicitly	declared with:

	      typeset -a name

       Associative arrays must be declared before assignment, by using:

	      typeset -A name

       When  name refers to an associative array, the list in an assignment is
       interpreted as alternating keys and values:

	      set -A name key value ...
	      name=(key	value ...)

       Every key must have a value in this case.  Note that  this  assigns  to
       the entire array, deleting any elements that do not appear in the list.
       The append syntax may also be used with an associative array:

	      name+=(key value ...)

       This adds a new key/value pair if the key is not	already	 present,  and
       replaces	the value for the existing key if it is.

       To create an empty array	(including associative arrays),	use one	of:

	      set -A name
	      name=()

   Array Subscripts
       Individual  elements  of	an array may be	selected using a subscript.  A
       subscript of the	form `[exp]' selects the single	element	exp, where exp
       is  an arithmetic expression which will be subject to arithmetic	expan-
       sion as if it were surrounded by	`$((...))'.  The elements are numbered
       beginning  with	1,  unless  the	KSH_ARRAYS option is set in which case
       they are	numbered from zero.

       Subscripts may be used inside braces used to delimit a parameter	 name,
       thus  `${foo[2]}' is equivalent to `$foo[2]'.  If the KSH_ARRAYS	option
       is set, the braced form is the only one that works,  as	bracketed  ex-
       pressions otherwise are not treated as subscripts.

       If the KSH_ARRAYS option	is not set, then by default accesses to	an ar-
       ray element with	a subscript that evaluates to  zero  return  an	 empty
       string,	while an attempt to write such an element is treated as	an er-
       ror.  For backward compatibility	the KSH_ZERO_SUBSCRIPT option  can  be
       set  to	cause  subscript  values 0 and 1 to be equivalent; see the de-
       scription of the	option in zshoptions(1).

       The same	subscripting syntax is used  for  associative  arrays,	except
       that  no	 arithmetic expansion is applied to exp.  However, the parsing
       rules for arithmetic expressions	still apply,  which  affects  the  way
       that  certain special characters	must be	protected from interpretation.
       See Subscript Parsing below for details.

       A subscript of the form `[*]' or	`[@]' evaluates	to all elements	of  an
       array;  there  is no difference between the two except when they	appear
       within double  quotes.	`"$foo[*]"'  evaluates	to  `"$foo[1]  $foo[2]
       ..."', whereas `"$foo[@]"' evaluates to `"$foo[1]" "$foo[2]" ...'.  For
       associative arrays, `[*]' or `[@]' evaluate to all the  values,	in  no
       particular order.  Note that this does not substitute the keys; see the
       documentation for the `k' flag under Parameter Expansion	Flags in  zsh-
       expn(1) for complete details.  When an array parameter is referenced as
       `$name' (with no	subscript) it  evaluates  to  `$name[*]',  unless  the
       KSH_ARRAYS  option  is  set  in which case it evaluates to `${name[0]}'
       (for an associative array, this means the value of the key  `0',	 which
       may not exist even if there are values for other	keys).

       A subscript of the form `[exp1,exp2]' selects all elements in the range
       exp1 to exp2, inclusive.	(Associative arrays are	unordered, and	so  do
       not  support  ranges.) If one of	the subscripts evaluates to a negative
       number, say -n, then the	nth element from the end of the	array is used.
       Thus `$foo[-3]' is the third element from the end of the	array foo, and
       `$foo[1,-1]' is the same	as `$foo[*]'.

       Subscripting may	also be	performed on non-array values, in  which  case
       the  subscripts	specify	 a substring to	be extracted.  For example, if
       FOO is set to `foobar', then `echo $FOO[2,5]' prints `ooba'.  Note that
       some  forms  of	subscripting described below perform pattern matching,
       and in that case	the substring extends from the start of	the  match  of
       the  first  subscript  to the end of the	match of the second subscript.
       For example,

	      string="abcdefghijklm"
	      print ${string[(r)d?,(r)h?]}

       prints `defghi'.	 This is an obvious generalisation  of	the  rule  for
       single-character	 matches.  For a single	subscript, only	a single char-
       acter is	referenced (not	the range of characters	covered	by the match).

       Note that in substring operations the second subscript is handled  dif-
       ferently	 by the	r and R	subscript flags: the former takes the shortest
       match as	the length and the latter the longest  match.	Hence  in  the
       former  case  a	*  at the end is redundant while in the	latter case it
       matches the whole remainder of the string.  This	does  not  affect  the
       result  of the single subscript case as here the	length of the match is
       irrelevant.

   Array Element Assignment
       A subscript may be used on the left side	of an assignment like so:

	      name[exp]=value

       In this form of assignment the element or range specified by exp	is re-
       placed by the expression	on the right side.  An array (but not an asso-
       ciative array) may be created by	assignment to a	range or element.  Ar-
       rays do not nest, so assigning a	parenthesized list of values to	an el-
       ement or	range changes the number of elements in	 the  array,  shifting
       the  other  elements  to	accommodate the	new values.  (This is not sup-
       ported for associative arrays.)

       This syntax also	works as an argument to	the typeset command:

	      typeset "name[exp]"=value

       The value may not be a parenthesized list in this case; only single-el-
       ement  assignments may be made with typeset.  Note that quotes are nec-
       essary in this case to prevent the brackets from	being  interpreted  as
       filename	generation operators.  The noglob precommand modifier could be
       used instead.

       To delete an element of an ordinary array, assign `()' to that element.
       To delete an element of an associative array, use the unset command:

	      unset "name[exp]"

   Subscript Flags
       If  the	opening	bracket, or the	comma in a range, in any subscript ex-
       pression	is directly followed by	an opening parenthesis,	the string  up
       to  the matching	closing	one is considered to be	a list of flags, as in
       `name[(flags)exp]'.

       The flags s, n and b take an argument; the delimiter is shown below  as
       `:',  but  any  character,  or  the  matching  pairs  `(...)', `{...}',
       `[...]',	or `<...>', may	be used, but note that	`<...>'	 can  only  be
       used if the subscript is	inside a double	quoted expression or a parame-
       ter substitution	enclosed in braces as otherwise	the expression is  in-
       terpreted as a redirection.

       The flags currently understood are:

       w      If  the  parameter  subscripted is a scalar then this flag makes
	      subscripting work	on words instead of characters.	  The  default
	      word  separator  is  whitespace.	This flag may not be used with
	      the i or I flag.

       s:string:
	      This gives the string that separates words (for use with	the  w
	      flag).  The delimiter character :	is arbitrary; see above.

       p      Recognize	 the same escape sequences as the print	builtin	in the
	      string argument of a subsequent `s' flag.

       f      If the parameter subscripted is a	scalar then  this  flag	 makes
	      subscripting work	on lines instead of characters,	i.e. with ele-
	      ments separated by newlines.  This is a shorthand	for `pws:\n:'.

       r      Reverse subscripting: 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 `w'	flag is	given, respec-
	      tively).	The subscript used is the number of the	matching  ele-
	      ment,  so	 that  pairs of	subscripts such	as `$foo[(r)??,3]' and
	      `$foo[(r)??,(r)f*]' are possible if the parameter	is not an  as-
	      sociative	array.	If the parameter is an associative array, only
	      the value	part of	each pair is compared to the pattern, and  the
	      result is	that value.

	      If  a  search  through an	ordinary array failed, the search sets
	      the subscript to one past	the end	of the array, and hence	 ${ar-
	      ray[(r)pattern]}	will  substitute  the  empty string.  Thus the
	      success of a search can be tested	by using the (i) flag, for ex-
	      ample (assuming the option KSH_ARRAYS is not in effect):

		     [[	${array[(i)pattern]} -le ${#array} ]]

	      If KSH_ARRAYS is in effect, the -le should be replaced by	-lt.

       R      Like  `r',  but  gives  the last match.  For associative arrays,
	      gives all	possible matches. May be used for assigning  to	 ordi-
	      nary  array  elements,  but not for assigning to associative ar-
	      rays.  On	failure, for normal arrays this	has the	effect of  re-
	      turning  the element corresponding to subscript 0; this is empty
	      unless one of the	options	KSH_ARRAYS or KSH_ZERO_SUBSCRIPT is in
	      effect.

	      Note that	in subscripts with both	`r' and	`R' pattern characters
	      are active even if they were substituted for  a  parameter  (re-
	      gardless	of  the	setting	of GLOB_SUBST which controls this fea-
	      ture in normal pattern matching).	 The flag `e' can be added  to
	      inhibit  pattern	matching.  As this flag	does not inhibit other
	      forms of substitution, care is still required; using a parameter
	      to hold the key has the desired effect:

		     key2='original key'
		     print ${array[(Re)$key2]}

       i      Like `r',	but gives the index of the match instead; this may not
	      be combined with a second	argument.  On the left side of an  as-
	      signment,	 behaves  like	`r'.   For associative arrays, the key
	      part of each pair	is compared to	the  pattern,  and  the	 first
	      matching	key  found  is the result.  On failure substitutes the
	      length of	the array plus one, as discussed under the description
	      of `r', or the empty string for an associative array.

       I      Like `i',	but gives the index of the last	match, or all possible
	      matching keys in an associative array.  On  failure  substitutes
	      0,  or  the empty	string for an associative array.  This flag is
	      best when	testing	for values or keys that	do not exist.

       k      If used in a subscript on	an associative array, this flag	causes
	      the  keys	 to  be	interpreted as patterns, and returns the value
	      for the first key	found where exp	is matched by the  key.	  Note
	      this  could be any such key as no	ordering of associative	arrays
	      is defined.  This	flag does not work on the left side of an  as-
	      signment	to  an	associative array element.  If used on another
	      type of parameter, this behaves like `r'.

       K      On an associative	array this is like `k' but returns all	values
	      where  exp is matched by the keys.  On other types of parameters
	      this has the same	effect as `R'.

       n:expr:
	      If combined with `r', `R', `i' or	`I', makes them	give  the  nth
	      or  nth  last  match (if expr evaluates to n).  This flag	is ig-
	      nored when the array is associative.  The	delimiter character  :
	      is arbitrary; see	above.

       b:expr:
	      If  combined  with `r', `R', `i' or `I', makes them begin	at the
	      nth or nth last element, word, or	character (if  expr  evaluates
	      to n).  This flag	is ignored when	the array is associative.  The
	      delimiter	character : is arbitrary; see above.

       e      This flag	causes any pattern matching that would be performed on
	      the  subscript  to  use  plain  string  matching instead.	 Hence
	      `${array[(re)*]}'	matches	only the array element whose value  is
	      *.  Note that other forms	of substitution	such as	parameter sub-
	      stitution	are not	inhibited.

	      This flag	can also be used to force * or @ to be interpreted  as
	      a	 single	 key rather than as a reference	to all values.	It may
	      be used for either purpose on the	left side of an	assignment.

       See Parameter Expansion Flags (zshexpn(1)) for additional ways  to  ma-
       nipulate	the results of array subscripting.

   Subscript Parsing
       This  discussion	applies	mainly to associative array key	strings	and to
       patterns	used for reverse subscripting (the `r',	`R', `i', etc. flags),
       but  it	may also affect	parameter substitutions	that appear as part of
       an arithmetic expression	in an ordinary subscript.

       To avoid	subscript parsing limitations in  assignments  to  associative
       array elements, use the append syntax:

	      aa+=('key	with "*strange*" characters' 'value string')

       The  basic rule to remember when	writing	a subscript expression is that
       all text	between	the opening `['	and the	closing	`]' is interpreted  as
       if  it  were in double quotes (see zshmisc(1)).	However, unlike	double
       quotes which normally cannot nest, subscript expressions	may appear in-
       side  double-quoted  strings  or	inside other subscript expressions (or
       both!), so the rules have two important differences.

       The first difference is that brackets (`[' and `]') must	appear as bal-
       anced  pairs  in	 a  subscript expression unless	they are preceded by a
       backslash (`\').	 Therefore, within a subscript expression (and	unlike
       true  double-quoting) the sequence `\[' becomes `[', and	similarly `\]'
       becomes `]'.  This applies even in cases	where a	backslash is not  nor-
       mally required; for example, the	pattern	`[^[]' (to match any character
       other than an open bracket) should be written `[^\[]' in	a reverse-sub-
       script pattern.	However, note that `\[^\[\]' and even `\[^[]' mean the
       same thing, because backslashes are always stripped  when  they	appear
       before brackets!

       The  same rule applies to parentheses (`(' and `)') and braces (`{' and
       `}'): they must appear either in	balanced pairs or preceded by a	 back-
       slash,  and  backslashes	that protect parentheses or braces are removed
       during parsing.	This is	because	parameter expansions may be surrounded
       by  balanced  braces,  and  subscript  flags are	introduced by balanced
       parentheses.

       The second difference is	that a double-quote (`"') may appear  as  part
       of  a  subscript	 expression without being preceded by a	backslash, and
       therefore that the two characters `\"' remain as	two characters in  the
       subscript (in true double-quoting, `\"' becomes `"').  However, because
       of the standard shell quoting rules, any	double-quotes that appear must
       occur  in balanced pairs	unless preceded	by a backslash.	 This makes it
       more difficult to write a subscript expression  that  contains  an  odd
       number  of  double-quote	characters, but	the reason for this difference
       is so that  when	 a  subscript  expression  appears  inside  true  dou-
       ble-quotes, one can still write `\"' (rather than `\\\"') for `"'.

       To  use	an  odd	number of double quotes	as a key in an assignment, use
       the typeset builtin and an enclosing pair of double quotes; to refer to
       the value of that key, again use	double quotes:

	      typeset -A aa
	      typeset "aa[one\"two\"three\"quotes]"=QQQ
	      print "$aa[one\"two\"three\"quotes]"

       It is important to note that the	quoting	rules do not change when a pa-
       rameter expansion with a	subscript is nested inside  another  subscript
       expression.  That is, it	is not necessary to use	additional backslashes
       within the inner	subscript expression; they are removed only once, from
       the  innermost  subscript  outwards.  Parameters	are also expanded from
       the innermost subscript first, as each expansion	is encountered left to
       right in	the outer expression.

       A  further complication arises from a way in which subscript parsing is
       not different from double quote parsing.	 As  in	 true  double-quoting,
       the  sequences `\*', and	`\@' remain as two characters when they	appear
       in a subscript expression.  To use a literal `*'	or `@' as an  associa-
       tive array key, the `e' flag must be used:

	      typeset -A aa
	      aa[(e)*]=star
	      print $aa[(e)*]

       A  last	detail	must  be  considered when reverse subscripting is per-
       formed.	Parameters appearing in	the subscript expression are first ex-
       panded  and  then  the complete expression is interpreted as a pattern.
       This has	two effects: first, parameters behave as if GLOB_SUBST were on
       (and  it	 cannot	 be  turned  off); second, backslashes are interpreted
       twice, once when	parsing	the array subscript and	again when parsing the
       pattern.	  In  a	 reverse  subscript,  it's necessary to	use four back-
       slashes to cause	a single backslash to match literally in the  pattern.
       For complex patterns, it	is often easiest to assign the desired pattern
       to a parameter and then refer to	that parameter in the  subscript,  be-
       cause  then the backslashes, brackets, parentheses, etc., are seen only
       when the	complete expression is converted to a pattern.	To  match  the
       value of	a parameter literally in a reverse subscript, rather than as a
       pattern,	use `${(q)name}' (see zshexpn(1)) to quote the expanded	value.

       Note that the `k' and `K' flags are reverse subscripting	for  an	 ordi-
       nary  array, but	are not	reverse	subscripting for an associative	array!
       (For an associative array, the keys in the array	itself are interpreted
       as  patterns  by	 those	flags; the subscript is	a plain	string in that
       case.)

       One final note, not directly related to subscripting: the numeric names
       of positional parameters	(described below) are parsed specially,	so for
       example `$2foo' is equivalent to	`${2}foo'.   Therefore,	 to  use  sub-
       script  syntax  to extract a substring from a positional	parameter, the
       expansion must be surrounded by braces; for example, `${2[3,5]}'	evalu-
       ates to the third through fifth characters of the second	positional pa-
       rameter,	but `$2[3,5]' is the entire second parameter concatenated with
       the filename generation pattern `[3,5]'.

POSITIONAL PARAMETERS
       The  positional parameters provide access to the	command-line arguments
       of a shell function, shell script, or the shell itself; see the section
       `Invocation', and also the section `Functions'.	The parameter n, where
       n is a number, is the nth positional parameter.	The parameter `$0'  is
       a special case, see the section `Parameters Set By The Shell'.

       The  parameters	*, @ and argv are arrays containing all	the positional
       parameters; thus	`$argv[n]', etc., is equivalent	to simply `$n'.	  Note
       that the	options	KSH_ARRAYS or KSH_ZERO_SUBSCRIPT apply to these	arrays
       as well,	so with	either of those	options	set, `${argv[0]}'  is  equiva-
       lent to `$1' and	so on.

       Positional parameters may be changed after the shell or function	starts
       by using	the set	builtin, by assigning to the argv array, or by	direct
       assignment  of  the  form  `n=value' where n is the number of the posi-
       tional parameter	to be changed.	This also creates (with	empty  values)
       any of the positions from 1 to n	that do	not already have values.  Note
       that, because the positional parameters form an array, an array assign-
       ment  of	 the  form  `n=(value  ...)' is	allowed, and has the effect of
       shifting	all the	values at positions greater than n by  as  many	 posi-
       tions as	necessary to accommodate the new values.

LOCAL PARAMETERS
       Shell function executions delimit scopes	for shell parameters.  (Param-
       eters are dynamically scoped.)  The typeset builtin, and	 its  alterna-
       tive  forms  declare, integer, local and	readonly (but not export), can
       be used to declare a parameter as being local to	the innermost scope.

       When a parameter	is read	or assigned to,	the innermost existing parame-
       ter  of	that  name  is	used.  (That is, the local parameter hides any
       less-local parameter.)  However,	assigning to a non-existent parameter,
       or  declaring  a	 new parameter with export, causes it to be created in
       the outermost scope.

       Local parameters	disappear when their scope ends.  unset	can be used to
       delete  a  parameter while it is	still in scope;	any outer parameter of
       the same	name remains hidden.

       Special parameters may also be made local; they	retain	their  special
       attributes  unless  either  the existing	or the newly-created parameter
       has the -h (hide) attribute.  This may have unexpected  effects:	 there
       is  no  default	value,	so  if there is	no assignment at the point the
       variable	is made	local, it will be set to an empty value	 (or  zero  in
       the case	of integers).  The following:

	      typeset PATH=/new/directory:$PATH

       is  valid  for temporarily allowing the shell or	programmes called from
       it to find the programs in /new/directory inside	a function.

       Note that the restriction in older versions of zsh that	local  parame-
       ters were never exported	has been removed.

PARAMETERS SET BY THE SHELL
       In  the	parameter lists	that follow, the mark `<S>' indicates that the
       parameter is special.  `<Z>' indicates that the parameter does not  ex-
       ist when	the shell initializes in sh or ksh emulation mode.

       The following parameters	are automatically set by the shell:

       ! <S>  The  process  ID	of  the	last command started in	the background
	      with &, or put into the background with the bg builtin.

       # <S>  The number of positional parameters in decimal.  Note that  some
	      confusion	 may  occur  with the syntax $#param which substitutes
	      the length of param.  Use	${#} to	resolve	ambiguities.  In  par-
	      ticular,	the  sequence  `$#-...'	in an arithmetic expression is
	      interpreted as the length	of the parameter -, q.v.

       ARGC <S>	<Z>
	      Same as #.

       $ <S>  The process ID of	this shell.   Note  that  this	indicates  the
	      original	shell  started	by  invoking zsh; all processes	forked
	      from the shells without executing	a new program,	such  as  sub-
	      shells started by	(...), substitute the same value.

       - <S>  Flags  supplied  to the shell on invocation or by	the set	or se-
	      topt commands.

       * <S>  An array containing the positional parameters.

       argv <S>	<Z>
	      Same as *.  Assigning to argv changes the	local  positional  pa-
	      rameters,	 but  argv  is not itself a local parameter.  Deleting
	      argv with	unset in any function deletes it everywhere,  although
	      only  the	 innermost positional parameter	array is deleted (so *
	      and @ in other scopes are	not affected).

       @ <S>  Same as argv[@], even when argv is not set.

       ? <S>  The exit status returned by the last command.

       0 <S>  The name used to invoke the current shell, or as set by  the  -c
	      command  line  option  upon invocation.  If the FUNCTION_ARGZERO
	      option is	set, $0	is set upon entry to a shell function  to  the
	      name  of the function, and upon entry to a sourced script	to the
	      name of the script, and reset to its  previous  value  when  the
	      function or script returns.

       status <S> <Z>
	      Same as ?.

       pipestatus <S> <Z>
	      An  array	 containing the	exit statuses returned by all commands
	      in the last pipeline.

       _ <S>  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.

       CPUTYPE
	      The machine type (microprocessor class or	machine	model),	as de-
	      termined at run time.

       EGID <S>
	      The effective group ID of	the shell process.  If you have	suffi-
	      cient 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 `(EGID=gid; command)'

	      If this is made local, it	is not implicitly set to 0, but	may be
	      explicitly set locally.

       EUID <S>
	      The effective user ID of the shell process.  If you have	suffi-
	      cient  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 `(EUID=uid; command)'

	      If this is made local, it	is not implicitly set to 0, but	may be
	      explicitly set locally.

       ERRNO <S>
	      The  value  of  errno (see errno(3)) as set by the most recently
	      failed system call.  This	value is system	dependent and  is  in-
	      tended  for  debugging  purposes.	  It  is  also useful with the
	      zsh/system module	which allows the number	to be  turned  into  a
	      name or message.

       GID <S>
	      The  real	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	privi-
	      leges), you may start a single command under a  different	 group
	      ID by `(GID=gid; command)'

	      If this is made local, it	is not implicitly set to 0, but	may be
	      explicitly set locally.

       HISTCMD
	      The current history event	number in  an  interactive  shell,  in
	      other  words  the	 event	number	for  the  command  that	caused
	      $HISTCMD to be read.  If the current history event modifies  the
	      history,	HISTCMD	 changes to the	new maximum history event num-
	      ber.

       HOST   The current hostname.

       LINENO <S>
	      The line number of the current line within the  current  script,
	      sourced  file,  or  shell	function being executed, whichever was
	      started most recently.  Note that	in the case of shell functions
	      the  line	 number	 refers	 to the	function as it appeared	in the
	      original definition, not necessarily as displayed	by  the	 func-
	      tions builtin.

       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 typeset builtin.   The	 value
	      is  set to the string returned by	the getlogin(3)	system call if
	      that is available.

       MACHTYPE
	      The machine type (microprocessor class or	machine	model),	as de-
	      termined at compile time.

       OLDPWD The previous working directory.  This is set when	the shell ini-
	      tializes and whenever the	directory changes.

       OPTARG <S>
	      The value	of the last option argument processed by  the  getopts
	      command.

       OPTIND <S>
	      The  index  of the last option argument processed	by the getopts
	      command.

       OSTYPE The operating system, as determined at compile time.

       PPID <S>
	      The process ID of	the parent of the shell.  As for $$, the value
	      indicates	 the  parent of	the original shell and does not	change
	      in subshells.

       PWD    The present working directory.  This is set when the shell  ini-
	      tializes and whenever the	directory changes.

       RANDOM <S>
	      A	 pseudo-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 RANDOM.

	      The   values   of	  RANDOM   form	  an  intentionally-repeatable
	      pseudo-random sequence; subshells	that reference RANDOM will re-
	      sult  in identical pseudo-random values unless the value of RAN-
	      DOM is referenced	or seeded in the parent	shell in between  sub-
	      shell invocations.

       SECONDS <S>
	      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.

	      Unlike other special parameters, the type	of the SECONDS parame-
	      ter  can be changed using	the typeset command.  Only integer and
	      one of the floating  point  types	 are  allowed.	 For  example,
	      `typeset -F SECONDS' causes the value to be reported as a	float-
	      ing point	number.	 The value is available	to  microsecond	 accu-
	      racy, although the shell may show	more or	fewer digits depending
	      on the use of typeset.  See the documentation  for  the  builtin
	      typeset in zshbuiltins(1)	for more details.

       SHLVL <S>
	      Incremented by one each time a new shell is started.

       signals
	      An  array	 containing  the names of the signals.	Note that with
	      the standard zsh numbering of array indices, where the first el-
	      ement  has  index	1, the signals are offset by 1 from the	signal
	      number used by the operating system.  For	 example,  on  typical
	      Unix-like	 systems HUP is	signal number 1, but is	referred to as
	      $signals[2].  This is because of EXIT at position	1 in  the  ar-
	      ray, which is used internally by zsh but is not known to the op-
	      erating system.

       TRY_BLOCK_ERROR <S>
	      In an always block, indicates whether the	preceding list of code
	      caused  an error.	 The value is 1	to indicate an error, 0	other-
	      wise.  It	may be reset, clearing the error condition.  See  Com-
	      plex Commands in zshmisc(1)

       TRY_BLOCK_INTERRUPT <S>
	      This  variable  works  in	 a similar way to TRY_BLOCK_ERROR, but
	      represents the status of an interrupt from  the  signal  SIGINT,
	      which  typically comes from the keyboard when the	user types ^C.
	      If set to	0, any such interrupt will be  reset;  otherwise,  the
	      interrupt	is propagated after the	always block.

	      Note  that  it  is possible that an interrupt arrives during the
	      execution	of the always block; this  interrupt  is  also	propa-
	      gated.

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

       TTYIDLE <S>
	      The idle time of the tty associated with the shell in seconds or
	      -1 if there is no	such tty.

       UID <S>
	      The real 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
	      `(UID=uid; command)'

	      If this is made local, it	is not implicitly set to 0, but	may be
	      explicitly set locally.

       USERNAME	<S>
	      The  username  corresponding  to	the  real 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 as-
	      signing to this parameter.   Also	 (assuming  sufficient	privi-
	      leges),  you  may	start a	single command under a different user-
	      name (and	user ID	and group  ID)	by  `(USERNAME=username;  com-
	      mand)'

       VENDOR The vendor, as determined	at compile time.

       zsh_eval_context	<S> <Z>	(ZSH_EVAL_CONTEXT <S>)
	      An  array	(colon-separated list) indicating the context of shell
	      code that	is being run.  Each time a piece of shell code that is
	      stored  within the shell is executed a string is temporarily ap-
	      pended to	the array to indicate the type of  operation  that  is
	      being performed.	Read in	order the array	gives an indication of
	      the stack	of operations being performed with the most  immediate
	      context last.

	      Note  that  the  variable	does not give information on syntactic
	      context such as pipelines	or subshells.	Use  $ZSH_SUBSHELL  to
	      detect subshells.

	      The context is one of the	following:
	      cmdarg Code  specified by	the -c option to the command line that
		     invoked the shell.

	      cmdsubst
		     Command substitution using	the `...` or $(...) construct.

	      equalsubst
		     File substitution using the =(...)	construct.

	      eval   Code executed by the eval builtin.

	      evalautofunc
		     Code executed with	the KSH_AUTOLOAD mechanism in order to
		     define an autoloaded function.

	      fc     Code  from	the shell history executed by the -e option to
		     the fc builtin.

	      file   Lines of code being read directly from a file, for	 exam-
		     ple by the	source builtin.

	      filecode
		     Lines  of code being read from a .zwc file	instead	of di-
		     rectly from the source file.

	      globqual
		     Code executed by the e or + glob qualifier.

	      globsort
		     Code executed to order files by the o glob	qualifier.

	      insubst
		     File substitution using the <(...)	construct.

	      loadautofunc
		     Code read directly	from a file to	define	an  autoloaded
		     function.

	      outsubst
		     File substitution using the >(...)	construct.

	      sched  Code executed by the sched	builtin.

	      shfunc A shell function.

	      stty   Code  passed  to  stty  by	the STTY environment variable.
		     Normally this is passed directly  to  the	system's  stty
		     command,  so  this	 value is unlikely to be seen in prac-
		     tice.

	      style  Code executed as part of a	style retrieved	by the	zstyle
		     builtin from the zsh/zutil	module.

	      toplevel
		     The  highest  execution  level of a script	or interactive
		     shell.

	      trap   Code executed as a	trap  defined  by  the	trap  builtin.
		     Traps  defined  as	functions have the context shfunc.  As
		     traps are asynchronous they may have a different  hierar-
		     chy from other code.

	      zpty   Code  executed by the zpty	builtin	from the zsh/zpty mod-
		     ule.

	      zregexparse-guard
		     Code executed as a	guard by the zregexparse command  from
		     the zsh/zutil module.

	      zregexparse-action
		     Code  executed  as	 an  action by the zregexparse command
		     from the zsh/zutil	module.

       ZSH_ARGZERO
	      If zsh was invoked to run	a script, this	is  the	 name  of  the
	      script.	Otherwise,  it	is the name used to invoke the current
	      shell.   This  is	 the  same  as	the  value  of	$0  when   the
	      POSIX_ARGZERO option is set, but is always available.

       ZSH_EXECUTION_STRING
	      If  the  shell was started with the option -c, this contains the
	      argument passed to the option.  Otherwise	it is not set.

       ZSH_NAME
	      Expands to the basename of the command used to invoke  this  in-
	      stance of	zsh.

       ZSH_PATCHLEVEL
	      The revision string for the version number of the	ChangeLog file
	      in the zsh distribution.	This is	most useful in order  to  keep
	      track  of	 versions  of the shell	during development between re-
	      leases; hence most users should not use it  and  should  instead
	      rely on $ZSH_VERSION.

       zsh_scheduled_events
	      See the section `The zsh/sched Module' in	zshmodules(1).

       ZSH_SCRIPT
	      If  zsh  was  invoked  to	 run a script, this is the name	of the
	      script, otherwise	it is unset.

       ZSH_SUBSHELL
	      Readonly integer.	 Initially zero,  incremented  each  time  the
	      shell  forks  to	create	a  subshell for	executing code.	 Hence
	      `(print $ZSH_SUBSHELL)' and `print $(print $ZSH_SUBSHELL)'  out-
	      put 1, while `( (print $ZSH_SUBSHELL) )' outputs 2.

       ZSH_VERSION
	      The version number of the	release	of zsh.

PARAMETERS USED	BY THE SHELL
       The following parameters	are used by the	shell.	Again, `<S>' indicates
       that the	parameter is special and `<Z>' indicates  that	the  parameter
       does not	exist when the shell initializes in sh or ksh emulation	mode.

       In  cases  where	 there are two parameters with an upper- and lowercase
       form of the same	name, such as path and PATH, the lowercase form	is  an
       array and the uppercase form is a scalar	with the elements of the array
       joined together by colons.  These are similar to	tied  parameters  cre-
       ated  via `typeset -T'.	The normal use for the colon-separated form is
       for exporting to	the environment, while the array form is easier	to ma-
       nipulate	within the shell.  Note	that unsetting either of the pair will
       unset the other;	they retain their special properties  when  recreated,
       and recreating one of the pair will recreate the	other.

       ARGV0  If  exported,  its value is used as the argv[0] of external com-
	      mands.  Usually used in constructs like `ARGV0=emacs nethack'.

       BAUD   The rate in bits per second at which data	reaches	the  terminal.
	      The line editor will use this value in order to compensate for a
	      slow terminal by delaying	updates	to the	display	 until	neces-
	      sary.   If  the parameter	is unset or the	value is zero the com-
	      pensation	mechanism is turned off.  The parameter	is not set  by
	      default.

	      This parameter may be profitably set in some circumstances, e.g.
	      for slow modems dialing into a communications server,  or	 on  a
	      slow  wide  area	network.  It should be set to the baud rate of
	      the slowest part of the link for best performance.

       cdpath <S> <Z> (CDPATH <S>)
	      An array (colon-separated	list) of  directories  specifying  the
	      search path for the cd command.

       COLUMNS <S>
	      The  number  of  columns	for  this  terminal session.  Used for
	      printing select lists and	for the	line editor.

       CORRECT_IGNORE
	      If set, is treated as a pattern during spelling correction.  Any
	      potential	 correction  that matches the pattern is ignored.  For
	      example, if the value is `_*' then completion functions  (which,
	      by  convention, have names beginning with	`_') will never	be of-
	      fered as spelling	corrections.  The pattern does	not  apply  to
	      the  correction of file names, as	applied	by the CORRECT_ALL op-
	      tion (so with the	example	just given files beginning with	`_' in
	      the current directory would still	be completed).

       CORRECT_IGNORE_FILE
	      If  set,	is  treated as a pattern during	spelling correction of
	      file names.  Any file name that matches the pattern is never of-
	      fered  as	 a correction.	For example, if	the value is `.*' then
	      dot file names will never	be offered  as	spelling  corrections.
	      This is useful with the CORRECT_ALL option.

       DIRSTACKSIZE
	      The  maximum size	of the directory stack,	by default there is no
	      limit.  If the stack gets	larger than this, it will be truncated
	      automatically.  This is useful with the AUTO_PUSHD option.

       ENV    If the ENV environment variable is set when zsh is invoked as sh
	      or ksh, $ENV is sourced after the	profile	scripts.  The value of
	      ENV  is  subjected to parameter expansion, command substitution,
	      and arithmetic expansion before being interpreted	as a pathname.
	      Note  that  ENV  is not used unless the shell is interactive and
	      zsh is emulating sh or ksh.

       FCEDIT The default editor for the fc builtin.  If FCEDIT	 is  not  set,
	      the  parameter  EDITOR  is  used;	 if  that is not set either, a
	      builtin default, usually vi, is used.

       fignore <S> <Z> (FIGNORE	<S>)
	      An array (colon separated	list) containing the suffixes of files
	      to  be  ignored during filename completion.  However, if comple-
	      tion only	generates files	with suffixes in this list, then these
	      files are	completed anyway.

       fpath <S> <Z> (FPATH <S>)
	      An  array	 (colon	 separated list) of directories	specifying the
	      search path for function definitions.   This  path  is  searched
	      when a function with the -u attribute is referenced.  If an exe-
	      cutable file is found, then it is	read and executed in the  cur-
	      rent environment.

       histchars <S>
	      Three  characters	used by	the shell's history and	lexical	analy-
	      sis mechanism.  The first	character signals the start of a  his-
	      tory  expansion (default `!').  The second character signals the
	      start of a quick history substitution (default `^').  The	 third
	      character	is the comment character (default `#').

	      The  characters  must be in the ASCII character set; any attempt
	      to set histchars to characters with a  locale-dependent  meaning
	      will be rejected with an error message.

       HISTCHARS <S> <Z>
	      Same as histchars.  (Deprecated.)

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

       HISTORY_IGNORE
	      If set, is treated as a pattern at the time  history  files  are
	      written.	 Any  potential	history	entry that matches the pattern
	      is skipped.  For example,	if the value is	`fc *'	then  commands
	      that  invoke the interactive history editor are never written to
	      the history file.

	      Note that	HISTORY_IGNORE defines a single	 pattern:  to  specify
	      alternatives use the `(first|second|...)'	syntax.

	      Compare  the HIST_NO_STORE option	or the zshaddhistory hook, ei-
	      ther of which would prevent such commands	from  being  added  to
	      the  interactive history at all.	If you wish to use HISTORY_IG-
	      NORE to stop history being added in the first place, you can de-
	      fine the following hook:

		     zshaddhistory() {
		       emulate -L zsh
		       ## uncomment if HISTORY_IGNORE
		       ## should use EXTENDED_GLOB syntax
		       # setopt	extendedglob
		       [[ $1 !=	${~HISTORY_IGNORE} ]]
		     }

       HISTSIZE	<S>
	      The  maximum  number  of	events	stored in the internal history
	      list.  If	you use	 the  HIST_EXPIRE_DUPS_FIRST  option,  setting
	      this  value larger than the SAVEHIST size	will give you the dif-
	      ference as a cushion for saving duplicated history events.

	      If this is made local, it	is not implicitly set to 0, but	may be
	      explicitly set locally.

       HOME <S>
	      The  default argument for	the cd command.	 This is not set auto-
	      matically	by the shell in	sh, ksh	or csh emulation,  but	it  is
	      typically	 present  in the environment anyway, and if it becomes
	      set it has its usual special behaviour.

       IFS <S>
	      Internal field separators	(by default space,  tab,  newline  and
	      NUL),  that are used to separate words which result from command
	      or parameter expansion and words read by the read	builtin.   Any
	      characters  from	the  set space,	tab and	newline	that appear in
	      the IFS are called 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
	      IFS, this	character is treated as	if it were not	an  IFS	 white
	      space character.

	      If the parameter is unset, the default is	used.  Note this has a
	      different	effect from setting the	parameter to an	empty string.

       KEYBOARD_HACK
	      This variable defines a character	to be removed from the end  of
	      the  command  line  before  interpreting	it (interactive	shells
	      only). It	is intended to fix the problem with keys placed	annoy-
	      ingly  close  to	return and replaces the	SUNKEYBOARDHACK	option
	      which did	this for backquotes only.  Should the chosen character
	      be one of	singlequote, doublequote or backquote, there must also
	      be an odd	number of them on the command line for the last	one to
	      be removed.

	      For backward compatibility, if the SUNKEYBOARDHACK option	is ex-
	      plicitly set, the	value of KEYBOARD_HACK reverts	to  backquote.
	      If  the  option  is  explicitly  unset,  this variable is	set to
	      empty.

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

       LANG <S>
	      This  variable  determines  the locale category for any category
	      not specifically selected	via a variable starting	with `LC_'.

       LC_ALL <S>
	      This variable overrides the value	of the `LANG' variable and the
	      value of any of the other	variables starting with	`LC_'.

       LC_COLLATE <S>
	      This  variable determines	the locale category for	character col-
	      lation information within	ranges in glob brackets	and for	 sort-
	      ing.

       LC_CTYPE	<S>
	      This  variable determines	the locale category for	character han-
	      dling functions.	If the MULTIBYTE  option  is  in  effect  this
	      variable	or LANG	should contain a value that reflects the char-
	      acter set	in use,	even if	it is a	single-byte character set, un-
	      less only	the 7-bit subset (ASCII) is used.  For example,	if the
	      character	 set  is  ISO-8859-1,  a  suitable  value   might   be
	      en_US.iso88591  (certain Linux distributions) or en_US.ISO8859-1
	      (MacOS).

       LC_MESSAGES <S>
	      This variable determines the language in which  messages	should
	      be written.  Note	that zsh does not use message catalogs.

       LC_NUMERIC <S>
	      This  variable affects the decimal point character and thousands
	      separator	character for the formatted input/output functions and
	      string conversion	functions.  Note that zsh ignores this setting
	      when parsing floating point mathematical expressions.

       LC_TIME <S>
	      This variable determines the locale category for date  and  time
	      formatting in prompt escape sequences.

       LINES <S>
	      The  number of lines for this terminal session.  Used for	print-
	      ing select lists and for the line	editor.

       LISTMAX
	      In the line editor, the number of	matches	to list	without	asking
	      first.  If  the  value is	negative, the list will	be shown if it
	      spans at most as many lines as given by the absolute value.   If
	      set to zero, the shell asks only if the top of the listing would
	      scroll off the screen.

       LOGCHECK
	      The interval in seconds between checks for login/logout activity
	      using the	watch parameter.

       MAIL   If  this	parameter  is  set  and	mailpath is not	set, the shell
	      looks for	mail in	the specified file.

       MAILCHECK
	      The interval in seconds between checks for new mail.

       mailpath	<S> <Z>	(MAILPATH <S>)
	      An array (colon-separated	list) of filenames to  check  for  new
	      mail.  Each filename can be followed by a	`?' and	a message that
	      will be printed.	The message will undergo parameter  expansion,
	      command  substitution and	arithmetic expansion with the variable
	      $_ defined as the	name of	the file that has  changed.   The  de-
	      fault message is `You have new mail'.  If	an element is a	direc-
	      tory instead of a	file the shell will  recursively  check	 every
	      file in every subdirectory of the	element.

       manpath <S> <Z> (MANPATH	<S> <Z>)
	      An  array	 (colon-separated list)	whose value is not used	by the
	      shell.  The manpath array	can be useful, however,	since  setting
	      it also sets MANPATH, and	vice versa.

       match
       mbegin
       mend   Arrays set by the	shell when the b globbing flag is used in pat-
	      tern matches.  See the subsection	Globbing flags in the documen-
	      tation for Filename Generation in	zshexpn(1).

       MATCH
       MBEGIN
       MEND   Set  by  the  shell  when	the m globbing flag is used in pattern
	      matches.	See the	subsection Globbing flags in the documentation
	      for Filename Generation in zshexpn(1).

       module_path <S> <Z> (MODULE_PATH	<S>)
	      An  array	 (colon-separated  list)  of directories that zmodload
	      searches for dynamically loadable	modules.  This is  initialized
	      to  a  standard  pathname, usually `/usr/local/lib/zsh/$ZSH_VER-
	      SION'.  (The `/usr/local/lib' part varies	from  installation  to
	      installation.)  For security reasons, any	value set in the envi-
	      ronment when the shell is	started	will be	ignored.

	      These parameters only exist if the installation supports dynamic
	      module loading.

       NULLCMD <S>
	      The command name to assume if a redirection is specified with no
	      command.	Defaults to cat.  For sh/ksh behavior, change this  to
	      :.   For csh-like	behavior, unset	this parameter;	the shell will
	      print an error message if	null commands are entered.

       path <S>	<Z> (PATH <S>)
	      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.

       POSTEDIT	<S>
	      This string is output whenever the line editor exits.   It  usu-
	      ally contains termcap strings to reset the terminal.

       PROMPT <S> <Z>
       PROMPT2 <S> <Z>
       PROMPT3 <S> <Z>
       PROMPT4 <S> <Z>
	      Same as PS1, PS2,	PS3 and	PS4, respectively.

       prompt <S> <Z>
	      Same as PS1.

       PROMPT_EOL_MARK
	      When   the   PROMPT_CR   and  PROMPT_SP  options	are  set,  the
	      PROMPT_EOL_MARK parameter	can be used to customize how  the  end
	      of partial lines are shown.  This	parameter undergoes prompt ex-
	      pansion, with the	PROMPT_PERCENT option set.  If	not  set,  the
	      default behavior is equivalent to	the value `%B%S%#%s%b'.

       PS1 <S>
	      The primary prompt string, printed before	a command is read.  It
	      undergoes	a special form of expansion  before  being  displayed;
	      see EXPANSION OF PROMPT SEQUENCES	in zshmisc(1).	The default is
	      `%m%# '.

       PS2 <S>
	      The secondary prompt, printed when the shell needs more informa-
	      tion  to	complete a command.  It	is expanded in the same	way as
	      PS1.  The	default	is `%_>	', which displays any shell constructs
	      or quotation marks which are currently being processed.

       PS3 <S>
	      Selection	 prompt	 used within a select loop.  It	is expanded in
	      the same way as PS1.  The	default	is `?# '.

       PS4 <S>
	      The execution trace prompt.  Default is `+%N:%i> ',  which  dis-
	      plays  the name of the current shell structure and the line num-
	      ber within it.  In sh or ksh emulation, the default is `+	'.

       psvar <S> <Z> (PSVAR <S>)
	      An array (colon-separated	list) whose elements can  be  used  in
	      PROMPT strings.  Setting psvar also sets PSVAR, and vice versa.

       READNULLCMD <S>
	      The  command  name  to  assume  if a single input	redirection is
	      specified	with no	command.  Defaults to more.

       REPORTMEMORY
	      If  nonnegative,	commands  whose	 maximum  resident  set	  size
	      (roughly	speaking,  main	 memory	usage) in megabytes is greater
	      than this	value have timing  statistics  reported.   The	format
	      used to output statistics	is the value of	the TIMEFMT parameter,
	      which is the same	as for the REPORTTIME variable	and  the  time
	      builtin; note that by default this does not output memory	usage.
	      Appending	" max RSS %M" to the value of  TIMEFMT	causes	it  to
	      output  the  value  that triggered the report.  If REPORTTIME is
	      also in use, at most a single report is printed for  both	 trig-
	      gers.   This  feature requires the getrusage() system call, com-
	      monly supported by modern	Unix-like systems.

       REPORTTIME
	      If nonnegative, commands whose combined user and	system	execu-
	      tion  times  (measured  in  seconds) are greater than this value
	      have timing statistics printed for them.	Output	is  suppressed
	      for  commands executed within the	line editor, including comple-
	      tion; commands explicitly	marked with  the  time	keyword	 still
	      cause the	summary	to be printed in this case.

       REPLY  This  parameter  is reserved by convention to pass string	values
	      between shell scripts and	shell builtins in situations  where  a
	      function call or redirection are impossible or undesirable.  The
	      read builtin and the select complex command may set  REPLY,  and
	      filename generation both sets and	examines its value when	evalu-
	      ating certain expressions.  Some modules also employ  REPLY  for
	      similar purposes.

       reply  As REPLY,	but for	array values rather than strings.

       RPROMPT <S>
       RPS1 <S>
	      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 SINGLE_LINE_ZLE option is set.  It	is ex-
	      panded in	the same way as	PS1.

       RPROMPT2	<S>
       RPS2 <S>
	      This prompt is displayed on the right-hand side  of  the	screen
	      when  the	secondary prompt is being displayed on the left.  This
	      does not work if the SINGLE_LINE_ZLE option is set.  It  is  ex-
	      panded in	the same way as	PS2.

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

	      If this is made local, it	is not implicitly set to 0, but	may be
	      explicitly set locally.

       SPROMPT <S>
	      The  prompt used for spelling correction.	 The sequence `%R' ex-
	      pands to the string which	presumably needs spelling  correction,
	      and  `%r'	 expands to the	proposed correction.  All other	prompt
	      escapes are also allowed.

	      The actions available at the prompt are [nyae]:
	      n	(`no') (default)
		     Discard the correction and	run the	command.
	      y	(`yes')
		     Make the correction and run the command.
	      a	(`abort')
		     Discard the entire	command	line without running it.
	      e	(`edit')
		     Resume editing the	command	line.

       STTY   If this parameter	is set in a command's environment,  the	 shell
	      runs  the	stty command with the value of this parameter as argu-
	      ments in order to	set up the terminal before executing the  com-
	      mand. The	modes apply only to the	command, and are reset when it
	      finishes or is suspended.	If the command is suspended  and  con-
	      tinued  later with the fg	or wait	builtins it will see the modes
	      specified	by STTY, as if it were not  suspended.	 This  (inten-
	      tionally)	 does  not apply if the	command	is continued via `kill
	      -CONT'.  STTY is ignored if the command  is  run	in  the	 back-
	      ground,  or if it	is in the environment of the shell but not ex-
	      plicitly assigned	to in the input	line. This avoids running stty
	      at  every	 external  command  by accidentally exporting it. Also
	      note that	STTY should not	be used	 for  window  size  specifica-
	      tions; these will	not be local to	the command.

       TERM <S>
	      The type of terminal in use.  This is used when looking up term-
	      cap sequences.  An assignment to TERM causes zsh to  re-initial-
	      ize  the	terminal,  even	 if  the  value	does not change	(e.g.,
	      `TERM=$TERM').  It is necessary to make such an assignment  upon
	      any  change to the terminal definition database or terminal type
	      in order for the new settings to take effect.

       TERMINFO	<S>
	      A	reference to your terminfo database, used  by  the  `terminfo'
	      library  when  the system	has it;	see terminfo(5).  If set, this
	      causes the shell to reinitialise the terminal, making the	 work-
	      around `TERM=$TERM' unnecessary.

       TERMINFO_DIRS <S>
	      A	colon-seprarated list of terminfo databases, used by the `ter-
	      minfo' library when the system has  it;  see  terminfo(5).  This
	      variable is only used by certain terminal	libraries, in particu-
	      lar ncurses; see terminfo(5) to check support  on	 your  system.
	      If set, this causes the shell to reinitialise the	terminal, mak-
	      ing the workaround `TERM=$TERM' unnecessary.  Note  that	unlike
	      other colon-separated arrays this	is not tied to a zsh array.

       TIMEFMT
	      The  format  of process time reports with	the time keyword.  The
	      default is `%J  %U user %S system	%P cpu %*E total'.  Recognizes
	      the  following  escape sequences,	although not all may be	avail-
	      able on all systems, and some that are available may not be use-
	      ful:

	      %%     A `%'.
	      %U     CPU seconds spent in user mode.
	      %S     CPU seconds spent in kernel mode.
	      %E     Elapsed time in seconds.
	      %P     The CPU percentage, computed as 100*(%U+%S)/%E.
	      %W     Number of times the process was swapped.
	      %X     The  average  amount in (shared) text space used in kilo-
		     bytes.
	      %D     The average amount	in (unshared) data/stack space used in
		     kilobytes.
	      %K     The total space used (%X+%D) in kilobytes.
	      %M     The  maximum memory the process had in use	at any time in
		     megabytes.
	      %F     The number	of  major  page	 faults	 (page	needed	to  be
		     brought from disk).
	      %R     The number	of minor page faults.
	      %I     The number	of input operations.
	      %O     The number	of output operations.
	      %r     The number	of socket messages received.
	      %s     The number	of socket messages sent.
	      %k     The number	of signals received.
	      %w     Number of voluntary context switches (waits).
	      %c     Number of involuntary context switches.
	      %J     The name of this job.

	      A	star may be inserted between the percent sign and flags	print-
	      ing time.	 This cause the	time to	be printed  in	`hh:mm:ss.ttt'
	      format  (hours  and  minutes  are	 only  printed if they are not
	      zero).

       TMOUT  If this parameter	is nonzero, the	shell  will  receive  an  ALRM
	      signal  if  a command is not entered within the specified	number
	      of seconds after issuing	a  prompt.  If	there  is  a  trap  on
	      SIGALRM,	it will	be executed and	a new alarm is scheduled using
	      the value	of the 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 TMOUT parameter, zsh  terminates.	Other-
	      wise  a  new  alarm is scheduled to TMOUT	seconds	after the last
	      keypress.

       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
	      `/tmp/zsh'.

       TMPSUFFIX
	      A	 filename  suffix which	the shell will use for temporary files
	      created by process substitutions (e.g., `=(list)').   Note  that
	      the value	should include a leading dot `.' if intended to	be in-
	      terpreted	as a file extension.  The default is not to append any
	      suffix,  thus this parameter should be assigned only when	needed
	      and then unset again.

       watch _S_ _Z_ (WATCH _S_)
	      An array (colon-separated	list) of login/logout  events  to  re-
	      port.

	      If  it  contains	the  single  word `all', then all login/logout
	      events are reported.  If it contains the	single	word  `notme',
	      then all events are reported as with `all' except	$USERNAME.

	      An entry in this list may	consist	of a username, an `@' followed
	      by a remote hostname, and	a `%' followed by a line  (tty).   Any
	      of  these	may be a pattern (be sure to quote this	during the as-
	      signment to watch	so that	it does	not immediately	 perform  file
	      generation);  the	 setting  of  the  EXTENDED_GLOB option	is re-
	      spected.	Any or all of these components may be  present	in  an
	      entry;  if  a  login/logout event	matches	all of them, it	is re-
	      ported.

	      For example, with	the EXTENDED_GLOB option set, the following:

		     watch=('^(pws|barts)')

	      causes reports for activity assoicated with any user other  than
	      pws or barts.

       WATCHFMT
	      The  format  of  login/logout  reports if	the watch parameter is
	      set.  Default is `%n has %a %l from %m'.	Recognizes the follow-
	      ing escape sequences:

	      %n     The name of the user that logged in/out.

	      %a     The observed action, i.e. "logged on" or "logged off".

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

	      %M     The full hostname of the remote host.

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

		     NOTE:  The	 `%m' and `%M' escapes will work only if there
		     is	a host name field in the utmp on your machine.	Other-
		     wise they are treated as ordinary strings.

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

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

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

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

	      %T     The time, in 24-hour format.

	      %w     The date in `day-dd' format.

	      %W     The date in `mm/dd/yy' format.

	      %D     The date in `yy-mm-dd' format.

	      %D{string}
		     The date formatted	as string using	the strftime function,
		     with zsh extensions as described by EXPANSION  OF	PROMPT
		     SEQUENCES in zshmisc(1).

	      %(x:true-text:false-text)
		     Specifies	a ternary expression.  The character following
		     the x is arbitrary; the same character is used  to	 sepa-
		     rate  the	text  for  the "true" result from that for the
		     "false" result.  Both the separator and the right	paren-
		     thesis  may be escaped with a backslash.  Ternary expres-
		     sions may be nested.

		     The test character	x may be any one of `l', `n',  `m'  or
		     `M',  which indicate a `true' result if the corresponding
		     escape sequence would return a non-empty value; or	it may
		     be	 `a',  which  indicates	a `true' result	if the watched
		     user has logged in, or `false'  if	 he  has  logged  out.
		     Other  characters evaluate	to neither true	nor false; the
		     entire expression is omitted in this case.

		     If	the result is `true', then the true-text is  formatted
		     according	to  the	 rules	above  and  printed,  and  the
		     false-text	is skipped.   If  `false',  the	 true-text  is
		     skipped and the false-text	is formatted and printed.  Ei-
		     ther or both of the branches may be empty,	but both sepa-
		     rators must be present in any case.

       WORDCHARS <S>
	      A	 list of non-alphanumeric characters considered	part of	a word
	      by the line editor.

       ZBEEP  If set, this gives a string of characters, which can use all the
	      same  codes  as  the bindkey command as described	in the zsh/zle
	      module entry in zshmodules(1), that will be output to the	termi-
	      nal  instead  of beeping.	 This may have a visible instead of an
	      audible effect; for example,  the	 string	 `\e[?5h\e[?5l'	 on  a
	      vt100 or xterm will have the effect of flashing reverse video on
	      and off (if you usually use reverse video, you  should  use  the
	      string  `\e[?5l\e[?5h' instead).	This takes precedence over the
	      NOBEEP option.

       ZDOTDIR
	      The directory to search for shell	startup	files  (.zshrc,	 etc),
	      if not $HOME.

       zle_bracketed_paste
	      Many  terminal emulators have a feature that allows applications
	      to identify when text is pasted into the	terminal  rather  than
	      being  typed  normally. For ZLE, this means that special charac-
	      ters such	as tabs	and newlines can be inserted instead of	invok-
	      ing  editor  commands.   Furthermore, pasted text	forms a	single
	      undo event and if	the region is active, pasted text will replace
	      the region.

	      This  two-element	 array	contains the terminal escape sequences
	      for enabling and disabling the feature. These  escape  sequences
	      are  used	 to enable bracketed paste when	ZLE is active and dis-
	      able it at other times.  Unsetting the parameter has the	effect
	      of ensuring that bracketed paste remains disabled.

       zle_highlight
	      An  array	 describing contexts in	which ZLE should highlight the
	      input text.  See Character Highlighting in zshzle(1).

       ZLE_LINE_ABORTED
	      This parameter is	set by the line	editor when an	error  occurs.
	      It  contains  the	line that was being edited at the point	of the
	      error.  `print -zr -- $ZLE_LINE_ABORTED' can be used to  recover
	      the line.	 Only the most recent line of this kind	is remembered.

       ZLE_REMOVE_SUFFIX_CHARS
       ZLE_SPACE_SUFFIX_CHARS
	      These  parameters	 are used by the line editor.  In certain cir-
	      cumstances suffixes (typically space or slash) added by the com-
	      pletion system will be removed automatically, either because the
	      next editing command was not an insertable character, or because
	      the character was	marked as requiring the	suffix to be removed.

	      These  variables	can  contain  the sets of characters that will
	      cause the	suffix to be removed.  If  ZLE_REMOVE_SUFFIX_CHARS  is
	      set,  those  characters  will cause the suffix to	be removed; if
	      ZLE_SPACE_SUFFIX_CHARS is	set, those characters will  cause  the
	      suffix to	be removed and replaced	by a space.

	      If  ZLE_REMOVE_SUFFIX_CHARS is not set, the default behaviour is
	      equivalent to:

		     ZLE_REMOVE_SUFFIX_CHARS=$'	\t\n;&|'

	      If ZLE_REMOVE_SUFFIX_CHARS is set	but is	empty,	no  characters
	      have  this  behaviour.  ZLE_SPACE_SUFFIX_CHARS takes precedence,
	      so that the following:

		     ZLE_SPACE_SUFFIX_CHARS=$'&|'

	      causes the characters `&'	and `|'	to remove the  suffix  but  to
	      replace it with a	space.

	      To  illustrate  the difference, suppose that the option AUTO_RE-
	      MOVE_SLASH is in effect and the directory	DIR has	just been com-
	      pleted,  with an appended	/, following which the user types `&'.
	      The default result is `DIR&'.  With ZLE_REMOVE_SUFFIX_CHARS  set
	      but   without   including	 `&'  the  result  is  `DIR/&'.	  With
	      ZLE_SPACE_SUFFIX_CHARS set to include `&'	the result is `DIR &'.

	      Note that	certain	completions may	provide	their own  suffix  re-
	      moval  or	 replacement  behaviour	which overrides	the values de-
	      scribed here.  See the completion	system documentation  in  zsh-
	      compsys(1).

       ZLE_RPROMPT_INDENT <S>
	      If set, used to give the indentation between the right hand side
	      of the right prompt in the line  editor  as  given  by  RPS1  or
	      RPROMPT  and the right hand side of the screen.  If not set, the
	      value 1 is used.

	      Typically	this will be used to set the value to 0	 so  that  the
	      prompt  appears  flush  with  the	right hand side	of the screen.
	      This is not the default as many terminals	 do  not  handle  this
	      correctly,  in particular	when the prompt	appears	at the extreme
	      bottom right of the screen.  Recent virtual terminals  are  more
	      likely  to  handle this case correctly.  Some experimentation is
	      necessary.

ZSHOPTIONS(1)		    General Commands Manual		 ZSHOPTIONS(1)

NAME
       zshoptions - zsh	options

SPECIFYING OPTIONS
       Options are primarily referred to by name.  These names are case	insen-
       sitive and underscores are ignored.  For	example, `allexport' is	equiv-
       alent to	`A__lleXP_ort'.

       The sense of an option name may be inverted by preceding	it with	 `no',
       so  `setopt  No_Beep' is	equivalent to `unsetopt	beep'.	This inversion
       can only	be done	once, so `nonobeep' is not a synonym for `beep'.  Sim-
       ilarly,	`tify'	is not a synonym for `nonotify'	(the inversion of `no-
       tify').

       Some options also have one or more single letter	names.	There are  two
       sets of single letter options: one used by default, and another used to
       emulate sh/ksh (used when the SH_OPTION_LETTERS option  is  set).   The
       single  letter  options	can be used on the shell command line, or with
       the set,	setopt and unsetopt builtins, as normal	Unix options  preceded
       by `-'.

       The sense of the	single letter options may be inverted by using `+' in-
       stead of	`-'.  Some of the single letter	option names refer to  an  op-
       tion  being off,	in which case the inversion of that name refers	to the
       option being on.	 For example, `+n' is the short	name  of  `exec',  and
       `-n' is the short name of its inversion,	`noexec'.

       In  strings  of single letter options supplied to the shell at startup,
       trailing	whitespace will	be ignored; for	example	the  string  `-f     '
       will  be	treated	just as	`-f', but the string `-f i' is an error.  This
       is because many systems which implement the `#!'	mechanism for  calling
       scripts do not strip trailing whitespace.

DESCRIPTION OF OPTIONS
       In  the	following  list,  options set by default in all	emulations are
       marked <D>; those set by	default	only in	csh, ksh, sh,  or  zsh	emula-
       tions  are  marked <C>, <K>, <S>, <Z> as	appropriate.  When listing op-
       tions (by `setopt', `unsetopt', `set -o'	or `set	+o'), those turned  on
       by  default  appear  in	the  list  prefixed  with `no'.	 Hence (unless
       KSH_OPTION_PRINT	is set), `setopt' shows	all options whose settings are
       changed from the	default.

   Changing Directories
       AUTO_CD (-J)
	      If  a  command is	issued that can't be executed as a normal com-
	      mand, and	the command is the name	of a directory,	perform	the cd
	      command  to  that	 directory.  This option is only applicable if
	      the option SHIN_STDIN is set, i.e. if commands  are  being  read
	      from  standard  input.   The  option is designed for interactive
	      use; it is recommended that cd be	used explicitly	in scripts  to
	      avoid ambiguity.

       AUTO_PUSHD (-N)
	      Make cd push the old directory onto the directory	stack.

       CDABLE_VARS (-T)
	      If  the  argument	 to  a	cd  command (or	an implied cd with the
	      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	`~' (see the section `Filename Expansion').

       CHASE_DOTS
	      When changing to a directory  containing	a  path	 segment  `..'
	      which  would otherwise be	treated	as canceling the previous seg-
	      ment in the path (in other words,	`foo/..' would be removed from
	      the  path,  or  if  `..' is the first part of the	path, the last
	      part of the current working directory would be removed), instead
	      resolve  the  path  to  the  physical directory.	This option is
	      overridden by CHASE_LINKS.

	      For example,  suppose  /foo/bar  is  a  link  to	the  directory
	      /alt/rod.	  Without this option set, `cd /foo/bar/..' changes to
	      /foo; with it set, it changes to /alt.  The same applies if  the
	      current  directory  is  /foo/bar and `cd ..' is used.  Note that
	      all other	symbolic links in the path will	also be	resolved.

       CHASE_LINKS (-w)
	      Resolve symbolic links to	their true values when changing	direc-
	      tory.   This also	has the	effect of CHASE_DOTS, i.e. a `..' path
	      segment will be treated as referring  to	the  physical  parent,
	      even if the preceding path segment is a symbolic link.

       POSIX_CD	<K> <S>
	      Modifies	the  behaviour of cd, chdir and	pushd commands to make
	      them more	compatible with	the POSIX standard. The	behaviour with
	      the  option  unset  is described in the documentation for	the cd
	      builtin in zshbuiltins(1).  If the option	is set,	the shell does
	      not test for directories beneath the local directory (`.') until
	      after all	directories in cdpath have been	tested.

	      Also, if the option is set, the conditions under which the shell
	      prints  the new directory	after changing to it are modified.  It
	      is no longer restricted to interactive shells (although printing
	      of  the  directory stack with pushd is still limited to interac-
	      tive shells); and	any use	of a component of CDPATH, including  a
	      `.'  but	excluding an empty component that is otherwise treated
	      as `.', causes the directory to be printed.

       PUSHD_IGNORE_DUPS
	      Don't push multiple copies of the	same directory onto the	direc-
	      tory stack.

       PUSHD_MINUS
	      Exchanges	the meanings of	`+' and	`-' when used with a number to
	      specify a	directory in the stack.

       PUSHD_SILENT (-E)
	      Do not print the directory stack after pushd or popd.

       PUSHD_TO_HOME (-D)
	      Have pushd with no arguments act like `pushd $HOME'.

   Completion
       ALWAYS_LAST_PROMPT <D>
	      If unset,	key functions that list	completions try	to  return  to
	      the  last	prompt if given	a numeric argument. If set these func-
	      tions try	to return to the last prompt if	given no numeric argu-
	      ment.

       ALWAYS_TO_END
	      If  a completion is performed with the cursor within a word, and
	      a	full completion	is inserted, the cursor	is moved to the	end of
	      the  word.   That	is, the	cursor is moved	to the end of the word
	      if either	a single match is inserted or menu completion is  per-
	      formed.

       AUTO_LIST (-9) <D>
	      Automatically list choices on an ambiguous completion.

       AUTO_MENU <D>
	      Automatically  use  menu completion after	the second consecutive
	      request for completion, for example by pressing the tab key  re-
	      peatedly.	This option is overridden by MENU_COMPLETE.

       AUTO_NAME_DIRS
	      Any  parameter  that  is set to the absolute name	of a directory
	      immediately becomes a name for that directory, that will be used
	      by  the `%~' and related prompt sequences, and will be available
	      when completion is performed on a	word starting with `~'.	 (Oth-
	      erwise, the parameter must be used in the	form `~param' first.)

       AUTO_PARAM_KEYS <D>
	      If  a  parameter	name  was  completed and a following character
	      (normally	a space) automatically inserted, and the next  charac-
	      ter  typed  is one of those that have to come directly after the
	      name (like `}', `:', etc.), the automatically added character is
	      deleted, so that the character typed comes immediately after the
	      parameter	name.  Completion in a	brace  expansion  is  affected
	      similarly:  the  added character is a `,', which will be removed
	      if `}' is	typed next.

       AUTO_PARAM_SLASH	<D>
	      If a parameter is	completed whose	content	is the name of	a  di-
	      rectory, then add	a trailing slash instead of a space.

       AUTO_REMOVE_SLASH <D>
	      When  the	 last character	resulting from a completion is a slash
	      and the next character typed is a	word delimiter,	a slash, or  a
	      character	 that ends a command (such as a	semicolon or an	amper-
	      sand), remove the	slash.

       BASH_AUTO_LIST
	      On an ambiguous completion, automatically	list choices when  the
	      completion  function  is called twice in succession.  This takes
	      precedence over AUTO_LIST.  The setting of LIST_AMBIGUOUS	is re-
	      spected.	 If  AUTO_MENU	is  set,  the menu behaviour will then
	      start with the third press.  Note	that this will not  work  with
	      MENU_COMPLETE, since repeated completion calls immediately cycle
	      through the list in that case.

       COMPLETE_ALIASES
	      Prevents aliases on the command line from	being internally  sub-
	      stituted	before completion is attempted.	 The effect is to make
	      the alias	a distinct command for completion purposes.

       COMPLETE_IN_WORD
	      If unset,	the cursor is set to the end of	the word if completion
	      is started. Otherwise it stays there and completion is done from
	      both ends.

       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  MENU_COMPLETE.  The
	      matches  are  generated  as if a `*' was added to	the end	of the
	      word, or inserted	at the cursor when  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.

	      Note  that  when	the  pattern matcher is	used, matching control
	      (for example, case-insensitive or	anchored matching)  cannot  be
	      used.   This  limitation only applies when the current word con-
	      tains a pattern; simply turning on the GLOB_COMPLETE option does
	      not have this effect.

       HASH_LIST_ALL <D>
	      Whenever	a  command  completion	or  spelling correction	is at-
	      tempted, make sure the entire  command  path  is	hashed	first.
	      This  makes the first completion slower but avoids false reports
	      of spelling errors.

       LIST_AMBIGUOUS <D>
	      This option works	when AUTO_LIST or BASH_AUTO_LIST is also  set.
	      If there is an unambiguous prefix	to insert on the command line,
	      that is done without a completion	list being displayed; in other
	      words,  auto-listing  behaviour  only  takes  place when nothing
	      would be inserted.  In the case of  BASH_AUTO_LIST,  this	 means
	      that the list will be delayed to the third call of the function.

       LIST_BEEP <D>
	      Beep  on	an ambiguous completion.  More accurately, this	forces
	      the completion widgets to	return status 1	on an  ambiguous  com-
	      pletion,	which  causes  the shell to beep if the	option BEEP is
	      also set;	this may be modified if	completion is  called  from  a
	      user-defined widget.

       LIST_PACKED
	      Try  to  make the	completion list	smaller	(occupying less	lines)
	      by printing the matches in columns with different	widths.

       LIST_ROWS_FIRST
	      Lay out the matches in  completion  lists	 sorted	 horizontally,
	      that  is,	the second match is to the right of the	first one, not
	      under it as usual.

       LIST_TYPES (-X) <D>
	      When listing files that are possible completions,	show the  type
	      of each file with	a trailing identifying mark.

       MENU_COMPLETE (-Y)
	      On  an ambiguous completion, instead of listing possibilities or
	      beeping, insert the first	match immediately.  Then when  comple-
	      tion  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.  reverse-menu-complete may be used to loop
	      through the list in the other direction. This  option  overrides
	      AUTO_MENU.

       REC_EXACT (-S)
	      In  completion, recognize	exact matches even if they are ambigu-
	      ous.

   Expansion and Globbing
       BAD_PATTERN (+2)	<C> <Z>
	      If a pattern for filename	generation is badly formed,  print  an
	      error  message.	(If  this option is unset, the pattern will be
	      left unchanged.)

       BARE_GLOB_QUAL <Z>
	      In a glob	pattern, treat a trailing  set	of  parentheses	 as  a
	      qualifier	 list,	if it contains no `|', `(' or (if special) `~'
	      characters.  See the section `Filename Generation'.

       BRACE_CCL
	      Expand expressions in braces which would not  otherwise  undergo
	      brace  expansion	to a lexically ordered list of all the charac-
	      ters.  See the section `Brace Expansion'.

       CASE_GLOB <D>
	      Make globbing (filename generation)  sensitive  to  case.	  Note
	      that  other  uses	 of patterns are always	sensitive to case.  If
	      the option is unset, the presence	of any character which is spe-
	      cial  to	filename generation will cause case-insensitive	match-
	      ing.  For	example, cvs(/)	can match the directory	CVS  owing  to
	      the   presence   of   the	  globbing  flag  (unless  the	option
	      BARE_GLOB_QUAL is	unset).

       CASE_MATCH <D>
	      Make regular expressions using the zsh/regex  module  (including
	      matches with =~) sensitive to case.

       CSH_NULL_GLOB <C>
	      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 NO-
	      MATCH.

       EQUALS <Z>
	      Perform =	filename expansion.  (See the section `Filename	Expan-
	      sion'.)

       EXTENDED_GLOB
	      Treat  the  `#',	`~' and	`^' characters as part of patterns for
	      filename generation, etc.	 (An initial unquoted `~' always  pro-
	      duces named directory expansion.)

       FORCE_FLOAT
	      Constants	 in  arithmetic	evaluation will	be treated as floating
	      point even without the use of a decimal point; the values	of in-
	      teger variables will be converted	to floating point when used in
	      arithmetic expressions.  Integers	in any base will be converted.

       GLOB (+F, ksh: +f) <D>
	      Perform filename generation (globbing).  (See the	section	`File-
	      name Generation'.)

       GLOB_ASSIGN <C>
	      If  this	option	is set,	filename generation (globbing) is per-
	      formed on	the right hand side of scalar parameter	assignments of
	      the  form	 `name=pattern (e.g. `foo=*').	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 com-
	      patibility only: globbing	is always performed on the right  hand
	      side  of	array  assignments  of	the  form `name=(value)' (e.g.
	      `foo=(*)') 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.

       GLOB_DOTS (-4)
	      Do not require a leading `.' in a	filename to be matched explic-
	      itly.

       GLOB_STAR_SHORT
	      When this	option is set and the default zsh-style	globbing is in
	      effect, the pattern `**/*' can be	abbreviated to	`**'  and  the
	      pattern `***/*' can be abbreviated to ***.  Hence	`**.c' finds a
	      file ending in .c	in any subdirectory, and `***.c' does the same
	      while  also following symbolic links.  A / immediately after the
	      `**' or `***' forces the pattern to be treated as	the unabbrevi-
	      ated form.

       GLOB_SUBST <C> <K> <S>
	      Treat any	characters resulting from parameter expansion as being
	      eligible for filename expansion and filename generation, and any
	      characters resulting from	command	substitution as	being eligible
	      for filename generation.	Braces (and commas in between) do  not
	      become eligible for expansion.

       HIST_SUBST_PATTERN
	      Substitutions  using  the	 :s  and :& history modifiers are per-
	      formed with pattern matching instead of string  matching.	  This
	      occurs  wherever	history	 modifiers  are	 valid,	including glob
	      qualifiers and parameters.  See the section  Modifiers  in  zsh-
	      expn(1).

       IGNORE_BRACES (-I) <S>
	      Do  not  perform	brace  expansion.  For historical reasons this
	      also includes the	effect of the IGNORE_CLOSE_BRACES option.

       IGNORE_CLOSE_BRACES
	      When neither this	option nor IGNORE_BRACES is set, a sole	 close
	      brace character `}' is syntactically significant at any point on
	      a	command	line.  This has	the effect that	no semicolon  or  new-
	      line  is	necessary  before  the brace terminating a function or
	      current shell construct.	When either option is set,  a  closing
	      brace  is	 syntactically	significant  only in command position.
	      Unlike IGNORE_BRACES, this option	does not disable brace	expan-
	      sion.

	      For  example,  with both options unset a function	may be defined
	      in the following fashion:

		     args() { echo $# }

	      while if either option is	set, this does not work	and  something
	      equivalent to the	following is required:

		     args() { echo $#; }

       KSH_GLOB	<K>
	      In  pattern  matching,  the interpretation of parentheses	is af-
	      fected by	a preceding `@', `*', `+', `?' or `!'.	See  the  sec-
	      tion `Filename Generation'.

       MAGIC_EQUAL_SUBST
	      All unquoted arguments of	the form `anything=expression' appear-
	      ing after	the command name have  filename	 expansion  (that  is,
	      where  expression	has a leading `~' or `=') performed on expres-
	      sion as if it were a parameter assignment.  The argument is  not
	      otherwise	 treated  specially;  it is passed to the command as a
	      single argument, and not used as an actual parameter assignment.
	      For  example,  in	 echo  foo=~/bar:~/rod,	 both occurrences of ~
	      would be replaced.  Note that this happens anyway	 with  typeset
	      and similar statements.

	      This  option respects the	setting	of the KSH_TYPESET option.  In
	      other words, if both options are in  effect,  arguments  looking
	      like assignments will not	undergo	word splitting.

       MARK_DIRS (-8, ksh: -X)
	      Append  a	 trailing  `/'	to  all	directory names	resulting from
	      filename generation (globbing).

       MULTIBYTE <D>
	      Respect multibyte	characters when	found in strings.   When  this
	      option  is set, strings are examined using the system library to
	      determine	how many bytes form a character, depending on the cur-
	      rent  locale.   This  affects  the way characters	are counted in
	      pattern matching,	parameter values and various delimiters.

	      The option is on by default  if  the  shell  was	compiled  with
	      MULTIBYTE_SUPPORT; otherwise it is off by	default	and has	no ef-
	      fect if turned on.

	      If the option is off a single byte is always treated as a	single
	      character.   This	 setting  is  designed	purely	for  examining
	      strings known to contain raw bytes or other values that may  not
	      be characters in the current locale.  It is not necessary	to un-
	      set the option merely because the	character set for the  current
	      locale does not contain multibyte	characters.

	      The  option  does	 not  affect the shell's editor,  which	always
	      uses the locale to determine multibyte characters.  This is  be-
	      cause  the  character  set displayed by the terminal emulator is
	      independent of shell settings.

       NOMATCH (+3) <C>	<Z>
	      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	`~' or `='.

       NULL_GLOB (-G)
	      If a pattern for filename	generation has no matches, delete  the
	      pattern  from  the  argument list	instead	of reporting an	error.
	      Overrides	NOMATCH.

       NUMERIC_GLOB_SORT
	      If numeric filenames are matched by a filename  generation  pat-
	      tern,  sort  the filenames numerically rather than lexicographi-
	      cally.

       RC_EXPAND_PARAM (-P)
	      Array expansions of the form `foo${xx}bar', where	the  parameter
	      xx  is  set  to  (a  b c), are substituted with `fooabar foobbar
	      foocbar' instead of the default `fooa b  cbar'.	Note  that  an
	      empty array will therefore cause all arguments to	be removed.

       REMATCH_PCRE <Z>
	      If  set,	regular	 expression matching with the =~ operator will
	      use Perl-Compatible Regular Expressions from the	PCRE  library,
	      if  available.  If not set, regular expressions will use the ex-
	      tended regexp syntax provided by the system libraries.

       SH_GLOB <K> <S>
	      Disables the special meaning of `(', `|',	`)' and	'<' for	 glob-
	      bing  the	 result	of parameter and command substitutions,	and in
	      some other places	where the shell	accepts	patterns.  If  SH_GLOB
	      is  set but KSH_GLOB is not, the shell allows the	interpretation
	      of subshell expressions enclosed in parentheses  in  some	 cases
	      where  there  is	no  space before the opening parenthesis, e.g.
	      !(true) is interpreted as	if there were a	 space	after  the  !.
	      This option is set by default if zsh is invoked as sh or ksh.

       UNSET (+u, ksh: +u) <K> <S> <Z>
	      Treat  unset parameters as if they were empty when substituting.
	      Otherwise	they are treated as an error.

       WARN_CREATE_GLOBAL
	      Print a warning message when a global parameter is created in  a
	      function	by an assignment or in math context.  This often indi-
	      cates that a parameter has  not  been  declared  local  when  it
	      should  have  been.   Parameters explicitly declared global from
	      within a function	using typeset -g do not	cause a	warning.  Note
	      that  there  is no warning when a	local parameter	is assigned to
	      in a nested function, which may also indicate an error.

   History
       APPEND_HISTORY <D>
	      If this is set, zsh sessions will	append their history  list  to
	      the  history file, rather	than replace it. Thus, multiple	paral-
	      lel zsh sessions will all	have the new entries from  their  his-
	      tory  lists  added  to  the history file,	in the order that they
	      exit.  The file will still be periodically re-written to trim it
	      when the number of lines grows 20% beyond	the value specified by
	      $SAVEHIST	(see also the HIST_SAVE_BY_COPY	option).

       BANG_HIST (+K) <C> <Z>
	      Perform textual history expansion, csh-style, treating the char-
	      acter `!'	specially.

       EXTENDED_HISTORY	<C>
	      Save  each  command's  beginning timestamp (in seconds since the
	      epoch) and the duration (in seconds) to the history  file.   The
	      format of	this prefixed data is:

	      `: _beginning time_:_elapsed seconds_;_command_'.

       HIST_ALLOW_CLOBBER
	      Add `|' to output	redirections in	the history.  This allows his-
	      tory references to clobber files even when CLOBBER is unset.

       HIST_BEEP <D>
	      Beep in ZLE when a widget	attempts to  access  a	history	 entry
	      which isn't there.

       HIST_EXPIRE_DUPS_FIRST
	      If  the  internal	history	needs to be trimmed to add the current
	      command line, setting this option	will cause the oldest  history
	      event  that  has	a  duplicate to	be lost	before losing a	unique
	      event from the list.  You	should be sure to  set	the  value  of
	      HISTSIZE	to  a larger number than SAVEHIST in order to give you
	      some room	for the	duplicated events, otherwise this option  will
	      behave  just like	HIST_IGNORE_ALL_DUPS once the history fills up
	      with unique events.

       HIST_FCNTL_LOCK
	      When writing out the history file, by default  zsh  uses	ad-hoc
	      file  locking to avoid known problems with locking on some oper-
	      ating systems.  With this	option locking is done by means	of the
	      system's	fcntl call, where this method is available.  On	recent
	      operating	systems	this may provide better	performance,  in  par-
	      ticular  avoiding	 history  corruption  when files are stored on
	      NFS.

       HIST_FIND_NO_DUPS
	      When searching for history entries in the	line  editor,  do  not
	      display  duplicates  of a	line previously	found, even if the du-
	      plicates are not contiguous.

       HIST_IGNORE_ALL_DUPS
	      If a new command line being added	to the history list duplicates
	      an  older	 one, the older	command	is removed from	the list (even
	      if it is not the previous	event).

       HIST_IGNORE_DUPS	(-h)
	      Do not enter command lines into the history list if they are du-
	      plicates of the previous event.

       HIST_IGNORE_SPACE (-g)
	      Remove  command lines from the history list when the first char-
	      acter on the line	is a  space,  or  when	one  of	 the  expanded
	      aliases  contains	 a  leading  space.   Only normal aliases (not
	      global or	suffix aliases)	have this behaviour.   Note  that  the
	      command  lingers	in the internal	history	until the next command
	      is entered before	it vanishes, allowing you to briefly reuse  or
	      edit the line.  If you want to make it vanish right away without
	      entering another command,	type a space and press return.

       HIST_LEX_WORDS
	      By default, shell	history	that is	read in	from  files  is	 split
	      into  words  on all white	space.	This means that	arguments with
	      quoted whitespace	are not	correctly  handled,  with  the	conse-
	      quence  that references to words in history lines	that have been
	      read from	a file may be inaccurate.  When	this  option  is  set,
	      words  read  in  from a history file are divided up in a similar
	      fashion to normal	shell command line  handling.	Although  this
	      produces	more  accurately  delimited  words, if the size	of the
	      history file is large this can be	slow.  Trial and error is nec-
	      essary to	decide.

       HIST_NO_FUNCTIONS
	      Remove  function	definitions  from the history list.  Note that
	      the function lingers in the internal history until the next com-
	      mand  is entered before it vanishes, allowing you	to briefly re-
	      use or edit the definition.

       HIST_NO_STORE
	      Remove the history (fc -l) command from the  history  list  when
	      invoked.	 Note that the command lingers in the internal history
	      until the	next command is	entered	before it  vanishes,  allowing
	      you to briefly reuse or edit the line.

       HIST_REDUCE_BLANKS
	      Remove  superfluous blanks from each command line	being added to
	      the history list.

       HIST_SAVE_BY_COPY <D>
	      When the history file is re-written, we  normally	 write	out  a
	      copy of the file named $HISTFILE.new and then rename it over the
	      old one.	However, if this option	is unset, we instead  truncate
	      the old history file and write out the new version in-place.  If
	      one of the history-appending options  is	enabled,  this	option
	      only  has	 an  effect when the enlarged history file needs to be
	      re-written to trim it down to size.  Disable this	 only  if  you
	      have  special  needs, as doing so	makes it possible to lose his-
	      tory entries if zsh gets interrupted during the save.

	      When writing out a copy of the history file, zsh	preserves  the
	      old file's permissions and group information, but	will refuse to
	      write out	a new file if  it  would  change  the  history	file's
	      owner.

       HIST_SAVE_NO_DUPS
	      When writing out the history file, older commands	that duplicate
	      newer ones are omitted.

       HIST_VERIFY
	      Whenever the user	enters a line with  history  expansion,	 don't
	      execute  the  line  directly; instead, perform history expansion
	      and reload the line into the editing buffer.

       INC_APPEND_HISTORY
	      This options works like APPEND_HISTORY except that  new  history
	      lines  are added to the $HISTFILE	incrementally (as soon as they
	      are entered), rather than	waiting	until the  shell  exits.   The
	      file  will  still	be periodically	re-written to trim it when the
	      number of	lines grows 20%	beyond the value specified  by	$SAVE-
	      HIST (see	also the HIST_SAVE_BY_COPY option).

       INC_APPEND_HISTORY_TIME
	      This  option  is a variant of INC_APPEND_HISTORY in which, where
	      possible,	the history entry is written out to the	file after the
	      command  is  finished,  so that the time taken by	the command is
	      recorded correctly in the	history	file in	EXTENDED_HISTORY  for-
	      mat.   This  means  that the history entry will not be available
	      immediately from other instances of the shell that are using the
	      same history file.

	      This  option is only useful if INC_APPEND_HISTORY	and SHARE_HIS-
	      TORY are turned off.  The	three options should be	considered mu-
	      tually exclusive.

       SHARE_HISTORY <K>

	      This option both imports new commands from the history file, and
	      also causes your typed commands to be appended  to  the  history
	      file  (the  latter  is like specifying INC_APPEND_HISTORY, which
	      should be	turned off if this option is in	effect).  The  history
	      lines  are  also	output	with  timestamps  ala EXTENDED_HISTORY
	      (which makes it easier to	find the spot where we left off	 read-
	      ing the file after it gets re-written).

	      By  default,  history movement commands visit the	imported lines
	      as well as the local lines, but you can toggle this on  and  off
	      with  the	set-local-history zle binding.	It is also possible to
	      create a zle widget that will make some commands ignore imported
	      commands,	and some include them.

	      If  you  find  that you want more	control	over when commands get
	      imported,	you  may  wish	to  turn  SHARE_HISTORY	 off,  INC_AP-
	      PEND_HISTORY or INC_APPEND_HISTORY_TIME (see above) on, and then
	      manually import commands whenever	you need them using `fc	-RI'.

   Initialisation
       ALL_EXPORT (-a, ksh: -a)
	      All parameters subsequently defined are automatically exported.

       GLOBAL_EXPORT <Z>
	      If this option is	set, passing the -x flag to the	 builtins  de-
	      clare, float, integer, readonly and typeset (but not local) will
	      also set the -g flag;  hence parameters exported to the environ-
	      ment  will  not  be made local to	the enclosing function,	unless
	      they were	already	or the flag +g is given	 explicitly.   If  the
	      option  is unset,	exported parameters will be made local in just
	      the same way as any other	parameter.

	      This option is set by default for	backward compatibility;	it  is
	      not  recommended	that  its behaviour be relied upon.  Note that
	      the builtin export always	sets both the -x  and  -g  flags,  and
	      hence its	effect extends beyond the scope	of the enclosing func-
	      tion; this is the	most portable way to achieve this behaviour.

       GLOBAL_RCS (-d) <D>
	      If this  option  is  unset,  the	startup	 files	/etc/zprofile,
	      /etc/zshrc,  /etc/zlogin	and  /etc/zlogout will not be run.  It
	      can be disabled and re-enabled at	any time, including inside lo-
	      cal startup files	(.zshrc, etc.).

       RCS (+f)	<D>
	      After  /etc/zshenv  is  sourced  on startup, source the .zshenv,
	      /etc/zprofile, .zprofile,	/etc/zshrc, .zshrc, /etc/zlogin, .zlo-
	      gin,  and	 .zlogout  files, as described in the section `Files'.
	      If this option is	unset, the /etc/zshenv file is still  sourced,
	      but  any of the others will not be; it can be set	at any time to
	      prevent the remaining startup files after	the currently  execut-
	      ing one from being sourced.

   Input/Output
       ALIASES <D>
	      Expand aliases.

       CLOBBER (+C, ksh: +C) <D>
	      Allows  `>'  redirection	to truncate existing files.  Otherwise
	      `>!' or `>|' must	be used	to truncate a file.

	      If the option is not set,	and the	option APPEND_CREATE  is  also
	      not  set,	 `>>!' or `>>|'	must be	used to	create a file.	If ei-
	      ther option is set, `>>' may be used.

       CORRECT (-0)
	      Try to correct the spelling of commands.	Note  that,  when  the
	      HASH_LIST_ALL  option is not set or when some directories	in the
	      path are not readable, this may falsely report  spelling	errors
	      the first	time some commands are used.

	      The  shell  variable  CORRECT_IGNORE  may	be set to a pattern to
	      match words that will never be offered as	corrections.

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

	      The shell	variable CORRECT_IGNORE_FILE may be set	to  a  pattern
	      to match file names that will never be offered as	corrections.

       DVORAK Use  the Dvorak keyboard instead of the standard qwerty keyboard
	      as a basis for examining spelling	mistakes for the  CORRECT  and
	      CORRECT_ALL options and the spell-word editor command.

       FLOW_CONTROL <D>
	      If  this	option	is  unset,  output flow	control	via start/stop
	      characters (usually  assigned  to	 ^S/^Q)	 is  disabled  in  the
	      shell's editor.

       IGNORE_EOF (-7)
	      Do  not  exit on end-of-file.  Require the use of	exit or	logout
	      instead.	However, ten consecutive EOFs will cause the shell  to
	      exit anyway, to avoid the	shell hanging if its tty goes away.

	      Also,  if	 this  option  is set and the Zsh Line Editor is used,
	      widgets implemented by shell functions can be bound to EOF (nor-
	      mally  Control-D)	 without  printing the normal warning message.
	      This works only for normal widgets, not for completion widgets.

       INTERACTIVE_COMMENTS (-k) <K> <S>
	      Allow comments even in interactive shells.

       HASH_CMDS <D>
	      Note the location	of each	command	the first time it is executed.
	      Subsequent  invocations  of  the same command will use the saved
	      location,	avoiding a path	search.	 If this option	is  unset,  no
	      path hashing is done at all.  However, when CORRECT is set, com-
	      mands whose names	do not appear in the functions or aliases hash
	      tables  are  hashed in order to avoid reporting them as spelling
	      errors.

       HASH_DIRS <D>
	      Whenever a command name is hashed, hash the directory containing
	      it,  as  well as all directories that occur earlier in the path.
	      Has no effect if neither HASH_CMDS nor CORRECT is	set.

       HASH_EXECUTABLES_ONLY
	      When hashing commands because of HASH_CMDS, check	that the  file
	      to be hashed is actually an executable.  This option is unset by
	      default as if the	path contains a	large number of	 commands,  or
	      consists	of  many remote	files, the additional tests can	take a
	      long time.  Trial	and error is needed to show if this option  is
	      beneficial.

       MAIL_WARNING (-U)
	      Print  a	warning	message	if a mail file has been	accessed since
	      the shell	last checked.

       PATH_DIRS (-Q)
	      Perform a	path search even on  command  names  with  slashes  in
	      them.  Thus if `/usr/local/bin' is in the	user's path, and he or
	      she types	`X11/xinit',  the  command  `/usr/local/bin/X11/xinit'
	      will  be executed	(assuming it exists).  Commands	explicitly be-
	      ginning with `/',	`./' or	`../' are  not	subject	 to  the  path
	      search.  This also applies to the	`.' and	source builtins.

	      Note  that  subdirectories  of  the current directory are	always
	      searched for executables specified in  this  form.   This	 takes
	      place before any search indicated	by this	option,	and regardless
	      of whether `.' or	the current directory appear  in  the  command
	      search path.

       PATH_SCRIPT <K> <S>
	      If  this option is not set, a script passed as the first non-op-
	      tion argument to the shell must contain the name of the file  to
	      open.   If this option is	set, and the script does not specify a
	      directory	path, the script is looked for first  in  the  current
	      directory, then in the command path.  See	the section INVOCATION
	      in zsh(1).

       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 ctype(3)).

       PRINT_EXIT_VALUE	(-1)
	      Print the	exit value of  programs	 with  non-zero	 exit  status.
	      This  is	only  available	 at  the  command  line	in interactive
	      shells.

       RC_QUOTES
	      Allow the	character sequence `'''	 to  signify  a	 single	 quote
	      within  singly  quoted  strings.	 Note  this  does not apply in
	      quoted strings using the format $'...', where a backslashed sin-
	      gle quote	can be used.

       RM_STAR_SILENT (-H) <K> <S>
	      Do not query the user before executing `rm *' or `rm path/*'.

       RM_STAR_WAIT
	      If  querying  the	 user  before executing	`rm *' or `rm path/*',
	      first wait ten seconds and ignore	anything typed in  that	 time.
	      This  avoids  the	 problem of reflexively	answering `yes'	to the
	      query when one didn't really mean	it.  The wait  and  query  can
	      always be	avoided	by expanding the `*' in	ZLE (with tab).

       SHORT_LOOPS <C> <Z>
	      Allow  the  short	forms of for, repeat, select, if, and function
	      constructs.

       SUN_KEYBOARD_HACK (-L)
	      If a line	ends with a backquote, and there are an	odd number  of
	      backquotes  on the line, ignore the trailing backquote.  This is
	      useful on	some keyboards where the return	key is too small,  and
	      the  backquote  key lies annoyingly close	to it.	As an alterna-
	      tive the variable	KEYBOARD_HACK lets you choose the character to
	      be removed.

   Job Control
       AUTO_CONTINUE
	      With this	option set, stopped jobs that are removed from the job
	      table with the disown builtin command are	automatically  sent  a
	      CONT signal to make them running.

       AUTO_RESUME (-W)
	      Treat  single word simple	commands without redirection as	candi-
	      dates for	resumption of an existing job.

       BG_NICE (-6) <C>	<Z>
	      Run all background jobs at a lower priority.  This option	is set
	      by default.

       CHECK_JOBS <Z>
	      Report  the status of background and suspended jobs before exit-
	      ing a shell with job control; a second attempt to	exit the shell
	      will  succeed.   NO_CHECK_JOBS  is best used only	in combination
	      with NO_HUP, else	such jobs will be killed automatically.

	      The check	is omitted if the commands run from the	previous  com-
	      mand  line  included  a  `jobs' command, since it	is assumed the
	      user is aware that there are background or  suspended  jobs.   A
	      `jobs' command run from one of the hook functions	defined	in the
	      section SPECIAL FUNCTIONS	in zshmisc(1) is not counted for  this
	      purpose.

       HUP <Z>
	      Send the HUP signal to running jobs when the shell exits.

       LONG_LIST_JOBS (-R)
	      List jobs	in the long format by default.

       MONITOR (-m, ksh: -m)
	      Allow job	control.  Set by default in interactive	shells.

       NOTIFY (-5, ksh:	-b) <Z>
	      Report  the  status  of background jobs immediately, rather than
	      waiting until just before	printing a prompt.

       POSIX_JOBS <K> <S>
	      This option makes	job control  more  compliant  with  the	 POSIX
	      standard.

	      When the option is not set, the MONITOR option is	unset on entry
	      to subshells, so that job	control	is no longer active.  When the
	      option  is set, the MONITOR option and job control remain	active
	      in the subshell, but note	that the subshell  has	no  access  to
	      jobs in the parent shell.

	      When  the	option is not set, jobs	put in the background or fore-
	      ground with bg or	fg are displayed  with	the  same  information
	      that  would  be  reported	by jobs.  When the option is set, only
	      the text is printed.  The	output from jobs  itself  is  not  af-
	      fected by	the option.

	      When  the	 option	 is  not  set, job information from the	parent
	      shell is saved for output	within a subshell (for example,	within
	      a	 pipeline).   When  the	 option	 is set, the output of jobs is
	      empty until a job	is started within the subshell.

	      In previous versions of the shell, it was	 necessary  to	enable
	      POSIX_JOBS  in  order for	the builtin command wait to return the
	      status of	background jobs	that had already exited.  This	is  no
	      longer the case.

   Prompting
       PROMPT_BANG <K>
	      If  set,	`!' is treated specially in prompt expansion.  See EX-
	      PANSION OF PROMPT	SEQUENCES in zshmisc(1).

       PROMPT_CR (+V) <D>
	      Print a carriage return just before printing  a  prompt  in  the
	      line  editor.   This  is	on by default as multi-line editing is
	      only possible if the editor knows	where the start	 of  the  line
	      appears.

       PROMPT_SP <D>
	      Attempt to preserve a partial line (i.e. a line that did not end
	      with a newline) that would otherwise be covered up by  the  com-
	      mand  prompt  due	 to  the PROMPT_CR option.  This works by out-
	      putting some cursor-control characters, including	 a  series  of
	      spaces, that should make the terminal wrap to the	next line when
	      a	partial	line is	present	(note that this	is only	successful  if
	      your terminal has	automatic margins, which is typical).

	      When a partial line is preserved,	by default you will see	an in-
	      verse+bold character at the end of the partial line:  a `%'  for
	      a	 normal	 user  or a `#'	for root.  If set, the shell parameter
	      PROMPT_EOL_MARK can be used to customize how the end of  partial
	      lines are	shown.

	      NOTE:  if	 the PROMPT_CR option is not set, enabling this	option
	      will have	no effect.  This option	is on by default.

       PROMPT_PERCENT <C> <Z>
	      If set, `%' is treated specially in prompt expansion.   See  EX-
	      PANSION OF PROMPT	SEQUENCES in zshmisc(1).

       PROMPT_SUBST <K>	<S>
	      If set, parameter	expansion, command substitution	and arithmetic
	      expansion	 are  performed	 in  prompts.	Substitutions	within
	      prompts do not affect the	command	status.

       TRANSIENT_RPROMPT
	      Remove  any  right  prompt from display when accepting a command
	      line.  This may be useful	with terminals	with  other  cut/paste
	      methods.

   Scripts and Functions
       C_BASES
	      Output hexadecimal numbers in the	standard C format, for example
	      `0xFF' instead of	the usual `16#FF'.  If the option OCTAL_ZEROES
	      is  also	set  (it  is  not  by  default), octal numbers will be
	      treated similarly	and hence appear as `077' instead  of  `8#77'.
	      This  option has no effect on the	choice of the output base, nor
	      on the output of bases other than	hexadecimal and	 octal.	  Note
	      that  these  formats will	be understood on input irrespective of
	      the setting of C_BASES.

       C_PRECEDENCES
	      This alters the precedence of arithmetic operators  to  be  more
	      like  C  and other programming languages;	the section ARITHMETIC
	      EVALUATION in zshmisc(1) has an explicit list.

       DEBUG_BEFORE_CMD	<D>
	      Run the DEBUG trap before	each command; otherwise	it is run  af-
	      ter  each	 command.  Setting this	option mimics the behaviour of
	      ksh 93; with the option unset the	behaviour is that of ksh 88.

       ERR_EXIT	(-e, ksh: -e)
	      If a command has a non-zero exit status, execute the ZERR	 trap,
	      if set, and exit.	 This is disabled while	running	initialization
	      scripts.

	      The behaviour is also disabled inside DEBUG traps.  In this case
	      the  option  is  handled	specially: it is unset on entry	to the
	      trap.  If	the option DEBUG_BEFORE_CMD is set, as it  is  by  de-
	      fault,  and  the	option	ERR_EXIT  is found to have been	set on
	      exit, then the command for which the DEBUG trap  is  being  exe-
	      cuted is skipped.	 The option is restored	after the trap exits.

	      Exiting  due to ERR_EXIT has certain interactions	with asynchro-
	      nous jobs	noted in the section JOBS in zshmisc(1).

       ERR_RETURN
	      If a command has a non-zero exit status, return immediately from
	      the  enclosing  function.	  The  logic  is identical to that for
	      ERR_EXIT,	except that an implicit	return statement  is  executed
	      instead  of an exit.  This will trigger an exit at the outermost
	      level of a non-interactive script.

       EVAL_LINENO <Z>
	      If set, line numbers of expressions evaluated using the  builtin
	      eval  are	tracked	separately of the enclosing environment.  This
	      applies both to the parameter LINENO and the line	number	output
	      by  the  prompt escape %i.  If the option	is set,	the prompt es-
	      cape %N will output the string `(eval)' instead of the script or
	      function	name  as  an indication.   (The	two prompt escapes are
	      typically	used in	the parameter PS4 to be	output when the	option
	      XTRACE is	set.)  If EVAL_LINENO is unset,	the line number	of the
	      surrounding script or function is	retained  during  the  evalua-
	      tion.

       EXEC (+n, ksh: +n) <D>
	      Do execute commands.  Without this option, commands are read and
	      checked for syntax errors, but not executed.  This option	cannot
	      be  turned off in	an interactive shell, except when `-n' is sup-
	      plied to the shell at startup.

       FUNCTION_ARGZERO	<C> <Z>
	      When executing a shell function or sourcing  a  script,  set  $0
	      temporarily  to the name of the function/script.	Note that tog-
	      gling FUNCTION_ARGZERO from on to	off (or	off to	on)  does  not
	      change  the  current  value of $0.  Only the state upon entry to
	      the function or script has an effect.  Compare POSIX_ARGZERO.

       LOCAL_LOOPS
	      When this	option is not set, the effect of  break	 and  continue
	      commands	may  propagate outside function	scope, affecting loops
	      in calling functions.  When the option is	set in a calling func-
	      tion,  a	break or a continue that is not	caught within a	called
	      function (regardless of the setting of the  option  within  that
	      function)	produces a warning and the effect is cancelled.

       LOCAL_OPTIONS <K>
	      If  this option is set at	the point of return from a shell func-
	      tion, most options (including this one) which were in force upon
	      entry  to	 the  function	are restored; options that are not re-
	      stored are PRIVILEGED and	RESTRICTED.  Otherwise,	only this  op-
	      tion,  and  the LOCAL_LOOPS, XTRACE and 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.  A shell function can also guarantee itself  a	 known
	      shell  configuration  with  a formulation	like `emulate -L zsh';
	      the -L activates LOCAL_OPTIONS.

       LOCAL_PATTERNS
	      If this option is	set at the point of return from	a shell	 func-
	      tion,  the  state	 of  pattern disables, as set with the builtin
	      command `disable -p', is restored	to what	it was when the	 func-
	      tion  was	 entered.   The	behaviour of this option is similar to
	      the effect of LOCAL_OPTIONS on options; hence  `emulate  -L  sh'
	      (or indeed any other emulation with the -L option) activates LO-
	      CAL_PATTERNS.

       LOCAL_TRAPS <K>
	      If this option is	set when a signal trap is set inside  a	 func-
	      tion,  then the previous status of the trap for that signal will
	      be restored when the function exits.  Note that this option must
	      be  set  prior to	altering the trap behaviour in a function; un-
	      like LOCAL_OPTIONS, the value on exit from the function  is  ir-
	      relevant.	 However, it does not need to be set before any	global
	      trap for that to be correctly restored by	a function.  For exam-
	      ple,

		     unsetopt localtraps
		     trap - INT
		     fn() { setopt localtraps; trap '' INT; sleep 3; }

	      will restore normal handling of SIGINT after the function	exits.

       MULTI_FUNC_DEF <Z>
	      Allow definitions	of multiple functions at once in the form `fn1
	      fn2...()'; if the	option is not set, this	causes a parse	error.
	      Definition  of  multiple	functions with the function keyword is
	      always allowed.  Multiple	function  definitions  are  not	 often
	      used and can cause obscure errors.

       MULTIOS <Z>
	      Perform implicit tees or cats when multiple redirections are at-
	      tempted (see the section `Redirection').

       OCTAL_ZEROES <S>
	      Interpret	any integer constant beginning with a 0	as octal,  per
	      IEEE  Std	1003.2-1992 (ISO 9945-2:1993).	This is	not enabled by
	      default as it causes problems with parsing of, for example, date
	      and time strings with leading zeroes.

	      Sequences	 of  digits indicating a numeric base such as the `08'
	      component	in `08#77' are always interpreted as decimal,  regard-
	      less of leading zeroes.

       PIPE_FAIL
	      By  default,  when  a pipeline exits the exit status recorded by
	      the shell	and returned by	the shell variable $? reflects that of
	      the rightmost element of a pipeline.  If this option is set, the
	      exit status instead reflects the status of the rightmost element
	      of  the  pipeline	that was non-zero, or zero if all elements ex-
	      ited with	zero status.

       SOURCE_TRACE
	      If set, zsh will print an	informational message  announcing  the
	      name of each file	it loads.  The format of the output is similar
	      to that for the XTRACE option, with the  message	<sourcetrace>.
	      A	 file  may be loaded by	the shell itself when it starts	up and
	      shuts down  (Startup/Shutdown  Files)  or	 by  the  use  of  the
	      `source' and `dot' builtin commands.

       TYPESET_SILENT
	      If  this is unset, executing any of the `typeset'	family of com-
	      mands with no options and	a list of parameters that have no val-
	      ues  to  be assigned but already exist will display the value of
	      the parameter.  If the option is set, they will  only  be	 shown
	      when  parameters	are selected with the `-m' option.  The	option
	      `-p' is available	whether	or not the option is set.

       VERBOSE (-v, ksh: -v)
	      Print shell input	lines as they are read.

       XTRACE (-x, ksh:	-x)
	      Print commands and their arguments as they  are  executed.   The
	      output  is preceded by the value of $PS4,	formatted as described
	      in the section EXPANSION OF PROMPT SEQUENCES in zshmisc(1).

   Shell Emulation
       APPEND_CREATE <K> <S>
	      This option only applies when NO_CLOBBER (-C) is in effect.

	      If this option is	not set, the shell will	report an error	when a
	      append  redirection (>>) is used on a file that does not already
	      exists (the traditional zsh behaviour of	NO_CLOBBER).   If  the
	      option is	set, no	error is reported (POSIX behaviour).

       BASH_REMATCH
	      When  set,  matches  performed with the =~ operator will set the
	      BASH_REMATCH array variable, instead of the  default  MATCH  and
	      match  variables.	  The  first element of	the BASH_REMATCH array
	      will contain the entire matched  text  and  subsequent  elements
	      will contain extracted substrings.  This option makes more sense
	      when KSH_ARRAYS is also set, so that the entire matched  portion
	      is  stored  at  index  0	and the	first substring	is at index 1.
	      Without this option, the	MATCH  variable	 contains  the	entire
	      matched text and the match array variable	contains substrings.

       BSD_ECHO	<S>
	      Make  the	 echo builtin compatible with the BSD echo(1) command.
	      This disables backslashed	escape sequences in echo  strings  un-
	      less the -e option is specified.

       CONTINUE_ON_ERROR
	      If  a fatal error	is encountered (see the	section	ERRORS in zsh-
	      misc(1)),	and the	code is	running	in a script,  the  shell  will
	      resume  execution	at the next statement in the script at the top
	      level, in	other words outside all	functions or shell  constructs
	      such  as loops and conditions.  This mimics the behaviour	of in-
	      teractive	shells,	where the shell	returns	to the line editor  to
	      read  a  new command; it was the normal behaviour	in versions of
	      zsh before 5.0.1.

       CSH_JUNKIE_HISTORY <C>
	      A	history	reference without an event specifier will always refer
	      to  the  previous	 command.  Without this	option,	such a history
	      reference	refers to the same event as the	previous history  ref-
	      erence  on  the current command line, defaulting to the previous
	      command.

       CSH_JUNKIE_LOOPS	<C>
	      Allow loop bodies	to take	the form `list;	end'  instead  of  `do
	      list; done'.

       CSH_JUNKIE_QUOTES <C>
	      Changes  the  rules  for single- and double-quoted text to match
	      that of csh.  These require that embedded	newlines  be  preceded
	      by  a backslash; unescaped newlines will cause an	error message.
	      In double-quoted strings,	it is made impossible to  escape  `$',
	      ``'  or  `"' (and	`\' itself no longer needs escaping).  Command
	      substitutions are	only expanded once, and	cannot be nested.

       CSH_NULLCMD <C>
	      Do not use the values of NULLCMD and  READNULLCMD	 when  running
	      redirections  with no command.  This make	such redirections fail
	      (see the section `Redirection').

       KSH_ARRAYS <K> <S>
	      Emulate ksh array	handling as closely as possible.  If this  op-
	      tion is set, array elements are numbered from zero, an array pa-
	      rameter without subscript	refers to the first element instead of
	      the  whole array,	and braces are required	to delimit a subscript
	      (`${path[2]}' rather than	just `$path[2]') or to apply modifiers
	      to any parameter (`${PWD:h}' rather than `$PWD:h').

       KSH_AUTOLOAD <K>	<S>
	      Emulate  ksh function autoloading.  This means that when a func-
	      tion is autoloaded, the corresponding file is  merely  executed,
	      and  must	define the function itself.  (By default, the function
	      is defined to the	contents of the	file.  However,	the most  com-
	      mon  ksh-style case - of the file	containing only	a simple defi-
	      nition of	the function - is always handled in the	ksh-compatible
	      manner.)

       KSH_OPTION_PRINT	<K>
	      Alters the way options settings are printed: instead of separate
	      lists of set and unset options, all options  are	shown,	marked
	      `on' if they are in the non-default state, `off' otherwise.

       KSH_TYPESET
	      This  option is now obsolete: a better appropximation to the be-
	      haviour of other shells is obtained with the reserved  word  in-
	      terface  to declare, export, float, integer, local, readonly and
	      typeset.	Note that the option is	only applied when the reserved
	      word interface is	not in use.

	      Alters  the way arguments	to the typeset family of commands, in-
	      cluding declare, export, float, integer, local and readonly, are
	      processed.   Without  this  option, zsh will perform normal word
	      splitting	after command and parameter expansion in arguments  of
	      an  assignment;  with  it, word splitting	does not take place in
	      those cases.

       KSH_ZERO_SUBSCRIPT
	      Treat use	of a subscript of value	zero in	array  or  string  ex-
	      pressions	 as a reference	to the first element, i.e. the element
	      that usually has the subscript 1.	 Ignored if KSH_ARRAYS is also
	      set.

	      If neither this option nor KSH_ARRAYS is set, accesses to	an el-
	      ement of an array	or string with subscript zero return an	 empty
	      element  or string, while	attempts to set	element	zero of	an ar-
	      ray or string are	treated	as an error.  However, attempts	to set
	      an  otherwise valid subscript range that includes	zero will suc-
	      ceed.  For example, if KSH_ZERO_SUBSCRIPT	is not set,

		     array[0]=(element)

	      is an error, while

		     array[0,1]=(element)

	      is not and will replace the first	element	of the array.

	      This option is for compatibility	with  older  versions  of  the
	      shell and	is not recommended in new code.

       POSIX_ALIASES <K> <S>
	      When  this  option is set, reserved words	are not	candidates for
	      alias expansion:	it is still possible to	declare	any of them as
	      an  alias, but the alias will never be expanded.	Reserved words
	      are described in the section RESERVED WORDS in zshmisc(1).

	      Alias expansion takes place while	text is	being read; hence when
	      this  option is set it does not take effect until	the end	of any
	      function or other	piece of shell code parsed as one unit.	  Note
	      this  may	 cause differences from	other shells even when the op-
	      tion is in effect.  For example, when  running  a	 command  with
	      `zsh  -c',  or even `zsh -o posixaliases -c', the	entire command
	      argument is parsed as one	unit, so aliases  defined  within  the
	      argument	are  not  available even in later lines.  If in	doubt,
	      avoid use	of aliases in non-interactive code.

       POSIX_ARGZERO
	      This option may be used to temporarily disable  FUNCTION_ARGZERO
	      and  thereby  restore the	value of $0 to the name	used to	invoke
	      the shell	(or as set by the -c command line option).   For  com-
	      patibility  with	previous versions of the shell,	emulations use
	      NO_FUNCTION_ARGZERO instead of POSIX_ARGZERO, which  may	result
	      in unexpected scoping of $0 if the emulation mode	is changed in-
	      side a function or script.  To  avoid  this,  explicitly	enable
	      POSIX_ARGZERO in the emulate command:

		     emulate sh	-o POSIX_ARGZERO

	      Note that	NO_POSIX_ARGZERO has no	effect unless FUNCTION_ARGZERO
	      was already enabled upon entry to	the function or	script.

       POSIX_BUILTINS <K> <S>
	      When this	option is set the command builtin can be used to  exe-
	      cute  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 command builtin.  Special builtins are  .,  :,  break,  con-
	      tinue,  declare,	eval,  exit, export, integer, local, readonly,
	      return, set, shift, source, times, trap and unset.

	      In addition, various error conditions associated with the	 above
	      builtins	or  exec  cause	a non-interactive shell	to exit	and an
	      interactive shell	to return to its top-level processing.

	      Furthermore, the getopts builtin behaves in  a  POSIX-compatible
	      fashion in that the associated variable OPTIND is	not made local
	      to functions.

       POSIX_IDENTIFIERS <K> <S>
	      When this	option is set, only the	ASCII characters a to z, A  to
	      Z,  0  to	9 and _	may be used in identifiers (names of shell pa-
	      rameters and modules).

	      In addition, setting this	option limits the effect of  parameter
	      substitution  with  no  braces,  so  that	 the  expression $# is
	      treated as the parameter $# even if followed by a	valid  parame-
	      ter  name.  When it is unset, zsh	allows expressions of the form
	      $#name to	refer to the length of $name, even for	special	 vari-
	      ables, for example in expressions	such as	$#- and	$#*.

	      Another  difference is that with the option set assignment to an
	      unset variable in	arithmetic context causes the variable	to  be
	      created as a scalar rather than a	numeric	type.  So after	`unset
	      t; (( t =	3 ))'. without POSIX_IDENTIFIERS  set  t  has  integer
	      type, while with it set it has scalar type.

	      When  the	option is unset	and multibyte character	support	is en-
	      abled (i.e. it is	compiled in and	the option MULTIBYTE is	 set),
	      then additionally	any alphanumeric characters in the local char-
	      acter set	may be used in identifiers.   Note  that  scripts  and
	      functions	 written  with this feature are	not portable, and also
	      that both	options	must be	set before the script or  function  is
	      parsed;  setting	them during execution is not sufficient	as the
	      syntax variable=value has	 already  been	parsed	as  a  command
	      rather than an assignment.

	      If  multibyte  character	support	is not compiled	into the shell
	      this option is ignored; all octets with the top bit set  may  be
	      used  in	identifiers.   This  is	non-standard but is the	tradi-
	      tional zsh behaviour.

       POSIX_STRINGS <K> <S>
	      This option affects processing of	quoted strings.	 Currently  it
	      only  affects the	behaviour of null characters, i.e. character 0
	      in the portable character	set corresponding to US	ASCII.

	      When this	option is not set,  null  characters  embedded	within
	      strings  of  the form $'...' are treated as ordinary characters.
	      The entire string	is maintained within the shell and  output  to
	      files where necessary, although owing to restrictions of the li-
	      brary interface the string is truncated at the null character in
	      file  names,  environment	variables, or in arguments to external
	      programs.

	      When this	option is set, the $'...' expression is	 truncated  at
	      the  null	 character.   Note  that  remaining  parts of the same
	      string beyond the	termination of the quotes are not truncated.

	      For example, the command line argument a$'b\0c'd is treated with
	      the  option off as the characters	a, b, null, c, d, and with the
	      option on	as the characters a, b,	d.

       POSIX_TRAPS <K> <S>
	      When this	option is set, the usual zsh  behaviour	 of  executing
	      traps  for  EXIT on exit from shell functions is suppressed.  In
	      that case, manipulating EXIT traps always	alters the global trap
	      for exiting the shell; the LOCAL_TRAPS option is ignored for the
	      EXIT trap.  Furthermore, a return	statement executed in  a  trap
	      with  no	argument  passes back from the function	the value from
	      the surrounding context, not from	code executed within the trap.

       SH_FILE_EXPANSION <K> <S>
	      Perform filename expansion (e.g.,	~ 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	`~$USERNAME' and `~{pfalstad,rc}' will
	      work.

       SH_NULLCMD <K> <S>
	      Do not use the values of	NULLCMD	 and  READNULLCMD  when	 doing
	      redirections, use	`:' instead (see the section `Redirection').

       SH_OPTION_LETTERS <K> <S>
	      If this option is	set the	shell tries to interpret single	letter
	      options (which are used with set	and  setopt)  like  ksh	 does.
	      This also	affects	the value of the - special parameter.

       SH_WORD_SPLIT (-y) <K> <S>
	      Causes field splitting to	be performed on	unquoted parameter ex-
	      pansions.	 Note that this	option has nothing  to	do  with  word
	      splitting.  (See the section `Parameter Expansion'.)

       TRAPS_ASYNC
	      While  waiting  for  a  program  to exit,	handle signals and run
	      traps immediately.  Otherwise the	trap  is  run  after  a	 child
	      process  has  exited.   Note  this  does not affect the point at
	      which traps are run for any case other than when	the  shell  is
	      waiting for a child process.

   Shell State
       INTERACTIVE (-i,	ksh: -i)
	      This is an interactive shell.  This option is set	upon initiali-
	      sation if	the standard input is a	tty  and  commands  are	 being
	      read  from  standard input.  (See	the discussion of SHIN_STDIN.)
	      This heuristic may be overridden by specifying a state for  this
	      option  on  the command line.  The value of this option can only
	      be changed via flags supplied at invocation of  the  shell.   It
	      cannot be	changed	once zsh is running.

       LOGIN (-l, ksh: -l)
	      This  is	a  login shell.	 If this option	is not explicitly set,
	      the shell	becomes	a login	shell if the first  character  of  the
	      argv[0] passed to	the shell is a `-'.

       PRIVILEGED (-p, ksh: -p)
	      Turn  on	privileged mode. Typically this	is used	when script is
	      to be run	with elevated privileges. This should be done as  fol-
	      lows  directly with the -p option	to zsh so that it takes	effect
	      during startup.

		     #!/bin/zsh	-p

	      The option is enabled automatically on startup if	the  effective
	      user  (group)  ID	 is  not equal to the real user	(group)	ID. In
	      this case, turning the option off	causes the effective user  and
	      group  IDs  to  be  set to the real user and group IDs. Be aware
	      that if that fails the shell may be running with	different  IDs
	      than  was	 intended so a script should check for failure and act
	      accordingly, for example:

		     unsetopt privileged || exit

	      The PRIVILEGED option disables sourcing user startup files.   If
	      zsh   is	invoked	 as  `sh'  or  `ksh'  with  this  option  set,
	      /etc/suid_profile	is sourced (after /etc/profile on  interactive
	      shells). Sourcing	~/.profile is disabled and the contents	of the
	      ENV variable is ignored. This option cannot be changed using the
	      -m option	of setopt and unsetopt,	and changing it	inside a func-
	      tion always changes it globally regardless of the	 LOCAL_OPTIONS
	      option.

       RESTRICTED (-r)
	      Enables  restricted  mode.   This	option cannot be changed using
	      unsetopt,	and setting it inside a	 function  always  changes  it
	      globally	regardless  of the LOCAL_OPTIONS option.  See the sec-
	      tion `Restricted Shell'.

       SHIN_STDIN (-s, ksh: -s)
	      Commands are being read from the standard	input.	 Commands  are
	      read  from standard input	if no command is specified with	-c and
	      no file of commands is specified.	 If SHIN_STDIN is set  explic-
	      itly 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 unsetting this op-
	      tion 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 can only be
	      changed via flags	supplied at invocation of the shell.  It  can-
	      not be changed once zsh is running.

       SINGLE_COMMAND (-t, ksh:	-t)
	      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 INTERACTIVE option is	explicitly set
	      on the command line.  The	value  of  this	 option	 can  only  be
	      changed  via flags supplied at invocation	of the shell.  It can-
	      not be changed once zsh is running.

   Zle
       BEEP (+B) <D>
	      Beep on error in ZLE.

       COMBINING_CHARS
	      Assume that the  terminal	 displays  combining  characters  cor-
	      rectly.	Specifically, if a base	alphanumeric character is fol-
	      lowed by one or more zero-width punctuation  characters,	assume
	      that  the	 zero-width  characters	will be	displayed as modifica-
	      tions to the base	character within the same width.  Not all ter-
	      minals handle this.  If this option is not set, zero-width char-
	      acters are displayed separately with special mark-up.

	      If this option is	set, the pattern  test	[[:WORD:]]  matches  a
	      zero-width  punctuation character	on the assumption that it will
	      be used as part of a word	in combination with a word  character.
	      Otherwise	 the  base  shell does not handle combining characters
	      specially.

       EMACS  If ZLE is	loaded,	turning	on this	option has the equivalent  ef-
	      fect  of	`bindkey  -e'.	 In  addition, the VI option is	unset.
	      Turning it off has no effect.  The option	setting	is not guaran-
	      teed to reflect the current keymap.  This	option is provided for
	      compatibility; bindkey is	the recommended	interface.

       OVERSTRIKE
	      Start up the line	editor in overstrike mode.

       SINGLE_LINE_ZLE (-M) <K>
	      Use single-line command line editing instead of multi-line.

	      Note that	although this is on by default	in  ksh	 emulation  it
	      only provides superficial	compatibility with the ksh line	editor
	      and reduces the effectiveness of the zsh line editor.  As	it has
	      no  effect  on shell syntax, many	users may wish to disable this
	      option when using	ksh emulation interactively.

       VI     If ZLE is	loaded,	turning	on this	option has the equivalent  ef-
	      fect  of	`bindkey -v'.  In addition, the	EMACS option is	unset.
	      Turning it off has no effect.  The option	setting	is not guaran-
	      teed to reflect the current keymap.  This	option is provided for
	      compatibility; bindkey is	the recommended	interface.

       ZLE (-Z)
	      Use the zsh line editor.	Set by default in  interactive	shells
	      connected	to a terminal.

OPTION ALIASES
       Some  options have alternative names.  These aliases are	never used for
       output, but can be used just like normal	option names  when  specifying
       options to the shell.

       BRACE_EXPAND
	      NO_IGNORE_BRACES (ksh and	bash compatibility)

       DOT_GLOB
	      GLOB_DOTS	(bash compatibility)

       HASH_ALL
	      HASH_CMDS	(bash compatibility)

       HIST_APPEND
	      APPEND_HISTORY (bash compatibility)

       HIST_EXPAND
	      BANG_HIST	(bash compatibility)

       LOG    NO_HIST_NO_FUNCTIONS (ksh	compatibility)

       MAIL_WARN
	      MAIL_WARNING (bash compatibility)

       ONE_CMD
	      SINGLE_COMMAND (bash compatibility)

       PHYSICAL
	      CHASE_LINKS (ksh and bash	compatibility)

       PROMPT_VARS
	      PROMPT_SUBST (bash compatibility)

       STDIN  SHIN_STDIN (ksh compatibility)

       TRACK_ALL
	      HASH_CMDS	(ksh compatibility)

SINGLE LETTER OPTIONS
   Default set
       -0     CORRECT
       -1     PRINT_EXIT_VALUE
       -2     NO_BAD_PATTERN
       -3     NO_NOMATCH
       -4     GLOB_DOTS
       -5     NOTIFY
       -6     BG_NICE
       -7     IGNORE_EOF
       -8     MARK_DIRS
       -9     AUTO_LIST
       -B     NO_BEEP
       -C     NO_CLOBBER
       -D     PUSHD_TO_HOME
       -E     PUSHD_SILENT
       -F     NO_GLOB
       -G     NULL_GLOB
       -H     RM_STAR_SILENT
       -I     IGNORE_BRACES
       -J     AUTO_CD
       -K     NO_BANG_HIST
       -L     SUN_KEYBOARD_HACK
       -M     SINGLE_LINE_ZLE
       -N     AUTO_PUSHD
       -O     CORRECT_ALL
       -P     RC_EXPAND_PARAM
       -Q     PATH_DIRS
       -R     LONG_LIST_JOBS
       -S     REC_EXACT
       -T     CDABLE_VARS
       -U     MAIL_WARNING
       -V     NO_PROMPT_CR
       -W     AUTO_RESUME
       -X     LIST_TYPES
       -Y     MENU_COMPLETE
       -Z     ZLE
       -a     ALL_EXPORT
       -e     ERR_EXIT
       -f     NO_RCS
       -g     HIST_IGNORE_SPACE
       -h     HIST_IGNORE_DUPS
       -i     INTERACTIVE
       -k     INTERACTIVE_COMMENTS
       -l     LOGIN
       -m     MONITOR
       -n     NO_EXEC
       -p     PRIVILEGED
       -r     RESTRICTED
       -s     SHIN_STDIN
       -t     SINGLE_COMMAND
       -u     NO_UNSET
       -v     VERBOSE
       -w     CHASE_LINKS
       -x     XTRACE
       -y     SH_WORD_SPLIT

   sh/ksh emulation set
       -C     NO_CLOBBER
       -T     TRAPS_ASYNC
       -X     MARK_DIRS
       -a     ALL_EXPORT
       -b     NOTIFY
       -e     ERR_EXIT
       -f     NO_GLOB
       -i     INTERACTIVE
       -l     LOGIN
       -m     MONITOR
       -n     NO_EXEC
       -p     PRIVILEGED
       -r     RESTRICTED
       -s     SHIN_STDIN
       -t     SINGLE_COMMAND
       -u     NO_UNSET
       -v     VERBOSE
       -x     XTRACE

   Also	note
       -A     Used by set for setting arrays
       -b     Used on the command line to specify end of option	processing
       -c     Used on the command line to specify a single command
       -m     Used by setopt for pattern-matching option setting
       -o     Used in all places to allow use of long option names
       -s     Used by set to sort positional parameters

ZSHBUILTINS(1)		    General Commands Manual		ZSHBUILTINS(1)

NAME
       zshbuiltins - zsh built-in commands

SHELL BUILTIN COMMANDS
       Some shell builtin commands take	options	as described in	individual en-
       tries; these are	often referred to in the  list	below  as  `flags'  to
       avoid  confusion	 with  shell options, which may	also have an effect on
       the behaviour of	builtin	commands.  In this introductory	section,  `op-
       tion'  always  has the meaning of an option to a	command	that should be
       familiar	to most	command	line users.

       Typically, options are single letters preceded by a  hyphen  (-).   Op-
       tions  that take	an argument accept it either immediately following the
       option letter or	after white space, for example `print -C3 *' or	`print
       -C 3 *' are equivalent.	Arguments to options are not the same as argu-
       ments to	the command; the documentation indicates which is which.   Op-
       tions  that  do	not take an argument may be combined in	a single word,
       for example `print -ca *' and `print -c -a *' are equivalent.

       Some shell builtin commands also	take options that begin	with  `+'  in-
       stead of	`-'.  The list below makes clear which commands	these are.

       Options	(together with their individual	arguments, if any) must	appear
       in a group before any non-option	arguments; once	the  first  non-option
       argument	has been found,	option processing is terminated.

       All  builtin  commands other than precommand modifiers, even those that
       have no options,	can be given the argument  `--'	 to  terminate	option
       processing.  This indicates that	the following words are	non-option ar-
       guments,	but is otherwise ignored.  This	is useful in cases where argu-
       ments  to the command may begin with `-'.  For historical reasons, most
       builtin commands	also recognize a single	`-' in	a  separate  word  for
       this purpose; note that this is less standard and use of	`--' is	recom-
       mended.

       - simple	command
	      See the section `Precommand Modifiers' in	zshmisc(1).

       . file [	arg ...	]
	      Read commands from file and execute them in  the	current	 shell
	      environment.

	      If  file	does  not contain a slash, or if PATH_DIRS is set, the
	      shell looks in the components of $path  to  find	the  directory
	      containing  file.	  Files	 in the	current	directory are not read
	      unless  `.'  appears  somewhere  in  $path.   If	a  file	 named
	      `file.zwc'  is  found,  is  newer	than file, and is the compiled
	      form (created with the zcompile builtin) of file,	then  commands
	      are read from that file instead of file.

	      If  any  arguments arg are given,	they become the	positional pa-
	      rameters;	the old	positional parameters are  restored  when  the
	      file is done executing.  However,	if no arguments	are given, the
	      positional parameters remain those of the	calling	 context,  and
	      no restoring is done.

	      If  file	was  not  found	 the return status is 127; if file was
	      found but	contained a syntax error the  return  status  is  126;
	      else  the	 return	 status	is the exit status of the last command
	      executed.

       : [ arg ... ]
	      This command does	nothing, although normal  argument  expansions
	      is performed which may have effects on shell parameters.	A zero
	      exit status is returned.

       alias [ {+|-}gmrsL ] [ name[=value] ... ]
	      For each name with a corresponding value,	define an  alias  with
	      that  value.   A trailing	space in value causes the next word to
	      be checked for alias expansion.  If the -g flag is present,  de-
	      fine a global alias; global aliases are expanded even if they do
	      not occur	in command position.

	      If the -s	flag is	present, define	a suffix alias:	if the command
	      word on a	command	line is	in the form `text.name', where text is
	      any  non-empty  string,  it  is  replaced	 by  the  text	`value
	      text.name'.   Note that name is treated as a literal string, not
	      a	pattern.  A trailing space in value is	not  special  in  this
	      case.  For example,

		     alias -s ps=gv

	      will  cause  the command `*.ps' to be expanded to	`gv *.ps'.  As
	      alias expansion is carried out earlier than globbing, the	`*.ps'
	      will  then  be  expanded.	 Suffix	aliases	constitute a different
	      name space from other aliases (so	in the	above  example	it  is
	      still  possible  to  create an alias for the command ps) and the
	      two sets are never listed	together.

	      For each name with no value, print the value of  name,  if  any.
	      With  no	arguments,  print  all currently defined aliases other
	      than suffix aliases.  If the -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	one of
	      the -g, -r or -s flags is	 present,  restrict  the  printing  to
	      global, regular or suffix	aliases, respectively; a regular alias
	      is one which is neither a	global nor a suffix alias.   Using `+'
	      instead  of  `-',	 or  ending the	option list with a single `+',
	      prevents the values of the aliases from being printed.

	      If the -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 name	(with no value)	is given for  which  no	 alias
	      has been defined.

	      For  more	 on  aliases, include common problems, see the section
	      ALIASING in zshmisc(1).

       autoload	[ {+|-}TUXkmtz ] [ -w ]	[ name ... ]
	      Equivalent to functions -u, with the exception of	-X/+X and  -w.
	      See  the	section	`Autoloading Functions'	in zshmisc(1) for full
	      details.	The fpath parameter will be searched to	find the func-
	      tion definition when the function	is first referenced.

	      The  flag	 -X  may be used only inside a shell function, and may
	      not be followed by a name.  It causes the	calling	function to be
	      marked for autoloading and then immediately loaded and executed,
	      with the current array of	positional  parameters	as  arguments.
	      This  replaces  the  previous definition of the function.	 If no
	      function definition is found, an error is	printed	and the	 func-
	      tion remains undefined and marked	for autoloading.

	      The  flag	 +X  attempts to load each name	as an autoloaded func-
	      tion, but	does not execute it.  The exit status  is  zero	 (suc-
	      cess)  if	 the function was not previously defined and a defini-
	      tion for it was found.  This does	not replace any	existing defi-
	      nition of	the function.  The exit	status is nonzero (failure) if
	      the function was already	defined	 or  when  no  definition  was
	      found.   In  the	latter case the	function remains undefined and
	      marked for autoloading.  If ksh-style  autoloading  is  enabled,
	      the  function created will contain the contents of the file plus
	      a	call to	the function itself appended to	it, thus giving	normal
	      ksh autoloading behaviour	on the first call to the function.  If
	      the -m flag is also given	each name is treated as	a pattern  and
	      all functions already marked for autoload	that match the pattern
	      are loaded.

	      With the -w flag,	the names are taken as names of	files compiled
	      with the zcompile	builtin, and all functions defined in them are
	      marked for autoloading.

	      The flags	-z and -k mark the function to be autoloaded using the
	      zsh  or  ksh  style, as if the option KSH_AUTOLOAD were unset or
	      were set,	respectively.  The flags override the setting  of  the
	      option at	the time the function is loaded.

	      Note  that  the  autoload	command	makes no attempt to ensure the
	      shell options set	during the loading or execution	 of  the  file
	      have any particular value.  For this, the	emulate	command	can be
	      used:

		     emulate zsh -c 'autoload -Uz func'

	      arranges that when func is loaded	the shell is in	native zsh em-
	      ulation, and this	emulation is also applied when func is run.

       bg [ job	... ]
       job ... &
	      Put  each	specified job in the background, or the	current	job if
	      none is specified.

       bindkey
	      See the section `Zle Builtins' in	zshzle(1).

       break [ n ]
	      Exit from	an enclosing for, while, until,	select or repeat loop.
	      If  an arithmetic	expression n is	specified, then	break n	levels
	      instead of just one.

       builtin name [ args ... ]
	      Executes the builtin name, with the given	args.

       bye    Same as exit.

       cap    See the section `The zsh/cap Module' in zshmodules(1).

       cd [ -qsLP ] [ arg ]
       cd [ -qsLP ] old	new
       cd [ -qsLP ] {+|-}n
	      Change the current directory.  In	the  first  form,  change  the
	      current directory	to arg,	or to the value	of $HOME if arg	is not
	      specified.  If arg is `-', change	to the previous	directory.

	      Otherwise, if arg	begins with a slash, attempt to	change to  the
	      directory	given by arg.

	      If  arg  does  not  begin	with a slash, the behaviour depends on
	      whether the current directory `.'	occurs in the list of directo-
	      ries  contained  in the shell parameter cdpath.  If it does not,
	      first attempt to change to the directory arg under  the  current
	      directory,  and  if that fails but cdpath	is set and contains at
	      least one	element	attempt	to change to the directory  arg	 under
	      each  component  of cdpath in turn until successful.  If `.' oc-
	      curs in cdpath, then cdpath is searched  strictly	 in  order  so
	      that `.' is only tried at	the appropriate	point.

	      The  order  of testing cdpath is modified	if the option POSIX_CD
	      is set, as described in the documentation	for the	option.

	      If no directory is found,	the option CDABLE_VARS is set,	and  a
	      parameter	 named	arg  exists  whose  value begins with a	slash,
	      treat its	value as the directory.	 In that case,	the  parameter
	      is added to the named directory hash table.

	      The  second form of cd substitutes the string new	for the	string
	      old in the name of the current directory,	and tries to change to
	      this new directory.

	      The third	form of	cd extracts an entry from the directory	stack,
	      and changes to that directory.  An argument  of  the  form  `+n'
	      identifies  a  stack entry by counting from the left of the list
	      shown by the dirs	command, starting with zero.  An  argument  of
	      the  form	`-n' counts from the right.  If	the PUSHD_MINUS	option
	      is set, the meanings of `+' and `-' in this context are swapped.

	      If the -q	(quiet)	option is specified, the hook  function	 chpwd
	      and  the	functions in the array chpwd_functions are not called.
	      This is useful for calls to cd that do not change	 the  environ-
	      ment seen	by an interactive user.

	      If  the -s option	is specified, cd refuses to change the current
	      directory	if the given pathname contains symlinks.   If  the  -P
	      option is	given or the CHASE_LINKS option	is set,	symbolic links
	      are resolved to their true values.  If the -L  option  is	 given
	      symbolic	links are retained in the directory (and not resolved)
	      regardless of the	state of the CHASE_LINKS option.

       chdir  Same as cd.

       clone  See the section `The zsh/clone Module' in	zshmodules(1).

       command [ -pvV ]	simple command
	      The simple command argument is taken as an external command  in-
	      stead  of	 a  function  or  builtin  and	is  executed.  If  the
	      POSIX_BUILTINS option is set, builtins will also be executed but
	      certain  special	properties of them are suppressed. The -p flag
	      causes a default path to be searched instead of that  in	$path.
	      With  the	 -v flag, command is similar to	whence and with	-V, it
	      is equivalent to whence -v.

	      See also the section `Precommand Modifiers' in zshmisc(1).

       comparguments
	      See the section `The zsh/computil	Module'	in zshmodules(1).

       compcall
	      See the section `The zsh/compctl Module' in zshmodules(1).

       compctl
	      See the section `The zsh/compctl Module' in zshmodules(1).

       compdescribe
	      See the section `The zsh/computil	Module'	in zshmodules(1).

       compfiles
	      See the section `The zsh/computil	Module'	in zshmodules(1).

       compgroups
	      See the section `The zsh/computil	Module'	in zshmodules(1).

       compquote
	      See the section `The zsh/computil	Module'	in zshmodules(1).

       comptags
	      See the section `The zsh/computil	Module'	in zshmodules(1).

       comptry
	      See the section `The zsh/computil	Module'	in zshmodules(1).

       compvalues
	      See the section `The zsh/computil	Module'	in zshmodules(1).

       continue	[ n ]
	      Resume the next iteration	of the enclosing  for,	while,	until,
	      select  or  repeat loop. If an arithmetic	expression n is	speci-
	      fied, break out of n-1 loops and resume  at  the	nth  enclosing
	      loop.

       declare
	      Same as typeset.

       dirs [ -c ] [ arg ... ]
       dirs [ -lpv ]
	      With  no	arguments,  print the contents of the directory	stack.
	      Directories are added to this stack with the pushd command,  and
	      removed  with  the cd or popd commands.  If arguments are	speci-
	      fied, load them onto the	directory  stack,  replacing  anything
	      that was there, and push the current directory onto the stack.

	      -c     clear the directory stack.

	      -l     print directory names in full instead of using of using ~
		     expressions (see Dynamic and Static named directories  in
		     zshexpn(1)).

	      -p     print directory entries one per line.

	      -v     number the	directories in the stack when printing.

       disable [ -afmprs ] name	...
	      Temporarily  disable  the	named hash table elements or patterns.
	      The default is to	disable	builtin	commands.  This	allows you  to
	      use an external command with the same name as a builtin command.
	      The -a option  causes  disable  to  act  on  regular  or	global
	      aliases.	The -s option causes disable to	act on suffix aliases.
	      The -f option causes disable to act on shell functions.  The  -r
	      options  causes disable to act on	reserved words.	 Without argu-
	      ments all	disabled hash table elements  from  the	 corresponding
	      hash  table  are	printed.   With	 the -m	flag the arguments are
	      taken as patterns	(which should be quoted	to prevent  them  from
	      undergoing filename expansion), and all hash table elements from
	      the corresponding	hash table matching these  patterns  are  dis-
	      abled.  Disabled objects can be enabled with the enable command.

	      With  the	 option	 -p, name ... refer to elements	of the shell's
	      pattern syntax as	described in  the  section  `Filename  Genera-
	      tion'.   Certain	elements  can be disabled separately, as given
	      below.

	      Note that	patterns not allowed by	the current settings  for  the
	      options  EXTENDED_GLOB,  KSH_GLOB	and SH_GLOB are	never enabled,
	      regardless of the	setting	here.  For example,  if	 EXTENDED_GLOB
	      is  not active, the pattern ^ is ineffective even	if `disable -p
	      "^"' has not been	issued.	 The list below	indicates  any	option
	      settings	that  restrict	the  use of the	pattern.  It should be
	      noted that setting SH_GLOB has a wider effect than  merely  dis-
	      abling  patterns as certain expressions, in particular those in-
	      volving parentheses, are parsed differently.

	      The following patterns may be disabled;  all  the	 strings  need
	      quoting  on  the	command	line to	prevent	them from being	inter-
	      preted immediately as patterns and the patterns are shown	 below
	      in single	quotes as a reminder.

	      '?'    The  pattern  character  ?	 wherever it occurs, including
		     when preceding a parenthesis with KSH_GLOB.

	      '*'    The pattern character * wherever it occurs, including re-
		     cursive  globbing	and  when preceding a parenthesis with
		     KSH_GLOB.

	      '['    Character classes.

	      '<' (NO_SH_GLOB)
		     Numeric ranges.

	      '|' (NO_SH_GLOB)
		     Alternation in  grouped  patterns,	 case  statements,  or
		     KSH_GLOB parenthesised expressions.

	      '(' (NO_SH_GLOB)
		     Grouping  using  single parentheses.  Disabling this does
		     not disable the use of  parentheses  for  KSH_GLOB	 where
		     they  are introduced by a special character, nor for glob
		     qualifiers	(use  `setopt  NO_BARE_GLOB_QUAL'  to  disable
		     glob qualifiers that use parentheses only).

	      '~' (EXTENDED_GLOB)
		     Exclusion in the form A~B.

	      '^' (EXTENDED_GLOB)
		     Exclusion in the form A^B.

	      '#' (EXTENDED_GLOB)
		     The pattern character # wherever it occurs, both for rep-
		     etition of	a previous pattern and for indicating globbing
		     flags.

	      '?(' (KSH_GLOB)
		     The  grouping form	?(...).	 Note this is also disabled if
		     '?' is disabled.

	      '*(' (KSH_GLOB)
		     The grouping form *(...).	Note this is also disabled  if
		     '*' is disabled.

	      '+(' (KSH_GLOB)
		     The grouping form +(...).

	      '!(' (KSH_GLOB)
		     The grouping form !(...).

	      '@(' (KSH_GLOB)
		     The grouping form @(...).

       disown [	job ...	]
       job ... &|
       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
	      job is specified,	disown the current job.

	      If the jobs are currently	stopped	and the	 AUTO_CONTINUE	option
	      is  not  set,  a warning is printed containing information about
	      how to make them running after they have been disowned.  If  one
	      of  the latter two forms is used,	the jobs will automatically be
	      made running, independent	of the setting	of  the	 AUTO_CONTINUE
	      option.

       echo [ -neE ] [ arg ... ]
	      Write  each  arg on the standard output, with a space separating
	      each one.	 If the	-n flag	is not present,	print a	newline	at the
	      end.  echo recognizes the	following escape sequences:

	      \a     bell character
	      \b     backspace
	      \c     suppress final newline
	      \e     escape
	      \f     form feed
	      \n     linefeed (newline)
	      \r     carriage return
	      \t     horizontal	tab
	      \v     vertical tab
	      \\     backslash
	      \0NNN  character code in octal
	      \xNN   character code in hexadecimal
	      \uNNNN unicode character code in hexadecimal
	      \UNNNNNNNN
		     unicode character code in hexadecimal

	      The  -E  flag,  or  the  BSD_ECHO	option,	can be used to disable
	      these escape sequences.  In the latter case, -e flag can be used
	      to enable	them.

       echotc See the section `The zsh/termcap Module' in zshmodules(1).

       echoti See the section `The zsh/terminfo	Module'	in zshmodules(1).

       emulate [ -lLR ]	[ {zsh|sh|ksh|csh} [ flags ... ] ]
	      Without any argument print current emulation mode.

	      With single argument set up zsh options to emulate the specified
	      shell as much as possible.  csh will never  be  fully  emulated.
	      If  the argument is not one of the shells	listed above, zsh will
	      be used as a default; more precisely, the	tests performed	on the
	      argument	are  the same as those used to determine the emulation
	      at startup based on the shell name, see the section  COMPATIBIL-
	      ITY  in zsh(1) .	In addition to setting shell options, the com-
	      mand also	restores the pristine state of pattern enables,	as  if
	      all patterns had been enabled using enable -p.

	      If  the  emulate	command	occurs inside a	function that has been
	      marked for execution tracing with	functions -t then  the	xtrace
	      option  will  be turned on regardless of emulation mode or other
	      options.	Note that code executed	inside the function by the  .,
	      source,  or  eval	 commands  is not considered to	be running di-
	      rectly from the function,	hence does not provoke this behaviour.

	      If the -R	switch is given, all settable  options	are  reset  to
	      their  default  value  corresponding  to the specified emulation
	      mode, except for certain options describing the interactive  en-
	      vironment;  otherwise, only those	options	likely to cause	porta-
	      bility problems in scripts and functions are altered.  If	the -L
	      switch  is  given, the options LOCAL_OPTIONS, LOCAL_PATTERNS and
	      LOCAL_TRAPS will be set as well, causing the effects of the emu-
	      late  command  and any setopt, disable -p	or enable -p, and trap
	      commands to be local to the immediately surrounding shell	 func-
	      tion,  if	any; normally these options are	turned off in all emu-
	      lation modes except ksh. The -L  switch  is  mutually  exclusive
	      with the use of -c in flags.

	      If  there	 is  a single argument and the -l switch is given, the
	      options that would be set	or unset (the  latter  indicated  with
	      the  prefix  `no') are listed.  -l can be	combined with -L or -R
	      and the list will	be modified in the appropriate way.  Note  the
	      list  does not depend on the current setting of options, i.e. it
	      includes all options that	may  in	 principle  change,  not  just
	      those that would actually	change.

	      The  flags  may be any of	the invocation-time flags described in
	      the section INVOCATION in	zsh(1),	except that `-o	EMACS' and `-o
	      VI'  may not be used.  Flags such	as `+r'/`+o RESTRICTED'	may be
	      prohibited in some circumstances.

	      If -c arg	appears	in flags, arg is evaluated while the requested
	      emulation	 is temporarily	in effect.  In this case the emulation
	      mode and all options are restored	to their previous  values  be-
	      fore emulate returns.  The -R switch may precede the name	of the
	      shell to emulate;	note this has a	meaning	distinct from  includ-
	      ing -R in	flags.

	      Use  of -c enables `sticky' emulation mode for functions defined
	      within the evaluated expression:	the emulation mode is  associ-
	      ated  thereafter with the	function so that whenever the function
	      is executed the emulation	(respecting the	-R switch, if present)
	      and  all	options	 are set (and pattern disables cleared)	before
	      entry to the function, and the state is restored after exit.  If
	      the  function  is	called when the	sticky emulation is already in
	      effect, either within an `emulate	shell -c' expression or	within
	      another  function	with the same sticky emulation,	entry and exit
	      from the function	do not cause options to	be altered (except due
	      to  standard processing such as the LOCAL_OPTIONS	option).  This
	      also applies to functions	marked for autoload within the	sticky
	      emulation; the appropriate set of	options	will be	applied	at the
	      point the	function is loaded as well as when it is run.

	      For example:

		     emulate sh	-c 'fni() { setopt cshnullglob;	}
		     fno() { fni; }'
		     fno

	      The two functions	fni and	fno are	defined	with sticky sh	emula-
	      tion.  fno is then executed, causing options associated with em-
	      ulations to be set to their values in sh.	 fno then  calls  fni;
	      because  fni  is	also marked for	sticky sh emulation, no	option
	      changes take place on entry to or	exit from it.  Hence  the  op-
	      tion  cshnullglob, turned	off by sh emulation, will be turned on
	      within fni and remain on return to fno.  On exit from  fno,  the
	      emulation	 mode  and  all	 options will be restored to the state
	      they were	in before entry	to the temporary emulation.

	      The documentation	above is typically sufficient for the intended
	      purpose  of  executing code designed for other shells in a suit-
	      able environment.	 More detailed rules follow.
	      1.     The sticky	emulation  environment	provided  by  `emulate
		     shell  -c'	 is  identical	to that	provided by entry to a
		     function marked for sticky	emulation as a consequence  of
		     being  defined  in	such an	environment.  Hence, for exam-
		     ple, the sticky emulation is  inherited  by  subfunctions
		     defined within functions with sticky emulation.
	      2.     No	change of options takes	place on entry to or exit from
		     functions that are	not marked for sticky emulation, other
		     than  those that would normally take place, even if those
		     functions are called within sticky	emulation.
	      3.     No	special	handling is provided for functions marked  for
		     autoload nor for functions	present	in wordcode created by
		     the zcompile command.
	      4.     The presence or absence of	the -R switch to emulate  cor-
		     responds  to different sticky emulation modes, so for ex-
		     ample `emulate sh -c', `emulate -R	sh  -c'	 and  `emulate
		     csh -c' are treated as three distinct sticky emulations.
	      5.     Difference	 in  shell options supplied in addition	to the
		     basic emulation also mean the sticky emulations are  dif-
		     ferent,  so for example `emulate zsh -c' and `emulate zsh
		     -o	cbases -c' are treated as distinct sticky emulations.

       enable [	-afmprs	] name ...
	      Enable the named hash table elements, presumably	disabled  ear-
	      lier  with  disable.  The	default	is to enable builtin commands.
	      The -a option causes enable to act on regular or global aliases.
	      The  -s  option  causes enable to	act on suffix aliases.	The -f
	      option causes enable to act on shell functions.  The  -r	option
	      causes  enable  to act on	reserved words.	 Without arguments all
	      enabled hash table elements from the  corresponding  hash	 table
	      are  printed.   With the -m flag the arguments are taken as pat-
	      terns (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	disable	 builtin  com-
	      mand.

	      enable  -p  reenables  patterns  disabled	with disable -p.  Note
	      that it does not override	globbing options; for example, `enable
	      -p  "~"' does not	cause the pattern character ~ to be active un-
	      less the EXTENDED_GLOB option is also set.  To enable all	possi-
	      ble  patterns  (so  that	they may be individually disabled with
	      disable -p), use `setopt EXTENDED_GLOB KSH_GLOB NO_SH_GLOB'.

       eval [ arg ... ]
	      Read the arguments as input to the shell and execute the result-
	      ing  command(s) in the current shell process.  The return	status
	      is the same as if	the commands had been executed directly	by the
	      shell;  if  there	 are no	args or	they contain no	commands (i.e.
	      are an empty string or whitespace) the return status is zero.

       exec [ -cl ] [ -a argv0 ] [ command [ arg ... ] ]
	      Replace the current shell	with an	external command  rather  than
	      forking.	 With  -c  clear the environment; with -l prepend - to
	      the argv[0] string of the	command	executed (to simulate a	 login
	      shell); with -a argv0 set	the argv[0] string of the command exe-
	      cuted.  See the section `Precommand Modifiers' in	zshmisc(1).

	      If command is omitted but	any redirections are  specified,  then
	      the redirections will take effect	in the current shell.

       exit [ n	]
	      Exit  the	 shell with the	exit status specified by an arithmetic
	      expression n; if none is specified, use the exit status from the
	      last  command  executed.	 An  EOF condition will	also cause the
	      shell to exit, unless the	IGNORE_EOF option is set.

	      See notes	at the end of the section JOBS in zshmisc(1) for  some
	      possibly unexpected interactions of the exit command with	jobs.

       export [	name[=value] ... ]
	      The specified names are marked for automatic export to the envi-
	      ronment of subsequently executed commands.  Equivalent to	 type-
	      set -gx.	If a parameter specified does not already exist, it is
	      created in the global scope.

       false [ arg ... ]
	      Do nothing and return an exit status of 1.

       fc [ -e ename ] [ -LI ] [ -m match ] [ old=new ... ] [ first [ last ] ]
       fc -l [ -LI ] [ -nrdfEiD	] [ -t timefmt ] [ -m match ]
	     [ old=new ... ] [ first [ last ] ]
       fc -p [ -a ] [ filename [ histsize [ savehistsize ] ] ]
       fc -P
       fc -ARWI	[ filename ]
	      The fc command controls the interactive history mechanism.  Note
	      that reading and writing of history options is only performed if
	      the shell	is interactive.	 Usually this  is  detected  automati-
	      cally,  but  it  can be forced by	setting	the interactive	option
	      when starting the	shell.

	      The first	two forms of this command select  a  range  of	events
	      from  first  to last from	the history list.  The arguments first
	      and last may be specified	as a number or as a string.   A	 nega-
	      tive  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 old=new, if any, are then
	      performed	on the text of the events.

	      In addition to the number	range,
	      -I     restricts to only internal	events (not from $HISTFILE)
	      -L     restricts to only local events (not  from	other  shells,
		     see SHARE_HISTORY in zshoptions(1)	-- note	that $HISTFILE
		     is	considered local when read at startup)
	      -m     takes the first argument as a pattern (should be  quoted)
		     and  only	the  history  events matching this pattern are
		     considered

	      If first is not specified, it will be set	to -1 (the most	recent
	      event), or to -16	if the -l flag is given.  If last is not spec-
	      ified, it	will be	set to first, or to  -1	 if  the  -l  flag  is
	      given.   However,	 if the	current	event has added	entries	to the
	      history with `print -s' or `fc -R', then the default last	for -l
	      includes all new history entries since the current event began.

	      When  the	 -l  flag is given, the	resulting events are listed on
	      standard output.	Otherwise the editor program ename is  invoked
	      on  a  file  containing  these  history events.  If ename	is not
	      given, the value of the parameter	FCEDIT is used;	if that	is not
	      set  the	value  of the parameter	EDITOR is used;	if that	is not
	      set a builtin default, usually `vi' is used.  If ename  is  `-',
	      no editor	is invoked.  When editing is complete, the edited com-
	      mand is executed.

	      The flag -r reverses the order of	the events  and	 the  flag  -n
	      suppresses event numbers when listing.

	      Also when	listing,
	      -d     prints timestamps for each	event
	      -f     prints  full  time-date stamps in the US `MM/DD/YY	hh:mm'
		     format
	      -E     prints full time-date stamps in the European  `dd.mm.yyyy
		     hh:mm' format
	      -i     prints  full  time-date  stamps  in  ISO8601  `yyyy-mm-dd
		     hh:mm' format
	      -t fmt prints time and date stamps in the	given format;  fmt  is
		     formatted	with the strftime function with	the zsh	exten-
		     sions described for the %D{string}	prompt format  in  the
		     section EXPANSION OF PROMPT SEQUENCES in zshmisc(1).  The
		     resulting formatted string	must be	no more	than 256 char-
		     acters or will not	be printed
	      -D     prints elapsed times; may be combined with	one of the op-
		     tions above

	      `fc -p' pushes  the  current  history  list  onto	 a  stack  and
	      switches to a new	history	list.  If the -a option	is also	speci-
	      fied, this history list will be automatically  popped  when  the
	      current  function	 scope is exited, which	is a much better solu-
	      tion than	creating a trap	function to call `fc -P' manually.  If
	      no  arguments  are  specified,  the  history list	is left	empty,
	      $HISTFILE	is unset, and $HISTSIZE	& $SAVEHIST are	set  to	 their
	      default  values.	 If one	argument is given, $HISTFILE is	set to
	      that filename, $HISTSIZE & $SAVEHIST are left unchanged, and the
	      history  file  is	 read  in (if it exists) to initialize the new
	      list.  If	a second argument is specified,	$HISTSIZE &  $SAVEHIST
	      are instead set to the single specified numeric value.  Finally,
	      if a third argument is specified,	$SAVEHIST is set to a separate
	      value  from $HISTSIZE.  You are free to change these environment
	      values for the new history list however you desire in  order  to
	      manipulate the new history list.

	      `fc -P' pops the history list back to an older list saved	by `fc
	      -p'.  The	current	list is	saved to its $HISTFILE	before	it  is
	      destroyed	 (assuming that	$HISTFILE and $SAVEHIST	are set	appro-
	      priately,	of course).  The values	of $HISTFILE,  $HISTSIZE,  and
	      $SAVEHIST	 are  restored to the values they had when `fc -p' was
	      called.  Note that this restoration  can	conflict  with	making
	      these variables "local", so your best bet	is to avoid local dec-
	      larations	for these variables in functions  that	use  `fc  -p'.
	      The  one	other  guaranteed-safe	combination is declaring these
	      variables	to be local at the top of your function	and using  the
	      automatic	 option	 (-a)  with `fc	-p'.  Finally, note that it is
	      legal to manually	pop a push marked for automatic	popping	if you
	      need to do so before the function	exits.

	      `fc  -R'	reads  the history from	the given file,	`fc -W'	writes
	      the history out to the given file, and `fc -A' appends the  his-
	      tory  out	 to  the given file.  If no filename is	specified, the
	      $HISTFILE	is assumed.  If	the -I option is  added	 to  -R,  only
	      those  events that are not already contained within the internal
	      history list are added.  If the -I option	is added to -A or  -W,
	      only  those  events  that	 are  new  since  last incremental ap-
	      pend/write to the	history	file  are  appended/written.   In  any
	      case, the	created	file will have no more than $SAVEHIST entries.

       fg [ job	... ]
       job ...
	      Bring  each  specified job in turn to the	foreground.  If	no job
	      is specified, resume the current job.

       float [ {+|-}Hghlprtux ]	[ {+|-}EFLRZ [ n ] ] [ name[=value] ...	]
	      Equivalent to typeset -E,	 except	 that  options	irrelevant  to
	      floating point numbers are not permitted.

       functions [ {+|-}UkmtTuz	] [ -x num ] [ name ...	]
       functions -M mathfn [ min [ max [ shellfn ] ] ]
       functions -M [ -m pattern ... ]
       functions +M [ -m ] mathfn ...
	      Equivalent  to  typeset  -f, with	the exception of the -x	and -M
	      options.

	      The -x option indicates that any functions output	will have each
	      leading  tab for indentation, added by the shell to show syntac-
	      tic structure, expanded to the given number num of spaces.   num
	      can also be 0 to suppress	all indentation.

	      Use of the -M option may not be combined with any	of the options
	      handled by typeset -f.

	      functions	-M mathfn defines mathfn as the	name of	a mathematical
	      function	recognised  in	all forms of arithmetical expressions;
	      see the section `Arithmetic Evaluation' in zshmisc(1).   By  de-
	      fault  mathfn  may take any number of comma-separated arguments.
	      If min is	given, it must have exactly min	args; if min  and  max
	      are  both	given, it must have at least min and at	most max args.
	      max may be -1 to indicate	that there is no upper limit.

	      By default the function is implemented by	a  shell  function  of
	      the  same	name; if shellfn is specified it gives the name	of the
	      corresponding shell function while mathfn	remains	the name  used
	      in  arithmetical expressions.  The name of the function in $0 is
	      mathfn (not shellfn as would usually be the case), provided  the
	      option FUNCTION_ARGZERO is in effect.  The positional parameters
	      in the shell function correspond to the arguments	of the	mathe-
	      matical  function	call.  The result of the last arithmetical ex-
	      pression evaluated inside	the shell function (even if  it	 is  a
	      form  that  normally  only returns a status) gives the result of
	      the mathematical function.

	      functions	-M with	no arguments lists all such user-defined func-
	      tions in the same	form as	a definition.  With the	additional op-
	      tion -m and a list of  arguments,	 all  functions	 whose	mathfn
	      matches one of the pattern arguments are listed.

	      function +M removes the list of mathematical functions; with the
	      additional option	-m the arguments are treated as	 patterns  and
	      all  functions  whose  mathfn  matches  the pattern are removed.
	      Note that	the shell function implementing	the behaviour  is  not
	      removed (regardless of whether its name coincides	with mathfn).

	      For example, the following prints	the cube of 3:

		     zmath_cube() { (( $1 * $1 * $1 )) }
		     functions -M cube 1 1 zmath_cube
		     print $(( cube(3) ))

       getcap See the section `The zsh/cap Module' in zshmodules(1).

       getln [ -AclneE ] name ...
	      Read the top value from the buffer stack and put it in the shell
	      parameter	name.  Equivalent to read -zr.

       getopts optstring name [	arg ...	]
	      Checks the args for legal	options.  If the args are omitted, use
	      the  positional parameters.  A valid option argument begins with
	      a	`+' or a `-'.  An argument not beginning with a	`+' or a  `-',
	      or  the argument `--', ends the options.	Note that a single `-'
	      is not considered	a valid	option argument.   optstring  contains
	      the letters that getopts recognizes.  If a letter	is followed by
	      a	`:', that option requires an argument.	 The  options  can  be
	      separated	from the argument by blanks.

	      Each  time  it  is  invoked, getopts places the option letter it
	      finds in the shell parameter name, prepended with	a `+' when arg
	      begins  with  a  `+'.   The  index  of the next arg is stored in
	      OPTIND.  The option argument, if any, is stored in OPTARG.

	      The first	option to be examined may be changed by	explicitly as-
	      signing  to  OPTIND.   OPTIND  has an initial value of 1,	and is
	      normally set to 1	upon entry to a	shell  function	 and  restored
	      upon  exit (this is disabled by the POSIX_BUILTINS option).  OP-
	      TARG is not reset	and retains its	value  from  the  most	recent
	      call  to	getopts.   If either of	OPTIND or OPTARG is explicitly
	      unset, it	remains	unset, and the index or	option argument	is not
	      stored.  The option itself is still stored in name in this case.

	      A	leading	`:' in optstring causes	getopts	to store the letter of
	      any invalid option in OPTARG, and	to set name to `?' for an  un-
	      known  option  and  to  `:' when a required argument is missing.
	      Otherwise, getopts sets name to `?' and prints an	error  message
	      when  an	option	is  invalid.   The exit	status is nonzero when
	      there are	no more	options.

       hash [ -Ldfmrv ]	[ name[=value] ] ...
	      hash can be used to directly modify the contents of the  command
	      hash  table,  and	 the named directory hash table.  Normally one
	      would modify these tables	by modifying one's PATH	(for the  com-
	      mand  hash  table)  or  by creating appropriate shell parameters
	      (for the named directory hash table).  The choice	of hash	 table
	      to  work	on  is determined by the -d option; without the	option
	      the command hash table is	used, and with the  option  the	 named
	      directory	hash table is used.

	      Given  no	 arguments,  and neither the -r	or -f options, the se-
	      lected hash table	will be	listed in full.

	      The -r option causes the selected	hash table to be emptied.   It
	      will  be subsequently rebuilt in the normal fashion.  The	-f op-
	      tion causes the selected hash table to be	fully rebuilt  immedi-
	      ately.   For the command hash table this hashes all the absolute
	      directories in the PATH, and for the named directory hash	 table
	      this adds	all users' home	directories.  These two	options	cannot
	      be used with any arguments.

	      The -m option causes the	arguments  to  be  taken  as  patterns
	      (which  should  be  quoted)  and	the elements of	the hash table
	      matching those patterns are printed.  This is the	 only  way  to
	      display a	limited	selection of hash table	elements.

	      For  each	name with a corresponding value, put `name' in the se-
	      lected hash table, associating it	with the pathname `value'.  In
	      the  command hash	table, this means that whenever	`name' is used
	      as a command argument, the shell will try	to  execute  the  file
	      given by `value'.	 In the	named directory	hash table, this means
	      that `value' may be referred to as `~name'.

	      For each name with no corresponding value, attempt to  add  name
	      to the hash table, checking what the appropriate value is	in the
	      normal manner for	that hash  table.   If	an  appropriate	 value
	      can't be found, then the hash table will be unchanged.

	      The -v option causes hash	table entries to be listed as they are
	      added by explicit	specification.	If has no effect if used  with
	      -f.

	      If the -L	flag is	present, then each hash	table entry is printed
	      in the form of a call to hash.

       history
	      Same as fc -l.

       integer [ {+|-}Hghlprtux	] [ {+|-}LRZi [	n ] ] [	name[=value] ... ]
	      Equivalent to typeset -i,	except that options irrelevant to  in-
	      tegers are not permitted.

       jobs [ -dlprs ] [ job ... ]
       jobs -Z string
	      Lists  information  about	 each given job, or all	jobs if	job is
	      omitted.	The -l flag lists process IDs, and the -p  flag	 lists
	      process  groups.	 If the	-r flag	is specified only running jobs
	      will be listed and if the	-s flag	is given only stopped jobs are
	      shown.   If  the	-d flag	is given, the directory	from which the
	      job was started (which may not be	the current directory  of  the
	      job) will	also be	shown.

	      The  -Z  option  replaces	 the  shell's argument and environment
	      space with the given string,  truncated  if  necessary  to  fit.
	      This will	normally be visible in ps (ps(1)) listings.  This fea-
	      ture is typically	used by	daemons, to indicate their state.

       kill [ -s signal_name | -n signal_number	| -sig ] job ...
       kill -l [ sig ... ]
	      Sends either SIGTERM or the specified signal to the  given  jobs
	      or  processes.  Signals are given	by number or by	names, with or
	      without the `SIG'	prefix.	 If  the  signal  being	 sent  is  not
	      `KILL'  or  `CONT', then the job will be sent a `CONT' signal if
	      it is stopped.  The argument job can be the process ID of	a  job
	      not in the job list.  In the second form,	kill -l, if sig	is not
	      specified	the signal names are listed.  Otherwise, for each  sig
	      that  is a name, the corresponding signal	number is listed.  For
	      each 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.

	      On some systems, alternative signal names	are allowed for	a  few
	      signals.	Typical	examples are SIGCHLD and SIGCLD	or SIGPOLL and
	      SIGIO, assuming they correspond to the same signal number.  kill
	      -l  will	only list the preferred	form, however kill -l alt will
	      show if the alternative form corresponds	to  a  signal  number.
	      For example, under Linux kill -l IO and kill -l POLL both	output
	      29, hence	kill -IO and kill -POLL	have the same effect.

	      Many systems will	allow process IDs to be	 negative  to  kill  a
	      process group or zero to kill the	current	process	group.

       let arg ...
	      Evaluate	each arg as an arithmetic expression.  See the section
	      `Arithmetic Evaluation'  in  zshmisc(1)  for  a  description  of
	      arithmetic  expressions.	 The  exit status is 0 if the value of
	      the last expression is nonzero, 1	if it is zero, and 2 if	an er-
	      ror occurred.

       limit [ -hs ] [ resource	[ limit	] ] ...
	      Set  or  display	resource limits.  Unless the -s	flag is	given,
	      the limit	applies	only the children of  the  shell.   If	-s  is
	      given  without  other arguments, the resource limits of the cur-
	      rent shell is set	to the previously set resource limits  of  the
	      children.

	      If limit is not specified, print the current limit placed	on re-
	      source, otherwise	set the	limit to the specified value.  If  the
	      -h flag is given,	use hard limits	instead	of soft	limits.	 If no
	      resource is given, print all limits.

	      When looping over	multiple resources, the	shell will abort imme-
	      diately  if  it detects a	badly formed argument.	However, if it
	      fails to set a limit for some other reason it will continue try-
	      ing to set the remaining limits.

	      resource can be one of:

	      addressspace
		     Maximum amount of address space used.
	      aiomemorylocked
		     Maximum  amount  of  memory  locked in RAM	for AIO	opera-
		     tions.
	      aiooperations
		     Maximum number of AIO operations.
	      cachedthreads
		     Maximum number of cached threads.
	      coredumpsize
		     Maximum size of a core dump.
	      cputime
		     Maximum CPU seconds per process.
	      datasize
		     Maximum data size (including stack) for each process.
	      descriptors
		     Maximum value for a file descriptor.
	      filesize
		     Largest single file allowed.
	      kqueues
		     Maximum number of kqueues allocated.
	      maxproc
		     Maximum number of processes.
	      maxpthreads
		     Maximum number of threads per process.
	      memorylocked
		     Maximum amount of memory locked in	RAM.
	      memoryuse
		     Maximum resident set size.
	      msgqueue
		     Maximum number of bytes in	POSIX message queues.
	      posixlocks
		     Maximum number of POSIX locks per user.
	      pseudoterminals
		     Maximum number of pseudo-terminals.
	      resident
		     Maximum resident set size.
	      sigpending
		     Maximum number of pending signals.
	      sockbufsize
		     Maximum size of all socket	buffers.
	      stacksize
		     Maximum stack size	for each process.
	      swapsize
		     Maximum amount of swap used.
	      vmemorysize
		     Maximum amount of virtual memory.

	      Which of these resource limits are available depends on the sys-
	      tem.  resource can be abbreviated	to any unambiguous prefix.  It
	      can also be an integer, which corresponds	to the integer defined
	      for the resource by the operating	system.

	      If argument corresponds to a number which	is out of the range of
	      the resources configured into the	shell, the shell will  try  to
	      read or write the	limit anyway, and will report an error if this
	      fails.  As the shell does	not store such	resources  internally,
	      an  attempt  to  set the limit will fail unless the -s option is
	      present.

	      limit is a number, with an optional scaling factor, as follows:

	      nh     hours
	      nk     kilobytes (default)
	      nm     megabytes or minutes
	      ng     gigabytes
	      [mm:]ss
		     minutes and seconds

	      The limit	command	is not made  available	by  default  when  the
	      shell  starts in a mode emulating	another	shell.	It can be made
	      available	with the command `zmodload -F zsh/rlimits b:limit'.

       local [ {+|-}AHUahlprtux	] [ {+|-}EFLRZi	[ n ] ]	[ name[=value] ... ]
	      Same as typeset, except that the options -g, and -f are not per-
	      mitted.	In  this  case the -x option does not force the	use of
	      -g, i.e. exported	variables will be local	to functions.

       log    List all users currently logged in who are affected by the  cur-
	      rent setting of the watch	parameter.

       logout [	n ]
	      Same as exit, except that	it only	works in a login shell.

       noglob simple command
	      See the section `Precommand Modifiers' in	zshmisc(1).

       popd [ -q ] [ {+|-}n ]
	      Remove  an  entry	 from the directory stack, and perform a cd to
	      the new top directory.  With no argument,	the current top	 entry
	      is removed.  An argument of the form `+n'	identifies a stack en-
	      try by counting from the left of the list	shown by the dirs com-
	      mand,  starting  with  zero.   An	argument of the	form -n	counts
	      from the right.  If the PUSHD_MINUS option is set, the  meanings
	      of `+' and `-' in	this context are swapped.

	      If  the  -q (quiet) option is specified, the hook	function chpwd
	      and the functions	in the array $chpwd_functions are not  called,
	      and  the new directory stack is not printed.  This is useful for
	      calls to popd that do not	change the environment seen by an  in-
	      teractive	user.

       print [ -abcDilmnNoOpPrsSz ] [ -u n ] [ -f format ] [ -C	cols ]
	     [ -v name ] [ -xX tabstop ] [ -R [	-en ]] [ arg ... ]
	      With  the	 `-f' option the arguments are printed as described by
	      printf.  With no flags or	with the flag `-', the	arguments  are
	      printed  on  the	standard output	as described by	echo, with the
	      following	differences: the escape	 sequence  `\M-x'  (or	`\Mx')
	      metafies	the  character	x  (sets  the highest bit), `\C-x' (or
	      `\Cx') produces a	control	character (`\C-@' and `\C-?' give  the
	      characters NULL and delete), a character code in octal is	repre-
	      sented by	`\NNN' (instead	of `\0NNN'), and `\E' is a synonym for
	      `\e'.   Finally,	if  not	in an escape sequence, `\' escapes the
	      following	character and is not printed.

	      -a     Print arguments with the column incrementing first.  Only
		     useful with the -c	and -C options.

	      -b     Recognize	all the	escape sequences defined for the bind-
		     key command, see the section `Zle Builtins' in zshzle(1).

	      -c     Print the arguments in columns.  Unless -a	is also	given,
		     arguments are printed with	the row	incrementing first.

	      -C cols
		     Print  the	 arguments in cols columns.  Unless -a is also
		     given, arguments are printed with	the  row  incrementing
		     first.

	      -D     Treat  the	 arguments  as paths, replacing	directory pre-
		     fixes  with  ~  expressions  corresponding	 to  directory
		     names, as appropriate.

	      -i     If	 given	together  with	-o or -O, sorting is performed
		     case-independently.

	      -l     Print the arguments separated by newlines instead of spa-
		     ces.

	      -m     Take  the first argument as a pattern (should be quoted),
		     and remove	it from	the argument list together with	subse-
		     quent arguments that do not match this pattern.

	      -n     Do	not add	a newline to the output.

	      -N     Print the arguments separated and terminated by nulls.

	      -o     Print the arguments sorted	in ascending order.

	      -O     Print the arguments sorted	in descending order.

	      -p     Print the arguments to the	input of the coprocess.

	      -P     Perform  prompt  expansion	 (see  EXPANSION OF PROMPT SE-
		     QUENCES in	zshmisc(1)).

	      -r     Ignore the	escape conventions of echo.

	      -R     Emulate the BSD echo command, which does not process  es-
		     cape  sequences unless the	-e flag	is given.  The -n flag
		     suppresses	the trailing newline.	Only  the  -e  and  -n
		     flags  are	 recognized  after -R; all other arguments and
		     options are printed.

	      -s     Place the results in the history list instead of  on  the
		     standard  output.	 Each argument to the print command is
		     treated as	a single word in the  history,	regardless  of
		     its content.

	      -S     Place  the	 results in the	history	list instead of	on the
		     standard output.  In this case only a single argument  is
		     allowed; it will be split into words as if	it were	a full
		     shell command line.  The effect is	similar	to reading the
		     line  from	 a history file	with the HIST_LEX_WORDS	option
		     active.

	      -u n   Print the arguments to file descriptor n.

	      -v name
		     Store the printed arguments as the	value of the parameter
		     name.

	      -x tab-stop
		     Expand leading tabs on each line of output	in the printed
		     string assuming a tab  stop  every	 tab-stop  characters.
		     This  is  appropriate for formatting code that may	be in-
		     dented with tabs.	Note that leading tabs of any argument
		     to	print, not just	the first, are expanded, even if print
		     is	using spaces to	separate arguments (the	 column	 count
		     is	 maintained  across  arguments but may be incorrect on
		     output owing to previous unexpanded tabs).

		     The start of the output of	each print command is  assumed
		     to	be aligned with	a tab stop.  Widths of multibyte char-
		     acters are	handled	if the option MULTIBYTE	is in  effect.
		     This option is ignored if other formatting	options	are in
		     effect, namely column alignment or	printf	style,	or  if
		     output  is	to a special location such as shell history or
		     the command line editor.

	      -X tab-stop
		     This is similar to	 -x,  except  that  all	 tabs  in  the
		     printed string are	expanded.  This	is appropriate if tabs
		     in	the arguments are being	used to	produce	a  table  for-
		     mat.

	      -z     Push  the	arguments onto the editing buffer stack, sepa-
		     rated by spaces.

	      If any of	`-m', `-o' or `-O' are used in combination  with  `-f'
	      and  there  are  no  arguments (after the	removal	process	in the
	      case of `-m') then nothing is printed.

       printf [	-v name	] format [ arg ... ]
	      Print the	arguments according to the format specification.  For-
	      matting  rules  are  the	same as	used in	C. The same escape se-
	      quences as for echo are recognised in the	format.	All C  conver-
	      sion specifications ending in one	of csdiouxXeEfgGn are handled.
	      In addition to this, `%b'	can be used instead of `%s'  to	 cause
	      escape  sequences	 in the	argument to be recognised and `%q' can
	      be used to quote the argument in such a way that allows it to be
	      reused  as  shell	 input.	With the numeric format	specifiers, if
	      the corresponding	argument starts	with a	quote  character,  the
	      numeric  value  of the following character is used as the	number
	      to print;	otherwise the argument is evaluated as	an  arithmetic
	      expression.  See	the  section  `Arithmetic  Evaluation' in zsh-
	      misc(1) for a description	of arithmetic expressions. With	 `%n',
	      the  corresponding  argument  is taken as	an identifier which is
	      created as an integer parameter.

	      Normally,	conversion specifications are applied to each argument
	      in  order	but they can explicitly	specify	the nth	argument is to
	      be used by replacing `%' by `%n$'	and `*'	by `*n$'.  It is  rec-
	      ommended	that  you do not mix references	of this	explicit style
	      with the normal style and	the handling of	such mixed styles  may
	      be subject to future change.

	      If  arguments  remain unused after formatting, the format	string
	      is reused	until all arguments have been consumed.	With the print
	      builtin,	this can be suppressed by using	the -r option. If more
	      arguments	are required by	the format than	have  been  specified,
	      the  behaviour  is as if zero or an empty	string had been	speci-
	      fied as the argument.

	      The -v option causes the output to be stored as the value	of the
	      parameter	 name, instead of printed. If name is an array and the
	      format string is reused when consuming arguments then one	 array
	      element will be used for each use	of the format string.

       pushd [ -qsLP ] [ arg ]
       pushd [ -qsLP ] old new
       pushd [ -qsLP ] {+|-}n
	      Change the current directory, and	push the old current directory
	      onto the directory stack.	 In the	first form, change the current
	      directory	to arg.	 If arg	is not specified, change to the	second
	      directory	on the stack (that is, exchange	the top	two  entries),
	      or  change  to  $HOME  if	 the PUSHD_TO_HOME option is set or if
	      there is only one	entry on the stack.  Otherwise,	arg is	inter-
	      preted  as it would be by	cd.  The meaning of old	and new	in the
	      second form is also the same as for cd.

	      The third	form of	pushd changes directory	by rotating the	direc-
	      tory  list.  An argument of the form `+n'	identifies a stack en-
	      try by counting from the left of the list	shown by the dirs com-
	      mand,  starting  with zero.  An argument of the form `-n'	counts
	      from the right.  If the PUSHD_MINUS option is set, the  meanings
	      of `+' and `-' in	this context are swapped.

	      If  the  -q (quiet) option is specified, the hook	function chpwd
	      and the functions	in the array $chpwd_functions are not  called,
	      and  the new directory stack is not printed.  This is useful for
	      calls to pushd that do not change	the environment	seen by	an in-
	      teractive	user.

	      If  the  option  -q  is  not  specified  and  the	 shell	option
	      PUSHD_SILENT is not set, the directory stack will	be printed af-
	      ter a pushd is performed.

	      The  options  -s,	-L and -P have the same	meanings as for	the cd
	      builtin.

       pushln [	arg ...	]
	      Equivalent to print -nz.

       pwd [ -rLP ]
	      Print the	absolute pathname of the  current  working  directory.
	      If the -r	or the -P flag is specified, or	the CHASE_LINKS	option
	      is set and the -L	flag is	not given, the printed path  will  not
	      contain symbolic links.

       r      Same as fc -e -.

       read [ -rszpqAclneE ] [ -t [ num	] ] [ -k [ num ] ] [ -d	delim ]
	    [ -u n ] [ name[?prompt] ] [ name ...  ]
	      Read  one	 line and break	it into	fields using the characters in
	      $IFS as separators, except as noted below.  The first  field  is
	      assigned to the first name, the second field to the second name,
	      etc., with leftover fields assigned to the last name.   If  name
	      is omitted then REPLY is used for	scalars	and reply for arrays.

	      -r     Raw  mode:	 a  `\'	 at the	end of a line does not signify
		     line continuation and backslashes in the line don't quote
		     the following character and are not removed.

	      -s     Don't echo	back characters	if reading from	the terminal.

	      -q     Read only one character from the terminal and set name to
		     `y' if this character was `y' or `Y' and  to  `n'	other-
		     wise.   With this flag set	the return status is zero only
		     if	the character was `y' or `Y'.  This option may be used
		     with  a  timeout  (see -t); if the	read times out,	or en-
		     counters end of file, status 2  is	 returned.   Input  is
		     read from the terminal unless one of -u or	-p is present.
		     This option may also be used within zle widgets.

	      -k [ num ]
		     Read only one (or num) characters.	 All are  assigned  to
		     the first name, without word splitting.  This flag	is ig-
		     nored when	-q is present.	Input is read from the	termi-
		     nal  unless  one of -u or -p is present.  This option may
		     also be used within zle widgets.

		     Note that despite the mnemonic  `key'  this  option  does
		     read full characters, which may consist of	multiple bytes
		     if	the option MULTIBYTE is	set.

	      -z     Read one entry from the editor buffer stack and assign it
		     to	 the  first  name,  without  word  splitting.  Text is
		     pushed onto the stack with	`print -z' or  with  push-line
		     from  the	line editor (see zshzle(1)).  This flag	is ig-
		     nored when	the -k or -q flags are present.

	      -e
	      -E     The input read is printed (echoed)	to the	standard  out-
		     put.  If the -e flag is used, no input is assigned	to the
		     parameters.

	      -A     The first name is taken as	the name of an array  and  all
		     words are assigned	to it.

	      -c
	      -l     These  flags are allowed only if called inside a function
		     used for completion (specified with the -K	flag  to  com-
		     pctl).  If	the -c flag is given, the words	of the current
		     command are read. If the -l flag is given,	the whole line
		     is	 assigned  as a	scalar.	 If both flags are present, -l
		     is	used and -c is ignored.

	      -n     Together with -c, the number of the word the cursor is on
		     is	 read.	With -l, the index of the character the	cursor
		     is	on is read.  Note that the command name	is word	number
		     1,	 not word 0, and that when the cursor is at the	end of
		     the line, its character index is the length of  the  line
		     plus one.

	      -u n   Input is read from	file descriptor	n.

	      -p     Input is read from	the coprocess.

	      -d delim
		     Input  is	terminated by the first	character of delim in-
		     stead of by newline.

	      -t [ num ]
		     Test if input is available	before attempting to read.  If
		     num  is  present,	it must	begin with a digit and will be
		     evaluated to give a number	of seconds,  which  may	 be  a
		     floating point number; in this case the read times	out if
		     input is not available within this	time.  If num  is  not
		     present, it is taken to be	zero, so that read returns im-
		     mediately if no input  is	available.   If	 no  input  is
		     available,	return status 1	and do not set any variables.

		     This option is not	available when reading from the	editor
		     buffer with -z, when called from within  completion  with
		     -c	 or  -l,  with	-q which clears	the input queue	before
		     reading, or within	zle where other	mechanisms  should  be
		     used to test for input.

		     Note  that	 read does not attempt to alter	the input pro-
		     cessing mode.  The	default	mode is	 canonical  input,  in
		     which  an entire line is read at a	time, so usually `read
		     -t' will not read anything	until an entire	line has  been
		     typed.   However,	when reading from the terminal with -k
		     input is processed	one key	at a time; in this case,  only
		     availability  of  the  first character is tested, so that
		     e.g. `read	-t -k 2' can still block on the	second charac-
		     ter.   Use	 two  instances	of `read -t -k'	if this	is not
		     what is wanted.

	      If the first argument contains a `?', the	remainder of this word
	      is used as a prompt on standard error when the shell is interac-
	      tive.

	      The value	(exit status) of read is 1 when	an end-of-file is  en-
	      countered,  or  when  -c or -l is	present	and the	command	is not
	      called from a compctl function, or as described for -q.	Other-
	      wise the value is	0.

	      The  behavior  of	some combinations of the -k, -p, -q, -u	and -z
	      flags is undefined.  Presently -q	cancels	 all  the  others,  -p
	      cancels  -u, -k cancels -z, and otherwise	-z cancels both	-p and
	      -u.

	      The -c or	-l flags cancel	any and	all of -kpquz.

       readonly
	      Same as typeset -r.  With	the POSIX_BUILTINS option set, same as
	      typeset -gr.

       rehash Same as hash -r.

       return [	n ]
	      Causes  a	shell function or `.' script to	return to the invoking
	      script with the return status specified by an arithmetic expres-
	      sion  n.	If n is	omitted, the return status is that of the last
	      command executed.

	      If return	was executed from a trap in a  TRAPNAL	function,  the
	      effect  is  different for	zero and non-zero 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 pro-
	      cessing; with a non-zero status, the shell will behave as	inter-
	      rupted  except  that  the	return status of the trap is retained.
	      Note that	the numeric value of the signal	which caused the  trap
	      is  passed  as  the  first  argument,  so	 the statement `return
	      $((128+$1))' will	return the same	status as if  the  signal  had
	      not been trapped.

       sched  See the section `The zsh/sched Module' in	zshmodules(1).

       set [ {+|-}options | {+|-}o [ option_name ] ] ... [ {+|-}A [ name ] ]
	   [ arg ... ]
	      Set  the options for the shell and/or set	the positional parame-
	      ters, or declare and set an array.  If the -s option  is	given,
	      it  causes the specified arguments to be sorted before assigning
	      them to the positional parameters	(or to the array name if -A is
	      used).   With  +s	 sort  arguments in descending order.  For the
	      meaning of the other flags, see  zshoptions(1).	Flags  may  be
	      specified	by name	using the -o option. If	no option name is sup-
	      plied with -o, the current option	states are printed:   see  the
	      description  of setopt below for more information	on the format.
	      With +o they are printed in a form that can be used as input  to
	      the shell.

	      If  the -A flag is specified, name is set	to an array containing
	      the given	args; if no name is specified, all arrays are  printed
	      together with their values.

	      If +A is used and	name is	an array, the given arguments will re-
	      place the	initial	elements of that array;	if no name  is	speci-
	      fied, all	arrays are printed without their values.

	      The  behaviour  of arguments after -A name or +A name depends on
	      whether the option KSH_ARRAYS is set.  If	it is not set, all ar-
	      guments  following name are treated as values for	the array, re-
	      gardless of their	form.  If the option  is  set,	normal	option
	      processing  continues  at	that point; only regular arguments are
	      treated as values	for the	array.	This means that

		     set -A array -x --	foo

	      sets array to `-x	-- foo'	if KSH_ARRAYS is not set, but sets the
	      array to foo and turns on	the option `-x'	if it is set.

	      If  the  -A  flag	is not present,	but there are arguments	beyond
	      the options, the positional parameters are set.  If  the	option
	      list  (if	 any)  is terminated by	`--', and there	are no further
	      arguments, the positional	parameters will	be unset.

	      If no arguments and no `--' are given, then the names and	values
	      of  all  parameters  are printed on the standard output.	If the
	      only argument is `+', the	names of all parameters	are printed.

	      For historical reasons, `set -' is treated as `set +xv' and `set
	      -	 args'	as  `set +xv --	args' when in any other	emulation mode
	      than zsh's native	mode.

       setcap See the section `The zsh/cap Module' in zshmodules(1).

       setopt [	{+|-}options | {+|-}o option_name ] [ -m ] [ name ... ]
	      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.	The form is chosen so as to minimize the  dif-
	      ferences from the	default	options	for the	current	emulation (the
	      default emulation	being native  zsh,  shown  as  <Z>  in	zshop-
	      tions(1)).  Options that are on by default for the emulation are
	      shown with the prefix no only if they are	off, while  other  op-
	      tions  are  shown	without	the prefix no and only if they are on.
	      In addition to options changed from the  default	state  by  the
	      user,  any options activated automatically by the	shell (for ex-
	      ample, SHIN_STDIN	or INTERACTIVE)	will be	 shown	in  the	 list.
	      The  format  is further modified by the option KSH_OPTION_PRINT,
	      however the rationale for	choosing options with or  without  the
	      no prefix	remains	the same in this case.

	      If  the  -m  flag	 is  given the arguments are taken as patterns
	      (which should be quoted to protect  them	from  filename	expan-
	      sion),  and  all	options	with names matching these patterns are
	      set.

	      Note that	a bad option name does not cause execution  of	subse-
	      quent  shell  code to be aborted;	this is	behaviour is different
	      from that	of `set	-o'.  This is because set  is  regarded	 as  a
	      special builtin by the POSIX standard, but setopt	is not.

       shift [ -p ] [ n	] [ name ... ]
	      The  positional  parameters  ${n+1}  ...	are renamed to $1 ...,
	      where n is an arithmetic expression that defaults	to 1.  If  any
	      names are	given then the arrays with these names are shifted in-
	      stead of the positional parameters.

	      If the option -p is given	arguments are instead removed (popped)
	      from the end rather than the start of the	array.

       source file [ arg ... ]
	      Same  as	`.',  except  that  the	 current  directory  is	always
	      searched and is always searched  first,  before  directories  in
	      $path.

       stat   See the section `The zsh/stat Module' in zshmodules(1).

       suspend [ -f ]
	      Suspend  the execution of	the shell (send	it a SIGTSTP) until it
	      receives a SIGCONT.  Unless the -f option	is  given,  this  will
	      refuse to	suspend	a login	shell.

       test [ arg ... ]
       [ [ arg ... ] ]
	      Like  the	 system	version	of test.  Added	for compatibility; use
	      conditional expressions instead (see  the	 section  `Conditional
	      Expressions').  The main differences between the conditional ex-
	      pression syntax and the test and [ builtins are:	these commands
	      are  not handled syntactically, so for example an	empty variable
	      expansion	may cause an argument to  be  omitted;	syntax	errors
	      cause  status  2	to  be	returned instead of a shell error; and
	      arithmetic operators expect integer arguments rather than	arith-
	      metic expressions.

	      The command attempts to implement	POSIX and its extensions where
	      these are	specified.  Unfortunately there	are intrinsic ambigui-
	      ties  in	the  syntax; in	particular there is no distinction be-
	      tween test operators and strings that resemble them.  The	 stan-
	      dard  attempts  to  resolve these	for small numbers of arguments
	      (up to four); for	five or	more arguments compatibility cannot be
	      relied  on.   Users  are urged wherever possible to use the `[['
	      test syntax which	does not have these ambiguities.

       times  Print the	accumulated user and system times for  the  shell  and
	      for processes run	from the shell.

       trap [ arg ] [ sig ... ]
	      arg  is  a series	of commands (usually quoted to protect it from
	      immediate	evaluation by the shell) to be read and	executed  when
	      the  shell  receives any of the signals specified	by one or more
	      sig args.	 Each sig can be given as a number, or as the name  of
	      a	signal either with or without the string SIG in	front (e.g. 1,
	      HUP, and SIGHUP are all the same signal).

	      If arg is	`-', then the specified	signals	are reset to their de-
	      faults, or, if no	sig args are present, all traps	are reset.

	      If  arg  is  an empty string, then the specified signals are ig-
	      nored by the shell (and by the commands it invokes).

	      If arg is	omitted	but one	or more	sig args  are  provided	 (i.e.
	      the first	argument is a valid signal number or name), the	effect
	      is the same as if	arg had	been specified as `-'.

	      The trap command with no arguments prints	a list of commands as-
	      sociated with each signal.

	      If sig is	ZERR then arg will be executed after each command with
	      a	nonzero	exit status.  ERR is an	alias for ZERR on systems that
	      have no SIGERR signal (this is the usual case).

	      If sig is	DEBUG then arg will be executed	before each command if
	      the option DEBUG_BEFORE_CMD is set (as it	is by  default),  else
	      after each command.  Here, a `command' is	what is	described as a
	      `sublist'	in the shell grammar, see the section SIMPLE  COMMANDS
	      &	 PIPELINES  in zshmisc(1).  If DEBUG_BEFORE_CMD	is set various
	      additional features are available.  First,  it  is  possible  to
	      skip  the	 next  command by setting the option ERR_EXIT; see the
	      description of the ERR_EXIT option in zshoptions(1).  Also,  the
	      shell parameter ZSH_DEBUG_CMD is set to the string corresponding
	      to the command to	be executed following  the  trap.   Note  that
	      this  string  is	reconstructed from the internal	format and may
	      not be formatted the same	way as the original text.  The parame-
	      ter is unset after the trap is executed.

	      If  sig  is  0 or	EXIT and the trap statement is executed	inside
	      the body of a function, then the command arg is  executed	 after
	      the  function completes.	The value of $?	at the start of	execu-
	      tion is the exit status of the shell or the return status	of the
	      function exiting.	 If sig	is 0 or	EXIT and the trap statement is
	      not executed inside the body of a	function, then the command arg
	      is  executed when	the shell terminates; the trap runs before any
	      zshexit hook functions.

	      ZERR, DEBUG, and EXIT traps are not executed inside other	traps.
	      ZERR  and	 DEBUG	traps  are  kept within	subshells, while other
	      traps are	reset.

	      Note that	traps defined with the trap builtin are	slightly  dif-
	      ferent from those	defined	as `TRAPNAL () { ... }', as the	latter
	      have their own function environment (line	numbers,  local	 vari-
	      ables, etc.) while the former use	the environment	of the command
	      in which they were called.  For example,

		     trap 'print $LINENO' DEBUG

	      will print the line number of a command executed	after  it  has
	      run, while

		     TRAPDEBUG() { print $LINENO; }

	      will always print	the number zero.

	      Alternative  signal  names  are  allowed as described under kill
	      above.  Defining a trap under either name	causes any trap	 under
	      an  alternative  name to be removed.  However, it	is recommended
	      that for consistency users stick exclusively to one name or  an-
	      other.

       true [ arg ... ]
	      Do nothing and return an exit status of 0.

       ttyctl [	-fu ]
	      The  -f option freezes the tty (i.e. terminal or terminal	emula-
	      tor), and	-u unfreezes it.  When the tty is frozen,  no  changes
	      made to the tty settings by external programs will be honored 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 or is suspended.  Thus, stty and sim-
	      ilar  programs  have no effect when the tty is frozen.  Freezing
	      the tty does not cause the current state to be  remembered:  in-
	      stead, it	causes future changes to the state to be blocked.

	      Without  options	it  reports  whether the terminal is frozen or
	      not.

	      Note that, regardless of whether the tty is frozen or  not,  the
	      shell  needs to change the settings when the line	editor starts,
	      so unfreezing the	tty does not guarantee settings	 made  on  the
	      command  line  are  preserved.   Strings of commands run between
	      editing the command line will see	a consistent tty  state.   See
	      also the shell variable STTY for a means of initialising the tty
	      before running external commands.

       type [ -wfpamsS ] name ...
	      Equivalent to whence -v.

       typeset [ {+|-}AHUaghlmprtux ] [	{+|-}EFLRZi [ n	] ]
	       [ + ] [ name[=value] ...	]
       typeset -T [ {+|-}Uglprux ] [ {+|-}LRZ [	n ] ]
	       [ + | SCALAR[=value] array[=(value ...)]	[ sep ]	]
       typeset -f [ {+|-}TUkmtuz ] [ + ] [ name	... ]
	      Set or display attributes	and values for shell parameters.

	      Except as	noted below for	control	flags that change  the	behav-
	      ior,  a parameter	is created for each name that does not already
	      refer to one.  When inside a function, a new parameter  is  cre-
	      ated  for	every name (even those that already exist), and	is un-
	      set again	when the function completes.  See  `Local  Parameters'
	      in  zshparam(1).	 The same rules	apply to special shell parame-
	      ters, which retain their special attributes when made local.

	      For each name=value assignment, the parameter  name  is  set  to
	      value.

	      If  the shell option TYPESET_SILENT is not set, for each remain-
	      ing name that refers to a	parameter that	is  already  set,  the
	      name  and	 value	of the parameter are printed in	the form of an
	      assignment.  Nothing is printed for newly-created	parameters, or
	      when  any	 attribute flags listed	below are given	along with the
	      name.  Using `+' instead of  minus  to  introduce	 an  attribute
	      turns it off.

	      If  no  name  is present,	the names and values of	all parameters
	      are printed.  In this case the attribute flags restrict the dis-
	      play  to	only  those  parameters	 that  have  the specified at-
	      tributes,	and using `+' rather than `-' to  introduce  the  flag
	      suppresses printing of the values	of parameters when there is no
	      parameter	name.

	      All forms	of the command handle scalar  assignment.   Array  as-
	      signment	is  possible if	any of the reserved words declare, ex-
	      port, float, integer, local, readonly or typeset is matched when
	      the line is parsed (N.B. not when	it is executed).  In this case
	      the arguments are	parsed as assignments, except  that  the  `+='
	      syntax  and the GLOB_ASSIGN option are not supported, and	scalar
	      values after = are not split further into	 words,	 even  if  ex-
	      panded  (regardless  of  the  setting of the KSH_TYPESET option;
	      this option is obsolete).

	      Examples of the differences between command  and	reserved  word
	      parsing:

		     # Reserved	word parsing
		     typeset svar=$(echo one word) avar=(several words)

	      The above	creates	a scalar parameter svar	and an array parameter
	      avar as if the assignments had been

		     svar="one word"
		     avar=(several words)

	      On the other hand:

		     # Normal builtin interface
		     builtin typeset svar=$(echo two words)

	      The builtin keyword causes the above to use the standard builtin
	      interface	 to  typeset in	which argument parsing is performed in
	      the same way as for other	 commands.   This  example  creates  a
	      scalar  svar containing the value	two and	another	scalar parame-
	      ter words	with no	value.	An array value in this case would  ei-
	      ther  cause  an  error  or  be treated as	an obscure set of glob
	      qualifiers.

	      Arbitrary	arguments are allowed if they take the form of assign-
	      ments  after command line	expansion; however, these only perform
	      scalar assignment:

		     var='svar=val'
		     typeset $var

	      The above	sets the scalar	 parameter  svar  to  the  value  val.
	      Parentheses  around  the	value within var would not cause array
	      assignment as they will be treated as ordinary  characters  when
	      $var is substituted.  Any	non-trivial expansion in the name part
	      of the assignment	causes the argument  to	 be  treated  in  this
	      fashion:

		     typeset {var1,var2,var3}=name

	      The  above  syntax is valid, and has the expected	effect of set-
	      ting the three parameters	to the same  value,  but  the  command
	      line  is	parsed as a set	of three normal	command	line arguments
	      to typeset after expansion.  Hence it is not possible to	assign
	      to multiple arrays by this means.

	      Note  that  each interface to any	of the commands	my be disabled
	      separately.  For example,	`disable -r typeset' disables the  re-
	      served  word  interface  to typeset, exposing the	builtin	inter-
	      face, while `disable typeset' disables the builtin.   Note  that
	      disabling	 the  reserved	word  interface	 for typeset may cause
	      problems with the	output of `typeset -p',	which assumes the  re-
	      served word interface is available in order to restore array and
	      associative array	values.

	      Unlike parameter assignment statements, typeset's	exit status on
	      an  assignment that involves a command substitution does not re-
	      flect the	exit status of the command  substitution.   Therefore,
	      to  test	for  an	 error in a command substitution, separate the
	      declaration of the parameter from	its initialization:

		     # WRONG
		     typeset var1=$(exit 1) || echo "Trouble with var1"

		     # RIGHT
		     typeset var1 && var1=$(exit 1) || echo "Trouble with var1"

	      To initialize a parameter	param to a command output and mark  it
	      readonly,	 use  typeset -r param or readonly param after the pa-
	      rameter assignment statement.

	      If no attribute flags are	given, and either  no  name  arguments
	      are  present  or	the  flag +m is	used, then each	parameter name
	      printed is preceded by a list of the attributes of that  parame-
	      ter  (array, association,	exported, float, integer, readonly, or
	      undefined	for autoloaded parameters not yet loaded).  If	+m  is
	      used  with  attribute  flags, and	all those flags	are introduced
	      with +, the matching parameter names are printed but their  val-
	      ues are not.

	      The following control flags change the behavior of typeset:

	      +	     If	 `+'  appears by itself	in a separate word as the last
		     option, then the names of all parameters (functions  with
		     -f)  are  printed,	 but  the values (function bodies) are
		     not.  No name arguments may appear, and it	 is  an	 error
		     for  any  other options to	follow `+'.  The effect	of `+'
		     is	as if all attribute flags which	precede	it were	 given
		     with a `+'	prefix.	 For example, `typeset -U +' is	equiv-
		     alent to `typeset +U' and displays	the names of  all  ar-
		     rays having the uniqueness	attribute, whereas `typeset -f
		     -U	+' displays the	names of all  autoloadable  functions.
		     If	 +  is	the only option, then type information (array,
		     readonly, etc.) is	also printed for  each	parameter,  in
		     the same manner as	`typeset +m "*"'.

	      -g     The  -g  (global) means that any resulting	parameter will
		     not be restricted to local	scope.	Note  that  this  does
		     not  necessarily  mean that the parameter will be global,
		     as	the flag will apply to any existing parameter (even if
		     unset)  from  an  enclosing function.  This flag does not
		     affect the	parameter after	creation, hence	it has no  ef-
		     fect  when	listing	existing parameters, nor does the flag
		     +g	have any effect	except in combination with -m (see be-
		     low).

	      -m     If	 the  -m flag is given the name	arguments are taken as
		     patterns (use quoting to prevent these from being	inter-
		     preted  as	 file patterns).  With no attribute flags, all
		     parameters	(or functions with the -f flag)	with  matching
		     names are printed (the shell option TYPESET_SILENT	is not
		     used in this case).

		     If	the +g flag is combined	with -m, a new local parameter
		     is	 created  for every matching parameter that is not al-
		     ready local.  Otherwise -m	applies	all other flags	or as-
		     signments to the existing parameters.

		     Except  when  assignments are made	with name=value, using
		     +m	forces the matching parameters and their attributes to
		     be	 printed, even inside a	function.  Note	that -m	is ig-
		     nored if no patterns are given, so	`typeset -m'  displays
		     attributes	but `typeset -a	+m' does not.

	      -p     If	 the  -p  option  is  given, parameters	and values are
		     printed in	the form of a typeset command with an  assign-
		     ment,  regardless	of other flags and options.  Note that
		     the -H flag on parameters is respected; no	value will  be
		     shown for these parameters.

	      -T [ scalar[=value] array[=(value	...)] [	sep ] ]
		     This  flag	has a different	meaning	when used with -f; see
		     below.  Otherwise the -T option requires  zero,  two,  or
		     three  arguments  to  be present.	With no	arguments, the
		     list of parameters	created	 in  this  fashion  is	shown.
		     With  two	or three arguments, the	first two are the name
		     of	a scalar and of	an array  parameter  (in  that	order)
		     that  will	 be  tied  together in the manner of $PATH and
		     $path.  The optional third	argument is a single-character
		     separator	which will be used to join the elements	of the
		     array to form the scalar; if absent, a colon is used,  as
		     with $PATH.  Only the first character of the separator is
		     significant;  any	remaining  characters	are   ignored.
		     Multibyte characters are not yet supported.

		     Only  one	of  the	scalar and array parameters may	be as-
		     signed an initial value (the restrictions	on  assignment
		     forms described above also	apply).

		     Both  the scalar and the array may	be manipulated as nor-
		     mal.  If one is unset, the	other  will  automatically  be
		     unset  too.   There  is  no  way of untying the variables
		     without unsetting them, nor of converting the type	of one
		     of	 them  with another typeset command; +T	does not work,
		     assigning an array	to scalar is an	error, and assigning a
		     scalar to array sets it to	be a single-element array.

		     Note  that	 both  `typeset	 -xT ...'  and `export -T ...'
		     work, but only the	scalar	will  be  marked  for  export.
		     Setting the value using the scalar	version	causes a split
		     on	all separators (which cannot be	quoted).  It is	possi-
		     ble to apply -T to	two previously tied variables but with
		     a different separator character, in which case the	 vari-
		     ables  remain  joined  as	before	but  the  separator is
		     changed.

	      Attribute	flags that transform the final value (-L, -R, -Z,  -l,
	      -u) are only applied to the expanded value at the	point of a pa-
	      rameter expansion	expression using `$'.  They  are  not  applied
	      when  a  parameter  is retrieved internally by the shell for any
	      purpose.

	      The following attribute flags may	be specified:

	      -A     The names refer to	associative array parameters; see `Ar-
		     ray Parameters' in	zshparam(1).

	      -L [ n ]
		     Left  justify  and	 remove	 leading blanks	from the value
		     when the parameter	is expanded.  If n is nonzero, it  de-
		     fines the width of	the field.  If n is zero, the width is
		     determined	by the width of	the value of the first assign-
		     ment.   In	 the case of numeric parameters, the length of
		     the complete value	assigned to the	parameter is  used  to
		     determine the width, not the value	that would be output.

		     The width is the count of characters, which may be	multi-
		     byte characters if	the MULTIBYTE  option  is  in  effect.
		     Note  that	the screen width of the	character is not taken
		     into account; if this is required,	use padding  with  pa-
		     rameter  expansion	 flags	${(ml...)...}  as described in
		     `Parameter	Expansion Flags' in zshexpn(1).

		     When the parameter	is expanded, it	is filled on the right
		     with  blanks  or truncated	if necessary to	fit the	field.
		     Note truncation can lead to unexpected results  with  nu-
		     meric  parameters.	  Leading  zeros are removed if	the -Z
		     flag is also set.

	      -R [ n ]
		     Similar to	-L, except that	right justification  is	 used;
		     when  the parameter is expanded, the field	is left	filled
		     with blanks or truncated from the end.  May not  be  com-
		     bined with	the -Z flag.

	      -U     For  arrays  (but	not for	associative arrays), keep only
		     the first occurrence of each duplicated value.  This  may
		     also  be  set for colon-separated special parameters like
		     PATH or FIGNORE, etc.  Note the flag takes	effect on  as-
		     signment,	and the	type of	the variable being assigned to
		     is	determinative; for variables with shared values	it  is
		     therefore recommended to set the flag for all interfaces,
		     e.g. `typeset -U PATH path'.

		     This flag has a different meaning when used with -f;  see
		     below.

	      -Z [ n ]
		     Specially	handled	if set along with the -L flag.	Other-
		     wise, similar to -R, except that leading zeros  are  used
		     for  padding  instead  of	blanks	if the first non-blank
		     character is a digit.  Numeric parameters	are  specially
		     handled:  they  are  always eligible for padding with ze-
		     roes, and the zeroes are inserted at an appropriate place
		     in	the output.

	      -a     The  names	refer to array parameters.  An array parameter
		     may be created this way, but it may be assigned to	in the
		     typeset statement only if the reserved word form of type-
		     set is enabled (as	it is by default).   When  displaying,
		     both normal and associative arrays	are shown.

	      -f     The  names	refer to functions rather than parameters.  No
		     assignments can be	made, and the only other  valid	 flags
		     are -t, -T, -k, -u, -U and	-z.  The flag -t turns on exe-
		     cution tracing for	this function; the flag	 -T  does  the
		     same, but turns off tracing for any named (not anonymous)
		     function called from the present one, unless  that	 func-
		     tion  also	 has  the  -t or -T flag.  The -u and -U flags
		     cause the function	to be marked for autoloading; -U  also
		     causes alias expansion to be suppressed when the function
		     is	loaded.	 See the description of	the `autoload' builtin
		     for details.

		     Note  that	 the builtin functions provides	the same basic
		     capabilities as typeset -f	but gives access to a few  ex-
		     tra options.

	      -h     Hide:  only  useful  for special parameters (those	marked
		     `<S>' in the table	in zshparam(1)), and for local parame-
		     ters  with	 the  same name	as a special parameter,	though
		     harmless for others.  A special parameter with  this  at-
		     tribute  will not retain its special effect when made lo-
		     cal.  Thus	after `typeset -h PATH', a function containing
		     `typeset  PATH'  will  create an ordinary local parameter
		     without the usual behaviour of PATH.  Alternatively,  the
		     local parameter may itself	be given this attribute; hence
		     inside a function `typeset	-h PATH' creates  an  ordinary
		     local parameter and the special PATH parameter is not al-
		     tered in any way.	It is also possible to create a	 local
		     parameter	using  `typeset	 +h  special', where the local
		     copy of special will retain its  special  properties  re-
		     gardless  of having the -h	attribute.  Global special pa-
		     rameters loaded from shell	modules	 (currently  those  in
		     zsh/mapfile  and  zsh/parameter)  are automatically given
		     the -h attribute to avoid name clashes.

	      -H     Hide value: specifies that	typeset	will not  display  the
		     value  of the parameter when listing parameters; the dis-
		     play for such parameters is always	as if the `+' flag had
		     been  given.   Use	 of the	parameter is in	other respects
		     normal, and the option does not apply if the parameter is
		     specified	by  name,  or  by  pattern with	the -m option.
		     This is on	by default for the parameters in  the  zsh/pa-
		     rameter and zsh/mapfile modules.  Note, however, that un-
		     like the -h flag this is also useful for non-special  pa-
		     rameters.

	      -i [ n ]
		     Use  an internal integer representation.  If n is nonzero
		     it	defines	the output arithmetic base,  otherwise	it  is
		     determined	 by  the first assignment.  Bases from 2 to 36
		     inclusive are allowed.

	      -E [ n ]
		     Use an internal double-precision floating point represen-
		     tation.  On output	the variable will be converted to sci-
		     entific notation.	If n is	nonzero	it defines the	number
		     of	significant figures to display;	the default is ten.

	      -F [ n ]
		     Use an internal double-precision floating point represen-
		     tation.  On output	the  variable  will  be	 converted  to
		     fixed-point decimal notation.  If n is nonzero it defines
		     the number	of digits to display after the decimal	point;
		     the default is ten.

	      -l     Convert  the  result to lower case	whenever the parameter
		     is	expanded.  The value is	not converted when assigned.

	      -r     The given names are marked	readonly.  Note	that  if  name
		     is	 a  special  parameter,	 the readonly attribute	can be
		     turned on,	but cannot then	be turned off.

		     If	the POSIX_BUILTINS option is set, the readonly	attri-
		     bute  is  more restrictive: unset variables can be	marked
		     readonly and cannot then be set; furthermore,  the	 read-
		     only attribute cannot be removed from any variable.  Note
		     that in zsh (unlike other shells) it is still possible to
		     create  a local variable of the same name as this is con-
		     sidered a different variable (though this variable,  too,
		     can be marked readonly).

	      -t     Tags  the named parameters.  Tags have no special meaning
		     to	the shell.  This flag has  a  different	 meaning  when
		     used with -f; see above.

	      -u     Convert  the  result to upper case	whenever the parameter
		     is	expanded.  The value is	not converted  when  assigned.
		     This  flag	has a different	meaning	when used with -f; see
		     above.

	      -x     Mark for automatic	export to the  environment  of	subse-
		     quently  executed	commands.  If the option GLOBAL_EXPORT
		     is	set, this implies the option -g, unless	+g is also ex-
		     plicitly  given; in other words the parameter is not made
		     local to the enclosing function.  This is for compatibil-
		     ity with previous versions	of zsh.

       ulimit [	-HSa ] [ { -bcdfiklmnpqrsTtvwx | -N resource } [ limit ] ... ]
	      Set  or  display	resource limits	of the shell and the processes
	      started by the shell.  The value of limit	can be a number	in the
	      unit specified below or one of the values	`unlimited', which re-
	      moves the	limit on the resource, or `hard', which	uses the  cur-
	      rent value of the	hard limit on the resource.

	      By  default, only	soft limits are	manipulated. If	the -H flag is
	      given use	hard limits instead of soft limits.  If	the -S flag is
	      given together with the -H flag set both hard and	soft limits.

	      If no options are	used, the file size limit (-f) is assumed.

	      If limit is omitted the current value of the specified resources
	      are printed.  When more than one resource	value is printed,  the
	      limit name and unit is printed before each value.

	      When looping over	multiple resources, the	shell will abort imme-
	      diately if it detects a badly formed argument.  However,	if  it
	      fails to set a limit for some other reason it will continue try-
	      ing to set the remaining limits.

	      Not all the following resources are supported  on	 all  systems.
	      Running ulimit -a	will show which	are supported.

	      -a     Lists all of the current resource limits.
	      -b     Socket buffer size	in bytes (N.B. not kilobytes)
	      -c     512-byte blocks on	the size of core dumps.
	      -d     Kilobytes on the size of the data segment.
	      -f     512-byte blocks on	the size of files written.
	      -i     The number	of pending signals.
	      -k     The number	of kqueues allocated.
	      -l     Kilobytes on the size of locked-in	memory.
	      -m     Kilobytes on the size of physical memory.
	      -n     open file descriptors.
	      -p     The number	of pseudo-terminals.
	      -q     Bytes in POSIX message queues.
	      -r     Maximum  real  time priority.  On some systems where this
		     is	not available, such as NetBSD, this has	the  same  ef-
		     fect as -T	for compatibility with sh.
	      -s     Kilobytes on the size of the stack.
	      -T     The number	of simultaneous	threads	available to the user.
	      -t     CPU seconds to be used.
	      -u     The number	of processes available to the user.
	      -v     Kilobytes on the size of virtual memory.  On some systems
		     this refers to the	limit called `address space'.
	      -w     Kilobytes on the size of swapped out memory.
	      -x     The number	of locks on files.

	      A	resource may also be specified by integer in the form `-N  re-
	      source',	where  resource	corresponds to the integer defined for
	      the resource by the operating system.  This may be used  to  set
	      the  limits for resources	known to the shell which do not	corre-
	      spond to option letters.	Such limits will be shown by number in
	      the output of `ulimit -a'.

	      The  number may alternatively be out of the range	of limits com-
	      piled into the shell.  The shell will try	to read	or  write  the
	      limit anyway, and	will report an error if	this fails.

       umask [ -S ] [ mask ]
	      The umask	is set to mask.	 mask can be either an octal number or
	      a	symbolic value as described in chmod(1).  If mask is  omitted,
	      the  current value is printed.  The -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 permis-
	      sions you	specify	are those which	are to be allowed (not denied)
	      to the users specified.

       unalias [ -ams ]	name ...
	      Removes  aliases.	 This command works the	same as	unhash -a, ex-
	      cept that	the -a option removes all regular or  global  aliases,
	      or  with	-s  all	suffix aliases:	in this	case no	name arguments
	      may appear.  The options -m (remove by pattern) and  -s  without
	      -a (remove listed	suffix aliases)	behave as for unhash -a.  Note
	      that the meaning of -a is	different between unalias and unhash.

       unfunction
	      Same as unhash -f.

       unhash [	-adfms ] name ...
	      Remove the element named name from an internal hash table.   The
	      default  is remove elements from the command hash	table.	The -a
	      option causes unhash to remove regular or	global	aliases;  note
	      when  removing a global aliases that the argument	must be	quoted
	      to prevent it from being expanded	before	being  passed  to  the
	      command.	 The -s	option causes unhash to	remove suffix aliases.
	      The -f option causes unhash to remove shell functions.   The  -d
	      options  causes  unhash  to remove named directories.  If	the -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.

       unlimit [ -hs ] resource	...
	      The resource limit for each resource is set to the  hard	limit.
	      If  the  -h  flag	 is given and the shell	has appropriate	privi-
	      leges, the hard resource limit for  each	resource  is  removed.
	      The  resources  of  the shell process are	only changed if	the -s
	      flag is given.

	      The unlimit command is not made available	by  default  when  the
	      shell  starts in a mode emulating	another	shell.	It can be made
	      available	with the command `zmodload -F zsh/rlimits b:unlimit'.

       unset [ -fmv ] name ...
	      Each named parameter is unset.  Local  parameters	 remain	 local
	      even  if unset; they appear unset	within scope, but the previous
	      value will still reappear	when the scope ends.

	      Individual elements of associative array parameters may be unset
	      by  using	 subscript  syntax on name, which should be quoted (or
	      the entire command prefixed with noglob)	to  protect  the  sub-
	      script from filename generation.

	      If  the -m flag is specified the arguments are taken as patterns
	      (should be quoted) and all parameters with  matching  names  are
	      unset.  Note that	this cannot be used when unsetting associative
	      array elements, as the subscript will be treated as part of  the
	      pattern.

	      The  -v  flag  specifies that name refers	to parameters. This is
	      the default behaviour.

	      unset -f is equivalent to	unfunction.

       unsetopt	[ {+|-}options | {+|-}o	option_name ] [	name ... ]
	      Unset the	options	for the	shell.	All options  specified	either
	      with  flags or by	name are unset.	 If no arguments are supplied,
	      the names	of all options currently unset are printed.  If	the -m
	      flag  is given the arguments are taken as	patterns (which	should
	      be quoted	to preserve them from being interpreted	as  glob  pat-
	      terns),  and  all	options	with names matching these patterns are
	      unset.

       vared  See the section `Zle Builtins' in	zshzle(1).

       wait [ job ... ]
	      Wait for the specified jobs or processes.	 If job	is  not	 given
	      then  all	currently active child processes are waited for.  Each
	      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.

	      It is possible  to  wait	for  recent  processes	(specified  by
	      process ID, not by job) that were	running	in the background even
	      if the process has exited.  Typically the	 process  ID  will  be
	      recorded	by  capturing the value	of the variable	$! immediately
	      after the	process	has been started.  There is  a	limit  on  the
	      number  of process IDs remembered	by the shell; this is given by
	      the value	of the system configuration parameter CHILD_MAX.  When
	      this  limit  is  reached,	older process IDs are discarded, least
	      recently started processes first.

	      Note there is no protection against  the	process	 ID  wrapping,
	      i.e.  if	the wait is not	executed soon enough there is a	chance
	      the process waited for is	the wrong  one.	  A  conflict  implies
	      both process IDs have been generated by the shell, as other pro-
	      cesses are not recorded, and that	the user is potentially	inter-
	      ested in both, so	this problem is	intrinsic to process IDs.

       whence [	-vcwfpamsS ] [ -x num ]	name ...
	      For each name, indicate how it would be interpreted if used as a
	      command name.

	      whence is	most useful when name is only the last path  component
	      of  a  command, i.e. does	not include a `/'; in particular, pat-
	      tern matching only succeeds if just the non-directory  component
	      of the command is	passed.

	      -v     Produce a more verbose report.

	      -c     Print  the	 results  in  a	 csh-like  format.  This takes
		     precedence	over -v.

	      -w     For each name, print `name: word' where word  is  one  of
		     alias,  builtin,  command,	 function, hashed, reserved or
		     none, according  as  name	corresponds  to	 an  alias,  a
		     built-in  command,	an external command, a shell function,
		     a command defined with the	hash builtin, a	reserved word,
		     or	 is not	recognised.  This takes	precedence over	-v and
		     -c.

	      -f     Causes the	contents of a shell function to	be  displayed,
		     which  would otherwise not	happen unless the -c flag were
		     used.

	      -p     Do	a path search for name even if it  is  an  alias,  re-
		     served word, shell	function or builtin.

	      -a     Do	 a  search  for	all occurrences	of name	throughout the
		     command path.  Normally  only  the	 first	occurrence  is
		     printed.

	      -m     The  arguments  are taken as patterns (pattern characters
		     should be quoted),	and the	information is	displayed  for
		     each command matching one of these	patterns.

	      -s     If	 a  pathname contains symlinks,	print the symlink-free
		     pathname as well.

	      -S     As	-s, but	if the pathname	had to be resolved by  follow-
		     ing   multiple   symlinks,	 the  intermediate  steps  are
		     printed, too.  The	symlink	resolved at each step might be
		     anywhere in the path.

	      -x num Expand  tabs when outputting shell	functions using	the -c
		     option.  This has the same	effect as the -x option	to the
		     functions builtin.

       where [ -wpmsS ]	[ -x num ] name	...
	      Equivalent to whence -ca.

       which [ -wpamsS ] [ -x num ] name ...
	      Equivalent to whence -c.

       zcompile	[ -U ] [ -z | -k ] [ -R	| -M ] file [ name ... ]
       zcompile	-ca [ -m ] [ -R	| -M ] file [ name ... ]
       zcompile	-t file	[ name ... ]
	      This  builtin  command  can  be  used  to	 compile  functions or
	      scripts, storing the compiled form in a  file,  and  to  examine
	      files  containing	 the  compiled	form.	This allows faster au-
	      toloading	of functions and sourcing of scripts by	avoiding pars-
	      ing of the text when the files are read.

	      The first	form (without the -c, -a or -t options)	creates	a com-
	      piled file.  If only the file argument is	given, the output file
	      has the name `file.zwc' and will be placed in the	same directory
	      as the file.  The	shell will load	the compiled file  instead  of
	      the  normal  function  file when the function is autoloaded; see
	      the section `Autoloading Functions' in zshmisc(1)	for a descrip-
	      tion  of	how  autoloaded	functions are searched.	 The extension
	      .zwc stands for `zsh word	code'.

	      If there is at least one name argument, all the named files  are
	      compiled	into  the output file given as the first argument.  If
	      file does	not end	in .zwc, this extension	is  automatically  ap-
	      pended.  Files containing	multiple compiled functions are	called
	      `digest' files, and are intended to be used as elements  of  the
	      FPATH/fpath special array.

	      The  second form,	with the -c or -a options, writes the compiled
	      definitions for all the named functions into file.  For -c,  the
	      names  must  be  functions  currently  defined in	the shell, not
	      those marked for	autoloading.   Undefined  functions  that  are
	      marked for autoloading may be written by using the -a option, in
	      which case the fpath is searched and the contents	of the defini-
	      tion  files  for	those  functions,  if found, are compiled into
	      file.  If	both -c	and -a are given, names	of both	defined	 func-
	      tions and	functions marked for autoloading may be	given.	In ei-
	      ther case, the functions in files	written	with the -c or -a  op-
	      tion  will  be autoloaded	as if the KSH_AUTOLOAD option were un-
	      set.

	      The reason for handling loaded and not-yet-loaded	functions with
	      different	 options is that some definition files for autoloading
	      define multiple functions, including the function	with the  same
	      name  as the file, and, at the end, call that function.  In such
	      cases the	output of `zcompile -c'	does  not  include  the	 addi-
	      tional  functions	defined	in the file, and any other initializa-
	      tion code	in the file is lost.  Using `zcompile -a' captures all
	      this extra information.

	      If  the  -m option is combined with -c or	-a, the	names are used
	      as patterns and all functions whose names	 match	one  of	 these
	      patterns	will  be written. If no	name is	given, the definitions
	      of all functions currently defined or marked as autoloaded  will
	      be written.

	      Note the second form cannot be used for compiling	functions that
	      include redirections as  part  of	 the  definition  rather  than
	      within the body of the function; for example

		     fn1() { { ... } >~/logfile	}

	      can be compiled but

		     fn1() { ... } >~/logfile

	      cannot.	It  is	possible  to use the first form	of zcompile to
	      compile autoloadable functions that include  the	full  function
	      definition instead of just the body of the function.

	      The  third  form,	 with the -t option, examines an existing com-
	      piled file.  Without further arguments, the names	of the	origi-
	      nal files	compiled into it are listed.  The first	line of	output
	      shows the	version	of the shell which compiled the	file  and  how
	      the file will be used (i.e. by reading it	directly or by mapping
	      it into memory).	With arguments,	nothing	is output and the  re-
	      turn  status  is	set  to	zero if	definitions for	all names were
	      found in the compiled file, and non-zero if the  definition  for
	      at least one name	was not	found.

	      Other options:

	      -U     Aliases are not expanded when compiling the named files.

	      -R     When  the	compiled file is read, its contents are	copied
		     into the shell's memory, rather than  memory-mapped  (see
		     -M).   This  happens automatically	on systems that	do not
		     support memory mapping.

		     When compiling scripts instead of autoloadable functions,
		     it	 is  often desirable to	use this option; otherwise the
		     whole file, including the code to define functions	 which
		     have  already  been  defined,  will remain	mapped,	conse-
		     quently wasting memory.

	      -M     The compiled file is mapped into the shell's memory  when
		     read.  This is done in such a way that multiple instances
		     of	the shell running on the same  host  will  share  this
		     mapped file.  If neither -R nor -M	is given, the zcompile
		     builtin decides what to do	based on the size of the  com-
		     piled file.

	      -k
	      -z     These  options  are  used when the	compiled file contains
		     functions which are to be autoloaded. If -z is given, the
		     function will be autoloaded as if the KSH_AUTOLOAD	option
		     is	not set, even if it is set at the  time	 the  compiled
		     file is read, while if the	-k is given, the function will
		     be	loaded as if KSH_AUTOLOAD is set.  These options  also
		     take  precedence  over  any -k or -z options specified to
		     the autoload builtin. If  neither	of  these  options  is
		     given,  the  function will	be loaded as determined	by the
		     setting of	the KSH_AUTOLOAD option	at the time  the  com-
		     piled file	is read.

		     These  options may	also appear as many times as necessary
		     between the listed	names to specify the loading style  of
		     all following functions, up to the	next -k	or -z.

		     The created file always contains two versions of the com-
		     piled format, one for big-endian  machines	 and  one  for
		     small-endian  machines.   The  upshot of this is that the
		     compiled file is machine independent and if it is read or
		     mapped,  only  one	half of	the file is actually used (and
		     mapped).

       zformat
	      See the section `The zsh/zutil Module' in	zshmodules(1).

       zftp   See the section `The zsh/zftp Module' in zshmodules(1).

       zle    See the section `Zle Builtins' in	zshzle(1).

       zmodload	[ -dL ]	[ ... ]
       zmodload	-F [ -alLme -P param ] module [	[+-]feature ...	]
       zmodload	-e [ -A	] [ ...	]
       zmodload	[ -a [ -bcpf [ -I ] ] ]	[ -iL ]	...
       zmodload	-u [ -abcdpf [ -I ] ] [	-iL ] ...
       zmodload	-A [ -L	] [ modalias[=module] ... ]
       zmodload	-R modalias ...
	      Performs operations relating to zsh's loadable modules.  Loading
	      of  modules  while the shell is running (`dynamical loading') is
	      not available on all operating systems, or on all	 installations
	      on  a particular operating system, although the zmodload command
	      itself is	always available and can be used to manipulate modules
	      built  into  versions  of	the shell executable without dynamical
	      loading.

	      Without arguments	the names of all currently loaded binary  mod-
	      ules  are	 printed.  The -L option causes	this list to be	in the
	      form of a	series of zmodload  commands.	Forms  with  arguments
	      are:

	      zmodload [ -i ] name ...
	      zmodload -u [ -i ] name ...
		     In	 the  simplest	case,  zmodload	loads a	binary module.
		     The module	must be	in a file with a  name	consisting  of
		     the specified name	followed by a standard suffix, usually
		     `.so' (`.sl' on HPUX).  If	the module to be loaded	is al-
		     ready  loaded  the	duplicate module is ignored.  If zmod-
		     load detects an inconsistency, such as an invalid	module
		     name  or circular dependency list,	the current code block
		     is	aborted.   Hence `zmodload module 2>/dev/null' is suf-
		     ficient  to test whether a	module is available.  If it is
		     available,	the module is loaded if	necessary, while if it
		     is	 not  available, non-zero status is silently returned.
		     The option	-i is accepted for compatibility  but  has  no
		     effect.

		     The  named	 module	is searched for	in the same way	a com-
		     mand is, using $module_path instead of  $path.   However,
		     the  path	search	is performed even when the module name
		     contains a	`/', which it usually does.  There is  no  way
		     to	prevent	the path search.

		     If	 the  module  supports	features (see below), zmodload
		     tries to enable all features when loading a  module.   If
		     the  module  was successfully loaded but not all features
		     could be enabled, zmodload	returns	status 2.

		     With -u, zmodload unloads modules.	 The same name must be
		     given  that  was given when the module was	loaded,	but it
		     is	not necessary for the module to	exist in the file sys-
		     tem.  The -i option suppresses the	error if the module is
		     already unloaded (or was never loaded).

		     Each module has a boot and	a cleanup function.  The  mod-
		     ule will not be loaded if its boot	function fails.	 Simi-
		     larly a module can	only be	unloaded if its	cleanup	 func-
		     tion runs successfully.

	      zmodload -F [ -almLe -P param ] module [ [+-]feature ... ]
		     zmodload  -F  allows more selective control over the fea-
		     tures provided by modules.	 With no  options  apart  from
		     -F,  the module named module is loaded, if	it was not al-
		     ready loaded, and the list	of features is set to the  re-
		     quired  state.   If no features are specified, the	module
		     is	loaded,	if it was not already loaded, but the state of
		     features is unchanged.  Each feature may be preceded by a
		     + to turn the feature on, or - to turn it off; the	 +  is
		     assumed if	neither	character is present.  Any feature not
		     explicitly	mentioned is left in its current state;	if the
		     module was	not previously loaded this means any such fea-
		     tures will	remain disabled.  The return status is zero if
		     all  features  were  set, 1 if the	module failed to load,
		     and 2 if some features could not be set (for  example,  a
		     parameter couldn't	be added because there was a different
		     parameter of the same name) but the module	was loaded.

		     The standard features are builtins,  conditions,  parame-
		     ters  and math functions; these are indicated by the pre-
		     fix `b:', `c:' (`C:' for an infix	condition),  `p:'  and
		     `f:',  respectively, followed by the name that the	corre-
		     sponding feature would have in the	shell.	 For  example,
		     `b:strftime'  indicates  a	 builtin  named	 strftime  and
		     p:EPOCHSECONDS indicates a	parameter named	 EPOCHSECONDS.
		     The module	may provide other (`abstract') features	of its
		     own as indicated by its documentation; these have no pre-
		     fix.

		     With  -l  or  -L,	features  provided  by	the module are
		     listed.  With -l alone, a list of features	together  with
		     their  states  is	shown,	one feature per	line.  With -L
		     alone, a zmodload -F command  that	 would	cause  enabled
		     features  of  the	module to be turned on is shown.  With
		     -lL, a zmodload -F	command	that would cause all the  fea-
		     tures  to be set to their current state is	shown.	If one
		     of	these combinations is given with the option  -P	 param
		     then  the parameter param is set to an array of features,
		     either features together with their state or (if -L alone
		     is	given) enabled features.

		     With the option -L	the module name	may be omitted;	then a
		     list of all enabled features for  all  modules  providing
		     features  is printed in the form of zmodload -F commands.
		     If	-l is also given, the state of both enabled  and  dis-
		     abled features is output in that form.

		     A	set of features	may be provided	together with -l or -L
		     and a module name;	in that	case only the state  of	 those
		     features  is considered.  Each feature may	be preceded by
		     + or - but	the character has no effect.   If  no  set  of
		     features is provided, all features	are considered.

		     With  -e,	the  command  first  tests  that the module is
		     loaded; if	it is not, status 1 is returned.  If the  mod-
		     ule  is loaded, the list of features given	as an argument
		     is	examined.  Any feature given with no prefix is	simply
		     tested  to	 see  if  the  module provides it; any feature
		     given with	a prefix + or -	is tested to see  if  is  pro-
		     vided  and	 in the	given state.  If the tests on all fea-
		     tures in the list succeed,	status	0  is  returned,  else
		     status 1.

		     With  -m,	each  entry  in	 the given list	of features is
		     taken as a	pattern	to be matched against the list of fea-
		     tures  provided by	the module.  An	initial	+ or - must be
		     given explicitly.	This may not be	combined with  the  -a
		     option as autoloads must be specified explicitly.

		     With  -a,	the  given  list of features is	marked for au-
		     toload from the specified module, which may  not  yet  be
		     loaded.   An  optional  +	may  appear before the feature
		     name.  If the feature is prefixed with  -,	 any  existing
		     autoload  is  removed.  The options -l and	-L may be used
		     to	list autoloads.	 Autoloading is	specific to individual
		     features;	when  the  module is loaded only the requested
		     feature is	enabled.  Autoload requests are	 preserved  if
		     the  module  is  subsequently  unloaded until an explicit
		     `zmodload -Fa module -feature' is issued.	It is  not  an
		     error  to	request	 an autoload for a feature of a	module
		     that is already loaded.

		     When the  module  is  loaded  each	 autoload  is  checked
		     against  the features actually provided by	the module; if
		     the feature is  not  provided  the	 autoload  request  is
		     deleted.	A  warning message is output; if the module is
		     being loaded to provide a different feature, and that au-
		     toload is successful, there is no effect on the status of
		     the current command.  If the module is already loaded  at
		     the  time	when  zmodload -Fa is run, an error message is
		     printed and status	1 returned.

		     zmodload -Fa can be used with the -l, -L, -e and  -P  op-
		     tions  for	listing	and testing the	existence of autoload-
		     able features.  In	this case -l is	ignored	if -L is spec-
		     ified.  zmodload -FaL with	no module name lists autoloads
		     for all modules.

		     Note that only standard features as described  above  can
		     be	 autoloaded;  other  features require the module to be
		     loaded before enabling.

	      zmodload -d [ -L ] [ name	]
	      zmodload -d name dep ...
	      zmodload -ud name	[ dep ... ]
		     The -d option can be used to specify module dependencies.
		     The  modules named	in the second and subsequent arguments
		     will be loaded before the module named in the first argu-
		     ment.

		     With  -d and one argument,	all dependencies for that mod-
		     ule are listed.  With -d and no arguments,	all module de-
		     pendencies	 are  listed.  This listing is by default in a
		     Makefile-like format.  The	-L option changes this	format
		     to	a list of zmodload -d commands.

		     If	-d and -u are both used, dependencies are removed.  If
		     only one argument is given,  all  dependencies  for  that
		     module are	removed.

	      zmodload -ab [ -L	]
	      zmodload -ab [ -i	] name [ builtin ... ]
	      zmodload -ub [ -i	] builtin ...
		     The  -ab  option defines autoloaded builtins.  It defines
		     the specified builtins.  When any of  those  builtins  is
		     called,  the  module  specified  in the first argument is
		     loaded and	all its	features are  enabled  (for  selective
		     control  of  features  use	 `zmodload -F -a' as described
		     above).  If only the name is given, one  builtin  is  de-
		     fined,  with  the same name as the	module.	 -i suppresses
		     the error if  the	builtin	 is  already  defined  or  au-
		     toloaded,	but not	if another builtin of the same name is
		     already defined.

		     With -ab and no arguments,	all  autoloaded	 builtins  are
		     listed,  with  the	 module	 name  (if different) shown in
		     parentheses  after	 the  builtin  name.   The  -L	option
		     changes this format to a list of zmodload -a commands.

		     If	 -b  is	 used  together	with the -u option, it removes
		     builtins previously defined with -ab.  This is only  pos-
		     sible  if	the  builtin is	not yet	loaded.	 -i suppresses
		     the error if the builtin is already removed (or never ex-
		     isted).

		     Autoload  requests	 are  retained if the module is	subse-
		     quently unloaded until an explicit	`zmodload -ub builtin'
		     is	issued.

	      zmodload -ac [ -IL ]
	      zmodload -ac [ -iI ] name	[ cond ... ]
	      zmodload -uc [ -iI ] cond	...
		     The  -ac  option  is  used	to define autoloaded condition
		     codes. The	cond strings give the names of the  conditions
		     defined  by the module. The optional -I option is used to
		     define infix condition names. Without this	option	prefix
		     condition names are defined.

		     If	given no condition names, all defined names are	listed
		     (as a series of zmodload commands if  the	-L  option  is
		     given).

		     The  -uc option removes definitions for autoloaded	condi-
		     tions.

	      zmodload -ap [ -L	]
	      zmodload -ap [ -i	] name [ parameter ... ]
	      zmodload -up [ -i	] parameter ...
		     The -p option is like the -b and -c  options,  but	 makes
		     zmodload work on autoloaded parameters instead.

	      zmodload -af [ -L	]
	      zmodload -af [ -i	] name [ function ... ]
	      zmodload -uf [ -i	] function ...
		     The  -f  option  is  like the -b, -p, and -c options, but
		     makes zmodload work on autoloaded math functions instead.

	      zmodload -a [ -L ]
	      zmodload -a [ -i ] name [	builtin	... ]
	      zmodload -ua [ -i	] builtin ...
		     Equivalent	to -ab and -ub.

	      zmodload -e [ -A ] [ string ... ]
		     The -e option without arguments lists all loaded modules;
		     if	 the  -A  option  is also given, module	aliases	corre-
		     sponding to loaded	modules	are also shown.	 If  arguments
		     are  provided,  nothing  is printed; the return status is
		     set to zero if all	strings	given as arguments  are	 names
		     of	loaded modules and to one if at	least on string	is not
		     the name of a loaded module.  This	can be	used  to  test
		     for  the  availability  of	things implemented by modules.
		     In	this case, any aliases are automatically resolved  and
		     the -A flag is not	used.

	      zmodload -A [ -L ] [ modalias[=module] ... ]
		     For each argument,	if both	modalias and module are	given,
		     define modalias to	be an alias for	the module module.  If
		     the  module  modalias is ever subsequently	requested, ei-
		     ther via a	call to	zmodload or implicitly,	the shell will
		     attempt  to load module instead.  If module is not	given,
		     show the definition of modalias.	If  no	arguments  are
		     given, list all defined module aliases.  When listing, if
		     the -L flag was also given,  list	the  definition	 as  a
		     zmodload command to recreate the alias.

		     The  existence of aliases for modules is completely inde-
		     pendent of	whether	the name resolved is  actually	loaded
		     as	 a module: while the alias exists, loading and unload-
		     ing the module under any alias has	exactly	the  same  ef-
		     fect  as using the	resolved name, and does	not affect the
		     connection	between	the alias and the resolved name	 which
		     can be removed either by zmodload -R or by	redefining the
		     alias.  Chains of aliases (i.e. where the first  resolved
		     name  is  itself an alias)	are valid so long as these are
		     not circular.  As the aliases take	 the  same  format  as
		     module  names, they may include path separators:  in this
		     case, there is no requirement for any part	 of  the  path
		     named  to exist as	the alias will be resolved first.  For
		     example, `any/old/alias' is always	a valid	alias.

		     Dependencies added	to aliased modules are actually	 added
		     to	 the resolved module; these remain if the alias	is re-
		     moved.  It	is valid to create an alias whose name is  one
		     of	 the  standard	shell  modules and which resolves to a
		     different module.	However, if a module has dependencies,
		     it	 will  not  be	possible  to use the module name as an
		     alias as the module will already be marked	as a  loadable
		     module in its own right.

		     Apart from	the above, aliases can be used in the zmodload
		     command anywhere module  names  are  required.   However,
		     aliases will not be shown in lists	of loaded modules with
		     a bare `zmodload'.

	      zmodload -R modalias ...
		     For each modalias argument	that was previously defined as
		     a module alias via	zmodload -A, delete the	alias.	If any
		     was not defined, an error is caused and the remainder  of
		     the line is ignored.

	      Note  that  zsh  makes  no distinction between modules that were
	      linked into the shell and	modules	that are  loaded  dynamically.
	      In both cases this builtin command has to	be used	to make	avail-
	      able the builtins	and other things defined  by  modules  (unless
	      the  module  is  autoloaded  on these definitions). This is true
	      even for systems that don't support dynamic loading of modules.

       zparseopts
	      See the section `The zsh/zutil Module' in	zshmodules(1).

       zprof  See the section `The zsh/zprof Module' in	zshmodules(1).

       zpty   See the section `The zsh/zpty Module' in zshmodules(1).

       zregexparse
	      See the section `The zsh/zutil Module' in	zshmodules(1).

       zsocket
	      See the section `The zsh/net/socket Module' in zshmodules(1).

       zstyle See the section `The zsh/zutil Module' in	zshmodules(1).

       ztcp   See the section `The zsh/net/tcp Module' in zshmodules(1).

ZSHZLE(1)		    General Commands Manual		     ZSHZLE(1)

NAME
       zshzle -	zsh command line editor

DESCRIPTION
       If the ZLE option is set	(which it is by	default	in interactive shells)
       and  the	 shell	input is attached to the terminal, the user is able to
       edit command lines.

       There are two display modes.  The first,	multiline  mode,  is  the  de-
       fault.	It only	works if the TERM parameter is set to a	valid terminal
       type that can move the cursor up.  The second,  single  line  mode,  is
       used if TERM is invalid or incapable of moving the cursor up, or	if the
       SINGLE_LINE_ZLE option is set.  This mode is similar to ksh,  and  uses
       no termcap sequences.  If TERM is "emacs", the ZLE option will be unset
       by default.

       The parameters BAUD, COLUMNS, and LINES are also	used by	the line  edi-
       tor. See	Parameters Used	By The Shell in	zshparam(1).

       The  parameter zle_highlight is also used by the	line editor; see Char-
       acter Highlighting below.  Highlighting of special characters  and  the
       region between the cursor and the mark (as set with set-mark-command in
       Emacs mode, or by visual-mode in	Vi mode) is enabled by	default;  con-
       sult this reference for more information.  Irascible conservatives will
       wish to know that all highlighting may be  disabled  by	the  following
       setting:

	      zle_highlight=(none)

       In  many	places,	references are made to the numeric argument.  This can
       by default be entered in	emacs mode by holding the alt key and typing a
       number, or pressing escape before each digit, and in vi command mode by
       typing the number before	entering a command.  Generally the numeric ar-
       gument  causes  the  next  command entered to be	repeated the specified
       number of times,	unless otherwise noted below. See also	the  Arguments
       subsection of the Widgets section for some other	ways the numeric argu-
       ment can	be modified. The  default  bindings  mentioned	here  use  the
       digit-argument widget.

KEYMAPS
       A  keymap  in  ZLE contains a set of bindings between key sequences and
       ZLE commands.  The empty	key sequence cannot be bound.

       There can be any	number of keymaps at any time, and each	keymap has one
       or  more	names.	If all of a keymap's names are deleted,	it disappears.
       bindkey can be used to manipulate keymap	names.

       Initially, there	are eight keymaps:

       emacs  EMACS emulation
       viins  vi emulation - insert mode
       vicmd  vi emulation - command mode
       viopp  vi emulation - operator pending
       visual vi emulation - selection active
       isearch
	      incremental search mode
       command
	      read a command name
       .safe  fallback keymap

       The `.safe' keymap is special.  It can never be altered,	and  the  name
       can  never be removed.  However,	it can be linked to other names, which
       can be removed.	In the future other  special  keymaps  may  be	added;
       users  should  avoid  using  names  beginning  with  `.'	 for their own
       keymaps.

       In addition to these names, either `emacs' or `viins' is	also linked to
       the  name `main'.  If one of the	VISUAL or EDITOR environment variables
       contain the string `vi' when the	shell starts up	then it	will  be  `vi-
       ins',  otherwise	 it will be `emacs'.  bindkey's	-e and -v options pro-
       vide a convenient way to	override this default choice.

       When the	editor starts up, it will select the `main' keymap.   If  that
       keymap doesn't exist, it	will use `.safe' instead.

       In  the `.safe' keymap, each single key is bound	to self-insert,	except
       for ^J (line feed) and ^M (return)  which  are  bound  to  accept-line.
       This is deliberately not	pleasant to use; if you	are using it, it means
       you deleted the main keymap, and	you should put it back.

   Reading Commands
       When ZLE	is reading a command from the terminal,	it may read a sequence
       that  is	 bound	to some	command	and is also a prefix of	a longer bound
       string.	In this	case ZLE will wait a certain time to see if more char-
       acters are typed, and if	not (or	they don't match any longer string) it
       will execute the	binding.  This timeout is defined  by  the  KEYTIMEOUT
       parameter;  its	default	is 0.4 sec.  There is no timeout if the	prefix
       string is not itself bound to a command.

       The key timeout is also applied when ZLE	is reading the	bytes  from  a
       multibyte  character  string when it is in the appropriate mode.	 (This
       requires	that the shell was compiled with multibyte mode	enabled; typi-
       cally  also the locale has characters with the UTF-8 encoding, although
       any multibyte encoding known to the operating system is supported.)  If
       the  second or a	subsequent byte	is not read within the timeout period,
       the shell acts as if ? were typed and resets the	input state.

       As well as ZLE commands,	key sequences can be bound to  other  strings,
       by  using  `bindkey -s'.	 When such a sequence is read, the replacement
       string is pushed	back as	input, and the command reading process	starts
       again  using  these fake	keystrokes.  This input	can itself invoke fur-
       ther replacement	strings, but in	order to detect	loops the process will
       be stopped if there are twenty such replacements	without	a real command
       being read.

       A key sequence typed by the user	can be turned into a command name  for
       use  in user-defined widgets with the read-command widget, described in
       the subsection `Miscellaneous' of the section `Standard Widgets'	below.

   Local Keymaps
       While for normal	editing	a single keymap	is used	exclusively,  in  many
       modes  a	 local keymap allows for some keys to be customised. For exam-
       ple, in an incremental search mode, a binding  in  the  isearch	keymap
       will  override  a  binding in the main keymap but all keys that are not
       overridden can still be used.

       If a key	sequence is defined in a local keymap, it will hide a key  se-
       quence in the global keymap that	is a prefix of that sequence. An exam-
       ple of this occurs with the binding of iw in viopp as  this  hides  the
       binding	of i in	vicmd. However,	a longer sequence in the global	keymap
       that shares the same prefix can still apply so for example the  binding
       of ^Xa in the global keymap will	be unaffected by the binding of	^Xb in
       the local keymap.

ZLE BUILTINS
       The ZLE module contains three related  builtin  commands.  The  bindkey
       command manipulates keymaps and key bindings; the vared command invokes
       ZLE on the value	of a shell parameter; and the zle command  manipulates
       editing	widgets	 and  allows  command line access to ZLE commands from
       within shell functions.

       bindkey [ options ] -l [	-L ] [ keymap ... ]
       bindkey [ options ] -d
       bindkey [ options ] -D keymap ...
       bindkey [ options ] -A old-keymap new-keymap
       bindkey [ options ] -N new-keymap [ old-keymap ]
       bindkey [ options ] -m
       bindkey [ options ] -r in-string	...
       bindkey [ options ] -s in-string	out-string ...
       bindkey [ options ] in-string command ...
       bindkey [ options ] [ in-string ]
	      bindkey's	options	can be divided into three  categories:	keymap
	      selection	for the	current	command, operation selection, and oth-
	      ers.  The	keymap selection options are:

	      -e     Selects keymap `emacs' for	any operations by the  current
		     command,  and  also links `emacs' to `main' so that it is
		     selected by default the next time the editor starts.

	      -v     Selects keymap `viins' for	any operations by the  current
		     command,  and  also links `viins' to `main' so that it is
		     selected by default the next time the editor starts.

	      -a     Selects keymap `vicmd' for	any operations by the  current
		     command.

	      -M keymap
		     The  keymap  specifies a keymap name that is selected for
		     any operations by the current command.

	      If a keymap selection is required	and none of the	options	 above
	      are  used,  the  `main'  keymap is used.	Some operations	do not
	      permit a keymap to be selected, namely:

	      -l     List all existing keymap  names;  if  any	arguments  are
		     given, list just those keymaps.

		     If	 the -L	option is also used, list in the form of bind-
		     key commands to create or link the	keymaps.  `bindkey -lL
		     main' shows which keymap is linked	to `main', if any, and
		     hence if the standard emacs or vi emulation is in effect.
		     This  option  does	 not  show the .safe keymap because it
		     cannot be created in that fashion;	 however,  neither  is
		     `bindkey  -lL .safe' reported as an error,	it simply out-
		     puts nothing.

	      -d     Delete all	existing keymaps  and  reset  to  the  default
		     state.

	      -D keymap	...
		     Delete the	named keymaps.

	      -A old-keymap new-keymap
		     Make the new-keymap name an alias for old-keymap, so that
		     both names	refer to the  same  keymap.   The  names  have
		     equal  standing; if either	is deleted, the	other remains.
		     If	there is already a keymap with the new-keymap name, it
		     is	deleted.

	      -N new-keymap [ old-keymap ]
		     Create  a	new keymap, named new-keymap.  If a keymap al-
		     ready has that name, it is	 deleted.   If	an  old-keymap
		     name  is given, the new keymap is initialized to be a du-
		     plicate of	it, otherwise the new keymap will be empty.

	      To use a newly created keymap, it	 should	 be  linked  to	 main.
	      Hence  the  sequence  of commands	to create and use a new	keymap
	      `mymap' initialized from the emacs  keymap  (which  remains  un-
	      changed) is:

		     bindkey -N	mymap emacs
		     bindkey -A	mymap main

	      Note  that  while	`bindkey -A newmap main' will work when	newmap
	      is emacs or viins, it will not work for vicmd, as	switching from
	      vi insert	to command mode	becomes	impossible.

	      The  following  operations act on	the `main' keymap if no	keymap
	      selection	option was given:

	      -m     Add the built-in set of meta-key bindings to the selected
		     keymap.   Only keys that are unbound or bound to self-in-
		     sert are affected.

	      -r in-string ...
		     Unbind the	specified in-strings in	the  selected  keymap.
		     This  is exactly equivalent to binding the	strings	to un-
		     defined-key.

		     When -R is	also used, interpret the in-strings as ranges.

		     When -p is	also used, the	in-strings  specify  prefixes.
		     Any binding that has the given in-string as a prefix, not
		     including the binding for the in-string itself,  if  any,
		     will be removed.  For example,

			    bindkey -rpM viins '^['

		     will  remove  all bindings	in the vi-insert keymap	begin-
		     ning with an escape character (probably cursor keys), but
		     leave the binding for the escape character	itself (proba-
		     bly vi-cmd-mode).	This is	incompatible with  the	option
		     -R.

	      -s in-string out-string ...
		     Bind  each	 in-string to each out-string.	When in-string
		     is	typed, out-string will be pushed back and  treated  as
		     input  to	the line editor.  When -R is also used,	inter-
		     pret the in-strings as ranges.

		     Note that both in-string and out-string  are  subject  to
		     the same form of interpretation, as described below.

	      in-string	command	...
		     Bind  each	 in-string  to each command.  When -R is used,
		     interpret the in-strings as ranges.

	      [	in-string ]
		     List key bindings.	 If an	in-string  is  specified,  the
		     binding  of  that	string	in the selected	keymap is dis-
		     played.  Otherwise, all  key  bindings  in	 the  selected
		     keymap  are  displayed.  (As a special case, if the -e or
		     -v	option is used alone, the keymap is  not  displayed  -
		     the  implicit  linking  of	keymaps	is the only thing that
		     happens.)

		     When the  option  -p  is  used,  the  in-string  must  be
		     present.	The  listing shows all bindings	which have the
		     given key sequence	as a prefix, not including  any	 bind-
		     ings for the key sequence itself.

		     When  the	-L  option is used, the	list is	in the form of
		     bindkey commands to create	the key	bindings.

	      When the -R option is used as noted above, a  valid  range  con-
	      sists of two characters, with an optional	`-' between them.  All
	      characters between the two specified, inclusive,	are  bound  as
	      specified.

	      For  either  in-string  or  out-string, the following escape se-
	      quences are recognised:

	      \a     bell character
	      \b     backspace
	      \e, \E escape
	      \f     form feed
	      \n     linefeed (newline)
	      \r     carriage return
	      \t     horizontal	tab
	      \v     vertical tab
	      \NNN   character code in octal
	      \xNN   character code in hexadecimal
	      \uNNNN unicode character code in hexadecimal
	      \UNNNNNNNN
		     unicode character code in hexadecimal
	      \M[-]X character with meta bit set
	      \C[-]X control character
	      ^X     control character

	      In all other cases, `\' escapes the following character.	Delete
	      is  written  as  `^?'.   Note that `\M^?'	and `^\M?' are not the
	      same, and	that (unlike emacs), the bindings `\M-X' and `\eX' are
	      entirely	distinct,  although  they  are initialized to the same
	      bindings by `bindkey -m'.

       vared [ -Aache ]	[ -p prompt ] [	-r rprompt ]
	     [ -M main-keymap ]	[ -m vicmd-keymap ]
	     [ -i init-widget ]	[ -f finish-widget ]
	     [ -t tty ]	name
	      The value	of the parameter name is loaded	into the edit  buffer,
	      and  the line editor is invoked.	When the editor	exits, name is
	      set to the string	value returned by the  editor.	 When  the  -c
	      flag  is	given,	the parameter is created if it doesn't already
	      exist.  The -a flag may be given with -c to create an array  pa-
	      rameter,	or the -A flag to create an associative	array.	If the
	      type of an existing parameter does not match the type to be cre-
	      ated, the	parameter is unset and recreated.

	      If an array or array slice is being edited, separator characters
	      as defined in $IFS will be shown quoted  with  a	backslash,  as
	      will  backslashes	 themselves.  Conversely, when the edited text
	      is split into an array, a	backslash quotes an  immediately  fol-
	      lowing  separator	 character or backslash; no other special han-
	      dling of backslashes, or any handling of quotes, is performed.

	      Individual elements of existing array or associative  array  pa-
	      rameters	may  be	edited by using	subscript syntax on name.  New
	      elements are created automatically, even without -c.

	      If the -p	flag is	given, the following string will be  taken  as
	      the prompt to display at the left.  If the -r flag is given, the
	      following	string gives the prompt	to display at the  right.   If
	      the  -h flag is specified, the history can be accessed from ZLE.
	      If the -e	flag is	given, typing ^D (Control-D) on	an empty  line
	      causes vared to exit immediately with a non-zero return value.

	      The  -M  option gives a keymap to	link to	the main keymap	during
	      editing, and the -m option gives a keymap	to link	to  the	 vicmd
	      keymap during editing.  For vi-style editing, this allows	a pair
	      of keymaps to override viins and vicmd.  For  emacs-style	 edit-
	      ing,  only  -M is	normally needed	but the	-m option may still be
	      used.  On	exit, the previous keymaps will	be restored.

	      Vared calls  the	usual  `zle-line-init'	and  `zle-line-finish'
	      hooks before and after it	takes control. Using the -i and	-f op-
	      tions, it	is possible to replace these with  other  custom  wid-
	      gets.

	      If `-t tty' is given, tty	is the name of a terminal device to be
	      used instead of the default /dev/tty.  If	tty does not refer  to
	      a	terminal an error is reported.

       zle
       zle -l [	-L | -a	] [ string ... ]
       zle -D widget ...
       zle -A old-widget new-widget
       zle -N widget [ function	]
       zle -f flag [ flag... ]
       zle -C widget completion-widget function
       zle -R [	-c ] [ display-string ]	[ string ... ]
       zle -M string
       zle -U string
       zle -K keymap
       zle -F [	-L | -w	] [ fd [ handler ] ]
       zle -I
       zle -T [	tc function | -r tc | -L ]
       zle widget [ -n num ] [ -Nw ] [ -K keymap ] args	...
	      The  zle builtin performs	a number of different actions concern-
	      ing ZLE.

	      With no options and no arguments,	only the return	status will be
	      set.  It is zero if ZLE is currently active and widgets could be
	      invoked using this builtin command and non-zero otherwise.  Note
	      that  even  if non-zero status is	returned, zle may still	be ac-
	      tive as part of the completion system; this does not  allow  di-
	      rect calls to ZLE	widgets.

	      Otherwise, which operation it performs depends on	its options:

	      -l [ -L |	-a ] [ string ]
		     List all existing user-defined widgets.  If the -L	option
		     is	used, list in the form of zle commands to  create  the
		     widgets.

		     When  combined  with  the -a option, all widget names are
		     listed, including the builtin ones. In this case  the  -L
		     option is ignored.

		     If	 at least one string is	given, and -a is present or -L
		     is	not used, nothing will be printed.  The	return	status
		     will be zero if all strings are names of existing widgets
		     and non-zero if at	least one string is not	a  name	 of  a
		     defined  widget.  If -a is	also present, all widget names
		     are used for the comparison  including  builtin  widgets,
		     else only user-defined widgets are	used.

		     If	 at  least  one	string is present and the -L option is
		     used, user-defined	widgets	matching any string are	listed
		     in	the form of zle	commands to create the widgets.

	      -D widget	...
		     Delete the	named widgets.

	      -A old-widget new-widget
		     Make the new-widget name an alias for old-widget, so that
		     both names	refer to the  same  widget.   The  names  have
		     equal  standing; if either	is deleted, the	other remains.
		     If	there is already a widget with the new-widget name, it
		     is	deleted.

	      -N widget	[ function ]
		     Create a user-defined widget.  If there is	already	a wid-
		     get with the specified name, it is	overwritten.  When the
		     new  widget is invoked from within	the editor, the	speci-
		     fied shell	function is called.  If	no  function  name  is
		     specified,	 it  defaults  to the same name	as the widget.
		     For further information, see the section `Widgets'	below.

	      -f flag [	flag...	]
		     Set various flags on the running widget.  Possible	values
		     for flag are:

		     yank  for indicating that the widget has yanked text into
		     the buffer.  If the widget	is wrapping an existing	inter-
		     nal widget, no further action is necessary, but if	it has
		     inserted the text manually, then it should	also take care
		     to	 set  YANK_START  and  YANK_END	correctly.  yankbefore
		     does the same but is used when the	 yanked	 text  appears
		     after the cursor.

		     kill  for	indicating  that text has been killed into the
		     cutbuffer.	 When repeatedly invoking a kill widget,  text
		     is	appended to the	cutbuffer instead of replacing it, but
		     when wrapping such	widgets, it is necessary to call  `zle
		     -f	kill' to retain	this effect.

		     vichange  for  indicating that the	widget represents a vi
		     change that can be	 repeated  as  a  whole	 with  `vi-re-
		     peat-change'.  The	 flag should be	set early in the func-
		     tion before inspecting the	value of NUMERIC  or  invoking
		     other  widgets.  This  has	no effect for a	widget invoked
		     from insert mode. If insert mode is active	when the  wid-
		     get  finishes, the	change extends until next returning to
		     command mode.

	      -C widget	completion-widget function
		     Create a user-defined completion widget named widget. The
		     completion	 widget	 will behave like the built-in comple-
		     tion-widget whose name is given as	completion-widget.  To
		     generate  the  completions,  the  shell function function
		     will be called.  For further  information,	 see  zshcomp-
		     wid(1).

	      -R [ -c ]	[ display-string ] [ string ...	]
		     Redisplay	the  command  line;  this is to	be called from
		     within a user-defined widget to allow changes  to	become
		     visible.	If  a  display-string  is given	and not	empty,
		     this is shown in the status line (immediately  below  the
		     line being	edited).

		     If	 the  optional strings are given they are listed below
		     the prompt	in  the	 same  way  as	completion  lists  are
		     printed.  If  no  strings	are given but the -c option is
		     used such a list is cleared.

		     Note that this option is only useful for widgets that  do
		     not  exit	immediately after using	it because the strings
		     displayed will be erased immediately  after  return  from
		     the widget.

		     This  command  can	 safely	be called outside user defined
		     widgets; if zle is	active,	the display will be refreshed,
		     while  if	zle  is	not active, the	command	has no effect.
		     In	this case there	will usually be	no other arguments.

		     The status	is zero	if zle was active, else	one.

	      -M string
		     As	with the -R option, the	string will be displayed below
		     the  command  line; unlike	the -R option, the string will
		     not be put	into the  status  line	but  will  instead  be
		     printed  normally	below the prompt.  This	means that the
		     string will still be displayed after the  widget  returns
		     (until it is overwritten by subsequent commands).

	      -U string
		     This  pushes  the characters in the string	onto the input
		     stack of ZLE.  After the widget currently	executed  fin-
		     ishes  ZLE	will behave as if the characters in the	string
		     were typed	by the user.

		     As	ZLE uses a stack, if this option  is  used  repeatedly
		     the  last	string pushed onto the stack will be processed
		     first.  However, the characters in	each  string  will  be
		     processed	in  the	 order	in  which  they	 appear	in the
		     string.

	      -K keymap
		     Selects the keymap	named keymap.  An error	 message  will
		     be	displayed if there is no such keymap.

		     This  keymap selection affects the	interpretation of fol-
		     lowing keystrokes within this  invocation	of  ZLE.   Any
		     following	invocation  (e.g., the next command line) will
		     start as usual with the `main' keymap selected.

	      -F [ -L |	-w ] [ fd [ handler ] ]
		     Only available if your system supports one	of the	`poll'
		     or	`select' system	calls; most modern systems do.

		     Installs handler (the name	of a shell function) to	handle
		     input from	file descriptor	fd.  Installing	a handler  for
		     an	 fd  which is already handled causes the existing han-
		     dler to be	replaced.  Any number of handlers for any num-
		     ber  of readable file descriptors may be installed.  Note
		     that zle makes no attempt to check	whether	this fd	is ac-
		     tually  readable  when  installing	the handler.  The user
		     must make their own arrangements for  handling  the  file
		     descriptor	when zle is not	active.

		     When zle is attempting to read data, it will examine both
		     the terminal and the list of handled fd's.	 If  data  be-
		     comes  available  on a handled fd,	zle calls handler with
		     the fd which is ready for reading as the first  argument.
		     Under normal circumstances	this is	the only argument, but
		     if	an error was detected, a second	argument provides  de-
		     tails:  `hup'  for	 a  disconnect,	`nval' for a closed or
		     otherwise invalid descriptor, or `err' for	any other con-
		     dition.   Systems	that  support only the `select'	system
		     call always use `err'.

		     If	the option -w is also given, the handler is instead  a
		     line  editor widget, typically a shell function made into
		     a widget using `zle -N'.  In that case  handler  can  use
		     all  the  facilities of zle to update the current editing
		     line.  Note, however, that	as handling fd takes place  at
		     a low level changes to the	display	will not automatically
		     appear; the widget	should call `zle -R' to	 force	redis-
		     play.  As of this writing,	widget handlers	only support a
		     single argument and thus are never	passed	a  string  for
		     error  state, so widgets must be prepared to test the de-
		     scriptor themselves.

		     If	either type of handler produces	output to  the	termi-
		     nal, it should call `zle -I' before doing so (see below).
		     Handlers should not attempt to read from the terminal.

		     If	no handler is given, but an fd is present, any handler
		     for  that fd is removed.  If there	is none, an error mes-
		     sage is printed and status	1 is returned.

		     If	no arguments are given,	or the -L option is  supplied,
		     a	list  of  handlers  is	printed	in a form which	can be
		     stored for	later execution.

		     An	fd (but	not a handler) may optionally  be  given  with
		     the  -L  option; in this case, the	function will list the
		     handler if	any, else silently return status 1.

		     Note that this feature should be used with	care.	Activ-
		     ity  on one of the	fd's which is not properly handled can
		     cause the terminal	to become unusable.   Removing	an  fd
		     handler from within a signal trap may cause unpredictable
		     behavior.

		     Here is a simple example of using this feature.   A  con-
		     nection  to  a  remote TCP	port is	created	using the ztcp
		     command; see the description of the zsh/net/tcp module in
		     zshmodules(1).   Then a handler is	installed which	simply
		     prints out	any data which	arrives	 on  this  connection.
		     Note that `select'	will indicate that the file descriptor
		     needs handling if the remote side has closed the  connec-
		     tion; we handle that by testing for a failed read.

			    if ztcp pwspc 2811;	then
			      tcpfd=$REPLY
			      handler()	{
				zle -I
				local line
				if ! read -r line <&$1;	then
				  # select marks this fd if we reach EOF,
				  # so handle this specially.
				  print	"[Read on fd $1	failed,	removing.]" >&2
				  zle -F $1
				  return 1
				fi
				print -r - $line
			      }
			      zle -F $tcpfd handler
			    fi

	      -I     Unusually,	 this  option  is most useful outside ordinary
		     widget functions, though it may be	used within if	normal
		     output  to	 the terminal is required.  It invalidates the
		     current zle display in preparation	for output;  typically
		     this  will	 be from a trap	function.  It has no effect if
		     zle is not	active.	 When a	trap exits, the	 shell	checks
		     to	 see if	the display needs restoring, hence the follow-
		     ing will print output in such a way as not	to disturb the
		     line being	edited:

			    TRAPUSR1() {
			      #	Invalidate zle display
			      [[ -o zle	]] && zle -I
			      #	Show output
			      print Hello
			    }

		     In	 general,  the	trap function may need to test whether
		     zle is active before using	this method (as	shown  in  the
		     example),	since  the  zsh/zle  module  may  not  even be
		     loaded; if	it is not, the command can be skipped.

		     It	is possible to call `zle -I' several times before con-
		     trol  is returned to the editor; the display will only be
		     invalidated the first time	to minimise disruption.

		     Note that there are normally better ways of  manipulating
		     the  display  from	 within	zle widgets; see, for example,
		     `zle -R' above.

		     The returned status is zero if zle	was invalidated,  even
		     though  this may have been	by a previous call to `zle -I'
		     or	by a system notification.  To test if a	zle widget may
		     be	 called	 at  this point, execute zle with no arguments
		     and examine the return status.

	      -T     This is used to add, list or remove internal  transforma-
		     tions on the processing performed by the line editor.  It
		     is	typically used only for	debugging or  testing  and  is
		     therefore of little interest to the general user.

		     `zle  -T  transformation  func'  specifies	that the given
		     transformation (see below)	is effected by shell  function
		     func.

		     `zle -Tr transformation' removes the given	transformation
		     if	it was present (it is not an error if none was).

		     `zle -TL' can be used to list  all	 transformations  cur-
		     rently in operation.

		     Currently	the  only  transformation is tc.  This is used
		     instead of	outputting  termcap  codes  to	the  terminal.
		     When  the	transformation is in operation the shell func-
		     tion is passed the	termcap	code that would	be  output  as
		     its  first	 argument; if the operation required a numeric
		     argument, that is passed as a second argument.  The func-
		     tion  should  set	the shell variable REPLY to the	trans-
		     formed termcap code.  Typically this is used  to  produce
		     some  simply  formatted  version of the code and optional
		     argument for debugging or testing.	 Note that this	trans-
		     formation is not applied to other non-printing characters
		     such as carriage returns and newlines.

	      widget [ -n num ]	[ -Nw ]	[ -K keymap ] args ...
		     Invoke the	specified widget.  This	can only be done  when
		     ZLE  is  active;  normally	this will be within a user-de-
		     fined widget.

		     With the options -n and -N, the current numeric  argument
		     will be saved and then restored after the call to widget;
		     `-n num' sets the numeric argument	 temporarily  to  num,
		     while  `-N' sets it to the	default, i.e. as if there were
		     none.

		     With the option -K, keymap	will be	used  as  the  current
		     keymap  during the	execution of the widget.  The previous
		     keymap will be restored when the widget exits.

		     Normally, calling a widget	in this	way does not  set  the
		     special  parameter	WIDGET and related parameters, so that
		     the environment appears as	if the top-level widget	called
		     by	 the user were still active.  With the option -w, WID-
		     GET and related parameters	are set	to reflect the	widget
		     being executed by the zle call.

		     Any  further arguments will be passed to the widget; note
		     that as standard argument handling	is performed, any gen-
		     eral  argument list should	be preceded by --.  If it is a
		     shell function, these are passed down as  positional  pa-
		     rameters;	for  builtin widgets it	is up to the widget in
		     question what it does with	them.  Currently arguments are
		     only handled by the incremental-search commands, the his-
		     tory-search-forward and -backward and  the	 corresponding
		     functions prefixed	by vi-,	and by universal-argument.  No
		     error is flagged if the command does not  use  the	 argu-
		     ments, or only uses some of them.

		     The  return status	reflects the success or	failure	of the
		     operation carried out by  the  widget,  or	 if  it	 is  a
		     user-defined  widget the return status of the shell func-
		     tion.

		     A non-zero	return status causes the shell	to  beep  when
		     the  widget  exits,  unless the BEEP options was unset or
		     the widget	was called via the zle	command.   Thus	 if  a
		     user defined widget requires an immediate beep, it	should
		     call the beep widget directly.

WIDGETS
       All actions in the editor are performed by `widgets'.  A	 widget's  job
       is  simply to perform some small	action.	 The ZLE commands that key se-
       quences in keymaps are bound to are in fact widgets.   Widgets  can  be
       user-defined or built in.

       The  standard widgets built into	ZLE are	listed in Standard Widgets be-
       low.  Other built-in widgets can	be defined by other modules (see  zsh-
       modules(1)).   Each built-in widget has two names: its normal canonical
       name, and the same name preceded	by a `.'.  The `.' name	is special: it
       can't  be  rebound to a different widget.  This makes the widget	avail-
       able even when its usual	name has been redefined.

       User-defined widgets are	defined	using `zle  -N',  and  implemented  as
       shell  functions.  When the widget is executed, the corresponding shell
       function	is executed, and can perform editing (or other)	 actions.   It
       is recommended that user-defined	widgets	should not have	names starting
       with `.'.

USER-DEFINED WIDGETS
       User-defined widgets, being implemented as shell	functions, can execute
       any  normal  shell  command.   They can also run	other widgets (whether
       built-in	or user-defined) using the zle builtin command.	 The  standard
       input of	the function is	closed to prevent external commands from unin-
       tentionally blocking ZLE	by reading from	the terminal, but read	-k  or
       read  -q	can be used to read characters.	 Finally, they can examine and
       edit the	ZLE buffer being edited	by reading and setting the special pa-
       rameters	described below.

       These  special parameters are always available in widget	functions, but
       are not in any way special outside ZLE.	If they	have some normal value
       outside	ZLE,  that  value is temporarily inaccessible, but will	return
       when the	widget function	exits.	These special parameters in fact  have
       local scope, like parameters created in a function using	local.

       Inside  completion  widgets and traps called while ZLE is active, these
       parameters are available	read-only.

       Note that the parameters	appear as local	to any	ZLE  widget  in	 which
       they  appear.  Hence if it is desired to	override them this needs to be
       done within a nested function:

	      widget-function()	{
		# $WIDGET here refers to the special variable
		# that is local	inside widget-function
		() {
		   # This anonymous nested function allows WIDGET
		   # to	be used	as a local variable.  The -h
		   # removes the special status	of the variable.
		   local -h WIDGET
		}
	      }

       BUFFER (scalar)
	      The entire contents of the edit buffer.  If it  is  written  to,
	      the  cursor remains at the same offset, unless that would	put it
	      outside the buffer.

       BUFFERLINES (integer)
	      The number of screen lines needed	for the	edit buffer  currently
	      displayed	 on  screen (i.e. without any changes to the preceding
	      parameters done after the	last redisplay); read-only.

       CONTEXT (scalar)
	      The context in which zle was called to read a  line;  read-only.
	      One of the values:

	      start  The start of a command line (at prompt PS1).

	      cont   A continuation to a command line (at prompt PS2).

	      select In	a select loop (at prompt PS3).

	      vared  Editing a variable	in vared.

       CURSOR (integer)
	      The  offset  of  the cursor, within the edit buffer.  This is in
	      the  range  0  to	 $#BUFFER,  and	 is  by	 definition  equal  to
	      $#LBUFFER.   Attempts to move the	cursor outside the buffer will
	      result in	the cursor being moved to the appropriate end  of  the
	      buffer.

       CUTBUFFER (scalar)
	      The  last	item cut using one of the `kill-' commands; the	string
	      which the	next yank would	insert in the line.  Later entries  in
	      the  kill	ring are in the	array killring.	 Note that the command
	      `zle copy-region-as-kill string' can be used to set the text  of
	      the  cut buffer from a shell function and	cycle the kill ring in
	      the same way as interactively killing text.

       HISTNO (integer)
	      The current history number.  Setting this	has the	same effect as
	      moving  up  or  down in the history to the corresponding history
	      line.  An	attempt	to set it is ignored if	the line is not	stored
	      in  the  history.	  Note	this  is not the same as the parameter
	      HISTCMD, which always gives the number of	the history line being
	      added  to	 the  main shell's history.  HISTNO refers to the line
	      being retrieved within zle.

       ISEARCHMATCH_ACTIVE (integer)
       ISEARCHMATCH_START (integer)
       ISEARCHMATCH_END	(integer)
	      ISEARCHMATCH_ACTIVE indicates whether a part of  the  BUFFER  is
	      currently	 matched  by  an  incremental search pattern. ISEARCH-
	      MATCH_START  and	ISEARCHMATCH_END  give	the  location  of  the
	      matched  part and	are in the same	units as CURSOR. They are only
	      valid for	reading	when ISEARCHMATCH_ACTIVE is non-zero.

	      All parameters are read-only.

       KEYMAP (scalar)
	      The name of the currently	selected keymap; read-only.

       KEYS (scalar)
	      The keys typed to	invoke	this  widget,  as  a  literal  string;
	      read-only.

       killring	(array)
	      The  array  of  previously  killed items,	with the most recently
	      killed first.  This gives	the items that would be	retrieved by a
	      yank-pop	in  the	 same order.  Note, however, that the most re-
	      cently killed item is in $CUTBUFFER; $killring shows  the	 array
	      of previous entries.

	      The  default size	for the	kill ring is eight, however the	length
	      may be changed by	normal array operations.  Any empty string  in
	      the kill ring is ignored by the yank-pop command,	hence the size
	      of the array effectively sets the	maximum	 length	 of  the  kill
	      ring,  while  the	 number	 of non-zero strings gives the current
	      length, both as seen by the user at the command line.

       LASTABORTEDSEARCH (scalar)
	      The last search string used by an	interactive  search  that  was
	      aborted by the user (status 3 returned by	the search widget).

       LASTSEARCH (scalar)
	      The last search string used by an	interactive search; read-only.
	      This is set even if the search failed (status 0, 1 or 2 returned
	      by the search widget), but not if	it was aborted by the user.

       LASTWIDGET (scalar)
	      The name of the last widget that was executed; read-only.

       LBUFFER (scalar)
	      The part of the buffer that lies to the left of the cursor posi-
	      tion.  If	it is assigned to, only	that part of the buffer	is re-
	      placed,  and the cursor remains between the new $LBUFFER and the
	      old $RBUFFER.

       MARK (integer)
	      Like CURSOR, but for the mark. With vi-mode operators that  wait
	      for  a movement command to select	a region of text, setting MARK
	      allows the selection to extend in	both directions	from the  ini-
	      tial cursor position.

       NUMERIC (integer)
	      The numeric argument. If no numeric argument was given, this pa-
	      rameter is unset.	When this is set  inside  a  widget  function,
	      builtin widgets called with the zle builtin command will use the
	      value assigned. If it is unset inside a widget function, builtin
	      widgets called behave as if no numeric argument was given.

       PENDING (integer)
	      The  number of bytes pending for input, i.e. the number of bytes
	      which have already been typed and	can immediately	 be  read.  On
	      systems  where  the  shell  is not able to get this information,
	      this parameter will always have a	value of zero.	Read-only.

       PREBUFFER (scalar)
	      In a multi-line input at the secondary  prompt,  this  read-only
	      parameter	 contains the contents of the lines before the one the
	      cursor is	currently in.

       PREDISPLAY (scalar)
	      Text to be displayed before the start of the editable text  buf-
	      fer.   This  does	 not  have to be a complete line; to display a
	      complete line, a newline must be appended	explicitly.  The  text
	      is  reset	 on each new invocation	(but not recursive invocation)
	      of zle.

       POSTDISPLAY (scalar)
	      Text to be displayed after the end of the	editable text  buffer.
	      This  does not have to be	a complete line; to display a complete
	      line, a newline must be prepended	explicitly.  The text is reset
	      on each new invocation (but not recursive	invocation) of zle.

       RBUFFER (scalar)
	      The  part	of the buffer that lies	to the right of	the cursor po-
	      sition.  If it is	assigned to, only that part of the  buffer  is
	      replaced,	 and  the  cursor remains between the old $LBUFFER and
	      the new $RBUFFER.

       REGION_ACTIVE (integer)
	      Indicates	if the region is currently active.  It can be assigned
	      0	 or  1	to  deactivate and activate the	region respectively. A
	      value of 2 activates the region in line-wise mode	with the high-
	      lighted text extending for whole lines only; see Character High-
	      lighting below.

       region_highlight	(array)
	      Each element of this array may be	set to a string	that describes
	      highlighting  for	 an  arbitrary region of the command line that
	      will take	effect the next	time the command line is  redisplayed.
	      Highlighting  of	the  non-editable parts	of the command line in
	      PREDISPLAY and POSTDISPLAY are possible, but  note  that	the  P
	      flag is needed for character indexing to include PREDISPLAY.

	      Each string consists of the following parts:

	      o	     Optionally,  a `P'	to signify that	the start and end off-
		     set that follow include any string	set by the  PREDISPLAY
		     special  parameter;  this	is  needed  if	the predisplay
		     string itself is to be highlighted.  Whitespace may  fol-
		     low the `P'.

	      o	     A start offset in the same	units as CURSOR, terminated by
		     whitespace.

	      o	     An	end offset in the same units as	CURSOR,	terminated  by
		     whitespace.

	      o	     A	highlight specification	in the same format as used for
		     contexts in the parameter zle_highlight, see the  section
		     `Character	 Highlighting' below; for example, standout or
		     fg=red,bold

	      For example,

		     region_highlight=("P0 20 bold")

	      specifies	that the first twenty characters of the	text including
	      any predisplay string should be highlighted in bold.

	      Note that	the effect of region_highlight is not saved and	disap-
	      pears as soon as the line	is accepted.

	      The final	highlighting on	the command line depends on  both  re-
	      gion_highlight  and  zle_highlight;  see	the  section CHARACTER
	      HIGHLIGHTING below for details.

       registers (associative array)
	      The contents of each of the vi register buffers. These are typi-
	      cally  set  using	 vi-set-buffer followed	by a delete, change or
	      yank command.

       SUFFIX_ACTIVE (integer)
       SUFFIX_START (integer)
       SUFFIX_END (integer)
	      SUFFIX_ACTIVE indicates  whether	an  auto-removable  completion
	      suffix is	currently active. SUFFIX_START and SUFFIX_END give the
	      location of the suffix and are in	the same units as CURSOR. They
	      are only valid for reading when SUFFIX_ACTIVE is non-zero.

	      All parameters are read-only.

       UNDO_CHANGE_NO (integer)
	      A	 number	 representing the state	of the undo history.  The only
	      use of this is passing as	an argument to the undo	widget in  or-
	      der to undo back to the recorded point.  Read-only.

       UNDO_LIMIT_NO (integer)
	      A	 number	 corresponding	to an existing change in the undo his-
	      tory; compare UNDO_CHANGE_NO.  If	this is	set to a value greater
	      than zero, the undo command will not allow the line to be	undone
	      beyond the given change number.  It is  still  possible  to  use
	      `zle undo	change'	in a widget to undo beyond that	point; in that
	      case, it will not	be possible to undo at all until UNDO_LIMIT_NO
	      is reduced.  Set to 0 to disable the limit.

	      A	 typical  use of this variable in a widget function is as fol-
	      lows (note the additional	function scope is required):

		     ()	{
		       local UNDO_LIMIT_NO=$UNDO_CHANGE_NO
		       # Perform some form of recursive	edit.
		     }

       WIDGET (scalar)
	      The name of the widget currently being executed; read-only.

       WIDGETFUNC (scalar)
	      The name of the shell function that implements a widget  defined
	      with  either  zle	-N or zle -C.  In the former case, this	is the
	      second argument to the zle -N command that defined  the  widget,
	      or  the  first argument if there was no second argument.	In the
	      latter case this is the third argument to	 the  zle  -C  command
	      that defined the widget.	Read-only.

       WIDGETSTYLE (scalar)
	      Describes	 the  implementation behind the	completion widget cur-
	      rently being executed; the second	argument that followed zle  -C
	      when the widget was defined.  This is the	name of	a builtin com-
	      pletion widget.  For widgets defined with	zle -N this is set  to
	      the empty	string.	 Read-only.

       YANK_ACTIVE (integer)
       YANK_START (integer)
       YANK_END	(integer)
	      YANK_ACTIVE indicates whether text has just been yanked (pasted)
	      into the buffer.	YANK_START and YANK_END	give the  location  of
	      the  pasted  text	and are	in the same units as CURSOR.  They are
	      only valid for reading when YANK_ACTIVE is non-zero.   They  can
	      also  be	assigned  by  widgets  that insert text	in a yank-like
	      fashion, for example wrappers of bracketed-paste.	 See also  zle
	      -f.

	      YANK_ACTIVE is read-only.

       ZLE_STATE (scalar)
	      Contains	a  set of space-separated words	that describe the cur-
	      rent zle state.

	      Currently, the states shown are the insert mode as  set  by  the
	      overwrite-mode  or  vi-replace  widgets and whether history com-
	      mands will visit imported	entries	as controlled by  the  set-lo-
	      cal-history  widget.  The	string contains	`insert' if characters
	      to be inserted on	the command line move existing	characters  to
	      the  right or `overwrite'	if characters to be inserted overwrite
	      existing characters. It contains `localhistory'  if  only	 local
	      history  commands	will be	visited	or `globalhistory' if imported
	      history commands will also be visited.

	      The substrings are sorted	in alphabetical	order so that  if  you
	      want  to test for	two specific substrings	in a future-proof way,
	      you can do match by doing:

		     if	[[ $ZLE_STATE == *globalhistory*insert*	]]; then ...; fi

   Special Widgets
       There are a few user-defined widgets which are special  to  the	shell.
       If they do not exist, no	special	action is taken.  The environment pro-
       vided is	identical to that for any other	editing	widget.

       zle-isearch-exit
	      Executed at the end of incremental search	at the point where the
	      isearch prompt is	removed	from the display.  See zle-isearch-up-
	      date for an example.

       zle-isearch-update
	      Executed within incremental search when the display is about  to
	      be  redrawn.   Additional	 output	 below	the incremental	search
	      prompt can be generated by using `zle  -M'  within  the  widget.
	      For example,

		     zle-isearch-update() { zle	-M "Line $HISTNO"; }
		     zle -N zle-isearch-update

	      Note the line output by `zle -M' is not deleted on exit from in-
	      cremental	search.	 This can be done from a zle-isearch-exit wid-
	      get:

		     zle-isearch-exit()	{ zle -M ""; }
		     zle -N zle-isearch-exit

       zle-line-pre-redraw
	      Executed whenever	the input line is about	to be redrawn, provid-
	      ing an opportunity to update the region_highlight	array.

       zle-line-init
	      Executed every time the line editor is started  to  read	a  new
	      line  of input.  The following example puts the line editor into
	      vi command mode when it starts up.

		     zle-line-init() { zle -K vicmd; }
		     zle -N zle-line-init

	      (The command inside the function sets the	keymap directly; it is
	      equivalent to zle	vi-cmd-mode.)

       zle-line-finish
	      This  is similar to zle-line-init	but is executed	every time the
	      line editor has finished reading a line of input.

       zle-history-line-set
	      Executed when the	history	line changes.

       zle-keymap-select
	      Executed every time the keymap changes, i.e. the special parame-
	      ter KEYMAP is set	to a different value, while the	line editor is
	      active.  Initialising the	keymap when  the  line	editor	starts
	      does not cause the widget	to be called.

	      The  value  $KEYMAP within the function reflects the new keymap.
	      The old keymap is	passed as the sole argument.

	      This can be used for detecting switches between the  vi  command
	      (vicmd) and insert (usually main)	keymaps.

STANDARD WIDGETS
       The  following is a list	of all the standard widgets, and their default
       bindings	in emacs mode,	vi  command  mode  and	vi  insert  mode  (the
       `emacs',	`vicmd'	and `viins' keymaps, respectively).

       Note  that cursor keys are bound	to movement keys in all	three keymaps;
       the shell assumes that the cursor keys send the key sequences  reported
       by  the	terminal-handling  library (termcap or terminfo).  The key se-
       quences shown in	the list are those based on the	VT100, common on  many
       modern  terminals, but in fact these are	not necessarily	bound.	In the
       case of the viins keymap, the initial escape character of the sequences
       serves  also to return to the vicmd keymap: whether this	happens	is de-
       termined	by the KEYTIMEOUT parameter, see zshparam(1).

   Movement
       vi-backward-blank-word (unbound)	(B) (unbound)
	      Move backward one	word, where a word is defined as a  series  of
	      non-blank	characters.

       vi-backward-blank-word-end (unbound) (gE) (unbound)
	      Move to the end of the previous word, where a word is defined as
	      a	series of non-blank characters.

       backward-char (^B ESC-[D) (unbound) (unbound)
	      Move backward one	character.

       vi-backward-char	(unbound) (^H h	^?) (ESC-[D)
	      Move backward one	character, without changing lines.

       backward-word (ESC-B ESC-b) (unbound) (unbound)
	      Move to the beginning of the previous word.

       emacs-backward-word
	      Move to the beginning of the previous word.

       vi-backward-word	(unbound) (b) (unbound)
	      Move to the beginning of the previous word, vi-style.

       vi-backward-word-end (unbound) (ge) (unbound)
	      Move to the end of the previous word, vi-style.

       beginning-of-line (^A) (unbound)	(unbound)
	      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.

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

       down-line (unbound) (unbound) (unbound)
	      Move down	a line in the buffer.

       end-of-line (^E)	(unbound) (unbound)
	      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.

       vi-end-of-line (unbound)	($) (unbound)
	      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	(argu-
	      ment - 1)	lines down.

       vi-forward-blank-word (unbound) (W) (unbound)
	      Move forward one word, where a word is defined as	 a  series  of
	      non-blank	characters.

       vi-forward-blank-word-end (unbound) (E) (unbound)
	      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  de-
	      fined as a series	of non-blank characters.

       forward-char (^F	ESC-[C)	(unbound) (unbound)
	      Move forward one character.

       vi-forward-char (unbound) (space	l) (ESC-[C)
	      Move forward one character.

       vi-find-next-char (^X^F)	(f) (unbound)
	      Read  a character	from the keyboard, and move to the next	occur-
	      rence of it in the line.

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

       vi-find-prev-char (unbound) (F) (unbound)
	      Read a character from the	keyboard, and move to the previous oc-
	      currence of it in	the line.

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

       vi-first-non-blank (unbound) (^)	(unbound)
	      Move to the first	non-blank character in the line.

       vi-forward-word (unbound) (w) (unbound)
	      Move forward one word, vi-style.

       forward-word (ESC-F ESC-f) (unbound) (unbound)
	      Move  to the beginning of	the next word.	The editor's idea of a
	      word is specified	with the WORDCHARS parameter.

       emacs-forward-word
	      Move to the end of the next word.

       vi-forward-word-end (unbound) (e) (unbound)
	      Move to the end of the next word.

       vi-goto-column (ESC-|) (|) (unbound)
	      Move to the column specified by the numeric argument.

       vi-goto-mark (unbound) (`) (unbound)
	      Move to the specified mark.

       vi-goto-mark-line (unbound) (') (unbound)
	      Move to beginning	of the line containing the specified mark.

       vi-repeat-find (unbound)	(;) (unbound)
	      Repeat the last vi-find command.

       vi-rev-repeat-find (unbound) (,)	(unbound)
	      Repeat the last vi-find command in the opposite direction.

       up-line (unbound) (unbound) (unbound)
	      Move up a	line in	the buffer.

   History Control
       beginning-of-buffer-or-history (ESC-<) (gg) (unbound)
	      Move to the beginning of the buffer, or if already  there,  move
	      to the first event in the	history	list.

       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.

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

       down-line-or-history (^N	ESC-[B)	(j) (ESC-[B)
	      Move down	a line in the buffer, or  if  already  at  the	bottom
	      line, move to the	next event in the history list.

       vi-down-line-or-history (unbound) (+) (unbound)
	      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.

       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.

	      If called	from a function	by the zle command with	arguments, the
	      first argument is	taken as  the  string  for  which  to  search,
	      rather than the first word in the	buffer.

       down-history (unbound) (^N) (unbound)
	      Move to the next event in	the history list.

       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.

       end-of-buffer-or-history	(ESC->)	(unbound) (unbound)
	      Move  to the end of the buffer, or if already there, move	to the
	      last event in the	history	list.

       end-of-line-hist
	      Move to the end of the line.  If already at the end of the  buf-
	      fer, move	to the next history line.

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

       vi-fetch-history	(unbound) (G) (unbound)
	      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).

       history-incremental-search-backward (^R ^Xr) (unbound) (unbound)
	      Search  backward	incrementally  for  a  specified  string.  The
	      search is	case-insensitive if the	search string  does  not  have
	      uppercase	letters	and no numeric argument	was given.  The	string
	      may begin	with `^' to anchor the search to the beginning of  the
	      line.  When called from a	user-defined function returns the fol-
	      lowing statuses: 0, if the search	succeeded; 1,  if  the	search
	      failed;  2,  if  the  search  term  was a	bad pattern; 3,	if the
	      search was aborted by the	send-break command.

	      A	restricted set	of  editing  functions	is  available  in  the
	      mini-buffer.   Keys are looked up	in the special isearch keymap,
	      and if not found there in	the main keymap	(note that by  default
	      the  isearch  keymap is empty).  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.
	      Note that	the following always perform the same task within  in-
	      cremental	 searches  and cannot be replaced by user defined wid-
	      gets, nor	can the	set of functions be extended.	The  supported
	      functions	are:

	      accept-and-hold
	      accept-and-infer-next-history
	      accept-line
	      accept-line-and-down-history
		     Perform  the  usual  function  after  exiting incremental
		     search.  The command line displayed is executed.

	      backward-delete-char
	      vi-backward-delete-char
		     Back up one place in the search history.  If  the	search
		     has been repeated this does not immediately erase a char-
		     acter in the minibuffer.

	      accept-search
		     Exit incremental search, retaining	the command  line  but
		     performing	no further action.  Note that this function is
		     not bound by default and has no effect outside  incremen-
		     tal search.

	      backward-delete-word
	      backward-kill-word
	      vi-backward-kill-word
		     Back  up  one  character  in  the minibuffer; if multiple
		     searches have been	performed since	the character was  in-
		     serted  the  search  history is rewound to	the point just
		     before the	character was entered.	Hence this has the ef-
		     fect of repeating backward-delete-char.

	      clear-screen
		     Clear the screen, remaining in incremental	search mode.

	      history-incremental-search-backward
		     Find the next occurrence of the contents of the mini-buf-
		     fer. If the mini-buffer is	empty, the most	recent	previ-
		     ously used	search string is reinstated.

	      history-incremental-search-forward
		     Invert the	sense of the search.

	      magic-space
		     Inserts a non-magical space.

	      quoted-insert
	      vi-quoted-insert
		     Quote the character to insert into	the minibuffer.

	      redisplay
		     Redisplay	the  command  line,  remaining	in incremental
		     search mode.

	      vi-cmd-mode
		     Select the	`vicmd'	 keymap;  the  `main'  keymap  (insert
		     mode) will	be selected initially.

		     In	addition, the modifications that were made while in vi
		     insert mode are merged to form a single undo event.

	      vi-repeat-search
	      vi-rev-repeat-search
		     Repeat the	search.	 The direction of the search is	 indi-
		     cated in the mini-buffer.

	      Any  character  that is not bound	to one of the above functions,
	      or self-insert or	self-insert-unmeta, will cause the mode	to  be
	      exited.	The  character	is  then looked	up and executed	in the
	      keymap in	effect at that point.

	      When called from a widget	function by the	zle command,  the  in-
	      cremental	search commands	can take a string argument.  This will
	      be treated as a string of	keys, as for arguments to the  bindkey
	      command, and used	as initial input for the command.  Any charac-
	      ters in the string which are unused by  the  incremental	search
	      will be silently ignored.	 For example,

		     zle history-incremental-search-backward forceps

	      will  search  backwards for forceps, leaving the minibuffer con-
	      taining the string `forceps'.

       history-incremental-search-forward (^S ^Xs) (unbound) (unbound)
	      Search forward incrementally for a specified string.  The	search
	      is case-insensitive if the search	string does not	have uppercase
	      letters and no numeric argument was given.  The string may begin
	      with `^' to anchor the search to the beginning of	the line.  The
	      functions	available in the mini-buffer are the same as for  his-
	      tory-incremental-search-backward.

       history-incremental-pattern-search-backward
       history-incremental-pattern-search-forward
	      These widgets behave similarly to	the corresponding widgets with
	      no -pattern, but the search string typed by the user is  treated
	      as a pattern, respecting the current settings of the various op-
	      tions affecting pattern matching.	 See  FILENAME	GENERATION  in
	      zshexpn(1)  for  a description of	patterns.  If no numeric argu-
	      ment was given lowercase letters in the search string may	 match
	      uppercase	letters	in the history.	 The string may	begin with `^'
	      to anchor	the search to the beginning of the line.

	      The prompt changes to indicate an	invalid	pattern; this may sim-
	      ply indicate the pattern is not yet complete.

	      Note  that  only non-overlapping matches are reported, so	an ex-
	      pression with wildcards may return fewer matches on a line  than
	      are visible by inspection.

       history-search-backward (ESC-P ESC-p) (unbound) (unbound)
	      Search  backward	in  the	 history for a line beginning with the
	      first word in the	buffer.

	      If called	from a function	by the zle command with	arguments, the
	      first  argument  is  taken  as  the  string for which to search,
	      rather than the first word in the	buffer.

       vi-history-search-backward (unbound) (/)	(unbound)
	      Search backward in the history  for  a  specified	 string.   The
	      string  may begin	with `^' 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 set-
	      ting,  will stop the search.  The	 functions  available  in  the
	      mini-buffer  are:	 accept-line,  backward-delete-char,  vi-back-
	      ward-delete-char,	  backward-kill-word,	vi-backward-kill-word,
	      clear-screen, redisplay, quoted-insert and vi-quoted-insert.

	      vi-cmd-mode  is treated the same as accept-line, and magic-space
	      is treated as a space.  Any other	character that is not bound to
	      self-insert  or  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.

	      If called	from a function	by the zle command with	arguments, the
	      first argument is	taken as  the  string  for  which  to  search,
	      rather than the first word in the	buffer.

       history-search-forward (ESC-N ESC-n) (unbound) (unbound)
	      Search  forward  in  the	history	 for a line beginning with the
	      first word in the	buffer.

	      If called	from a function	by the zle command with	arguments, the
	      first  argument  is  taken  as  the  string for which to search,
	      rather than the first word in the	buffer.

       vi-history-search-forward (unbound) (?) (unbound)
	      Search forward in	the  history  for  a  specified	 string.   The
	      string  may begin	with `^' to anchor the search to the beginning
	      of the line. The functions available in the mini-buffer are  the
	      same  as	for  vi-history-search-backward.  Argument handling is
	      also the same as for that	command.

       infer-next-history (^X^N) (unbound) (unbound)
	      Search in	the history list for a line matching the  current  one
	      and fetch	the event following it.

       insert-last-word	(ESC-_ ESC-.) (unbound)	(unbound)
	      Insert the last word from	the previous history event at the cur-
	      sor 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).  Repeating this com-
	      mand replaces the	word just inserted with	the last word from the
	      history  event prior to the one just used; numeric arguments can
	      be used in the same way to pick a	word from that event.

	      When called from a shell function	invoked	 from  a  user-defined
	      widget,  the command can take one	to three arguments.  The first
	      argument specifies a history offset which	applies	to  successive
	      calls  to	 this  widget:	if  it is -1, the default behaviour is
	      used, while if it	is 1,  successive  calls  will	move  forwards
	      through  the  history.  The value	0 can be used to indicate that
	      the history line examined	by the previous	execution of the  com-
	      mand  will  be reexamined.  Note that negative numbers should be
	      preceded by a `--' argument to avoid  confusing  them  with  op-
	      tions.

	      If two arguments are given, the second specifies the word	on the
	      command line in normal array index notation (as a	 more  natural
	      alternative  to  the  numeric  argument).	  Hence	1 is the first
	      word, and	-1 (the	default) is the	last word.

	      If a third argument is given, its	value is ignored,  but	it  is
	      used  to signify that the	history	offset is relative to the cur-
	      rent history line, rather	than the one remembered	after the pre-
	      vious invocations	of insert-last-word.

	      For example, the default behaviour of the	command	corresponds to

		     zle insert-last-word -- -1	-1

	      while the	command

		     zle insert-last-word -- -1	1 -

	      always  copies the first word of the line	in the history immedi-
	      ately before the line being edited.  This	has  the  side	effect
	      that  later  invocations	of the widget will be relative to that
	      line.

       vi-repeat-search	(unbound) (n) (unbound)
	      Repeat the last vi history search.

       vi-rev-repeat-search (unbound) (N) (unbound)
	      Repeat the last vi history search, but in	reverse.

       up-line-or-history (^P ESC-[A) (k) (ESC-[A)
	      Move up a	line in	the buffer, or if already  at  the  top	 line,
	      move to the previous event in the	history	list.

       vi-up-line-or-history (unbound) (-) (unbound)
	      Move  up	a  line	 in the	buffer,	or if already at the top line,
	      move to the previous event in the	history	list.	Then  move  to
	      the first	non-blank character on the line.

       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.

	      If called	from a function	by the zle command with	arguments, the
	      first argument is	taken as  the  string  for  which  to  search,
	      rather than the first word in the	buffer.

       up-history (unbound) (^P) (unbound)
	      Move to the previous event in the	history	list.

       history-beginning-search-forward
	      Search forward in	the history for	a line beginning with the cur-
	      rent line	up to the cursor.  This	leaves the cursor in its orig-
	      inal position.

       set-local-history
	      By  default,  history movement commands visit the	imported lines
	      as well as the local lines. This widget lets you toggle this  on
	      and  off,	or set it with the numeric argument. Zero for both lo-
	      cal and imported lines and nonzero for only local	lines.

   Modifying Text
       vi-add-eol (unbound) (A)	(unbound)
	      Move to the end of the line and enter insert mode.

       vi-add-next (unbound) (a) (unbound)
	      Enter insert mode	after the  current  cursor  position,  without
	      changing lines.

       backward-delete-char (^H	^?) (unbound) (unbound)
	      Delete the character behind the cursor.

       vi-backward-delete-char (unbound) (X) (^H)
	      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.

       backward-delete-word
	      Delete the word behind the cursor.

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

       backward-kill-word (^W ESC-^H ESC-^?) (unbound) (unbound)
	      Kill the word behind the cursor.

       vi-backward-kill-word (unbound) (unbound) (^W)
	      Kill  the	 word  behind the cursor, without going	past the point
	      where insert mode	was last entered.

       capitalize-word (ESC-C ESC-c) (unbound) (unbound)
	      Capitalize the current word and move past	it.

       vi-change (unbound) (c) (unbound)
	      Read a movement command from the keyboard,  and  kill  from  the
	      cursor position to the endpoint of the movement.	Then enter in-
	      sert mode.  If the command  is  vi-change,  change  the  current
	      line.

	      For  compatibility with vi, if the command is vi-forward-word or
	      vi-forward-blank-word, the whitespace after the word is not  in-
	      cluded.  If  you	prefer	the more consistent behaviour with the
	      whitespace included use the following key	binding:

		     bindkey -a	-s cw dwi

       vi-change-eol (unbound) (C) (unbound)
	      Kill to the end of the line and enter insert mode.

       vi-change-whole-line (unbound) (S) (unbound)
	      Kill the current line and	enter insert mode.

       copy-region-as-kill (ESC-W ESC-w) (unbound) (unbound)
	      Copy the area from the cursor to the mark	to the kill buffer.

	      If called	from a ZLE widget function in the form	`zle  copy-re-
	      gion-as-kill  string'  then  string will be taken	as the text to
	      copy to the kill buffer.	The cursor, the	mark and the  text  on
	      the command line are not used in this case.

       copy-prev-word (ESC-^_) (unbound) (unbound)
	      Duplicate	the word to the	left of	the cursor.

       copy-prev-shell-word
	      Like  copy-prev-word, but	the word is found by using shell pars-
	      ing, whereas copy-prev-word looks	for blanks. This makes a  dif-
	      ference when the word is quoted and contains spaces.

       vi-delete (unbound) (d) (unbound)
	      Read  a  movement	 command  from the keyboard, and kill from the
	      cursor position to the endpoint of the movement.	If the command
	      is vi-delete, kill the current line.

       delete-char
	      Delete the character under the cursor.

       vi-delete-char (unbound)	(x) (unbound)
	      Delete  the  character  under the	cursor,	without	going past the
	      end of the line.

       delete-word
	      Delete the current word.

       down-case-word (ESC-L ESC-l) (unbound) (unbound)
	      Convert the current word to all lowercase	and move past it.

       vi-down-case (unbound) (gu) (unbound)
	      Read a movement command from the keyboard, and convert all char-
	      acters  from the cursor position to the endpoint of the movement
	      to lowercase.  If	the movement command is	vi-down-case, swap the
	      case of all characters on	the current line.

       kill-word (ESC-D	ESC-d) (unbound) (unbound)
	      Kill the current word.

       gosmacs-transpose-chars
	      Exchange the two characters behind the cursor.

       vi-indent (unbound) (>) (unbound)
	      Indent a number of lines.

       vi-insert (unbound) (i) (unbound)
	      Enter insert mode.

       vi-insert-bol (unbound) (I) (unbound)
	      Move  to the first non-blank character on	the line and enter in-
	      sert mode.

       vi-join (^X^J) (J) (unbound)
	      Join the current line with the next one.

       kill-line (^K) (unbound)	(unbound)
	      Kill from	the cursor to the end of the line.  If already on  the
	      end of the line, kill the	newline	character.

       vi-kill-line (unbound) (unbound)	(^U)
	      Kill  from  the cursor back to wherever insert mode was last en-
	      tered.

       vi-kill-eol (unbound) (D) (unbound)
	      Kill from	the cursor to the end of the line.

       kill-region
	      Kill from	the cursor to the mark.

       kill-buffer (^X^K) (unbound) (unbound)
	      Kill the entire buffer.

       kill-whole-line (^U) (unbound) (unbound)
	      Kill the current line.

       vi-match-bracket	(^X^B) (%) (unbound)
	      Move to the bracket character (one of {},	() or []) 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.

       vi-open-line-above (unbound) (O)	(unbound)
	      Open a line above	the cursor and enter insert mode.

       vi-open-line-below (unbound) (o)	(unbound)
	      Open a line below	the cursor and enter insert mode.

       vi-oper-swap-case (unbound) (g~)	(unbound)
	      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 vi-oper-swap-case, swap
	      the case of all characters on the	current	line.

       overwrite-mode (^X^O) (unbound) (unbound)
	      Toggle between overwrite mode and	insert mode.

       vi-put-before (unbound) (P) (unbound)
	      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.

       vi-put-after (unbound) (p) (unbound)
	      Insert the contents of the kill buffer after the cursor.	If the
	      kill  buffer contains a sequence of lines	(as opposed to charac-
	      ters), paste it below the	current	line.

       put-replace-selection (unbound) (unbound) (unbound)
	      Replace the contents of the current region or selection with the
	      contents	of  the	kill buffer. If	the kill buffer	contains a se-
	      quence of	lines (as opposed to  characters),  the	 current  line
	      will be split by the pasted lines.

       quoted-insert (^V) (unbound) (unbound)
	      Insert  the  next	character typed	into the buffer	literally.  An
	      interrupt	character will not be inserted.

       vi-quoted-insert	(unbound) (unbound) (^Q	^V)
	      Display a	`^' at the cursor position, and	insert the next	 char-
	      acter  typed  into the buffer literally.	An interrupt character
	      will not be inserted.

       quote-line (ESC-') (unbound) (unbound)
	      Quote the	current	line; that is, put a `'' character at the  be-
	      ginning and the end, and convert all `'' characters to `'\'''.

       quote-region (ESC-") (unbound) (unbound)
	      Quote the	region from the	cursor to the mark.

       vi-replace (unbound) (R)	(unbound)
	      Enter overwrite mode.

       vi-repeat-change	(unbound) (.) (unbound)
	      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	remem-
	      bered for	future uses of this command.  The cut buffer  specifi-
	      cation is	similarly remembered.

       vi-replace-chars	(unbound) (r) (unbound)
	      Replace  the  character  under  the cursor with a	character read
	      from the keyboard.

       self-insert (printable characters) (unbound) (printable characters  and
       some control characters)
	      Insert a character into the buffer at the	cursor position.

       self-insert-unmeta (ESC-^I ESC-^J ESC-^M) (unbound) (unbound)
	      Insert  a	character into the buffer after	stripping the meta bit
	      and converting ^M	to ^J.

       vi-substitute (unbound) (s) (unbound)
	      Substitute the next character(s).

       vi-swap-case (unbound) (~) (unbound)
	      Swap the case of the character under the cursor  and  move  past
	      it.

       transpose-chars (^T) (unbound) (unbound)
	      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.

       transpose-words (ESC-T ESC-t) (unbound) (unbound)
	      Exchange the current word	with the one before it.

	      With  a positive numeric argument	N, the word around the cursor,
	      or following it if the cursor is between	words,	is  transposed
	      with the preceding N words.  The cursor is put at	the end	of the
	      resulting	group of words.

	      With a negative numeric argument -N, the effect is the  same  as
	      using  a positive	argument N except that the original cursor po-
	      sition is	retained, regardless of	how the	words are rearranged.

       vi-unindent (unbound) (<) (unbound)
	      Unindent a number	of lines.

       vi-up-case (unbound) (gU) (unbound)
	      Read a movement command from the keyboard, and convert all char-
	      acters  from the cursor position to the endpoint of the movement
	      to lowercase.  If	the movement command is	vi-up-case,  swap  the
	      case of all characters on	the current line.

       up-case-word (ESC-U ESC-u) (unbound) (unbound)
	      Convert the current word to all caps and move past it.

       yank (^Y) (unbound) (unbound)
	      Insert the contents of the kill buffer at	the cursor position.

       yank-pop	(ESC-y)	(unbound) (unbound)
	      Remove  the  text	just yanked, rotate the	kill-ring (the history
	      of previously killed text) and yank the  new  top.   Only	 works
	      following	yank, vi-put-before, vi-put-after or yank-pop.

       vi-yank (unbound) (y) (unbound)
	      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 vi-yank, copy the current
	      line.

       vi-yank-whole-line (unbound) (Y)	(unbound)
	      Copy the current line into the kill buffer.

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

   Arguments
       digit-argument (ESC-0..ESC-9) (1-9) (unbound)
	      Start a new numeric argument, or add to the  current  one.   See
	      also vi-digit-or-beginning-of-line.  This	only works if bound to
	      a	key sequence ending in a decimal digit.

	      Inside a widget function,	a call to  this	 function  treats  the
	      last  key	 of  the  key  sequence	which called the widget	as the
	      digit.

       neg-argument (ESC--) (unbound) (unbound)
	      Changes the sign of the following	argument.

       universal-argument
	      Multiply the argument of the next	command	by 4.	Alternatively,
	      if  this	command	 is  followed by an integer (positive or nega-
	      tive), use that as the argument for the next command.  Thus dig-
	      its cannot be repeated using this	command.  For example, if this
	      command occurs twice, followed immediately by forward-char, move
	      forward  sixteen	spaces;	 if instead it is followed by -2, then
	      forward-char, move backward two spaces.

	      Inside a widget function,	if passed an argument, i.e. `zle  uni-
	      versal-argument  num',  the numeric argument will	be set to num;
	      this is equivalent to `NUMERIC=num'.

       argument-base
	      Use the existing numeric argument	as a numeric base, which  must
	      be  in the range 2 to 36 inclusive.  Subsequent use of digit-ar-
	      gument and universal-argument will input a new numeric  argument
	      in  the  given  base.  The usual hexadecimal convention is used:
	      the letter a or A	corresponds to 10, and so  on.	 Arguments  in
	      bases requiring digits from 10 upwards are more conveniently in-
	      put with universal-argument, since ESC-a etc.  are  not  usually
	      bound to digit-argument.

	      The  function  can  be  used  with  a  command argument inside a
	      user-defined widget.  The	following code sets the	base to	16 and
	      lets  the	 user  input a hexadecimal argument until a key	out of
	      the digit	range is typed:

		     zle argument-base 16
		     zle universal-argument

   Completion
       accept-and-menu-complete
	      In a menu	completion, insert the	current	 completion  into  the
	      buffer, and advance to the next possible completion.

       complete-word
	      Attempt completion on the	current	word.

       delete-char-or-list (^D)	(unbound) (unbound)
	      Delete  the character under the cursor.  If the cursor is	at the
	      end of the line, list possible completions for the current word.

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

       expand-or-complete (TAB)	(unbound) (TAB)
	      Attempt shell expansion on the current word.  If that fails, at-
	      tempt completion.

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

       expand-history (ESC-space ESC-!)	(unbound) (unbound)
	      Perform history expansion	on the edit buffer.

       expand-word (^X*) (unbound) (unbound)
	      Attempt shell expansion on the current word.

       list-choices (ESC-^D) (^D =) (^D)
	      List possible completions	for the	current	word.

       list-expand (^Xg	^XG) (^G) (^G)
	      List the expansion of the	current	word.

       magic-space
	      Perform  history	expansion  and insert a	space into the buffer.
	      This is intended to be bound to space.

       menu-complete
	      Like complete-word, except that menu completion  is  used.   See
	      the MENU_COMPLETE	option.

       menu-expand-or-complete
	      Like expand-or-complete, except that menu	completion is used.

       reverse-menu-complete
	      Perform  menu  completion,  like menu-complete, except that if a
	      menu completion is already in progress,  move  to	 the  previous
	      completion rather	than the next.

       end-of-list
	      When  a  previous	 completion displayed a	list below the prompt,
	      this widget can be used to move the prompt below the list.

   Miscellaneous
       accept-and-hold (ESC-A ESC-a) (unbound) (unbound)
	      Push the contents	of the buffer on the buffer stack and  execute
	      it.

       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 fol-
	      lowing onto the buffer stack.

       accept-line (^J ^M) (^J ^M) (^J ^M)
	      Finish  editing  the buffer.  Normally this causes the buffer to
	      be executed as a shell command.

       accept-line-and-down-history (^O) (unbound) (unbound)
	      Execute the current line,	and push the next history event	on the
	      buffer stack.

       auto-suffix-remove
	      If  the  previous	 action	added a	suffix (space, slash, etc.) to
	      the word on the command line, remove it.	Otherwise do  nothing.
	      Removing	the suffix ends	any active menu	completion or menu se-
	      lection.

	      This widget is intended to be called from	 user-defined  widgets
	      to enforce a desired suffix-removal behavior.

       auto-suffix-retain
	      If  the  previous	 action	added a	suffix (space, slash, etc.) to
	      the word on the command line, force it to	be preserved.	Other-
	      wise do nothing.	Retaining the suffix ends any active menu com-
	      pletion or menu selection.

	      This widget is intended to be called from	 user-defined  widgets
	      to enforce a desired suffix-preservation behavior.

       beep   Beep, unless the BEEP option is unset.

       bracketed-paste
	      This  widget is invoked when text	is pasted to the terminal emu-
	      lator. It	is not intended	to be bound to actual keys but instead
	      to  the special sequence generated by the	terminal emulator when
	      text is pasted.

	      When invoked interactively, the pasted text is inserted  to  the
	      buffer  and  placed  in the cutbuffer.  If a numeric argument is
	      given, shell quoting will	be applied to the pasted  text	before
	      it is inserted.

	      When  a  named  buffer is	specified with vi-set-buffer ("x), the
	      pasted text is stored in that named buffer but not inserted.

	      When called from a widget	function  as  `bracketed-paste	name`,
	      the  pasted  text	 is assigned to	the variable name and no other
	      processing is done.

	      See also the zle_bracketed_paste parameter.

       vi-cmd-mode (^X^V) (unbound) (^[)
	      Enter command mode; that is, select the  `vicmd'	keymap.	  Yes,
	      this is bound by default in emacs	mode.

       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).

       clear-screen (^L	ESC-^L)	(^L) (^L)
	      Clear the	screen and redraw the prompt.

       deactivate-region
	      Make the current region inactive.	This disables vim-style	visual
	      selection	mode if	it is active.

       describe-key-briefly
	      Reads a key sequence, then prints	the function bound to that se-
	      quence.

       exchange-point-and-mark (^X^X) (unbound)	(unbound)
	      Exchange	the  cursor  position (point) with the position	of the
	      mark.  Unless a negative numeric argument	is given,  the	region
	      between  point  and  mark	 is  activated so that it can be high-
	      lighted.	If a zero numeric argument is given, the region	is ac-
	      tivated but point	and mark are not swapped.

       execute-named-cmd (ESC-x) (:) (unbound)
	      Read  the	 name  of  an editor command and execute it.  Aliasing
	      this widget with `zle -A'	or replacing it	with `zle -N'  has  no
	      effect   when   interpreting   key   bindings,   but  `zle  exe-
	      cute-named-cmd' will invoke such an alias	or replacement.

	      A	restricted set	of  editing  functions	is  available  in  the
	      mini-buffer.   Keys are looked up	in the special command keymap,
	      and if not found there in	the main keymap.  An interrupt signal,
	      as  defined  by the stty setting,	will abort the function.  Note
	      that the following always	perform	the same task within the  exe-
	      cuted-named-cmd  environment  and	cannot be replaced by user de-
	      fined widgets, nor can the set of	functions  be  extended.   The
	      allowed	 functions    are:    backward-delete-char,   vi-back-
	      ward-delete-char,	  clear-screen,	  redisplay,	quoted-insert,
	      vi-quoted-insert,	  backward-kill-word,	vi-backward-kill-word,
	      kill-whole-line, vi-kill-line, backward-kill-line, list-choices,
	      delete-char-or-list,  complete-word, accept-line,	expand-or-com-
	      plete and	expand-or-complete-prefix.

	      kill-region kills	the last word, and vi-cmd-mode is treated  the
	      same as accept-line.  The	space and tab characters, if not bound
	      to one of	these functions, will complete the name	and then  list
	      the  possibilities  if  the  AUTO_LIST option is set.  Any other
	      character	that is	not bound to self-insert or self-insert-unmeta
	      will  beep  and  be ignored.  The	bindings of the	current	insert
	      mode will	be used.

	      Currently	this command may not be	redefined or called by name.

       execute-last-named-cmd (ESC-z) (unbound)	(unbound)
	      Redo the last function executed with execute-named-cmd.

	      Like execute-named-cmd, this command may not be  redefined,  but
	      it may be	called by name.

       get-line	(ESC-G ESC-g) (unbound)	(unbound)
	      Pop  the top line	off the	buffer stack and insert	it at the cur-
	      sor position.

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

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

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

       push-line (^Q ESC-Q ESC-q) (unbound) (unbound)
	      Push the current buffer onto the buffer stack and	clear the buf-
	      fer.  Next time the editor starts	up, the	buffer will be	popped
	      off the top of the buffer	stack and loaded into the editing buf-
	      fer.

       push-line-or-edit
	      At the top-level (PS1) prompt, equivalent	to  push-line.	 At  a
	      secondary	 (PS2)	prompt,	move the entire	current	multiline con-
	      struct into the editor buffer.   The  latter  is	equivalent  to
	      push-input followed by get-line.

       read-command
	      Only  useful  from  a  user-defined widget.  A keystroke is read
	      just as in normal	operation, but instead of  the	command	 being
	      executed	the  name  of  the  command  that would	be executed is
	      stored in	the shell parameter REPLY.  This can be	 used  as  the
	      argument	of  a  future zle command.  If the key sequence	is not
	      bound, status 1 is returned; typically, however, REPLY is	set to
	      undefined-key to indicate	a useless key sequence.

       recursive-edit
	      Only  useful  from  a user-defined widget.  At this point	in the
	      function,	the editor regains control until one of	 the  standard
	      widgets which would normally cause zle to	exit (typically	an ac-
	      cept-line	caused by hitting the return key)  is  executed.   In-
	      stead,  control  returns to the user-defined widget.  The	status
	      returned is non-zero if the return was caused by an  error,  but
	      the  function  still  continues executing	and hence may tidy up.
	      This makes it safe for the user-defined widget to	alter the com-
	      mand line	or key bindings	temporarily.

	      The following widget, caps-lock, serves as an example.

		     self-insert-ucase() {
		       LBUFFER+=${(U)KEYS[-1]}
		     }

		     integer stat

		     zle -N self-insert	self-insert-ucase
		     zle -A caps-lock save-caps-lock
		     zle -A accept-line	caps-lock

		     zle recursive-edit
		     stat=$?

		     zle -A .self-insert self-insert
		     zle -A save-caps-lock caps-lock
		     zle -D save-caps-lock

		     ((	stat ))	&& zle send-break

		     return $stat

	      This  causes  typed letters to be	inserted capitalised until ei-
	      ther accept-line (i.e. typically the return key) is typed	or the
	      caps-lock	 widget	is invoked again; the later is handled by sav-
	      ing the old definition of	caps-lock as save-caps-lock  and  then
	      rebinding	it to invoke accept-line.  Note	that an	error from the
	      recursive	edit is	detected as a non-zero return status and prop-
	      agated by	using the send-break widget.

       redisplay (unbound) (^R)	(^R)
	      Redisplays the edit buffer.

       reset-prompt (unbound) (unbound)	(unbound)
	      Force the	prompts	on both	the left and right of the screen to be
	      re-expanded, then	redisplay  the	edit  buffer.	This  reflects
	      changes  both  to	the prompt variables themselves	and changes in
	      the expansion of the values (for example,	changes	in time	or di-
	      rectory, or changes to the value of variables referred to	by the
	      prompt).

	      Otherwise, the prompt is only expanded each time zle starts, and
	      when the display as been interrupted by output from another part
	      of the shell (such as a job notification)	which causes the  com-
	      mand line	to be reprinted.

       send-break (^G ESC-^G) (unbound)	(unbound)
	      Abort  the  current editor function, e.g.	execute-named-command,
	      or the editor itself, e.g. if you	are in vared. Otherwise	 abort
	      the  parsing  of the current line; in this case the aborted line
	      is available in the shell	variable ZLE_LINE_ABORTED.  If the ed-
	      itor    is    aborted    from   within   vared,	the   variable
	      ZLE_VARED_ABORTED	is set.

       run-help	(ESC-H ESC-h) (unbound)	(unbound)
	      Push the buffer onto the buffer stack, and execute  the  command
	      `run-help	 cmd',	where cmd is the current command.  run-help is
	      normally aliased to man.

       vi-set-buffer (unbound) (") (unbound)
	      Specify a	buffer to be used in the following command.  There are
	      37  buffers  that	can be specified: the 26 `named' buffers "a to
	      "z, the `yank' buffer "0,	the nine `queued' buffers "1 to	"9 and
	      the `black hole' buffer "_.  The named buffers can also be spec-
	      ified as "A to "Z.

	      When a buffer is specified for a cut, change  or	yank  command,
	      the  text	concerned replaces the previous	contents of the	speci-
	      fied buffer. If a	named buffer is	specified using	a capital, the
	      newly  cut text is appended to the buffer	instead	of overwriting
	      it. When using the "_ buffer, nothing happens. This can be  use-
	      ful for deleting text without affecting any buffers.

	      If  no  buffer  is  specified for	a cut or change	command, "1 is
	      used, and	the contents of	"1 to "8 are each  shifted  along  one
	      buffer;  the  contents  of "9 is lost. If	no buffer is specified
	      for a yank command, "0 is	used. Finally, a paste command without
	      a	specified buffer will paste the	text from the most recent com-
	      mand regardless of any buffer that might	have  been  used  with
	      that command.

	      When  called from	a widget function by the zle command, the buf-
	      fer can optionally be specified with an argument.	For example,

		     zle vi-set-buffer A

       vi-set-mark (unbound) (m) (unbound)
	      Set the specified	mark at	the cursor position.

       set-mark-command	(^@) (unbound) (unbound)
	      Set the mark at the cursor position.  If called with a  negative
	      numeric  argument, do not	set the	mark but deactivate the	region
	      so that it is no longer highlighted  (it	is  still  usable  for
	      other purposes).	Otherwise the region is	marked as active.

       spell-word (ESC-$ ESC-S ESC-s) (unbound)	(unbound)
	      Attempt spelling correction on the current word.

       split-undo
	      Breaks  the undo sequence	at the current change.	This is	useful
	      in vi mode as changes made in insert mode	are coalesced  on  en-
	      tering  command  mode.   Similarly, undo will normally revert as
	      one all the changes made by a user-defined widget.

       undefined-key
	      This command is executed when a key sequence that	is  not	 bound
	      to any command is	typed.	By default it beeps.

       undo (^_	^Xu ^X^U) (u) (unbound)
	      Incrementally undo the last text modification.  When called from
	      a	user-defined widget, takes an optional argument	 indicating  a
	      previous	 state	 of  the  undo	history	 as  returned  by  the
	      UNDO_CHANGE_NO variable; modifications  are  undone  until  that
	      state   is   reached,  subject  to  any  limit  imposed  by  the
	      UNDO_LIMIT_NO variable.

	      Note that	when invoked from vi  command  mode,  the  full	 prior
	      change  made in insert mode is reverted, the changes having been
	      merged when command mode was selected.

       redo (unbound) (^R) (unbound)
	      Incrementally redo undone	text modifications.

       vi-undo-change (unbound)	(unbound) (unbound)
	      Undo the last text modification.	If repeated, redo the  modifi-
	      cation.

       visual-mode (unbound) (v) (unbound)
	      Toggle vim-style visual selection	mode. If line-wise visual mode
	      is currently enabled then	it is changed to being character-wise.
	      If used following	an operator, it	forces the subsequent movement
	      command to be treated as a character-wise	movement.

       visual-line-mode	(unbound) (V) (unbound)
	      Toggle vim-style line-wise visual	 selection  mode.  If  charac-
	      ter-wise	visual mode is currently enabled then it is changed to
	      being line-wise. If used following an operator,  it  forces  the
	      subsequent  movement  command to be treated as a line-wise move-
	      ment.

       what-cursor-position (^X=) (ga) (unbound)
	      Print the	character under	the cursor, its	code as	an octal, dec-
	      imal  and	hexadecimal number, the	current	cursor position	within
	      the buffer and the column	of the cursor in the current line.

       where-is
	      Read the name of an editor command and print the listing of  key
	      sequences	 that  invoke the specified command.  A	restricted set
	      of editing functions is available	in the mini-buffer.  Keys  are
	      looked  up in the	special	command	keymap,	and if not found there
	      in the main keymap.

       which-command (ESC-?) (unbound) (unbound)
	      Push the buffer onto the buffer stack, and execute  the  command
	      `which-command   cmd'.   where   cmd  is	the  current  command.
	      which-command is normally	aliased	to whence.

       vi-digit-or-beginning-of-line (unbound) (0) (unbound)
	      If the last command executed was a digit as part of an argument,
	      continue the argument.  Otherwise, execute vi-beginning-of-line.

   Text	Objects
       Text  objects  are  commands that can be	used to	select a block of text
       according to some criteria. They	are a feature of the vim  text	editor
       and  so are primarily intended for use with vi operators	or from	visual
       selection mode. However,	they can also be used from vi-insert or	 emacs
       mode. Key bindings listed below apply to	the viopp and visual keymaps.

       select-a-blank-word (aW)
	      Select a word including adjacent blanks, where a word is defined
	      as a series of non-blank characters. With	 a  numeric  argument,
	      multiple words will be selected.

       select-a-shell-word (aa)
	      Select  the  current  command argument applying the normal rules
	      for quoting.

       select-a-word (aw)
	      Select a	word  including	 adjacent  blanks,  using  the	normal
	      vi-style	word  definition.  With	 a  numeric argument, multiple
	      words will be selected.

       select-in-blank-word (iW)
	      Select a word, where a word is defined as	a series of  non-blank
	      characters.  With	a numeric argument, multiple words will	be se-
	      lected.

       select-in-shell-word (ia)
	      Select the current command argument applying  the	 normal	 rules
	      for quoting. If the argument begins and ends with	matching quote
	      characters, these	are not	included in the	selection.

       select-in-word (iw)
	      Select a word, using the normal vi-style word definition.	With a
	      numeric argument,	multiple words will be selected.

CHARACTER HIGHLIGHTING
       The  line  editor has the ability to highlight characters or regions of
       the line	that have a particular significance.  This  is	controlled  by
       the array parameter zle_highlight, if it	has been set by	the user.

       If  the	parameter  contains  the single	entry none all highlighting is
       turned off.  Note the parameter is still	expected to be an array.

       Otherwise each entry of the array should	consist	of a word indicating a
       context	for highlighting, then a colon,	then a comma-separated list of
       the types of highlighting to apply in that context.

       The contexts available for highlighting are the following:

       default
	      Any text within the command line not affected by any other high-
	      lighting.	 Text outside the editable area	of the command line is
	      not affected.

       isearch
	      When one of the incremental history search  widgets  is  active,
	      the  area	 of  the  command line matched by the search string or
	      pattern.

       region The currently selected text. In emacs terminology, this  is  re-
	      ferred to	as the region and is bounded by	the cursor (point) and
	      the mark.	The region is only highlighted if it is	active,	 which
	      is  the case after the mark is modified with set-mark-command or
	      exchange-point-and-mark.	Note that whether or not the region is
	      active  has  no effect on	its use	within emacs style widgets, it
	      simply determines	whether	it is highlighted. In vi mode, the re-
	      gion corresponds to selected text	in visual mode.

       special
	      Individual  characters that have no direct printable representa-
	      tion but are shown in a  special	manner	by  the	 line  editor.
	      These characters are described below.

       suffix This  context  is	 used  in  completion  for characters that are
	      marked as	suffixes that will be removed if the  completion  ends
	      at  that point, the most obvious example being a slash (/) after
	      a	directory name.	 Note that suffix removal is configurable; the
	      circumstances  under which the suffix will be removed may	differ
	      for different completions.

       paste  Following	a command to paste text, the characters	that were  in-
	      serted.

       When  region_highlight  is  set,	the contexts that describe a region --
       isearch,	region,	suffix,	and paste  --  are  applied  first,  then  re-
       gion_highlight  is  applied,  then the remaining	zle_highlight contexts
       are applied.  If	a particular character is affected by multiple	speci-
       fications, the last specification wins.

       zle_highlight  may contain additional fields for	controlling how	termi-
       nal sequences to	change colours are output.  Each of the	 following  is
       followed	 by a colon and	a string in the	same form as for key bindings.
       This will not be	necessary for the vast majority	of  terminals  as  the
       defaults	shown in parentheses are widely	used.

       fg_start_code (\e[3)
	      The  start  of  the  escape  sequence for	the foreground colour.
	      This is followed by an ASCII digit representing the colour.

       fg_default_code (9)
	      The number to use	instead	of the colour  to  reset  the  default
	      foreground colour.

       fg_end_code (m)
	      The end of the escape sequence for the foreground	colour.

       bg_start_code (\e[4)
	      The  start  of  the  escape  sequence for	the background colour.
	      This is followed by an ASCII digit representing the colour.

       bg_default_code (9)
	      The number to use	instead	of the colour  to  reset  the  default
	      background colour.

       bg_end_code (m)
	      The end of the escape sequence for the background	colour.

       The  available  types of	highlighting are the following.	 Note that not
       all types of highlighting are available on all terminals:

       none   No highlighting is applied to the	given context.	It is not use-
	      ful  for	this to	appear with other types	of highlighting; it is
	      used to override a default.

       fg=colour
	      The foreground colour should be set to colour, a decimal integer
	      or the name of one of the	eight most widely-supported colours.

	      Not  all	terminals  support this	and, of	those that do, not all
	      provide facilities to test the support, hence  the  user	should
	      decide  based  on	the terminal type.  Most terminals support the
	      colours black, red,  green,  yellow,  blue,  magenta,  cyan  and
	      white,  which  can  be set by name.  In addition.	default	may be
	      used to set the terminal's default foreground colour.  Abbrevia-
	      tions  are  allowed;  b or bl selects black.  Some terminals may
	      generate additional  colours  if	the  bold  attribute  is  also
	      present.

	      On  recent  terminals and	on systems with	an up-to-date terminal
	      database the number of colours supported may be  tested  by  the
	      command  `echotc	Co'; if	this succeeds, it indicates a limit on
	      the number of colours which will be enforced by the line editor.
	      The  number  of  colours is in any case limited to 256 (i.e. the
	      range 0 to 255).

	      Colour is	also known as color.

       bg=colour
	      The background colour should be set to colour.  This works simi-
	      larly  to	 the  foreground  colour, except the background	is not
	      usually affected by the bold attribute.

       bold   The characters in	the given context are shown in	a  bold	 font.
	      Not all terminals	distinguish bold fonts.

       standout
	      The  characters in the given context are shown in	the terminal's
	      standout mode.  The actual effect	is specific to	the  terminal;
	      on  many terminals it is inverse video.  On some such terminals,
	      where the	cursor does not	blink it appears  with	standout  mode
	      negated, making it less than clear where the cursor actually is.
	      On such terminals	one of the other effects may be	preferable for
	      highlighting the region and matched search string.

       underline
	      The  characters in the given context are shown underlined.  Some
	      terminals	show the foreground in a different colour instead;  in
	      this case	whitespace will	not be highlighted.

       The  characters	described above	as `special' are as follows.  The for-
       matting described here is used irrespective of whether  the  characters
       are highlighted:

       ASCII control characters
	      Control  characters in the ASCII range are shown as `^' followed
	      by the base character.

       Unprintable multibyte characters
	      This item	applies	to control characters not in the ASCII	range,
	      plus other characters as follows.	 If the	MULTIBYTE option is in
	      effect, multibyte	characters not in the ASCII character set that
	      are reported as having zero width	are treated as combining char-
	      acters when the option COMBINING_CHARS is	on.  If	the option  is
	      off,  or	if  a character	appears	where a	combining character is
	      not valid, the character is treated as unprintable.

	      Unprintable multibyte characters are shown as a hexadecimal num-
	      ber between angle	brackets.  The number is the code point	of the
	      character	in the wide character set; this	may or may not be Uni-
	      code, depending on the operating system.

       Invalid multibyte characters
	      If  the  MULTIBYTE  option  is in	effect,	any sequence of	one or
	      more bytes that does not form a valid character in  the  current
	      character	 set  is  treated as a series of bytes each shown as a
	      special character.  This case can	be  distinguished  from	 other
	      unprintable characters as	the bytes are represented as two hexa-
	      decimal digits between angle brackets, as	distinct from the four
	      or  eight	 digits	 that are used for unprintable characters that
	      are nonetheless valid in the current character set.

	      Not all systems support this: for	it to work, the	system's  rep-
	      resentation of wide characters must be code values from the Uni-
	      versal Character Set, as defined by IS0  10646  (also  known  as
	      Unicode).

       Wrapped double-width characters
	      When  a  double-width character appears in the final column of a
	      line, it is instead shown	on the next line. The empty space left
	      in the original position is highlighted as a special character.

       If  zle_highlight  is  not set or no value applies to a particular con-
       text, the defaults applied are equivalent to

	      zle_highlight=(region:standout special:standout
	      suffix:bold isearch:underline paste:standout)

       i.e. both the region and	special	characters are shown in	standout mode.

       Within widgets, arbitrary regions may be	 highlighted  by  setting  the
       special array parameter region_highlight; see above.

ZSHCOMPWID(1)		    General Commands Manual		 ZSHCOMPWID(1)

NAME
       zshcompwid - zsh	completion widgets

DESCRIPTION
       The shell's programmable	completion mechanism can be manipulated	in two
       ways; here the low-level	features supporting the	newer,	function-based
       mechanism  are  defined.	  A  complete  set of shell functions based on
       these features is described in zshcompsys(1), and users with no	inter-
       est in adding to	that system (or, potentially, writing their own	-- see
       dictionary entry	for `hubris') should skip the  current	section.   The
       older  system based on the compctl builtin command is described in zsh-
       compctl(1).

       Completion widgets are defined by the -C	option to the zle builtin com-
       mand provided by	the zsh/zle module (see	zshzle(1)). For	example,

	      zle -C complete expand-or-complete completer

       defines	a widget named `complete'.  The	second argument	is the name of
       any of the builtin widgets that handle completions: complete-word,  ex-
       pand-or-complete,  expand-or-complete-prefix,  menu-complete,  menu-ex-
       pand-or-complete,     reverse-menu-complete,	 list-choices,	    or
       delete-char-or-list.  Note that this will still work even if the	widget
       in question has been re-bound.

       When this newly defined widget is bound to  a  key  using  the  bindkey
       builtin	command	 defined in the	zsh/zle	module (see zshzle(1)),	typing
       that key	will call the shell function `completer'. This function	is re-
       sponsible  for  generating  the possible	matches	using the builtins de-
       scribed below.  As with other ZLE widgets, the function is called  with
       its standard input closed.

       Once the	function returns, the completion code takes over control again
       and treats the matches in the same manner as the	specified builtin wid-
       get, in this case expand-or-complete.

COMPLETION SPECIAL PARAMETERS
       The  parameters	ZLE_REMOVE_SUFFIX_CHARS	and ZLE_SPACE_SUFFIX_CHARS are
       used by the completion mechanism, but are not special.  See  Parameters
       Used By The Shell in zshparam(1).

       Inside completion widgets, and any functions called from	them, some pa-
       rameters	have special meaning; outside these  functions	they  are  not
       special to the shell in any way.	 These parameters are used to pass in-
       formation between the completion	code and the completion	 widget.  Some
       of  the builtin commands	and the	condition codes	use or change the cur-
       rent values of these parameters.	 Any existing values  will  be	hidden
       during  execution  of completion	widgets; except	for compstate, the pa-
       rameters	are reset on each function  exit  (including  nested  function
       calls  from  within  the	completion widget) to the values they had when
       the function was	entered.

       CURRENT
	      This is the number of the	current	word, i.e. the word the	cursor
	      is  currently  on	 in  the words array.  Note that this value is
	      only correct if the ksharrays option is not set.

       IPREFIX
	      Initially	this will be set to the	empty string.  This  parameter
	      functions	 like  PREFIX; it contains a string which precedes the
	      one in PREFIX and	is not considered part of the list of matches.
	      Typically,  a string is transferred from the beginning of	PREFIX
	      to the end of IPREFIX, for example:

		     IPREFIX=${PREFIX%%\=*}=
		     PREFIX=${PREFIX#*=}

	      causes the part of the prefix up	to  and	 including  the	 first
	      equal  sign not to be treated as part of a matched string.  This
	      can be done automatically	by the compset builtin,	see below.

       ISUFFIX
	      As IPREFIX, but for a suffix that	should not be considered  part
	      of  the matches; note that the ISUFFIX string follows the	SUFFIX
	      string.

       PREFIX Initially	this will be set to the	part of	the current word  from
	      the  beginning  of the word up to	the position of	the cursor; it
	      may be altered to	give a common prefix for all matches.

       QIPREFIX
	      This parameter is	read-only and contains the quoted string up to
	      the  word	being completed. E.g. when completing `"foo', this pa-
	      rameter contains the double quote. If the	-q option  of  compset
	      is used (see below), and the original string was `"foo bar' with
	      the cursor on the	`bar', this parameter contains `"foo '.

       QISUFFIX
	      Like QIPREFIX, but containing the	suffix.

       SUFFIX Initially	this will be set to the	part of	the current word  from
	      the cursor position to the end; it may be	altered	to give	a com-
	      mon suffix for all matches.  It is most useful when  the	option
	      COMPLETE_IN_WORD is set, as otherwise the	whole word on the com-
	      mand line	is treated as a	prefix.

       compstate
	      This is an associative array with	various	keys and  values  that
	      the  completion  code uses to exchange information with the com-
	      pletion widget.  The keys	are:

	      all_quotes
		     The -q option of the compset builtin command (see	below)
		     allows  a quoted string to	be broken into separate	words;
		     if	the cursor is on one of	those words, that word will be
		     completed,	 possibly  invoking  `compset -q' recursively.
		     With this key it is possible to test the types of	quoted
		     strings  which  are  currently  broken into parts in this
		     fashion.  Its value contains one character	for each quot-
		     ing level.	 The characters	are a single quote or a	double
		     quote for strings quoted with these characters, a dollars
		     sign  for	strings	quoted with $'...' and a backslash for
		     strings not starting with a quote character.   The	 first
		     character	in  the	value always corresponds to the	inner-
		     most quoting level.

	      context
		     This will be set by the completion	code  to  the  overall
		     context in	which completion is attempted. Possible	values
		     are:

		     array_value
			    when completing inside the value of	an  array  pa-
			    rameter  assignment;  in this case the words array
			    contains the words inside the parentheses.

		     brace_parameter
			    when completing the	name of	a parameter in	a  pa-
			    rameter expansion beginning	with ${.  This context
			    will also be set when completing  parameter	 flags
			    following  ${(;  the full command line argument is
			    presented and the handler must test	the  value  to
			    be completed to ascertain that this	is the case.

		     assign_parameter
			    when  completing  the name of a parameter in a pa-
			    rameter assignment.

		     command
			    when completing for	a normal  command  (either  in
			    command  position  or  for an argument of the com-
			    mand).

		     condition
			    when completing inside a `[[...]]' conditional ex-
			    pression;  in  this	 case the words	array contains
			    only the words inside the conditional expression.

		     math   when completing in a mathematical environment such
			    as a `((...))' construct.

		     parameter
			    when  completing  the name of a parameter in a pa-
			    rameter expansion beginning	with $ but not ${.

		     redirect
			    when completing after a redirection	operator.

		     subscript
			    when completing inside a parameter subscript.

		     value  when completing the	value of a  parameter  assign-
			    ment.

	      exact  Controls  the behaviour when the REC_EXACT	option is set.
		     It	will be	set to accept if an exact match	would  be  ac-
		     cepted, and will be unset otherwise.

		     If	it was set when	at least one match equal to the	string
		     on	the line was generated,	the match is accepted.

	      exact_string
		     The string	of an exact match if one was found,  otherwise
		     unset.

	      ignored
		     The  number  of  words  that  were	 ignored  because they
		     matched one of the	patterns given with the	-F  option  to
		     the compadd builtin command.

	      insert This  controls  the  manner  in which a match is inserted
		     into the command line.  On	entry to the widget  function,
		     if	 it is unset the command line is not to	be changed; if
		     set to unambiguous, any prefix common to all  matches  is
		     to	 be inserted; if set to	automenu-unambiguous, the com-
		     mon prefix	is to be inserted and the next	invocation  of
		     the completion code may start menu	completion (due	to the
		     AUTO_MENU option being set); if set to menu  or  automenu
		     menu completion will be started for the matches currently
		     generated (in the latter case this	 will  happen  because
		     the  AUTO_MENU  is	 set).	The value may also contain the
		     string `tab' when the completion code would normally  not
		     really do completion, but only insert the TAB character.

		     On	 exit  it may be set to	any of the values above	(where
		     setting it	to the empty string is the same	 as  unsetting
		     it), or to	a number, in which case	the match whose	number
		     is	given will be inserted into the	command	 line.	 Nega-
		     tive  numbers  count  backward  from the last match (with
		     `-1' selecting the	last match)  and  out-of-range	values
		     are  wrapped  around, so that a value of zero selects the
		     last match	and a value one	more than the maximum  selects
		     the  first. Unless	the value of this key ends in a	space,
		     the match is inserted as in a menu	completion, i.e. with-
		     out automatically appending a space.

		     Both menu and automenu may	also specify the number	of the
		     match to insert,  given  after  a	colon.	 For  example,
		     `menu:2'  says  to	 start menu completion,	beginning with
		     the second	match.

		     Note that a value containing the  substring  `tab'	 makes
		     the  matches generated be ignored and only	the TAB	be in-
		     serted.

		     Finally, it may also be  set  to  all,  which  makes  all
		     matches generated be inserted into	the line.

	      insert_positions
		     When  the completion system inserts an unambiguous	string
		     into the line, there may be multiple places where charac-
		     ters  are missing or where	the character inserted differs
		     from at least one match.  The value of this key  contains
		     a colon separated list of all these positions, as indexes
		     into the command line.

	      last_prompt
		     If	this is	set to a  non-empty  string  for  every	 match
		     added,  the  completion code will move the	cursor back to
		     the previous prompt after the  list  of  completions  has
		     been displayed.  Initially	this is	set or unset according
		     to	the ALWAYS_LAST_PROMPT option.

	      list   This controls whether or how the list of matches will  be
		     displayed.	  If  it  is unset or empty they will never be
		     listed; if	its value begins with list, they  will	always
		     be	 listed; if it begins with autolist or ambiguous, they
		     will be listed when the AUTO_LIST or  LIST_AMBIGUOUS  op-
		     tions respectively	would normally cause them to be.

		     If	 the  substring	force appears in the value, this makes
		     the list be shown even if there is	only one  match.  Nor-
		     mally, the	list would be shown only if there are at least
		     two matches.

		     The  value	 contains  the	 substring   packed   if   the
		     LIST_PACKED option	is set.	If this	substring is given for
		     all matches added to a group, this	group  will  show  the
		     LIST_PACKED   behavior.   The   same   is	done  for  the
		     LIST_ROWS_FIRST option with the substring rows.

		     Finally, if the value contains the	 string	 explanations,
		     only  the explanation strings, if any, will be listed and
		     if	it contains messages, only the	messages  (added  with
		     the -x option of compadd) will be listed.	If it contains
		     both explanations and messages both kinds of  explanation
		     strings  will be listed.  It will be set appropriately on
		     entry to a	completion widget and may be changed there.

	      list_lines
		     This gives	the number of lines that are needed to display
		     the full list of completions.  Note that to calculate the
		     total number of lines to display you need to add the num-
		     ber  of  lines needed for the command line	to this	value,
		     this is available as the value of the BUFFERLINES special
		     parameter.

	      list_max
		     Initially this is set to the value	of the LISTMAX parame-
		     ter.  It may be set to any	other value; when  the	widget
		     exits  this  value	 will  be  used	in the same way	as the
		     value of LISTMAX.

	      nmatches
		     The number	of matches generated and accepted by the  com-
		     pletion code so far.

	      old_insert
		     On	 entry to the widget this will be set to the number of
		     the match of an old list of completions that is currently
		     inserted  into the	command	line. If no match has been in-
		     serted, this is unset.

		     As	with old_list, the value of this key will only be used
		     if	 it is the string keep.	If it was set to this value by
		     the widget	and there was an old match inserted  into  the
		     command line, this	match will be kept and if the value of
		     the insert	key specifies that another match should	be in-
		     serted, this will be inserted after the old one.

	      old_list
		     This is set to yes	if there is still a valid list of com-
		     pletions from a previous completion at the	time the  wid-
		     get  is  invoked.	 This  will usually be the case	if and
		     only if the previous editing operation was	 a  completion
		     widget  or	 one  of the builtin completion	functions.  If
		     there is a	valid list and it is also currently  shown  on
		     the screen, the value of this key is shown.

		     After the widget has exited the value of this key is only
		     used if it	was set	to keep.  In this case the  completion
		     code  will	 continue to use this old list.	 If the	widget
		     generated new matches, they will not be used.

	      parameter
		     The name of the parameter when completing in a  subscript
		     or	in the value of	a parameter assignment.

	      pattern_insert
		     Normally  this  is	set to menu, which specifies that menu
		     completion	will be	used whenever a	 set  of  matches  was
		     generated	using  pattern	matching.  If it is set	to any
		     other non-empty string by the user	and menu completion is
		     not  selected by other option settings, the code will in-
		     stead insert any common prefix for	the generated  matches
		     as	with normal completion.

	      pattern_match
		     Locally controls the behaviour given by the GLOB_COMPLETE
		     option.  Initially	it is set to `*' if and	 only  if  the
		     option  is	set.  The completion widget may	set it to this
		     value, to an empty	string (which has the same  effect  as
		     unsetting	it),  or to any	other non-empty	string.	 If it
		     is	non-empty, unquoted metacharacters on the command line
		     will be treated as	patterns; if it	is `*',	then addition-
		     ally a wildcard `*' is assumed at the cursor position; if
		     it	is empty or unset, metacharacters will be treated lit-
		     erally.

		     Note that the matcher specifications given	to the compadd
		     builtin  command  are  not	 used  if  this	 is  set  to a
		     non-empty string.

	      quote  When completing inside quotes, this contains  the	quota-
		     tion  character  (i.e.  either  a	single quote, a	double
		     quote, or a backtick).  Otherwise it is unset.

	      quoting
		     When completing inside single quotes, this	is set to  the
		     string  single;  inside double quotes, the	string double;
		     inside backticks, the string backtick.  Otherwise	it  is
		     unset.

	      redirect
		     The redirection operator when completing in a redirection
		     position, i.e. one	of <, >, etc.

	      restore
		     This is set to auto before	a function is  entered,	 which
		     forces  the  special  parameters  mentioned above (words,
		     CURRENT, PREFIX, IPREFIX, SUFFIX, and ISUFFIX) to be  re-
		     stored  to	their previous values when the function	exits.
		     If	a function unsets it or	sets it	to any	other  string,
		     they will not be restored.

	      to_end Specifies	the  occasions on which	the cursor is moved to
		     the end of	a string when a	match is inserted.   On	 entry
		     to	 a widget function, it may be single if	this will hap-
		     pen when a	single unambiguous match was inserted or match
		     if	it will	happen any time	a match	is inserted (for exam-
		     ple, by menu completion; this is likely to	be the	effect
		     of	the ALWAYS_TO_END option).

		     On	 exit,	it may be set to single	as above.  It may also
		     be	set to always, or to the empty	string	or  unset;  in
		     those  cases  the	cursor will be moved to	the end	of the
		     string always or never respectively.  Any other string is
		     treated as	match.

	      unambiguous
		     This  key is read-only and	will always be set to the com-
		     mon (unambiguous) prefix the completion code  has	gener-
		     ated for all matches added	so far.

	      unambiguous_cursor
		     This  gives the position the cursor would be placed at if
		     the common	prefix in the unambiguous key  were  inserted,
		     relative  to  the	value of that key. The cursor would be
		     placed before the character whose index is	given by  this
		     key.

	      unambiguous_positions
		     This contains all positions where characters in the unam-
		     biguous string are	missing	or  where  the	character  in-
		     serted differs from at least one of the matches.  The po-
		     sitions are given as indexes into the string given	by the
		     value of the unambiguous key.

	      vared  If	 completion  is	 called	while editing a	line using the
		     vared builtin, the	value of this key is set to  the  name
		     of	the parameter given as an argument to vared.  This key
		     is	only set while a vared command is active.

       words  This array contains the words present on the command  line  cur-
	      rently being edited.

COMPLETION BUILTIN COMMANDS
       compadd [ -akqQfenUlo12C	] [ -F array ]
	       [-P prefix ] [ -S suffix	]
	       [-p hidden-prefix ] [ -s	hidden-suffix ]
	       [-i ignored-prefix ] [ -I ignored-suffix	]
	       [-W file-prefix ] [ -d array ]
	       [-J name	] [ -V name ] [	-X explanation ] [ -x message ]
	       [-r remove-chars	] [ -R remove-func ]
	       [-D array ] [ -O	array ]	[ -A array ]
	       [-E number ]
	       [-M match-spec ]	[ -- ] [ words ... ]

	      This  builtin  command  can  be used to add matches directly and
	      control all the information the completion code stores with each
	      possible	match. The return status is zero if at least one match
	      was added	and non-zero if	no matches were	added.

	      The completion code breaks the string  to	 complete  into	 seven
	      fields in	the order:

		     _ipre__apre__hpre__word__hsuf__asuf__isuf_

	      The  first  field	 is  an	 ignored prefix	taken from the command
	      line, the	contents of the	 IPREFIX  parameter  plus  the	string
	      given  with  the	-i option. With	the -U option, only the	string
	      from the -i option is used. The field _apre_ is an optional pre-
	      fix  string  given  with	the  -P	option.	 The _hpre_ field is a
	      string that is considered	part of	the match but that should  not
	      be shown when listing completions, given with the	-p option; for
	      example, functions that do filename generation might  specify  a
	      common  path  prefix  this way.  _word_ is the part of the match
	      that should appear in the	list of	completions, i.e. one  of  the
	      words given at the end of	the compadd command line. The suffixes
	      _hsuf_, _asuf_ and _isuf_	correspond  to	the  prefixes  _hpre_,
	      _apre_  and  _ipre_  and are given by the	options	-s, -S and -I,
	      respectively.

	      The supported flags are:

	      -P prefix
		     This gives	a string  to  be  inserted  before  the	 given
		     words.  The string	given is not considered	as part	of the
		     match and any shell metacharacters	 in  it	 will  not  be
		     quoted when the string is inserted.

	      -S suffix
		     Like  -P,	but  gives  a  string to be inserted after the
		     match.

	      -p hidden-prefix
		     This gives	a string that should be	inserted into the com-
		     mand  line	before the match but that should not appear in
		     the list of matches. Unless the -U	option is given,  this
		     string  must be matched as	part of	the string on the com-
		     mand line.

	      -s hidden-suffix
		     Like `-p',	but gives a string to insert after the match.

	      -i ignored-prefix
		     This gives	a string to insert into	the command line  just
		     before  any  string  given	with the `-P' option.  Without
		     `-P' the string is	inserted before	the string given  with
		     `-p' or directly before the match.

	      -I ignored-suffix
		     Like -i, but gives	an ignored suffix.

	      -a     With this flag the	words are taken	as names of arrays and
		     the possible matches are their values.  If	only some ele-
		     ments  of	the arrays are needed, the words may also con-
		     tain subscripts, as in `foo[2,-1]'.

	      -k     With this flag the	words are taken	as names  of  associa-
		     tive  arrays and the possible matches are their keys.  As
		     for -a, the words may  also  contain  subscripts,	as  in
		     `foo[(R)*bar*]'.

	      -d array
		     This  adds	 per-match  display  strings. The array	should
		     contain one element per word given. The  completion  code
		     will  then	display	the first element instead of the first
		     word, and so on. The array	may be given as	the name of an
		     array  parameter or directly as a space-separated list of
		     words in parentheses.

		     If	there are fewer	display	strings	than words, the	 left-
		     over  words  will be displayed unchanged and if there are
		     more display strings than	words,	the  leftover  display
		     strings will be silently ignored.

	      -l     This  option only has an effect if	used together with the
		     -d	option.	If it is given,	the display strings are	listed
		     one per line, not arrayed in columns.

	      -o     This  option only has an effect if	used together with the
		     -d	option.	 If it is given, the order of  the  output  is
		     determined	 by the	match strings;	otherwise it is	deter-
		     mined by the display strings (i.e.	the strings  given  by
		     the -d option).

	      -J name
		     Gives  the	 name of the group of matches the words	should
		     be	stored in.

	      -V name
		     Like -J but naming	an unsorted group. These are in	a dif-
		     ferent name space than groups created with	the -J flag.

	      -1     If	given together with the	-V option, makes only consecu-
		     tive duplicates in	the group be removed. If combined with
		     the  -J  option,  this  has  no visible effect. Note that
		     groups with and without this flag are in  different  name
		     spaces.

	      -2     If	given together with the	-J or -V option, makes all du-
		     plicates be kept. Again, groups  with  and	 without  this
		     flag are in different name	spaces.

	      -X explanation
		     The  explanation  string will be printed with the list of
		     matches, above the	group currently	selected.

	      -x message
		     Like -X, but the message will be printed  even  if	 there
		     are no matches in the group.

	      -q     The suffix	given with -S will be automatically removed if
		     the next character	typed is a blank or  does  not	insert
		     anything, or if the suffix	consists of only one character
		     and the next character typed is the same character.

	      -r remove-chars
		     This is a more versatile form of the -q option.  The suf-
		     fix  given	with -S	or the slash automatically added after
		     completing	directories will be automatically  removed  if
		     the  next	character  typed inserts one of	the characters
		     given in the remove-chars.	 This string is	 parsed	 as  a
		     characters	 class and understands the backslash sequences
		     used by the print command.	 For example, `-r "a-z\t"' re-
		     moves  the	 suffix	 if the	next character typed inserts a
		     lower case	character or a TAB, and	 `-r  "^0-9"'  removes
		     the  suffix  if the next character	typed inserts anything
		     but a digit. One extra backslash sequence	is  understood
		     in	 this  string: `\-' stands for all characters that in-
		     sert nothing. Thus	`-S "="	-q' is the same	as `-S "="  -r
		     "=	\t\n\-"'.

		     This  option may also be used without the -S option; then
		     any automatically added space will	be removed when	one of
		     the characters in the list	is typed.

	      -R remove-func
		     This  is another form of the -r option. When a suffix has
		     been inserted and the completion accepted,	 the  function
		     remove-func  will	be  called  after  the	next character
		     typed.  It	is passed the length of	the suffix as an argu-
		     ment  and can use the special parameters available	in or-
		     dinary (non-completion) zle widgets  (see	zshzle(1))  to
		     analyse and modify	the command line.

	      -f     If	 this  flag  is	 given,	 all of	the matches built from
		     words are marked as being the names of files.   They  are
		     not required to be	actual filenames, but if they are, and
		     the option	LIST_TYPES is set, the	characters  describing
		     the  types	 of  the files in the completion lists will be
		     shown. This also forces a slash to	be added when the name
		     of	a directory is completed.

	      -e     This  flag	 can  be used to tell the completion code that
		     the matches added are parameter names for a parameter ex-
		     pansion.	This   will   make  the	 AUTO_PARAM_SLASH  and
		     AUTO_PARAM_KEYS options be	used for the matches.

	      -W file-prefix
		     This string is a pathname that will be prepended to  each
		     of	 the  matches  formed by the given words together with
		     any prefix	specified by the -p option to form a  complete
		     filename  for  testing.   Hence it	is only	useful if com-
		     bined with	the -f flag, as	the tests will	not  otherwise
		     be	performed.

	      -F array
		     Specifies	an  array  containing patterns.	Words matching
		     one of these patterns are ignored,	i.e. not considered to
		     be	possible matches.

		     The array may be the name of an array parameter or	a list
		     of	literal	patterns enclosed in parentheses  and  quoted,
		     as	 in  `-F  "(*?.o  *?.h)"'.  If the name	of an array is
		     given, the	elements of the	array are taken	 as  the  pat-
		     terns.

	      -Q     This  flag	instructs the completion code not to quote any
		     metacharacters in the words when inserting	them into  the
		     command line.

	      -M match-spec
		     This  gives local match specifications as described below
		     in	the section `Completion	Matching Control'. This	option
		     may   be	given  more  than  once.   In  this  case  all
		     match-specs given are concatenated	 with  spaces  between
		     them  to form the specification string to use.  Note that
		     they will only be used if the -U option is	not given.

	      -n     Specifies that the	words added are	to be used as possible
		     matches, but are not to appear in the completion listing.

	      -U     If	 this  flag is given, all words	given will be accepted
		     and no matching will be done by the completion code. Nor-
		     mally  this  is  used  in	functions that do the matching
		     themselves.

	      -O array
		     If	this option is given, the words	are not	added  to  the
		     set  of  possible completions.  Instead, matching is done
		     as	usual and all of the words  given  as  arguments  that
		     match  the	 string	 on the	command	line will be stored in
		     the array parameter whose name is given as	array.

	      -A array
		     As	the -O option, except that instead  of	those  of  the
		     words which match being stored in array, the strings gen-
		     erated internally by the completion code are stored.  For
		     example,  with a matching specification of	`-M "L:|no="',
		     the string	`nof' on the command line and the string `foo'
		     as	 one  of the words, this option	stores the string `no-
		     foo' in the array,	whereas	the -O option stores the `foo'
		     originally	given.

	      -D array
		     As	 with -O, the words are	not added to the set of	possi-
		     ble completions.	Instead,  the  completion  code	 tests
		     whether  each  word  in turn matches what is on the line.
		     If	the nth	word does not match, the nth  element  of  the
		     array  is	removed.  Elements for which the corresponding
		     word is matched are retained.

	      -C     This option adds a	special	match  which  expands  to  all
		     other  matches  when  inserted  into the line, even those
		     that are added after this option is used.	Together  with
		     the  -d  option  it  is possible to specify a string that
		     should be displayed in the	list for this  special	match.
		     If	 no string is given, it	will be	shown as a string con-
		     taining the strings that would be inserted	for the	 other
		     matches, truncated	to the width of	the screen.

	      -E number
		     This  option  adds	 number	 empty matches after the words
		     have been added.  An empty	match takes up space  in  com-
		     pletion  listings	but will never be inserted in the line
		     and can't be selected with	menu completion	or menu	selec-
		     tion.   This  makes  empty	 matches only useful to	format
		     completion	lists and to make explanatory string be	 shown
		     in	 completion  lists  (since  empty matches can be given
		     display strings with the -d option).  And because all but
		     one  empty	string would otherwise be removed, this	option
		     implies the -V and	-2 options (even if an explicit	-J op-
		     tion  is given).  This can	be important to	note as	it af-
		     fects the name space into which matches are added.

	      -
	      --     This flag ends the	list of	flags and options.  All	 argu-
		     ments  after  it  will  be	 taken	as the words to	use as
		     matches even if they begin	with hyphens.

	      Except for the -M	flag, if any of	these flags is given more than
	      once, the	first one (and its argument) will be used.

       compset -p number
       compset -P [ number ] pattern
       compset -s number
       compset -S [ number ] pattern
       compset -n begin	[ end ]
       compset -N beg-pat [ end-pat ]
       compset -q
	      This  command simplifies modification of the special parameters,
	      while its	return status allows tests on them to be carried out.

	      The options are:

	      -p number
		     If	the contents of	the PREFIX parameter  is  longer  than
		     number  characters,  the  first number characters are re-
		     moved from	it and appended	to the contents	of the IPREFIX
		     parameter.

	      -P [ number ] pattern
		     If	the value of the PREFIX	parameter begins with anything
		     that matches the pattern, the matched portion is  removed
		     from PREFIX and appended to IPREFIX.

		     Without  the optional number, the longest match is	taken,
		     but if number is given, anything up to the	numberth match
		     is	 moved.	 If the	number is negative, the	numberth long-
		     est match is moved. For example, if PREFIX	 contains  the
		     string  `a=b=c',  then  compset  -P  '*\='	 will move the
		     string `a=b=' into	the IPREFIX parameter, but compset  -P
		     1 '*\=' will move only the	string `a='.

	      -s number
		     As	 -p,  but transfer the last number characters from the
		     value of SUFFIX to	the front of the value of ISUFFIX.

	      -S [ number ] pattern
		     As	-P, but	match the last portion of SUFFIX and  transfer
		     the matched portion to the	front of the value of ISUFFIX.

	      -n begin [ end ]
		     If	 the current word position as specified	by the parame-
		     ter CURRENT is greater than or equal to  begin,  anything
		     up	 to  the  beginth word is removed from the words array
		     and the value of the parameter CURRENT is decremented  by
		     begin.

		     If	 the  optional	end is given, the modification is done
		     only if the current word position is also	less  than  or
		     equal  to	end. In	this case, the words from position end
		     onwards are also removed from the words array.

		     Both begin	and end	may be	negative  to  count  backwards
		     from the last element of the words	array.

	      -N beg-pat [ end-pat ]
		     If	 one of	the elements of	the words array	before the one
		     at	the index given	by the value of	the parameter  CURRENT
		     matches  the  pattern beg-pat, all	elements up to and in-
		     cluding the matching one are removed from the words array
		     and  the value of CURRENT is changed to point to the same
		     word in the changed array.

		     If	the optional pattern end-pat is	also given, and	 there
		     is	 an  element in	the words array	matching this pattern,
		     the parameters are	modified only if  the  index  of  this
		     word  is higher than the one given	by the CURRENT parame-
		     ter (so that the matching word has	to be after  the  cur-
		     sor).  In	this  case,  the  words	 starting with the one
		     matching end-pat are also removed from the	 words	array.
		     If	 words	contains no word matching end-pat, the testing
		     and modification is performed as if it were not given.

	      -q     The word currently	being completed	 is  split  on	spaces
		     into  separate  words, respecting the usual shell quoting
		     conventions.  The resulting words are stored in the words
		     array,  and CURRENT, PREFIX, SUFFIX, QIPREFIX, and	QISUF-
		     FIX are modified to reflect the word part	that  is  com-
		     pleted.

	      In  all  the  above  cases the return status is zero if the test
	      succeeded	and the	parameters were	modified and  non-zero	other-
	      wise. This allows	one to use this	builtin	in tests such as:

		     if	compset	-P '*\='; then ...

	      This  forces anything up to and including	the last equal sign to
	      be ignored by the	completion code.

       compcall	[ -TD ]
	      This allows the use of  completions  defined  with  the  compctl
	      builtin  from  within  completion	 widgets.  The list of matches
	      will be generated	as if one of the non-widget  completion	 func-
	      tions  (complete-word,  etc.)  had been called, except that only
	      compctls given for specific commands are used. To	force the code
	      to  try completions defined with the -T option of	compctl	and/or
	      the default completion (whether defined by  compctl  -D  or  the
	      builtin  default)	 in  the  appropriate places, the -T and/or -D
	      flags can	be passed to compcall.

	      The return status	can be used to test if a matching compctl def-
	      inition  was  found.  It	is non-zero if a compctl was found and
	      zero otherwise.

	      Note that	this builtin is	defined	by the zsh/compctl module.

COMPLETION CONDITION CODES
       The following additional	condition codes	for use	within the [[  ...  ]]
       construct  are available	in completion widgets.	These work on the spe-
       cial parameters.	 All of	these tests  can  also	be  performed  by  the
       compset builtin,	but in the case	of the condition codes the contents of
       the special parameters are not modified.

       -prefix [ number	] pattern
	      true if the test for the -P option of compset would succeed.

       -suffix [ number	] pattern
	      true if the test for the -S option of compset would succeed.

       -after beg-pat
	      true if the test of the -N option	with only  the	beg-pat	 given
	      would succeed.

       -between	beg-pat	end-pat
	      true if the test for the -N option with both patterns would suc-
	      ceed.

COMPLETION MATCHING CONTROL
       It is possible by use of	the -M option of the compadd  builtin  command
       to  specify  how	the characters in the string to	be completed (referred
       to here as the command line) map	onto the characters  in	 the  list  of
       matches	produced by the	completion code	(referred to here as the trial
       completions). Note that this is not used	if the command line contains a
       glob  pattern  and the GLOB_COMPLETE option is set or the pattern_match
       of the compstate	special	association is set to a	non-empty string.

       The match-spec given as the argument to the -M option (see  `Completion
       Builtin	Commands' above) consists of one or more matching descriptions
       separated by whitespace.	 Each description consists of  a  letter  fol-
       lowed  by  a colon and then the patterns	describing which character se-
       quences on the line match which character sequences in the  trial  com-
       pletion.	  Any  sequence	of characters not handled in this fashion must
       match exactly, as usual.

       The forms of match-spec understood are as follows. In  each  case,  the
       form  with  an  upper case initial character retains the	string already
       typed on	the command line as the	final result of	completion, while with
       a  lower	 case  initial	character  the	string	on the command line is
       changed into the	corresponding part of the trial	completion.

       m:lpat=tpat
       M:lpat=tpat
	      Here, lpat is a pattern that matches on the command line,	corre-
	      sponding to tpat which matches in	the trial completion.

       l:lanchor|lpat=tpat
       L:lanchor|lpat=tpat
       l:lanchor||ranchor=tpat
       L:lanchor||ranchor=tpat
       b:lpat=tpat
       B:lpat=tpat
	      These letters are	for patterns that are anchored by another pat-
	      tern on the left side. Matching for lpat and tpat	is  as	for  m
	      and  M, but the pattern lpat matched on the command line must be
	      preceded by the pattern lanchor.	The lanchor can	 be  blank  to
	      anchor the match to the start of the command line	string;	other-
	      wise the anchor can occur	anywhere, but must match in  both  the
	      command line and trial completion	strings.

	      If  no  lpat is given but	a ranchor is, this matches the gap be-
	      tween substrings matched by lanchor and ranchor. Unlike lanchor,
	      the ranchor only needs to	match the trial	completion string.

	      The  b  and B forms are similar to l and L with an empty anchor,
	      but need to match	only the beginning of the word on the  command
	      line or trial completion,	respectively.

       r:lpat|ranchor=tpat
       R:lpat|ranchor=tpat
       r:lanchor||ranchor=tpat
       R:lanchor||ranchor=tpat
       e:lpat=tpat
       E:lpat=tpat
	      As  l, L,	b and B, with the difference that the command line and
	      trial completion patterns	are anchored on	the right side.	  Here
	      an  empty	 ranchor  and the e and	E forms	force the match	to the
	      end of the command line or trial completion string.

       x:     This form	is used	to mark	the end	 of  matching  specifications:
	      subsequent  specifications  are  ignored.	In a single standalone
	      list of specifications this has no use but where matching	speci-
	      fications	 are  accumulated, such	as from	nested function	calls,
	      it can allow one function	to override another.

       Each lpat, tpat or anchor is either an empty string or  consists	 of  a
       sequence	 of literal characters (which may be quoted with a backslash),
       question	marks, character classes, and correspondence classes; ordinary
       shell patterns are not used.  Literal characters	match only themselves,
       question	marks match any	character, and character classes are formed as
       for globbing and	match any character in the given set.

       Correspondence classes are defined like character classes, but with two
       differences: they are delimited	by  a  pair  of	 braces,  and  negated
       classes	are  not  allowed,  so	the characters ! and ^ have no special
       meaning directly	after the opening brace.  They indicate	that  a	 range
       of characters on	the line match a range of characters in	the trial com-
       pletion,	but (unlike ordinary character classes)	 paired	 according  to
       the  corresponding  position in the sequence.  For example, to make any
       ASCII lower case	letter on the line match the corresponding upper  case
       letter  in  the trial completion, you can use `m:{a-z}={A-Z}' (however,
       see below for the recommended form for this).  More than	 one  pair  of
       classes	can  occur,  in	which case the first class before the =	corre-
       sponds to the first after it, and so on.	 If one	 side  has  more  such
       classes than the	other side, the	superfluous classes behave like	normal
       character classes.  In anchor patterns correspondence classes also  be-
       have like normal	character classes.

       The  standard  `[:name:]'  forms	 described for standard	shell patterns
       (see the	section	FILENAME GENERATION in zshexpn(1)) may appear in  cor-
       respondence classes as well as normal character classes.	 The only spe-
       cial behaviour in correspondence	classes	is if the form on the left and
       the  form  on the right are each	one of [:upper:], [:lower:].  In these
       cases the character in the word and the character on the	line  must  be
       the  same  up  to  a  difference	in case.  Hence	to make	any lower case
       character on the	line match the corresponding upper case	 character  in
       the trial completion you	can use	`m:{[:lower:]}={[:upper:]}'.  Although
       the matching system does	not yet	handle multibyte characters,  this  is
       likely to be a future extension,	at which point this syntax will	handle
       arbitrary alphabets; hence this form, rather than the use  of  explicit
       ranges,	is  the	recommended form.  In other cases `[:name:]' forms are
       allowed.	 If the	two forms on the left and  right  are  the  same,  the
       characters  must	 match exactly.	 In remaining cases, the corresponding
       tests are applied to both characters, but they are not  otherwise  con-
       strained;  any  matching	 character  in	one set	goes with any matching
       character in the	other set:  this is equivalent to the behaviour	of or-
       dinary character	classes.

       The  pattern tpat may also be one or two	stars, `*' or `**'. This means
       that the	pattern	on the command line can	match any number of characters
       in  the trial completion. In this case the pattern must be anchored (on
       either side); in	the case of a single star, the anchor then  determines
       how  much of the	trial completion is to be included -- only the charac-
       ters up to the next appearance of the anchor will be matched. With  two
       stars, substrings matched by the	anchor can be matched, too.

       Examples:

       The keys	of the options association defined by the parameter module are
       the option names	in all-lower-case form,	without	underscores, and with-
       out  the	 optional  no at the beginning even though the builtins	setopt
       and unsetopt understand option names with upper	case  letters,	under-
       scores,	and  the optional no.  The following alters the	matching rules
       so that the prefix no and any underscore	are  ignored  when  trying  to
       match  the  trial  completions  generated and upper case	letters	on the
       line match the corresponding lower case letters in the words:

	      compadd -M 'L:|[nN][oO]= M:_= M:{[:upper:]}={[:lower:]}' - \
		${(k)options}

       The first part says that	the pattern `[nN][oO]' at the  beginning  (the
       empty  anchor before the	pipe symbol) of	the string on the line matches
       the empty string	in the list of words generated by  completion,	so  it
       will be ignored if present. The second part does	the same for an	under-
       score anywhere in the command line string, and the third	part uses cor-
       respondence  classes  so	that any upper case letter on the line matches
       the corresponding lower case letter in the word.	The use	of  the	 upper
       case  forms  of	the specification characters (L	and M) guarantees that
       what has	already	been typed on the command line (in particular the pre-
       fix no) will not	be deleted.

       Note  that  the	use  of	L in the first part means that it matches only
       when at the beginning of	both the command line  string  and  the	 trial
       completion.  I.e.,  the	string	`_NO_f'	 would	not  be	 completed  to
       `_NO_foo', nor would `NONO_f' be	completed to `NONO_foo'	because	of the
       leading	underscore or the second `NO' on the line which	makes the pat-
       tern fail even though they are otherwise	 ignored.  To  fix  this,  one
       would  use `B:[nN][oO]='	instead	of the first part. As described	above,
       this matches at the beginning of	the trial completion,  independent  of
       other  characters  or  substrings  at the beginning of the command line
       word which are ignored by the same or other match-specs.

       The second example makes	completion case	insensitive.  This is just the
       same  as	in the option example, except here we wish to retain the char-
       acters in the list of completions:

	      compadd -M 'm:{[:lower:]}={[:upper:]}' ...

       This makes lower	case letters match their upper case counterparts.   To
       make upper case letters match the lower case forms as well:

	      compadd -M 'm:{[:lower:][:upper:]}={[:upper:][:lower:]}' ...

       A  nice	example	 for the use of	* patterns is partial word completion.
       Sometimes you would like	to  make  strings  like	 `c.s.u'  complete  to
       strings like `comp.source.unix',	i.e. the word on the command line con-
       sists of	multiple parts,	separated by a dot in this example, where each
       part  should  be	 completed  separately -- note,	however, that the case
       where each part of the word, i.e. `comp', `source' and `unix'  in  this
       example,	 is to be completed from separate sets of matches is a differ-
       ent problem to be solved	by the implementation of the  completion  wid-
       get.  The example can be	handled	by:

	      compadd -M 'r:|.=* r:|=*'	\
		- comp.sources.unix comp.sources.misc ...

       The  first  specification says that lpat	is the empty string, while an-
       chor is a dot; tpat is *, so this can match anything except for the `.'
       from  the  anchor  in  the  trial  completion word.  So in `c.s.u', the
       matcher sees `c', followed by the empty string, followed	by the	anchor
       `.',  and  likewise  for	the second dot,	and replaces the empty strings
       before the anchors, giving `c[omp].s[ources].u[nix]',  where  the  last
       part of the completion is just as normal.

       With  the  pattern shown	above, the string `c.u'	could not be completed
       to `comp.sources.unix' because  the  single  star  means	 that  no  dot
       (matched	 by  the  anchor)  can	be  skipped.  By using two stars as in
       `r:|.=**', however, `c.u' could be  completed  to  `comp.sources.unix'.
       This  also shows	that in	some cases, especially if the anchor is	a real
       pattern,	like a character class,	the form with two stars	may result  in
       more matches than one would like.

       The second specification	is needed to make this work when the cursor is
       in the middle of	the string on the command line	and  the  option  COM-
       PLETE_IN_WORD  is  set. In this case the	completion code	would normally
       try to match trial completions that end with the	 string	 as  typed  so
       far,  i.e.  it  will  only insert new characters	at the cursor position
       rather than at the end.	However	in our example we would	like the  code
       to recognise matches which contain extra	characters after the string on
       the line	(the `nix' in the example).   Hence  we	 say  that  the	 empty
       string  at  the end of the string on the	line matches any characters at
       the end of the trial completion.

       More generally, the specification

	      compadd -M 'r:|[.,_-]=* r:|=*' ...

       allows one to complete words with abbreviations before any of the char-
       acters  in the square brackets.	For example, to	complete veryverylong-
       file.c rather than veryverylongheader.h with the	above in  effect,  you
       can just	type very.c before attempting completion.

       The  specifications  with  both a left and a right anchor are useful to
       complete	partial	words whose parts are not separated  by	 some  special
       character.  For	example,  in  some places strings have to be completed
       that are	formed `LikeThis' (i.e.	the separate parts are determined by a
       leading	upper  case  letter) or	maybe one has to complete strings with
       trailing	numbers. Here one could	use the	simple form with only one  an-
       chor as in:

	      compadd -M 'r:|[[:upper:]0-9]=* r:|=*' LikeTHIS FooHoo 5foo123 5bar234

       But with	this, the string `H' would neither complete to `FooHoo'	nor to
       `LikeTHIS' because in each case there is	an upper  case	letter	before
       the `H' and that	is matched by the anchor. Likewise, a `2' would	not be
       completed. In both cases	this could  be	changed	 by  using  `r:|[[:up-
       per:]0-9]=**',  but  then `H' completes to both `LikeTHIS' and `FooHoo'
       and a `2' matches the other strings because characters can be  inserted
       before every upper case letter and digit. To avoid this one would use:

	      compadd -M 'r:[^[:upper:]0-9]||[[:upper:]0-9]=** r:|=*' \
		  LikeTHIS FooHoo foo123 bar234

       By using	these two anchors, a `H' matches only upper case `H's that are
       immediately preceded by something matching  the	left  anchor  `[^[:up-
       per:]0-9]'.  The	effect is, of course, that `H' matches only the	string
       `FooHoo', a `2' matches only `bar234' and so on.

       When using the completion system	(see zshcompsys(1)), users can	define
       match specifications that are to	be used	for specific contexts by using
       the matcher and matcher-list styles. The	values for the latter will  be
       used everywhere.

COMPLETION WIDGET EXAMPLE
       The first step is to define the widget:

	      zle -C complete complete-word complete-files

       Then  the  widget  can be bound to a key	using the bindkey builtin com-
       mand:

	      bindkey '^X\t' complete

       After that the shell function complete-files will be invoked after typ-
       ing  control-X  and TAB.	The function should then generate the matches,
       e.g.:

	      complete-files ()	{ compadd - * }

       This function will complete files in the	current	directory matching the
       current word.

ZSHCOMPSYS(1)		    General Commands Manual		 ZSHCOMPSYS(1)

NAME
       zshcompsys - zsh	completion system

DESCRIPTION
       This describes the shell	code for the `new' completion system, referred
       to as compsys.  It is written in	shell functions	based on the  features
       described in zshcompwid(1).

       The features are	contextual, sensitive to the point at which completion
       is started.  Many completions are already provided.  For	this reason, a
       user  can perform a great many tasks without knowing any	details	beyond
       how to initialize the system, which is described	below  in  INITIALIZA-
       TION.

       The context that	decides	what completion	is to be performed may be
       o      an  argument  or option position:	these describe the position on
	      the command line at which	completion is requested.  For  example
	      `first  argument	to rmdir, the word being completed names a di-
	      rectory';

       o      a	special	context, denoting an element in	 the  shell's  syntax.
	      For  example  `a	word  in  command  position' or	`an array sub-
	      script'.

       A full context specification contains other elements, as	we  shall  de-
       scribe.

       Besides	commands  names	and contexts, the system employs two more con-
       cepts, styles and tags.	These provide ways for the user	 to  configure
       the system's behaviour.

       Tags  play  a dual role.	 They serve as a classification	system for the
       matches,	typically indicating a class of	object that the	user may  need
       to  distinguish.	 For example, when completing arguments	of the ls com-
       mand the	user may prefer	to try files before directories,  so  both  of
       these are tags.	They also appear as the	rightmost element in a context
       specification.

       Styles modify various operations	of the completion system, such as out-
       put formatting, but also	what kinds of completers are used (and in what
       order), or which	tags are examined.  Styles may	accept	arguments  and
       are  manipulated	 using	the  zstyle  command  described	in see zshmod-
       ules(1).

       In summary, tags	describe what the completion objects  are,  and	 style
       how they	are to be completed.  At various points	of execution, the com-
       pletion system checks what styles and/or	tags are defined for the  cur-
       rent  context, and uses that to modify its behavior.  The full descrip-
       tion of context handling, which determines how tags and other  elements
       of the context influence	the behaviour of styles, is described below in
       COMPLETION SYSTEM CONFIGURATION.

       When a completion is requested, a dispatcher function  is  called;  see
       the  description	of _main_complete in the list of control functions be-
       low. This dispatcher decides which function should be called to produce
       the completions,	and calls it. The result is passed to one or more com-
       pleters,	functions that	implement  individual  completion  strategies:
       simple  completion, error correction, completion	with error correction,
       menu selection, etc.

       More generally, the shell functions contained in	the completion	system
       are of two types:
       o      those beginning `comp' are to be called directly;	there are only
	      a	few of these;

       o      those beginning `_' are called  by  the  completion  code.   The
	      shell  functions	of this	set, which implement completion	behav-
	      iour and may be bound to keystrokes, are referred	 to  as	 `wid-
	      gets'.  These proliferate	as new completions are required.

INITIALIZATION
       If the system was installed completely, it should be enough to call the
       shell function compinit from your initialization	 file;	see  the  next
       section.	  However,  the	 function  compinstall can be run by a user to
       configure various aspects of the	completion system.

       Usually,	compinstall will insert	code into .zshrc, although if that  is
       not  writable  it will save it in another file and tell you that	file's
       location.  Note that it is up to	you to make sure that the lines	 added
       to  .zshrc are actually run; you	may, for example, need to move them to
       an earlier place	in the file if .zshrc usually returns early.  So  long
       as you keep them	all together (including	the comment lines at the start
       and finish), you	can rerun compinstall and it will correctly locate and
       modify  these lines.  Note, however, that any code you add to this sec-
       tion by hand is likely to be lost if you	 rerun	compinstall,  although
       lines using the command `zstyle'	should be gracefully handled.

       The  new	 code  will  take effect next time you start the shell,	or run
       .zshrc by hand; there is	also an	option to make them take effect	 imme-
       diately.	  However,  if	compinstall  has removed definitions, you will
       need to restart the shell to see	the changes.

       To run compinstall you will need	to make	sure it	is in a	directory men-
       tioned in your fpath parameter, which should already be the case	if zsh
       was properly configured as long as your startup files do	not remove the
       appropriate  directories	 from fpath.  Then it must be autoloaded (`au-
       toload -U compinstall' is recommended).	You can	abort the installation
       any  time  you are being	prompted for information, and your .zshrc will
       not be altered at all; changes only take	place right at the end,	 where
       you are specifically asked for confirmation.

   Use of compinit
       This section describes the use of compinit to initialize	completion for
       the current session when	called directly; if you	have  run  compinstall
       it will be called automatically from your .zshrc.

       To  initialize  the system, the function	compinit should	be in a	direc-
       tory mentioned in the fpath parameter, and should be  autoloaded	 (`au-
       toload -U compinit' is recommended), and	then run simply	as `compinit'.
       This will define	a few utility functions, arrange for all the necessary
       shell  functions	 to be autoloaded, and will then re-define all widgets
       that do completion to use the new system.  If you use  the  menu-select
       widget,	which is part of the zsh/complist module, you should make sure
       that that module	is loaded before the call to  compinit	so  that  that
       widget is also re-defined.  If completion styles	(see below) are	set up
       to perform expansion as well as completion by default, and the TAB  key
       is  bound  to  expand-or-complete,  compinit  will  rebind  it  to com-
       plete-word; this	is necessary to	use the	correct	form of	expansion.

       Should you need to use the original completion commands,	you can	 still
       bind  keys  to  the old widgets by putting a `.'	in front of the	widget
       name, e.g. `.expand-or-complete'.

       To speed	up the running of compinit, it can be made to produce a	dumped
       configuration  that  will be read in on future invocations; this	is the
       default,	but can	be turned off by calling compinit with the option  -D.
       The  dumped  file  is  .zcompdump  in the same directory	as the startup
       files (i.e. $ZDOTDIR or $HOME); alternatively, an  explicit  file  name
       can  be	given  by  `compinit  -d  dumpfile'.   The  next invocation of
       compinit	will read the dumped file instead of performing	 a  full  ini-
       tialization.

       If the number of	completion files changes, compinit will	recognise this
       and produce a new dump file.  However, if the name of a function	or the
       arguments in the	first line of a	#compdef function (as described	below)
       change, it is easiest to	delete the dump	file by	hand so	that  compinit
       will  re-create it the next time	it is run.  The	check performed	to see
       if there	are new	functions can be omitted by giving the option -C.   In
       this  case  the	dump  file will	only be	created	if there isn't one al-
       ready.

       The dumping is actually done by another	function,  compdump,  but  you
       will  only  need	 to  run this yourself if you change the configuration
       (e.g. using compdef) and	then want to dump the new one.	 The  name  of
       the old dumped file will	be remembered for this purpose.

       If the parameter	_compdir is set, compinit uses it as a directory where
       completion functions can	be found; this is only necessary if  they  are
       not already in the function search path.

       For  security  reasons  compinit	 also  checks if the completion	system
       would use files not owned by root or by the current user, or  files  in
       directories  that are world- or group-writable or that are not owned by
       root or by the current user.  If	such files or directories  are	found,
       compinit	 will  ask if the completion system should really be used.  To
       avoid these tests and make all files found be used without asking,  use
       the  option -u, and to make compinit silently ignore all	insecure files
       and directories use the option -i.  This	security check is skipped  en-
       tirely when the -C option is given.

       The  security  check can	be retried at any time by running the function
       compaudit.  This	is the same check used by compinit, but	when it	is ex-
       ecuted  directly	any changes to fpath are made local to the function so
       they do not persist.  The directories to	be checked may	be  passed  as
       arguments; if none are given, compaudit uses fpath and _compdir to find
       completion system directories, adding missing ones to fpath  as	neces-
       sary.   To  force a check of exactly the	directories currently named in
       fpath, set _compdir to an empty	string	before	calling	 compaudit  or
       compinit.

       The  function  bashcompinit provides compatibility with bash's program-
       mable completion	system.	 When run it will define the functions,	 comp-
       gen  and	 complete  which correspond to the bash	builtins with the same
       names.  It will then be possible	to use completion  specifications  and
       functions written for bash.

   Autoloaded files
       The convention for autoloaded functions used in completion is that they
       start with an underscore; as already mentioned, the fpath/FPATH parame-
       ter  must  contain  the directory in which they are stored.  If zsh was
       properly	installed on your system, then fpath/FPATH automatically  con-
       tains the required directories for the standard functions.

       For  incomplete	installations,	if compinit does not find enough files
       beginning with an underscore (fewer than	twenty)	in the search path, it
       will  try  to  find more	by adding the directory	_compdir to the	search
       path.  If that directory	has a subdirectory named Base, all subdirecto-
       ries  will be added to the path.	 Furthermore, if the subdirectory Base
       has a subdirectory named	Core, compinit will add	all subdirectories  of
       the  subdirectories to the path:	this allows the	functions to be	in the
       same format as in the zsh source	distribution.

       When compinit is	 run,  it  searches  all  such	files  accessible  via
       fpath/FPATH and reads the first line of each of them.  This line	should
       contain one of the tags described below.	 Files whose first  line  does
       not  start  with	one of these tags are not considered to	be part	of the
       completion system and will not be treated specially.

       The tags	are:

       #compdef	name ... [ -{p|P} pattern ... [	-N name	... ] ]
	      The file will be made autoloadable and the function  defined  in
	      it will be called	when completing	names, each of which is	either
	      the name of a command whose arguments are	to be completed	or one
	      of  a number of special contexts in the form -context- described
	      below.

	      Each name	may also be of the form	`cmd=service'.	When  complet-
	      ing  the	command	 cmd, the function typically behaves as	if the
	      command (or special context) service  was	 being	completed  in-
	      stead.   This  provides a	way of altering	the behaviour of func-
	      tions that can perform many different completions.  It is	imple-
	      mented  by setting the parameter $service	when calling the func-
	      tion; the	function may choose to interpret this how  it  wishes,
	      and simpler functions will probably ignore it.

	      If  the  #compdef	line contains one of the options -p or -P, the
	      words following are taken	to be patterns.	 The function will  be
	      called  when  completion	is  attempted for a command or context
	      that matches one of the patterns.	 The options  -p  and  -P  are
	      used  to specify patterns	to be tried before or after other com-
	      pletions respectively.  Hence -P may be used to specify  default
	      actions.

	      The option -N is used after a list following -p or -P; it	speci-
	      fies that	remaining words	no longer define patterns.  It is pos-
	      sible  to	toggle between the three options as many times as nec-
	      essary.

       #compdef	-k style key-sequence ...
	      This option creates a widget behaving like  the  builtin	widget
	      style  and  binds	 it  to	 the given key-sequences, if any.  The
	      style must be one	of the builtin widgets	that  perform  comple-
	      tion,  namely complete-word, delete-char-or-list,	expand-or-com-
	      plete, expand-or-complete-prefix,	 list-choices,	menu-complete,
	      menu-expand-or-complete,	 or   reverse-menu-complete.   If  the
	      zsh/complist module is loaded  (see  zshmodules(1))  the	widget
	      menu-select is also available.

	      When one of the key-sequences is typed, the function in the file
	      will be invoked to generate the matches.	Note that a  key  will
	      not  be  re-bound	if it already was (that	is, was	bound to some-
	      thing other than undefined-key).	The  widget  created  has  the
	      same  name  as the file and can be bound to any other keys using
	      bindkey as usual.

       #compdef	-K widget-name style key-sequence [ name style seq ... ]
	      This is similar to -k except that	only one key-sequence argument
	      may  be given for	each widget-name style pair.  However, the en-
	      tire set of three	arguments may be repeated with a different set
	      of  arguments.   Note in particular that the widget-name must be
	      distinct in each set.  If	it does	not begin with `_'  this  will
	      be added.	 The widget-name should	not clash with the name	of any
	      existing widget: names based on the name	of  the	 function  are
	      most useful.  For	example,

		     #compdef -K _foo_complete complete-word "^X^C" \
		       _foo_list list-choices "^X^D"

	      (all on one line)	defines	a widget _foo_complete for completion,
	      bound to `^X^C', and a widget _foo_list for  listing,  bound  to
	      `^X^D'.

       #autoload [ options ]
	      Functions	 with the #autoload tag	are marked for autoloading but
	      are not otherwise	treated	specially.  Typically they are	to  be
	      called from within one of	the completion functions.  Any options
	      supplied will be passed to the autoload builtin; a  typical  use
	      is +X to force the function to be	loaded immediately.  Note that
	      the -U and -z flags are always added implicitly.

       The # is	part of	the tag	name and no white space	is allowed  after  it.
       The  #compdef  tags  use	the compdef function described below; the main
       difference is that the name of the function is supplied implicitly.

       The special contexts for	which completion functions can be defined are:

       -array-value-
	      The right	hand side of an	array-assignment (`name=(...)')

       -brace-parameter-
	      The name of a parameter expansion	within braces (`${...}')

       -assign-parameter-
	      The name of a parameter in an assignment,	i.e. on	the left  hand
	      side of an `='

       -command-
	      A	word in	command	position

       -condition-
	      A	word inside a condition	(`[[...]]')

       -default-
	      Any word for which no other completion is	defined

       -equal-
	      A	word beginning with an equals sign

       -first-
	      This  is	tried before any other completion function.  The func-
	      tion called may set the _compskip	parameter to  one  of  various
	      values:  all:  no	further	completion is attempted; a string con-
	      taining the substring patterns: no pattern completion  functions
	      will  be	called;	 a string containing default: the function for
	      the `-default-' context will not be called,  but	functions  de-
	      fined for	commands will be.

       -math- Inside mathematical contexts, such as `((...))'

       -parameter-
	      The name of a parameter expansion	(`$...')

       -redirect-
	      The word after a redirection operator.

       -subscript-
	      The contents of a	parameter subscript.

       -tilde-
	      After  an	initial	tilde (`~'), but before	the first slash	in the
	      word.

       -value-
	      On the right hand	side of	an assignment.

       Default implementations are supplied for	each of	 these	contexts.   In
       most  cases  the	 context  -context-  is	implemented by a corresponding
       function	_context, for example the context `-tilde-' and	 the  function
       `_tilde').

       The contexts -redirect- and -value- allow extra context-specific	infor-
       mation.	(Internally, this is handled by	the functions for each context
       calling	the function _dispatch.)  The extra information	is added sepa-
       rated by	commas.

       For the -redirect- context, the extra information is in the form	 `-re-
       direct-,op,command',  where  op is the redirection operator and command
       is the name of the command on the line.	If there is no command on  the
       line yet, the command field will	be empty.

       For the -value- context,	the form is `-value-,name,command', where name
       is the name of the parameter on the left	hand side of  the  assignment.
       In  the	case  of  elements  of	an associative array, for example `as-
       soc=(key	<TAB>',	name is	expanded to `name-key'.	  In  certain  special
       contexts,  such	as  completing	after `make CFLAGS=', the command part
       gives the name of the command, here make; otherwise it is empty.

       It is not necessary to define fully specific completions	as  the	 func-
       tions  provided	will  try to generate completions by progressively re-
       placing the elements with `-default-'.  For  example,  when  completing
       after  `foo=<TAB>',  _value will	try the	names `-value-,foo,' (note the
       empty command part), `-value-,foo,-default-' and`-value-,-default-,-de-
       fault-',	 in  that  order, until	it finds a function to handle the con-
       text.

       As an example:

	      compdef '_files -g "*.log"' '-redirect-,2>,-default-'

       completes files matching	`*.log'	after `2> <TAB>' for any command  with
       no more specific	handler	defined.

       Also:

	      compdef _foo -value-,-default-,-default-

       specifies  that	_foo provides completions for the values of parameters
       for which no special function has been defined.	This is	 usually  han-
       dled by the function _value itself.

       The same	lookup rules are used when looking up styles (as described be-
       low); for example

	      zstyle ':completion:*:*:-redirect-,2>,*:*' file-patterns '*.log'

       is another way to make  completion  after  `2>  <TAB>'  complete	 files
       matching	`*.log'.

   Functions
       The  following  function	 is  defined by	compinit and may be called di-
       rectly.

       compdef [ -ane ]	function name ... [ -{p|P} pattern ... [ -N name ...]]
       compdef -d name ...
       compdef -k [ -an	] function style key-sequence [	key-sequence ... ]
       compdef -K [ -an	] function name	style key-seq [	name style seq ... ]
	      The first	form defines the function to call  for	completion  in
	      the given	contexts as described for the #compdef tag above.

	      Alternatively,  all  the	arguments  may have the	form `cmd=ser-
	      vice'.   Here  service  should  already  have  been  defined  by
	      `cmd1=service' lines in #compdef files, as described above.  The
	      argument for cmd will be completed in the	same way as service.

	      The function argument may	alternatively be a  string  containing
	      almost  any  shell  code.	 If the	string contains	an equal sign,
	      the above	will take precedence.  The option -e may  be  used  to
	      specify the first	argument is to be evaluated as shell code even
	      if it contains an	equal sign.  The string	will be	executed using
	      the eval builtin command to generate completions.	 This provides
	      a	way of avoiding	having to define a  new	 completion  function.
	      For  example,  to	 complete files	ending in `.h' as arguments to
	      the command foo:

		     compdef '_files -g	"*.h"' foo

	      The option -n prevents any completions already defined  for  the
	      command or context from being overwritten.

	      The  option -d deletes any completion defined for	the command or
	      contexts listed.

	      The names	may also contain -p, -P	and -N	options	 as  described
	      for  the #compdef	tag.  The effect on the	argument list is iden-
	      tical, switching between	definitions  of	 patterns  tried  ini-
	      tially,  patterns	 tried	finally,  and normal commands and con-
	      texts.

	      The parameter $_compskip may be set by any function defined  for
	      a	 pattern context.  If it is set	to a value containing the sub-
	      string `patterns'	none of	the pattern-functions will be  called;
	      if it is set to a	value containing the substring `all', no other
	      function will be called.

	      The form with -k defines a widget	with  the  same	 name  as  the
	      function that will be called for each of the key-sequences; this
	      is like the #compdef -k tag.  The	function should	 generate  the
	      completions  needed  and	will otherwise behave like the builtin
	      widget whose name	is given as the	style argument.	  The  widgets
	      usable  for  this	 are:  complete-word, delete-char-or-list, ex-
	      pand-or-complete,	   expand-or-complete-prefix,	 list-choices,
	      menu-complete,  menu-expand-or-complete,	and  reverse-menu-com-
	      plete, as	well as	menu-select  if	 the  zsh/complist  module  is
	      loaded.  The option -n prevents the key being bound if it	is al-
	      ready to bound to	something other	than undefined-key.

	      The form with -K is similar and defines multiple	widgets	 based
	      on  the  same  function, each of which requires the set of three
	      arguments	name, style and	key-sequence, where the	latter two are
	      as  for  -k and the first	must be	a unique widget	name beginning
	      with an underscore.

	      Wherever applicable, the -a option makes the function  autoload-
	      able, equivalent to autoload -U function.

       The function compdef can	be used	to associate existing completion func-
       tions with new commands.	 For example,

	      compdef _pids foo

       uses the	function _pids to complete process IDs for the command foo.

       Note also the _gnu_generic function described below, which can be  used
       to complete options for commands	that understand	the `--help' option.

COMPLETION SYSTEM CONFIGURATION
       This section gives a short overview of how the completion system	works,
       and then	more detail on how users can configure how  and	 when  matches
       are generated.

   Overview
       When  completion	is attempted somewhere on the command line the comple-
       tion system begins building the context.	 The context represents	every-
       thing  that  the	 shell knows about the meaning of the command line and
       the significance	of the cursor position.	 This takes account of a  num-
       ber  of things including	the command word (such as `grep' or `zsh') and
       options to which	the current word may be	an argument (such as the  `-o'
       option to zsh which takes a shell option	as an argument).

       The  context  starts out	very generic ("we are beginning	a completion")
       and becomes more	specific as more is learned ("the current word is in a
       position	 that is usually a command name" or "the current word might be
       a variable name"	and so on).  Therefore the context  will  vary	during
       the same	call to	the completion system.

       This  context information is condensed into a string consisting of mul-
       tiple fields separated by colons, referred to simply as	`the  context'
       in the remainder	of the documentation.  Note that a user	of the comple-
       tion system rarely needs	to compose a context string, unless for	 exam-
       ple  a  new  function  is being written to perform completion for a new
       command.	 What a	user may need to do is compose a style pattern,	 which
       is  matched  against a context when needed to look up context-sensitive
       options that configure the completion system.

       The next	few paragraphs explain how a context is	 composed  within  the
       completion  function suite.  Following that is discussion of how	styles
       are defined.  Styles determine such things as how the matches are  gen-
       erated,	similarly  to  shell options but with much more	control.  They
       are defined with	the zstyle builtin command (see	zshmodules(1)).

       The context string always consists of a fixed set of fields,  separated
       by  colons and with a leading colon before the first.  Fields which are
       not yet known are left empty, but the surrounding colons	appear anyway.
       The  fields are always in the order :completion:function:completer:com-
       mand:argument:tag.  These have the following meaning:

       o      The literal string completion, saying that this style is used by
	      the  completion  system.	 This  distinguishes  the context from
	      those used by, for example, zle widgets and ZFTP functions.

       o      The function, if completion is called from a named widget	rather
	      than  through  the  normal completion system.  Typically this is
	      blank, but it is set by special widgets such as  predict-on  and
	      the  various  functions in the Widget directory of the distribu-
	      tion to the name of that function, often in an abbreviated form.

       o      The completer currently active, the name of the function without
	      the  leading  underscore and with	other underscores converted to
	      hyphens.	A `completer' is in overall control of how  completion
	      is  to  be performed; `complete' is the simplest,	but other com-
	      pleters exist to perform related tasks such as correction, or to
	      modify  the  behaviour  of  a  later completer.  See the section
	      `Control Functions' below	for more information.

       o      The command or a special -context-, just at it appears following
	      the  #compdef tag	or the compdef function.  Completion functions
	      for commands that	have sub-commands usually modify this field to
	      contain the name of the command followed by a minus sign and the
	      sub-command.  For	example, the completion	function for  the  cvs
	      command  sets this field to cvs-add when completing arguments to
	      the add subcommand.

       o      The argument; this indicates which command line or option	 argu-
	      ment  we	are  completing.  For command arguments	this generally
	      takes the	form argument-n, where n is the	number	of  the	 argu-
	      ment, and	for arguments to options the form option-opt-n where n
	      is the number of the argument to option opt.  However,  this  is
	      only  the	 case  if  the	command	 line  is parsed with standard
	      UNIX-style options and arguments,	so many	completions do not set
	      this.

       o      The tag.	As described previously, tags are used to discriminate
	      between the types	of matches a completion	function can  generate
	      in  a  certain context.  Any completion function may use any tag
	      name it likes, but a list	of the more common ones	is  given  be-
	      low.

       The  context  is	 gradually put together	as the functions are executed,
       starting	with the main entry point, which  adds	:completion:  and  the
       function	 element  if necessary.	 The completer then adds the completer
       element.	 The contextual	completion adds	the command and	 argument  op-
       tions.	Finally,  the  tag  is	added when the types of	completion are
       known.  For example, the	context	name

	      :completion::complete:dvips:option-o-1:files

       says that normal	completion was attempted as the	first argument to  the
       option -o of the	command	dvips:

	      dvips -o ...

       and the completion function will	generate filenames.

       Usually	completion  will  be  tried  for all possible tags in an order
       given by	the completion function.  However, this	can be altered by  us-
       ing  the	tag-order style.  Completion is	then restricted	to the list of
       given tags in the given order.

       The _complete_help bindable command shows all  the  contexts  and  tags
       available  for completion at a particular point.	 This provides an easy
       way of finding information for tag-order	and other styles.  It  is  de-
       scribed in the section `Bindable	Commands' below.

       When  looking  up styles	the completion system uses full	context	names,
       including the tag.  Looking up the value	of a style therefore  consists
       of two things: the context, which is matched to the most	specific (best
       fitting)	style pattern, and the name of the style itself, which must be
       matched	exactly.   The	following examples demonstrate that style pat-
       terns may be loosely defined for	 styles	 that  apply  broadly,	or  as
       tightly	defined	 as  desired for styles	that apply in narrower circum-
       stances.

       For example, many completion functions can generate matches in a	simple
       and  a  verbose	form  and  use	the verbose style to decide which form
       should be used.	To make	all such functions use the verbose form, put

	      zstyle ':completion:*' verbose yes

       in a startup file (probably .zshrc).  This gives	the verbose style  the
       value  yes  in  every context inside the	completion system, unless that
       context has a more specific definition.	It is best to avoid giving the
       context	as  `*'	in case	the style has some meaning outside the comple-
       tion system.

       Many such general purpose styles	can be configured simply by using  the
       compinstall function.

       A  more specific	example	of the use of the verbose style	is by the com-
       pletion for the kill builtin.  If the style is set, the	builtin	 lists
       full  job  texts	and process command lines; otherwise it	shows the bare
       job numbers and PIDs.  To turn the style	off for	this use only:

	      zstyle ':completion:*:*:kill:*:*'	verbose	no

       For even	more control, the style	can use	one  of	 the  tags  `jobs'  or
       `processes'.  To	turn off verbose display only for jobs:

	      zstyle ':completion:*:*:kill:*:jobs' verbose no

       The  -e option to zstyle	even allows completion function	code to	appear
       as the argument to a style; this	requires some understanding of the in-
       ternals of completion functions (see see	zshcompwid(1))).  For example,

	      zstyle -e	':completion:*'	hosts 'reply=($myhosts)'

       This  forces  the value of the hosts style to be	read from the variable
       myhosts each time a host	name is	needed;	this is	useful if the value of
       myhosts	can  change  dynamically.  For another useful example, see the
       example in the description of the file-list style below.	 This form can
       be slow and should be avoided for commonly examined styles such as menu
       and list-rows-first.

       Note that the order in which styles are defined does  not  matter;  the
       style  mechanism	uses the most specific possible	match for a particular
       style to	determine the set of values.  More precisely, strings are pre-
       ferred  over  patterns  (for  example, `:completion::complete:::foo' is
       more specific than `:completion::complete:::*'),	 and  longer  patterns
       are preferred over shorter patterns.

       A good rule of thumb is that any	completion style pattern that needs to
       include more than one wildcard (*) and that does	not end	in a tag name,
       should  include	all  six  colons  (:), possibly	surrounding additional
       wildcards.

       Style names like	those of tags are arbitrary and	depend on the  comple-
       tion  function.	 However,  the following two sections list some	of the
       most common tags	and styles.

   Standard Tags
       Some of the following are only used when	looking	up  particular	styles
       and do not refer	to a type of match.

       accounts
	      used to look up the users-hosts style

       all-expansions
	      used by the _expand completer when adding	the single string con-
	      taining all possible expansions

       all-files
	      for the names of all files (as distinct from a  particular  sub-
	      set, see the globbed-files tag).

       arguments
	      for arguments to a command

       arrays for names	of array parameters

       association-keys
	      for  keys	 of  associative arrays; used when completing inside a
	      subscript	to a parameter of this type

       bookmarks
	      when completing bookmarks	(e.g. for URLs and the	zftp  function
	      suite)

       builtins
	      for names	of builtin commands

       characters
	      for  single  characters  in  arguments of	commands such as stty.
	      Also used	when completing	character  classes  after  an  opening
	      bracket

       colormapids
	      for X colormap ids

       colors for color	names

       commands
	      for  names  of external commands.	 Also used by complex commands
	      such as cvs when completing names	subcommands.

       contexts
	      for contexts in arguments	to the zstyle builtin command

       corrections
	      used by the _approximate and _correct  completers	 for  possible
	      corrections

       cursors
	      for cursor names used by X programs

       default
	      used  in	some  contexts to provide a way	of supplying a default
	      when more	specific tags are also valid.  Note that this  tag  is
	      used when	only the function field	of the context name is set

       descriptions
	      used  when  looking up the value of the format style to generate
	      descriptions for types of	matches

       devices
	      for names	of device special files

       directories
	      for names	of directories -- local-directories  is	 used  instead
	      when  completing	arguments  of  cd and related builtin commands
	      when the cdpath array is set

       directory-stack
	      for entries in the directory stack

       displays
	      for X display names

       domains
	      for network domains

       email-plugin
	      for  email  addresses  from  the	`_email-plugin'	  backend   of
	      _email_addresses

       expansions
	      used  by	the _expand completer for individual words (as opposed
	      to the complete set of expansions) resulting from	the  expansion
	      of a word	on the command line

       extensions
	      for X server extensions

       file-descriptors
	      for numbers of open file descriptors

       files  the generic file-matching	tag used by functions completing file-
	      names

       fonts  for X font names

       fstypes
	      for file system types (e.g. for the mount	command)

       functions
	      names of functions -- normally shell functions, although certain
	      commands may understand other kinds of function

       globbed-files
	      for filenames when the name has been generated by	pattern	match-
	      ing

       groups for names	of user	groups

       history-words
	      for words	from the history

       hosts  for hostnames

       indexes
	      for array	indexes

       jobs   for jobs (as listed by the `jobs'	builtin)

       interfaces
	      for network interfaces

       keymaps
	      for names	of zsh keymaps

       keysyms
	      for names	of X keysyms

       libraries
	      for names	of system libraries

       limits for system limits

       local-directories
	      for names	of directories that are	subdirectories of the  current
	      working  directory  when	completing arguments of	cd and related
	      builtin commands (compare	path-directories) -- when  the	cdpath
	      array is unset, directories is used instead

       manuals
	      for names	of manual pages

       mailboxes
	      for e-mail folders

       maps   for map names (e.g. NIS maps)

       messages
	      used to look up the format style for messages

       modifiers
	      for names	of X modifiers

       modules
	      for modules (e.g.	zsh modules)

       my-accounts
	      used to look up the users-hosts style

       named-directories
	      for  named  directories  (you  wouldn't have guessed that, would
	      you?)

       names  for all kinds of names

       newsgroups
	      for USENET groups

       nicknames
	      for nicknames of NIS maps

       options
	      for command options

       original
	      used by the _approximate,	_correct and _expand  completers  when
	      offering the original string as a	match

       other-accounts
	      used to look up the users-hosts style

       other-files
	      for  the names of	any non-directory files.  This is used instead
	      of all-files when	the list-dirs-first style is in	effect.

       packages
	      for packages (e.g. rpm or	installed Debian packages)

       parameters
	      for names	of parameters

       path-directories
	      for names	of directories found by	 searching  the	 cdpath	 array
	      when  completing	arguments  of  cd and related builtin commands
	      (compare local-directories)

       paths  used to look up the values of the	 expand,  ambiguous  and  spe-
	      cial-dirs	styles

       pods   for perl pods (documentation files)

       ports  for communication	ports

       prefixes
	      for prefixes (like those of a URL)

       printers
	      for print	queue names

       processes
	      for process identifiers

       processes-names
	      used  to	look up	the command style when generating the names of
	      processes	for killall

       sequences
	      for sequences (e.g. mh sequences)

       sessions
	      for sessions in the zftp function	suite

       signals
	      for signal names

       strings
	      for strings (e.g.	the replacement	strings	 for  the  cd  builtin
	      command)

       styles for styles used by the zstyle builtin command

       suffixes
	      for filename extensions

       tags   for tags (e.g. rpm tags)

       targets
	      for makefile targets

       time-zones
	      for time zones (e.g. when	setting	the TZ parameter)

       types  for types	of whatever (e.g. address types	for the	xhost command)

       urls   used to look up the urls and local styles	when completing	URLs

       users  for usernames

       values for one of a set of values in certain lists

       variant
	      used  by _pick_variant to	look up	the command to run when	deter-
	      mining what program is installed for a particular	command	name.

       visuals
	      for X visuals

       warnings
	      used to look up the format style for warnings

       widgets
	      for zsh widget names

       windows
	      for IDs of X windows

       zsh-options
	      for shell	options

   Standard Styles
       Note that the values of several of these	styles represent boolean  val-
       ues.   Any  of the strings `true', `on',	`yes', and `1' can be used for
       the value `true'	and any	of the strings `false',	`off', `no',  and  `0'
       for  the	 value `false'.	 The behavior for any other value is undefined
       except where explicitly mentioned.  The default	value  may  be	either
       `true' or `false' if the	style is not set.

       Some  of	 these	styles	are tested first for every possible tag	corre-
       sponding	to a type of match, and	if no style was	found, for the default
       tag.   The  most	 notable styles	of this	type are menu, list-colors and
       styles  controlling  completion	listing	 such	as   list-packed   and
       last-prompt.   When tested for the default tag, only the	function field
       of the context will be set so that a style using	the default  tag  will
       normally	be defined along the lines of:

	      zstyle ':completion:*:default' menu ...

       accept-exact
	      This is tested for the default tag in addition to	the tags valid
	      for the current context.	If it is set to	`true' and any of  the
	      trial  matches  is  the  same as the string on the command line,
	      this match will immediately be accepted (even if it would	other-
	      wise be considered ambiguous).

	      When  completing	pathnames (where the tag used is `paths') this
	      style accepts any	number of patterns as the value	in addition to
	      the  boolean  values.   Pathnames	matching one of	these patterns
	      will be accepted immediately even	if the command	line  contains
	      some more	partially typed	pathname components and	these match no
	      file under the directory accepted.

	      This style is also used by the _expand completer	to  decide  if
	      words  beginning	with  a	tilde or parameter expansion should be
	      expanded.	 For example, if there are parameters foo and  foobar,
	      the  string  `$foo' will only be expanded	if accept-exact	is set
	      to `true'; otherwise the completion system will  be  allowed  to
	      complete	$foo  to  $foobar.  If the style is set	to `continue',
	      _expand will add the expansion as	a  match  and  the  completion
	      system will also be allowed to continue.

       accept-exact-dirs
	      This  is used by filename	completion.  Unlike accept-exact it is
	      a	boolean.  By default, filename completion examines all	compo-
	      nents  of	 a path	to see if there	are completions	of that	compo-
	      nent, even if the	component matches an existing directory.   For
	      example,	when completion	after /usr/bin/, the function examines
	      possible completions to /usr.

	      When this	style is `true', any prefix of a path that matches  an
	      existing	directory  is accepted without any attempt to complete
	      it further.  Hence, in the given example,	the path /usr/bin/  is
	      accepted immediately and completion tried	in that	directory.

	      If  you  wish  to	 inhibit  this	behaviour  entirely,  set  the
	      path-completion style (see below)	to `false'.

       add-space
	      This style is used by the	_expand	completer.  If	it  is	`true'
	      (the  default), a	space will be inserted after all words result-
	      ing from the expansion, or a slash  in  the  case	 of  directory
	      names.   If  the	value is `file', the completer will only add a
	      space to names of	existing files.	 Either	a  boolean  `true'  or
	      the value	`file' may be combined with `subst', in	which case the
	      completer	will not add a space to	words generated	from  the  ex-
	      pansion of a substitution	of the form `$(...)' or	`${...}'.

	      The  _prefix completer uses this style as	a simple boolean value
	      to decide	if a space should be inserted before the suffix.

       ambiguous
	      This applies when	completing non-final  components  of  filename
	      paths,  in  other	 words	those with a trailing slash.  If it is
	      set, the cursor is left after  the  first	 ambiguous  component,
	      even  if	menu completion	is in use.  The	style is always	tested
	      with the paths tag.

       assign-list
	      When completing after an equals sign that	is being treated as an
	      assignment,  the	completion  system normally completes only one
	      filename.	 In some cases the value  may be a list	 of  filenames
	      separated	 by colons, as with PATH and similar parameters.  This
	      style can	be set to a list of patterns  matching	the  names  of
	      such parameters.

	      The  default  is to complete lists when the word on the line al-
	      ready contains a colon.

       auto-description
	      If set, this style's value will be used as the  description  for
	      options  that are	not described by the completion	functions, but
	      that have	exactly	one argument.  The sequence `%d' in the	 value
	      will  be replaced	by the description for this argument.  Depend-
	      ing on personal preferences, it may be useful to set this	 style
	      to  something  like  `specify: %d'.  Note	that this may not work
	      for some commands.

       avoid-completer
	      This is used by the _all_matches	completer  to  decide  if  the
	      string  consisting  of  all  matches should be added to the list
	      currently	being generated.  Its value is a list of names of com-
	      pleters.	If any of these	is the name of the completer that gen-
	      erated the matches in this completion, the string	 will  not  be
	      added.

	      The  default value for this style	is `_expand _old_list _correct
	      _approximate', i.e. it  contains	the  completers	 for  which  a
	      string with all matches will almost never	be wanted.

       cache-path
	      This  style  defines  the	 path where any	cache files containing
	      dumped completion	data  are  stored.   It	 defaults  to  `$ZDOT-
	      DIR/.zcompcache',	 or `$HOME/.zcompcache'	if $ZDOTDIR is not de-
	      fined.  The  completion  cache  will  not	 be  used  unless  the
	      use-cache	style is set.

       cache-policy
	      This  style  defines the function	that will be used to determine
	      whether a	cache  needs  rebuilding.   See	 the  section  on  the
	      _cache_invalid function below.

       call-command
	      This style is used in the	function for commands such as make and
	      ant where	calling	the command directly to	generate matches  suf-
	      fers  problems such as being slow	or, as in the case of make can
	      potentially cause	actions	in the makefile	to be executed.	If  it
	      is  set to `true'	the command is called to generate matches. The
	      default value of this style is `false'.

       command
	      In many places, completion functions need	to call	external  com-
	      mands  to	 generate  the list of completions.  This style	can be
	      used to override the command that	is called in some such	cases.
	      The  elements of the value are joined with spaces	to form	a com-
	      mand line	to execute.  The value can also	start with  a  hyphen,
	      in  which	 case the usual	command	will be	added to the end; this
	      is most useful for putting `builtin' or `command'	 in  front  to
	      make  sure  the  appropriate version of a	command	is called, for
	      example to avoid calling a shell function	with the same name  as
	      an external command.

	      As an example, the completion function for process IDs uses this
	      style with the processes tag to generate the IDs to complete and
	      the  list	 of  processes	to  display  (if  the verbose style is
	      `true').	The list produced by the command should	look like  the
	      output  of the ps	command.  The first line is not	displayed, but
	      is searched for the string `PID' (or `pid') to find the position
	      of the process IDs in the	following lines.  If the line does not
	      contain `PID', the first numbers in each of the other lines  are
	      taken as the process IDs to complete.

	      Note  that  the  completion  function  generally has to call the
	      specified	command	for each attempt to  generate  the  completion
	      list.   Hence care should	be taken to specify only commands that
	      take a short time	to run,	and in particular to  avoid  any  that
	      may never	terminate.

       command-path
	      This  is	a  list	 of directories	to search for commands to com-
	      plete.  The default for this style is the	value of  the  special
	      parameter	path.

       commands
	      This  is	used  by  the function completing sub-commands for the
	      system initialisation scripts (residing in /etc/init.d or	 some-
	      where  not too far away from that).  Its values give the default
	      commands to complete for those commands for which	the completion
	      function isn't able to find them out automatically.  The default
	      for this style are the two strings `start' and `stop'.

       complete
	      This is used by the _expand_alias	function  when	invoked	 as  a
	      bindable	command.  If set to `true' and the word	on the command
	      line is not the name of an alias,	matching alias names  will  be
	      completed.

       complete-options
	      This  is	used  by  the  completer for cd, chdir and pushd.  For
	      these commands a - is used to introduce a	directory stack	 entry
	      and  completion  of these	is far more common than	completing op-
	      tions.  Hence unless the value of	this style is  `true'  options
	      will  not	 be  completed,	 even  after  an  initial -.  If it is
	      `true', options will be completed	 after	an  initial  -	unless
	      there is a preceding -- on the command line.

       completer
	      The  strings  given as the value of this style provide the names
	      of the completer functions to use. The available completer func-
	      tions are	described in the section `Control Functions' below.

	      Each  string may be either the name of a completer function or a
	      string of	the form `function:name'.  In the first	case the  com-
	      pleter  field  of	 the context will contain the name of the com-
	      pleter without the leading underscore and	with all other	under-
	      scores  replaced by hyphens.  In the second case the function is
	      the name of the completer	to call, but the context will  contain
	      the user-defined name in the completer field of the context.  If
	      the name starts with a hyphen, the string	for the	 context  will
	      be build from the	name of	the completer function as in the first
	      case with	the name appended to it.  For example:

		     zstyle ':completion:*' completer _complete	_complete:-foo

	      Here, completion will call the _complete completer  twice,  once
	      using  `complete'	and once using `complete-foo' in the completer
	      field of the context.  Normally, using the same  completer  more
	      than  once  only makes sense when	used with the `functions:name'
	      form, because otherwise the context name will be the same	in all
	      calls to the completer; possible exceptions to this rule are the
	      _ignored and _prefix completers.

	      The default value	for this style is `_complete  _ignored':  only
	      completion  will be done,	first using the	ignored-patterns style
	      and the $fignore array and then without ignoring matches.

       condition
	      This style is used by the	_list completer	function to decide  if
	      insertion	 of matches should be delayed unconditionally. The de-
	      fault is `true'.

       delimiters
	      This style is used when adding a delimiter for use with  history
	      modifiers	 or glob qualifiers that have delimited	arguments.  It
	      is an array of preferred delimiters to add.  Non-special charac-
	      ters are preferred as the	completion system may otherwise	become
	      confused.	 The default list is :,	+, /, -, %.  The list  may  be
	      empty to force a delimiter to be typed.

       disabled
	      If  this is set to `true', the _expand_alias completer and bind-
	      able command will	try to expand disabled aliases,	too.  The  de-
	      fault is `false'.

       domains
	      A	 list  of names	of network domains for completion.  If this is
	      not set, domain names will  be  taken  from  the	file  /etc/re-
	      solv.conf.

       environ
	      The environ style	is used	when completing	for `sudo'.  It	is set
	      to an array of `VAR=value' assignments to	be exported  into  the
	      local  environment  before the completion	for the	target command
	      is invoked.
	      zstyle ':completion:*:sudo::' environ \
		PATH="/sbin:/usr/sbin:$PATH" HOME="/root"

       expand This style is used when completing strings consisting of	multi-
	      ple parts, such as path names.

	      If one of	its values is the string `prefix', the partially typed
	      word from	the line will be expanded as far as possible  even  if
	      trailing parts cannot be completed.

	      If  one of its values is the string `suffix', matching names for
	      components after the first ambiguous one	will  also  be	added.
	      This  means that the resulting string is the longest unambiguous
	      string possible.	However, menu completion can be	used to	 cycle
	      through all matches.

       fake   This  style may be set for any completion	context.  It specifies
	      additional strings that will always be completed	in  that  con-
	      text.  The form of each string is	`value:description'; the colon
	      and description may be omitted, but any literal colons in	 value
	      must  be	quoted	with a backslash.  Any description provided is
	      shown alongside the value	in completion listings.

	      It is important to use a sufficiently restrictive	 context  when
	      specifying  fake	strings.   Note	that the styles	fake-files and
	      fake-parameters  provide	additional  features  when  completing
	      files or parameters.

       fake-always
	      This  works  identically	to  the	fake style except that the ig-
	      nored-patterns style is not applied to it.  This makes it	possi-
	      ble  to  override	a set of matches completely by setting the ig-
	      nored patterns to	`*'.

	      The following shows a way	of supplementing any  tag  with	 arbi-
	      trary  data,  but	 having	 it behave for display purposes	like a
	      separate tag.  In	this  example  we  use	the  features  of  the
	      tag-order	 style	to  divide  the	named-directories tag into two
	      when performing completion with the standard completer  complete
	      for  arguments  of cd.  The tag named-directories-normal behaves
	      as normal, but the tag named-directories-mine contains  a	 fixed
	      set  of  directories.   This  has	the effect of adding the match
	      group `extra directories'	with the given completions.

		     zstyle ':completion::complete:cd:*' tag-order \
		       'named-directories:-mine:extra\ directories
		       named-directories:-normal:named\	directories *'
		     zstyle ':completion::complete:cd:*:named-directories-mine'	\
		       fake-always mydir1 mydir2
		     zstyle ':completion::complete:cd:*:named-directories-mine'	\
		       ignored-patterns	'*'

       fake-files
	      This style is used when completing files and looked up without a
	      tag.   Its values	are of the form	`dir:names...'.	 This will add
	      the names	(strings separated by spaces) as possible matches when
	      completing  in  the  directory dir, even if no such files	really
	      exist.  The dir may be a pattern;	pattern	characters  or	colons
	      in  dir  should  be quoted with a	backslash to be	treated	liter-
	      ally.

	      This can be useful on systems that support special file  systems
	      whose  top-level	pathnames  can not be listed or	generated with
	      glob patterns.  It can also be used for  directories  for	 which
	      one does not have	read permission.

	      The  pattern  form can be	used to	add a certain `magic' entry to
	      all directories on a particular file system.

       fake-parameters
	      This is used by the completion  function	for  parameter	names.
	      Its values are names of parameters that might not	yet be set but
	      should be	completed nonetheless.	Each name may also be followed
	      by  a  colon  and	 a string specifying the type of the parameter
	      (like `scalar', `array' or `integer').  If the  type  is	given,
	      the  name	 will only be completed	if parameters of that type are
	      required in the particular context.  Names for which no type  is
	      specified	will always be completed.

       file-list
	      This  style  controls whether files completed using the standard
	      builtin mechanism	are to be listed with a	long list  similar  to
	      ls  -l.	Note  that this	feature	uses the shell module zsh/stat
	      for file information; this loads the builtin stat	which will re-
	      place any	external stat executable.  To avoid this the following
	      code can be included in an initialization	file:

		     zmodload -i zsh/stat
		     disable stat

	      The style	may either be set to a `true' value (or	`all'),	or one
	      of  the  values `insert' or `list', indicating that files	are to
	      be listed	in long	format in all circumstances, or	when  attempt-
	      ing  to  insert  a file name, or when listing file names without
	      attempting to insert one.

	      More generally, the value	may be an array	of any	of  the	 above
	      values, optionally followed by =num.  If num is present it gives
	      the maximum number of matches for	which long listing style  will
	      be used.	For example,

		     zstyle ':completion:*' file-list list=20 insert=10

	      specifies	 that  long  format will be used when listing up to 20
	      files or inserting a file	with up	 to  10	 matches  (assuming  a
	      listing  is to be	shown at all, for example on an	ambiguous com-
	      pletion),	else short format will be used.

		     zstyle -e ':completion:*' file-list \
			    '((	${+NUMERIC} )) && reply=(true)'

	      specifies	that long format will be used any time a numeric argu-
	      ment is supplied,	else short format.

       file-patterns
	      This  is used by the standard function for completing filenames,
	      _files.  If the style is unset up	to  three  tags	 are  offered,
	      `globbed-files',`directories'  and `all-files', depending	on the
	      types of files  expected by the caller of	_files.	 The first two
	      (`globbed-files'	and  `directories')  are  normally offered to-
	      gether to	make it	easier to complete files in sub-directories.

	      The file-patterns	style provides	alternatives  to  the  default
	      tags, which are not used.	 Its value consists of elements	of the
	      form `pattern:tag'; each string may contain any number  of  such
	      specifications separated by spaces.

	      The  pattern  is	a pattern that is to be	used to	generate file-
	      names.  Any occurrence of	the sequence `%p' is replaced  by  any
	      pattern(s) passed	by the function	calling	_files.	 Colons	in the
	      pattern must be preceded by a backslash  to  make	 them  distin-
	      guishable	 from the colon	before the tag.	 If more than one pat-
	      tern is needed, the patterns can be given	inside	braces,	 sepa-
	      rated by commas.

	      The  tags	 of all	strings	in the value will be offered by	_files
	      and used when looking up other styles.  Any  tags	 in  the  same
	      word  will  be  offered at the same time and before later	words.
	      If no `:tag' is given the	`files'	tag will be used.

	      The tag may also be followed by an optional second colon	and  a
	      description, which will be used for the `%d' in the value	of the
	      format style (if that is set) instead of the default description
	      supplied	by  the	completion function.  If the description given
	      here contains itself a `%d', that	is replaced with the  descrip-
	      tion supplied by the completion function.

	      For example, to make the rm command first	complete only names of
	      object files and then the	names of all  files  if	 there	is  no
	      matching object file:

		     zstyle ':completion:*:*:rm:*:*' file-patterns \
			 '*.o:object-files' '%p:all-files'

	      To alter the default behaviour of	file completion	-- offer files
	      matching a pattern and directories on the	 first	attempt,  then
	      all  files -- to offer only matching files on the	first attempt,
	      then directories,	and finally all	files:

		     zstyle ':completion:*' file-patterns \
			 '%p:globbed-files' '*(-/):directories'	'*:all-files'

	      This works even  where  there  is	 no  special  pattern:	_files
	      matches  all  files  using the pattern `*' at the	first step and
	      stops when it sees this pattern.	Note also it will never	try  a
	      pattern more than	once for a single completion attempt.

	      During  the execution of completion functions, the EXTENDED_GLOB
	      option is	in effect, so the characters `#',  `~'	and  `^'  have
	      special meanings in the patterns.

       file-sort
	      The  standard filename completion	function uses this style with-
	      out a tag	to determine  in  which	 order	the  names  should  be
	      listed;  menu completion will cycle through them in the same or-
	      der.  The	possible values	are: `size' to sort by the size	of the
	      file; `links' to sort by the number of links to the file;	`modi-
	      fication'	(or `time' or `date') to sort by the last modification
	      time;  `access' to sort by the last access time; and `inode' (or
	      `change')	to sort	by the last inode change time.	If  the	 style
	      is set to	any other value, or is unset, files will be sorted al-
	      phabetically by name.  If	the value  contains  the  string  `re-
	      verse',  sorting	is  done  in the opposite order.  If the value
	      contains the string `follow', timestamps are associated with the
	      targets  of symbolic links; the default is to use	the timestamps
	      of the links themselves.

       filter The ldap plugin of  email	 address  completion  (see  _email_ad-
	      dresses)	uses  this  style  to  specify the attributes to match
	      against when filtering entries.  So for example, if the style is
	      set  to  `sn', matching is done against surnames.	 Standard LDAP
	      filtering	is used	so normal completion matching is bypassed.  If
	      this style is not	set, the LDAP plugin is	skipped.  You may also
	      need to set the command style to specify how to connect to  your
	      LDAP server.

       force-list
	      This forces a list of completions	to be shown at any point where
	      listing is done, even in cases where the list would  usually  be
	      suppressed.   For	 example,  normally  the list is only shown if
	      there are	at least two different matches.	 By setting this style
	      to  `always',  the  list	will always be shown, even if there is
	      only a single match that	will  immediately  be  accepted.   The
	      style  may  also be set to a number.  In this case the list will
	      be shown if there	are at least that many matches,	even  if  they
	      would all	insert the same	string.

	      This style is tested for the default tag as well as for each tag
	      valid for	the current completion.	  Hence	 the  listing  can  be
	      forced only for certain types of match.

       format If  this is set for the descriptions tag,	its value is used as a
	      string to	display	above matches in completion  lists.   The  se-
	      quence  `%d'  in	this  string will be replaced with a short de-
	      scription	of what	these matches are.  This string	may also  con-
	      tain the following sequences to specify output attributes	as de-
	      scribed in the section EXPANSION OF  PROMPT  SEQUENCES  in  zsh-
	      misc(1): `%B', `%S', `%U', `%F', `%K' and	their lower case coun-
	      terparts,	as well	as `%{...%}'.  `%F', `%K' and  `%{...%}'  take
	      arguments	 in  the same form as prompt expansion.	 Note that the
	      sequence `%G' is not available; an argument to  `%{'  should  be
	      used instead.

	      The  style is tested with	each tag valid for the current comple-
	      tion before it is	tested for the descriptions tag.   Hence  dif-
	      ferent  format  strings  can  be	defined	for different types of
	      match.

	      Note  also  that	some  completer	 functions  define  additional
	      `%'-sequences.   These are described for the completer functions
	      that make	use of them.

	      Some completion functions	display	 messages  that	 may  be  cus-
	      tomised  by  setting this	style for the messages tag.  Here, the
	      `%d' is replaced with a message given by	the  completion	 func-
	      tion.

	      Finally,	the  format string is looked up	with the warnings tag,
	      for use when no matches could be generated at all.  In this case
	      the  `%d'	is replaced with the descriptions for the matches that
	      were expected separated by spaces.  The  sequence	 `%D'  is  re-
	      placed with the same descriptions	separated by newlines.

	      It  is  possible to use printf-style field width specifiers with
	      `%d' and similar escape sequences.  This is handled by the zfor-
	      mat  builtin  command  from  the	zsh/zutil  module, see zshmod-
	      ules(1).

       glob   This is used by the _expand completer.  If it is set  to	`true'
	      (the default), globbing will be attempted	on the words resulting
	      from a previous substitution (see	the substitute style) or  else
	      the original string from the line.

       global If  this	is set to `true' (the default),	the _expand_alias com-
	      pleter and bindable command will try to expand global aliases.

       group-name
	      The completion system can	 group	different  types  of  matches,
	      which  appear in separate	lists.	This style can be used to give
	      the names	of groups for particular tags.	For example,  in  com-
	      mand  position  the completion system generates names of builtin
	      and external commands, names of aliases, shell functions and pa-
	      rameters	and  reserved  words as	possible completions.  To have
	      the external commands and	shell functions	listed separately:

		     zstyle ':completion:*:*:-command-:*:commands' \
			    group-name commands
		     zstyle ':completion:*:*:-command-:*:functions' \
			    group-name functions

	      As a consequence,	any match with the same	tag will be  displayed
	      in the same group.

	      If  the  name  given is the empty	string the name	of the tag for
	      the matches will be used as the name of the group.  So, to  have
	      all  different  types  of	 matches displayed separately, one can
	      just set:

		     zstyle ':completion:*' group-name ''

	      All matches for which no group name is defined will be put in  a
	      group named -default-.

       group-order
	      This  style is additional	to the group-name style	to specify the
	      order for	display	of the groups defined by that  style  (compare
	      tag-order,  which	 determines  which completions appear at all).
	      The groups named are shown in the	given order; any other	groups
	      are shown	in the order defined by	the completion function.

	      For  example, to have names of builtin commands, shell functions
	      and external commands appear in that order  when	completing  in
	      command position:

		     zstyle ':completion:*:*:-command-:*:*' group-order	\
			    builtins functions commands

       groups A	list of	names of UNIX groups.  If this is not set, group names
	      are taken	from the YP database or	the file `/etc/group'.

       hidden If this is set to	`true',	matches	for the	given context will not
	      be listed, although any description for the matches set with the
	      format style will	be shown.  If it is set	to `all', not even the
	      description will be displayed.

	      Note that	the matches will still be completed; they are just not
	      shown in the list.  To avoid having matches considered as	possi-
	      ble  completions	at all,	the tag-order style can	be modified as
	      described	below.

       hosts  A	list of	names of hosts that should be completed.  If  this  is
	      not set, hostnames are taken from	the file `/etc/hosts'.

       hosts-ports
	      This style is used by commands that need or accept hostnames and
	      network ports.  The strings in the value should be of  the  form
	      `host:port'.   Valid  ports  are	determined  by the presence of
	      hostnames; multiple ports	for the	same host may appear.

       ignore-line
	      This is tested for each tag valid	for  the  current  completion.
	      If  it  is  set to `true', none of the words that	are already on
	      the line will be considered as possible completions.  If	it  is
	      set  to `current', the word the cursor is	on will	not be consid-
	      ered as a	possible completion.   The  value  `current-shown'  is
	      similar but only applies if the list of completions is currently
	      shown on the screen.  Finally, if	the style is set  to  `other',
	      all  words  on  the  line	except for the current one will	be ex-
	      cluded from the possible completions.

	      The values `current' and `current-shown' are a bit like the  op-
	      posite  of  the  accept-exact  style:  only strings with missing
	      characters will be completed.

	      Note that	you almost certainly don't want	to set this to	`true'
	      or  `other' for a	general	context	such as	`:completion:*'.  This
	      is because it would disallow completion of, for example, options
	      multiple	times  even if the command in question accepts the op-
	      tion more	than once.

       ignore-parents
	      The style	is tested without a tag	 by  the  function  completing
	      pathnames	 in  order to determine	whether	to ignore the names of
	      directories already mentioned in the current word, or  the  name
	      of the current working directory.	 The value must	include	one or
	      both of the following strings:

	      parent The name of any directory whose path is already contained
		     in	 the  word  on the line	is ignored.  For example, when
		     completing	after foo/../, the directory foo will  not  be
		     considered	a valid	completion.

	      pwd    The  name	of  the	 current working directory will	not be
		     completed;	hence, for example, completion after ../  will
		     not use the name of the current directory.

	      In addition, the value may include one or	both of:

	      ..     Ignore  the  specified  directories only when the word on
		     the line contains the substring `../'.

	      directory
		     Ignore the	specified directories only when	names  of  di-
		     rectories	are  completed,	 not  when completing names of
		     files.

	      Excluded values act in a similar fashion to values  of  the  ig-
	      nored-patterns  style,  so they can be restored to consideration
	      by the _ignored completer.

       extra-verbose
	      If set, the completion listing is	more verbose at	the cost of  a
	      probable	decrease  in completion	speed.	Completion performance
	      will suffer if this style	is set to `true'.

       ignored-patterns
	      A	list of	patterns; any trial completion	matching  one  of  the
	      patterns will be excluded	from consideration.  The _ignored com-
	      pleter can appear	in the list of completers to restore  the  ig-
	      nored matches.  This is a	more configurable version of the shell
	      parameter	$fignore.

	      Note that	the EXTENDED_GLOB option is set	during	the  execution
	      of completion functions, so the characters `#', `~' and `^' have
	      special meanings in the patterns.

       insert This style is used  by  the  _all_matches	 completer  to	decide
	      whether  to  insert  the list of all matches unconditionally in-
	      stead of adding the list as another match.

       insert-ids
	      When completing process IDs, for example	as  arguments  to  the
	      kill and wait builtins the name of a command may be converted to
	      the appropriate process ID.  A problem arises when  the  process
	      name  typed  is not unique.  By default (or if this style	is set
	      explicitly to `menu') the	name will be converted immediately  to
	      a	 set  of  possible IDs,	and menu completion will be started to
	      cycle through them.

	      If the value of the style	is `single', the shell will wait until
	      the user has typed enough	to make	the command unique before con-
	      verting the name to an ID; attempts at completion	will be	unsuc-
	      cessful  until  that  point.   If	the value is any other string,
	      menu completion will be started when the	string	typed  by  the
	      user is longer than the common prefix to the corresponding IDs.

       insert-tab
	      If  this	is  set	to `true', the completion system will insert a
	      TAB character (assuming that was used to start  completion)  in-
	      stead  of	performing completion when there is no non-blank char-
	      acter to the left	of the cursor.	If it is set to	`false',  com-
	      pletion will be done even	there.

	      The  value  may  also contain the	substrings `pending' or	`pend-
	      ing=val'.	 In this case, the typed character  will  be  inserted
	      instead  of  starting completion when there is unprocessed input
	      pending.	If a val is given, completion  will  not  be  done  if
	      there  are  at  least that many characters of unprocessed	input.
	      This is often useful when	pasting	characters  into  a  terminal.
	      Note  however,  that it relies on	the $PENDING special parameter
	      from the zsh/zle module being set	properly which is not  guaran-
	      teed on all platforms.

	      The  default value of this style is `true' except	for completion
	      within vared builtin command where it is `false'.

       insert-unambiguous
	      This is used by the _match and _approximate  completers.	 These
	      completers  are  often  used with	menu completion	since the word
	      typed may	bear little resemblance	to the final completion.  How-
	      ever,  if	 this  style  is `true', the completer will start menu
	      completion only if it could find no unambiguous  initial	string
	      at least as long as the original string typed by the user.

	      In  the  case of the _approximate	completer, the completer field
	      in the context will already have been set	to one of  correct-num
	      or  approximate-num, where num is	the number of errors that were
	      accepted.

	      In the case of the _match	completer, the style may also  be  set
	      to  the  string `pattern'.  Then the pattern on the line is left
	      unchanged	if it does not match unambiguously.

       gain-privileges
	      If set to	true, this style enables the use of commands like sudo
	      or doas to gain extra privileges when retrieving information for
	      completion. This is only done when a command such	 as  sudo  ap-
	      pears  on	the command-line. To force the use of, e.g. sudo or to
	      override any prefix that might be	added due to  gain-privileges,
	      the  command  style  can be used with a value that begins	with a
	      hyphen.

       keep-prefix
	      This style is used by the	_expand	completer.  If it  is  `true',
	      the  completer  will  try	to keep	a prefix containing a tilde or
	      parameter	expansion.  Hence,  for	 example,  the	string	`~/f*'
	      would  be	 expanded  to `~/foo' instead of `/home/user/foo'.  If
	      the style	is set to `changed' (the  default),  the  prefix  will
	      only  be	left unchanged if there	were other changes between the
	      expanded words and the original word from	the command line.  Any
	      other value forces the prefix to be expanded unconditionally.

	      The  behaviour  of _expand when this style is `true' is to cause
	      _expand to give up when a	single	expansion  with	 the  restored
	      prefix  is  the  same  as	the original; hence any	remaining com-
	      pleters may be called.

       last-prompt
	      This is a	more flexible form of the  ALWAYS_LAST_PROMPT  option.
	      If  it  is  `true', the completion system	will try to return the
	      cursor to	the previous command line after	displaying  a  comple-
	      tion list.  It is	tested for all tags valid for the current com-
	      pletion, then the	default	tag.  The cursor will be moved back to
	      the  previous  line  if  this  style  is `true' for all types of
	      match.  Note that	unlike the ALWAYS_LAST_PROMPT option  this  is
	      independent of the numeric argument.

       known-hosts-files
	      This  style  should  contain  a list of files to search for host
	      names and	(if the	use-ip style is	set) IP	addresses in a	format
	      compatible  with	ssh  known_hosts files.	 If it is not set, the
	      files /etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts are	used.

       list   This style is used by the	_history_complete_word	bindable  com-
	      mand.  If	it is set to `true' it has no effect.  If it is	set to
	      `false' matches will not be listed.  This	overrides the  setting
	      of  the  options	controlling  listing  behaviour, in particular
	      AUTO_LIST.  The context  always  starts  with  `:completion:his-
	      tory-words'.

       list-colors
	      If  the zsh/complist module is loaded, this style	can be used to
	      set color	specifications.	 This mechanism	replaces  the  use  of
	      the  ZLS_COLORS and ZLS_COLOURS parameters described in the sec-
	      tion `The	zsh/complist Module' in	zshmodules(1), but the	syntax
	      is the same.

	      If  this	style  is  set for the default tag, the	strings	in the
	      value are	taken as specifications	that are  to  be  used	every-
	      where.  If it is set for other tags, the specifications are used
	      only for matches of the type described by	the tag.  For this  to
	      work best, the group-name	style must be set to an	empty string.

	      In addition to setting styles for	specific tags, it is also pos-
	      sible to use group names specified explicitly by the  group-name
	      tag together with	the `(group)' syntax allowed by	the ZLS_COLORS
	      and ZLS_COLOURS parameters and simply using the default tag.

	      It is possible to	use any	color specifications  already  set  up
	      for the GNU version of the ls command:

		     zstyle ':completion:*:default' list-colors	\
			    ${(s.:.)LS_COLORS}

	      The  default  colors  are	the same as for	the GNU	ls command and
	      can be obtained by setting the style to an  empty	 string	 (i.e.
	      '').

       list-dirs-first
	      This is used by file completion.	If set,	directories to be com-
	      pleted are listed	separately  from  and  before  completion  for
	      other  files,  regardless	of tag ordering.  In addition, the tag
	      other-files is used in place  of	all-files  for	the  remaining
	      files,  to  indicate that	no directories are presented with that
	      tag.

       list-grouped
	      If this style is `true' (the  default),  the  completion	system
	      will  try	 to  make  certain completion listings more compact by
	      grouping matches.	 For example, options for commands  that  have
	      the  same	 description  (shown  when the verbose style is	set to
	      `true') will appear as a single entry.  However, menu  selection
	      can be used to cycle through all the matches.

       list-packed
	      This is tested for each tag valid	in the current context as well
	      as the default tag.  If it is set	to `true',  the	 corresponding
	      matches  appear  in  listings  as	if the LIST_PACKED option were
	      set.  If it is set to `false', they are listed normally.

       list-prompt
	      If this style is set for the default tag,	completion lists  that
	      don't  fit on the	screen can be scrolled (see the	description of
	      the zsh/complist module in zshmodules(1)).  The  value,  if  not
	      the  empty  string,  will	be displayed after every screenful and
	      the shell	will prompt for	a key press; if	the style  is  set  to
	      the empty	string,	a default prompt will be used.

	      The  value may contain the escape	sequences: `%l'	or `%L', which
	      will be replaced by the number of	the last  line	displayed  and
	      the total	number of lines; `%m' or `%M', the number of the  last
	      match shown and the total	number of matches; and `%p' and	 `%P',
	      `Top'  when  at  the beginning of	the list, `Bottom' when	at the
	      end and the position shown as a percentage of the	 total	length
	      otherwise.  In each case the form	with the uppercase letter will
	      be replaced by a string of fixed width,  padded  to  the	 right
	      with  spaces,  while  the	 lowercase  form will be replaced by a
	      variable width string.  As in other prompt strings,  the	escape
	      sequences	 `%S',	`%s',  `%B', `%b', `%U', `%u' for entering and
	      leaving the display modes	 standout,  bold  and  underline,  and
	      `%F',  `%f',  `%K',  `%k'	for changing the foreground background
	      colour, are also available, as is	the form `%{...%}' for enclos-
	      ing escape sequences which display with zero (or,	with a numeric
	      argument,	some other) width.

	      After deleting this prompt the variable LISTPROMPT should	be un-
	      set for the removal to take effect.

       list-rows-first
	      This  style  is  tested in the same way as the list-packed style
	      and determines whether matches are to be listed in a  rows-first
	      fashion as if the	LIST_ROWS_FIRST	option were set.

       list-suffixes
	      This style is used by the	function that completes	filenames.  If
	      it is `true', and	completion is attempted	on a string containing
	      multiple partially typed pathname	components, all	ambiguous com-
	      ponents will be shown.  Otherwise, completion stops at the first
	      ambiguous	component.

       list-separator
	      The  value  of this style	is used	in completion listing to sepa-
	      rate the string to complete from	a  description	when  possible
	      (e.g.  when  completing  options).  It defaults to `--' (two hy-
	      phens).

       local  This is for use with functions that complete URLs	for which  the
	      corresponding files are available	directly from the file system.
	      Its value	should consist of three	strings: a hostname, the  path
	      to  the default web pages	for the	server,	and the	directory name
	      used by a	user placing web pages within their home area.

	      For example:

		     zstyle ':completion:*' local toast	\
			 /var/http/public/toast	public_html

	      Completion after `http://toast/stuff/' will look	for  files  in
	      the  directory  /var/http/public/toast/stuff,   while completion
	      after `http://toast/~yousir/' will look for files	in the	direc-
	      tory ~yousir/public_html.

       mail-directory
	      If  set,	zsh will assume	that mailbox files can be found	in the
	      directory	specified.  It defaults	to `~/Mail'.

       match-original
	      This is used by the _match completer.  If	it  is	set  to	 only,
	      _match  will  try	to generate matches without inserting a	`*' at
	      the cursor position.  If set to any other	 non-empty  value,  it
	      will first try to	generate matches without inserting the `*' and
	      if that yields no	matches, it will try again with	 the  `*'  in-
	      serted.	If  it	is  unset or set to the	empty string, matching
	      will only	be performed with the `*' inserted.

       matcher
	      This style is tested separately for each tag valid in  the  cur-
	      rent  context.   Its value is placed before any match specifica-
	      tions given by the matcher-list style so can override  them  via
	      the use of an x: specification.  The value should	be in the form
	      described	in the section `Completion Matching Control'  in  zsh-
	      compwid(1).   For	 examples  of this, see	the description	of the
	      tag-order	style.

       matcher-list
	      This style can be	set to a list of match specifications that are
	      to  be applied everywhere. Match specifications are described in
	      the section `Completion Matching Control'	in zshcompwid(1).  The
	      completion  system will try them one after another for each com-
	      pleter selected.	For example, to	try  first  simple  completion
	      and, if that generates no	matches, case-insensitive completion:

		     zstyle ':completion:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}'

	      By  default  each	 specification replaces	the previous one; how-
	      ever, if a specification is prefixed with	+, it is added to  the
	      existing list.  Hence it is possible to create increasingly gen-
	      eral specifications without repetition:

		     zstyle ':completion:*' matcher-list \
			    '' '+m:{a-z}={A-Z}'	'+m:{A-Z}={a-z}'

	      It is possible to	create match specifications valid for particu-
	      lar  completers  by  using the third field of the	context.  This
	      applies  only   to   completers	that   override	  the	global
	      matcher-list, which as of	this writing includes only _prefix and
	      _ignored.	 For example, to  use  the  completers	_complete  and
	      _prefix  but  allow  case-insensitive completion only with _com-
	      plete:

		     zstyle ':completion:*' completer _complete	_prefix
		     zstyle ':completion:*:complete:*:*:*' matcher-list	\
			    '' 'm:{a-zA-Z}={A-Za-z}'

	      User-defined names, as explained for the	completer  style,  are
	      available.   This	 makes	it  possible to	try the	same completer
	      more than	once with different match  specifications  each	 time.
	      For example, to try normal completion without a match specifica-
	      tion, then normal	 completion  with  case-insensitive  matching,
	      then correction, and finally partial-word	completion:

		     zstyle ':completion:*' completer \
			 _complete _correct _complete:foo
		     zstyle ':completion:*:complete:*:*:*' matcher-list	\
			 '' 'm:{a-zA-Z}={A-Za-z}'
		     zstyle ':completion:*:foo:*:*:*' matcher-list \
			 'm:{a-zA-Z}={A-Za-z} r:|[-_./]=* r:|=*'

	      If  the  style is	unset in any context no	match specification is
	      applied.	Note also that some completers such  as	 _correct  and
	      _approximate  do not use the match specifications	at all,	though
	      these completers will only ever  be  called  once	 even  if  the
	      matcher-list contains more than one element.

	      Where  multiple  specifications are useful, note that the	entire
	      completion is done for each element of matcher-list,  which  can
	      quickly  reduce  the  shell's  performance.   As a rough rule of
	      thumb, one to three strings will	give  acceptable  performance.
	      On  the other hand, putting multiple space-separated values into
	      the same string does not have an appreciable impact  on  perfor-
	      mance.

	      If  there	 is  no	current	matcher	or it is empty,	and the	option
	      NO_CASE_GLOB is in effect, the matching for files	 is  performed
	      case-insensitively  in  any case.	 However, any matcher must ex-
	      plicitly specify case-insensitive	matching if that is required.

       max-errors
	      This is used by the _approximate and  _correct  completer	 func-
	      tions  to	 determine the maximum number of errors	to allow.  The
	      completer	will try to generate completions by first allowing one
	      error,  then  two	 errors,  and  so  on, until either a match or
	      matches were found or the	maximum	number of errors given by this
	      style has	been reached.

	      If  the  value for this style contains the string	`numeric', the
	      completer	function will take any numeric argument	as the maximum
	      number of	errors allowed.	For example, with

		     zstyle ':completion:*:approximate:::' max-errors 2	numeric

	      two errors are allowed if	no numeric argument is given, but with
	      a	numeric	argument of six	(as in `ESC-6 TAB'), up	to six	errors
	      are  accepted.  Hence with a value of `0 numeric', no correcting
	      completion will be attempted unless a numeric argument is	given.

	      If the value contains the	string	`not-numeric',	the  completer
	      will  not	try to generate	corrected completions when given a nu-
	      meric argument, so in this  case	the  number  given  should  be
	      greater  than zero.  For example,	`2 not-numeric'	specifies that
	      correcting completion with two errors will usually be performed,
	      but  if  a numeric argument is given, correcting completion will
	      not be performed.

	      The default value	for this style is `2 numeric'.

       max-matches-width
	      This style is used to determine the trade	off between the	 width
	      of the display used for matches and the width used for their de-
	      scriptions when the verbose style	is in effect.  The value gives
	      the  number  of display columns to reserve for the matches.  The
	      default is half the width	of the screen.

	      This has the most	impact when several matches have the same  de-
	      scription	and so will be grouped together.  Increasing the style
	      will allow more matches to be grouped  together;	decreasing  it
	      will allow more of the description to be visible.

       menu   If  this is `true' in the	context	of any of the tags defined for
	      the current completion menu completion will be used.  The	 value
	      for  a  specific tag will	take precedence	over that for the `de-
	      fault' tag.

	      If none of the values found in this way is `true'	but  at	 least
	      one  is set to `auto', the shell behaves as if the AUTO_MENU op-
	      tion is set.

	      If one of	the values is explicitly set to	`false', menu  comple-
	      tion will	be explicitly turned off, overriding the MENU_COMPLETE
	      option and other settings.

	      In the form `yes=num', where `yes' may be	any of the `true' val-
	      ues  (`yes',  `true',  `on'  and	`1'),  menu completion will be
	      turned on	if there are  at  least	 num  matches.	 In  the  form
	      `yes=long',  menu	 completion will be turned on if the list does
	      not fit on the screen.  This does	not activate  menu  completion
	      if  the widget normally only lists completions, but menu comple-
	      tion  can	 be  activated	 in   that   case   with   the	 value
	      `yes=long-list'  (Typically,  the	 value	`select=long-list' de-
	      scribed later  is	 more  useful  as  it  provides	 control  over
	      scrolling.)

	      Similarly,  with any of the `false' values (as in	`no=10'), menu
	      completion will not be used if there are num or more matches.

	      The value	of this	widget also controls menu selection, as	imple-
	      mented by	the zsh/complist module.  The following	values may ap-
	      pear either alongside or instead of the values above.

	      If the value contains the	string `select', menu  selection  will
	      be started unconditionally.

	      In the form `select=num',	menu selection will only be started if
	      there are	at least num matches.  If the values for more than one
	      tag provide a number, the	smallest number	is taken.

	      Menu  selection can be turned off	explicitly by defining a value
	      containing the string`no-select'.

	      It is also possible to start menu	selection only if the list  of
	      matches  does  not  fit  on  the	screen by using	the value `se-
	      lect=long'.  To start menu selection even	if the current	widget
	      only performs listing, use the value `select=long-list'.

	      To  turn on menu completion or menu selection when a there are a
	      certain number of	matches	or the list of matches does not	fit on
	      the  screen,  both  of  `yes=' and `select=' may be given	twice,
	      once with	a number and once with `long' or `long-list'.

	      Finally, it is possible to activate two special  modes  of  menu
	      selection.   The word `interactive' in the value causes interac-
	      tive mode	to be  entered	immediately  when  menu	 selection  is
	      started;	see the	description of the zsh/complist	module in zsh-
	      modules(1) for a description of interactive mode.	 Including the
	      string  `search'	does the same for incremental search mode.  To
	      select  backward	incremental   search,	include	  the	string
	      `search-backward'.

       muttrc If  set,	gives the location of the mutt configuration file.  It
	      defaults to `~/.muttrc'.

       numbers
	      This is used with	the jobs tag.  If it is	`true',	the shell will
	      complete	job numbers instead of the shortest unambiguous	prefix
	      of the job command text.	If the value is	a number, job  numbers
	      will  only  be used if that many words from the job descriptions
	      are required to resolve ambiguities.  For	example, if the	 value
	      is  `1',	strings	 will  only  be	used if	all jobs differ	in the
	      first word on their command lines.

       old-list
	      This is used by the _oldlist completer.  If it is	 set  to  `al-
	      ways',  then  standard widgets which perform listing will	retain
	      the current list of matches, however they	were  generated;  this
	      can  be turned off explicitly with the value `never', giving the
	      behaviour	without	the _oldlist completer.	 If the	style  is  un-
	      set,  or	any other value, then the existing list	of completions
	      is displayed if it is not	already; otherwise, the	standard  com-
	      pletion  list  is	 generated;  this  is the default behaviour of
	      _oldlist.	 However, if there is an old list and this style  con-
	      tains  the  name	of  the	 completer function that generated the
	      list, then the old list will be used even	if it was generated by
	      a	widget which does not do listing.

	      For  example, suppose you	type ^Xc to use	the _correct_word wid-
	      get, which generates a list of corrections for  the  word	 under
	      the  cursor.   Usually, typing ^D	would generate a standard list
	      of completions for the word on the command line, and show	 that.
	      With  _oldlist, it will instead show the list of corrections al-
	      ready generated.

	      As another example consider the _match completer:	with  the  in-
	      sert-unambiguous	style  set  to `true' it inserts only a	common
	      prefix string, if	there is any.  However,	this may remove	 parts
	      of  the  original	pattern, so that further completion could pro-
	      duce more	matches	than on	 the  first  attempt.	By  using  the
	      _oldlist completer and setting this style	to _match, the list of
	      matches generated	on the first attempt will be used again.

       old-matches
	      This is used by the _all_matches completer to decide if  an  old
	      list  of matches should be used if one exists.  This is selected
	      by one of	the `true' values or by	the  string  `only'.   If  the
	      value  is	 `only',  _all_matches	will  only use an old list and
	      won't have any effect on the list	 of  matches  currently	 being
	      generated.

	      If  this	style  is  set	it  is	generally  unwise  to call the
	      _all_matches completer unconditionally.  One possible use	is for
	      either  this style or the	completer style	to be defined with the
	      -e option	to zstyle to make the style conditional.

       old-menu
	      This is used by the _oldlist completer.  It  controls  how  menu
	      completion  behaves  when	a completion has already been inserted
	      and the user types a standard completion key such	as  TAB.   The
	      default  behaviour  of  _oldlist	is that	menu completion	always
	      continues	with the existing list of completions.	If this	 style
	      is  set  to `false', however, a new completion is	started	if the
	      old list was generated by	a different completion	command;  this
	      is the behaviour without the _oldlist completer.

	      For  example, suppose you	type ^Xc to generate a list of correc-
	      tions, and menu completion is started in one of the usual	 ways.
	      Usually,	or  with this style set	to `false', typing TAB at this
	      point would start	trying to complete the line as it now appears.
	      With _oldlist, it	instead	continues to cycle through the list of
	      corrections.

       original
	      This is used by the _approximate and _correct completers to  de-
	      cide  if	the original string should be added as a possible com-
	      pletion.	Normally, this is done only if there are at least  two
	      possible	corrections, but if this style is set to `true', it is
	      always added.  Note that the style will  be  examined  with  the
	      completer	 field	in  the	context	name set to correct-num	or ap-
	      proximate-num, where num is the number of	errors that  were  ac-
	      cepted.

       packageset
	      This  style  is  used  when  completing  arguments of the	Debian
	      `dpkg' program.  It contains an override for the default package
	      set for a	given context.	For example,

		     zstyle ':completion:*:complete:dpkg:option--status-1:*' \
				    packageset avail

	      causes  available	packages, rather than only installed packages,
	      to be completed for `dpkg	--status'.

       path   The function that	completes color	names uses this	style with the
	      colors tag.  The value should be the pathname of a file contain-
	      ing color	names in the format of an X11 rgb.txt  file.   If  the
	      style  is	not set	but this file is found in one of various stan-
	      dard locations it	will be	used as	the default.

       path-completion
	      This is used by filename completion.  By default,	filename  com-
	      pletion  examines	 all  components of a path to see if there are
	      completions of that component.  For example, /u/b/z can be  com-
	      pleted  to  /usr/bin/zsh.	  Explicitly  setting  this  style  to
	      `false' inhibits this behaviour for path components up to	the  /
	      before  the  cursor;  this  overrides  the setting of accept-ex-
	      act-dirs.

	      Even with	the style set to `false', it is	still possible to com-
	      plete  multiple paths by setting the option COMPLETE_IN_WORD and
	      moving the cursor	back to	the first component in the path	to  be
	      completed.  For example, /u/b/z can be completed to /usr/bin/zsh
	      if the cursor is after the /u.

       pine-directory
	      If set, specifies	the directory containing PINE  mailbox	files.
	      There  is	no default, since recursively searching	this directory
	      is inconvenient for anyone who doesn't use PINE.

       ports  A	list of	Internet service names (network	 ports)	 to  complete.
	      If  this	is  not	 set,  service	names  are taken from the file
	      `/etc/services'.

       prefix-hidden
	      This is used for certain completions which share a  common  pre-
	      fix,  for	 example command options beginning with	dashes.	 If it
	      is `true', the prefix will not be	shown in the list of matches.

	      The default value	for this style is `false'.

       prefix-needed
	      This style is also relevant for matches with  a  common  prefix.
	      If  it  is set to	`true' this common prefix must be typed	by the
	      user to generate the matches.

	      The style	is applicable to the  options,	signals,  jobs,	 func-
	      tions, and parameters completion tags.

	      For  command  options,  this means that the initial `-', `+', or
	      `--' must	be typed explicitly before option names	will  be  com-
	      pleted.

	      For signals, an initial `-' is required before signal names will
	      be completed.

	      For jobs,	an initial `%' is required before job  names  will  be
	      completed.

	      For  function  and parameter names, an initial `_' or `.'	is re-
	      quired before function or	parameter names	 starting  with	 those
	      characters will be completed.

	      The default value	for this style is `false' for function and pa-
	      rameter completions, and	`true' otherwise.

       preserve-prefix
	      This style is used when completing path names.  Its value	should
	      be  a pattern matching an	initial	prefix of the word to complete
	      that should be left unchanged under all circumstances.  For  ex-
	      ample,  on some Unices an	initial	`//' (double slash) has	a spe-
	      cial meaning; setting this style to the string  `//'  will  pre-
	      serve it.	 As another example, setting this style	to `?:/' under
	      Cygwin would allow completion after `a:/...' and so on.

       range  This is used by the _history  completer  and  the	 _history_com-
	      plete_word bindable command to decide which words	should be com-
	      pleted.

	      If it is a single	number,	only the last N	words from the history
	      will be completed.

	      If  it  is a range of the	form `max:slice', the last slice words
	      will be completed; then if that yields  no  matches,  the	 slice
	      words  before those will be tried	and so on.  This process stops
	      either when at least one match has been found, or	max words have
	      been tried.

	      The default is to	complete all words from	the history at once.

       recursive-files
	      If  this	style  is set, its value is an array of	patterns to be
	      tested against `$PWD/': note the trailing	 slash,	 which	allows
	      directories  in the pattern to be	delimited unambiguously	by in-
	      cluding slashes on both sides.  If an ordinary  file  completion
	      fails  and  the word on the command line does not	yet have a di-
	      rectory part to its name,	the style is retrieved using the  same
	      tag  as  for  the	 completion  just attempted, then the elements
	      tested against $PWD/ in turn.  If	one matches,  then  the	 shell
	      reattempts completion by prepending the word on the command line
	      with each	directory in the expansion of **/*(/) in turn.	 Typi-
	      cally the	elements of the	style will be set to restrict the num-
	      ber of directories beneath the current one to a manageable  num-
	      ber, for example `*/.git/*'.

	      For example,

		     zstyle ':completion:*' recursive-files '*/zsh/*'

	      If  the  current	directory is /home/pws/zsh/Src,	then zle_trTAB
	      can be completed to Zle/zle_tricky.c.

       regular
	      This style is used by the	_expand_alias completer	 and  bindable
	      command.	 If  set to `true' (the	default), regular aliases will
	      be expanded but only in command  position.   If  it  is  set  to
	      `false',	regular	aliases	will never be expanded.	  If it	is set
	      to `always', regular aliases will	be expanded  even  if  not  in
	      command position.

       rehash If  this	is set when completing external	commands, the internal
	      list (hash) of commands will be updated for each search by issu-
	      ing the rehash command.  There is	a speed	penalty	for this which
	      is only likely to	be noticeable when  directories	 in  the  path
	      have slow	file access.

       remote-access
	      If  set to `false', certain commands will	be prevented from mak-
	      ing Internet connections to retrieve remote  information.	  This
	      includes the completion for the CVS command.

	      It  is not always	possible to know if connections	are in fact to
	      a	remote site, so	some may be prevented unnecessarily.

       remove-all-dups
	      The _history_complete_word bindable  command  and	 the  _history
	      completer	 use this to decide if all duplicate matches should be
	      removed, rather than just	consecutive duplicates.

       select-prompt
	      If this is set for the default tag, its value will be  displayed
	      during  menu  selection (see the menu style above) when the com-
	      pletion list does	not fit	on the screen as a  whole.   The  same
	      escapes as for the list-prompt style are understood, except that
	      the numbers refer	to the match or	line the mark is  on.	A  de-
	      fault prompt is used when	the value is the empty string.

       select-scroll
	      This  style  is  tested for the default tag and determines how a
	      completion list is scrolled during a  menu  selection  (see  the
	      menu  style  above) when the completion list does	not fit	on the
	      screen as	a whole.  If the value is  `0'	(zero),	 the  list  is
	      scrolled	by  half-screenfuls;  if it is a positive integer, the
	      list is scrolled by the given number of lines; if	it is a	 nega-
	      tive number, the list is scrolled	by a screenful minus the abso-
	      lute value of the	given number of	 lines.	  The  default	is  to
	      scroll by	single lines.

       separate-sections
	      This style is used with the manuals tag when completing names of
	      manual pages.  If	it is `true', entries for  different  sections
	      are  added  separately  using  tag names of the form `manual.X',
	      where X is the section number.  When  the	 group-name  style  is
	      also  in effect, pages from different sections will appear sepa-
	      rately.  This style is also used similarly with the words	 style
	      when completing words for	the dict command. It allows words from
	      different	dictionary databases to	be added separately.  The  de-
	      fault for	this style is `false'.

       show-ambiguity
	      If  the zsh/complist module is loaded, this style	can be used to
	      highlight	the first ambiguous character in completion lists. The
	      value  is	 either	 a color indication such as those supported by
	      the list-colors style or,	with a value of	`true',	a  default  of
	      underlining is selected. The highlighting	is only	applied	if the
	      completion display strings correspond to the actual matches.

       show-completer
	      Tested whenever a	new completer is tried.	 If it is `true',  the
	      completion system	outputs	a progress message in the listing area
	      showing what completer is	being  tried.	The  message  will  be
	      overwritten  by any output when completions are found and	is re-
	      moved after completion is	finished.

       single-ignored
	      This is used by the _ignored completer when there	 is  only  one
	      match.   If  its	value is `show', the single match will be dis-
	      played but not inserted.	If the value is	`menu',	then the  sin-
	      gle  match and the original string are both added	as matches and
	      menu completion is started, making it easy to select  either  of
	      them.

       sort   Many  completion	widgets	 call _description at some point which
	      decides whether the matches are added sorted or unsorted	(often
	      indirectly  via  _wanted	or _requested).	 This style can	be set
	      explicitly to one	of the usual `true' or `false'	values	as  an
	      override.	 If it is not set for the context, the standard	behav-
	      iour of the calling widget is used.

	      The style	is tested first	against	the full context including the
	      tag,  and	 if  that fails	to produce a value against the context
	      without the tag.

	      If the calling widget explicitly requests	unsorted matches, this
	      is  usually honoured.  However, the default (unsorted) behaviour
	      of completion for	the command history may	be overridden by  set-
	      ting the style to	`true'.

	      In the _expand completer,	if it is set to	`true',	the expansions
	      generated	will always be sorted.	If it is set to	 `menu',  then
	      the  expansions  are only	sorted when they are offered as	single
	      strings but not in the string  containing	 all  possible	expan-
	      sions.

       special-dirs
	      Normally,	 the  completion  code	will not produce the directory
	      names `.'	and `..' as possible completions.  If  this  style  is
	      set to `true', it	will add both `.' and `..' as possible comple-
	      tions; if	it is set to `..', only	`..' will be added.

	      The following example sets special-dirs to `..' when the current
	      prefix is	empty, is a single `.',	or consists only of a path be-
	      ginning with `../'.  Otherwise the value is `false'.

		     zstyle -e ':completion:*' special-dirs \
			'[[ $PREFIX = (../)#(|.|..) ]] && reply=(..)'

       squeeze-slashes
	      If set to	`true',	sequences of slashes in	 filename  paths  (for
	      example  in `foo//bar') will be treated as a single slash.  This
	      is the usual behaviour of	UNIX paths.  However, by  default  the
	      file  completion function	behaves	as if there were a `*' between
	      the slashes.

       stop   If set to	`true',	the  _history_complete_word  bindable  command
	      will  stop  once	when reaching the beginning or end of the his-
	      tory.  Invoking _history_complete_word will then wrap around  to
	      the  opposite  end  of  the  history.   If  this style is	set to
	      `false' (the default), _history_complete_word will loop  immedi-
	      ately as in a menu completion.

       strip-comments
	      If  set  to `true', this style causes non-essential comment text
	      to be removed from completion matches.   Currently  it  is  only
	      used  when completing e-mail addresses where it removes any dis-
	      play name	 from  the  addresses,	cutting	 them  down  to	 plain
	      user@host	form.

       subst-globs-only
	      This  is used by the _expand completer.  If it is	set to `true',
	      the expansion will only be used if it  resulted  from  globbing;
	      hence,  if  expansions  resulted	from the use of	the substitute
	      style described below, but these were  not  further  changed  by
	      globbing,	the expansions will be rejected.

	      The default for this style is `false'.

       substitute
	      This  boolean  style controls whether the	_expand	completer will
	      first try	to expand all substitutions in	the  string  (such  as
	      `$(...)' and `${...}').

	      The default is `true'.

       suffix This  is used by the _expand completer if	the word starts	with a
	      tilde or contains	a  parameter  expansion.   If  it  is  set  to
	      `true', the word will only be expanded if	it doesn't have	a suf-
	      fix, i.e.	if it is something like	`~foo' or `$foo'  rather  than
	      `~foo/'  or `$foo/bar', unless that suffix itself	contains char-
	      acters eligible for expansion.  The default for  this  style  is
	      `true'.

       tag-order
	      This  provides a mechanism for sorting how the tags available in
	      a	particular context will	be used.

	      The values for the style are sets	of  space-separated  lists  of
	      tags.  The tags in each value will be tried at the same time; if
	      no match is found, the next value	is used.  (See	the  file-pat-
	      terns style for an exception to this behavior.)

	      For example:

		     zstyle ':completion:*:complete:-command-:*:*' tag-order \
			 'commands functions'

	      specifies	 that  completion in command position first offers ex-
	      ternal commands and shell	functions.   Remaining	tags  will  be
	      tried if no completions are found.

	      In  addition to tag names, each string in	the value may take one
	      of the following forms:

	      -	     If	any value consists of only a  hyphen,  then  only  the
		     tags  specified  in the other values are generated.  Nor-
		     mally all tags not	explicitly selected are	tried last  if
		     the  specified  tags  fail	to generate any	matches.  This
		     means that	a single value consisting only of a single hy-
		     phen turns	off completion.

	      !	tags...
		     A	string	starting  with	an  exclamation	mark specifies
		     names of tags that	are not	to be used.  The effect	is the
		     same  as  if  all other possible tags for the context had
		     been listed.

	      tag:label	...
		     Here, tag is one of the standard tags and label is	an ar-
		     bitrary  name.   Matches  are generated as	normal but the
		     name label	is used	in contexts instead of tag.   This  is
		     not useful	in words starting with !.

		     If	 the  label starts with	a hyphen, the tag is prepended
		     to	the label to form the name used	for lookup.  This  can
		     be	 used  to make the completion system try a certain tag
		     more than once, supplying different  style	 settings  for
		     each attempt; see below for an example.

	      tag:label:description
		     As	 before,  but description will replace the `%d'	in the
		     value of the format style instead of the default descrip-
		     tion  supplied by the completion function.	 Spaces	in the
		     description must be quoted	with a backslash.  A `%d'  ap-
		     pearing  in  description is replaced with the description
		     given by the completion function.

	      In any of	the forms above	the tag	may be a  pattern  or  several
	      patterns	in the form `{pat1,pat2...}'.  In this case all	match-
	      ing tags will be used except for any  given  explicitly  in  the
	      same string.

	      One use of these features	is to try one tag more than once, set-
	      ting other styles	differently on each attempt, but still to  use
	      all the other tags without having	to repeat them all.  For exam-
	      ple, to make completion of function names	 in  command  position
	      ignore  all the completion functions starting with an underscore
	      the first	time completion	is tried:

		     zstyle ':completion:*:*:-command-:*:*' tag-order \
			 'functions:-non-comp *' functions
		     zstyle ':completion:*:functions-non-comp' \
			 ignored-patterns '_*'

	      On the first attempt, all	tags will be offered but the functions
	      tag  will	 be  replaced by functions-non-comp.  The ignored-pat-
	      terns style is set for this tag to  exclude  functions  starting
	      with  an	underscore.  If	there are no matches, the second value
	      of the tag-order style is	used which completes  functions	 using
	      the  default  tag,  this	time presumably	including all function
	      names.

	      The matches for one tag can be split into	different groups.  For
	      example:

		     zstyle ':completion:*' tag-order \
			 'options:-long:long\ options
			  options:-short:short\	options
			  options:-single-letter:single\ letter\ options'
		     zstyle ':completion:*:options-long' \
			  ignored-patterns '[-+](|-|[^-]*)'
		     zstyle ':completion:*:options-short' \
			  ignored-patterns '--*' '[-+]?'
		     zstyle ':completion:*:options-single-letter' \
			  ignored-patterns '???*'

	      With the group-names style set, options beginning	with `--', op-
	      tions beginning with a single `-'	or `+' but containing multiple
	      characters, and single-letter options will be displayed in sepa-
	      rate groups with different descriptions.

	      Another use of patterns is to try	multiple match	specifications
	      one after	another.  The matcher-list style offers	something sim-
	      ilar, but	it is tested very early	in the completion  system  and
	      hence  can't  be	set  for single	commands nor for more specific
	      contexts.	 Here is how to	 try  normal  completion  without  any
	      match specification and, if that generates no matches, try again
	      with case-insensitive matching, restricting the effect to	 argu-
	      ments of the command foo:

		     zstyle ':completion:*:*:foo:*:*' tag-order	'*' '*:-case'
		     zstyle ':completion:*-case' matcher 'm:{a-z}={A-Z}'

	      First,  all the tags offered when	completing after foo are tried
	      using the	normal tag name.  If that generates  no	 matches,  the
	      second  value  of	 tag-order is used, which tries	all tags again
	      except that this time each has -case appended to	its  name  for
	      lookup  of  styles.   Hence  this	time the value for the matcher
	      style from the second call to zstyle in the example is  used  to
	      make completion case-insensitive.

	      It  is  possible to use the -e option of the zstyle builtin com-
	      mand to specify conditions for the use of	particular tags.   For
	      example:

		     zstyle -e '*:-command-:*' tag-order '
			 if [[ -n $PREFIX$SUFFIX ]]; then
			   reply=( )
			 else
			   reply=( - )
			 fi'

	      Completion  in  command  position	 will be attempted only	if the
	      string typed so far is not empty.	 This is tested	using the PRE-
	      FIX  special  parameter; see zshcompwid for a description	of pa-
	      rameters which are special inside	completion  widgets.   Setting
	      reply to an empty	array provides the default behaviour of	trying
	      all tags at once;	setting	it to an array containing only	a  hy-
	      phen disables the	use of all tags	and hence of all completions.

	      If  no  tag-order	 style	has  been  defined  for	a context, the
	      strings `(|*-)argument-*	(|*-)option-*  values'	and  `options'
	      plus all tags offered by the completion function will be used to
	      provide  a  sensible  default  behavior  that  causes  arguments
	      (whether normal command arguments	or arguments of	options) to be
	      completed	before option names for	most commands.

       urls   This is used together with the urls tag by functions  completing
	      URLs.

	      If  the  value  consists of more than one	string,	or if the only
	      string does not name a file or directory,	the strings  are  used
	      as the URLs to complete.

	      If  the  value  contains	only one string	which is the name of a
	      normal file the URLs are taken from that file  (where  the  URLs
	      may be separated by white	space or newlines).

	      Finally,	if the only string in the value	names a	directory, the
	      directory	hierarchy rooted at this directory gives  the  comple-
	      tions.   The  top	 level	directory  should  be  the file	access
	      method, such as `http', `ftp', `bookmark'	and so	on.   In  many
	      cases the	next level of directories will be a filename.  The di-
	      rectory hierarchy	can descend as deep as necessary.

	      For example,

		     zstyle ':completion:*' urls ~/.urls
		     mkdir -p ~/.urls/ftp/ftp.zsh.org/pub

	      allows  completion  of   all   the   components	of   the   URL
	      ftp://ftp.zsh.org/pub after suitable commands such as `netscape'
	      or `lynx'.  Note,	however, that access  methods  and  files  are
	      completed	 separately, so	if the hosts style is set hosts	can be
	      completed	without	reference to the urls style.

	      See the description in the function _urls	itself for more	infor-
	      mation (e.g. `more $^fpath/_urls(N)').

       use-cache
	      If  this	is  set, the completion	caching	layer is activated for
	      any  completions	which  use  it	(via  the  _store_cache,  _re-
	      trieve_cache, and	_cache_invalid functions).  The	directory con-
	      taining the cache	files  can  be	changed	 with  the  cache-path
	      style.

       use-compctl
	      If  this style is	set to a string	not equal to false, 0, no, and
	      off, the completion system may use any completion	specifications
	      defined  with  the compctl builtin command.  If the style	is un-
	      set, this	is done	only if	the zsh/compctl	module is loaded.  The
	      string may also contain the substring `first' to use completions
	      defined with `compctl -T', and the substring  `default'  to  use
	      the completion defined with `compctl -D'.

	      Note  that  this	is only	intended to smooth the transition from
	      compctl to the new completion system and may  disappear  in  the
	      future.

	      Note also	that the definitions from compctl will only be used if
	      there is no specific completion  function	 for  the  command  in
	      question.	  For example, if there	is a function _foo to complete
	      arguments	to the command foo, compctl will never be invoked  for
	      foo.   However,  the  compctl  version will be tried if foo only
	      uses default completion.

       use-ip By default, the function _hosts that completes host names	strips
	      IP  addresses  from entries read from host databases such	as NIS
	      and ssh files.  If this style is `true',	the  corresponding  IP
	      addresses	 can  be  completed as well.  This style is not	use in
	      any context where	the hosts style	is set;	note also it  must  be
	      set  before  the cache of	host names is generated	(typically the
	      first completion attempt).

       users  This may be set to a list	of usernames to	be completed.	If  it
	      is  not set all usernames	will be	completed.  Note that if it is
	      set only that list of users will be completed; this  is  because
	      on some systems querying all users can take a prohibitive	amount
	      of time.

       users-hosts
	      The values of this style should be of the	 form  `user@host'  or
	      `user:host'.  It	is  used for commands that need	pairs of user-
	      and hostnames.  These commands will complete usernames from this
	      style  (only),  and will restrict	subsequent hostname completion
	      to hosts paired with that	user in	 one  of  the  values  of  the
	      style.

	      It  is possible to group values for sets of commands which allow
	      a	remote login, such as rlogin and ssh, by using the my-accounts
	      tag.  Similarly, values for sets of commands which usually refer
	      to the accounts of other people, such as talk and	finger,	can be
	      grouped  by  using the other-accounts tag.  More ambivalent com-
	      mands may	use the	accounts tag.

       users-hosts-ports
	      Like users-hosts but used	for commands like telnet and  contain-
	      ing strings of the form `user@host:port'.

       verbose
	      If set, as it is by default, the completion listing is more ver-
	      bose.  In	particular many	commands show descriptions for options
	      if this style is `true'.

       word   This  is	used by	the _list completer, which prevents the	inser-
	      tion of completions until	a second completion attempt  when  the
	      line has not changed.  The normal	way of finding out if the line
	      has changed is to	compare	its entire contents  between  the  two
	      occasions.   If  this style is `true', the comparison is instead
	      performed	only on	the current word.  Hence if completion is per-
	      formed  on  another word with the	same contents, completion will
	      not be delayed.

CONTROL	FUNCTIONS
       The initialization script compinit redefines all	the widgets which per-
       form  completion	 to  call the supplied widget function _main_complete.
       This function acts as a wrapper calling the so-called `completer' func-
       tions  that  generate  matches.	If _main_complete is called with argu-
       ments, these are	taken as the names of completer	functions to be	called
       in the order given.  If no arguments are	given, the set of functions to
       try is taken from the completer style.  For example, to use normal com-
       pletion and correction if that doesn't generate any matches:

	      zstyle ':completion:*' completer _complete _correct

       after  calling compinit.	The default value for this style is `_complete
       _ignored', i.e. normally	only ordinary completion is tried, first  with
       the  effect  of	the  ignored-patterns  style and then without it.  The
       _main_complete function uses the	return status of the  completer	 func-
       tions  to  decide  if other completers should be	called.	 If the	return
       status is zero, no other	completers are tried  and  the	_main_complete
       function	returns.

       If  the	first argument to _main_complete is a single hyphen, the argu-
       ments will not be taken as names	of completers.	 Instead,  the	second
       argument	 gives a name to use in	the completer field of the context and
       the other arguments give	a command name and arguments to	call to	gener-
       ate the matches.

       The  following  completer  functions are	contained in the distribution,
       although	users may write	their own.  Note that in contexts the  leading
       underscore  is  stripped,  for example basic completion is performed in
       the context `:completion::complete:...'.

       _all_matches
	      This completer can be used to add	a  string  consisting  of  all
	      other matches.  As it influences later completers	it must	appear
	      as the first completer in	the list.  The list of all matches  is
	      affected by the avoid-completer and old-matches styles described
	      above.

	      It may be	useful to use the _generic function described below to
	      bind _all_matches	to its own keystroke, for example:

		     zle -C all-matches	complete-word _generic
		     bindkey '^Xa' all-matches
		     zstyle ':completion:all-matches:*'	old-matches only
		     zstyle ':completion:all-matches::::' completer _all_matches

	      Note  that  this does not	generate completions by	itself:	 first
	      use any of the standard ways of generating  a  list  of  comple-
	      tions, then use ^Xa to show all matches.	It is possible instead
	      to add a standard	completer to the list  and  request  that  the
	      list of all matches should be directly inserted:

		     zstyle ':completion:all-matches::::' completer \
			    _all_matches _complete
		     zstyle ':completion:all-matches:*'	insert true

	      In this case the old-matches style should	not be set.

       _approximate
	      This  is similar to the basic _complete completer	but allows the
	      completions to undergo corrections.  The maximum number  of  er-
	      rors  can	be specified by	the max-errors style; see the descrip-
	      tion of approximate matching in zshexpn(1) for  how  errors  are
	      counted.	 Normally  this	completer will only be tried after the
	      normal _complete completer:

		     zstyle ':completion:*' completer _complete	_approximate

	      This will	give correcting	completion if and only if normal  com-
	      pletion  yields no possible completions.	When corrected comple-
	      tions are	found, the completer will normally start menu  comple-
	      tion allowing you	to cycle through these strings.

	      This  completer uses the tags corrections	and original when gen-
	      erating the possible corrections and the original	 string.   The
	      format style for the former may contain the additional sequences
	      `%e' and `%o' which will be replaced by the number of errors ac-
	      cepted  to generate the corrections and the original string, re-
	      spectively.

	      The completer progressively increases the	number of  errors  al-
	      lowed  up	 to the	limit by the max-errors	style, hence if	a com-
	      pletion is found with one	error, no completions with two	errors
	      will be shown, and so on.	 It modifies the completer name	in the
	      context to indicate the number of	errors	being  tried:  on  the
	      first  try  the completer	field contains `approximate-1',	on the
	      second try `approximate-2', and so on.

	      When _approximate	is called from another function, the number of
	      errors to	accept may be passed with the -a option.  The argument
	      is in the	same format  as	 the  max-errors  style,  all  in  one
	      string.

	      Note  that  this completer (and the _correct completer mentioned
	      below) can be quite expensive to call, especially	when  a	 large
	      number  of  errors are allowed.  One way to avoid	this is	to set
	      up the completer style using the -e option  to  zstyle  so  that
	      some  completers	are  only  used	when completion	is attempted a
	      second time on the same string, e.g.:

		     zstyle -e ':completion:*' completer '
		       if [[ $_last_try	!= "$HISTNO$BUFFER$CURSOR" ]]; then
			 _last_try="$HISTNO$BUFFER$CURSOR"
			 reply=(_complete _match _prefix)
		       else
			 reply=(_ignored _correct _approximate)
		       fi'

	      This uses	the HISTNO parameter and the BUFFER and	CURSOR special
	      parameters  that are available inside zle	and completion widgets
	      to find out if the command line hasn't changed  since  the  last
	      time completion was tried.  Only then are	the _ignored, _correct
	      and _approximate completers called.

       _canonical_paths	[ -A var ] [ -N	] [ -MJV12nfX ]	tag descr [ paths  ...
       ]
	      This  completion	function  completes all	paths given to it, and
	      also tries to offer completions which point to the same file  as
	      one  of  the paths given (relative path when an absolute path is
	      given, and vice versa; when ..'s are present in the word	to  be
	      completed; and some paths	got from symlinks).

	      -A, if specified,	takes the paths	from the array variable	speci-
	      fied. Paths can also be specified	on the command line  as	 shown
	      above.   -N,  if	specified,  prevents  canonicalizing the paths
	      given before using them for completion, in case they are already
	      so.  The	options	 -M,  -J, -V, -1, -2, -n, -F, -X are passed to
	      compadd.

	      See _description for a description of tag	and descr.

       _complete
	      This completer generates all  possible  completions  in  a  con-
	      text-sensitive  manner, i.e. using the settings defined with the
	      compdef function explained above and the current settings	of all
	      special parameters.  This	gives the normal completion behaviour.

	      To  complete  arguments  of commands, _complete uses the utility
	      function _normal,	which is in turn responsible for  finding  the
	      particular function; it is described below.  Various contexts of
	      the form -context- are handled specifically. These are all  men-
	      tioned above as possible arguments to the	#compdef tag.

	      Before  trying  to find a	function for a specific	context, _com-
	      plete checks if the  parameter  `compcontext'  is	 set.  Setting
	      `compcontext'  allows  the  usual	 completion  dispatching to be
	      overridden which is useful in places such	 as  a	function  that
	      uses vared for input. If it is set to an array, the elements are
	      taken to be the possible matches which will be  completed	 using
	      the tag `values' and the description `value'. If it is set to an
	      associative array, the keys are used as the possible completions
	      and  the	values (if non-empty) are used as descriptions for the
	      matches.	If `compcontext' is set	to a string containing colons,
	      it  should  be of	the form `tag:descr:action'.  In this case the
	      tag and descr give the tag and description to use	and the	action
	      indicates	 what should be	completed in one of the	forms accepted
	      by the _arguments	utility	function described below.

	      Finally, if `compcontext'	is set to a string without colons, the
	      value  is	 taken as the name of the context to use and the func-
	      tion defined for that context will be called.  For this purpose,
	      there  is	 a special context named -command-line-	that completes
	      whole command lines (commands and	their arguments).  This	is not
	      used  by the completion system itself but	is nonetheless handled
	      when explicitly called.

       _correct
	      Generate corrections, but	not completions, for the current word;
	      this is similar to _approximate but will not allow any number of
	      extra characters at the cursor as	that completer does.  The  ef-
	      fect is similar to spell-checking.  It is	based on _approximate,
	      but the completer	field in the context name is correct.

	      For example, with:

		     zstyle ':completion:::::' completer \
			    _complete _correct _approximate
		     zstyle ':completion:*:correct:::' max-errors 2 not-numeric
		     zstyle ':completion:*:approximate:::' max-errors 3	numeric

	      correction will accept up	to two errors.	If a numeric  argument
	      is  given, correction will not be	performed, but correcting com-
	      pletion will be, and will	accept as many errors as given by  the
	      numeric  argument.  Without a numeric argument, first correction
	      and then correcting completion will be tried, with the first one
	      accepting	two errors and the second one accepting	three errors.

	      When  _correct  is called	as a function, the number of errors to
	      accept may be given following the	-a option.  The	argument is in
	      the same form a values to	the accept style, all in one string.

	      This  completer function is intended to be used without the _ap-
	      proximate	completer or, as in the	example, just before it.   Us-
	      ing  it  after  the _approximate completer is useless since _ap-
	      proximate	will at	least generate the corrected strings generated
	      by the _correct completer	-- and probably	more.

       _expand
	      This  completer function does not	really perform completion, but
	      instead checks if	the word on the	command	line is	 eligible  for
	      expansion	 and,  if  it is, gives	detailed control over how this
	      expansion	is done.  For this to happen,  the  completion	system
	      needs  to	 be invoked with complete-word,	not expand-or-complete
	      (the default binding for TAB), as	otherwise the string  will  be
	      expanded by the shell's internal mechanism before	the completion
	      system is	started.  Note also this completer  should  be	called
	      before the _complete completer function.

	      The  tags	used when generating expansions	are all-expansions for
	      the string containing all	possible expansions,  expansions  when
	      adding  the  possible  expansions	as single matches and original
	      when adding the original string from the	line.	The  order  in
	      which  these strings are generated, if at	all, can be controlled
	      by the group-order and tag-order styles, as usual.

	      The format string	for all-expansions and for expansions may con-
	      tain  the	 sequence  `%o'	which will be replaced by the original
	      string from the line.

	      The kind of expansion to be tried	is controlled by  the  substi-
	      tute, glob and subst-globs-only styles.

	      It is also possible to call _expand as a function, in which case
	      the different modes may be selected with options:	-s for substi-
	      tute, -g for glob	and -o for subst-globs-only.

       _expand_alias
	      If  the word the cursor is on is an alias, it is expanded	and no
	      other completers are called.  The	types of aliases which are  to
	      be  expanded  can	 be controlled with the	styles regular,	global
	      and disabled.

	      This function is also a bindable command,	see the	section	`Bind-
	      able Commands' below.

       _extensions
	      If  the  cursor follows the string `*.', filename	extensions are
	      completed. The extensions	are taken from files in	current	direc-
	      tory  or	a  directory specified at the beginning	of the current
	      word. For	exact matches, completion  continues  to  allow	 other
	      completers  such	as _expand to expand the pattern. The standard
	      add-space	and prefix-hidden styles are observed.

       _external_pwds
	      Completes	current	directories of other zsh  processes  belonging
	      to the current user.

	      This  is intended	to be used via _generic, bound to a custom key
	      combination. Note	that pattern matching is enabled  so  matching
	      is performed similar to how it works with	the _match completer.

       _history
	      Complete	words  from  the  shell's command  history.  This com-
	      pleter can be controlled by the remove-all-dups, and sort	styles
	      as for the _history_complete_word	bindable command, see the sec-
	      tion `Bindable Commands' below and the section `Completion  Sys-
	      tem Configuration' above.

       _ignored
	      The  ignored-patterns  style  can	 be  set to a list of patterns
	      which are	compared against possible completions;	matching  ones
	      are  removed.   With  this  completer those matches can be rein-
	      stated, as if no ignored-patterns	style were set.	 The completer
	      actually generates its own list of matches; which	completers are
	      invoked is determined in the same	way as for  the	 _prefix  com-
	      pleter.  The single-ignored style	is also	available as described
	      above.

       _list  This completer allows the	insertion of matches to	be delayed un-
	      til  completion  is  attempted a second time without the word on
	      the line being changed.  On the first attempt, only the list  of
	      matches  will  be	shown.	It is affected by the styles condition
	      and word,	see  the  section  `Completion	System	Configuration'
	      above.

       _match This  completer  is intended to be used after the	_complete com-
	      pleter.  It behaves similarly but	the string on the command line
	      may be a pattern to match	against	trial completions.  This gives
	      the effect of the	GLOB_COMPLETE option.

	      Normally completion will be performed by taking the pattern from
	      the  line,  inserting a `*' at the cursor	position and comparing
	      the resulting pattern with the possible  completions  generated.
	      This  can	 be  modified  with the	match-original style described
	      above.

	      The generated matches will be offered in a menu  completion  un-
	      less  the	insert-unambiguous style is set	to `true'; see the de-
	      scription	above for other	options	for this style.

	      Note that	matcher	specifications defined globally	or used	by the
	      completion  functions (the styles	matcher-list and matcher) will
	      not be used.

       _menu  This completer was written as simple example  function  to  show
	      how  menu	 completion  can be enabled in shell code. However, it
	      has the notable effect of	disabling menu selection which can  be
	      useful  with  _generic  based  widgets. It should	be used	as the
	      first completer in the list.  Note that this is  independent  of
	      the  setting  of the MENU_COMPLETE option	and does not work with
	      the other	menu completion	widgets	such as	reverse-menu-complete,
	      or accept-and-menu-complete.

       _oldlist
	      This  completer controls how the standard	completion widgets be-
	      have when	there is an existing list  of  completions  which  may
	      have  been  generated  by	 a  special  completion	 (i.e. a sepa-
	      rately-bound completion command).	 It allows the	ordinary  com-
	      pletion  keys  to	 continue  to use the list of completions thus
	      generated, instead of producing a	new list of  ordinary  contex-
	      tual  completions.   It  should appear in	the list of completers
	      before any of the	widgets	which generate matches.	 It  uses  two
	      styles:  old-list	and old-menu, see the section `Completion Sys-
	      tem Configuration' above.

       _prefix
	      This completer can be used to try	 completion  with  the	suffix
	      (everything after	the cursor) ignored.  In other words, the suf-
	      fix will not be considered to be part of the word	 to  complete.
	      The effect is similar to the expand-or-complete-prefix command.

	      The completer style is used to decide which other	completers are
	      to be called to generate matches.	 If this style is  unset,  the
	      list  of	completers  set	for the	current	context	is used	-- ex-
	      cept, of course, the _prefix completer itself.  Furthermore,  if
	      this  completer appears more than	once in	the list of completers
	      only those completers not	already	tried by the  last  invocation
	      of _prefix will be called.

	      For example, consider this global	completer style:

		     zstyle ':completion:*' completer \
			 _complete _prefix _correct _prefix:foo

	      Here, the	_prefix	completer tries	normal completion but ignoring
	      the suffix.  If that doesn't generate any	matches,  and  neither
	      does  the	 call to the _correct completer	after it, _prefix will
	      be called	a second time and, now only trying correction with the
	      suffix  ignored.	On the second invocation the completer part of
	      the context appears as `foo'.

	      To use _prefix as	the last resort	and try	only normal completion
	      when it is invoked:

		     zstyle ':completion:*' completer _complete	... _prefix
		     zstyle ':completion::prefix:*' completer _complete

	      The  add-space  style is also respected.	If it is set to	`true'
	      then _prefix will	insert a space between the  matches  generated
	      (if any) and the suffix.

	      Note  that this completer	is only	useful if the COMPLETE_IN_WORD
	      option is	set; otherwise,	the cursor will	be moved to the	end of
	      the  current word	before the completion code is called and hence
	      there will be no suffix.

       _user_expand
	      This completer behaves similarly to the  _expand	completer  but
	      instead  performs	 expansions  defined  by  users.   The	styles
	      add-space	and sort styles	specific to the	_expand	completer  are
	      usable  with  _user_expand  in  addition to other	styles handled
	      more generally by	the completion system.	The tag	all-expansions
	      is also available.

	      The  expansion  depends on the array style user-expand being de-
	      fined for	the current context; remember  that  the  context  for
	      completers  is less specific than	that for contextual completion
	      as the full context has not yet been  determined.	  Elements  of
	      the array	may have one of	the following forms:

	      $hash

		     hash  is  the name	of an associative array.  Note this is
		     not a full	parameter expression,  merely  a  $,  suitably
		     quoted  to	 prevent  immediate expansion, followed	by the
		     name of an	associative array.   If	 the  trial  expansion
		     word  matches  a  key in hash, the	resulting expansion is
		     the corresponding value.
	      _func

		     _func is the name of a shell function whose name must be-
		     gin with _	but is not otherwise special to	the completion
		     system.  The function is called with the trial word as an
		     argument.	 If  the  word is to be	expanded, the function
		     should set	the array reply	to a list of expansions.   Op-
		     tionally, it can set REPLY	to a word that will be used as
		     a description for the set of expansions.  The return sta-
		     tus of the	function is irrelevant.
BINDABLE COMMANDS
       In  addition  to	 the context-dependent completions provided, which are
       expected	to work	in an intuitively obvious way, there are a few widgets
       implementing  special  behaviour	which can be bound separately to keys.
       The following is	a list of these	and their default bindings.

       _bash_completions
	      This function is used by two  widgets,  _bash_complete-word  and
	      _bash_list-choices.   It	exists	to  provide compatibility with
	      completion bindings in bash.  The	last character of the  binding
	      determines  what is completed: `!', command names; `$', environ-
	      ment variables; `@', host	 names;	 `/',  file  names;  `~'  user
	      names.   In bash,	the binding preceded by	`\e' gives completion,
	      and preceded by `^X' lists options.  As some of  these  bindings
	      clash with standard zsh bindings,	only `\e~' and `^X~' are bound
	      by default.  To add the rest, the	following should be  added  to
	      .zshrc after compinit has	been run:

		     for key in	'!' '$'	'@' '/'	'~'; do
		       bindkey "\e$key"	_bash_complete-word
		       bindkey "^X$key"	_bash_list-choices
		     done

	      This  includes  the  bindings  for `~' in	case they were already
	      bound to something else; the completion code does	 not  override
	      user bindings.

       _correct_filename (^XC)
	      Correct  the filename path at the	cursor position.  Allows up to
	      six errors in the	name.  Can also	be called with an argument  to
	      correct a	filename path, independently of	zle; the correction is
	      printed on standard output.

       _correct_word (^Xc)
	      Performs correction of the current argument using	the usual con-
	      textual  completions as possible choices.	This stores the	string
	      `correct-word' in	the function field of  the  context  name  and
	      then calls the _correct completer.

       _expand_alias (^Xa)
	      This  function can be used as a completer	and as a bindable com-
	      mand.  It	expands	the word the cursor is on if it	is  an	alias.
	      The  types  of  alias expanded can be controlled with the	styles
	      regular, global and disabled.

	      When used	as a bindable command there is one additional  feature
	      that  can	 be  selected by setting the complete style to `true'.
	      In this case, if the word	is not the  name  of  an  alias,  _ex-
	      pand_alias tries to complete the word to a full alias name with-
	      out expanding it.	 It leaves the cursor directly after the  com-
	      pleted word so that invoking _expand_alias once more will	expand
	      the now-complete alias name.

       _expand_word (^Xe)
	      Performs expansion on the	current	word:  equivalent to the stan-
	      dard  expand-word	command, but using the _expand completer.  Be-
	      fore calling it, the function field of the  context  is  set  to
	      `expand-word'.

       _generic
	      This  function  is  not defined as a widget and not bound	by de-
	      fault.  However, it can be used to define	a widget and will then
	      store  the  name of the widget in	the function field of the con-
	      text and call the	completion system.  This allows	custom comple-
	      tion  widgets with their own set of style	settings to be defined
	      easily.  For example, to define a	widget	that  performs	normal
	      completion and starts menu selection:

		     zle -C foo	complete-word _generic
		     bindkey '...' foo
		     zstyle ':completion:foo:*'	menu yes select=1

	      Note  in	particular that	the completer style may	be set for the
	      context in order to change the set of functions used to generate
	      possible	matches.   If _generic is called with arguments, those
	      are passed through to _main_complete as the list	of  completers
	      in place of those	defined	by the completer style.

       _history_complete_word (\e/)
	      Complete	words  from the	shell's	command	history. This uses the
	      list, remove-all-dups, sort, and stop styles.

       _most_recent_file (^Xm)
	      Complete the name	of the most recently  modified	file  matching
	      the  pattern on the command line (which may be blank).  If given
	      a	numeric	argument N, complete the Nth  most  recently  modified
	      file.  Note the completion, if any, is always unique.

       _next_tags (^Xn)
	      This command alters the set of matches used to that for the next
	      tag, or set of tags, either as given by the tag-order  style  or
	      as  set  by default; these matches would otherwise not be	avail-
	      able.  Successive	invocations of the command cycle  through  all
	      possible sets of tags.

       _read_comp (^X^R)
	      Prompt the user for a string, and	use that to perform completion
	      on the current  word.   There  are  two  possibilities  for  the
	      string.	First, it can be a set of words	beginning `_', for ex-
	      ample `_files -/', in which case the function with any arguments
	      will  be	called to generate the completions.  Unambiguous parts
	      of the function name will	 be  completed	automatically  (normal
	      completion  is  not  available  at  this point) until a space is
	      typed.

	      Second, any other	string will be passed as a set of arguments to
	      compadd and should hence be an expression	specifying what	should
	      be completed.

	      A	very restricted	set of	editing	 commands  is  available  when
	      reading  the  string:  `DEL' and `^H' delete the last character;
	      `^U' deletes the line, and `^C' and  `^G'	 abort	the  function,
	      while  `RET'  accepts  the  completion.  Note the	string is used
	      verbatim as a command line, so arguments must be quoted  in  ac-
	      cordance with standard shell rules.

	      Once  a  string  has been	read, the next call to _read_comp will
	      use the existing string instead of reading a new one.  To	 force
	      a	 new  string  to be read, call _read_comp with a numeric argu-
	      ment.

       _complete_debug (^X?)
	      This widget performs ordinary completion,	but captures in	a tem-
	      porary  file  a trace of the shell commands executed by the com-
	      pletion system.  Each completion attempt gets its	own  file.   A
	      command  to  view	 each of these files is	pushed onto the	editor
	      buffer stack.

       _complete_help (^Xh)
	      This widget displays information about the  context  names,  the
	      tags,  and  the completion functions used	when completing	at the
	      current cursor position. If given	a numeric argument other  than
	      1	(as in `ESC-2 ^Xh'), then the styles used and the contexts for
	      which they are used will be shown, too.

	      Note that	the information	about styles may be incomplete;	it de-
	      pends on the information available from the completion functions
	      called, which in turn is determined by the user's	own styles and
	      other settings.

       _complete_help_generic
	      Unlike  other  commands  listed  here, this must be created as a
	      normal ZLE widget	rather than a completion widget	(i.e. with zle
	      -N).   It	is used	for generating help with a widget bound	to the
	      _generic widget that is described	above.

	      If this widget is	created	using the name of the function,	as  it
	      is  by  default, then when executed it will read a key sequence.
	      This is expected to be bound to a	call to	a completion  function
	      that  uses  the  _generic	widget.	 That widget will be executed,
	      and information provided in  the	same  format  that  the	 _com-
	      plete_help widget	displays for contextual	completion.

	      If  the  widget's	name contains debug, for example if it is cre-
	      ated as `zle -N _complete_debug_generic _complete_help_generic',
	      it  will	read and execute the keystring for a generic widget as
	      before, but then generate	debugging information as done by _com-
	      plete_debug for contextual completion.

	      If  the  widget's	 name  contains	 noread,  it  will  not	read a
	      keystring	but instead arrange that the next  use	of  a  generic
	      widget  run  in the same shell will have the effect as described
	      above.

	      The   widget   works   by	  setting    the    shell    parameter
	      ZSH_TRACE_GENERIC_WIDGET	which  is read by _generic.  Unsetting
	      the parameter cancels any	pending	effect of the noread form.

	      For example, after executing the following:

		     zle -N _complete_debug_generic _complete_help_generic
		     bindkey '^x:' _complete_debug_generic

	      typing `C-x :' followed by the key sequence for a	generic	widget
	      will cause trace output for that widget to be saved to a file.

       _complete_tag (^Xt)
	      This  widget completes symbol tags created by the	etags or ctags
	      programmes (note there is	no connection with the completion sys-
	      tem's  tags) stored in a file TAGS, in the format	used by	etags,
	      or tags, in the format created by	ctags.	It will	look  back  up
	      the  path	 hierarchy for the first occurrence of either file; if
	      both exist, the file TAGS	is preferred.	You  can  specify  the
	      full path	to a TAGS or tags file by setting the parameter	$TAGS-
	      FILE or $tagsfile	respectively.	The  corresponding  completion
	      tags used	are etags and vtags, after emacs and vi	respectively.

UTILITY	FUNCTIONS
       Descriptions follow for utility functions that may be useful when writ-
       ing completion functions.  If functions are  installed  in  subdirecto-
       ries,  most of these reside in the Base subdirectory.  Like the example
       functions for commands in the distribution, the utility functions  gen-
       erating	matches	 all follow the	convention of returning	status zero if
       they generated completions and  non-zero	 if  no	 matching  completions
       could be	added.

       _absolute_command_paths
	      This function completes external commands	as absolute paths (un-
	      like _command_names -e which  completes  their  basenames).   It
	      takes no arguments.

       _all_labels [ -x	] [ -12VJ ] tag	name descr [ command arg ... ]
	      This  is	a convenient interface to the _next_label function be-
	      low, implementing	the loop shown	in  the	 _next_label  example.
	      The  command  and	 its  arguments	 are  called  to  generate the
	      matches.	The options stored in the parameter name will automat-
	      ically  be  inserted  into the args passed to the	command.  Nor-
	      mally, they are put directly after the command, but  if  one  of
	      the  args	 is a single hyphen, they are inserted directly	before
	      that.  If	the hyphen is the last argument, it  will  be  removed
	      from  the	 argument list before the command is called.  This al-
	      lows _all_labels to be  used  in	almost	all  cases  where  the
	      matches can be generated by a single call	to the compadd builtin
	      command or by a call to one of the utility functions.

	      For example:

		     local expl
		     ...
		     if	_requested foo;	then
		       ...
		       _all_labels foo expl '...' compadd ... -	$matches
		     fi

	      Will complete the	strings	from the matches parameter, using com-
	      padd  with  additional  options  which will take precedence over
	      those generated by _all_labels.

       _alternative [ -O name ]	[ -C name ] spec ...
	      This function is useful in simple	cases where multiple tags  are
	      available.   Essentially	it  implements a loop like the one de-
	      scribed for the _tags function below.

	      The tags to use and the action to	perform	if a tag is  requested
	      are  described  using  the specs which are of the	form: `tag:de-
	      scr:action'.  The	tags are offered using _tags and if the	tag is
	      requested, the action is executed	with the given description de-
	      scr.  The	actions	are those accepted by the _arguments  function
	      (described below), excluding the `->state' and `=...' forms.

	      For example, the action may be a simple function call:

		     _alternative \
			 'users:user:_users' \
			 'hosts:host:_hosts'

	      offers usernames and hostnames as	possible matches, generated by
	      the _users and _hosts functions respectively.

	      Like _arguments, this function uses _all_labels to  execute  the
	      actions,	which  will  loop over all sets	of tags.  Special han-
	      dling is only required if	there is an additional valid tag,  for
	      example inside a function	called from _alternative.

	      The  option  `-O	name' is used in the same way as by the	_argu-
	      ments function.  In other	words, the elements of the name	 array
	      will be passed to	compadd	when executing an action.

	      Like  _tags  this	function supports the -C option	to give	a dif-
	      ferent name for the argument context field.

       _arguments [ -nswWCRS ] [ -A pat	] [ -O name ] [	-M matchspec ]
		  [ : ]	spec ...
       _arguments [ opt	... ] -- [ -i pats ] [ -s pair ] [ helpspec ...	]
	      This function can	be used	to give	a complete  specification  for
	      completion  for  a  command whose	arguments follow standard UNIX
	      option and argument conventions.

	      Options overview

	      Options to _arguments itself must	be in separate words, i.e.  -s
	      -w,  not	-sw.   The options are followed	by specs that describe
	      options and arguments of the analyzed command.  specs  that  de-
	      scribe  option flags must	precede	specs that describe non-option
	      ("positional" or "normal") arguments of the analyzed  line.   To
	      avoid  ambiguity,	 all options to	_arguments itself may be sepa-
	      rated from the spec forms	by a single colon.

	      The `--' form is used to intuit spec forms from the help	output
	      of the command being analyzed, and is described in detail	below.
	      The opts for the `--' form are otherwise the same	options	as the
	      first  form.  Note that `-s' following `--' has a	distinct mean-
	      ing from `-s' preceding `--', and	both may appear.

	      The option switches -s, -S, -A, -w, and -W affect	how _arguments
	      parses  the analyzed command line's options.  These switches are
	      useful for commands with standard	argument parsing.

	      The options of _arguments	have the following meanings:

	      -n     With this option, _arguments sets the  parameter  NORMARG
		     to	 the  position	of  the	 first	normal argument	in the
		     $words array, i.e.	the position after the end of the  op-
		     tions.  If	that argument has not been reached, NORMARG is
		     set to -1.	 The caller should declare  `integer  NORMARG'
		     if	 the  -n  option is passed; otherwise the parameter is
		     not used.

	      -s     Enable option stacking for	single-letter options, whereby
		     multiple  single-letter  options  may  be combined	into a
		     single word.  For example,	the two	options	`-x' and  `-y'
		     may  be  combined	into a single word `-xy'.  By default,
		     every word	corresponds to a single	option name (`-xy'  is
		     a single option named `xy').

		     Options  beginning	 with a	single hyphen or plus sign are
		     eligible for stacking; words beginning with  two  hyphens
		     are not.

		     Note  that	 -s after -- has a different meaning, which is
		     documented	in the segment entitled	`Deriving  spec	 forms
		     from the help output'.

	      -w     In	combination with -s, allow option stacking even	if one
		     or	more of	the options take arguments.  For  example,  if
		     -x	 takes an argument, with no -s,	`-xy' is considered as
		     a single (unhandled) option; with -s, -xy	is  an	option
		     with  the	argument  `y'; with both -s and	-w, -xy	is the
		     option -x and the option -y with arguments	to -x (and  to
		     -y,  if  it  takes	arguments) still to come in subsequent
		     words.

	      -W     This option takes -w a stage further:  it is possible  to
		     complete  single-letter  options  even  after an argument
		     that occurs in the	same word.  However, it	depends	on the
		     action performed whether options will really be completed
		     at	this point.  For more control, use a utility  function
		     like _guard as part of the	action.

	      -C     Modify the	curcontext parameter for an action of the form
		     `->state'.	 This is discussed in detail below.

	      -R     Return status 300 instead of zero when a $state is	to  be
		     handled, in the `->string'	syntax.

	      -S     Do	 not  complete	options	 after a `--' appearing	on the
		     line, and ignore the `--'.	 For example, with -S, in  the
		     line

			    foobar -x -- -y

		     the  `-x' is considered an	option,	the `-y' is considered
		     an	argument, and the `--' is considered to	be neither.

	      -A pat Do	not complete options after the first non-option	 argu-
		     ment  on the line.	 pat is	a pattern matching all strings
		     which are not to be taken as arguments.  For example,  to
		     make  _arguments  stop completing options after the first
		     normal argument, but ignoring all strings starting	with a
		     hyphen  even if they are not described by one of the opt-
		     specs, the	form is	`-A "-*"'.

	      -O name
		     Pass the elements of the array name as arguments to func-
		     tions  called  to	execute	actions.  This is discussed in
		     detail below.

	      -M matchspec
		     Use the match specification matchspec for completing  op-
		     tion names	and values.  The default matchspec allows par-
		     tial word completion after	`_' and	`-', such as  complet-
		     ing `-f-b'	to `-foo-bar'.	The default matchspec is:
		     r:|[_-]=* r:|=*

	      specs: overview

	      Each of the following forms is a spec describing individual sets
	      of options or arguments on the command line being	analyzed.

	      n:message:action
	      n::message:action
		     This describes the	n'th  normal  argument.	  The  message
		     will  be  printed above the matches generated and the ac-
		     tion indicates what can be	 completed  in	this  position
		     (see  below).  If there are two colons before the message
		     the argument is optional.	If the message	contains  only
		     white  space,  nothing  will be printed above the matches
		     unless the	action adds an explanation string itself.

	      :message:action
	      ::message:action
		     Similar, but describes the	next argument, whatever	number
		     that  happens  to	be.  If	all arguments are specified in
		     this form in the correct order the	numbers	 are  unneces-
		     sary.

	      *:message:action
	      *::message:action
	      *:::message:action
		     This  describes  how  arguments (usually non-option argu-
		     ments, those not beginning	with - or +) are  to  be  com-
		     pleted  when neither of the first two forms was provided.
		     Any number	of arguments can be completed in this fashion.

		     With two colons before the	message, the words special ar-
		     ray and the CURRENT special parameter are modified	to re-
		     fer only to the normal arguments when the action is  exe-
		     cuted or evaluated.  With three colons before the message
		     they are modified to refer	only to	the  normal  arguments
		     covered by	this description.

	      optspec
	      optspec:...
		     This  describes  an option.  The colon indicates handling
		     for one or	more arguments to the option;  if  it  is  not
		     present, the option is assumed to take no arguments.

		     The  following  forms  are	available for the initial opt-
		     spec, whether or not the option has arguments.

		     *optspec
			    Here optspec is one	of the remaining forms	below.
			    This  indicates  the  following optspec may	be re-
			    peated.  Otherwise if the corresponding option  is
			    already present on the command line	to the left of
			    the	cursor it will not be offered again.

		     -optname
		     +optname
			    In the simplest form the optspec is	just  the  op-
			    tion  name	beginning with a minus or a plus sign,
			    such as `-foo'.  The first argument	for the	option
			    (if	 any)  must follow as a	separate word directly
			    after the option.

			    Either of `-+optname' and `+-optname' can be  used
			    to	specify	 that  -optname	 and +optname are both
			    valid.

			    In all the remaining forms,	the leading `-'	may be
			    replaced by	or paired with `+' in this way.

		     -optname-
			    The	 first	argument  of  the option must come di-
			    rectly after the option name  in  the  same	 word.
			    For	 example,  `-foo-:...' specifies that the com-
			    pleted  option  and	 argument   will   look	  like
			    `-fooarg'.

		     -optname+
			    The	 first	argument  may appear immediately after
			    optname in the same	word, or may appear as a sepa-
			    rate   word	  after	  the  option.	 For  example,
			    `-foo+:...'	specifies that	the  completed	option
			    and	 argument  will	 look like either `-fooarg' or
			    `-foo arg'.

		     -optname=
			    The	argument may appear as the next	 word,	or  in
			    same  word	as the option name provided that it is
			    separated from it by an equals sign,  for  example
			    `-foo=arg' or `-foo	arg'.

		     -optname=-
			    The	 argument  to  the option must appear after an
			    equals sign	in the same word, and may not be given
			    in the next	argument.

		     optspec[explanation]
			    An	explanation  string  may be appended to	any of
			    the	preceding forms	of optspec by enclosing	it  in
			    brackets, as in `-q[query operation]'.

			    The	 verbose  style	 is used to decide whether the
			    explanation	strings	are displayed with the	option
			    in a completion listing.

			    If	no  bracketed  explanation string is given but
			    the	auto-description style is set and only one ar-
			    gument is described	for this optspec, the value of
			    the	style is displayed, with any appearance	of the
			    sequence `%d' in it	replaced by the	message	of the
			    first optarg that follows the optspec; see below.

		     It	is possible for	options	with a literal `+' or  `='  to
		     appear,  but  that	 character must	be quoted, for example
		     `-\+'.

		     Each optarg following an optspec must  take  one  of  the
		     following forms:

		     :message:action
		     ::message:action
			    An	argument to the	option;	message	and action are
			    treated as for ordinary arguments.	In  the	 first
			    form, the argument is mandatory, and in the	second
			    form it is optional.

			    This group may be repeated for options which  take
			    multiple arguments.	 In other words, :message1:ac-
			    tion1:message2:action2 specifies that  the	option
			    takes two arguments.

		     :*pattern:message:action
		     :*pattern::message:action
		     :*pattern:::message:action
			    This  describes multiple arguments.	 Only the last
			    optarg for an option taking	multiple arguments may
			    be	given  in  this	form.  If the pattern is empty
			    (i.e. :*:),	all the	remaining words	 on  the  line
			    are	 to  be	 completed as described	by the action;
			    otherwise, all the words up	 to  and  including  a
			    word  matching the pattern are to be completed us-
			    ing	the action.

			    Multiple colons are	treated	 as  for  the  `*:...'
			    forms for ordinary arguments:  when	the message is
			    preceded by	two colons, the	 words	special	 array
			    and	 the  CURRENT  special	parameter are modified
			    during the execution or evaluation of  the	action
			    to refer only to the words after the option.  When
			    preceded by	three colons, they are modified	to re-
			    fer	only to	the words covered by this description.

	      Any literal colon	in an optname, message,	or action must be pre-
	      ceded by a backslash, `\:'.

	      Each of the forms	above may be preceded by a list	in parentheses
	      of option	names and argument numbers.  If	the given option is on
	      the command line,	the options and	arguments indicated in	paren-
	      theses   will  not  be  offered.	 For  example,	`(-two	-three
	      1)-one:...' completes the	option `-one'; if this appears on  the
	      command line, the	options	-two and -three	and the	first ordinary
	      argument will not	be completed after it.	`(-foo):...' specifies
	      an  ordinary  argument completion; -foo will not be completed if
	      that argument is already present.

	      Other items may appear in	the list of excluded options to	 indi-
	      cate  various  other  items  that	should not be applied when the
	      current specification is matched:	a single star (*) for the rest
	      arguments	 (i.e.	a  specification of the	form `*:...'); a colon
	      (:) for all normal (non-option-) arguments; and a	hyphen (-) for
	      all options.  For	example, if `(*)' appears before an option and
	      the option appears on the	command	line, the  list	 of  remaining
	      arguments	 (those	 shown in the above table beginning with `*:')
	      will not be completed.

	      To aid in	reuse of specifications, it is possible	to precede any
	      of  the  forms  above  with `!'; then the	form will no longer be
	      completed, although if the option	or  argument  appears  on  the
	      command  line  they will be skipped as normal.  The main use for
	      this is when the arguments are given by an array,	and _arguments
	      is  called  repeatedly  for more specific	contexts: on the first
	      call `_arguments $global_options'	is  used,  and	on  subsequent
	      calls `_arguments	!$^global_options'.

	      specs: actions

	      In each of the forms above the action determines how completions
	      should be	generated.  Except for the `->string' form below,  the
	      action  will  be executed	by calling the _all_labels function to
	      process all tag labels.  No special handling of tags  is	needed
	      unless a function	call introduces	a new one.

	      The  functions called to execute actions will be called with the
	      elements of the array named by the `-O  name'  option  as	 argu-
	      ments.   This  can be used, for example, to pass the same	set of
	      options for the compadd builtin to all actions.

	      The forms	for action are as follows.

	       (single unquoted	space)
		     This is useful where an argument is required  but	it  is
		     not  possible  or	desirable  to generate matches for it.
		     The message will be displayed but no completions  listed.
		     Note  that	 even in this case the colon at	the end	of the
		     message is	needed;	it may only be omitted when neither  a
		     message nor an action is given.

	      (item1 item2 ...)
		     One of a list of possible matches,	for example:

			    :foo:(foo bar baz)

	      ((item1\:desc1 ...))
		     Similar to	the above, but with descriptions for each pos-
		     sible match.  Note	the backslash before the  colon.   For
		     example,

			    :foo:((a\:bar b\:baz))

		     The  matches  will	be listed together with	their descrip-
		     tions if the description style is set with	the values tag
		     in	the context.

	      ->string
		     In	 this form, _arguments processes the arguments and op-
		     tions and then returns control to	the  calling  function
		     with  parameters set to indicate the state	of processing;
		     the calling function then makes its own arrangements  for
		     generating	 completions.  For example, functions that im-
		     plement a state machine can use this type of action.

		     Where _arguments encounters action	in the `->string' for-
		     mat,  it  will  strip all leading and trailing whitespace
		     from string and set the array state to  the  set  of  all
		     strings for which an action is to be performed.  The ele-
		     ments of the array	state_descr are	 assigned  the	corre-
		     sponding  message	field from each	optarg containing such
		     an	action.

		     By	default	and in common with all other well behaved com-
		     pletion  functions,  _arguments returns status zero if it
		     was able to add matches and non-zero otherwise.  However,
		     if	the -R option is given,	_arguments will	instead	return
		     a status of 300 to	indicate that $state is	to be handled.

		     In	addition to $state and $state_descr,  _arguments  also
		     sets   the	  global   parameters  `context',  `line'  and
		     `opt_args'	as described below, and	 does  not  reset  any
		     changes made to the special parameters such as PREFIX and
		     words.  This gives	the calling function the choice	of re-
		     setting these parameters or propagating changes in	them.

		     A	function  calling  _arguments with at least one	action
		     containing	a `->string' must therefore declare  appropri-
		     ate local parameters:

			    local context state	state_descr line
			    typeset -A opt_args

		     to	 prevent  _arguments from altering the global environ-
		     ment.

	      {eval-string}
		     A string in braces	is evaluated as	shell code to generate
		     matches.	If  the	eval-string itself does	not begin with
		     an	opening	parenthesis or brace it	is split into separate
		     words before execution.

	      =	action
		     If	 the  action starts with `= ' (an equals sign followed
		     by	a space), _arguments will insert the contents  of  the
		     argument  field  of  the current context as the new first
		     element in	the words  special  array  and	increment  the
		     value of the CURRENT special parameter.  This has the ef-
		     fect of inserting a dummy word onto the  completion  com-
		     mand  line	 while not changing the	point at which comple-
		     tion is taking place.

		     This is most useful with one of the specifiers  that  re-
		     strict  the words on the command line on which the	action
		     is	to operate (the	two-  and  three-colon	forms  above).
		     One particular use	is when	an action itself causes	_argu-
		     ments on a	restricted range; it is	necessary to use  this
		     trick  to	insert	an  appropriate	 command name into the
		     range for the second call to _arguments  to  be  able  to
		     parse the line.

	       word...
	      word...
		     This covers all forms other than those above.  If the ac-
		     tion starts with a	space, the  remaining  list  of	 words
		     will be invoked unchanged.

		     Otherwise	it  will  be  invoked  with some extra strings
		     placed after the first word; these	are to be passed  down
		     as	 options to the	compadd	builtin.  They ensure that the
		     state specified by	_arguments, in particular the descrip-
		     tions  of	options	 and arguments,	is correctly passed to
		     the completion command.  These additional	arguments  are
		     taken  from  the array parameter `expl'; this will	be set
		     up	before executing the action and	hence may be  referred
		     to	 inside	 it,  typically	 in  an	 expansion of the form
		     `$expl[@]'	which preserves	empty elements of the array.

	      During the performance of	the action the array  `line'  will  be
	      set  to  the  normal  arguments  from the	command	line, i.e. the
	      words from the command line after	the command name excluding all
	      options and their	arguments.  Options are	stored in the associa-
	      tive array `opt_args' with option	names as keys and their	 argu-
	      ments  as	the values.  For options that have more	than one argu-
	      ment these are given as one string, separated  by	 colons.   All
	      colons  and  backslashes	in the original	arguments are preceded
	      with backslashes.

	      The parameter `context' is set when  returning  to  the  calling
	      function to perform an action of the form	`->string'.  It	is set
	      to an array of elements corresponding to the elements of $state.
	      Each  element  is	 a suitable name for the argument field	of the
	      context: either a	string of the form `option-opt-n' for the n'th
	      argument	of  the	 option	 -opt,	or a string of the form	`argu-
	      ment-n' for the n'th argument.  For `rest'  arguments,  that  is
	      those  in	 the list at the end not handled by position, n	is the
	      string `rest'.  For example, when	completing the argument	of the
	      -o option, the name is `option-o-1', while for the second	normal
	      (non-option-) argument it	is `argument-2'.

	      Furthermore, during the evaluation of  the  action  the  context
	      name  in	the curcontext parameter is altered to append the same
	      string that is stored in the context parameter.

	      The option -C tells _arguments to	modify the curcontext  parame-
	      ter  for	an action of the form `->state'.  This is the standard
	      parameter	used to	keep track of the current  context.   Here  it
	      (and  not	the context array) should be made local	to the calling
	      function to avoid	passing	back the modified value	and should  be
	      initialised to the current value at the start of the function:

		     local curcontext="$curcontext"

	      This  is	useful where it	is not possible	for multiple states to
	      be valid together.

	      Specifying multiple sets of options

	      It is possible to	specify	multiple sets of options and arguments
	      with  the	 sets separated	by single hyphens.  The	specifications
	      before the first hyphen (if any) are shared by all the remaining
	      sets.  The first word in every other set provides	a name for the
	      set which	may appear in exclusion	lists in  specifications,  ei-
	      ther alone or before one of the possible values described	above.
	      In the second case a `-' should appear between this name and the
	      remainder.

	      For example:

		     _arguments	\
			 -a \
		       - set1 \
			 -c \
		       - set2 \
			 -d \
			 ':arg:(x2 y2)'

	      This  defines  two sets.	When the command line contains the op-
	      tion `-c', the `-d' option and the argument will not be  consid-
	      ered  possible  completions.   When it contains `-d' or an argu-
	      ment, the	option `-c' will not be	 considered.   However,	 after
	      `-a' both	sets will still	be considered valid.

	      If  an option in a set appears on	the command line, it is	stored
	      in the associative array `opt_args' with 'set-option' as a  key.
	      In the example above, a key `set1--c' is used if the option `-c'
	      is on the	command	line.

	      If the name given	for one	of the mutually	exclusive sets	is  of
	      the form `(name)'	then only one value from each set will ever be
	      completed; more formally,	all specifications are mutually	exclu-
	      sive  to all other specifications	in the same set.  This is use-
	      ful for defining multiple	sets of	options	which are mutually ex-
	      clusive  and  in	which  the options are aliases for each	other.
	      For example:

		     _arguments	\
			 -a -b \
		       - '(compress)' \
			 {-c,--compress}'[compress]' \
		       - '(uncompress)'	\
			 {-d,--decompress}'[decompress]'

	      As the completion	code has to parse the command line  separately
	      for  each	 set  this form	of argument is slow and	should only be
	      used when	necessary.  A useful alternative is  often  an	option
	      specification with rest-arguments	(as in `-foo:*:...'); here the
	      option -foo swallows up all remaining arguments as described  by
	      the optarg definitions.

	      Deriving spec forms from the help	output

	      The  option `--' allows _arguments to work out the names of long
	      options that support the `--help'	option which  is  standard  in
	      many GNU commands.  The command word is called with the argument
	      `--help' and the output examined for option names.  Clearly,  it
	      can  be dangerous	to pass	this to	commands which may not support
	      this option as the behaviour of the command is unspecified.

	      In addition to options, `_arguments --' will try to  deduce  the
	      types   of   arguments  available	 for  options  when  the  form
	      `--opt=val' is valid.  It	is also	possible to provide  hints  by
	      examining	 the  help  text of the	command	and adding helpspec of
	      the form `pattern:message:action'; note  that  other  _arguments
	      spec  forms  are	not  used.  The	pattern	is matched against the
	      help text	for an option, and if it matches the message  and  ac-
	      tion  are	 used  as  for other argument specifiers.  The special
	      case of `*:' means both message and action are empty, which  has
	      the  effect of causing options having no description in the help
	      output to	be ordered in listings ahead of	options	 that  have  a
	      description.

	      For example:

		     _arguments	-- '*\*:toggle:(yes no)' \
				   '*=FILE*:file:_files' \
				   '*=DIR*:directory:_files -/'	\
				   '*=PATH*:directory:_files -/'

	      Here,  `yes'  and	 `no' will be completed	as the argument	of op-
	      tions whose description ends in a	star; file names will be  com-
	      pleted for options that contain the substring `=FILE' in the de-
	      scription; and directories will be completed for	options	 whose
	      description  contains  `=DIR' or `=PATH'.	 The last three	are in
	      fact the default and so need not be given	 explicitly,  although
	      it is possible to	override the use of these patterns.  A typical
	      help text	which uses this	feature	is:

		       -C, --directory=DIR	    change to directory	DIR

	      so that the above	specifications will cause  directories	to  be
	      completed	after `--directory', though not	after `-C'.

	      Note also	that _arguments	tries to find out automatically	if the
	      argument for an option is	optional.  This	can be	specified  ex-
	      plicitly by doubling the colon before the	message.

	      If the pattern ends in `(-)', this will be removed from the pat-
	      tern and the action will be used only directly  after  the  `=',
	      not  in the next word.  This is the behaviour of a normal	speci-
	      fication defined with the	form `=-'.

	      The `_arguments --' can be followed by the option	`-i  patterns'
	      to give patterns for options which are not to be completed.  The
	      patterns can be given as the name	of an array parameter or as  a
	      literal list in parentheses.  For	example,

		     _arguments	-- -i \
			 "(--(en|dis)able-FEATURE*)"

	      will  cause  completion to ignore	the options `--enable-FEATURE'
	      and `--disable-FEATURE' (this example is useful with GNU config-
	      ure).

	      The  `_arguments --' form	can also be followed by	the option `-s
	      pair' to describe	option aliases.	 The pair consists of  a  list
	      of alternating patterns and corresponding	replacements, enclosed
	      in parens	and quoted so that it forms a single argument word  in
	      the _arguments call.

	      For example, some	configure-script help output describes options
	      only as `--enable-foo', but the script also accepts the  negated
	      form `--disable-foo'.  To	allow completion of the	second form:

		     _arguments	-- -s "((#s)--enable- --disable-)"

	      Miscellaneous notes

	      Finally,	note  that _arguments generally	expects	to be the pri-
	      mary function handling any completion for	which it is used.   It
	      may  have	side effects which change the treatment	of any matches
	      added by other functions called after it.	 To combine _arguments
	      with  other  functions,  those functions should be called	either
	      before _arguments, as an action within a spec,  or  in  handlers
	      for `->state' actions.

	      Here is a	more general example of	the use	of _arguments:

		     _arguments	'-l+:left border:' \
				'-format:paper size:(letter A4)' \
				'*-copy:output file:_files::resolution:(300 600)' \
				':postscript file:_files -g \*.\(ps\|eps\)' \
				'*:page	number:'

	      This describes three options: `-l', `-format', and `-copy'.  The
	      first takes one argument described as `left border' for which no
	      completion will be offered because of the	empty action.  Its ar-
	      gument may come directly after the `-l' or it may	 be  given  as
	      the next word on the line.

	      The  `-format'  option  takes one	argument in the	next word, de-
	      scribed as `paper	size' for which	only the strings `letter'  and
	      `A4' will	be completed.

	      The `-copy' option may appear more than once on the command line
	      and takes	two arguments.	The first is  mandatory	 and  will  be
	      completed	as a filename.	The second is optional (because	of the
	      second colon before the description `resolution')	 and  will  be
	      completed	from the strings `300' and `600'.

	      The  last	two descriptions say what should be completed as argu-
	      ments.  The first	describes the first argument as	a  `postscript
	      file' and	makes files ending in `ps' or `eps' be completed.  The
	      last description gives all other arguments the description `page
	      numbers' but does	not offer completions.

       _cache_invalid cache_identifier
	      This  function returns status zero if the	completions cache cor-
	      responding to the	given cache identifier needs  rebuilding.   It
	      determines  this	by  looking  up	the cache-policy style for the
	      current context.	This should provide a function name  which  is
	      run  with	 the  full path	to the relevant	cache file as the only
	      argument.

	      Example:

		     _example_caching_policy ()	{
			 # rebuild if cache is more than a week	old
			 local -a oldp
			 oldp=(	"$1"(Nm+7) )
			 (( $#oldp ))
		     }

       _call_function return name [ arg	... ]
	      If a function name exists, it is called with the arguments args.
	      The  return  argument gives the name of a	parameter in which the
	      return status from the function name should be stored; if	return
	      is empty or a single hyphen it is	ignored.

	      The  return status of _call_function itself is zero if the func-
	      tion name	exists and was called and non-zero otherwise.

       _call_program [ -p ] tag	string ...
	      This function provides a mechanism for the user to override  the
	      use  of an external command.  It looks up	the command style with
	      the supplied tag.	 If the	style is set, its value	is used	as the
	      command to execute.  The strings from the	call to	_call_program,
	      or from the style	if set,	are concatenated with  spaces  between
	      them  and	 the resulting string is evaluated.  The return	status
	      is the return status of the command called.

	      If the option `-p' is supplied it	 indicates  that  the  command
	      output  is  influenced by	the permissions	it is run with.	If the
	      gain-privileges style is set to true,  _call_program  will  make
	      use of commands such as sudo, if present on the command-line, to
	      match the	permissions to whatever	the final command is likely to
	      run  under.  When	 looking  up  the  gain-privileges and command
	      styles, the command component of the  zstyle  context  will  end
	      with a slash (`/') followed by the command that would be used to
	      gain privileges.

       _combination [ -s pattern ] tag style spec ... field opts ...
	      This function is used to complete	combinations of	 values,   for
	      example  pairs  of  hostnames and	usernames.  The	style argument
	      gives the	style which defines the	pairs; it is looked  up	 in  a
	      context with the tag specified.

	      The style	name consists of field names separated by hyphens, for
	      example `users-hosts-ports'.  For	each field for a value is  al-
	      ready  known,  a spec of the form	`field=pattern'	is given.  For
	      example, if the command line so far specifies a user `pws',  the
	      argument `users=pws' should appear.

	      The  next	 argument  with	no equals sign is taken	as the name of
	      the field	for which completions should be	generated  (presumably
	      not one of the fields for	which the value	is known).

	      The matches gener