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:

       zsh	    Zsh	overview
       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.
       It does not provide compatibility with POSIX or other shells in its de-
       fault operating mode:  see the section Compatibility below.

       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 HTTP	and anonymous FTP site.

       ftp://ftp.zsh.org/pub/
       https://www.zsh.org/pub/
       )

       The up-to-date source code is available via Git from Sourceforge.   See
       https://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
       https://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	https://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.

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).

       The long	option `--emulate' followed (in	a separate word) by an	emula-
       tion  mode  may	be passed to the shell.	 The emulation modes are those
       described for the emulate builtin, see zshbuiltins(1).  The `--emulate'
       option  must  precede any other options (which might otherwise be over-
       ridden),	but following options are honoured, so may be used  to	modify
       the  requested emulation	mode.  Note that certain extra steps are taken
       to ensure a smooth emulation when this option is	used compared with the
       emulate	command	within the shell: for example, variables that conflict
       with POSIX usage	such as	path are not defined within the	shell.

       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.

       A  shell	 Restricted Mode is an outdated	way to restrict	what users may
       do:  modern systems have	better,	safer and more reliable	ways  to  con-
       fine user actions, such as chroot jails,	containers and zones.

       A  restricted shell is very difficult to	implement safely.  The feature
       may be removed in a future version of zsh.

       It is important to realise that the  restrictions  only	apply  to  the
       shell,  not  to	the commands it	runs (except for some shell builtins).
       While a restricted shell	can only run the restricted list  of  commands
       accessible  via	the  predefined	 `PATH'	 variable, it does not prevent
       those commands from running any other command.

       As an example, if `env' is among	the list of allowed commands, then  it
       allows the user to run any command as `env' is not a shell builtin com-
       mand and	can run	arbitrary executables.

       So when implementing a restricted shell framework it is important to be
       fully  aware  of	 what actions each of the allowed commands or features
       (which may be regarded as modules) can perform.

       Many commands can have their behaviour affected	by  environment	 vari-
       ables.  Except for the few listed above,	zsh does not restrict the set-
       ting of environment variables.

       If a `perl', `python', `bash', or  other	 general  purpose  interpreted
       script it treated as a restricted command, the user can work around the
       restriction by  setting	specially  crafted  `PERL5LIB',	 `PYTHONPATH',
       `BASHENV' (etc.)	environment variables. On GNU systems, any command can
       be made to run arbitrary	code when performing character set  conversion
       (including  zsh itself) by setting a `GCONV_PATH' environment variable.
       Those are only a	few examples.

       Bear in mind that, contrary to some other shells, `readonly' is	not  a
       security	 feature  in  zsh as it	can be undone and so cannot be used to
       mitigate	the above.

       A restricted shell only works if	the allowed commands are few and care-
       fully  written  so  as not to grant more	access to users	than intended.
       It is also important to restrict	what zsh module	the user may  load  as
       some  of	them, such as `zsh/system', `zsh/mapfile' and `zsh/files', al-
       low bypassing most of the restrictions.

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

       |      for matching either of two alternatives

       ~, ^   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
	      Expand  the list of words, and set the parameter name to each of
	      them in turn, executing list each	time.  If  the	`in  word'  is
	      omitted, use the positional parameters instead of	the words.

	      The  term	 consists  of one or more newline or ; which terminate
	      the words, and are optional when the `in word' is	omitted.

	      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 or  con-
	      tinue 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 or continue com-
	      mand is treated in the normal way, as if	always-list  were  not
	      present.	 The  two  chunks  of code are referred	to as the `try
	      block' and the `always block'.

	      Optional newlines	or semicolons may  appear  after  the  always;
	      note,  however,  that  they may not appear between the 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.

	      When  a  try block occurs	outside	of any function, a return or a
	      exit encountered in try-list does	not cause the execution	of al-
	      ways-list.   Instead, the	shell exits immediately	after any EXIT
	      trap has been executed.  Otherwise, a return command encountered
	      in  try-list  will cause the execution of	always-list, just like
	      break and	continue.

       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.

       function	word ... [ () ]	[ term ] sublist
	      This is a	short form of function.

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

       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.

       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.

       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.

   Alias difficulties
       Although	aliases	can be used in ways that bend normal shell syntax, not
       every string of non-white-space characters can be used as an alias.

       Any  set	 of characters not listed as a word above is not a word, hence
       no attempt is made to expand it as an alias, no matter how  it  is  de-
       fined  (i.e. via	the builtin or the special parameter aliases described
       in the section THE ZSH/PARAMETER	MODULE in zshmodules(1)).  However, as
       noted in	the case of POSIX_ALIASES above, the shell does	not attempt to
       deduce whether the string corresponds to	a word at the time  the	 alias
       is created.

       For  example,  an  expression containing	an = at	the start of a command
       line is an assignment and cannot	be expanded as an alias; a lone	 =  is
       not  an assignment but can only be set as an alias using	the parameter,
       as otherwise the	= is taken part	of the syntax of the builtin command.

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

       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 the first charac-
       ter of $histchars (default `!').

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.  It	is an error to
	      open a file in this fashion if it	does not exist.

       <> 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, regardless of CLOBBER.

       >> word
	      Open file	word for writing in append mode	 as  standard  output.
	      If  the  file  does not exist, and the CLOBBER and APPEND_CREATE
	      options are both 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, regardless of CLOBBER and APPEND_CREATE.

       <<[-] 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 file descriptor remains open in sub-
       shells and forked external executables.

       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 that the shell opens all the  files	 to  be	 used  in  the	multio
       process immediately, not	at the point they are about to be written.

       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, provided
       the MULTIOS option is set.  It should be	noted that each	file is	opened
       immediately, not	at the point where it is about to be read: this	behav-
       iour differs from cat, so if strictly standard behaviour	is needed, cat
       should be used instead.

       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.

       One additional side effect is that use of disown	with a job created  by
       suspending  shell  code in this fashion is delayed: the job can only be
       disowned	once any process started from the parent shell has terminated.
       At that point, the disowned job disappears silently from	the job	list.

       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'.)

	      When no option named option exists, and the  POSIX_BUILTINS  op-
	      tion  hasn't  been set, return 3 with a warning.	If that	option
	      is set, return 1 with no warning.

       -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 subexpressions.  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 9 may be given  following
	      the %; hence %6.	outputs	microseconds, and %9. outputs nanosec-
	      onds.  (The latter requires  a  nanosecond-precision  clock_get-
	      time; systems lacking this will return a value multiplied	by the
	      appropriate power	of 10.)	 A typical example of this is the for-
	      mat `%D{%H:%M:%S.%.}'.

	      The GNU extension	%N is handled as a synonym for %9..

	      Additionally, the	GNU extension that a `-' between the % and the
	      format character 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
	      handling 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 left-to-right fashion.  On each ar-
	      gument, any of the five steps that are needed are	performed  one
	      after the	other.	Hence, for example, all	the parts of parameter
	      expansion	are completed before command substitution is  started.
	      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, including inside double quotes (but not inside single	quotes
       '...' or	C-style	quotes $'...' nor when escaped with a backslash).

       The first character is followed by 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.

       History expansions do not nest.

       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 [ digits ]
	      Remove a trailing	pathname component, shortening the path	by one
	      directory	level: this is the `head' of the pathname.  This works
	      like  `dirname'.	If the h is followed immediately (with no spa-
	      ces or other separator) by any number of decimal digits, and the
	      value  of	the resulting number is	non-zero, that number of lead-
	      ing components is	preserved instead of the final component being
	      removed.	 In an absolute	path the leading `/' is	the first com-
	      ponent, so,  for	example,  if  var=/my/path/to/something,  then
	      ${var:h3}	 substitutes  /my/path.	  Consecutive `/'s are treated
	      the same as a single `/'.	 In parameter substitution, digits may
	      only  be used if the expression is in braces, so for example the
	      short form substitution $var:h2 is treated as ${var:h}2, not  as
	      ${var:h2}.   No restriction applies to the use of	digits in his-
	      tory substitution	or globbing qualifiers.	  If  more  components
	      are  requested  than are present,	the entire path	is substituted
	      (so this does not	trigger	a `failed modifier' error  in  history
	      expansion).

       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 [ digits ]
	      Remove all leading pathname components, leaving the final	compo-
	      nent  (tail).  This works	like `basename'.  Any trailing slashes
	      are first	removed.  Decimal  digits  are	handled	 as  described
	      above  for  (h), but in this case	that number of trailing	compo-
	      nents is preserved instead of the	default	1; 0  is  treated  the
	      same as 1.

       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 -r -- *.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.	However, as in	other  shells,
       null words are elided from unquoted parameters' expansions.

       With default options, after the assignments:

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

       then  $array  substitutes two words, `first word' and `third word', and
       $scalar substitutes a single word `only word'.  Note that  second  ele-
       ment of array was elided.  Scalar parameters can	be elided too if their
       value is	null (empty).  To  avoid  elision,  use	 quoting  as  follows:
       "$scalar"  for  scalars	and "${array[@]}" or "${(@)array}" for arrays.
       (The last two forms are equivalent.)

       Parameter expansions can	involve	flags, as  in  `${(@kv)aliases}',  and
       other  operators,  such as `${PREFIX:-"/usr/local"}'.  Parameter	expan-
       sions can also be nested.  These	topics will be introduced below.   The
       full rules are complicated and are noted	at the end.

       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.

       ${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: note, however, the expansion  hap-
	      pens  immediately,  with	any explicit brace expansion happening
	      later.  If word splitting	is also	 in  effect  the  $var[N]  may
	      themselves be split into different list elements.

       ${=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      Convert the substitution into an array expression,  even	if  it
	      otherwise	 would be scalar.  This	has lower precedence than sub-
	      scripting, so one	level of nested	expansion is required in order
	      that  subscripts apply to	array elements.	 Thus ${${(A)name}[1]}
	      yields the full value of name when name is scalar.

	      This assigns an array parameter with `${...=...}', `${...:=...}'
	      or  `${...::=...}'.   If this flag is repeated (as in `AA'), as-
	      signs an associative array parameter.  Assignment	is made	before
	      sorting  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; when assigning an associative	array,
	      the word part must be converted to an array, for example by  us-
	      ing `${(AA)=name=...}' to	activate field splitting.

	      Surrounding  context  such  as  additional nesting or use	of the
	      value in a scalar	assignment may cause the array	to  be	joined
	      back into	a single string	again.

       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  single  word  shell expansions, namely parameter	expan-
	      sion, command substitution and arithmetic	expansion, on the  re-
	      sult.  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.
	      With  the	KSH_ARRAYS option a subscript `[*]' or `[@]' is	needed
	      to operate on the	whole array, as	usual.

       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 minimal  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      With # or	##, search for the match that starts  closest  to  the
	      start  of	 the string (a `substring match'). Of all matches at a
	      particular position, # selects the shortest and ## the longest:

		     % str="aXbXc"
		     % echo ${(S)str#X*}
		     abXc
		     % echo ${(S)str##X*}
		     a
		     %

	      With % or	%%, search for the match that starts  closest  to  the
	      end of the string:

		     % str="aXbXc"
		     % echo ${(S)str%X*}
		     aXbc
		     % echo ${(S)str%%X*}
		     aXb
		     %

	      (Note that % and %% don't	search for the match that ends closest
	      to the end of the	string,	as one might expect.)

	      With  substitution  via  ${.../...}  or  ${...//...},  specifies
	      non-greedy matching, i.e.	that the shortest instead of the long-
	      est match	should be replaced:

		     % str="abab"
		     % echo ${str/*b/_}
		     _
		     % echo ${(S)str/*b/_}
		     _ab
		     %

       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 faster  `$(<foo)'.
       In  this	case foo undergoes single word shell expansions	(parameter ex-
       pansion,	command	substitution and arithmetic expansion),	but not	 file-
       name generation.

       If  the	option	GLOB_SUBST  is set, the	result of any unquoted command
       substitution, including the special form	just  mentioned,  is  eligible
       for filename generation.

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 a	blank character

	      [: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.  The alternatives are	 tried
	      in order from left to right.

       ^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_message'.	 Note  that  the  first	set of
	      parentheses is before the	(#b) and does not create a  backrefer-
	      ence.

	      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 -ld --	(*/)#bar

       or

	      ls -ld --	**/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 -ld --	**.c

       is equivalent to

	      ls -ld --	**/*.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	-ld -- *(+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 -ld --	*(-/)

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

	      ls -ld --	*(-@)

       lists all broken	symbolic links,	and

	      ls -ld --	*(%W)

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

	      ls -ld --	*(W,X)

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

	      print -rC1 /tmp/foo*(u0^@:t)

       outputs the basename of all root-owned files beginning with the	string
       `foo' in	/tmp, ignoring symlinks, and

	      ls -ld --	*.*~(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 -rC1 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 ...)
	      name=([key]=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.

       In  the	third  form,  key  is  an expression that will be evaluated in
       arithmetic context (in its simplest form, an integer)  that  gives  the
       index  of the element to	be assigned with value.	 In this form any ele-
       ments not explicitly mentioned that come	before the  largest  index  to
       which  a	 value	is assigned are	assigned an empty string.  The indices
       may be in any order.  Note that this syntax is strict: [	 and  ]=  must
       not  be	quoted,	and key	may not	consist	of the unquoted	string ]=, but
       is otherwise treated as a simple	string.	 The enhanced  forms  of  sub-
       script  expression  that	may be used when directly subscripting a vari-
       able name, described in the section Array  Subscripts  below,  are  not
       available.

       The  syntaxes  with  and	without	the explicit key may be	mixed.	An im-
       plicit key is deduced by	incrementing the index from the	previously as-
       signed  element.	 Note that it is not treated as	an error if latter as-
       signments in this form overwrite	earlier	assignments.

       For example, assuming the option	KSH_ARRAYS is not set, the following:

	      array=(one [3]=three four)

       causes the array	variable array to contain four elements	one, an	 empty
       string, three and four, in that order.

       In the forms where only value is	specified, full	command	line expansion
       is performed.

       In the [key]=value form,	both key and value undergo all forms of	expan-
       sion  allowed  for  single word shell expansions	(this does not include
       filename	generation); these are as performed by the parameter expansion
       flag  (e)  as described in zshexpn(1).  Nested parentheses may surround
       value and are included as part of the value, which  is  joined  into  a
       plain  string; this differs from	ksh which allows the values themselves
       to be arrays.  A	future version of zsh may support that.	 To cause  the
       brackets	 to  be	 interpreted as	a character class for filename genera-
       tion, and therefore to treat the	resulting list of files	as  a  set  of
       values, quote the equal sign using any form of quoting.	Example:

	      name=([a-z]'='*)

       To  append to an	array without changing the existing values, use	one of
       the following:

	      name+=(value ...)
	      name+=([key]=value ...)

       In the second form key may specify an existing index as well as an  in-
       dex  off	the end	of the old array; any existing value is	overwritten by
       value.  Also, it	is possible to use [key]+=value	to append to  the  ex-
       isting value at that index.

       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 ...)
	      name=([key]=value	...)

       Note  that  only	one of the two syntaxes	above may be used in any given
       assignment; the forms may not be	mixed.	This is	unlike the case	of nu-
       merically indexed arrays.

       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 ...)
	      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.  In the  second  form
       it is also possible to use [key]+=value to append to the	existing value
       at that key.  Expansion is performed identically	to  the	 corresponding
       forms for normal	arrays,	as described above.

       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.	 When combined with the	i or I
	      flag, the	effect is to produce the index of the first  character
	      of  the  first/last  word	 which matches the given pattern; note
	      that a failed match in this case always yields 0.

       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 &, put into the background with the bg builtin, or  spawned
	      with coproc.

       # <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.

       FUNCNEST	<S>
	      Integer.	If greater than	or equal to zero, the maximum  nesting
	      depth  of	 shell	functions.   When  it is exceeded, an error is
	      raised at	the point where	a function  is	called.	  The  default
	      value  is	 determined when the shell is configured, but is typi-
	      cally 500.  Increasing the value increases the danger of a  run-
	      away  function  recursion	causing	the shell to crash.  Setting a
	      negative value turns off the check.

       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 output of `git describe --tags --long' for the  zsh  reposi-
	      tory  used  to build the shell.  This is most useful in order to
	      keep track of versions of	the shell during  development  between
	      releases;	 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	kilobytes  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
		     kilobytes.
	      %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	 (e.g.,	 `%*E'); this causes the time to be printed in
	      `hh:mm:ss.ttt' format (hours and minutes	are  only  printed  if
	      they  are	 not  zero).   Alternatively,  `m'  or `u' may be used
	      (e.g., `%mE') to produce time  output  in	 milliseconds  or  mi-
	      croseconds, respectively.

       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 associated 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').

       CD_SILENT
	      Never  print  the	working	directory after	a cd (whether explicit
	      or implied with the AUTO_CD option set). cd normally prints  the
	      working  directory  when the argument given to it	was -, a stack
	      entry, or	the name of a directory	found under CDPATH. Note  that
	      this is distinct from pushd's stack-printing behaviour, which is
	      controlled by PUSHD_SILENT. This	option	overrides  the	print-
	      ing-related effects of POSIX_CD.

       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,	and the	cd and
	      chdir commands do	not recognise arguments	of the	form  `{+|-}n'
	      as directory stack entries.

	      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)
	      If the string on the command line	exactly	 matches  one  of  the
	      possible	completions,  it is accepted, even if there is another
	      completion (i.e. that string with	 something  else  added)  that
	      also matches.

   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
	      If set, regular expression matching with the  =~	operator  will
	      use  Perl-Compatible  Regular Expressions	from the PCRE library.
	      (The zsh/pcre module must	be available.)	If  not	 set,  regular
	      expressions  will	use the	extended 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,
	      and as if	they were zero when reading their values in arithmetic
	      expansion	 and  arithmetic commands.  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.

       WARN_NESTED_VAR
	      Print a warning message when an existing parameter from  an  en-
	      closing  function	 scope,	 or global, is set in a	function by an
	      assignment or in math context.  Assignment to shell special  pa-
	      rameters	does  not  cause  a warning.  This is the companion to
	      WARN_CREATE_GLOBAL as in this case the warning is	 only  printed
	      when a parameter is not created.	Where possible,	use of typeset
	      -g to set	the parameter suppresses the error, but	note that this
	      needs  to	 be used every time the	parameter is set.  To restrict
	      the effect of this option	to a single function scope, use	`func-
	      tions -W'.

	      For  example,  the following code	produces a warning for the as-
	      signment inside the function nested as that overrides the	 value
	      within toplevel

		     toplevel()	{
		       local foo="in fn"
		       nested
		     }
		     nested() {
			  foo="in nested"
		     }
		     setopt warn_nested_var
		     toplevel

   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  option  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.

       CHECK_RUNNING_JOBS <Z>
	      Check for	both running and suspended jobs	when CHECK_JOBS	is en-
	      abled.   When  this option is disabled, zsh checks only for sus-
	      pended jobs, which matches the default behavior of bash.

	      This option has no effect	unless CHECK_JOBS is set.

       HUP <Z>
	      Send the HUP signal to running jobs when the shell exits.

       LONG_LIST_JOBS (-R)
	      Print job	notifications 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
       ALIAS_FUNC_DEF <S>
	      By default, zsh does not allow the definition of functions using
	      the  `name  ()'  syntax  if  name	was expanded as	an alias: this
	      causes an	error.	This is	usually	the desired behaviour, as oth-
	      erwise  the  combination of an alias and a function based	on the
	      same definition can easily cause problems.

	      When this	option is set, aliases can be used for defining	 func-
	      tions.

	      For  example,  consider  the following definitions as they might
	      occur in a startup file.

		     alias foo=bar
		     foo() {
		       print This probably does	not do what you	expect.
		     }

	      Here, foo	is expanded as an alias	to bar before the  ()  is  en-
	      countered,  so  the function defined would be named bar.	By de-
	      fault this is instead an error in	native mode.  Note that	 quot-
	      ing  any	part  of the function name, or using the keyword func-
	      tion, avoids the problem,	so is recommended  when	 the  function
	      name can also be an alias.

       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.

	      Non-zero status in a command list	containing && or || is ignored
	      for commands not at the end of the list.	Hence

		     false && true

	      does not trigger exit.

	      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	similar	 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.

	      Normally	this  option  inherits	the behaviour of ERR_EXIT that
	      code followed by `&&' `||' does not trigger a return.  Hence  in
	      the following:

		     summit || true

	      no return	is forced as the combined effect always	has a zero re-
	      turn status.

	      Note. however, that if summit in the above example is  itself  a
	      function,	 code inside it	is considered separately: it may force
	      a	return from summit (assuming the  option  remains  set	within
	      summit),	but not	from the enclosing context.  This behaviour is
	      different	from ERR_EXIT which is unaffected by function scope.

       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, functions and shell builtins	are not	executed after
	      an  exec	prefix;	the command to be executed must	be an external
	      command found in the path.

	      Furthermore, the getopts builtin behaves in  a  POSIX-compatible
	      fashion in that the associated variable OPTIND is	not made local
	      to functions.

	      Moreover,	the warning and	special	exit code from [[ -o non_exis-
	      tent_option ]] are suppressed.

       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 zshexpn(1).)

       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 {1..9}' or
       `print -C 3 {1..9}' are equivalent.  Arguments to options are  not  the
       same  as	arguments to the command; the documentation indicates which is
       which.  Options that do not take	an argument may	be combined in a  sin-
       gle  word,  for example `print -rca -- *' and `print -r -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 `echo'	and 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-op-
       tion arguments, but is otherwise	ignored.   This	 is  useful  in	 cases
       where arguments to the command may begin	with `-'.  For historical rea-
       sons, most builtin commands (including `echo') also recognize a	single
       `-'  in	a separate word	for this purpose; note that this is less stan-
       dard and	use of `--' is recommended.

       - 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 dif-
	      ferent 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	[ {+|-}RTUXdkmrtWz ] [ -w ] [ name ... ]
	      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.

	      If name consists of an absolute path, the	function is defined to
	      load  from  the file given (searching as usual for dump files in
	      the given	location).  The	name of	the function is	 the  basename
	      (non-directory  part)  of	 the file.  It is normally an error if
	      the function is not found	in the given location; however,	if the
	      option  -d  is  given,  searching	 for  the function defaults to
	      $fpath.  If a function is	loaded by absolute path, any functions
	      loaded  from it that are marked for autoload without an absolute
	      path have	the load  path	of  the	 parent	 function  temporarily
	      prepended	to $fpath.

	      If  the  option  -r or -R	is given, the function is searched for
	      immediately and the location is recorded internally for use when
	      the  function is executed; a relative path is expanded using the
	      value of $PWD.  This protects against a change to	 $fpath	 after
	      the call to autoload.  With -r, if the function is not found, it
	      is silently left unresolved until	execution; with	-R,  an	 error
	      message  is  printed  and	command	processing aborted immediately
	      the search fails,	i.e. at	the autoload command  rather  than  at
	      function execution..

	      The flag -X may be used only inside a shell function.  It	causes
	      the calling function to be marked	for autoloading	and then imme-
	      diately  loaded  and  executed,  with the	current	array of posi-
	      tional parameters	as arguments.  This replaces the previous def-
	      inition of the function.	If no function definition is found, an
	      error is printed and the function	remains	undefined  and	marked
	      for  autoloading.	  If an	argument is given, it is used as a di-
	      rectory (i.e. it does not	include	the name of the	 function)  in
	      which the	function is to be found; this may be combined with the
	      -d option	to allow the function search to	default	to  $fpath  if
	      it is not	in the given location.

	      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 -t flag,	turn on	execution tracing; with	 -T,  turn  on
	      execution	 tracing only for the current function,	turning	it off
	      on entry to any called functions that do not also	 have  tracing
	      enabled.

	      With  the	 -U flag, alias	expansion is suppressed	when the func-
	      tion is 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.

	      Some of the functions of autoload	are also provided by functions
	      -u or functions -U, but autoload is a more comprehensive	inter-
	      face.

       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 POSIX_CD option is	set, this form of cd is	not recognised
	      and will be interpreted as the first form.

	      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 subsequent characters and	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.

	      Note that	for standards compliance a double dash does not	termi-
	      nate option processing; instead, it is printed  directly.	  How-
	      ever,  a	single	dash  does terminate option processing,	so the
	      first dash, possibly following options, is not printed, but  ev-
	      erything	following  it  is  printed as an argument.  The	single
	      dash behaviour is	different from other shells.  For a more  por-
	      table  way of printing text, see printf, and for a more control-
	      lable way	of printing text within	zsh, see print.

       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 command rather than forking.  If
	      command is a shell builtin command  or  a	 shell	function,  the
	      shell executes it, and exits when	the command is complete.

	      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	executed.  See
	      the section `Precommand Modifiers' in zshmisc(1).

	      If the option POSIX_BUILTINS is set,  command  is	 never	inter-
	      preted as	a shell	builtin	command	or shell function.  This means
	      further precommand modifiers such	as builtin and noglob are also
	      not interpreted within the shell.	 Hence command is always found
	      by searching the command path.

	      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 specified	by  -e
	      ename  is	invoked	on a file containing these history events.  If
	      -e 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 command 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 [ {+|-}UkmtTuWz ] [ -x	num ] [	name ... ]
       functions -c oldfn newfn
       functions -M [-s] mathfn	[ min [	max [ shellfn ]	] ]
       functions -M [ -m pattern ... ]
       functions +M [ -m ] mathfn ...
	      Equivalent  to  typeset -f, with the exception of	the -c,	-x, -M
	      and -W options.  For functions -u	 and  functions	 -U,  see  au-
	      toload, which provides additional	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.

	      The -W option turns on the option	WARN_NESTED_VAR	for the	 named
	      function	or  functions  only.   The option is turned off	at the
	      start of nested functions	(apart from anonoymous functions)  un-
	      less the called function also has	the -W attribute.

	      The  -c  option causes oldfn to be copied	to newfn.  The copy is
	      efficiently handled internally by	reference counting.  If	 oldfn
	      was marked for autoload it is first loaded and if	this fails the
	      copy fails.  Either function may subsequently be redefined with-
	      out  affecting  the other.  A typical idiom is that oldfn	is the
	      name of a	library	shell function which is	then redefined to call
	      newfn, thereby installing	a modified version of the function.

	      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.

	      If the additional	option -s is given to functions	-M, the	 argu-
	      ment  to	the  function is a single string: anything between the
	      opening and matching closing parenthesis is passed to the	 func-
	      tion  as	a single argument, even	if it includes commas or white
	      space.  The minimum and maximum argument specifiers must	there-
	      fore  be	1  if  given.	An  empty argument list	is passed as a
	      zero-length string.

	      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) ))

	      The following string function takes a single argument, including
	      the commas, so prints 11:

		     stringfn()	{ (( $#1 )) }
		     functions -Ms stringfn
		     print $(( stringfn(foo,bar,rod) ))

       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.

	      A	command	name starting with a / is never	hashed,	whether	by ex-
	      plicit  use of the hash command or otherwise.  Such a command is
	      always found by direct look up in	the file system.

	      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.  Note: if the	list of	arguments is empty,  print  -l
		     will  still  output  one  empty  line.  To	print a	possi-
		     bly-empty list of arguments one per line, use print  -C1,
		     as	in `print -rC1 -- "$list[@]"'.

	      -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.
		     Again, print -rNC1	-- "$list[@]" is a  canonical  way  to
		     print an arbitrary	list as	null-delimited records.

	      -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)).  In combination with `-f',	prompt
		     escape  sequences are parsed only within interpolated ar-
		     guments, not within the format string.

	      -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 [ {+|-}AHUaghlmrtux ] [ {+|-}EFLRZip [ n	] ]
	       [ + ] [ name[=value] ...	]
       typeset -T [ {+|-}Uglrux	] [ {+|-}LRZp [	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 [ n ]
		     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.

		     -p	may be followed	by an optional integer argument.  Cur-
		     rently only the value 1 is	supported.  In this  case  ar-
		     rays and associative arrays are printed with newlines be-
		     tween indented elements for readability.

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

		     When an existing scalar is	tied to	a new array, the value
		     of	the scalar is preserved	but no	attribute  other  than
		     export will be preserved.

	      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 tied parameters (see -T)  or  colon-sepa-
		     rated special parameters like PATH	or FIGNORE, etc.  Note
		     the flag takes effect on assignment, and the type of  the
		     variable  being  assigned	to is determinative; for vari-
		     ables 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;  autoload  gives further additional options
		     for the case typeset -fu and typeset -fU.

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

		     It	is still possible to change other  attributes  of  the
		     variable though, some of which like -U or -Z would	affect
		     the value.	More generally,	the readonly attribute	should
		     not be relied on as a security mechanism.

		     Note  that	 in  zsh  (like	in pdksh but unlike most other
		     shells) it	is still possible to create a  local  variable
		     of	 the same name as this is considered a different vari-
		     able (though this variable, too, can be marked readonly).
		     Special  variables	 that  have  been made readonly	retain
		     their value and readonly attribute	when made local.

	      -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.  If job represents an	unknown	job or process
	      ID, a warning is printed (unless the  POSIX_BUILTINS  option  is
	      set) and the exit	status is 127.

	      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.

	      If  name	is  not	 an alias, built-in command, external command,
	      shell function, hashed command, or a  reserved  word,  the  exit
	      status  shall be non-zero, and --	if -v, -c, or -w was passed --
	      a	message	will be	written	to standard output.  (This is  differ-
	      ent  from	 other	shells that write that message to standard er-
	      ror.)

	      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 ]	[ -s ] [ ... ]
       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 [ -is ] 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.  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 com-
		     patibility	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.

		     If	the option -s is given,	no error  is  printed  if  the
		     module  was not available (though other errors indicating
		     a problem with the	module are printed).  The return  sta-
		     tus  indicates  if	the module was loaded.	This is	appro-
		     priate if the caller considers the	module optional.

		     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; this is  implemented  by
       the  digit-argument  widget.  See  also the Arguments subsection	of the
       Widgets section for some	other ways the numeric argument	can  be	 modi-
       fied.

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 [ -Aacghe ] [ -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.  The	-g flag	may be
	      given to	suppress  warnings  from  the  WARN_CREATE_GLOBAL  and
	      WARN_NESTED_VAR options.

	      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 redirected from /dev/null to prevent external
       commands	from unintentionally blocking ZLE by reading from  the	termi-
       nal,  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 parameters 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.

       KEYS_QUEUED_COUNT (integer)
	      The number of bytes pushed back to the input queue and therefore
	      available	for  reading  immediately  before  any	I/O  is	 done;
	      read-only.  See also PENDING; the	two values are distinct.

       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.
	      See also KEYS_QUEUED_COUNT; the two values are distinct.

       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_RECURSIVE (integer)
	      Usually zero, but	incremented  inside  any  instance  of	recur-
	      sive-edit.  Hence	indicates the current recursion	level.

	      ZLE_RECURSIVE 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  has  been interrupted	by output from another
	      part of the shell	(such as a job notification) which causes  the
	      command line to be reprinted.

	      reset-prompt doesn't alter the special parameter LASTWIDGET.

       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 one to three ASCII digits  representing  the
	      colour.	Only  used  for	palette	colors,	i.e. not 24-bit	colors
	      specified	via a color triplet.

       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.  See
	      fg_start_code above.

       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	 inte-
	      ger,  the	name of	one of the eight most widely-supported colours
	      or as a `#' followed by an RGB triplet in	hexadecimal format.

	      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).

	      Some  modern  terminal  emulators	 have  support for 24-bit true
	      colour (16 million colours). In this case, the hex triplet  for-
	      mat  can	be  used.  This	consists of a `#' followed by either a
	      three or six digit hexadecimal number describing the red,	 green
	      and blue components of the colour. Hex triplets can also be used
	      with 88 and 256 colour terminals via  the	 zsh/nearcolor	module
	      (see zshmodules(1)).

	      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 [ -akqQfenUl12C ] [ -F array ]
	       [-P prefix ] [ -S suffix	]
	       [-p hidden-prefix ] [ -s	hidden-suffix ]
	       [-i ignored-prefix ] [ -I ignored-suffix	]
	       [-W file-prefix ] [ -d array ]
	       [-J group-name ]	[ -X explanation ] [ -x	message	]
	       [-V group-name ]	[ -o [ order ] ]
	       [-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 [ order ]
		     This controls the order in	which matches are sorted.  or-
		     der  is  a	 comma-separated list comprising the following
		     possible values.  These  values  can  be  abbreviated  to
		     their initial two or three	characters.  Note that the or-
		     der forms part of the group name space  so	 matches  with
		     different orderings will not be in	the same group.

		     match  If given, the order	of the output is determined by
			    the	match strings; otherwise it is	determined  by
			    the	display	strings	(i.e. the strings given	by the
			    -d option).	This is	the default if `-o' is	speci-
			    fied but the order argument	is omitted.

		     nosort This specifies that	the matches are	pre-sorted and
			    their order	should be preserved.  This value  only
			    makes  sense alone and cannot be combined with any
			    others.

		     numeric
			    If the matches include numbers, sort them  numeri-
			    cally rather than lexicographically.

		     reverse
			    Arrange  the  matches  backwards  by reversing the
			    sort ordering.

	      -J group-name
		     Gives the name of the group of matches the	 words	should
		     be	stored in.

	      -V group-name
		     Like  -J  but  naming  an	unsorted group.	This option is
		     identical to the combination of -J	and -o nosort.

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

		     Within  the  explanation,	the following sequences	may be
		     used to specify output attributes	as  described  in  the
		     section  EXPANSION	 OF  PROMPT  SEQUENCES	in zshmisc(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 argu-
		     ment to `%{' should be used instead.)  The	sequence  `%%'
		     produces a	literal	`%'.

		     These  sequences  are  most  often	employed by users when
		     customising the format  style  (see  zshcompsys(1)),  but
		     they must also be taken into account when writing comple-
		     tion functions, as	passing	 descriptions  with  unescaped
		     `%'  characters  to  utility functions such as _arguments
		     and _message may produce unexpected results. If arbitrary
		     text  is to be passed in a	description, it	can be escaped
		     using e.g.	${my_str//\%/%%}.

	      -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 value of the PREFIX	parameter is at	 least	number
		     characters	 long, the first number	characters are removed
		     from it and appended to the contents of the  IPREFIX  pa-
		     rameter.

	      -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.	Setting	$_compskip in this  manner  is
	      of particular utility when using the -p option, as otherwise the
	      dispatcher will move on to additional functions (likely the  de-
	      fault one) after calling the pattern-context one,	which can man-
	      gle the display of completion possibilities if not handled prop-
	      erly.

	      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.

	      This style is also useful	when completing	after directories that
	      magically	 appear	 when referenced, such as ZFS .zfs directories
	      or NetApp	.snapshot directories.	When  the  style  is  set  the
	      shell  does  not check for the existence of the directory	within
	      the parent 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 (but see accept-exact-dirs	for a more general way
	      of dealing with this problem).  It can also be used for directo-
	      ries 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.

       file-split-chars
	      A	set of characters that will cause all file completions for the
	      given  context to	be split at the	point where any	of the charac-
	      ters occurs.  A typical use is to	set the	style to :;  then  ev-
	      erything	up to and including the	last : in the string so	far is
	      ignored when completing files.  As this is  quite	 heavy-handed,
	      it is usually preferable to update completion functions for con-
	      texts where this behaviour is useful.

       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	 output	 attribute  sequences understood by compadd -X
	      (see zshcompwid(1)).

	      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.

	      For  notes comparing the use of this and the matcher-list	style,
	      see under	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.

	      For notes	comparing the use of this and the matcher  style,  see
	      under the	description of the tag-order style.

       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	 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   This allows the standard ordering	of matches to be overridden.

	      If its value is `true' or	`false', sorting is  enabled  or  dis-
	      abled.   Additionally the	values associated with the `-o'	option
	      to compadd can also be listed: match, nosort, numeric,  reverse.
	      If  it is	not set	for the	context, the standard behaviour	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.

	      In many cases where a calling widget explicitly selects  a  par-
	      ticular  ordering	 in  lieu of the default, a value of `true' is
	      not honoured.  An	example	of where this is not the case  is  for
	      command history where the	default	of sorting matches chronologi-
	      cally may	be overridden by setting 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.

       _cmdambivalent
	      Completes	the remaining positional arguments as an external com-
	      mand.  The external command and its arguments are	 completed  as
	      separate	arguments  (in	a  manner  appropriate	for completing
	      /usr/bin/env) if there are two or	more remaining positional  ar-
	      guments  on the command line, and	as a quoted command string (in
	      the manner of system(...)) otherwise.  See also  _cmdstring  and
	      _precommand.

	      This function takes no arguments.

       _cmdstring
	      Completes	 an external command as	a single argument, as for sys-
	      tem(...).

       _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.

       _precommand
	      Complete an external command in word-separated arguments,	as for
	      exec and /usr/bin/env.

       _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	... ] -- [ -l ]	[ -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.  To avoid ambigu-
	      ity, all options to _arguments itself may	be separated 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  arr