zshall



ZSHALL(1)                                                            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:

       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
       zshzftpsys   Zsh built-in FTP client


DESCRIPTION

       Zsh  is  a  UNIX  command  interpreter (shell) usable as an interactive
       login shell and as a shell script command processor.  Of  the  standard
       shells,  zsh most closely resembles ksh but includes many enhancements.
       Zsh has command line editing, builtin spelling correction, programmable
       command completion, shell functions (with autoloading), a history 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@sunsite.dk>.  The development is  currently  coordinated  by  Peter
       Stephenson <pws@zsh.org>.  The coordinator can be contacted at <coordi-
       nator@zsh.org>, but matters relating to the code should generally go to
       the mailing list.


AVAILABILITY

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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



MAILING LISTS

       Zsh has 3 mailing lists:

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

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

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

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

       <zsh-announce-subscribe@sunsite.dk>
       <zsh-users-subscribe@sunsite.dk>
       <zsh-workers-subscribe@sunsite.dk>
       <zsh-announce-unsubscribe@sunsite.dk>
       <zsh-users-unsubscribe@sunsite.dk>
       <zsh-workers-unsubscribe@sunsite.dk>

       YOU ONLY NEED TO JOIN ONE OF THE MAILING LISTS AS THEY ARE NESTED.  All
       submissions  to  zsh-announce are automatically forwarded to zsh-users.
       All submissions to zsh-users are automatically forwarded  to  zsh-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
       archive,   maintained   by   Geoff  Wing  <gcw@zsh.org>,  available  at
       http://www.zsh.org/mla/.


THE ZSH FAQ

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


THE ZSH WEB PAGE

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


THE ZSH USERGUIDE

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


THE ZSH WIKI

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


INVOCATION OPTIONS

       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.

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

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

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

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

              zsh -x -o shwordsplit scr

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

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

       The special GNU-style option ‘--version’ is handled; it sends to  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 ‘s’ or ‘k’ it will emulate sh or ksh.
       Furthermore, if invoked as su (which happens on  certain  systems  when
       the shell is executed by the su command), the shell will try to find an
       alternative name from the SHELL environment variable and perform emula-
       tion 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_OPTION_LETTERS,   SH_WORD_SPLIT.    Additionally  the  BSD_ECHO  and
       IGNORE_BRACES options are set if zsh  is  invoked  as  sh.   Also,  the
       KSH_OPTION_PRINT,  LOCAL_OPTIONS,  PROMPT_BANG,  PROMPT_SUBST  and 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:

       ·      changing directories with the cd builtin

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

       ·      specifying command names containing /

       ·      specifying command pathnames using hash

       ·      redirecting output to files

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

       ·      using jobs -Z to overwrite the shell process’ argument and envi-
              ronment space

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

       ·      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
       RESTRICTED option.   This  immediately  enables  all  the  restrictions
       described  above  even if the shell still has not processed all startup
       files.


STARTUP/SHUTDOWN FILES

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

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

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

       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-
ZSHMISC(1)                                                          ZSHMISC(1)



       nal file, the compiled file will be used instead.


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.  The first word is the command to be executed, and the remain-
       ing  words, if any, are arguments to the command.  If a command name is
       given, the parameter assignments modify the environment of the  command
       when it is executed.  The value of a simple command is its exit status,
       or 128 plus the signal number if terminated by a signal.  For example,

              echo foo

       is a simple command with arguments.

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

              echo foo | sed s/foo/bar/

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

       If a pipeline is preceded by ‘coproc’, it is executed as a coprocess; a
       two-way pipe is established between it and the parent shell.  The shell
       can read from or write to the coprocess by means of the ‘>&p’ and ‘<&p’
       redirection operators or with ‘print -p’ and  ‘read  -p’.   A  pipeline
       cannot be preceded by both ‘coproc’ and ‘!’.  If job control is active,
       the coprocess can be treated in other than input and output as an 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
       (returns a zero value).  If two pipelines are separated  by  ‘||’,  the
       second  is  executed only if the first fails (returns a nonzero value).
       Both operators have equal precedence and  are  left  associative.   The
       value  of  the sublist is the value of the last pipeline executed.  For
       example,

              dmesg | grep panic && print yes

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

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

       More generally, a list can be seen as a set of any shell commands 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.

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

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

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

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

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


COMPLEX COMMANDS

       A complex command in zsh is one of the following:

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

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

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

       for (( [expr1] ; [expr2] ; [expr3] )) do list done
              The arithmetic expression expr1 is evaluated first (see 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.

       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’.
              If  the  list that is executed is terminated with ;& rather than
              ;;, the following list is also executed.  This  continues  until
              either a list is terminated with ;; or the esac is reached.

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

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

       { list }
              Execute list.

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

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

              An ‘error’ in this context is a condition such as a syntax error
              which causes the shell to abort execution of the  current  func-
              tion,  script,  or  list.   Syntax  errors encountered while the
              shell is parsing the code do not cause  the  always-list  to  be
              executed.   For  example, an erroneously constructed if block in
              try-list would cause the shell to abort during parsing, so  that
              always-list  would not be executed, while an erroneous 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
              integer variable TRY_BLOCK_ERROR.  Outside  an  always-list  the
              value  is  irrelevant,  but  it  is  initialised  to -1.  Inside
              always-list, the  value  is  1  if  an  error  occurred  in  the
              try-list,  else  0.   If  TRY_BLOCK_ERROR is set to 0 during the
              always-list, the error  condition  caused  by  the  try-list  is
              reset,  and  shell execution continues normally after the end of
              always-list.  Altering the value during the try-list is not use-
              ful (unless this forms part of an enclosing always block).

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

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

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

              An exit command encountered in try-list does not cause the  exe-
              cution  of  always-list.   Instead,  the shell exits immediately
              after any EXIT trap has been executed.

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

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

       time [ pipeline ]
              The pipeline is executed, and timing statistics are reported  on
              the  standard error in the form specified by the TIMEFMT 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 particular
       versions of complex commands should be considered deprecated and may be
       removed  in the future.  The versions in the previous section should be
       preferred instead.

       The short versions below only work if sublist is of the form ‘{ list }’
       or  if the SHORT_LOOPS option is set.  For the if, while and until 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
              select.


RESERVED WORDS

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

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

       Additionally, ‘}’ is recognized in any position  if  the  IGNORE_BRACES
       option is not set.


COMMENTS

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

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


QUOTING

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

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

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

              print 

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

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


REDIRECTION

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

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

       < word Open file word for reading as standard input.

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

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

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

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

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

       <<[-] word
              The shell input is read up to a line that is the same  as  word,
              or to an end-of-file.  No parameter expansion, command 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
              behave similarly to double quotes, except  that  the  backquotes
              themselves  are  passed through unchanged.  (This information is
              given for completeness and it is not recommended that backquotes
              be  used.)  Quotes in the form $... have their standard effect
              of expanding backslashed references to special characters.

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

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

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

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

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

       >& word
       &> word
              (Except where ‘>& word’ matches one of the above syntaxes;  ‘&>’
              can  always  be  used  to avoid this ambiguity.)  Redirects both
              standard output and standard error (file descriptor  2)  in  the
              manner  of  ‘>  word’.   Note  that  this does not have the same
              effect as ‘> word 2>&1’ in the presence of multios (see the 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 |’.

       For output redirections only, if word is of the form ‘>(list)’ then the
       output  is  piped to the command represented by list.  See Process Sub-
       stitution in zshexpn(1).


MULTIOS

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

              date >foo >bar

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

              date >foo | cat

       writes the date to the file ‘foo’, and also pipes it to cat.

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

              : > *

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

              echo exit 0 >> *.sh

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

              sort <foo <fubar

       or even

              sort <f{oo,ubar}

       is equivalent to ‘cat foo fubar | sort’.

       Note that a pipe is an implicit redirection; thus

              cat bar | sort <foo

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

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

              echo foo > bar > baz

       when MULTIOS is unset will truncate bar, and write ‘foo’ into baz.

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

              cat file >file1 >file2
              cat file1 file2

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

       The  reason for this is that the multios are spawned after the cat pro-
       cess 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.


FUNCTIONS

       Shell functions are defined with the function reserved word or the spe-
       cial syntax ‘funcname ()’.  Shell functions  are  read  in  and  stored
       internally.  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
       inside 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
       autoload builtin or its equivalent is given the option -U. This is rec-
       ommended  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
              expected to contain the definitions for  all  functions  in  the
              directory 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
       directory in fpath; second, if more than one of these contains a  defi-
       nition  for  the  function that is sought, the leftmost in the fpath is
       chosen; 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
       itself is not re-executed.  To force the shell to  perform  initializa-
       tion  and  then call the function defined, the file should contain ini-
       tialization code (which will be executed then discarded) in addition to
       a  complete  function definition (which will be retained for subsequent
       calls to the function), and a call to the shell function, including any
       arguments, 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
       autoloaded, but which loads its own definition by searching  fpath,  by
       using  ‘autoload -X’ within a shell function.  For example, the follow-
       ing 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,
       because all comments are discarded from defined functions.

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

              autoload +X myfunc



SPECIAL FUNCTIONS

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

       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.

       precmd Executed before each prompt.

       preexec
              Executed just after a command has been read and is about  to  be
              executed.   If the history mechanism is active (and the line was
              not discarded from the history buffer), the string that the user
              typed  is passed as the first argument, otherwise 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 version of  the  command
              (with  things  like  function bodies elided); the third argument
              contains the full text that is being executed.

       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 value 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 normal  effect  of  the
              signal  is  produced; if this causes execution to terminate, the
              status returned to the shell is the  status  returned  from  the
              function.

              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
              Executed after each command.

       TRAPEXIT
              Executed  when  the  shell  exits,  or when the current function
              exits if defined inside a function.

       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  functions  beginning  ‘TRAP’ may alternatively be defined with the
       trap builtin:  this may be preferable for some uses, as they  are  then
       run in the environment of the calling process, rather than in their own
       function environment.  Apart from the difference in  calling  procedure
       and  the fact that the function form appears in lists of functions, the
       forms

              TRAPNAL() {
               # code
              }

       and

              trap 
               # code

       are equivalent.


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.  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
       referred 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
              Any job whose command line begins with string.
       %?string
              Any 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.   Other-
       wise,  signals  have  the values inherited by the shell from its parent
       (but see the TRAPNAL special functions in the section ‘Functions’).


ARITHMETIC EVALUATION

       The shell can perform integer and  floating  point  arithmetic,  either
       using 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 is always double precision.

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

       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
       affected.   If  an  integer variable is implicitly defined by an arith-
       metic expression, any base specified in this way will  be  set  as  the
       variable’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 occurs more than once in a mathematical expression, the last encoun-
       tered 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.

       If  the  C_BASES  option  is set, 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 output of bases other than hexadecimal and
       octal, and these formats are always understood on input.

       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.

       An arithmetic expression uses nearly the same syntax,  precedence,  and
       associativity  of  expressions  in C.  The following operators are sup-
       ported (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.

       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
       defines no mathematical functions by default, but the module  zsh/math-
       func may be loaded with the zmodload builtin to provide standard float-
       ing 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 ASCII value of this character and
       an expression of the form ‘#foo’ gives the ASCII  value  of  the  first
       character of the value of the parameter foo.  Note that this is differ-
       ent from the expression  ‘$#foo’,  a  standard  parameter  substitution
       which  gives the length of the parameter foo.  ‘#\’ 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 down to the next integer.

       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 down to
       the next integer.

       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
       retain that type either until the type is explicitly changed  or  until
       the  end  of  the  scope.   This can have unforeseen consequences.  For
       example, in the loop

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

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


CONDITIONAL EXPRESSIONS

       A  conditional  expression is used with the [[ compound command to test
       attributes of files and to compare strings.   Each  expression  can  be
       constructed  from  one or more of the following unary or binary expres-
       sions:

       -a file
              true if file exists.

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

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

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

       -e file
              true if file exists.

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

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

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

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

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

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

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

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

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

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

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

       -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 ‘==’ form is the  preferred
              one.   The  ‘=’ form is for backward compatibility and should be
              considered obsolete.

       string != pattern
              true if string does not match 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.

       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.

       Normal shell expansion is performed on the  file,  string  and  pattern
       arguments, but the result of each expansion is constrained to be a sin-
       gle word, similar to the effect of  double  quotes.   However,  pattern
       metacharacters  are  active for the pattern arguments; the patterns are
       the same as those used for filename  generation,  see  zshexpn(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
       descriptor 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.


PROMPT EXPANSION

       Prompt sequences undergo a special form of  expansion.   This  type  of
       expansion 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.  Some escapes  take  an  optional  integer
       argument, which should appear between the ‘%’ and the next character of
       the sequence.  The following escape sequences are recognized:


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

       %?     The return code 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.

       %d
       %/     Present  working  directory  ($PWD).   If an integer follows the
              ‘%’, it specifies a number of trailing  components  of  $PWD  to
              show;  zero  means the whole path.  A negative integer specifies
              leading components, i.e. %-1d specifies the first component.

       %~     As %d and %/, but if $PWD has a named directory as  its  prefix,
              that  part  is  replaced  by  a  ‘~’ followed by the name of the
              directory.  If it starts with $HOME, that part is replaced by  a
              ‘~’.

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

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

       %c
       %.
       %C     Trailing component of $PWD.  An integer may follow  the  ‘%’  to
              get  more  than  one component.  Unless ‘%C’ is used, tilde con-
              traction is performed first.  These are deprecated as %c and  %C
              are equivalent to %1~ and %1/, respectively, while explicit pos-
              itive 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.  Three additional codes are available:
              %f  prints the day of the month, like %e but without any preced-
              ing space if the day is a single digit, and %K/%L correspond  to
              %k/%l  for  the  hour  of the day (24/12 hour clock) in the same
              way.


   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.

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


   Conditional substrings
       %v     The value of the first element of  the  psvar  array  parameter.
              Following  the  ‘%’  with  an  integer gives that element of the
              array.  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
              escape 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.  The test character x may be any of  the  fol-
              lowing:

              !      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.
              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.
              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.
              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  numeric  argument,
              which  in  the  third form may appear immediately after the ‘[’,
              specifies the maximum permitted length of  the  various  strings
              that  can  be  displayed in the prompt.  The string will be dis-
              played in place of the truncated portion  of  any  string;  note
              this does not undergo prompt expansion.

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




NAME

       zshexpn - zsh expansion and substitution


DESCRIPTION

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

       History Expansion
              This is performed only in interactive shells.

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

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

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

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

       The following sections explain the types of expansion in detail.



HISTORY EXPANSION

       History expansion allows you to use words from previous  command  lines
       in  the  command line you are typing.  This simplifies spelling correc-
       tions and the repetition of complicated commands or arguments.  Immedi-
       ately  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 Prompt Expansion in zshmisc(1)) is
       the number that is to be assigned to the next command.


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

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

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

       For  example,  ‘!’ is the event designator for the previous command, so
       ‘!!:1’ always refers to the first word of  the  previous  command,  and
       ‘!!$’  always  refers  to  the last word of the previous command.  With
       CSH_JUNKIE_HISTORY set, then ‘!:1’ and ‘!$’ function in the same manner
       as  ‘!!:1’  and ‘!!$’, respectively.  Conversely, if CSH_JUNKIE_HISTORY
       is unset, then ‘!:1’ and ‘!$’  refer  to  the  first  and  last  words,
       respectively, 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 ‘^’.

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

       !      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
              repeats 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
              before 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
       expansion, except where noted.

       h      Remove a trailing pathname component, leaving  the  head.   This
              works like ‘dirname’.

       r      Remove a filename extension of the form ‘.xxx’, leaving the root
              name.

       e      Remove all but the extension.

       t      Remove all leading pathname components, leaving the tail.   This
              works like ‘basename’.

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

       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.

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

       l      Convert the words to all lowercase.

       u      Convert the words to all uppercase.

       s/l/r[/]
              Substitute r for l as described below.  Unless preceded  immedi-
              ately  by  a  g, with no colon between, 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.

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

       The  s/l/r/  substitution works as follows.  The left-hand side of sub-
       stitutions are not regular expressions,  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.

       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
              until 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 command argument of the form ‘<(list)’, ‘>(list)’ or ‘=(list)’  is
       subject  to process substitution.  In the case of the < or > forms, the
       shell runs process list asynchronously.  If  the  system  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 special 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 pro-
       cess2.

       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.

       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
       security  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
       behaviour)  block  for  ever and have to be killed explicitly.  In both
       cases, the shell actually supplies the information  using  a  pipe,  so
       that  programmes  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 pro-
       cess 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
       described 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 asyn-
       chronously.  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.



PARAMETER EXPANSION

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

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

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

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

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

       ${name:-word}
              If name is set and is non-null then substitute its value; other-
              wise substitute word. If name is missing, substitute word.

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

       ${name:?word}
              If name is set and is non-null then substitute its value; other-
              wise, print word and exit from the  shell.   Interactive  shells
              instead  return to the prompt.  If word is omitted, then a stan-
              dard message is printed.

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

       If  the colon is omitted from one of the above expressions containing a
       colon, then the shell only checks whether name is set, not whether  its
       value is null.

       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/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.  Both
              pattern and repl are subject to double-quoted  substitution,  so
              that  expressions  like  ${name/$opat/$npat} will work, but note
              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.   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.

              The first ‘/’ may be preceded by a ‘:’, in which case the  match
              will  only succeed if it matches the entire word.  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
              result 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.  Note that ‘^’, ‘=’, and ‘~’, below, must  appear
              to the left of ‘#’ when these forms are combined.

       ${^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’.

              Internally, each such expansion is converted into the equivalent
              list   for   brace    expansion.     E.g.,    ${^var}    becomes
              {$var[1],$var[2],...}, and is processed as described in the sec-
              tion ‘Brace Expansion’ below.  If  word  splitting  is  also  in
              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
              affects 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.

       If a ${...} type parameter expression or a $(...) type command  substi-
       tution  is  used  in  place of name above, it is expanded first and the
       result 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
       examples below.  Each name or nested ${...} in  a  parameter  expansion
       may  also  be  followed by a subscript expression as described in Array
       Parameters 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
       below)  is  applied using the rules for unquoted expansions.  Note fur-
       ther 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
       before.


   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:

       %      Expand all % escapes in the resulting words in the same  way  as
              in in prompts (see the section ‘Prompt Expansion’). 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 the f, s or z flags,
              which still applies within each array element.

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

       a      With o or O, sort in array index order. Note that ‘oa’ is there-
              fore  equivalent to the default but ‘Oa’ is useful for obtaining
              an array’s elements in reverse order.

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

       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.

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

       f      Split  the result of the expansion to lines. This is a shorthand
              for ‘ps:\n:’.

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

       i      With o or O, sort case-independently.

       k      If  name  refers  to  an  associative array, substitute the keys
              (element 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 val-
              ues.   However,  this  flag  may  not be combined with subscript
              ranges.

       L      Convert all letters in the result to lower case.

       n      With o or O, sort numerically.

       o      Sort the resulting words in ascending order.

       O      Sort the resulting words in descending order.

       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. If used with a nested parameter or command substitution,
              the result 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’.

       q      Quote the resulting words with  backslashes.  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.  If it is given four times, the words are quoted in sin-
              gle quotes preceded by a $.

       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
              consists of keywords separated by hyphens (‘-’). The first  key-
              word  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

              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
              repeated delimiters are also counted.

       X      With  this  flag parsing errors occurring with the Q and e flags
              or the pattern matching  forms  such  as  ‘${name#pattern}’  are
              reported. Without the flag they 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.

              Note  that  this is done very late, as for the ‘(s)’ flag. So to
              access single words in the result, one has to use nested  expan-
              sions as in ‘${${(z)foo}[2]}’. Likewise, to remove the quotes in
              the resulting words one would do: ‘${(Q)${(z)foo}}’.

       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.

       j:string:
              Join  the  words of arrays together using string as a separator.
              Note  that  this  occurs   before   field   splitting   by   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  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,  this string is inserted once
              directly to the left of each word, before padding.

       r:expr::string1::string2:
              As l, but pad the words on the right and insert string2  on  the
              right.

       s:string:
              Force field splitting (see the option SH_WORD_SPLIT) at the sep-
              arator string.  Note that a string of  two  or  more  characters
              means  all  must  all  match  in sequence; this differs from the
              treatment of two or more characters in the IFS parameter.

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

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

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

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

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

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

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

       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
       accepts  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  substitution;  for  example,  the  expansion   ${${foo}}
              behaves exactly the same as ${foo}.

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

       3. Parameter Name Replacement
              The  effect  of any (P) flag, which treats the value so far as a
              parameter name and replaces it with the corresponding value,  is
              applied.

       4. Double-Quoted Joining
              If  the  value after this process is an array, and the substitu-
              tion appears in double quotes, and no (@) flag is present at the
              current  level, the words of the value are joined with the first
              character of the parameter $IFS, by  default  a  space,  between
              each  word  (single  word  arrays are not modified).  If the (j)
              flag is present, that is used for joining instead of $IFS.

       5. 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 2., 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).

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

       7. Forced Joining
              If  the  ‘(j)’  flag is present, or no ‘(j)’ flag is present but
              the string is to be split as given by rules 8. or 9., and  join-
              ing  did  not  take place at step 4., any words in the value are
              joined together 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.

       8. Forced Splitting
              If one of the ‘(s)’, ‘(f)’ or ‘(z)’ flags are  present,  or  the
              ‘=’  specifier  was present (e.g. ${=var}), the word is split on
              occurrences of the specified string, or (for = with  neither  of
              the two flags present) any of the characters in $IFS.

       9. Shell Word Splitting
              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
              occurrences  of  any of the characters in $IFS.  Note this step,
              too, takes place at all levels of a nested substitution.

       10. Re-Evaluation
              Any ‘(e)’ flag is  applied  to  the  value,  forcing  it  to  be
              re-examined  for  new parameter substitutions, but also for com-
              mand and arithmetic substitutions.

       11. Padding
              Any padding of the value by the ‘(l.fill.)’ or ‘(r.fill.)’ flags
              is applied.

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


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

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

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

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

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

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

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

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



COMMAND SUBSTITUTION

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


ARITHMETIC EXPANSION

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


BRACE EXPANSION

       A  string  of the form ‘foo{xx,yy,zz}bar’ is expanded to the individual
       words ‘fooxxbar’, ‘fooyybar’ and ‘foozzbar’.   Left-to-right  order  is
       preserved.   This  construct  may  be  nested.  Commas may be quoted in
       order 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.  If the numbers are in decreasing
       order the resulting sequence will also be in decreasing order.

       If a brace expression matches none of  the  above  forms,  it  is  left
       unchanged,  unless  the  BRACE_CCL  option is set.  In that case, it is
       expanded to a sorted list of  the  individual  characters  between  the
       braces,  in the manner of a search set.  ‘-’ is treated specially as in
       a search set, but ‘^’ or ‘!’ as the first  character  is  treated  nor-
       mally.

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


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
       described 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 the value of $PWD or $OLDPWD, respectively.

       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
       directory 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
       exchanges the effects of ‘~+’ and ‘~-’ where they  are  followed  by  a
       number.

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

       In  certain  circumstances  (in  prompts, for instance), when the shell
       prints a path, the path is checked to see if it has a  named  directory
       as  its  prefix.  If so, then the prefix portion is replaced with a ‘~’
       followed by the name of the directory.  The shortest way  of  referring
       to  the  directory is used, with ties broken in favour of using a named
       directory, except when the directory is / itself.  The parameters  $PWD
       and $OLDPWD are never abbreviated in this fashion.

       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.

       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
       behaviour  can  be  disabled  by quoting the ‘~’, the ‘=’, or the whole
       expression (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
       inhibits 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
       option 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:  ‘[:alnum:]’
              alphanumeric,   ‘[:alpha:]’   alphabetic,   ‘[:ascii:]’   7-bit,
              ‘[:blank:]’  space  or  tab,  ‘[:cntrl:]’   control   character,
              ‘[:digit:]’   decimal  digit,  ‘[:graph:]’  printable  character
              except whitespace,  ‘[:lower:]’  lowercase  letter,  ‘[:print:]’
              printable  character,  ‘[:punct:]’  printable  character neither
              alphanumeric nor whitespace, ‘[:space:]’  whitespace  character,
              ‘[:upper:]’  uppercase  letter,  ‘[:xdigit:]’ hexadecimal digit.
              These use the macros provided by the operating  system  to  test
              for  the  given  character combinations, including any modifica-
              tions due to local language settings:  see ctype(3).  Note  that
              the  square brackets are additional to those enclosing the whole
              set of characters, so to test for a single alphanumeric  charac-
              ter  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
              instead.

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

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

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

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

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

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

       x##    (Requires  EXTENDED_GLOB to be set.)  Matches one or more occur-
              rences of the pattern x.  This  operator  has  high  precedence;
              ‘12##’ is equivalent to ‘1(2##)’, rather than ‘(12)##’.  No more
              than two active ‘#’ characters may appear together.

   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 ‘(...)#’.)

       +(...) Match at least one occurrence.  (Like ‘(...)##’.)

       ?(...) Match zero or one occurrence.  (Like ‘(|...)’.)

       !(...) Match  anything  but  the  expression  in  parentheses.    (Like
              ‘(^(...))’.)

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

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

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

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

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

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

              For example,

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

              prints  ‘string  with  a’.   Note  that the first parenthesis is
              before the (#b) and does not create a backreference.

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

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

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

              Pattern  matching  with  backreferences  is slightly slower than
              without.

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

       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
              expressions.  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
              ‘${array/(#s)A*Z(#e)}’  will  remove  only  elements of an array
              which match the complete pattern ‘A*Z’.  There are other ways of
              performing 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.

       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
       delimited by grouping.  For example, (#a1)cat((#a0)dog)fox  allows  one
       error 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
       approximate match.  It is best to place the (#a1) after any  path  seg-
       ments which are known to be correct.


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

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

              ls (*/)#bar

       or

              ls **/bar

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

   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.

       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)

       %      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
              exactly, 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
              access 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
              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).  The first charac-
              ter after the ‘e’ will be used as a separator and anything up to
              the next matching separator 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.

              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 lonely2’ to be inserted  into  the
              command line.  Note the quotation marks.

       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 it is a number, if  not,  than  the
              character  after  the  ‘u’  will  be used as a separator and the
              string between it and the next matching separator (‘[’, ‘{’, and
              ‘<’  match  ‘]’,  ‘}’, and ‘>’ respectively, any other character
              matches itself) will be taken as a user name, and the user ID of
              this  user  will  be  taken  (e.g. ‘u:foo:’ or ‘u[foo]’ for 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.  For instance, ‘echo *(ah-5)’ would echo files  accessed
              within the last 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
              inode 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  ‘k’
              (‘K’),  ‘m’ (‘M’), or ‘p’ (‘P’) (e.g. ‘Lk-50’) the check is per-
              formed with kilobytes,  megabytes,  or  blocks  (of  512  bytes)
              instead.

       ^      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

       oc     specifies how the names of the files should be sorted. If c is n
              they are sorted by name (the default);  if  it  is  L  they  are
              sorted  depending  on  the size (length) of the files; if l they
              are sorted by the number 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 directory 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.  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.

       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.

       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’).  Note  that  each  modifier
       must  be introduced by a separate ‘:’.  Note also that the result after
       modification does not have to be an existing file.   The  name  of  any
       existing file can be followed by a modifier of the form ‘(:..)’ even if
       no actual filename generation is performed.  Thus:

              ls *(-/)

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

              ls *(%W)

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

              ls *(W,X)

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

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

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

              ls *.*~(lex|parse).[ch](^D^l1)

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

              print b*.pro(#q:s/pro/shmo/)(#q.:s/builtin/shmiltin/)

       demonstrates  how  colon  modifiers and other qualifiers may be chained
       together.  The ordinary qualifier ‘.’ is applied first, then the  colon
       modifiers  in order from left to right.  So if EXTENDED_GLOB is set and
       the base pattern matches the regular file builtin.pro, the  shell  will
ZSHPARAM(1)                                                        ZSHPARAM(1)



       print ‘shmiltin.shmo’.


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 ‘!’.  The value may
       be a scalar (a string), an integer, an array (indexed numerically),  or
       an  associative array (an unordered set of name-value pairs, indexed by
       name).  To declare the type of a parameter, or to assign  a  scalar  or
       integer value to a parameter, use the typeset builtin.

       The  value  of  a  scalar  or integer parameter may also be assigned by
       writing:

              name=value

       If the integer attribute, -i, is set for name, the value is subject  to
       arithmetic  evaluation.   Furthermore,  by  replacing  ‘=’ with ‘+=’, a
       parameter can be added or appended to.  See the section ‘Array  Parame-
       ters’ for additional forms of assignment.

       To  refer to the value of a parameter, write ‘$name’ or ‘${name}’.  See
       Parameter Expansion in zshexpn(1) for complete details.

       In the parameter lists that follow, the mark ‘<S>’ indicates  that  the
       parameter  is  special.   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
       retained.  ‘<Z>’ indicates that the parameter does not exist  when  the
       shell initializes in sh or ksh emulation mode.


ARRAY PARAMETERS

       To assign an array value, write one of:

              set -A name value ...
              name=(value ...)

       If  no  parameter  name exists, an ordinary array parameter is created.
       If the parameter name exists and is a scalar, it is replaced by  a  new
       array.  Ordinary array parameters may also be explicitly declared with:

              typeset -a name

       Associative arrays must be declared before assignment, by using:

              typeset -A name

       When name refers to an associative array, the list in an assignment  is
       interpreted as alternating keys and values:

              set -A name key value ...
              name=(key value ...)

       Every  key  must  have a value in this case.  Note that this assigns to
       the entire array, deleting any elements that do not appear in the list.

       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
       expressions otherwise are not treated as subscripts.

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


   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
       replaced by the expression on the right side.  An  array  (but  not  an
       associative  array) may be created by assignment to a range or element.
       Arrays do not nest, so assigning a parenthesized list of values  to  an
       element  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 sin-
       gle-element assignments may be made with typeset.  Note that quotes are
       necessary  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
       expression  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 currently understood are:

       w      If  the  parameter  subscripted is a scalar than this flag makes
              subscripting work on words instead of characters.   The  default
              word separator is whitespace.

       s:string:
              This  gives  the string that separates words (for use with the w
              flag).

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

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

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

       I      Like ‘i’, but gives the index of the last match, or all possible
              matching keys in an associative array.

       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.  This
              flag does not work on the left side of an assignment to an asso-
              ciative  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
              ignored when the array is associative.

       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.

       e      This flag has no effect and for ordinary arrays is retained  for
              backward  compatibility only.  For associative arrays, this flag
              can be used to force * or @ to be interpreted as  a  single  key
              rather than as a reference to all values.  This flag may be used
              on the left side of an assignment.

       See Parameter Expansion  Flags  (zshexpn(1))  for  additional  ways  to
       manipulate 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.

       It is possible to avoid the use of subscripts in assignments  to  asso-
       ciative array elements by using the syntax:


                 aa+=(key with "*strange*" characters value string)

       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.

       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
       inside 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
       balanced braces, and subscript flags are introduced by balanced  paren-
       thesis.

       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
       parameter 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
       expanded 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,
       because 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
       parameter, 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  parameters  *,  @
       and  argv  are  arrays  containing  all the positional parameters; thus
       ‘$argv[n]’, etc., is equivalent to simply ‘$n’.

       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

       The following parameters are automatically set by the shell:

       ! <S>  The process ID of the last background command invoked.

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

       - <S>  Flags supplied to the shell on  invocation  or  by  the  set  or
              setopt commands.

       * <S>  An array containing the positional parameters.

       argv <S> <Z>
              Same  as  *.   Assigning  to  argv  changes the local positional
              parameters, 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 value returned by the last command.

       0 <S>  The  name  used  to  invoke  the  current  shell.   If the FUNC-
              TION_ARGZERO option is set, this is  set  temporarily  within  a
              shell function to the name of the function, and within a sourced
              script to the name of the script.

       status <S> <Z>
              Same as ?.

       pipestatus <S> <Z>
              An array containing the exit values 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
              determined 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)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)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
              intended for debugging purposes.  It is  also  useful  with  the
              zsh/system  module  which  allows the number to be turned into a
              name or message.

       GID <S>
              The real group ID of the shell process.  If you have  sufficient
              privileges,  you may change the group ID of the shell process by
              assigning to this parameter.  Also (assuming  sufficient  privi-
              leges),  you  may start a single command under a different group
              ID by ‘(GID=gid; command)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.

       MACHTYPE
              The machine type (microprocessor class  or  machine  model),  as
              determined 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.

       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
              result  in  identical  pseudo-random  values unless the value of
              RANDOM is referenced or seeded in the parent  shell  in  between
              subshell 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 precision is six decimal places, although
              not all places may be useful.

       SHLVL <S>
              Incremented by one each time a new shell is started.

       signals
              An array containing the names of the signals.

       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)

       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)USERNAME <S>
              The username corresponding to the real user ID of the shell pro-
              cess.  If you have sufficient privileges,  you  may  change  the
              username  (and  also  the  user ID and group ID) of the shell by
              assigning to this parameter.  Also (assuming  sufficient  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_NAME
              Expands  to  the  basename  of  the  command used to invoke this
              instance of zsh.

       ZSH_VERSION
              The version number of this zsh.


PARAMETERS USED BY THE SHELL

       The following parameters are used by the shell.

       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
       manipulate within the shell.  Note that unsetting either  of  the  pair
       will  unset the other; they retain their special properties when recre-
       ated, 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  baud rate of the current connection.  Used by the line edi-
              tor update mechanism to compensate for a slow terminal by delay-
              ing  updates  until  necessary.  This may be profitably set to a
              lower value in some circumstances, e.g.  for slow modems dialing
              into  a communications server which is connected to a host via a
              fast link; in this case, this variable would be set  by  default
              to  the speed of the fast link, and not the modem.  This parame-
              ter should be set to the baud rate of the slowest  part  of  the
              link  for  best  performance.  The compensation mechanism can be
              turned off by setting the variable to zero.

       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.

       DIRSTACKSIZE
              The maximum size of the directory  stack.   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 zsh is emulating sh or ksh.

       FCEDIT The default editor for the fc builtin.

       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 ‘#’).

       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.

       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.

       HOME <S>
              The default argument for the cd command.

       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.

       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.

       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
              default message is ‘You have new mail’.   If  an  element  is  a
              directory  instead  of  a  file the shell will recursively check
              every file in every subdirectory of the element.

       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.

       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.

       PS1 <S>
              The primary prompt string, printed before  a  command  is  read.
              the  default  is ‘%m%# ’.  It undergoes a special form of expan-
              sion before being displayed; see the section ‘Prompt Expansion’.

       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 first nine values 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.

       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.

       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  SINGLELINEZLE  option  is  set.   It  is
              expanded 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  SINGLELINEZLE  option  is  set.  It is
              expanded in the same way as PS2.

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

       SPROMPT <S>
              The  prompt  used  for  spelling  correction.  The sequence ‘%R’
              expands to the string which presumably  needs  spelling  correc-
              tion,  and  ‘%r’  expands to the proposed correction.  All other
              prompt escapes are also allowed.

       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
              explicitly 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  specifi-
              cations; 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.

       TIMEFMT
              The format of process time reports with the time  keyword.   The
              default is ‘%E real  %U user  %S system  %P %J’.  Recognizes the
              following escape sequences:

              %%     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 (%U+%S)/%E.
              %J     The name of this job.

              A star may be inserted between the percent sign and flags print-
              ing  time.   This cause the time to be printed in ‘hh:mm:ss.ttt’
              format (hours and minutes are  only  printed  if  they  are  not
              zero).

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

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

       watch <S> <Z> (WATCH <S>)
              An  array  (colon-separated  list)  of  login/logout  events  to
              report.   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 or all of these components  may  be  present  in  an
              entry;  if  a  login/logout  event  matches  all  of them, it is
              reported.

       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.

              %(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.
                     Either  or  both  of  the branches may be empty, but both
                     separators 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),
ZSHOPTIONS(1)                                                    ZSHOPTIONS(1)



              if not $HOME.


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
       ‘notify’).

       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 ‘+’
       instead of ‘-’.  Some of the single letter option  names  refer  to  an
       option  being  off,  in which case the inversion of that name refers to
       the option being on.  For example, ‘+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
       options (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.

       AUTO_PUSHD (-N)
              Make cd push the old directory onto the directory stack.

       CDABLE_VARS (-T)
              If  the  argument  to  a  cd  command (or an implied cd with the
              AUTO_CD option set) is not a directory, and does not begin  with
              a  slash, try to expand the expression as if it were preceded by
              a ‘~’ (see the section ‘Filename Expansion’).

       CHASE_DOTS
              When changing to a directory  containing  a  path  segment  ‘..’
              which  would otherwise be treated as canceling the previous seg-
              ment in the path (in other words, ‘foo/..’ would be removed from
              the  path,  or  if  ‘..’ is the first part of the path, the last
              part of $PWD would be deleted), 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.

       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
              repeatedly. 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
              directory, 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
              respected.  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.

       HASH_LIST_ALL <D>
              Whenever a command completion is attempted, make sure the entire
              command  path  is hashed first.  This makes the first completion
              slower.

       LIST_AMBIGUOUS <D>
              This option works when AUTO_LIST or BASH_AUTO_LIST is also  set.
              If there is an unambiguous prefix to insert on the command line,
              that is done without a completion list being displayed; in other
              words,  auto-listing  behaviour  only  takes  place when nothing
              would be inserted.  In the case of  BASH_AUTO_LIST,  this  means
              that the list will be delayed to the third call of the function.

       LIST_BEEP <D>
              Beep on an ambiguous completion.  More accurately,  this  forces
              the  completion  widgets to return status 1 on an ambiguous com-
              pletion, which causes the shell to beep if the  option  BEEP  is
              also  set;  this  may be modified if completion is called from a
              user-defined widget.

       LIST_PACKED
              Try to make the completion list smaller (occupying  less  lines)
              by printing the matches in columns with different widths.

       LIST_ROWS_FIRST
              Lay  out  the  matches  in completion lists sorted horizontally,
              that is, the second match is to the right of the first one,  not
              under it as usual.

       LIST_TYPES (-X) <D>
              When  listing files that are possible completions, show the type
              of each file with a trailing identifying mark.

       MENU_COMPLETE (-Y)
              On an ambiguous completion, instead of listing possibilities  or
              beeping,  insert the first match immediately.  Then when comple-
              tion is requested again, remove the first match and  insert  the
              second  match,  etc.  When there are no more matches, go back to
              the first one again.  reverse-menu-complete may be used to  loop
              through  the  list in the other direction. This option overrides
              AUTO_MENU.

       REC_EXACT (-S)
              In completion, recognize exact matches even if they are  ambigu-
              ous.


   Expansion and Globbing
       BAD_PATTERN (+2) <C> <Z>
              If  a  pattern for filename generation is badly formed, print an
              error message.  (If this option is unset, the  pattern  will  be
              left unchanged.)

       BARE_GLOB_QUAL <Z>
              In  a  glob  pattern,  treat  a trailing set of parentheses as a
              qualifier list, if it contains no ‘|’, ‘(’ or (if  special)  ‘~’
              characters.  See the section ‘Filename Generation’.

       BRACE_CCL
              Expand  expressions  in braces which would not otherwise undergo
              brace expansion to a lexically ordered list of all  the  charac-
              ters.  See the section ‘Brace Expansion’.

       CASE_GLOB <D>
              Make  globbing  (filename  generation)  sensitive to case.  Note
              that other uses of patterns are always sensitive  to  case.   If
              the option is unset, the presence of any character which is spe-
              cial to filename generation will cause  case-insensitive  match-
              ing.   For  example, cvs(/) can match the directory CVS owing to
              the  presence  of  the  globbing   flag   (unless   the   option
              BARE_GLOB_QUAL is unset).

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

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

       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_SUBST <C> <K> <S>
              Treat any characters resulting from parameter expansion as being
              eligible  for  file  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.

       IGNORE_BRACES (-I) <S>
              Do not perform brace expansion.

       KSH_GLOB <K>
              In  pattern  matching,  the  interpretation  of  parentheses  is
              affected 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 wordsplitting.

       MARK_DIRS (-8, ksh: -X)
              Append a trailing ‘/’ to  all  directory  names  resulting  from
              filename generation (globbing).

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

       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.  This option
              is set by default if zsh is invoked as sh or ksh.

       UNSET (+u, ksh: +u) <K> <S> <Z>
              Treat unset parameters as if they were empty when  substituting.
              Otherwise they are treated as an error.


   History
       APPEND_HISTORY <D>
              If  this  is set, zsh sessions will append their history list to
              the history file, rather than overwrite it. Thus, multiple  par-
              allel  zsh  sessions  will all have their history lists added to
              the history file, in the order they are killed.

       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 when an attempt is made 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_FIND_NO_DUPS
              When searching for history entries in the line  editor,  do  not
              display  duplicates  of  a  line  previously  found, even if the
              duplicates 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
              duplicates 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.  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_NO_FUNCTIONS
              Remove  function  definitions  from the history list.  Note that
              the function lingers in the  internal  history  until  the  next
              command  is  entered before it vanishes, allowing you to briefly
              reuse 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_NO_DUPS
              When writing out the history file, older commands that duplicate
              newer ones are omitted.

       HIST_VERIFY
              Whenever  the  user  enters a line with history expansion, don’t
              execute the line directly; instead,  perform  history  expansion
              and reload the line into the editing buffer.

       INC_APPEND_HISTORY
              This  options  works like APPEND_HISTORY except that new history
              lines are added to the $HISTFILE incrementally (as soon as  they
              are  entered),  rather  than  waiting until the shell is killed.
              The file is periodically trimmed to the number of  lines  speci-
              fied  by $SAVEHIST, but can exceed this value between trimmings.

       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).   The
              history  lines are also output with timestamps ala EXTENDED_HIS-
              TORY (which makes it easier to find the spot where we  left  off
              reading 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_APPEND_HISTORY  on,  and then manually import commands when-
              ever 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
              declare, float, integer, readonly and typeset  (but  not  local)
              will  also  set  the  -g flag;  hence parameters exported to the
              environment 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
              local 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, and  ‘>>’  to
              create files.  Otherwise ‘>!’ or ‘>|’ must be used to truncate a
              file, and ‘>>!’ or ‘>>|’ to create a file.

       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.

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

       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.

       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
              beginning with ‘/’, ‘./’ or ‘../’ are not subject  to  the  path
              search.  This also applies to the . builtin.

              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.

       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.

       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.


   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 the precmd function is not  counted  for
              this purpose.

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

       LONG_LIST_JOBS (-R)
              List jobs in the long format by default.

       MONITOR (-m, ksh: -m)
              Allow job control.  Set by default in interactive shells.

       NOTIFY (-5, ksh: -b) <Z>
              Report  the  status  of background jobs immediately, rather than
              waiting until just before printing a prompt.


   Prompting
       PROMPT_BANG <K>
              If set, ‘!’ is treated specially in prompt expansion.   See  the
              section ‘Prompt Expansion’.

       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_PERCENT <C> <Z>
              If set, ‘%’ is treated specially in prompt expansion.   See  the
              section ‘Prompt Expansion’.

       PROMPT_SUBST <K>
              If set, parameter expansion, command substitution and arithmetic
              expansion are performed in prompts.

       TRANSIENT_RPROMPT
              Remove any right prompt from display when  accepting  a  command
              line.   This  may  be useful with terminals with other cut/paste
              methods.


   Scripts and Functions
       C_BASES
              Output hexadecimal numbers in the standard C format, for example
              ‘0xFF’ instead of the usual ‘16#FF’.  If the option OCTAL_ZEROES
              is also set (it is  not  by  default),  octal  numbers  will  be
              treated  similarly  and hence appear as ‘077’ instead of ‘8#77’.
              This option has no effect on the choice of the output base,  nor
              on  the  output of bases other than hexadecimal and octal.  Note
              that these formats will be understood on input  irrespective  of
              the setting of C_BASES.

       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.  cidnex(return from function, on error)

       ERR_RETURN
              If a command has a non-zero exit status, return immediately from
              the enclosing function.  The logic  is  identical  to  that  for
              ERR_EXIT,  except  that an implicit return statement is executed
              instead of an exit.  This will trigger an exit at the  outermost
              level of a non-interactive script.

       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.

       LOCAL_OPTIONS <K>
              If  this option is set at the point of return from a shell func-
              tion, all the options (including this one) which were  in  force
              upon  entry  to the function are restored.  Otherwise, only this
              option and the 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_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;
              unlike  LOCAL_OPTIONS,  the  value  on exit from the function is
              irrelevant.  However, it does not need  to  be  set  before  any
              global  trap  for  that  to be correctly restored by a function.
              For example,

                     unsetopt localtraps
                     trap - INT
                     fn() { setopt localtraps; trap  INT; sleep 3; }

              will restore normally handling  of  SIGINT  after  the  function
              exits.

       MULTIOS <Z>
              Perform  implicit  tees  or  cats when multiple redirections are
              attempted (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.

       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.


   Shell Emulation
       BSD_ECHO <S>
              Make the echo builtin compatible with the BSD  echo(1)  command.
              This  disables  backslashed  escape  sequences  in  echo strings
              unless the -e option is specified.

       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, 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
              option is set, array elements are numbered from zero,  an  array
              parameter  without subscript refers to the first element instead
              of the whole array, and braces are required to  delimit  a  sub-
              script (‘${path[2]}’ rather than just ‘$path[2]’).

       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 <K>
              Alters  the  way  arguments  to  the typeset family of commands,
              including declare, export, float, integer, local  and  readonly,
              are  processed.   Without  this  option, zsh will perform normal
              word splitting after command and parameter  expansion  in  argu-
              ments  of  an  assignment; with it, word splitting does not take
              place in those cases.

       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.

       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
              expansions.  Note that this option has nothing to do  with  word
              splitting.  (See the section ‘Parameter Expansion’.)

       TRAPS_ASYNC
              While  waiting  for  a  program  to exit, handle signals and run
              traps immediately.  Otherwise the trap is run after a child pro-
              cess  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 cannot be
              changed anywhere other than the command line.

       LOGIN (-l, ksh: -l)
              This is a login shell.  If this option is  not  explicitly  set,
              the shell is 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.  This  is  enabled  automatically  on
              startup  if  the  effective  user (group) ID is not equal to the
              real user (group) ID.  Turning this option off causes the effec-
              tive  user  and  group  IDs to be set to the real user and group
              IDs. This option disables sourcing user startup files.   If  zsh
              is invoked as ‘sh’ or ‘ksh’ with this option set, /etc/suid_pro-
              file 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 function
              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
              option on the command line does not necessarily affect the state
              the option will have while the shell is running - that is purely
              an indicator of whether on not commands are actually being  read
              from standard input.  The value of this option cannot be changed
              anywhere other than the command line.

       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 cannot be changed
              anywhere other than the command line.


   Zle
       BEEP (+B) <D>
              Beep on error in ZLE.

       EMACS  If ZLE is loaded, turning on  this  option  has  the  equivalent
              effect  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.

       VI     If ZLE is loaded, turning on  this  option  has  the  equivalent
              effect 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
ZSHBUILTINS(1)                                                  ZSHBUILTINS(1)



       -s     Used by set to sort positional parameters


NAME

       zshbuiltins - zsh built-in commands


SHELL BUILTIN COMMANDS

       - simple command
              See the section ‘Precommand Modifiers’.

       . 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
              parameters;  the old positional parameters are restored when the
              file is done executing.  The exit 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 code 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,
              define a global alias; global aliases are expanded even if  they
              do not occur in command position.

              If  the  -s flags is present, define a suffix alias: if the com-
              mand word on a command line is in the  form  ‘text.name’,  where
              text  is any non-empty string, it is replaced by the text ‘value
              text.name’.  Note that name is treated as a literal string,  not
              a  pattern.   A  trailing  space in value is not special in this
              case.  For example,

                     alias -s ps=gv

              will cause the command ‘*.ps’ to be expanded to ‘gv  *.ps’.   As
              alias expansion is carried out earlier than globbing, the ‘*.ps’
              will then be expanded.  Suffix aliases  constitute  a  different
              name  space  from  other  aliases (so in the above example it is
              still possible to create an alias for the command  ps)  and  the
              two sets are never listed together.

              For  each  name  with no value, print the value of name, if any.
              With no arguments, print all  currently  defined  aliases  other
              than  suffix aliases.  If the -m flag is given the arguments are
              taken as patterns (they should be quoted to preserve  them  from
              being  interpreted  as  glob patterns), and the aliases matching
              these patterns are printed.  When printing aliases  and  one  of
              the  -g,  -r  or  -s  flags is present, restrict the printing to
              global, regular or suffix aliases, respectively; a regular alias
              is one which is neither a global nor a suffix alias.   Using ‘+’
              instead of ‘-’, or ending the option list  with  a  single  ‘+’,
              prevents the values of the aliases from being printed.

              If  the  -L  flag  is present, then print each alias in a manner
              suitable for putting in a startup script.  The  exit  status  is
              nonzero  if  a  name (with no value) is given for which no alias
              has been defined.

       autoload [ {+|-}UXktz ] [ -w ] [ name ... ]
              Equivalent to functions -u, with the exception of -X/+X and  -w.

              The  flag  -X  may be used only inside a shell function, and may
              not be followed by a name.  It causes the calling function to be
              marked for autoloading and then immediately loaded and executed,
              with the current array of positional  parameters  as  arguments.
              This  replaces  the  previous definition of the function.  If no
              function definition is found, an error is printed and the  func-
              tion remains undefined and marked for autoloading.

              The  flag  +X  attempts to load each name as an autoloaded func-
              tion, but does not execute it.  The exit status  is  zero  (suc-
              cess)  if  the function was not previously defined and a defini-
              tion for it was found.  This does not replace any existing defi-
              nition of the function.  The exit status is nonzero (failure) if
              the function was already  defined  or  when  no  definition  was
              found.   In  the  latter case the function remains undefined and
              marked for autoloading.  If ksh-style  autoloading  is  enabled,
              the  function created will contain the contents of the file plus
              a call to the function itself appended to it, thus giving normal
              ksh autoloading behaviour on the first call to the function.

              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.

       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 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 [ -sLP ] [ arg ]
       cd [ -sLP ] old new
       cd [ -sLP ] {+|-}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 value of $OLDPWD, the
              previous directory.  Otherwise, if a directory named arg is  not
              found  in  the  current  directory and arg does not begin with a
              slash, search each component of the shell parameter cdpath.   If
              no  directory  is found and 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 -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 followed  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
              instead 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’.

       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 n is  specified,  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.

              -p     print directory entries one per line.

              -v     number the directories in the stack when printing.


       disable [ -afmrs ] name ...
              Temporarily disable the named hash table elements.  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 arguments  all
              disabled  hash  table elements from the corresponding hash table
              are printed.  With the -m flag the arguments are taken  as  pat-
              terns  (which  should  be quoted to prevent them from undergoing
              filename expansion), and all hash table elements from the corre-
              sponding  hash table matching these patterns are disabled.  Dis-
              abled objects can be enabled with the enable command.

       disown [ job ... ]
       job ... &|
       job ... &!
              Remove the specified jobs from the job table; the shell will  no
              longer  report their status, and will not complain if you try to
              exit an interactive shell with them running or stopped.   If  no
              job is specified, disown the current job.

              If  the  jobs are currently stopped and the AUTO_CONTINUE option
              is not set, a warning is printed  containing  information  about
              how  to make them running after they have been disowned.  If one
              of the latter two forms is used, the jobs will automatically  be
              made  running,  independent  of the setting of the AUTO_CONTINUE
              option.

       echo [ -neE ] [ arg ... ]
              Write each arg on the standard output, with a  space  separating
              each one.  If the -n flag is not present, print a newline at the
              end.  echo recognizes the following escape sequences:

              \a     bell character
              \b     backspace
              \c     suppress final newline
              \e     escape
              \f     form feed
              \n     linefeed (newline)
              \r     carriage return
              \t     horizontal tab
              \v     vertical tab
              \\     backslash
              \0NNN  character code in octal
              \xNN   character code in hexadecimal
              \uNNNN unicode character code in hexadecimal
              \UNNNNNNNN
                     unicode character code in hexadecimal

              The -E flag, or the BSD_ECHO option,  can  be  used  to  disable
              these escape sequences.  In the latter case, -e flag can be used
              to enable them.

       echotc See the section ‘The zsh/termcap Module’ in zshmodules(1).

       echoti See the section ‘The zsh/terminfo Module’ in zshmodules(1).

       emulate [ -LR ] {zsh|sh|ksh|csh}
              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 ‘Compatibility’ in zsh-
              misc(1) .  If the -R option is given, all options are  reset  to
              their  default  value  corresponding  to the specified emulation
              mode, except for  certain  options  describing  the  interactive
              environment;  otherwise,  only  those  options  likely  to cause
              portability problems in scripts and functions are  altered.   If
              the   -L   option   is  given,  the  options  LOCAL_OPTIONS  and
              LOCAL_TRAPS will be set as well, causing the effects of the emu-
              late command and any setopt and trap commands to be local to the
              immediately surrounding shell function, if any;  normally  these
              options are turned off in all emulation modes except ksh.

       enable [ -afmrs ] 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.

       eval [ arg ... ]
              Read the arguments as input to the shell and execute the result-
              ing command in the current shell process.

       exec simple command
              See the section ‘Precommand Modifiers’.

       exit [ n ]
              Exit  the  shell  with  the exit code specified by n; if none is
              specified, use the exit code from the last command executed.  An
              EOF  condition  will  also  cause  the shell to exit, unless the
              IGNORE_EOF option is set.

       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 code of 1.

       fc [ -e ename ] [ -nlrdDfEim ] [ old=new ... ] [ first [ last ] ]
       fc -p [ -a ] [ filename [ histsize [ savehistsize ] ] ]
       fc -P
       fc -ARWI [ filename ]
              Select  a  range of commands from first to last from the history
              list.  The arguments first and last may be specified as a number
              or  as  a string.  A negative number is used as an offset to the
              current history event  number.   A  string  specifies  the  most
              recent event beginning with the given string.  All substitutions
              old=new, if any, are then performed on the commands.

              If the -l flag is given, the resulting commands  are  listed  on
              standard  output.   If the -m flag is also given the first argu-
              ment is taken as a pattern (should be quoted) and only the  his-
              tory  events matching this pattern will be shown.  Otherwise the
              editor program ename is invoked on a file containing these  his-
              tory  events.  If ename is not given, the value of the parameter
              FCEDIT is used.  If ename is ‘-’, no editor  is  invoked.   When
              editing is complete, the edited command is executed.

              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.

              The flag -r reverses the order of the commands and the  flag  -n
              suppresses  command numbers when listing.  Also when listing, -d
              prints timestamps for each command, and -f prints full time-date
              stamps.   Adding  the  -E flag causes the dates to be printed as
              ‘dd.mm.yyyy’, instead of the default ‘mm/dd/yyyy’.   Adding  the
              -i  flag  causes the dates to be printed in ISO8601 ‘yyyy-mm-dd’
              format.  With the -D flag, fc prints elapsed times.


              ‘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
              append/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 [ {+|-}EFHghlprtux ] [ name[=value] ... ]
              Equivalent  to  typeset  -E,  except  that options irrelevant to
              floating point numbers are not permitted.

       functions [ {+|-}UXkmtuz ] [ name ... ]
              Equivalent to typeset -f.

       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 is expected to have 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
              assigning to OPTIND.  OPTIND has an initial value of 1,  and  is
              normally  reset to 1 upon exit from a shell function.  OPTARG 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
              unknown  option  and  to  ‘:’ when a required option is missing.
              Otherwise, getopts sets name to ‘?’ and prints an error  message
              when  an  option  is  invalid.   The exit status is nonzero when
              there are no more options.

       hash [ -Ldfmrv ] [ name[=value] ] ...
              hash can be used to directly modify the contents of the  command
              hash  table,  and  the named directory hash table.  Normally one
              would modify these tables by modifying one’s PATH (for the  com-
              mand  hash  table)  or  by creating appropriate shell parameters
              (for the named directory hash table).  The choice of hash  table
              to  work  on  is determined by the -d option; without the option
              the command hash table is used, and with the  option  the  named
              directory hash table is used.

              Given  no  arguments,  and  neither  the  -r  or -f options, the
              selected 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
              option causes the selected hash table to be fully rebuilt  imme-
              diately.   For  the command hash table this hashes all the abso-
              lute 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
              selected 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 [ {+|-}Hghilprtux ] [ name[=value] ... ]
              Equivalent to typeset -i,  except  that  options  irrelevant  to
              integers 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.

       let arg ...
              Evaluate each arg as an arithmetic expression.  See the  section
              ‘Arithmetic  Evaluation’ for a description of arithmetic expres-
              sions.  The exit status is 0 if the value of the last expression
              is nonzero, and 1 otherwise.

       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
              resource, 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.
              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.
              resident
                     Maximum resident set size.
              sockbufsize
                     Maximum size of all socket buffers.
              stacksize
                     Maximum stack size for each process.
              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
              [mm:]ss
                     minutes and seconds

       local [ {+|-}AEFHLRUZahilprtux [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’.

       popd [ {+|-}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
              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.

       print [ -abcDilmnNoOpPrsz ] [ -u n ] [ -f format ] [ -C cols ]
         [ -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’  metafies  the
              character  x  (sets  the highest bit), ‘\C-x’ produces a control
              character  (‘\C-@’  and  ‘\C-?’  give  the  characters  NUL  and
              delete),  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 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 directory  names,  replacing  pre-
                     fixes with ~ expressions, as appropriate.

              -i     If  given  together  with  -o or -O, sorting is performed
                     case-independently.

              -l     Print the arguments  separated  by  newlines  instead  of
                     spaces.

              -m     Take  the first argument as a pattern (should be quoted),
                     and remove it from the argument list together with subse-
                     quent arguments that do not match this pattern.

              -n     Do not add a newline to the output.

              -N     Print the arguments separated and terminated by nulls.

              -o     Print the arguments sorted in ascending order.

              -O     Print the arguments sorted in descending order.

              -p     Print the arguments to the input of the coprocess.

              -P     Perform prompt expansion (see zshmisc(1)).

              -r     Ignore the escape conventions of echo.

              -R     Emulate  the  BSD  echo  command,  which does not process
                     escape 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.

              -u n   Print the arguments to file descriptor n.

              -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 format [ arg ... ]
              Print  the arguments according to the format specification. For-
              matting rules are the  same  as  used  in  C.  The  same  escape
              sequences  as  for echo are recognised in the format. All C con-
              version 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  speci-
              fiers, if the corresponding argument starts with a quote charac-
              ter, the numeric value of the following character is used as the
              number to print otherwise the argument is evaluated as an arith-
              metic expression. See the section ‘Arithmetic Evaluation’ for  a
              description  of  arithmetic  expressions.  With ‘%n’, the corre-
              sponding 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.

       pushd [ -sLP ] [ arg ]
       pushd [ -sLP ] old new
       pushd [ -sLP ] {+|-}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
              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 option PUSHD_SILENT is not set, the directory stack will
              be printed after 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.
                     Currently does not work with the -q option.

              -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 value is  zero  only
                     if  the  character was ‘y’ or ‘Y’.  Note that this always
                     reads from the terminal, even if used with the -p  or  -u
                     or  -z  flags  or with redirected input.  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
                     ignored when -q is present.  Input is read from the  ter-
                     minal unless one of -u or -p is present.  This option may
                     also be used within zle widgets.

              -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
                     ignored 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
                     instead 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
                     immediately 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  stan-
                     dard error when the shell is interactive.

              The  value  (exit  status)  of  read is 1 when an end-of-file is
              encountered, 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.

       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 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.  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
              replace 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
              arguments  following  name  are treated as values for the array,
              regardless 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.

       setcap See the section ‘The zsh/cap Module’ in zshmodules(1).

       setopt [ {+|-}options | {+|-}o option_name ] [ 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.  If  the  -m
              flag  is given the arguments are taken as patterns (which should
              be quoted to protect them  from  filename  expansion),  and  all
              options with names matching these patterns are set.

       shift [ 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
              instead of the positional parameters.

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

       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 sig.  Each sig can be given as a number or as
              the  name  of  a  signal.  If arg is ‘-’, then all traps sig are
              reset to their default values.  If arg is the empty string, then
              this  signal  is  ignored  by  the  shell and by the commands it
              invokes.

              If sig is ZERR then arg will be executed after each command with
              a  nonzero  exit  status.  If sig is DEBUG then arg will be exe-
              cuted after each command.  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.  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.

              ZERR,  DEBUG and EXIT traps are not executed inside other traps.

              The trap command with no arguments prints  a  list  of  commands
              associated with each signal.

              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.

       true [ arg ... ]
              Do nothing and return an exit code of 0.

       ttyctl -fu
              The -f option freezes the tty, 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  sus-
              pended.  Thus, stty and similar programs have no effect when the
              tty is frozen.  Without options it reports whether the  terminal
              is frozen or not.

       type [ -wfpams ] name ...
              Equivalent to whence -v.

       typeset [ {+|-}AEFHLRUZafghiklprtuxmz [n]] [ name[=value] ... ]
       typeset -T [ {+|-}LRUZrux ] SCALAR[=value] array [ sep ]
              Set or display attributes and values for shell parameters.

              A parameter is created for each name that does not already refer
              to one.  When inside a function, a new parameter is created  for
              every  name  (even those that already exist), and is unset again
              when the function completes.  See  ‘Local  Parameters’  in  zsh-
              param(1).   The  same  rules  apply to special shell parameters,
              which retain their special attributes when made local.

              For each name=value assignment, the parameter  name  is  set  to
              value.  Note that arrays currently cannot be assigned in typeset
              expressions, only scalars and integers.

              If the shell option TYPESET_SILENT is not set, for each  remain-
              ing  name  that  refers to a parameter that is 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 the -p option is given, parameters and values are printed  in
              the  form  of  a typeset comand and an assignment (which will be
              printed separately for arrays and associative  arrays),  regard-
              less  of  other  flags  and  options.   Note that the -h flag on
              parameters is respected; no value will be shown for these param-
              eters.

              If  the  -T  option  is  given,  two  or three arguments must be
              present (an exception is that zero arguments are allowed to show
              the  list of parameters created in this fashion).  The first two
              are the name of a scalar and 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.   Only  the  scalar  parameter  may  be
              assigned  an  initial  value.  Both the scalar and the array may
              otherwise be manipulated as normal.  If one is unset, the  other
              will automatically be unset too.  There is no way of untying the
              variables without unsetting them, or converting the type of  one
              of  them with another typeset command; +T does not work, assign-
              ing 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).

              The  -g  (global)  flag  is treated specially: it 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 effect when  list-
              ing  existing  parameters,  nor does the flag +g have any effect
              except in combination with -m (see below).

              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
              attributes,  and using ‘+’ rather than ‘-’ to introduce the flag
              suppresses printing of the values of parameters when there is no
              parameter  name.  Also, if the last option is the word ‘+’, then
              names are printed but values are not.

              If the -m flag is given the name arguments are taken as patterns
              (which  should be quoted).  With no attribute flags, all parame-
              ters (or functions with the -f flag)  with  matching  names  are
              printed  (the  shell  option  TYPESET_SILENT is not used in this
              case).  Note that -m is ignored if no patterns  are  given.   If
              the  +g  flag is combined with -m, a new local parameter is cre-
              ated for every matching parameter that  is  not  already  local.
              Otherwise  -m  applies  all  other  flags  or assignments to the
              existing parameters.  Except  when  assignments  are  made  with
              name=value,  using  +m  forces  the  matching  parameters  to be
              printed, even inside a function.

              If no attribute flags are given and either no -m flag is present
              or the +m form was used, each parameter name printed is preceded
              by a list of the attributes of that parameter  (array,  associa-
              tion,   exported,  integer,  readonly).   If  +m  is  used  with
              attribute flags, and all those flags are introduced with +,  the
              matching parameter names are printed but their values are not.

              The following attribute flags may be specified:

              -A     The  names  refer  to  associative  array parameters; see
                     ‘Array Parameters’ in zshparam(1).

              -L     Left justify and remove leading blanks from value.  If  n
                     is  nonzero, it defines the width of the field; otherwise
                     it is determined by the width of the value of  the  first
                     assignment.  When the parameter is expanded, it is filled
                     on the right with blanks or truncated if necessary to fit
                     the  field.   Leading zeros are removed if the -Z flag is
                     also set.

              -R     Right justify and fill with  leading  blanks.   If  n  is
                     nonzero  if  defines the width of the field; otherwise it
                     is determined by the width of  the  value  of  the  first
                     assignment.  When the parameter is expanded, the field is
                     left filled with blanks or truncated from the end.

              -U     For arrays (but not for associative  arrays),  keep  only
                     the  first occurrence of each duplicated value.  This may
                     also be set for colon-separated special  parameters  like
                     PATH  or FIGNORE, etc.  This flag has a different meaning
                     when used with -f; see below.

              -Z     Right justify and fill with leading zeros  if  the  first
                     non-blank  character  is  a digit and the -L flag has not
                     been set.  If n is nonzero it defines the  width  of  the
                     field;  otherwise  it  is  determined by the width of the
                     value of the first assignment.

              -a     The names refer to array parameters.  An array  parameter
                     may be created this way, but it may not be assigned to in
                     the typeset statement.  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,  -k, -u, -U and -z.  The flag -t turns on execu-
                     tion tracing for this function.   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.  The fpath parameter will be searched to find
                     the function definition when the function is first refer-
                     enced;  see  the section ‘Functions’. The -k and -z flags
                     make the function be loaded using ksh-style or  zsh-style
                     autoloading  respectively.  If neither is given, the set-
                     ting of the KSH_AUTOLOAD option determines how the  func-
                     tion is loaded.

              -h     Hide:  only  useful  for special parameters (those marked
                     ‘<S>’ in the table in zshparams(1)), and for local param-
                     eters  with  the same name as a special parameter, though
                     harmless for  others.   A  special  parameter  with  this
                     attribute  will  not  retain its special effect when made
                     local.  Thus after ‘typeset -h PATH’, a function contain-
                     ing  ‘typeset PATH’ will create an ordinary local parame-
                     ter 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 altered 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
                     regardless  of  having  the -h attribute.  Global special
                     parameters 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/parameter  and  zsh/mapfile  modules.  Note, however,
                     that unlike the -h flag this is also useful for  non-spe-
                     cial parameters.

              -i     Use  an internal integer representation.  If n is nonzero
                     it defines the output arithmetic base,  otherwise  it  is
                     determined by the first assignment.

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

              -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
                     explicitly  given;  in  other  words the parameter is not
                     made local to the enclosing function.  This is  for  com-
                     patibility with previous versions of zsh.

       ulimit [ [ -SHacdflmnpstv | -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 the value ‘unlimited’.  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 values are 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 reson it will continue  try-
              ing to set the remaining limits.

              -a     Lists all of the current resource limits.
              -c     512-byte blocks on the size of core dumps.
              -d     K-bytes on the size of the data segment.
              -f     512-byte blocks on the size of files written.
              -l     K-bytes on the size of locked-in memory.
              -m     K-bytes on the size of physical memory.
              -n     open file descriptors.
              -s     K-bytes on the size of the stack.
              -t     CPU seconds to be used.
              -u     processes available to the user.
              -v     K-bytes  on  the size of virtual memory.  On some systems
                     this refers to the limit called ‘address space’.

              A resource may also be specified by  integer  in  the  form  ‘-N
              resource’, 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
              Same as unhash -a.

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

       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.

       whence [ -vcwfpams ] name ...
              For each name, indicate how it would be interpreted if used as a
              command name.

              -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,
                     reserved 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 (should  be  quoted),
                     and  the information is displayed for each command match-
                     ing one of these patterns.

              -s     If a pathname contains symlinks, print  the  symlink-free
                     pathname as well.

       where [ -wpms ] name ...
              Equivalent to whence -ca.

       which [ -wpams ] 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
              autoloading of functions and execution of  scripts  by  avoiding
              parsing 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 zshfunc(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
              appended.   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
              either case, the functions in files written with the  -c  or  -a
              option  will  be  autoloaded  as if the KSH_AUTOLOAD option were
              unset.

              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.

              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
              return  value  is  set to zero if definitions for all names were
              found in the compiled file, and non-zero if the  definition  for
              at least one name was not found.

              Other options:

              -U     Aliases  are not expanded when compiling the named files.

              -R     When the compiled file is read, its contents  are  copied
                     into  the  shell’s memory, rather than memory-mapped (see
                     -M).  This happens automatically on systems that  do  not
                     support memory mapping.

                     When compiling scripts instead of autoloadable functions,
                     it is often desirable to use this option;  otherwise  the
                     whole  file, including the code to define functions which
                     have already been defined,  will  remain  mapped,  conse-
                     quently wasting memory.

              -M     The  compiled file is mapped into the shell’s memory when
                     read. This is done in such a way that multiple  instances
                     of  the  shell  running  on the same host will share this
                     mapped file.  If neither -R nor -M is given, the zcompile
                     builtin  decides what to do based on the size of the com-
                     piled file.

              -k
              -z     These options are used when the  compiled  file  contains
                     functions which are to be autoloaded. If -z is given, the
                     function will be autoloaded as if the KSH_AUTOLOAD option
                     is  not  set,  even if it is set at the time the compiled
                     file is read, while if the -k is given, the function will
                     be  loaded as if KSH_AUTOLOAD is set.  These options also
                     take precedence over any -k or -z  options  specified  to
                     the  autoload  builtin.  If  neither  of these options is
                     given, the function will be loaded as determined  by  the
                     setting  of  the KSH_AUTOLOAD option at the time the com-
                     piled file is read.

                     These options may also appear as many times as  necessary
                     between  the listed names to specify the loading style of
                     all following functions, up to the next -k or -z.

                     The created file always contains two versions of the com-
                     piled  format,  one  for  big-endian machines and one for
                     small-endian machines.  The upshot of this  is  that  the
                     compiled file is machine independent and if it is read or
                     mapped, only one half of the file is actually  used  (and
                     mapped).

       zformat
              See the section ‘The zsh/zutil Module’ in zshmodules(1).

       zftp   See the section ‘The zsh/zftp Module’ in zshmodules(1).

       zle    See the section ‘Zle Builtins’ in zshzle(1).

       zmodload [ -dL ] [ ... ]
       zmodload -e [ -A ] [ ... ]
       zmodload [ -a [ -bcpf [ -I ] ] ] [ -iL ] ...
       zmodload -u [ -abcdpf [ -I ] ] [ -iL ] ...
       zmodload -A [ -L ] [ modalias[=module] ... ]
       zmodload -R modalias ...
              Performs operations relating to zsh’s loadable modules.  Loading
              of modules while the shell is running (‘dynamical  loading’)  is
              not  available on all operating systems, or on all installations
              on a particular operating system, although the zmodload  command
              itself is always available and can be used to manipulate modules
              built into versions of the shell  executable  without  dynamical
              loading.

              Without  arguments the names of all currently loaded binary mod-
              ules are printed.  The -L option causes this list to be  in  the
              form  of  a  series  of zmodload commands.  Forms with arguments
              are:

              zmodload [ -i ] name ...
              zmodload -u [ -i ] name ...
                     In the simplest case, zmodload  loads  a  binary  module.
                     The  module  must  be in a file with a name consisting of
                     the specified name followed by a standard suffix, usually
                     ‘.so’  (‘.sl’  on  HPUX).   If the module to be loaded is
                     already loaded and the -i option is given, the  duplicate
                     module  is  ignored.   Otherwise zmodload prints an error
                     message.

                     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.

                     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  filesys-
                     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
                     function runs successfully.

              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
                     dependencies 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.   If  only  the  name  is  given,  one builtin is
                     defined, with the same name as the module.  -i suppresses
                     the   error   if   the  builtin  is  already  defined  or
                     autoloaded, regardless of which module it came from.

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

              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.  With argu-
                     ments only 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 avail-
                     ability 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,
                     either  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  list-
                     ing,  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
                     effect 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 redefin-
                     ing  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
                     removed.   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).

ZSHZLE(1)                                                            ZSHZLE(1)



       ztcp   See the section ‘The zsh/net/tcp Module’ in zshmodules(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
       default.   It only works if the TERM parameter is set to a valid termi-
       nal 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).




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 four keymaps:

       emacs  EMACS emulation
       viins  vi emulation - insert mode
       vicmd  vi emulation - command mode
       .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 four 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  ‘viins’, otherwise it will be ‘emacs’.  bindkey’s -e and -v options
       provide 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.

       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.



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
       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,  operation  selection, and others.  The keymap selec-
              tion options are:

              -e     Selects keymap ‘emacs’, and also links it to ‘main’.

              -v     Selects keymap ‘viins’, and also links it to ‘main’.

              -a     Selects keymap ‘vicmd’.

              -M keymap
                     The keymap specifies a keymap name.

              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 the -L option is also
                     used,  list in the form of bindkey commands to create the
                     keymaps.

              -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
                     already has that name, it is deleted.  If  an  old-keymap
                     name  is  given,  the  new  keymap is initialized to be a
                     duplicate 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
              unchanged) 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-insert are affected.

              -r in-string ...
                     Unbind  the  specified in-strings in the selected keymap.
                     This is exactly equivalent  to  binding  the  strings  to
                     undefined-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.

              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 consists 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 sequences 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
       \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  dis-
       tinct,  although  they are initialized to the same bindings by ‘bindkey
       -m’.

       vared [ -Aache ] [ -p prompt ] [ -r rprompt ]
         [ -M main-keymap ] [ -m vicmd-keymap ] 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
              parameter,  or  the  -A flag to create an associative array.  If
              the type of an existing parameter does not match the type to  be
              created, the parameter is unset and recreated.

              If an array or array slice is being edited, separator characters
              as defined in $IFS will be shown quoted  with  a  backslash,  as
              will  backslashes  themselves.  Conversely, when the edited text
              is split into an array, a backslash quotes an  immediately  fol-
              lowing  separator  character or backslash; no other special han-
              dling of backslashes, or any handling of quotes, is performed.

              Individual elements  of  existing  array  or  associative  array
              parameters 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.

       zle -l [ -L | -a ] [ string ... ]
       zle -D widget ...
       zle -A old-widget new-widget
       zle -N widget [ function ]
       zle -C widget completion-widget function
       zle -R [ -c ] [ display-string ] [ string ... ]
       zle -M string
       zle -U string
       zle -K keymap
       zle -F [ -L ] [ fd [ handler ] ]
       zle -I
       zle widget [ -n num ] [ -N ] args ...
       zle    The zle builtin performs a number of different actions  concern-
              ing ZLE.  Which operation it performs depends on its options:

              -l [ -L | -a ]
                     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, nothing will be printed
                     but the return status will be zero  if  all  strings  are
                     names  of existing widgets (or of user-defined widgets if
                     the -a flag is not given) and non-zero if  at  least  one
                     string is not a name of an defined widget.

              -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 in  zsh-
                     zle(1).

              -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 ] [ 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.  When zle is attempting to
                     read data, it will examine both the terminal and the list
                     of handled fd’s.  If data becomes available on a  handled
                     fd,  zle will call handler with the fd which is ready for
                     reading as the only argument.  If  the  handler  produces
                     output  to  the  terminal, it should call ‘zle -I’ before
                     doing so (see below).  The handler should not attempt  to
                     read  from  the terminal.  Note that zle makes no attempt
                     to check  whether  this  fd  is  actually  readable  when
                     installing  the  handler.   The  user must make their own
                     arrangements for handling the file descriptor when zle is
                     not active.

                     Any  number  of  handlers for any number of readable file
                     descriptors may be installed.  Installing a  handler  for
                     an  fd  which is already handled causes the existing han-
                     dler to be replaced.

                     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.

                     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 status is zero if zle is active and the  current  zle
                     display  has been invalidated (even if this was by a pre-
                     vious call to ‘zle -I’), else one.

              widget [ -n num ] [ -N ] args ...
                     Invoke the specified widget.  This can only be done  when
                     ZLE   is   active;   normally   this  will  be  within  a
                     user-defined widget.

                     With the options -n and -N, the current  numerical  argu-
                     ment  will  be  saved and then restored after the call to
                     widget; ‘-n num’ sets the numerical argument  temporarily
                     to  num,  while  ‘-N’  sets it to the default, i.e. as if
                     there were none.

                     Any further arguments will be passed to the  widget.   If
                     it  is  a  shell function, these are passed down as posi-
                     tional parameters; 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 com-
                     mands,  the  history-search-forward and -backward and the
                     corresponding functions prefixed by vi-, and  by  univer-
                     sal-argument.   No  error  is flagged if the command does
                     not use the arguments, 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.

       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 if ZLE is not active.



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
       sequences  in keymaps are bound to are in fact widgets.  Widgets can be
       user-defined or built in.

       The standard widgets built in to ZLE are  listed  in  Standard  Widgets
       below.   Other  built-in  widgets  can be defined by other modules (see
       zshmodules(1)).  Each built-in widget has two names: its normal canoni-
       cal  name,  and  the same name preceded by a ‘.’.  The ‘.’ name is spe-
       cial: it can’t be rebound to a different widget.  This makes the widget
       available even when its usual name has been redefined.

       User-defined  widgets  are  defined  using ‘zle -N’, and implemented as
       shell functions.  When the widget is executed, the corresponding  shell
       function  is  executed, and can perform editing (or other) actions.  It
       is recommended that user-defined widgets should not have names starting
       with ‘.’.


USER-DEFINED WIDGETS

       User-defined widgets, being implemented as shell functions, can execute
       any normal shell command.  They can also  run  other  widgets  (whether
       built-in  or user-defined) using the zle builtin command.  The standard
       input of the function is closed to prevent external commands from unin-
       tentionally  blocking  ZLE by reading from the terminal, but read -k or
       read -q can be used to read characters.  Finally, they can examine  and
       edit  the  ZLE  buffer  being edited by reading and setting the special
       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.

       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.

       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 to be cut using one of the ‘kill-’  commands;  the
              string which the next yank would insert in the line.

       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.

       KEYMAP (scalar)
              The name of the currently selected keymap; read-only.

       KEYS (scalar)
              The keys typed to invoke  this  widget,  as  a  literal  string;
              read-only.

       killring (array)
              The  array  of  previously  killed items, with the most recently
              killed first.  This gives the items that would be retrieved by a
              yank-pop in the same order.

              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.


       LASTSEARCH (scalar)
              The  last  search  string  used  by  an  interactive  search   ;
              read-only.

       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
              replaced,  and  the  cursor remains between the new $LBUFFER and
              the old $RBUFFER.

       MARK (integer)
              Like CURSOR, but for the mark.

       NUMERIC (integer)
              The numeric argument. If no numeric  argument  was  given,  this
              parameter  is  unset. When this is set inside a widget function,
              builtin widgets called with the zle builtin command will use the
              value assigned. If it is unset inside a widget function, builtin
              widgets called behave as if no numeric argument was given.

       PENDING (integer)
              The number of bytes pending for input, i.e. the number of  bytes
              which  have  already  been typed and can immediately be read. On
              systems where the shell is not able  to  get  this  information,
              this parameter will always have a value of zero.  Read-only.

       PREBUFFER (scalar)
              In  a  multi-line  input at the secondary prompt, this read-only
              parameter contains the contents of the lines before the one  the
              cursor is currently in.

       PREDISPLAY (scalar)
              Text  to  be  displayed  before  the  start of the editable text
              buffer.  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  invoca-
              tion) 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
              position.  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.

       WIDGET (scalar)
              The name of the widget currently being executed; read-only.


   Special Widget
       There  is one user-defined widget which is special to the shell.  If it
       does not exist, no special action is taken.  The  environment  provided
       is identical to that for any other editing widget.

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



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
       sequences  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  hap-
       pens is determined 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.

       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.

       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.

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

   History Control
       beginning-of-buffer-or-history (ESC-<) (unbound) (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
              buffer, 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.

              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 and go back to the original line.  An
              undefined key will have the same effect. The supported functions
              are:       backward-delete-char,        vi-backward-delete-char,
              clear-screen,    redisplay,   quoted-insert,   vi-quoted-insert,
              accept-and-hold, accept-and-infer-next-history, accept-line  and
              accept-line-and-down-history.

              magic-space  just  inserts a space.  vi-cmd-mode toggles between
              the ‘main’ and ‘vicmd’ keymaps; the ‘main’ keymap (insert  mode)
              will be selected initially.  history-incremental-search-backward
              will get the next occurrence of the contents of the mini-buffer.
              history-incremental-search-forward  inverts  the  sense  of  the
              search.  vi-repeat-search and vi-rev-repeat-search are similarly
              supported.   The  direction  of  the  search is indicated in the
              mini-buffer.

              Any multi-character string that is not bound to one of the above
              functions  will  beep and interrupt the search, leaving the last
              found line in the buffer. Any single character that is not bound
              to   one   of   the   above   functions,   or   self-insert   or
              self-insert-unmeta, will have the same effect but  the  function
              will be executed.

              When  called  from  a  widget  function  by the zle command, the
              incremental 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
              characters  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-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 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  his-
              tory line examined by the previous execution of the command will
              be reexamined.  Note that negative numbers  should  be  preceded
              with a ‘--’ argument to avoid confusing them with options.

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

   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
              insert mode.  If the command is vi-change,  change  the  current
              line.

       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.

       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.

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

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

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

       vi-unindent (unbound) (<) (unbound)
              Unindent a number of lines.

       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, and yank the
              new top.  Only works following yank 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 numerical argument will be set to num;
              this is equivalent to ‘NUMERIC=num’.

   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,
              attempt 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
              the buffer stack.

       beep   Beep, unless the BEEP option is unset.

       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.

       describe-key-briefly
              Reads a key sequence, then prints the  function  bound  to  that
              sequence.

       exchange-point-and-mark (^X^X) (unbound) (unbound)
              Exchange the cursor position with the position of the mark.

       execute-named-cmd (ESC-x) (unbound) (unbound)
              Read the name of an editor command and execute it.  A restricted
              set of editing functions is available in  the  mini-buffer.   An
              interrupt signal, as defined by the stty setting, will abort the
              function.  The  allowed  functions  are:   backward-delete-char,
              vi-backward-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.

       execute-last-named-cmd (ESC-z) (unbound) (unbound)
              Redo the last function executed with execute-named-cmd.

       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
              buffer.  Next time the editor starts  up,  the  buffer  will  be
              popped off the top of the buffer stack and loaded into the edit-
              ing buffer.

       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.

       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
              accept-line caused by  hitting  the  return  key)  is  executed.
              Instead, 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
              either accept-line (i.e. typically the return key) is  typed  or
              the  caps-lock  widget is invoked again; the later is handled by
              saving 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 propagated 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
              directory,  or  changes to the value of variables referred to by
              the prompt).

              Otherwise, the prompt is only expanded each time zle starts, and
              when the display as been interrupted by output from another part
              of the shell (such as a job notification) which causes the  com-
              mand line to be reprinted.

       send-break (^G ESC-^G) (unbound) (unbound)
              Abort  the  current editor function, e.g. execute-named-command,
              or the editor itself, e.g. if you are in vared. Otherwise  abort
              the parsing of the current line.

       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
              35 buffers that can be specified: the 26 ‘named’ buffers  "a  to
              "z  and  the  nine ‘queued’ buffers "1 to "9.  The named buffers
              can also be specified as "A to "Z.

              When a buffer is specified for a cut command, the text being cut
              replaces  the  previous  contents of the specified buffer.  If a
              named buffer is specified using a capital, the newly cut text is
              appended to the buffer instead of overwriting it.

              If no buffer is specified for a cut command, "1 is used, and the
              contents of "1 to "8 are each shifted along one buffer; the con-
              tents of "9 is lost.

       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.

       spell-word (ESC-$ ESC-S ESC-s) (unbound) (unbound)
              Attempt spelling correction on the current word.

       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) (unbound) (unbound)
              Incrementally undo the last text modification.

       redo   Incrementally redo undone text modifications.

       vi-undo-change (unbound) (u) (unbound)
              Undo the last text modification.  If repeated, redo the  modifi-
              cation.

       what-cursor-position (^X=) (unbound) (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 and print the listing of
              key sequences that invoke the specified command.

       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,
ZSHCOMPWID(1)                                                    ZSHCOMPWID(1)



              continue the argument.  Otherwise, execute vi-beginning-of-line.


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 this section.  The older
       system based on the compctl builtin command  is  described  in  zshcom-
       pctl(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,
       expand-or-complete,      expand-or-complete-prefix,      menu-complete,
       menu-expand-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
       responsible for generating the  possible  matches  using  the  builtins
       described  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.




SPECIAL PARAMETERS

       Inside completion widgets, and any functions  called  from  them,  some
       parameters  have  special meaning; outside these functions they are not
       special to the shell in any way.  These parameters  are  used  to  pass
       information 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
       parameters  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
              parameter 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 and a
                     backslash for strings not starting with a  quote  charac-
                     ter.  The first character in the value always corresponds
                     to the innermost 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
                             parameter  assignment;  in  this  case  the words
                             array contains the words inside the  parentheses.

                     brace_parameter
                             when  completing  the  name  of  a parameter in a
                             parameter expansion beginning with ${.

                     assign_parameter
                             when completing the name  of  a  parameter  in  a
                             parameter 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
                             expression; 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
                             parameter 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
                     accepted, 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 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
                     inserted.

                     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
                     options 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
                     inserted, 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
                     inserted, 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
                     instead  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
                     restored  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
                     inserted  differs  from at least one of the matches.  The
                     positions 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.



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 name ] [ -V name ] [ -X explanation ] [ -x message ]
       [ -r remove-chars ] [ -R remove-func ]
       [ -D array ] [ -O array ] [ -A array ]
       [ -E number ]
       [ -M match-spec ] [ -- ] [ words ... ]

              This  builtin  command  can  be used to add matches directly and
              control all the information the completion code stores with each
              possible  match.  The return value 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.

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

              -V name
                     Like  -J but naming a unsorted group. These are in a dif-
                     ferent name space than groups created with the -J flag.

              -1     If given together with the -V option, makes only consecu-
                     tive duplicates in the group be removed. If combined with
                     the -J option, this has  no  visible  effect.  Note  that
                     groups  with  and without this flag are in different name
                     spaces.

              -2     If given together with the -J or  -V  option,  makes  all
                     duplicates  be  kept. Again, groups with and without this
                     flag are in different name spaces.

              -X explanation
                     The explanation string will be printed with the  list  of
                     matches, above the group currently selected.

              -x message
                     Like  -X,  but  the message will be printed even if there
                     are no matches in the group.

              -q     The suffix given with -S will be automatically removed if
                     the  next  character  typed is a blank or does not insert
                     anything, or if the suffix consists of only one character
                     and the next character typed is the same character.

              -r remove-chars
                     This is a more versatile form of the -q option.  The suf-
                     fix given with -S or the slash automatically added  after
                     completing  directories  will be automatically removed if
                     the next character typed inserts one  of  the  characters
                     given  in  the  remove-chars.  This string is parsed as a
                     characters class and understands the backslash  sequences
                     used  by  the  print  command.  For example, ‘-r "a-z\t"’
                     removes the suffix if the next character typed inserts  a
                     lowercase 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 insert  noth-
                     ing.  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
                     ordinary  (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
                     expansion.  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  ‘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
                     ‘nofoo’ 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 n’th word does not match, the n’th 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     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
                     option is given).

              -
              --     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 value allows tests on them to be carried out.

              The options are:

              -p number
                     If  the  contents  of the PREFIX parameter is longer than
                     number  characters,  the  first  number  characters   are
                     removed  from  it  and  appended  to  the contents of the
                     IPREFIX parameter.

              -P [ number ] pattern
                     If the value of the PREFIX parameter begins with anything
                     that  matches the pattern, the matched portion is removed
                     from PREFIX and appended to IPREFIX.

                     Without the optional number, the longest match is  taken,
                     but  if  number  is  given,  anything up to the number’th
                     match is moved.  If the number is negative, the number’th
                     longest  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 begin’th 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
                     including 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 value is zero if the test suc-
              ceeded and the parameters were modified and non-zero  otherwise.
              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-
              tion  (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 value can be used to test if a matching compctl defi-
              nition 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.



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.



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  ‘Builtin
       Commands’  above)  consists  of one or more matching descriptions sepa-
       rated by whitespace.  Each description consists of a letter followed by
       a  colon  and then the patterns describing which character sequences on
       the line match which character sequences in the trial completion.   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  uppercase  initial character retains the string already
       typed on the command line as the final result of completion, while with
       a lowercase 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
              between substrings matched by lanchor and ranchor.  Unlike  lan-
              chor,  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 trial completion or
              the word on the command line, 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 trial completion or command line string.

       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
       lowercase  letter  on the line match the corresponding uppercase letter
       in the trial completion, you can use ‘m:{a-z}={A-Z}’.   More  than  one
       pair  of  classes can occur, in which case the first class before the =
       corresponds 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 behave like normal 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-lowercase form, without underscores, and  with-
       out  the  optional  no at the beginning even though the builtins setopt
       and unsetopt understand option names  with  uppercase  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 uppercase letters on the line
       match the corresponding lowercase letters in the words:

              compadd -M L:|[nN][oO]= M:_= M:{A-Z}={a-z} - \
                ${(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 uppercase letter on the line matches
       the corresponding lowercase 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
       prefix 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:{a-z}={A-Z} ...

       This makes lowercase letters match their  uppercase  counterparts.   To
       make uppercase letters match the lowercase forms as well:

              compadd -M m:{a-zA-Z}={A-Za-z} ...

       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
       anchor 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 then 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  uppercase  letter)  or  maybe one has to complete strings with
       trailing numbers. Here one could use the  simple  form  with  only  one
       anchor as in:

              compadd -M r:|[A-Z0-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 uppercase 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:|[A-Z0-9]=**’,  but  then  ‘H’  completes  to  both  ‘LikeTHIS’  and
       ‘FooHoo’ and a ‘2’ matches the other strings because characters can  be
       inserted  before  every  uppercase  letter and digit. To avoid this one
       would use:

              compadd -M r:[^A-Z0-9]||[A-Z0-9]=** r:|=* \
                  LikeTHIS FooHoo foo123 bar234

       By using these two anchors, a ‘H’ matches only uppercase ‘H’s that  are
       immediately preceded by something matching the left anchor ‘[^A-Z0-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
ZSHCOMPSYS(1)                                                    ZSHCOMPSYS(1)



       current word.


NAME

       zshcompsys - zsh completion system


DESCRIPTION

       This describes the shell code for the new completion system.   It  con-
       sists  of  various  shell  functions;  those beginning ‘comp’ are to be
       called directly, while those beginning ‘_’ are called by the completion
       code.   The  shell functions of the second set, which implement comple-
       tion behaviour and may be bound to keystrokes, are referred to as ‘wid-
       gets’.




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
       (‘autoload -U compinstall’ is recommended).  You can abort the  instal-
       lation 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
       (‘autoload  -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 complete-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
       already.

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


   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 is 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 names... [ -[pP] patterns... [ -N names... ] ]
              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
              instead.  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-sequences...
              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 if it already was  (that  is,  was  bound  to
              something 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-sequences ...
              This  is  similar to -k except that only one key-sequences argu-
              ment may be given for each widget-name style pair.  However, the
              entire  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 (‘foo=(...)’)

       -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
              defined for commands will

       -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
       ‘-redirect-,op,command’,  where op is the redirection operator and com-
       mand 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.  In the case of elements of  an  associa-
       tive  array,  for  example  ‘assoc=(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
       replacing 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-,-default-’, in that order, until it finds a func-
       tion to handle the context.

       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
       below); 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
       directly.

       compdef [ -an ] function names... [ -[pP] patterns... [ -N names... ] ]
       compdef -d names...
       compdef -k [ -an ] function style key-sequences...
       compdef -K [ -an ] function name style key-sequences ...
              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
              any  shell  code.   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 exam-
              ple, to complete files ending in ‘.h’ as arguments to  the  com-
              mand foo:

                     compdef _files -g "*.h" foo

              The  option  -n prevents any completions already defined for the
              command or context from being overwritten.

              The option -d deletes any completion defined for the command  or
              contexts listed.

              The  names  may  also contain -p, -P and -N options as described
              for the #compdef tag.  The effect on the argument list is  iden-
              tical,  switching  between  definitions  of  patterns tried ini-
              tially, patterns tried finally, and  normal  commands  and  con-
              texts.

              The  parameter $_compskip may be set by any function defined for
              a pattern context.  If it is set to a value containing the  sub-
              string  ‘patterns’ none of the pattern-functions will be called;
              if it is set to a value containing the substring ‘all’, no other
              function will be called.

              The  form  with  -k  defines  a widget with the same name as the
              function that will be called for each of the key-sequences; this
              is  like  the #compdef -k tag.  The function should generate the
              completions needed and will otherwise behave  like  the  builtin
              widget  whose  name is given as the style argument.  The widgets
              usable  for  this   are:   complete-word,   delete-char-or-list,
              expand-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
              already 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-sequences, where the latter two
              are as for -k and the first must be a unique widget name  begin-
              ning 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 first works out the context.  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).

       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.  This is used to look up styles,
       context-sensitive  options that can be used to configure the completion
       system.  The context used for lookup may vary during the same  call  to
       the completion system.

       The  context  string always consists of the following fields, separated
       by colons and with a leading colon before the first:

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


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


       ·      The completer currently active, the name of the function without
              the leading underscore.  A ‘completer’ is in overall control  of
              how  completion  is to be performed; ‘complete’ is the simplest,
              but other completers exist to perform related tasks such as cor-
              rection,  or  to modify the behaviour of a later completer.  See
              the section ‘Control Functions’ below for more information.


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


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


       ·      The  tag.   Tags  are  used to discriminate between the types of
              matches a completion function can generate in a certain  context
              and are described further below.


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

       Each type of completion the system can perform in a  given  context  is
       described  by  a ‘tag’, a short descriptive string such as files in the
       example above.  Any completion function may use any tag name it  likes,
       but a list of the more common ones is given below.

       Usually completion will be tried by all possible tags in an order given
       by the completion function.  However, this can be altered by using  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
       described in the section ‘Bindable Commands’ below.

       Styles  determine  such  things as how the matches are generated, simi-
       larly to shell options but with much more control.  They can  have  any
       number  of  strings  as  their value.  They are defined with the zstyle
       builtin command (see zshmodules(1)).

       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 may be matched as a pattern, and the
       name of the style itself, which must be given exactly.

       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
       internals of completion functions (see see zshcompwid(1))).  For  exam-
       ple:

              zstyle -e :completion:* completer 
                  if [[ $words[1] = cvs ]]; then
                    reply=(_complete)
                  else
                    reply=(_complete _approximate)
                  fi

       uses  the  value  ‘_complete’ for the completer style in most contexts,
       but the value ‘_complete _approximate’ when the first word on the  com-
       mand  line is ‘cvs’.  This is probably more conveniently done by speci-
       fying the style for two different contexts.  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  pre-
       ferred over shorter patterns.

       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

       directory-stack
              for entries in the directory stack

       displays
              for X display names

       domains
              for network domains

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

       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

       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.

       add-space
              This style is used by the _expand completer.  If it is true (the
              default), a space will be inserted  after  all  words  resulting
              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 expansion 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
              already 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
              defined.   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 causes 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 it set to ‘true’ and the word on the  com-
              mand line is not the name of an alias, matching alias names will
              be completed.

       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
              default is ‘true’.

       disabled
              If  this is set to ‘true’, the _expand_alias completer and bind-
              able command will try to  expand  disabled  aliases,  too.   The
              default is ‘false’.

       disable-stat
              This  is  used  with an empty tag by the _cvs function to decide
              whether the zsh/stat module should be used to generate names  of
              modified files in the appropriate places (this is its only use).
              If the style is set, completion will use the ls command.

       domains
              A list of names of network domains for completion.  If  this  is
              not   set,   domain   names   will   be   taken  from  the  file
              /etc/resolv.conf.

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

              This  can  be useful on systems that support special filesystems
              whose top-level pathnames can not be listed  or  generated  with
              glob  patterns.   It  can also be used for directories for which
              one does not have read permission.

       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-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
              together 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
              order.   The  possible values are: ‘size’ to sort by the size of
              the file; ‘links’ to sort by the number of links  to  the  file;
              ‘modification’ (or ‘time’ or ‘date’) to sort by the last modifi-
              cation 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 alphabetically by name.  If the value contains the string
              ‘reverse’, sorting is done in the opposite order.

       filter This is used by the LDAP plugin for e-mail address completion 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
              sequence ‘%d’ in this string  will  be  replaced  with  a  short
              description  of  what  these  matches are.  This string may also
              contain the sequences to  specify  output  attributes,  such  as
              ‘%B’, ‘%S’ and ‘%{...%}’.

              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
              replaced 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
              parameters  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’,
              no  word apart from the current one will be considered as a pos-
              sible completion.

              The values ‘current’ and ‘current-shown’  are  a  bit  like  the
              opposite  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
              option 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
                     directories  are  completed, not when completing names of
                     files.

              Excluded values act in  a  similar  fashion  to  values  of  the
              ignored-patterns style, so they can be restored to consideration
              by the _ignored completer.

       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
              ignored  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
              instead 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)
              instead of performing completion  when  there  is  no  non-blank
              character  to  the left of the cursor.  If it is set to ‘false’,
              completion 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 staring 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.

       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 cur-
              sor  to  the previous command line after displaying a completion
              list.  It is tested for all tags valid for the  current  comple-
              tion,  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 prefix argument.

       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-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 are  also
              available,  as  is  the  form  ‘%{...%}’  for  enclosing  escape
              sequences which display with zero width.

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

       local  This  is for use with functions that complete URLs for which the
              corresponding files are available directly from the filing  sys-
              tem.  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 ‘*’
              inserted.  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 added to  any  match  specifications
              given  by  the  matcher-list  style.   It  should be in the form
              described in the section ‘Matching Control’ in zshcompwid(1).

       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 ‘Matching Control’ in zshcompwid(1).  The completion
              system  will  try  them  one  after  another  for each completer
              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.  For
              example, to use the completers _complete and  _prefix  but  only
              allow case-insensitive completion with _complete:

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

       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
              numeric  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
              descriptions  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
              description 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
              ‘default’ 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  option
              is set.

              If one of the values is explicitly set to false, menu completion
              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 values
              (‘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  completion  can  be
              activated  in  that  case  with the value ‘yes=long-list’ (Typi-
              cally, the value ‘select=long-list’ described later is more use-
              ful 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
              appear 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
              ‘select=long’.  To start menu selection even if the current wid-
              get only performs listing, use the value ‘select=long-list’.

              To  turn on menu completion or menu selection when a there are a
              certain number of matches or the list of matches does not fit on
              the  screen,  both  of  ‘yes=’ and ‘select=’ may be given twice,
              once with a number and once with ‘long’ or ‘long-list’.

              Finally, it is possible to activate two special  modes  of  menu
              selection.   The word ‘interactive’ in the value causes interac-
              tive mode to be  entered  immediately  when  menu  selection  is
              started;  see the description of the zsh/complist module in zsh-
              modules(1).RE 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
                     ‘always’, 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 unset, or any  other
                     value, then the existing list of completions is displayed
                     if it is not already; otherwise, the standard  completion
                     list  is  generated;  this  is  the  default behaviour of
                     _oldlist.  However, if there is  an  old  list  and  this
                     style  contains  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 list-
                     ing.

                     For example, suppose  you  type  ^Xc  to  use  the  _cor-
                     rect_word  widget,  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 already generated.

                     As  another  example  consider the _match completer: with
                     the insert-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 produce more matches than on the
                     first attempt.  By using the _oldlist completer and  set-
                     ting  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
                     corrections, 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  decide  if  the  original string should be added as a
                     possible completion.  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  approximate-num,
                     where num is the number of errors that were accepted.

              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 containing 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 standard  locations  it  will  be
                     used as the default.

              pine-directory
                     If  set,  specifies the directory containing PINE mailbox
                     files.  It defaults to ‘~/mail’.

              ports  A list of Internet service names (network ports) to  com-
                     plete.   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
                     prefix,   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,  too, is used 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.  In the case of command
                     options, this means that the initial ‘-’,  ‘+’,  or  ‘--’
                     must be typed explicitly before option names will be com-
                     pleted.

                     The default value for this style is ‘true’.

              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  example,  on some Unices an initial
                     ‘//’ (double slash) has a special meaning;  setting  this
                     style  to  the  string ‘//’ will preserve 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 _his-
                     tory_complete_word bindable command to decide which words
                     should be completed.

                     If  it  is a singe 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 was
                     been found, or max words have been tried.

                     The default is to complete all words from the history  at
                     once.

              regular
                     This  style  is  used  by the _expand_alias completer and
                     bindable command.  If set to ‘true’ (the default),  regu-
                     lar  aliases  will  be expanded but only in command posi-
                     tion.  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.

              remote-access
                     If  set to false, certain commands will be prevented from
                     making Internet connections to retrieve  remote  informa-
                     tion.   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 unneces-
                     sarily.

              remove-all-dups
                     The _history_complete_word bindable command and the _his-
                     tory  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  completion  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  default
                     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 negative number, the list is
                     scrolled by a screenful minus the absolute value  of  the
                     given  number of lines.  The default is to scroll by sin-
                     gle lines.

              separate-sections
                     This style is used with the manuals tag  when  completing
                     names of manual pages.  If it is ‘true’, entries for dif-
                     ferent 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  dif-
                     ferent  sections  will  appear separately.  This style is
                     also used similarly with the words style when  completing
                     words  for the dict command. It allows words from differ-
                     ent dictionary databases to  be  added  separately.   The
                     default for this style is ‘false’.

              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  displayed  but not inserted.  If the value is ‘menu’,
                     then the single match and the original  string  are  both
                     added  as  matches and menu completion is started, making
                     it easy to select either of them.

              sort   Many completion widgets call _description at  some  point
                     which  decides  whether  the  matches are added sorted or
                     unsorted (often indirectly via  _wanted  or  _requested).
                     This style can be set explicitly to one of the usual true
                     or false values as an override.  If it is not set for the
                     context,  the standard 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.

                     If  the  calling  widget  explicitly  requests   unsorted
                     matches,  this is usually honoured.  However, the default
                     (unsorted) behaviour of completion for the  command  his-
                     tory 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  con-
                     taining all possible expansions.

              special-dirs
                     Normally, the completion code will not produce the direc-
                     tory names ‘.’ and ‘..’ as possible completions.  If this
                     style  is set to ‘true’, it will add both ‘.’ and ‘..’ as
                     possible completions; 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 beginning 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.   How-
                     ever,  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  history.   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_com-
                     plete_word will loop immediately 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 display 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 suffix,  i.e.  if  it  is  something  like
                     ‘~foo’  or  ‘$foo’  rather  than  ‘~foo/’  or ‘$foo/bar’,
                     unless that suffix itself  contains  characters  eligible
                     for expansion.  The default for this style is ‘true’.

              tag-order
                     This provides a mechanism for sorting how the tags avail-
                     able 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-patterns 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  external 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 gener-
                             ated.   Normally all tags not explicitly selected
                             are tried last if the specified tags fail to gen-
                             erate  any  matches.   This  means  that a single
                             value consisting only of a  single  hyphen  turns
                             off completion.

                     ! tags...
                             A string starting with an exclamation mark speci-
                             fies 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  arbitrary 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, supply-
                             ing 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  description  supplied  by the completion
                             function.  Spaces  in  the  description  must  be
                             quoted  with  a  backslash.   A ‘%d’ appearing 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 matching 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,  setting  other styles differently on each attempt,
                     but still to use all the other  tags  without  having  to
                     repeat  them  all.   For  example,  to make completion of
                     function names in command position ignore all the comple-
                     tion 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-patterns 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
                     ‘--’, options beginning with a single ‘-’ or ‘+’ but con-
                     taining  multiple  characters,  and single-letter options
                     will be  displayed  in  separate  groups  with  different
                     descriptions.

                     Another use of patterns is to try multiple match specifi-
                     cations one after another.  The matcher-list style offers
                     something  similar,  but  it  is tested very early in the
                     completion system and hence can’t be set for single  com-
                     mands 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-insensi-
                     tive matching, restricting the effect to arguments 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
                     command  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 PREFIX special parameter; see zshcompwid for  a
                     description  of  parameters which are special inside com-
                     pletion widgets.  Setting reply to an  empty  array  pro-
                     vides  the  default behaviour of trying all tags at once;
                     setting it to an array containing only a hyphen  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 func-
                     tion 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 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  direc-
                     tory,  the  directory  hierarchy rooted at this directory
                     gives the completions.  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 directory hierarchy can descend
                     as deep as necessary.

                     For example,

                             zstyle :completion:* urls ~/.urls
                             mkdir -p ~/.urls/ftp/ftp.zsh.org/pub/development

                     allows completion  of  all  the  components  of  the  URL
                     ftp://ftp.zsh.org/pub/development 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  refer-
                     ence to the urls style.

                     See the description in the function _urls itself for more
                     information (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,
                     _retrieve_cache,  and  _cache_invalid  functions).    The
                     directory  containing 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 unset, this is done only if the zsh/com-
                     pctl module is loaded.  The string may also  contain  the
                     substring  ‘first’  to use completions defined with ‘com-
                     pctl -T’, and the substring ‘default’ to use the  comple-
                     tion defined with ‘compctl -D’.

                     Note  that this is only intended to smooth the transition
                     from compctl to the new completion system and may  disap-
                     pear 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 ver-
                     sion will be tried if foo only uses default completion.

              use-perl
                     Various parts of the function system use awk  to  extract
                     words  from  files  or command output as this universally
                     available.  However, many versions of awk have  arbitrary
                     limits  on the size of input.  If this style is set, perl
                     will be used instead.  This is almost  always  preferable
                     if perl is available on your system.

                     Currently  this  is  only used in completions for ‘make’,
                     but it may be extended depending  on  authorial  frustra-
                     tion.

              users  This  may  be set to a list of usernames to be completed.
                     If it is not set or the string on the line doesn’t  match
                     any  of  the  strings in this list, all usernames will be
                     completed.

              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 com-
                     mands which usually refer to the accounts of  other  peo-
                     ple, such as talk and finger, can be grouped by using the
                     other-accounts tag.  More ambivalent commands may use the
                     accounts tag.

              users-hosts-ports
                     Like  users-hosts  but  used for commands like telnet and
                     containing strings of the form ‘user@host:port’.

              verbose
                     If set, as it is by default, the  completion  listing  is
                     more  verbose.  In particular many commands show descrip-
                     tions for options if this style is ‘true’.

              word   This is used by the _list completer, which  prevents  the
                     insertion   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  performed  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 value of  the  completer  func-
       tions  to  decide  if other completers should be called.  If the return
       value 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

       _approximate
              This  is similar to the basic _complete completer but allows the
              completions to  undergo  corrections.   The  maximum  number  of
              errors  can  be  specified  by  the  max-errors  style;  see the
              description 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
              accepted  to  generate  the corrections and the original string,
              respectively.

              The completer  progressively  increases  the  number  of  errors
              allowed 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.

       _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
              effect is similar to spell-checking.  It is based  on  _approxi-
              mate, 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
              _approximate completer or, as in the example,  just  before  it.
              Using  it  after  the  _approximate  completer  is useless since
              _approximate will at least generate the corrected strings gener-
              ated 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.

       _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
              until  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
              unless  the  insert-unambiguous  style is set to ‘true’; see the
              description 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
              behave when there is an existing list of completions  which  may
              have  been  generated  by  a  special  completion  (i.e. a sepa-
              rately-bound completion command).  It allows the  ordinary  com-
              pletion  keys  to  continue  to use the list of completions thus
              generated, instead of producing a new list of  ordinary  contex-
              tual  completions.   It  should appear in the list of completers
              before any of the widgets which generate matches.  It  uses  two
              styles:  old-list and old-menu, see the section ‘Completion Sys-
              tem Configuration’ above.

       _prefix
              This completer can be used to try  completion  with  the  suffix
              (everything after the cursor) ignored.  In other words, the suf-
              fix will not be considered to be part of the word  to  complete.
              The  effect is similar to the expand-or-complete-prefix command.

              The completer style is used to decide which other completers are
              to  be  called to generate matches.  If this style is unset, the
              list of completers set  for  the  current  context  is  used  --
              except,  of  course, the _prefix completer itself.  Furthermore,
              if this completer appears more than once in  the  list  of  com-
              pleters  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.

       bashcompinit
              This  function  provides  compatibility with bash’s programmable
              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 specifi-
              cations and functions written for bash.



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,
              _expand_alias  tries  to  complete the word to a full alias name
              without expanding it.  It leaves the cursor directly  after  the
              completed  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.
              Before 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
              default.  However, it can be used to define a  widget  and  will
              then  store  the name of the widget in the function field of the
              context and call the completion system.  This allows custom com-
              pletion  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

       _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
              example ‘_files -/’, in which case the function with  any  argu-
              ments  will  be called to generate the completions.  Unambiguous
              parts of the function name will be completed automatically (nor-
              mal  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
              accordance 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
              depends  on  the information available from the completion func-
              tions called, which in turn is  determined  by  the  user’s  own
              styles and other settings.

       _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  zero  if  they
       generated  completions and non-zero if no matching completions could be
       added.

       Two more features are offered  by  the  _main_complete  function.   The
       arrays  compprefuncs  and  comppostfuncs may contain names of functions
       that are to be called immediately before or after completion  has  been
       tried.   A function will only be called once unless it explicitly rein-
       serts itself into the array.

       _all_labels [ -x ] [ -12VJ ] tag name descr [ command args ... ]
              This is a  convenient  interface  to  the  _next_label  function
              below,  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
              allows  _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 [ -C name ] spec ...
              This  function is useful in simple cases where multiple tags are
              available.  Essentially  it  implements  a  loop  like  the  one
              described 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:descr:action’.  The tags are offered using _tags and if the
              tag is requested, the action is executed with the given descrip-
              tion  descr.   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 functions 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.

              Like  _tags  this function supports the -C option to give a dif-
              ferent name for the argument context field.

       _arguments [ -swWACRS ] [ -O name ] [ -M matchspec ] [ : ] spec ...
              This function can be used to give a complete  specification  for
              completion  for  a  command whose arguments follow standard UNIX
              option and argument conventions.  The  following  forms  specify
              individual  sets  of  options and arguments; to avoid ambiguity,
              these may be separated from the options to _arguments itself  by
              a single colon.

              n:message:action
              n::message:action
                     This  describes  the  n’th  normal argument.  The message
                     will be printed  above  the  matches  generated  and  the
                     action  indicates  what can be completed in this position
                     (see below).  If there are two colons before the  message
                     the  argument  is optional.  If the message contains only
                     white space, nothing will be printed  above  the  matches
                     unless the action adds an explanation string itself.

              :message:action
              ::message:action
                     Similar, but describes the next argument, whatever number
                     that happens to be.  If all arguments  are  specified  in
                     this  form  in the correct order the numbers are unneces-
                     sary.

              *:message:action
              *::message:action
              *:::message:action
                     This describes how arguments  (usually  non-option  argu-
                     ments,  those  not  beginning with - or +) are to be com-
                     pleted when neither of the first two forms was  provided.
                     Any number of arguments can be completed in this fashion.

                     With two colons before the  message,  the  words  special
                     array  and  the CURRENT special parameter are modified to
                     refer only to the normal arguments  when  the  action  is
                     executed or evaluated.  With three colons before the mes-
                     sage they are modified to refer only to the normal  argu-
                     ments covered by this description.

              optspec
              optspec:...
                     This  describes  an option.  The colon indicates handling
                     for one or more arguments to the option;  if  it  is  not
                     present, the option is assumed to take no arguments.

                     By default, options are multi-character name, one ‘-word’
                     per option.  With -s, options may be  single  characters,
                     with more than one option per word, although words start-
                     ing with two hyphens, such as ‘--prefix’, are still  con-
                     sidered  complete  option  names.   This  is suitable for
                     standard GNU options.

                     The  combination  of  -s  with  -w  allows  single-letter
                     options  to  be  combined in a single word even if one or
                     more of the options take arguments.  For example,  if  -a
                     takes  an  argument,  with no -s-ab’ is considered as a
                     single (unhandled) option; with -s -ab is an option  with
                     the  argument  ‘b’;  with  both -s and -w, -ab may be the
                     option -a and the  option(-b)  with  arguments  still  to
                     come.

                     The option -W takes this a stage further:  it is possible
                     to complete single-letter options even after an  argument
                     that occurs in the same word.  However, it depends on the
                     action performed whether options will really be completed
                     at  this point.  For more control, use a utility function
                     like _guard as part of the action.

                     The following forms are available for  the  initial  opt-
                     spec, whether or not the option has arguments.

                     *optspec
                             Here optspec is one of the remaining forms below.
                             This  indicates  the  following  optspec  may  be
                             repeated.   Otherwise if the corresponding option
                             is already present on the  command  line  to  the
                             left  of the cursor it will not be offered again.

                     -optname
                     +optname
                             In the simplest form  the  optspec  is  just  the
                             option  name  beginning  with  a  minus or a plus
                             sign, such as ‘-foo’.  The first argument for the
                             option  (if  any)  must follow as a separate word
                             directly after the option.

                             Either of ‘-+optname’ and ‘+-optname’ can be used
                             to  specify  that  -optname and +optname are both
                             valid.

                             In all the remaining forms, the leading  ‘-’  may
                             be replaced by or paired with ‘+’ in this way.

                     -optname-
                             The  first  argument  of  the  option  must  come
                             directly after the option name in the same  word.
                             For  example, ‘-foo-:...’ specifies that the com-
                             pleted  option  and  argument  will   look   like
                             ‘-fooarg’.

                     -optname+
                             The  first  argument may appear immediately after
                             optname in the same word, or may appear as a sep-
                             arate   word  after  the  option.   For  example,
                             ‘-foo+:...’ specifies that the  completed  option
                             and  argument  will look like either ‘-fooarg’ or
                             ‘-foo arg’.

                     -optname=
                             The argument may appear as the next word,  or  in
                             same  word as the option name provided that it is
                             separated from it by an equals sign, for  example
                             ‘-foo=arg’ or ‘-foo arg’.

                     -optname=-
                             The  argument  to the option must appear after an
                             equals sign in the same  word,  and  may  not  be
                             given in the next argument.

                     optspec[explanation]
                             An  explanation  string may be appended to any of
                             the preceding forms of optspec by enclosing it in
                             brackets, as in ‘-q[query operation]’.

                             The  verbose  style is used to decide whether the
                             explanation strings are displayed with the option
                             in a completion listing.

                             If  no  bracketed explanation string is given but
                             the auto-description style is set  and  only  one
                             argument is described for this optspec, the value
                             of the style is displayed, with any appearance of
                             the  sequence  ‘%d’ in it replaced by the message
                             of the first optarg that follows the optspec; see
                             below.

              It  is possible for options with a literal ‘+’ or ‘=’ to appear,
              but that character must be quoted, for example ‘-\+’.

              Each optarg following an optspec must take one of the  following
              forms:

              :message:action
              ::message:action
                     An argument to the option; message and action are treated
                     as for ordinary arguments.  In the first form, the  argu-
                     ment is mandatory, and in the second form it is optional.

                     This group may be repeated for options which take  multi-
                     ple  arguments.   In  other words, :message1:action1:mes-
                     sage2:action2 specifies that the option takes  two  argu-
                     ments.

              :*pattern:message:action
              :*pattern::message:action
              :*pattern:::message:action
                     This  describes multiple arguments.  Only the last optarg
                     for an option taking multiple arguments may be  given  in
                     this  form.  If the pattern is empty (i.e., :*:), all the
                     remaining words on  the  line  are  to  be  completed  as
                     described by the action; otherwise, all the words up to a
                     word matching the pattern are to be completed  using  the
                     action.

                     Multiple  colons are treated as for the ‘*:...’ forms for
                     ordinary arguments:  when the message is preceded by  two
                     colons,  the  words special array and the CURRENT special
                     parameter are modified during the execution or evaluation
                     of  the  action  to  refer  only  to  the words after the
                     option.  When preceded by three colons, they are modified
                     to refer only to the words covered by this description.

       Any literal colon in an optname, message, or action must be preceded by
       a backslash, ‘\:’.

       Each of the forms above may be preceded by a  list  in  parentheses  of
       option  names and argument numbers.  If the given option is on the com-
       mand line, the options and arguments indicated in parentheses will  not
       be  offered.   For  example,  ‘(-two  -three  1)-one:...’ completes the
       option ‘-one’; if this appears on the command line,  the  options  -two
       and  -three and the first ordinary argument will not be completed after
       it.  ‘(-foo):...’ specifies an ordinary argument completion; -foo  will
       not be completed if that argument is already present.

       Other items may appear in the list of excluded options to indicate var-
       ious other items that should not be applied when the current specifica-
       tion is matched: a single star (*) for the rest arguments (i.e. a spec-
       ification  of  the  form  ‘*:...’);  a  colon  (:)   for   all   normal
       (non-option-)  arguments;  and a hyphen (-) for all options.  For exam-
       ple, if ‘(*)’ appears before an option and the option  appears  on  the
       command line, the list of remaining arguments (those shown in the above
       table beginning with ‘*:’) will not be completed.

       To aid in reuse of specifications, it is possible to precede any of the
       forms  above  with  ‘!’;  then  the  form  will no longer be completed,
       although if the option or argument appears on  the  command  line  they
       will be skipped as normal.  The main use for this is when the arguments
       are given by an array, and _arguments is  called  repeatedly  for  more
       specific  contexts:  on  the first call ‘_arguments $global_options’ is
       used, and on subsequent calls ‘_arguments !$^global_options’.

       In each of the forms above the action determines how completions should
       be generated.  Except for the ‘->string’ form below, the action will be
       executed by calling the _all_labels function to process all tag labels.
       No special handling of tags is needed unless a function call introduces
       a new one.

       The forms for action are as follows.

         (single unquoted space)
              This is useful where an argument is required but it is not  pos-
              sible or desirable to generate matches for it.  The message will
              be displayed but no completions listed.  Note that even in  this
              case  the colon at the end of the message is needed; it may only
              be omitted when neither a message nor an action is given.

       (item1 item2 ...)
              One of a list of possible matches, for example:

                     :foo:(foo bar baz)

       ((item1\:desc1 ...))
              Similar to the above, but with descriptions  for  each  possible
              match.  Note the backslash before the colon.  For example,

                     :foo:((a\:bar b\:baz))

              The  matches  will be listed together with their descriptions if
              the description style is set with the values tag in the context.

       ->string
              In this form, _arguments processes the arguments and options and
              then returns control to the calling function with parameters set
              to  indicate  the state of processing; the calling function then
              makes its own  arrangements  for  generating  completions.   For
              example,  functions  that implement a state machine can use this
              type of action.

              Where _arguments encounters a  ‘->string’,  it  will  strip  all
              leading  and  trailing  whitespace from string and set the array
              state to the set of all stringss for which an action  is  to  be
              performed.

              By  default and in common with all other well behaved completion
              functions, _arguments returns zero if it was able to add matches
              and  non-zero  otherwise.  However,  if  the -R option is given,
              _arguments will instead return a status of 300 to indicate  that
              $state is to be handled.

              In  addition  to $state, _arguments also sets the global parame-
              ters ‘context’, ‘line’ and ‘opt_args’ as  described  below,  and
              does  not  reset any changes made to the special parameters such
              as PREFIX and words.  This gives the calling function the choice
              of resetting these parameters or propagating changes in them.

              A  function calling _arguments with at least one action contain-
              ing a ‘->string’ therefore must declare appropriate local param-
              eters:

                     local context state line
                     typeset -A opt_args

              to avoid _arguments from altering the global environment.

       {eval-string}
              A  string  in  braces  is  evaluated  as  shell code to generate
              matches.  If the eval-string itself does not begin with an open-
              ing  parenthesis or brace it is split into separate words before
              execution.

       = action
              If the action starts with ‘= ’ (an equals  sign  followed  by  a
              space),  _arguments  will  insert  the  contents of the argument
              field of the current context as the new  first  element  in  the
              words  special array and increment the value of the CURRENT spe-
              cial parameter.  This has the effect of inserting a  dummy  word
              onto the completion command line while not changing the point at
              which completion is taking place.

              This is most useful with one of the specifiers that restrict the
              words on the command line on which the action is to operate (the
              two- and three-colon forms above).  One particular use  is  when
              an  action itself causes _arguments on a restricted range; it is
              necessary to use this trick to  insert  an  appropriate  command
              name into the range for the second call to _arguments to be able
              to parse the line.

        word...
       word...
              This covers all forms other than those  above.   If  the  action
              starts with a space, the remaining list of words will be invoked
              unchanged.

              Otherwise it will be invoked  with  some  extra  strings  placed
              after  the first word; these are to be passed down as options to
              the compadd builtin.  They ensure that the  state  specified  by
              _arguments,  in particular the descriptions of options and argu-
              ments, is correctly passed to  the  completion  command.   These
              additional  arguments are taken from the array parameter ‘expl’;
              this will be set up before executing the action and hence may be
              referred  to  inside  it,  typically in an expansion of the form
              ‘$expl[@]’ which preserves empty elements of the array.

       During the performance of the action the array ‘line’ will  be  set  to
       the  command  name and normal arguments from the command line, i.e. the
       words from the command line excluding all options and their  arguments.
       Options  are  stored  in  the  associative array ‘opt_args’ with option
       names as keys and their arguments as the values.  For options that have
       more  than  one  argument  these  are given as one string, separated by
       colons.  All colons in the original arguments are preceded  with  back-
       slashes.

       The  parameter  ‘context’ is set when returning to the calling function
       to perform an action of the form ‘->string’.  It is set to an array  of
       elements  corresponding  to  the elements of $state.  Each element is a
       suitable name for the argument field of the context: either a string of
       the  form ‘option-opt-n’ for the n’th argument of the option -opt, or a
       string of the form ‘argument-n’ for  the  n’th  argument.   For  ‘rest’
       arguments,  that  is  those in the list at the end not handled by posi-
       tion, n is the string ‘rest’.  For example, when completing  the  argu-
       ment  of  the -o option, the name is ‘option-o-1’, while for the second
       normal (non-option-) argument it is ‘argument-2’.

       Furthermore, during the evaluation of the action the  context  name  in
       the  curcontext  parameter is altered to append the same string that is
       stored in the context parameter.

       It is possible to specify multiple sets of options and  arguments  with
       the  sets  separated  by single hyphens.  The specifications before the
       first hyphen (if any) are shared by all the remaining sets.  The  first
       word in every other set provides a name for the set which may appear in
       exclusion lists in specifications, either alone or before  one  of  the
       possible  values  described  above.   In  the  second case a ‘-’ should
       appear between this name and the remainder.

       For example:

              _arguments \
                  -a \
                - set1 \
                  -c \
                - set2 \
                  -d \
                  :arg:(x2 y2)

       This defines two sets.  When the command line contains the option ‘-c’,
       the  ‘-d’  option and the argument will not be considered possible com-
       pletions.  When it contains ‘-d’ or an argument, the option  ‘-c’  will
       not be considered.  However, after ‘-a’ both sets will still be consid-
       ered valid.

       If the name given for one of the mutually exclusive sets is of the form
       ‘(name)’ then only one value from each set will ever be completed; more
       formally, all specifications are mutually exclusive to all other speci-
       fications  in  the same set.  This is useful for defining multiple sets
       of options which are mutually exclusive and in which  the  options  are
       aliases for each other.  For example:

              _arguments \
                  -a -b \
                - (compress) \
                  {-c,--compress}[compress] \
                - (uncompress) \
                  {-d,--decompress}[decompress]

       As  the  completion  code  has to parse the command line separately for
       each set this form of argument is slow and should  only  be  used  when
       necessary.   A useful alternative is often an option specification with
       rest-arguments (as in ‘-foo:*:...’); here the option -foo  swallows  up
       all remaining arguments as described by the optarg definitions.

       The  options -S and -A are available to simplify the specifications for
       commands with standard option parsing.  With -S, no option will be com-
       pleted  after  a  ‘--’  appearing on its own on the line; this argument
       will otherwise be ignored; hence in the line

              foobar -a -- -b

       the ‘-a’ is considered an option but the ‘-b’ is  considered  an  argu-
       ment, while the ‘--’ is considered to be neither.

       With  -A, no options will be completed after the first non-option argu-
       ment on the line.  The -A must be followed by a  pattern  matching  all
       strings  which  are not to be taken as arguments.  For example, to make
       _arguments stop completing options after the first normal argument, but
       ignoring  all  strings  starting  with  a  hyphen  even if they are not
       described by one of the optspecs, the form is ‘-A "-*"’.

       The option ‘-O name’ specifies the name of an array whose elements will
       be  passed  as  arguments  to functions called to execute actions.  For
       example, this can be used to pass the same set of options for the  com-
       padd builtin to all actions.

       The  option  ‘-M  spec’ sets a match specification to use to completion
       option names and values.  It must  appear  before  the  first  argument
       specification.   The  default is ‘r:|[_-]=* r:|=*’: this allows partial
       word completion after ‘_’ and ‘-’, for example ‘-f-b’ can be  completed
       to ‘-foo-bar’.

       The  option  -C tells _arguments to modify the curcontext parameter for
       an action of the form ‘->state’.  This is the standard  parameter  used
       to  keep  track  of  the current context.  Here it (and not the context
       array) should be made local to the calling function  to  avoid  passing
       back  the modified value and should be initialised to the current value
       at the start of the function:

              local curcontext="$curcontext"

       This is useful where it is not possible for multiple states to be valid
       together.

       The option ‘--’ allows _arguments to work out the names of long options
       that support the ‘--help’ option which is standard  in  many  GNU  com-
       mands.   The  command word is called with the argument ‘--help’ and the
       output examined for option names.  Clearly, it can be dangerous to pass
       this  to commands which may not support this option as the behaviour of
       the command is unspecified.

       In addition to options, ‘_arguments --’ will try to deduce the types of
       arguments available for options when the form ‘--opt=val’ is valid.  It
       is also possible to provide hints by examining the  help  text  of  the
       command  and  adding  specifiers  of the form ‘pattern:message:action’;
       note that normal _arguments specifiers are not used.   The  pattern  is
       matched against the help text for an option, and if it matches the mes-
       sage and action are used as for other argument specifiers.   For  exam-
       ple:

              _arguments -- *\*:toggle:(yes no) \
                            *=FILE*:file:_files \
                            *=DIR*:directory:_files -/ \
                            *=PATH*:directory:_files -/

       Here, ‘yes’ and ‘no’ will be completed as the argument of options whose
       description ends in a star; file names will be  completed  for  options
       that  contain the substring ‘=FILE’ in the description; and directories
       will be completed for options  whose  description  contains  ‘=DIR’  or
       ‘=PATH’.   The  last  three  are in fact the default and so need not be
       given explicitly, although it is possible to override the use of  these
       patterns.  A typical help text which uses this feature is:

                -C, --directory=DIR          change to directory DIR

       so that the above specifications will cause directories to be completed
       after ‘--directory’, though not after ‘-C’.

       Note also that _arguments tries to find out automatically if the  argu-
       ment  for  an  option is optional.  This can be specified explicitly by
       doubling the colon before the message.

       If the pattern ends in ‘(-)’, this will removed from  the  pattern  and
       the  action  will  be used only directly after the ‘=’, not in the next
       word.  This is the behaviour of a normal specification defined with the
       form ‘=-’.

       The ‘_arguments --’ can be followed by the option ‘-i patterns’ to give
       patterns for options which are not to be completed.  The  patterns  can
       be  given  as  the  name  of an array parameter or as a literal list in
       parentheses.  For example,

              _arguments -- -i \
                  "(--(en|dis)able-FEATURE*)"

       will cause completion to  ignore  the  options  ‘--enable-FEATURE’  and
       ‘--disable-FEATURE’ (this example is useful with GNU configure).

       The  ‘_arguments  --’ form can also be followed by the option ‘-s pair’
       to describe option aliases.  Each pair consists  of  a  pattern  and  a
       replacement.  For example, some configure-scripts describe options only
       as ‘--enable-foo’, but also accept ‘--disable-foo’.  To  allow  comple-
       tion of the second form:

              _arguments -- -s "(#--enable- --disable-)"

       Here is a more general example of the use of _arguments:

              _arguments -l+:left border: \
                         -format:paper size:(letter A4) \
                         *-copy:output file:_files::resolution:(300 600) \
                         :postscript file:_files -g \*.\(ps\|eps\) \
                         *:page number:

       This  describes three options: ‘-l’, ‘-format’, and ‘-copy’.  The first
       takes one argument described as ‘left border’ for which  no  completion
       will  be  offered  because  of the empty action.  Its argument may come
       directly after the ‘-l’ or it may be given as  the  next  word  on  the
       line.

       The  ‘-format’ option takes one argument in the next word, described as
       ‘paper size’ for which only the strings ‘letter’ and ‘A4’ will be  com-
       pleted.

       The  ‘-copy’  option  may appear more than once on the command line and
       takes two arguments.  The first is mandatory and will be completed as a
       filename.   The  second is optional (because of the second colon before
       the description ‘resolution’) and will be completed  from  the  strings
       ‘300’ and ‘600’.

       The  last  two  descriptions say what should be completed as arguments.
       The first describes the first argument as a ‘postscript file’ and makes
       files ending in ‘ps’ or ‘eps’ be completed.  The last description gives
       all other arguments the description ‘page numbers’ but does  not  offer
       completions.

       _cache_invalid cache_identifier
              This  function returns status zero if the completions cache cor-
              responding to the given cache identifier needs  rebuilding.   It
              determines  this  by  looking  up the cache-policy style for the
              current context.  This should provide a function name  which  is
              run  with  the  full path to the relevant cache file as the only
              argument.

              Example:

                     _example_caching_policy () {
                         # rebuild if cache is more than a week old
                         oldp=( "$1"(Nmw+1) )
                         (( $#oldp ))
                     }

       _call_function return name [ args ... ]
              If a function name exists, it is called with the arguments args.
              The  return  argument gives the name of a parameter in which the
              return status from the function name; if return is  empty  or  a
              single hyphen it is ignored.

              The  return  value of _call_function itself is zero if the func-
              tion name exists and was called and non-zero otherwise.

       _call_program tag string ...
              This function provides a mechanism for the user to override  the
              use  of an external command.  It looks up the command style with
              the supplied tag.  If the style is set, its value is used as the
              command to execute.  The strings from the call to _call_program,
              or from the style if set, are concatenated with  spaces  between
              them and the resulting string is evaluated.  The return value is
              the return value of the command called.

       _combination [ -s pattern ] tag style spec ... field opts ...
              This function is used to complete combinations of  values,   for
              example  pairs  of  hostnames and usernames.  The style argument
              gives the style which defines the pairs; it is looked  up  in  a
              context with the tag specified.

              The style name consists of field names separated by hyphens, for
              example ‘users-hosts-ports’.  For each  field  for  a  value  is
              already known, a spec of the form ‘field=pattern’ is given.  For
              example, if the command line so far specifies a user ‘pws’,  the
              argument ‘users=pws’ should appear.

              The  next  argument  with no equals sign is taken as the name of
              the field for which completions should be generated  (presumably
              not one of the fields for which the value is known).

              The matches generated will be taken from the value of the style.
              These should contain the possible values for the combinations in
              the  appropriate  order  (users,  hosts,  ports  in  the example
              above).  The different  fields  the  values  for  the  different
              fields  are  separated  by colons.  This can be altered with the
              option -s to _combination which specifies a pattern.   Typically
              this  is  a  character  class, as for example ‘-s "[:@]"’ in the
              case of the users-hosts style.    Each ‘field=pattern’  specifi-
              cation  restricts the completions which apply to elements of the
              style with appropriately matching fields.

              If no style with the given name is defined for the given tag, or
              if  none  of  the strings in style’s value match, but a function
              name of the required field preceded by an underscore is defined,
              that function will be called to generate the matches.  For exam-
              ple, if there is no ‘users-hosts-ports’ or no matching  hostname
              when  a  host  is required, the function ‘_hosts’ will automati-
              cally be called.

              If the same name is used for more than one field,  in  both  the
              ‘field=pattern’  and  the  argument  that  gives the name of the
              field to be completed, the number of the  field  (starting  with
              one)  may  be  given after the fieldname, separated from it by a
              colon.

              All arguments after the required field name are passed  to  com-
              padd  when  generating  matches  from the style value, or to the
              functions for the fields if they are called.

       _describe [ -oO | -t tag ] descr name1 [ name2 ] opts ... -- ...
              This function associates completions with descriptions.   Multi-
              ple  groups  separated  by  -- can be supplied, potentially with
              different completion options opts.

              The descr is taken as a string to display above the  matches  if
              the  format style for the descriptions tag is set.  This is fol-
              lowed by one or two names of arrays followed by options to  pass
              to  compadd.   The first array contains the possible completions
              with their descriptions in  the  form  ‘completion:description’.
              If  a  second  array is given, it should have the same number of
              elements as the first; in this case the  corresponding  elements
              are  added  as  possible  completions  instead of the completion
              strings from the first array.  The completion list  will  retain
              the  descriptions  from the first array.  Finally, a set of com-
              pletion options can appear.

              If the option  ‘-o’  appears  before  the  first  argument,  the
              matches  added will be treated as names of command options (N.B.
              not shell options), typically following a ‘-’, ‘--’  or  ‘+’  on
              the  command  line.  In this case _describe uses the prefix-hid-
              den, prefix-needed and verbose styles to find out if the strings
              should be added as completions and if the descriptions should be
              shown.  Without the ‘-o’ option, only the verbose style is  used
              to  decide  how descriptions are shown.  If ‘-O’ is used instead
              of ‘-O’, command options are completed as  above  but  _describe
              will not handle the prefix-needed style.

              With the -t option a tag can be specified.  The default is ‘val-
              ues’ or, if the -o option is given, ‘options’.

              If selected by the list-grouped style,  strings  with  the  same
              description will appear together in the list.

              _describe uses the _all_labels function to generate the matches,
              so it does not need to appear inside a loop over tag labels.

       _description [ -x ] [ -12VJ ] tag name descr [ spec ... ]
              This function is not to be confused with the previous one; it is
              used  as  a helper function for creating options to compadd.  It
              is buried inside many of the higher level  completion  functions
              and so often does not need to be called directly.

              The  styles listed below are tested in the current context using
              the given tag.  The resulting options for compadd are  put  into
              the  array  named  name  (this is traditionally ‘expl’, but this
              convention is not enforced).  The  description  for  the  corre-
              sponding set of matches is passed to the function in descr.

              The styles tested are: format, hidden, matcher, ignored-patterns
              and group-name.  The format style is first tested for the  given
              tag  and  then  for  the descriptions tag if no value was found,
              while the remainder are only tested for the  tag  given  as  the
              first argument.  The function also calls _setup which tests some
              more styles.

              The string returned by the format style (if any) will  be  modi-
              fied so that the sequence ‘%d’ is replaced by the descr given as
              the third argument without any leading or trailing white  space.
              If,  after  removing  the  white  space,  the descr is the empty
              string, the format style will not be used and  the  options  put
              into the name array will not contain an explanation string to be
              displayed above the matches.

              If _description is called with more than  three  arguments,  the
              additional specs should be of the form ‘char:str’.  These supply
              escape sequence replacements for the format style: every appear-
              ance of ‘%char’ will be replaced by string.

              If  the  -x  option  is given, the description will be passed to
              compadd using the -x option instead of  the  default  -X.   This
              means  that  the description will be displayed even if there are
              no corresponding matches.

              The options placed  in  the  array  name  take  account  of  the
              group-name  style,  so  matches  are  placed in a separate group
              where necessary.  The group normally has its elements sorted (by
              passing  the  option  -J  to compadd), but if an option starting
              with ‘-V’, ‘-J’, ‘-1’, or ‘-2’ is passed to  _description,  that
              option  will be included in the array.  Hence it is possible for
              the completion group to be unsorted by giving the  option  ‘-V’,
              ‘-1V’, or ‘-2V’.

              In most cases, the function will be used like this:

                     local expl
                     _description files expl file
                     compadd "$expl[@]" - "$files[@]"

              Note  the use of the parameter expl, the hyphen, and the list of
              matches.  Almost all calls to compadd within the completion sys-
              tem  use  a  similar  format;  this  ensures that user-specified
              styles are correctly passed down to the builtins which implement
              the internals of completion.

       _dispatch context string ...
              This  sets  the current context to context and looks for comple-
              tion functions to handle this context  by  hunting  through  the
              list  of  command  names or special contexts (as described above
              for compdef) given as string ....  The first completion function
              to  be  defined  for  one of the contexts in the list is used to
              generate matches.  Typically, the last string  is  -default-  to
              cause  the function for default completion to be used as a fall-
              back.

              The function sets the parameter $service  to  the  string  being
              tried,  and  sets  the context/command field (the fourth) of the
              $curcontext parameter to the context given as  the  first  argu-
              ment.

       _files The  function _files calls _path_files with all the arguments it
              was passed except for -g and -/.  The use of these  two  options
              depends on the setting of the  file-patterns style.

              This  function  accepts  the  full  set  of  options  allowed by
              _path_files, described below.

       _gnu_generic
              This function is a simple wrapper around the _arguments function
              described  above.  It can be used to determine automatically the
              long options understood by commands that  produce  a  list  when
              passed  the  option  ‘--help’.   It  is intended to be used as a
              top-level completion function in its own right.  For example, to
              enable option completion for the commands foo and bar, use

                     compdef _gnu_generic foo bar

              after the call to compinit.

              The  completion system as supplied is conservative in its use of
              this function, since it is important  to  be  sure  the  command
              understands the option ‘--help’.

       _guard [ options ] pattern descr
              This function is intended to be used in the action for the spec-
              ifications passed  to  _arguments  and  similar  functions.   It
              returns  immediately  with a non-zero return value if the string
              to be completed does not match  the  pattern.   If  the  pattern
              matches,  the descr is displayed; the function then returns zero
              if the word to complete is not empty, non-zero otherwise.

              The pattern may be preceded by any of the options understood  by
              compadd  that  are passed down from _description, namely -M, -J,
              -V, -1, -2, -n, -F  and  -X.   All  of  these  options  will  be
              ignored.   This  fits  in conveniently with the argument-passing
              conventions of actions for _arguments.

              As an example, consider a command  taking  the  options  -n  and
              -none,  where -n must be followed by a numeric value in the same
              word.  By using:

                     _arguments -n-: :_guard "[0-9]#" "numeric value" -none

              _arguments can be made to  both  display  the  message  ‘numeric
              value’  and  complete  options  after ‘-n<TAB>’.  If the ‘-n’ is
              already followed by one or more digits (the  pattern  passed  to
              _guard)  only the message will be displayed; if the ‘-n’ is fol-
              lowed by another character, only options are completed.

       _message [ -r12 ] [ -VJ group ] descr
       _message -e [ tag ] descr
              The descr is used in the same way as the third argument  to  the
              _description  function,  except  that  the resulting string will
              always be shown whether or not matches were generated.  This  is
              useful  for displaying a help message in places where no comple-
              tions can be generated.

              The format style is examined with the messages  tag  to  find  a
              message;  the usual tag, descriptions, is used only if the style
              is not set with the former.

              If the -r option is given, no style is used; the descr is  taken
              literally  as  the  string to display.  This is most useful when
              the descr comes from a pre-processed argument list which already
              contains an expanded description.

              The  -12VJ options and the group are passed to compadd and hence
              determine the group the message string is added to.

              The second form gives a description for completions with the tag
              tag  to be shown even if there are no matches for that tag.  The
              tag can be omitted and if so the tag is taken from the parameter
              $curtag;  this  is maintained by the completion system and so is
              usually correct.

       _multi_parts sep array
              The argument sep is a separator character.   The  array  may  be
              either  the name of an array parameter or a literal array in the
              form ‘(foo bar)’, a parenthesised list  of  words  separated  by
              whitespace.   The  possible completions are the strings from the
              array.  However, each chunk delimited by sep will  be  completed
              separately.  For example, the _tar function uses ‘_multi_parts /
              patharray’ to complete partial file paths from the  given  array
              of complete file paths.

              The  -i option causes _multi_parts to insert a unique match even
              if that requires multiple separators to be  inserted.   This  is
              not  usually  the expected behaviour with filenames, but certain
              other types of completion, for example those with a fixed set of
              possibilities, may be more suited to this form.

              Like  other  utility  functions, this function accepts the ‘-V’,
              ‘-J’, ‘-1’, ‘-2’, ‘-n’, ‘-f’,  ‘-X’,  ‘-M’,  ‘-P’,  ‘-S’,  ‘-r’,
              ‘-R’, and ‘-q’ options and passes them to the compadd builtin.

       _next_label [ -x ] [ -12VJ ] tag name descr [ options ... ]
              This  function  is used to implement the loop over different tag
              labels for a particular tag as described above for the tag-order
              style.   On each call it checks to see if there are any more tag
              labels; if there is it returns status zero, otherwise  non-zero.
              As  this  function  requires  a  current  tag to be set, it must
              always follow a call to _tags or _requested.

              The -x12VJ options and the first three arguments are  passed  to
              the  _description  function.   Where appropriate the tag will be
              replaced by a tag label in this call.  Any description given  in
              the  tag-order  style  is  preferred  to  the  descr  passed  to
              _next_label.

              The options given after the descr are set in the parameter given
              by name, and hence are to be passed to compadd or whatever func-
              tion is called to add the matches.

              Here is a typical use of this function for  the  tag  foo.   The
              call to _requested determines if tag foo is required at all; the
              loop over _next_label handles any labels defined for the tag  in
              the tag-order style.

                     local expl ret=1
                     ...
                     if _requested foo; then
                       ...
                       while _next_label foo expl ...; do
                         compadd "$expl[@]" ... && ret=0
                       done
                       ...
                     fi
                     return ret

       _normal
              This  is  the standard function called to handle completion out-
              side any special -context-.  It is called both to  complete  the
              command  word and also the arguments for a command.  In the sec-
              ond case, _normal looks for a special completion for  that  com-
              mand,  and  if  there  is  none  it  uses the completion for the
              -default- context.

              A second use is to reexamine the command line specified  by  the
              $words  array  and  the $CURRENT parameter after those have been
              modified.  For example, the  function  _precommand,  which  com-
              pletes  after  pre-command specifiers such as nohup, removes the
              first word from the words array, decrements the CURRENT  parame-
              ter,  then  calls  _normal again.  The effect is that ‘nohup cmd
              ...’  is treated in the same way as ‘cmd ...’.

              If the command name matches one of the patterns given by one  of
              the  options  -p  or -P to compdef, the corresponding completion
              function is called and then the parameter _compskip is  checked.
              If  it  is set completion is terminated at that point even if no
              matches have been found.  This is the  same  effect  as  in  the
              -first- context.

       _options
              This  can  be  used  to complete the names of shell options.  It
              provides a matcher specification that ignores  a  leading  ‘no’,
              ignores underscores and allows upper-case letters to match their
              lower-case  counterparts   (for   example,   ‘glob’,   ‘noglob’,
              ‘NO_GLOB’  are  all completed).  Any arguments are propagated to
              the compadd builtin.

       _options_set and _options_unset
              These functions complete only set or  unset  options,  with  the
              same matching specification used in the _options function.

              Note  that  you  need to uncomment a few lines in the _main_com-
              plete function for these functions to work properly.  The  lines
              in  question  are  used  to  store the option settings in effect
              before the completion widget locally sets the options it  needs.
              Hence  these  functions are not generally used by the completion
              system.

       _parameters
              This is used to complete the names of shell parameters.

              The option ‘-g pattern  limits  the  completion  to  parameters
              whose type matches the pattern.  The type of a parameter is that
              shown by print ${(t)param}, hence judicious use of * in pat-
              tern is probably necessary.

              All other arguments are passed to the compadd builtin.

       _path_files
              This  function  is used throughout the completion system to com-
              plete filenames.  It allows completion of  partial  paths.   For
              example,   the   string   ‘/u/i/s/sig’   may   be  completed  to
              ‘/usr/include/sys/signal.h’.

              The options accepted by both _path_files and _files are:

              -f     Complete all filenames.  This is the default.

              -/     Specifies that only directories should be completed.

              -g pattern
                     Specifies that only files matching the pattern should  be
                     completed.

              -W paths
                     Specifies  path  prefixes that are to be prepended to the
                     string from the command line to  generate  the  filenames
                     but  that should not be inserted as completions nor shown
                     in completion listings.  Here, paths may be the  name  of
                     an  array  parameter, a literal list of paths enclosed in
                     parentheses or an absolute pathname.

              -F ignored-files
                     This behaves as for the corresponding option to the  com-
                     padd  builtin.   It gives direct control over which file-
                     names should be ignored.  If the option is  not  present,
                     the ignored-patterns style is used.

              Both  _path_files  and  _files also accept the following options
              which are passed to compadd: ‘-J’, ‘-V’, ‘-1’, ‘-2’, ‘-n’, ‘-X’,
              ‘-M’, ‘-P’, ‘-S’, ‘-q’, ‘-r’, and ‘-R’.

              Finally,  the  _path_files  function   uses  the  styles expand,
              ambiguous, special-dirs, list-suffixes and  file-sort  described
              above.

       _pick_variant [ -c command ] [ -r name ] label=pattern ... label [ args
       ... ]
              This  function is used to resolve situations where a single com-
              mand name requires  more  than  one  type  of  handling,  either
              because  it has more than one variant or because there is a name
              clash between two different commands.

              The command to run is taken from the first element of the  array
              words  unless this is overridden by the option -c.  This command
              is run and its output is compared with  a  series  of  patterns.
              Arguments  to  be  passed to the command can be specified at the
              end after all the other arguments.  The patterns to try in order
              are given by the arguments label=pattern; if the output of ‘com-
              mand args ...’ contains pattern, then label is selected  as  the
              label  for  the command variant.  If none of the patterns match,
              the final command label is selected and status 1 is returned.

              If the ‘-r name’ is given, the label picked  is  stored  in  the
              parameter named name.

              The  results  are  also  cached  in the _cmd_variant associative
              array indexed by the name of the command run.

       _regex_arguments name spec ...
              This function generates a completion function name which matches
              the  specifications  spec  ...,  a set of regular expressions as
              described below.  After running _regex_arguments,  the  function
              name  should be called at the appropriate point.  The pattern to
              be matched is given by the contents of the words array up to the
              current cursor position joined together with null characters; no
              quotation is applied.

              The arguments are grouped as sets of alternatives  separated  by
              ‘|’,  which  are  tried  one  after the other until one matches.
              Each alternative consists of a one or more specifications  which
              are  tried  left  to  right,  with  each  pattern  matched being
              stripped in turn from the command line being tested,  until  all
              of  the  group  succeeds or until one fails; in the latter case,
              the next alternative is tried.  This structure can  be  repeated
              to  arbitrary depth by using parentheses; matching proceeds from
              inside to outside.

              A special procedure is applied  if  no  test  succeeds  but  the
              remaining command line string contains no null character (imply-
              ing the remaining word is the one for which completions  are  to
              be  generated).   The  completion  target  is  restricted to the
              remaining word and any actions for  the  corresponding  patterns
              are  executed.   In this case, nothing is stripped from the com-
              mand line string.  The order of evaluation of the actions can be
              determined by the tag-order style; the various formats supported
              by _alternative can be used in action.  The descr  is  used  for
              setting up the array parameter expl.

              Specification  arguments  take  one of following forms, in which
              metacharacters such as ‘(’, ‘)’, ‘#’ and ‘|’ should be quoted.

              /pattern/ [%lookahead%] [-guard] [:tag:descr:action]
                     This is a single primitive component.  The function tests
                     whether  the  combined  pattern  ‘(#b)((#B)pattern)looka-
                     head*’ matches the command line string.  If  so,  ‘guard’
                     is  evaluated and its return status is examined to deter-
                     mine if the test has succeeded.  The pattern string  ‘[]’
                     is  guaranteed  never  to  match.   The  lookahead is not
                     stripped from the command line before the next pattern is
                     examined.

              /pattern/+ [%lookahead%] [-guard] [:tag:descr:action]
                     This  is  similar to ‘/pattern/ ...’ but the left part of
                     the command line string (i.e. the part already matched by
                     previous patterns) is also considered part of the comple-
                     tion target.

              /pattern/- [%lookahead%] [-guard] [:tag:descr:action]
                     This is similar to ‘/pattern/ ...’ but the actions of the
                     current  and previously matched patterns are ignored even
                     if the following ‘pattern’ matches the empty string.

              ( spec )
                     Parentheses may be used to groups specs; note each paren-
                     thesis is a single argument to _regex_arguments.

              spec # This allows any number of repetitions of spec.

              spec spec
                     The  two  specs  are to be matched one after the other as
                     described above.

              spec | spec
                     Either of the two specs can be matched.

       _requested [ -x ] [ -12VJ ] tag [ name descr [ command args ... ] ]
              This function is called to decide whether a tag  already  regis-
              tered  by  a call to _tags (see below) has been requested by the
              user and hence  completion  should  be  performed  for  it.   It
              returns  status zero if the tag is requested and non-zero other-
              wise.  The function is typically used as part  of  a  loop  over
              different tags as follows:

                     _tags foo bar baz
                     while _tags; do
                       if _requested foo; then
                         ... # perform completion for foo
                       fi
                       ... # test the tags bar and baz in the same way
                       ... # exit loop if matches were generated
                     done

              Note  that  the  test  for whether matches were generated is not
              performed until the end of the _tags loop.  This is so that  the
              user  can set the tag-order style to specify a set of tags to be
              completed at the same time.

              If name and descr are given, _requested calls  the  _description
              function  with  these arguments together with the options passed
              to _requested.

              If command is given, the _all_labels  function  will  be  called
              immediately with the same arguments.  In simple cases this makes
              it possible to perform the test for the tag and the matching  in
              one go.  For example:

                     local expl ret=1
                     _tags foo bar baz
                     while _tags; do
                       _requested foo expl description \
                           compadd foobar foobaz && ret=0
                       ...
                       (( ret )) || break
                     done

              If  the command is not compadd, it must nevertheless be prepared
              to handle the same options.

       _retrieve_cache cache_identifier
              This function retrieves completion  information  from  the  file
              given  by  cache_identifier,  stored in a directory specified by
              the cache-path style which defaults to ~/.zsh/cache.  The return
              value is zero if retrieval was successful.  It will only attempt
              retrieval if the use-cache style is set, so you  can  call  this
              function  without  worrying about whether the user wanted to use
              the caching layer.

              See _store_cache below for more details.

       _sep_parts
              This function is passed alternating  arrays  and  separators  as
              arguments.   The arrays specify completions for parts of strings
              to be separated by the separators.  The arrays may be the  names
              of  array  parameters  or a quoted list of words in parentheses.
              For  example,  with  the  array  ‘hosts=(ftp  news)’  the   call
              ‘_sep_parts  (foo  bar) @ hosts’ will complete the string  ‘f’
              to ‘foo’ and the string ‘b@n’ to ‘bar@news’.

              This function accepts the  compadd  options  ‘-V’,  ‘-J’,  ‘-1’,
              ‘-2’,  ‘-n’,  ‘-X’,  ‘-M’,  ‘-P’, ‘-S’, ‘-r’, ‘-R’, and ‘-q’ and
              passes them on to the compadd builtin used to add the matches.

       _setup tag [ group ]
              This function sets up the special parameters used by the comple-
              tion  system  appropriately  for  the  tag  given  as  the first
              argument.   It  uses  the   styles   list-colors,   list-packed,
              list-rows-first, last-prompt, accept-exact, menu and force-list.

              The optional group supplies the name of the group in  which  the
              matches  will be placed.  If it is not given, the tag is used as
              the group name.

              This function is  called  automatically  from  _description  and
              hence is not normally called explicitly.

       _store_cache cache_identifier params ...
              This function, together with _retrieve_cache and _cache_invalid,
              implements a caching layer which can be used in  any  completion
              function.   Data  obtained  by  costly  operations are stored in
              parameters; this function then dumps the values of those parame-
              ters  to  a  file.   The data can then be retrieved quickly from
              that file via _retrieve_cache, even in  different  instances  of
              the shell.

              The cache_identifier specifies the file which the data should be
              dumped to.  The file is stored in a directory specified  by  the
              cache-path  style which defaults to ~/.zsh/cache.  The remaining
              params arguments are the parameters to dump to the file.

              The return value is zero if storage was successful.   The  func-
              tion will only attempt storage if the use-cache style is set, so
              you can call this function without worrying  about  whether  the
              user wanted to use the caching layer.

              The  completion  function may avoid calling _retrieve_cache when
              it already has the  completion  data  available  as  parameters.
              However,  in  that  case  it should call _cache_invalid to check
              whether the data in the parameters and in the  cache  are  still
              valid.

              See  the  _perl_modules completion function for a simple example
              of the usage of the caching layer.

       _tags [ [ -C name ] tags ... ]
              If called with arguments, these are taken to  be  the  names  of
              tags  valid  for completions in the current context.  These tags
              are stored internally and sorted by using the tag-order style.

              Next, _tags is called repeatedly without arguments from the same
              completion  function.  This successively selects the first, sec-
              ond, etc. set of tags requested by the user.  The  return  value
              is  zero  if  at least one of the tags is requested and non-zero
              otherwise.  To test if a particular tag  is  to  be  tried,  the
              _requested function should be called (see above).

              If  ‘-C  name’ is given, name is temporarily stored in the argu-
              ment field (the fifth) of the context in the curcontext  parame-
              ter  during  the  call  to _tags; the field is restored on exit.
              This allows _tags to use a more specific context without  having
              to change and reset the curcontext parameter (which has the same
              effect).

       _values [ -O name ] [ -s sep ] [ -S sep ] [ -wC ] desc spec ...
              This is used to complete arbitrary keywords (values)  and  their
              arguments, or lists of such combinations.

              If  the  first argument is the option ‘-O name’, it will be used
              in the same way as by the _arguments function.  In other  words,
              the  elements  of  the name array will be passed to compadd when
              executing an action.

              If the first argument (or the first argument after ‘-O name’) is
              ‘-s’,  the next argument is used as the character that separates
              multiple values.  This character is  automatically  added  after
              each  value in an auto-removable fashion (see below); all values
              completed by ‘_values -s’ appear in the same word on the command
              line, unlike completion using _arguments.  If this option is not
              present, only a single value will be completed per word.

              Normally, _values will only use the current  word  to  determine
              which  values  are already present on the command line and hence
              are not to be completed again.  If the -w option is given, other
              arguments are examined as well.

              The  first non-option argument is used as a string to print as a
              description before listing the values.

              All other arguments describe the possible values and their argu-
              ments  in the same format used for the description of options by
              the _arguments function (see above).  The only  differences  are
              that  no minus or plus sign is required at the beginning, values
              can have only one argument, and the forms  of  action  beginning
              with an equal sign are not supported.

              The  character  separating  a value from its argument can be set
              using the option -S (like -s, followed by the character  to  use
              as  the  separator in the next argument).  By default the equals
              sign will be used as the separator between values and arguments.

              Example:

                     _values -s , description \
                             *foo[bar] \
                             (two)*one[number]:first count: \
                             two[another number]::second count:(1 2 3)

              This  describes  three possible values: ‘foo’, ‘one’, and ‘two’.
              The first is described as  ‘bar’,  takes  no  argument  and  may
              appear more than once.  The second is described as ‘number’, may
              appear  more  than  once,  and  takes  one  mandatory   argument
              described  as  ‘first count’; no action is specified, so it will
              not be completed.  The ‘(two)’ at the beginning says that if the
              value  ‘one’  is  on the line, the value ‘two’ will no longer be
              considered a  possible  completion.   Finally,  the  last  value
              (‘two’)  is  described as ‘another number’ and takes an optional
              argument described as ‘second count’ for which  the  completions
              (to  appear  after  an  ‘=’) are ‘1’, ‘2’, and ‘3’.  The _values
              function will complete lists of these values separated  by  com-
              mas.

              Like  _arguments, this function temporarily adds another context
              name component to the arguments element (the fifth) of the  cur-
              rent context while executing the action.  Here this name is just
              the name of the value for which the argument is completed.

              The style verbose is used to decide if the descriptions for  the
              values (but not those for the arguments) should be printed.

              The  associative  array  val_args  is  used to report values and
              their arguments; this works similarly to the  opt_args  associa-
              tive array used by _arguments.  Hence the function calling _val-
              ues should declare the local parameters state, line, context and
              val_args:

                     local context state line
                     typeset -A val_args

              when using an action of the form ‘->string’.  With this function
              the context parameter will be set to the name of the value whose
              argument is to be completed.

              Note  also  that _values normally adds the character used as the
              separator between values as an auto-removable suffix (similar to
              a  ‘/’  after a directory).  However, this is not possible for a
              ‘->string’ action as the matches for the argument are  generated
              by  the  calling  function.  To get the usual behaviour, the the
              calling function can add the separator x as a suffix by  passing
              the options ‘-qS x’ either directly or indirectly to compadd.

              The option -C is treated in the same way as it is by _arguments.
              In that case the  parameter  curcontext  should  be  made  local
              instead of context (as described above).

       _wanted [ -x ] [ -C name ]  [ -12VJ ] tag name descr command args ...
              In  many  contexts,  completion can only generate one particular
              set of matches, usually corresponding to a single tag.  However,
              it  is  still  necessary  to  decide  whether  the user requires
              matches of this type.  This function is useful in such a case.

              The arguments to _wanted are the same as  those  to  _requested,
              i.e.  arguments  to be passed to _description.  However, in this
              case the command is not optional;  all the processing  of  tags,
              including the loop over both tags and tag labels and the genera-
              tion of matches, is carried out automatically by _wanted.

              Hence to offer only one tag and immediately add the  correspond-
              ing matches with the given description:

                     _wanted tag expl description \
                         compadd matches...

              Note that, as for _requested, the command must be able to accept
              options to be passed down to compadd.

              Like _tags this function supports the -C option to give  a  dif-
              ferent  name  for the argument context field.  The -x option has
              the same meaning as for _description.



COMPLETION DIRECTORIES

       In the source distribution, the files are contained in  various  subdi-
       rectories of the Completion directory.  They may have been installed in
       the same structure, or into one single function directory.  The follow-
       ing  is  a  description  of  the  files found in the original directory
       structure.  If you wish to alter an installed file, you  will  need  to
       copy  it to some directory which appears earlier in your fpath than the
       standard directory where it appears.

       Base   The core functions and special completion widgets  automatically
              bound  to  keys.   You will certainly need most of these, though
              will probably not need to alter them.  Many of these  are  docu-
              mented above.

       Zsh    Functions for completing arguments of shell builtin commands and
              utility functions for this.  Some of  these  are  also  used  by
              functions from the Unix directory.

       Unix   Functions  for  completing  arguments  of  external commands and
              suites of commands.  They may need modifying  for  your  system,
              although in many cases some attempt is made to decide which ver-
              sion of a command is present.  For example, completion  for  the
              mount  command  tries  to determine the system it is running on,
              while completion for many other utilities try to decide  whether
              the  GNU version of the command is in use, and hence whether the
              --help option is supported.

       X, AIX, BSD, ...
              Completion and utility function for commands available  only  on
              some  systems.   These  are not arranged hierarchically, so, for
              example, both the Linux and Debian directories, as well as the X
ZSHCOMPCTL(1)                                                    ZSHCOMPCTL(1)



              directory, may be useful on your system.


NAME

       zshcompctl - zsh programmable completion


DESCRIPTION

       This  version  of zsh has two ways of performing completion of words on
       the command line.  New users of the shell may prefer to use  the  newer
       and more powerful system based on shell functions; this is described in
       zshcompsys(1), and the basic shell  mechanisms  which  support  it  are
       described in zshcompwid(1).  This manual entry describes the older com-
       pctl command.
       compctl [ -CDT ] options [ command ... ]
       compctl [ -CDT ] options [ -x pattern options - ... -- ] [ + options  [
       -x ... -- ] ... [+] ] [ command ... ]
       compctl -M match-specs ...
       compctl -L [ -CDTM ] [ command ... ]
       compctl + command ...

       Control the editor’s completion behavior according to the supplied  set
       of options.  Various editing commands, notably expand-or-complete-word,
       usually bound to tab, will attempt to complete  a  word  typed  by  the
       user, while others, notably delete-char-or-list, usually bound to ^D in
       EMACS editing mode, list the possibilities; compctl controls what those
       possibilities  are.  They may for example be filenames (the most common
       case, and  hence  the  default),  shell  variables,  or  words  from  a
       user-specified list.



COMMAND FLAGS

       Completion of the arguments of a command may be different for each com-
       mand or may use the default.  The behavior when completing the  command
       word  itself may also be separately specified.  These correspond to the
       following flags and arguments, all of which (except for -L) may be com-
       bined with any combination of the options described subsequently in the
       section ‘Option Flags’:

       command ...
              controls completion for the named commands, which must be listed
              last on the command line.  If completion is attempted for a com-
              mand with a pathname containing slashes and no completion  defi-
              nition  is  found,  the search is retried with the last pathname
              component. If the command starts with a =, completion  is  tried
              with the pathname of the command.

              Any  of the command strings may be patterns of the form normally
              used for filename generation.  These should be be quoted to pro-
              tect  them  from  immediate  expansion;  for example the command
              string foo* arranges for completion of the words of  any  com-
              mand beginning with foo.  When completion is attempted, all pat-
              tern completions are tried in the reverse order of their defini-
              tion until one matches.  By default, completion then proceeds as
              normal, i.e. the shell will try to generate more matches for the
              specific  command on the command line; this can be overridden by
              including -tn in the flags for the pattern completion.

              Note that aliases are expanded before the command name is deter-
              mined  unless  the COMPLETE_ALIASES option is set.  Commands may
              not be combined with the -C, -D or -T flags.

       -C     controls completion when the command word itself is  being  com-
              pleted.  If no compctl -C command has been issued,  the names of
              any executable command (whether in the path or specific  to  the
              shell, such as aliases or functions) are completed.

       -D     controls  default  completion behavior for the arguments of com-
              mands not assigned any  special  behavior.   If  no  compctl  -D
              command has been issued, filenames are completed.

       -T     supplies completion flags to be used before any other processing
              is done, even before processing for compctls  defined  for  spe-
              cific  commands.   This  is especially useful when combined with
              extended completion (the -x flag, see the section ‘Extended Com-
              pletion’  below).  Using this flag you can define default behav-
              ior which will apply to all commands without exception,  or  you
              can  alter the standard behavior for all commands.  For example,
              if your access to the user database is too slow and/or  it  con-
              tains  too  many users (so that completion after ‘~’ is too slow
              to be usable), you can use

                     compctl -T -x s[~] C[0,[^/]#] -k friends -S/ -tn

              to complete the strings in the array friends after a  ‘~’.   The
              C[...]  argument  is necessary so that this form of ~-completion
              is not tried after the directory name is finished.

       -L     lists the existing completion behavior in a manner suitable  for
              putting  into  a  start-up  script; the existing behavior is not
              changed.  Any combination of the above forms,  or  the  -M  flag
              (which must follow the -L flag), may be specified, otherwise all
              defined completions are listed.  Any other  flags  supplied  are
              ignored.

       no argument
              If  no  argument is given, compctl lists all defined completions
              in an abbreviated form;  with a list of options, all completions
              with  those  flags  set  (not  counting extended completion) are
              listed.

       If the + flag is alone and followed immediately by  the  command  list,
       the  completion  behavior  for all the commands in the list is reset to
       the default.  In other words,  completion  will  subsequently  use  the
       options specified by the -D flag.

       The  form  with -M as the first and only option defines global matching
       specifications (see zshcompwid). The match specifications given will be
       used  for  every  completion attempt (only when using compctl, not with
       the new completion system) and are tried in the order in which they are
       defined until one generates at least one match. E.g.:

              compctl -M  m:{a-zA-Z}={A-Za-z}

       This  will first try completion without any global match specifications
       (the empty string) and, if that generates no  matches,  will  try  case
       insensitive completion.



OPTION FLAGS

       [ -fcFBdeaRGovNAIOPZEnbjrzu/12 ]
       [ -k array ] [ -g globstring ] [ -s subststring ]
       [ -K function ]
       [ -Q ] [ -P prefix ] [ -S suffix ]
       [ -W file-prefix ] [ -H num pattern ]
       [ -q ] [ -X explanation ] [ -Y explanation ]
       [ -y func-or-var ] [ -l cmd ] [ -h cmd ] [ -U ]
       [ -t continue ] [ -J name ] [ -V name ]
       [ -M match-spec ]

       The remaining options specify the type of command arguments to look for
       during completion.  Any combination of these flags  may  be  specified;
       the  result is a sorted list of all the possibilities.  The options are
       as follows.


   Simple Flags
       These produce completion lists made up by the shell itself:

       -f     Filenames and filesystem paths.

       -/     Just filesystem paths.

       -c     Command names, including aliases, shell functions, builtins  and
              reserved words.

       -F     Function names.

       -B     Names of builtin commands.

       -m     Names of external commands.

       -w     Reserved words.

       -a     Alias names.

       -R     Names of regular (non-global) aliases.

       -G     Names of global aliases.

       -d     This can be combined with -F, -B, -w, -a, -R and -G to get names
              of disabled functions, builtins, reserved words or aliases.

       -e     This option (to show enabled commands) is in effect by  default,
              but may be combined with -d; -de in combination with -F, -B, -w,
              -a, -R and  -G  will  complete  names  of  functions,  builtins,
              reserved words or aliases whether or not they are disabled.

       -o     Names of shell options (see zshoptions(1)).

       -v     Names of any variable defined in the shell.

       -N     Names of scalar (non-array) parameters.

       -A     Array names.

       -I     Names of integer variables.

       -O     Names of read-only variables.

       -p     Names of parameters used by the shell (including special parame-
              ters).

       -Z     Names of shell special parameters.

       -E     Names of environment variables.

       -n     Named directories.

       -b     Key binding names.

       -j     Job names:  the first word of the  job  leader’s  command  line.
              This is useful with the kill builtin.

       -r     Names of running jobs.

       -z     Names of suspended jobs.

       -u     User names.


   Flags with Arguments
       These have user supplied arguments to determine how the list of comple-
       tions is to be made up:

       -k array
              Names taken from the elements of $array (note that the ‘$’  does
              not  appear  on  the command line).  Alternatively, the argument
              array itself may be a set of space- or comma-separated values in
              parentheses,  in which any delimiter may be escaped with a back-
              slash; in this case the argument should be quoted.  For example,

                     compctl -k "(cputime filesize datasize stacksize
                                 coredumpsize resident descriptors)" limit

       -g globstring
              The globstring is expanded using filename globbing; it should be
              quoted to protect it from  immediate  expansion.  The  resulting
              filenames  are  taken  as  the possible completions.  Use ‘*(/)’
              instead of ‘*/’ for directories.  The fignore special  parameter
              is  not  applied  to the resulting files.  More than one pattern
              may be given separated by blanks. (Note that brace expansion  is
              not  part  of  globbing.   Use the syntax ‘(either|or)’ to match
              alternatives.)

       -s subststring
              The subststring is split into words and  these  words  are  than
              expanded  using all shell expansion mechanisms (see zshexpn(1)).
              The resulting words are taken as possible completions.  The fig-
              nore  special  parameter  is not applied to the resulting files.
              Note that -g is faster for filenames.

       -K function
              Call the given function to get the completions.  Unless the name
              starts with an underscore, the function is passed two arguments:
              the prefix and the suffix of the word on which completion is  to
              be  attempted, in other words those characters before the cursor
              position, and those from the cursor position onwards.  The whole
              command  line  can  be  accessed with the -c and -l flags of the
              read builtin. The function should set the variable reply  to  an
              array  containing  the completions (one completion per element);
              note that reply should not be made local to the function.   From
              such a function the command line can be accessed with the -c and
              -l flags to the read builtin.  For example,

                     function whoson { reply=(users); }
                     compctl -K whoson talk

              completes only logged-on users after ‘talk’.  Note that ‘whoson’
              must return an array, so ‘reply=users’ would be incorrect.

       -H num pattern
              The  possible  completions  are  taken from the last num history
              lines.  Only words matching pattern are taken.  If num  is  zero
              or  negative the whole history is searched and if pattern is the
              empty string all words are taken (as with ‘*’).  A  typical  use
              is

                     compctl -D -f + -H 0 

              which  forces  completion to look back in the history list for a
              word if no filename matches.


   Control Flags
       These do not directly specify types of name to be completed, but manip-
       ulate the options that do:

       -Q     This  instructs the shell not to quote any metacharacters in the
              possible completions.  Normally the results of a completion  are
              inserted into the command line with any metacharacters quoted so
              that they are interpreted as normal characters.  This is  appro-
              priate for filenames and ordinary strings.  However, for special
              effects, such as inserting a backquoted expression from  a  com-
              pletion  array (-k) so that the expression will not be evaluated
              until the complete line is executed, this option must be used.

       -P prefix
              The prefix is inserted just before  the  completed  string;  any
              initial  part already typed will be completed and the whole pre-
              fix ignored for completion purposes.  For example,

                     compctl -j -P "%" kill

              inserts a ‘%’ after the kill  command  and  then  completes  job
              names.

       -S suffix
              When a completion is found the suffix is inserted after the com-
              pleted string.  In the case of menu  completion  the  suffix  is
              inserted  immediately, but it is still possible to cycle through
              the list of completions by repeatedly hitting the same key.

       -W file-prefix
              With directory file-prefix:  for command,  file,  directory  and
              globbing completion (options -c, -f, -/, -g), the file prefix is
              implicitly added in front of the completion.  For example,

                     compctl -/ -W ~/Mail maildirs

              completes any subdirectories to any depth beneath the  directory
              ~/Mail,  although  that  prefix  does  not appear on the command
              line.  The file-prefix may also be of the form accepted  by  the
              -k  flag,  i.e. the name of an array or a literal list in paren-
              thesis. In this case all the directories in  the  list  will  be
              searched for possible completions.

       -q     If used with a suffix as specified by the -S option, this causes
              the suffix to be 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  charac-
              ter;  this  the same rule used for the AUTO_REMOVE_SLASH option.
              The option is most useful for  list  separators  (comma,  colon,
              etc.).

       -l cmd This  option  restricts the range of command line words that are
              considered to  be  arguments.   If  combined  with  one  of  the
              extended  completion  patterns  ‘p[...]’,  ‘r[...]’, or ‘R[...]’
              (see the section  ‘Extended  Completion’  below)  the  range  is
              restricted  to the range of arguments specified in the brackets.
              Completion is then performed as if these had been given as argu-
              ments  to the cmd supplied with the option. If the cmd string is
              empty the first word in the range is instead taken as  the  com-
              mand  name,  and  command name completion performed on the first
              word in the range.  For example,

                     compctl -x r[-exec,;] -l  -- find

              completes arguments between ‘-exec’ and the  following  ‘;’  (or
              the  end  of  the command line if there is no such string) as if
              they were a separate command line.

       -h cmd Normally zsh completes quoted strings  as  a  whole.  With  this
              option,  completion can be done separately on different parts of
              such strings. It works like the -l option but makes the  comple-
              tion  code  work on the parts of the current word that are sepa-
              rated by spaces. These parts are completed as if they were argu-
              ments  to  the  given cmd. If cmd is the empty string, the first
              part is completed as a command name, as with -l.

       -U     Use the whole list of possible completions, whether or not  they
              actually  match the word on the command line.  The word typed so
              far will be deleted.  This is most useful with a function (given
              by  the  -K option) which can examine the word components passed
              to it (or via the read builtin’s -c and -l flags)  and  use  its
              own criteria to decide what matches.  If there is no completion,
              the original word is  retained.   Since  the  produced  possible
              completions  seldom  have  interesting  common prefixes and suf-
              fixes, menu completion is started immediately  if  AUTO_MENU  is
              set and this flag is used.

       -y func-or-var
              The  list  provided  by  func-or-var is displayed instead of the
              list of completions whenever a listing is required;  the  actual
              completions to be inserted are not affected.  It can be provided
              in two ways. Firstly, if func-or-var begins with a $ it  defines
              a  variable,  or  if it begins with a left parenthesis a literal
              array, which contains the list.  A variable may have been set by
              a call to a function using the -K option.  Otherwise it contains
              the name of a function which will  be  executed  to  create  the
              list.   The  function  will  be  passed  as an argument list all
              matching completions, including prefixes and  suffixes  expanded
              in  full, and should set the array reply to the result.  In both
              cases, the display list will only be retrieved after a  complete
              list of matches has been created.

              Note that the returned list does not have to correspond, even in
              length, to the original set of matches, and may be passed  as  a
              scalar instead of an array.  No special formatting of characters
              is performed on the output in this case; in particular, newlines
              are  printed  literally  and if they appear output in columns is
              suppressed.

       -X explanation
              Print explanation when trying completion on the current  set  of
              options.  A  ‘%n’  in  this  string is replaced by the number of
              matches that were added for this explanation string.  The expla-
              nation  only  appears  if  completion was tried and there was no
              unique match, or when listing completions.  Explanation  strings
              will  be listed together with the matches of the group specified
              together with the -X option (using the -J or -V option). If  the
              same  explanation  string  is  given to multiple -X options, the
              string appears only once (for each  group)  and  the  number  of
              matches  shown  for  the ‘%n’ is the total number of all matches
              for each of these uses. In any case, the explanation string will
              only  be  shown  if  there  was at least one match added for the
              explanation string.

              The sequences  %B,  %b,  %S,  %s,  %U,  and  %u  specify  output
              attributes  (bold,  standout,  and underline) and %{...%} can be
              used to include literal escape sequences as in prompts.

       -Y explanation
              Identical to -X, except that  the  explanation  first  undergoes
              expansion  following  the  usual  rules  for  strings  in double
              quotes.  The expansion will be carried out after  any  functions
              are  called for the -K or -y options, allowing them to set vari-
              ables.

       -t continue
              The continue-string contains a character  that  specifies  which
              set of completion flags should be used next.  It is useful:

              (i)  With -T, or when trying a list of pattern completions, when
              compctl would usually continue with  ordinary  processing  after
              finding matches; this can be suppressed with ‘-tn’.

              (ii)  With  a  list of alternatives separated by +, when compctl
              would normally stop  when  one  of  the  alternatives  generates
              matches.   It  can be forced to consider the next set of comple-
              tions by adding ‘-t+’ to the flags of the alternative before the
              ‘+’.

              (iii)  In  an extended completion list (see below), when compctl
              would normally continue until a  set  of  conditions  succeeded,
              then use only the immediately following flags.  With ‘-t-’, com-
              pctl will continue trying extended completions  after  the  next
              ‘-’;  with  ‘-tx’  it  will  attempt completion with the default
              flags, in other words those before the ‘-x’.

       -J name
              This gives the name of the group the matches  should  be  placed
              in. Groups are listed and sorted separately; likewise, menu com-
              pletion will offer the matches in the groups  in  the  order  in
              which  the  groups  were defined. If no group name is explicitly
              given, the matches are stored in  a  group  named  default.  The
              first  time  a group name is encountered, a group with that name
              is created. After that all matches with the same group name  are
              stored in that group.

              This  can  be useful with non-exclusive alternative completions.
              For example, in

                     compctl -f -J files -t+ + -v -J variables foo

              both files and variables are possible completions,  as  the  -t+
              forces  both  sets  of alternatives before and after the + to be
              considered at once.  Because of the  -J  options,  however,  all
              files are listed before all variables.

       -V name
              Like  -J,  but  matches  within  the group will not be sorted in
              listings nor in menu completion. These unsorted groups are in  a
              different  name space from the sorted ones, so groups defined as
              -J files and -V files are distinct.

       -1     If given together with the -V  option,  makes  only  consecutive
              duplicates  in  the  group be removed. 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 duplicates
              be kept. Again, groups with and without this flag are in differ-
              ent name spaces.

       -M match-spec
              This defines additional  matching  control  specifications  that
              should  be  used  only  when testing words for the list of flags
              this flag appears in. The format of  the  match-spec  string  is
              described in zshcompwid.



ALTERNATIVE COMPLETION

       compctl [ -CDT ] options + options [ + ... ] [ + ] command ...

       The  form  with  ‘+’ specifies alternative options. Completion is tried
       with the options before the first ‘+’. If this produces no matches com-
       pletion  is  tried with the flags after the ‘+’ and so on. If there are
       no flags after the last ‘+’ and a match has not been found up  to  that
       point, default completion is tried.  If the list of flags contains a -t
       with a + character, the next list of flags is used even if the  current
       list produced matches.



EXTENDED COMPLETION

       compctl [ -CDT ] options -x pattern options - ... --
                [ command ... ]
       compctl [ -CDT ] options [ -x pattern options - ... -- ]
                [ + options [ -x ... -- ] ... [+] ] [ command ... ]

       The  form  with  ‘-x’  specifies  extended  completion for the commands
       given; as shown, it may be combined with alternative  completion  using
       ‘+’.  Each pattern is examined in turn; when a match is found, the cor-
       responding options, as described in the section ‘Option  Flags’  above,
       are  used to generate possible completions.  If no pattern matches, the
       options given before the -x are used.

       Note that each pattern should be supplied  as  a  single  argument  and
       should be quoted to prevent expansion of metacharacters by the shell.

       A  pattern  is built of sub-patterns separated by commas; it matches if
       at least one of these sub-patterns matches  (they  are  ‘or’ed).  These
       sub-patterns  are  in  turn composed of other sub-patterns separated by
       white spaces which match if all of the  sub-patterns  match  (they  are
       ‘and’ed).  An element of the sub-patterns is of the form ‘c[...][...]’,
       where the pairs of brackets may be repeated as often as necessary,  and
       matches  if  any  of the sets of brackets match (an ‘or’).  The example
       below makes this clearer.

       The elements may be any of the following:

       s[string]...
              Matches if the current word on the command line starts with  one
              of the strings given in brackets.  The string is not removed and
              is not part of the completion.

       S[string]...
              Like s[string] except that the string is part of the completion.

       p[from,to]...
              Matches  if the number of the current word is between one of the
              from and to pairs inclusive. The comma and to are  optional;  to
              defaults  to  the  same value as from.  The numbers may be nega-
              tive: -n refers to the n’th last word on the line.

       c[offset,string]...
              Matches if the string matches the word offset by offset from the
              current word position.  Usually offset will be negative.

       C[offset,pattern]...
              Like c but using pattern matching instead.

       w[index,string]...
              Matches  if  the  word  in position index is equal to the corre-
              sponding string.  Note that the word count  is  made  after  any
              alias expansion.

       W[index,pattern]...
              Like w but using pattern matching instead.

       n[index,string]...
              Matches if the current word contains string.  Anything up to and
              including the indexth occurrence of this string will not be con-
              sidered part of the completion, but the rest will.  index may be
              negative to count from the end: in most cases, index will  be  1
              or -1.  For example,

                     compctl -s users -x n[1,@] -k hosts -- talk

              will  usually  complete  usernames, but if you insert an @ after
              the name, names from the array hosts (assumed to  contain  host-
              names,  though  you  must  make the array yourself) will be com-
              pleted.  Other commands such as rcp can be handled similarly.

       N[index,string]...
              Like n except that the string  will  be  taken  as  a  character
              class.   Anything  up to and including the indexth occurrence of
              any of the characters in string will not be considered  part  of
              the completion.

       m[min,max]...
              Matches  if  the  total number of words lies between min and max
              inclusive.

       r[str1,str2]...
              Matches if the cursor is after a  word  with  prefix  str1.   If
              there  is also a word with prefix str2 on the command line after
              the one matched by str1 it matches only if the cursor is  before
              this  word. If the comma and str2 are omitted, it matches if the
              cursor is after a word with prefix str1.

       R[str1,str2]...
              Like r but using pattern matching instead.

       q[str]...
              Matches the word currently being completed is in  single  quotes
              and the str begins with the letter ‘s’, or if completion is done
              in double quotes and str starts with the letter ‘d’, or if  com-
              pletion is done in backticks and str starts with a ‘b’.



EXAMPLE

              compctl -u -x s[+] c[-1,-f],s[-f+] \
                -g ~/Mail/*(:t) - s[-f],c[-1,-f] -f -- mail

       This is to be interpreted as follows:

       If the current command is mail, then


              if ((the current word begins with + and the previous word is -f)
              or (the current word begins with -f+)), then complete the
              non-directory part (the ‘:t’ glob modifier) of files in the directory
              ~/Mail; else

              if the current word begins with -f or the previous word was -f, then
              complete any file; else

              complete user names.

ZSHMODULES(1)                                                    ZSHMODULES(1)




NAME

       zshmodules - zsh loadable modules


DESCRIPTION

       Some  optional  parts  of zsh are in modules, separate from the core of
       the shell.  Each of these modules may be linked  in  to  the  shell  at
       build  time, or can be dynamically linked while the shell is running if
       the installation supports this feature.  The modules that  are  bundled
       with the zsh distribution are:

       zsh/cap
              Builtins  for manipulating POSIX.1e (POSIX.6) capability (privi-
              lege) sets.

       zsh/clone
              A builtin that can clone a running shell onto another  terminal.

       zsh/compctl
              The compctl builtin for controlling completion.

       zsh/complete
              The basic completion code.

       zsh/complist
              Completion listing extensions.

       zsh/computil
              A  module  with  utility  builtins needed for the shell function
              based completion system.

       zsh/datetime
              Some date/time commands and parameters.

       zsh/deltochar
              A ZLE function duplicating EMACS’ zap-to-char.

       zsh/example
              An example of how to write a module.

       zsh/files
              Some basic file manipulation commands as builtins.

       zsh/mapfile
              Access to external files via a special associative array.

       zsh/mathfunc
              Standard scientific functions for use  in  mathematical  evalua-
              tions.

       zsh/parameter
              Access to internal hash tables via special associative arrays.

       zsh/pcre
              Interface to the PCRE library.

       zsh/sched
              A  builtin  that  provides a timed execution facility within the
              shell.

       zsh/net/socket
              Manipulation of Unix domain sockets

       zsh/stat
              A builtin command interface to the stat system call.

       zsh/system
              A builtin interface to various low-level system features.

       zsh/net/tcp
              Manipulation of TCP sockets

       zsh/termcap
              Interface to the termcap database.

       zsh/terminfo
              Interface to the terminfo database.

       zsh/zftp
              A builtin FTP client.

       zsh/zle
              The Zsh Line Editor, including the bindkey and vared builtins.

       zsh/zleparameter
              Access to internals of the Zsh Line Editor via parameters.

       zsh/zprof
              A module allowing profiling for shell functions.

       zsh/zpty
              A builtin for starting a command in a pseudo-terminal.

       zsh/zselect
              Block and return when file descriptors are ready.

       zsh/zutil
              Some utility builtins, e.g. the one for supporting configuration
              via styles.


THE ZSH/CAP MODULE

       The zsh/cap module is used for manipulating POSIX.1e (POSIX.6) capabil-
       ity sets.  If the operating system does not support this interface, the
       builtins  defined by this module will do nothing.  The builtins in this
       module are:

       cap [ capabilities ]
              Change the shell’s process  capability  sets  to  the  specified
              capabilities,  otherwise  display  the shell’s current capabili-
              ties.

       getcap filename ...
              This is a built-in implementation of the POSIX standard utility.
              It displays the capability sets on each specified filename.

       setcap capabilities filename ...
              This is a built-in implementation of the POSIX standard utility.
              It sets the capability sets on each specified  filename  to  the
              specified capabilities.


THE ZSH/CLONE MODULE

       The zsh/clone module makes available one builtin command:

       clone tty
              Creates  a forked instance of the current shell, attached to the
              specified tty.  In the new shell, the PID, PPID and TTY  special
              parameters  are changed appropriately.  $! is set to zero in the
              new shell, and to the new shell’s PID in the original shell.

              The return value of the builtin is zero in both shells  if  suc-
              cessful, and non-zero on error.

              The  target  of  clone  should be an unused terminal, such as an
              unused virtual console or a virtual terminal created by

              xterm -e sh -c ’trap : INT QUIT TSTP; tty;  while  :;  do  sleep
              100000000; done’

              Some  words  of  explanation are warranted about this long xterm
              command line: when doing clone on a pseudo-terminal, some  other
              session  ("session"  meant  as  a unix session group, or SID) is
              already owning the terminal. Hence the cloned zsh cannot acquire
              the pseudo-terminal as a controlling tty. That means two things:

              the job control signals will go to the sh-started-by-xterm  pro-
              cess
                    group  (that’s why we disable INT QUIT and TSTP with trap;
              otherwise
                    the while loop could get suspended or killed)

              the cloned shell will have job control disabled, and the job
                    control keys (control-C, control-\ and control-Z) will not
              work.

              This does not apply when cloning to an unused vc.

              Cloning  to an used (and unprepared) terminal will result in two
              processes reading simultaneously from the  same  terminal,  with
              input bytes going randomly to either process.

              clone  is  mostly  useful  as  a  shell built-in replacement for
              openvt.


THE ZSH/COMPCTL MODULE

       The zsh/compctl module makes available two builtin  commands.  compctl,
       is the old, deprecated way to control completions for ZLE.  See zshcom-
       pctl(1).   The  other  builtin  command,  compcall  can  be   used   in
       user-defined completion widgets, see zshcompwid(1).


THE ZSH/COMPLETE MODULE

       The  zsh/complete module makes available several builtin commands which
       can be used in user-defined completion widgets, see zshcompwid(1).


THE ZSH/COMPLIST MODULE

       The zsh/complist module offers three extensions to completion listings:
       the  ability to highlight matches in such a list, the ability to scroll
       through long lists and a different style of menu completion.


   Colored completion listings
       Whenever one of the parameters ZLS_COLORS or ZLS_COLOURS is set and the
       zsh/complist  module  is  loaded  or  linked into the shell, completion
       lists will be colored.  Note, however, that complist will not automati-
       cally  be loaded if it is not linked in:  on systems with dynamic load-
       ing, ‘zmodload zsh/complist’ is required.

       The parameters ZLS_COLORS and  ZLS_COLOURS  describe  how  matches  are
       highlighted.  To turn on highlighting an empty value suffices, in which
       case all the default values given below will be used.   The  format  of
       the value of these parameters is the same as used by the GNU version of
       the ls command: a colon-separated list of specifications  of  the  form
       ‘name=value’.   The  name  may be one of the following strings, most of
       which specify file types for which the value will be used.  The strings
       and their default values are:

       no 0   for  normal  text  (i.e.  when displaying something other than a
              matched file)

       fi 0   for regular files

       di 32  for directories

       ln 36  for symbolic links

       pi 31  for named pipes (FIFOs)

       so 33  for sockets

       bd 44;37
              for block devices

       cd 44;37
              for character devices

       ex 35  for executable files

       mi none
              for a non-existent file (default is the value defined for fi)

       lc \e[ for the left code (see below)

       rc m   for the right code

       tc 0   for the character indicating the file type  printed after  file-
              names if the LIST_TYPES option is set

       sp 0   for the spaces printed after matches to align the next column

       ec none
              for the end code

       Apart  from  these strings, the name may also be an asterisk (‘*’) fol-
       lowed by any string. The value given for such a string will be used for
       all  files  whose  name  ends with the string.  The name may also be an
       equals sign (‘=’) followed by a pattern.  The value given for this pat-
       tern  will  be  used for all matches (not just filenames) whose display
       string are matched by the pattern.  Definitions for both of these  take
       precedence over the values defined for file types and the form with the
       leading asterisk takes precedence over the form with the leading  equal
       sign.

       The  last  form also allows different parts of the displayed strings to
       be colored differently.  For this, the pattern has to  use  the  ‘(#b)’
       globbing  flag  and  pairs  of parentheses surrounding the parts of the
       strings that are to be colored differently.  In this case the value may
       consist  of  more  than  one  color code separated by equal signs.  The
       first code will be used for all parts for which  no  explicit  code  is
       specified and the following codes will be used for the parts matched by
       the  sub-patterns  in  parentheses.   For  example,  the  specification
       ‘=(#b)(?)*(?)=0=3=7’  will  be  used for all matches which are at least
       two characters long and will use the code ‘3’ for the first  character,
       ‘7’ for the last character and ‘0’ for the rest.

       All  three  forms  of name may be preceded by a pattern in parentheses.
       If this is given, the value will be used only  for  matches  in  groups
       whose  names  are matched by the pattern given in the parentheses.  For
       example, ‘(g*)m*=43’ highlights  all  matches  beginning  with  ‘m’  in
       groups  whose names  begin with ‘g’ using the color code ‘43’.  In case
       of the ‘lc’, ‘rc’, and ‘ec’ codes, the group pattern is ignored.

       Note also that all patterns are tried in the order in which they appear
       in  the parameter value until the first one matches which is then used.

       When printing a match, the code prints the value of lc, the  value  for
       the  file-type or the last matching specification with a ‘*’, the value
       of rc, the string to display for the match itself, and then  the  value
       of  ec  if that is defined or the values of lc, no, and rc if ec is not
       defined.

       The default values are ISO 6429 (ANSI) compliant and  can  be  used  on
       vt100 compatible terminals such as xterms.  On monochrome terminals the
       default values will have no visible effect.  The colors  function  from
       the  contribution  can be used to get associative arrays containing the
       codes for ANSI terminals (see the section ‘Other Functions’ in  zshcon-
       trib(1)).   For  example,  after  loading  colors, one could use ‘$col-
       ors[red]’  to  get  the  code  for  foreground  color  red  and  ‘$col-
       ors[bg-green]’ for the code for background color green.

       If  the completion system invoked by compinit is used, these parameters
       should not be set directly because the  system  controls  them  itself.
       Instead, the list-colors style should be used (see the section ‘Comple-
       tion System Configuration’ in zshcompsys(1)).


   Scrolling in completion listings
       To enable scrolling through a completion list, the LISTPROMPT parameter
       must  be set.  Its value will be used as the prompt; if it is the empty
       string, a default prompt will be used.  The value may  contain  escapes
       of  the  form  ‘%x’.   It  supports the escapes ‘%B’, ‘%b’, ‘%S’, ‘%s’,
       ‘%U’, ‘%u’ and ‘%{...%}’ used also in shell prompts as  well  as  three
       pairs of additional sequences: a ‘%l’ or ‘%L’ is replaced by the number
       of the last line shown and the total number of lines in the form  ‘num-
       ber/total’;  a  ‘%m’  or  ‘%M’  is replaced with the number of the last
       match shown and the total number  of  matches;  and  ‘%p’  or  ‘%P’  is
       replaced  with  ‘Top’, ‘Bottom’ or the position of the first line shown
       in percent of the total number of  lines,  respectively.   In  each  of
       these  cases the form with the uppercase letter will be replaced with a
       string of fixed width, padded to the right with spaces, while the  low-
       ercase form will not be padded.

       If the parameter LISTPROMPT is set, the completion code will not ask if
       the list should be shown.  Instead it immediately starts displaying the
       list,  stopping  after  the  first screenful, showing the prompt at the
       bottom, waiting for a  keypress  after  temporarily  switching  to  the
       listscroll  keymap.   Some  of the zle functions have a special meaning
       while scrolling lists:

       send-break
              stops listing discarding the key pressed

       accept-line, down-history, down-line-or-history
       down-line-or-search, vi-down-line-or-history
              scrolls forward one line

       complete-word, menu-complete, expand-or-complete
       expand-or-complete-prefix, menu-complete-or-expand
              scrolls forward one screenful

       Every other character stops listing and immediately processes  the  key
       as  usual.   Any key that is not bound in the listscroll keymap or that
       is bound  to  undefined-key  is  looked  up  in  the  keymap  currently
       selected.

       As for the ZLS_COLORS and ZLS_COLOURS parameters, LISTPROMPT should not
       be set directly when using the shell function based completion  system.
       Instead, the list-prompt style should be used.


   Menu selection
       The  zsh/complist  module also offers an alternative style of selecting
       matches from a list, called menu selection, which can be  used  if  the
       shell is set up to return to the last prompt after showing a completion
       list (see the ALWAYS_LAST_PROMPT option in zshoptions(1)).  It  can  be
       invoked  directly  by  the  widget  menu-select  defined by the module.
       Alternatively, the parameter MENUSELECT can be set to an integer, which
       gives  the  minimum  number of matches that must be present before menu
       selection is automatically turned on.  This second method requires that
       menu  completion  be  started,  either  directly  from a widget such as
       menu-complete, or due to one of the options MENU_COMPLETE or  AUTO_MENU
       being  set.  If MENUSELECT is set, but is 0, 1 or empty, menu selection
       will always be started during an ambiguous menu completion.

       When using the completion system based on shell functions, the  MENUSE-
       LECT  parameter should not be used (like the ZLS_COLORS and ZLS_COLOURS
       parameters described above).  Instead, the menu style  should  be  used
       with the select=... keyword.

       After  menu  selection is started, the matches will be listed. If there
       are more matches than fit on the screen, only the  first  screenful  is
       shown.   The  matches  to  insert into the command line can be selected
       from this list.  In the list one match is highlighted using  the  value
       for ma from the ZLS_COLORS or ZLS_COLOURS parameter.  The default value
       for this is ‘7’ which forces the selected match to be highlighted using
       standout  mode  on  a vt100-compatible terminal.  If neither ZLS_COLORS
       nor ZLS_COLOURS is set, the same terminal control sequence as  for  the
       ‘%S’ escape in prompts is used.

       If  there  are  more  matches  than fit on the screen and the parameter
       MENUPROMPT is set, its value will be shown below the matches.  It  sup-
       ports  the  same  escape sequences as LISTPROMPT, but the number of the
       match or line shown will be that of the one where the mark  is  placed.
       If its value is the empty string, a default prompt will be used.

       The  MENUSCROLL  parameter  can  be  used  to  specify  how the list is
       scrolled.  If the parameter is unset, this is done line by line, if  it
       is  set to ‘0’ (zero), the list will scroll half the number of lines of
       the screen.  If the value is positive, it gives the number of lines  to
       scroll  and  if it is negative, the list will be scrolled the number of
       lines of the screen minus the (absolute) value.

       As for the ZLS_COLORS, ZLS_COLOURS and LISTPROMPT  parameters,  neither
       MENUPROMPT  nor  MENUSCROLL should be set directly when using the shell
       function based  completion  system.   Instead,  the  select-prompt  and
       select-scroll styles should be used.

       The completion code sometimes decides not to show all of the matches in
       the list.  These hidden matches are either matches for which  the  com-
       pletion  function  which  added them explicitly requested that they not
       appear in the list (using the -n option of the compadd builtin command)
       or  they  are  matches  which  duplicate  a  string already in the list
       (because they differ only in things like prefixes or suffixes that  are
       not  displayed).   In  the  list used for menu selection, however, even
       these matches are shown so that it is  possible  to  select  them.   To
       highlight such matches the hi and du capabilities in the ZLS_COLORS and
       ZLS_COLOURS parameters are supported for hidden matches  of  the  first
       and second kind, respectively.

       Selecting matches is done by moving the mark around using the zle move-
       ment functions.  When not all matches can be shown on the screen at the
       same  time,  the  list will scroll up and down when crossing the top or
       bottom line.  The following zle functions have special  meaning  during
       menu selection:

       accept-line
              accepts the current match and leaves menu selection

       send-break
              leaves  menu selection and restores the previous contents of the
              command line

       redisplay, clear-screen
              execute their normal function without leaving menu selection

       accept-and-hold, accept-and-menu-complete
              accept the  currently  inserted  match  and  continue  selection
              allowing to select the next match to insert into the line

       accept-and-infer-next-history
              accepts  the  current  match and then tries completion with menu
              selection again;  in the case of files this allows one to select
              a directory and immediately attempt to complete files in it;  if
              there are no matches, a message is shown and one can use undo to
              go  back  to  completion  on the previous level, every other key
              leaves menu selection (including the other zle  functions  which
              are otherwise special during menu selection)

       undo   removes matches inserted during the menu selection by one of the
              three functions before

       down-history, down-line-or-history
       vi-down-line-or-history,  down-line-or-search
              moves the mark one line down

       up-history, up-line-or-history
       vi-up-line-or-history, up-line-or-search
              moves the mark one line up

       forward-char, vi-forward-char
              moves the mark one column right

       backward-char, vi-backward-char
              moves the mark one column left

       forward-word, vi-forward-word
       vi-forward-word-end, emacs-forward-word
              moves the mark one screenful down

       backward-word, vi-backward-word, emacs-backward-word
              moves the mark one screenful up

       vi-forward-blank-word, vi-forward-blank-word-end
              moves the mark to the first line of the next group of matches

       vi-backward-blank-word
              moves the mark to the last line of the previous group of matches

       beginning-of-history
              moves the mark to the first line

       end-of-history
              moves the mark to the last line

       beginning-of-buffer-or-history, beginning-of-line
       beginning-of-line-hist, vi-beginning-of-line
              moves the mark to the leftmost column

       end-of-buffer-or-history, end-of-line
       end-of-line-hist, vi-end-of-line
              moves the mark to the rightmost column

       complete-word, menu-complete, expand-or-complete
       expand-or-complete-prefix, menu-expand-or-complete
              moves the mark to the next match

       reverse-menu-complete
              moves the mark to the previous match

       vi-insert
              this toggles between normal and interactive mode; in interactive
              mode the keys bound to self-insert and self-insert-unmeta insert
              into  the  command  line  as  in normal editing mode but without
              leaving menu selection; after each character completion is tried
              again  and the list changes to contain only the new matches; the
              completion  widgets  make  the  longest  unambiguous  string  be
              inserted  in  the command line and undo and backward-delete-char
              go back to the previous set of matches

       history-incremental-search-forward,
              history-incremental-search-backward  this   starts   incremental
              searches  in  the  list  of completions displayed; in this mode,
              accept-line only leaves incremental search, going  back  to  the
              normal menu selection mode

       All movement functions wrap around at the edges; any other zle function
       not listed leaves menu selection and executes  that  function.   It  is
       possible  to  make  widgets  in the above list do the same by using the
       form of the widget with a  ‘.’  in  front.   For  example,  the  widget
       ‘.accept-line’  has  the effect of leaving menu selection and accepting
       the entire command line.

       During this selection the widget uses the keymap menuselect.   Any  key
       that is not defined in this keymap or that is bound to undefined-key is
       looked up in the keymap currently selected.  This  is  used  to  ensure
       that  the  most important keys used during selection (namely the cursor
       keys, return, and TAB) have sensible defaults.  However,  keys  in  the
       menuselect  keymap  can  be modified directly using the bindkey builtin
       command (see zshmodules(1)). For example, to make the return key  leave
       menu selection without accepting the match currently selected one could
       call

              bindkey -M menuselect ^M send-break

       after loading the zsh/complist module.


THE ZSH/COMPUTIL MODULE

       The zsh/computil module adds several builtin commands that are used  by
       some  of  the  completion  functions  in the completion system based on
       shell functions (see  zshcompsys(1)  ).   Except  for  compquote  these
       builtin  commands  are  very  specialised and thus not very interesting
       when writing your own completion functions.  In summary, these  builtin
       commands are:

       comparguments
              This  is  used by the _arguments function to do the argument and
              command line parsing.  Like compdescribe it has an option -i  to
              do  the  parsing  and initialize some internal state and various
              options to access the state information to decide what should be
              completed.

       compdescribe
              This is used by the _describe function to build the displays for
              the matches and to get the strings to add as matches with  their
              options.   On  the first call one of the options -i or -I should
              be supplied as the first argument.  In the first  case,  display
              strings  without the descriptions will be generated, in the sec-
              ond case, the string used to separate  the  matches  from  their
              descriptions  must  be  given  as  the  second  argument and the
              descriptions (if any) will be shown.  All  other  arguments  are
              like the definition arguments to _describe itself.

              Once  compdescribe  has been called with either the -i or the -I
              option, it can be repeatedly called with the -g option  and  the
              names  of  five arrays as its arguments.  This will step through
              the different sets of matches and store the options in the first
              array,  the strings with descriptions in the second, the matches
              for these in the third, the strings without descriptions in  the
              fourth,  and the matches for them in the fifth array.  These are
              then directly given to compadd to register the matches with  the
              completion code.

       compfiles
              Used  by  the _path_files function to optimize complex recursive
              filename generation (globbing).  It does three things.  With the
              -p  and -P options it builds the glob patterns to use, including
              the paths already handled and trying to  optimize  the  patterns
              with  respect  to  the  prefix  and suffix from the line and the
              match specification currently used.   The  -i  option  does  the
              directory  tests  for the ignore-parents style and the -r option
              tests if a component for some of the matches are  equal  to  the
              string  on  the  line  and  removes all other matches if that is
              true.

       compgroups
              Used by the _tags function to implement  the  internals  of  the
              group-order  style.   This  only takes its arguments as names of
              completion groups and creates the groups for it (all six  types:
              sorted  and  unsorted,  both  without  removing duplicates, with
              removing all duplicates and  with  removing  consecutive  dupli-
              cates).

       compquote [ -p ] names ...
              There  may be reasons to write completion functions that have to
              add the matches using the -Q option to compadd and perform quot-
              ing  themselves.  Instead of interpreting the first character of
              the all_quotes key of  the  compstate  special  association  and
              using  the  q  flag  for  parameter expansions, one can use this
              builtin command.  The arguments are the names of scalar or array
              parameters  and  the  values  of  these parameters are quoted as
              needed for the innermost quoting level.  If  the  -p  option  is
              given,  quoting  is  done  as if there is some prefix before the
              values of the parameters, so that a leading equal sign will  not
              be quoted.

              The return value is non-zero in case of an error and zero other-
              wise.

       comptags
       comptry
              These implement the internals of the tags mechanism.

       compvalues
              Like comparguments, but for the _values function.


THE ZSH/DATETIME MODULE

       The zsh/datetime module makes available one builtin command:

       strftime [ -s scalar ] format epochtime
              Output the date denoted by epochtime in the format specified.

              If -s scalar is given, assign the  date  to  scalar  instead  of
              printing it.

       The zsh/datetime module makes available one parameter:

       EPOCHSECONDS
              An  integer  value  representing the number of seconds since the
              epoch.


THE ZSH/DELTOCHAR MODULE

       The zsh/deltochar module makes available two ZLE functions:

       delete-to-char
              Read a character from the keyboard, and delete from  the  cursor
              position  up to and including the next (or, with repeat count n,
              the nth) instance of that  character.   Negative  repeat  counts
              mean delete backwards.

       zap-to-char
              This  behaves  like delete-to-char, except that the final occur-
              rence of the character itself is not deleted.


THE ZSH/EXAMPLE MODULE

       The zsh/example module makes available one builtin command:

       example [ -flags ] [ args ... ]
              Displays the flags and arguments it is invoked with.

       The purpose of the module is to serve as an example of how to  write  a
       module.


THE ZSH/FILES MODULE

       The   zsh/files  module  makes  some  standard  commands  available  as
       builtins:

       chgrp [ -Rs ] group filename ...
              Changes group of files specified.  This is equivalent  to  chown
              with a user-spec argument of ‘:group’.

       chown [ -Rs ] user-spec filename ...
              Changes ownership and group of files specified.

              The user-spec can be in four forms:

              user   change owner to user; do not change group
              user:: change owner to user; do not change group
              user:  change  owner  to  user;  change  group to user’s primary
                     group
              user:group
                     change owner to user; change group to group
              :group do not change owner; change group to group

              In each case, the ‘:’ may instead be a ‘.’.  The rule is that if
              there  is a ‘:’ then the separator is ‘:’, otherwise if there is
              a ‘.’ then the separator is ‘.’, otherwise there is  no  separa-
              tor.

              Each  of user and group may be either a username (or group name,
              as appropriate) or a decimal user ID (group ID).  Interpretation
              as  a name takes precedence, if there is an all-numeric username
              (or group name).

              The -R option causes chown to recursively descend into  directo-
              ries, changing the ownership of all files in the directory after
              changing the ownership of the directory itself.

              The -s option is a zsh extension  to  chown  functionality.   It
              enables  paranoid behaviour, intended to avoid security problems
              involving a chown being tricked into affecting files other  than
              the  ones intended.  It will refuse to follow symbolic links, so
              that (for example) ‘‘chown luser /tmp/foo/passwd’’  can’t  acci-
              dentally  chown  /etc/passwd if /tmp/foo happens to be a link to
              /etc.  It will also check where it is after leaving directories,
              so  that a recursive chown of a deep directory tree can’t end up
              recursively chowning /usr as a result of directories being moved
              up the tree.

       ln [ -dfis ] filename dest
       ln [ -dfis ] filename ... dir
              Creates  hard (or, with -s, symbolic) links.  In the first form,
              the specified destination is created, as a link to the specified
              filename.  In the second form, each of the filenames is taken in
              turn, and linked to a pathname in the specified  directory  that
              has the same last pathname component.

              Normally,  ln  will not attempt to create hard links to directo-
              ries.  This check can be overridden using the -d option.   Typi-
              cally  only the super-user can actually succeed in creating hard
              links to directories.  This does not apply to symbolic links  in
              any case.

              By  default, existing files cannot be replaced by links.  The -i
              option causes the user to be queried  about  replacing  existing
              files.   The  -f  option  causes  existing  files to be silently
              deleted, without querying.  -f takes precedence.

       mkdir [ -p ] [ -m mode ] dir ...
              Creates directories.  With the -p  option,  non-existing  parent
              directories are first created if necessary, and there will be no
              complaint if the directory already exists.  The -m option can be
              used  to  specify  (in  octal) a set of file permissions for the
              created directories, otherwise mode 777 modified by the  current
              umask (see umask(2)) is used.

       mv [ -fi ] filename dest
       mv [ -fi ] filename ... dir
              Moves files.  In the first form, the specified filename is moved
              to the specified destination.  In the second form, each  of  the
              filenames is taken in turn, and moved to a pathname in the spec-
              ified directory that has the same last pathname component.

              By default, the user will be queried before replacing  any  file
              that  the  user  cannot  write  to,  but  writable files will be
              silently removed.  The -i option causes the user to  be  queried
              about  replacing  any  existing files.  The -f option causes any
              existing files to be silently  deleted,  without  querying.   -f
              takes precedence.

              Note  that this mv will not move files across devices.  Histori-
              cal versions of mv, when actual  renaming  is  impossible,  fall
              back  on  copying  and  removing  files;  if  this  behaviour is
              desired, use cp and rm manually.  This may change  in  a  future
              version.

       rm [ -dfirs ] filename ...
              Removes files and directories specified.

              Normally,  rm  will  not  remove directories (except with the -r
              option).  The -d option causes rm to  try  removing  directories
              with  unlink  (see  unlink(2)),  the same method used for files.
              Typically only the super-user can actually succeed in  unlinking
              directories in this way.  -d takes precedence over -r.

              By  default,  the  user will be queried before removing any file
              that the user cannot  write  to,  but  writable  files  will  be
              silently  removed.   The -i option causes the user to be queried
              about removing any files.  The -f  option  causes  files  to  be
              silently  deleted,  without  querying,  and suppresses all error
              indications.  -f takes precedence.

              The -r option causes rm to recursively descend into directories,
              deleting  all  files in the directory before removing the direc-
              tory with the rmdir system call (see rmdir(2)).

              The -s option is  a  zsh  extension  to  rm  functionality.   It
              enables  paranoid  behaviour,  intended to avoid common security
              problems involving a root-run rm  being  tricked  into  removing
              files  other  than  the ones intended.  It will refuse to follow
              symbolic links, so that  (for  example)  ‘‘rm  /tmp/foo/passwd’’
              can’t  accidentally remove /etc/passwd if /tmp/foo happens to be
              a link to /etc.  It will also check where it  is  after  leaving
              directories,  so  that  a  recursive removal of a deep directory
              tree can’t end up recursively  removing  /usr  as  a  result  of
              directories being moved up the tree.

       rmdir dir ...
              Removes empty directories specified.

       sync   Calls  the  system  call  of  the same name (see sync(2)), which
              flushes dirty buffers to disk.  It might return before  the  I/O
              has actually been completed.


THE ZSH/MAPFILE MODULE

       The zsh/mapfile module provides one special associative array parameter
       of the same name.

       mapfile
              This associative array takes as keys the  names  of  files;  the
              resulting  value  is  the  content  of  the  file.  The value is
              treated identically to any other text coming from  a  parameter.
              The  value  may  also  be assigned to, in which case the file in
              question is written (whether or not it originally  existed);  or
              an element may be unset, which will delete the file in question.
              For example, ‘vared mapfile[myfile]’ works as expected,  editing
              the file ‘myfile’.

              When the array is accessed as a whole, the keys are the names of
              files in the current directory, and the  values  are  empty  (to
              save  a  huge  overhead  in memory).  Thus ${(k)mapfile} has the
              same affect as the glob operator  *(D),  since  files  beginning
              with a dot are not special.  Care must be taken with expressions
              such as rm ${(k)mapfile}, which will delete every  file  in  the
              current directory without the usual ‘rm *’ test.

              The parameter mapfile may be made read-only; in that case, files
              referenced may not be written or deleted.


   Limitations
       Although reading and writing of the file  in  question  is  efficiently
       handled,  zsh’s  internal memory management may be arbitrarily baroque.
       Thus it should not automatically be assumed that use of mapfile  repre-
       sents  a gain in efficiency over use of other mechanisms.  Note in par-
       ticular that the whole contents of the file will always  reside  physi-
       cally in memory when accessed (possibly multiple times, due to standard
       parameter substitution operations).  In particular, this means handling
       of  sufficiently  long files (greater than the machine’s swap space, or
       than the range of the pointer type) will be incorrect.

       No errors are printed  or  flagged  for  non-existent,  unreadable,  or
       unwritable  files,  as  the parameter mechanism is too low in the shell
       execution hierarchy to make this convenient.

       It is unfortunate that the mechanism for loading modules does  not  yet
       allow  the  user to specify the name of the shell parameter to be given
       the special behaviour.


THE ZSH/MATHFUNC MODULE

       The zsh/mathfunc module provides standard  mathematical  functions  for
       use when evaluating mathematical formulae.  The syntax agrees with nor-
       mal C and FORTRAN conventions, for example,

              (( f = sin(0.3) ))

       assigns the sine of 0.3 to the parameter f.

       Most functions take floating point  arguments  and  return  a  floating
       point  value.   However,  any  necessary conversions from or to integer
       type will be performed automatically by the  shell.   Apart  from  atan
       with  a second argument and the abs, int and float functions, all func-
       tions behave as noted in the manual page for the corresponding C  func-
       tion,  except that any arguments out of range for the function in ques-
       tion will be detected by the shell and an error reported.

       The following functions take a single floating  point  argument:  acos,
       acosh, asin, asinh, atan, atanh, cbrt, ceil, cos, cosh, erf, erfc, exp,
       expm1, fabs, floor, gamma, j0, j1, lgamma,  log,  log10,  log1p,  logb,
       sin,  sinh,  sqrt, tan, tanh, y0, y1.  The atan function can optionally
       take a second argument, in which case it behaves like  the  C  function
       atan2.   The ilogb function takes a single floating point argument, but
       returns an integer.

       The function signgam takes no arguments, and returns an integer,  which
       is  the  C  variable  of the same name, as described in gamma(3).  Note
       that it is therefore only useful immediately after a call to  gamma  or
       lgamma.   Note also that ‘signgam()’ and ‘signgam’ are distinct expres-
       sions.

       The following functions take two floating  point  arguments:  copysign,
       fmod, hypot, nextafter.

       The  following take an integer first argument and a floating point sec-
       ond argument: jn, yn.

       The following take a floating point first argument and an integer  sec-
       ond argument: ldexp, scalb.

       The  function  abs does not convert the type of its single argument; it
       returns the absolute value of either a  floating  point  number  or  an
       integer.   The  functions  float and int convert their arguments into a
       floating point or integer value (by truncation) respectively.

       Note that the C pow function is available in ordinary  math  evaluation
       as the ‘**’ operator and is not provided here.

       The  function rand48 is available if your system’s mathematical library
       has the function erand48(3).  It returns a pseudo-random floating point
       number between 0 and 1.  It takes a single string optional argument.

       If  the  argument is not present, the random number seed is initialised
       by three calls to the rand(3) function --- this produces the same  ran-
       dom numbers as the next three values of $RANDOM.

       If  the  argument  is  present, it gives the name of a scalar parameter
       where the current random number seed will  be  stored.   On  the  first
       call,  the  value  must contain at least twelve hexadecimal digits (the
       remainder of the string is ignored), or the seed will be initialised in
       the  same  manner as for a call to rand48 with no argument.  Subsequent
       calls to rand48(param) will then maintain the  seed  in  the  parameter
       param as a string of twelve hexadecimal digits, with no base signifier.
       The random number sequences for  different  parameters  are  completely
       independent, and are also independent from that used by calls to rand48
       with no argument.

       For example, consider

              print $(( rand48(seed) ))
              print $(( rand48() ))
              print $(( rand48(seed) ))

       Assuming $seed does not exist, it will  be  initialised  by  the  first
       call.   In the second call, the default seed is initialised; note, how-
       ever, that because of the properties of rand() there is  a  correlation
       between  the seeds used for the two initialisations, so for more secure
       uses, you should generate  your  own  12-byte  seed.   The  third  call
       returns  to the same sequence of random numbers used in the first call,
       unaffected by the intervening rand48().


THE ZSH/PARAMETER MODULE

       The zsh/parameter module gives access to  some  of  the  internal  hash
       tables used by the shell by defining some special parameters.

       options
              The keys for this associative array are the names of the options
              that can  be  set  and  unset  using  the  setopt  and  unsetopt
              builtins.  The  value of each key is either the string on if the
              option is currently set, or the string  off  if  the  option  is
              unset.  Setting a key to one of these strings is like setting or
              unsetting the option, respectively.  Unsetting  a  key  in  this
              array is like setting it to the value off.

       commands
              This  array gives access to the command hash table. The keys are
              the names of external commands, the values are the pathnames  of
              the  files  that  would  be  executed  when the command would be
              invoked. Setting a key in this array defines a new entry in this
              table  in the same way as with the hash builtin. Unsetting a key
              as in ‘unset "commands[foo]"’ removes the entry  for  the  given
              key from the command hash table.

       functions
              This  associative array maps names of enabled functions to their
              definitions. Setting a key in it is  like  defining  a  function
              with  the name given by the key and the body given by the value.
              Unsetting a key removes the definition for the function named by
              the key.

       dis_functions
              Like functions but for disabled functions.

       builtins
              This  associative array gives information about the builtin com-
              mands currently enabled. The keys are the names of  the  builtin
              commands  and the values are either ‘undefined’ for builtin com-
              mands that will automatically be loaded from a module if invoked
              or ‘defined’ for builtin commands that are already loaded.

       dis_builtins
              Like builtins but for disabled builtin commands.

       reswords
              This array contains the enabled reserved words.

       dis_reswords
              Like reswords but for disabled reserved words.

       aliases
              This  maps the names of the regular aliases currently enabled to
              their expansions.

       dis_aliases
              Like aliases but for disabled regular aliases.

       galiases
              Like aliases, but for global aliases.

       dis_galiases
              Like galiases but for disabled global aliases.

       saliases
              Like raliases, but for suffix aliases.

       dis_saliases
              Like saliases but for disabled suffix aliases.

       parameters
              The keys in this associative array are the names of the  parame-
              ters  currently  defined.  The values are strings describing the
              type of the parameter, in the same format used by the t  parame-
              ter  flag,  see  zshexpn(1) .  Setting or unsetting keys in this
              array is not possible.

       modules
              An associative array giving information about modules. The  keys
              are   the   names  of  the  modules  loaded,  registered  to  be
              autoloaded, or aliased. The value says  which  state  the  named
              module  is  in and is one of the strings ‘loaded’, ‘autoloaded’,
              or ‘alias:name’, where name is the name the  module  is  aliased
              to.

              Setting or unsetting keys in this array is not possible.

       dirstack
              A normal array holding the elements of the directory stack. Note
              that the output of the dirs builtin command  includes  one  more
              directory, the current working directory.

       history
              This  associative  array  maps history event numbers to the full
              history lines.

       historywords
              A special array containing the words stored in the history.

       jobdirs
              This associative array maps job numbers to the directories  from
              which  the  job was started (which may not be the current direc-
              tory of the job).

       jobtexts
              This associative array maps job numbers to the texts of the com-
              mand lines that were used to start the jobs.

       jobstates
              This associative array gives information about the states of the
              jobs currently known. The keys are the job numbers and the  val-
              ues  are  strings of the form ‘job-state:mark:pid=state...’. The
              job-state gives the state the whole job is currently in, one  of
              ‘running’,  ‘suspended’, or ‘done’. The mark is ‘+’ for the cur-
              rent job, ‘-’ for the previous job and empty otherwise. This  is
              followed  by  one  ‘pid=state’ for every process in the job. The
              pids are, of course, the process IDs and the state describes the
              state of that process.

       nameddirs
              This  associative  array  maps the names of named directories to
              the pathnames they stand for.

       userdirs
              This associative array maps user names to the pathnames of their
              home directories.

       funcstack
              This  array  contains the names of the functions currently being
              executed. The first element is the name of  the  function  using
              the parameter.


THE ZSH/PCRE MODULE

       The zsh/pcre module makes some commands available as builtins:

       pcre_compile [ -aimx ] PCRE
              Compiles a perl-compatible regular expression.

              Option -a will force the pattern to be anchored.  Option -i will
              compile a case-insensitive pattern.  Option -m  will  compile  a
              multi-line  pattern; that is, ^ and $ will match newlines within
              the pattern.   Option  -x  will  compile  an  extended  pattern,
              wherein whitespace and # comments are ignored.

       pcre_study
              Studies  the previously-compiled PCRE which may result in faster
              matching.

       pcre_match [ -a arr ] string
              Returns successfully if string matches  the  previously-compiled
              PCRE.

              If   the  expression  captures  substrings  within  parentheses,
              pcre_match will set the array $match to those substrings, unless
              the -a option is given, in which case it will set the array arr.

       The zsh/pcre module makes available the following test condition:
       expr -pcre-match pcre
              Matches a string against a perl-compatible regular expression.

              For example,

              [[ "$text" -pcre-match ^d+$ ]] && print text  variable  contains
              only "d’s".


THE ZSH/SCHED MODULE

       The zsh/sched module makes available one builtin command:

       sched [+]hh:mm command ...
       sched [ -item ]
              Make an entry in the scheduled list of commands to execute.  The
              time may be specified in either absolute or relative time.  With
              no  arguments,  prints the list of scheduled commands.  With the
              argument ‘-item’, removes the given item from the list.


THE ZSH/NET/SOCKET MODULE

       The zsh/net/socket module makes available one builtin command:

       zsocket [ -altv ] [ -d fd ] [ args ]
              zsocket is implemented as a builtin to allow full use  of  shell
              command line editing, file I/O, and job control mechanisms.


   Outbound Connections
       zsocket [ -v ] [ -d fd ] filename
              Open a new Unix domain connection to filename.  The shell param-
              eter REPLY will be set to the file  descriptor  associated  with
              that  connection.   Currently,  only stream connections are sup-
              ported.

              If -d is specified, its argument will be  taken  as  the  target
              file descriptor for the connection.

              In order to elicit more verbose output, use -v.


   Inbound Connections
       zsocket -l [ -v ] [ -d fd ] filename
              zsocket  -l will open a socket listening on filename.  The shell
              parameter REPLY will be set to the  file  descriptor  associated
              with that listener.

              If  -d  is  specified,  its argument will be taken as the target
              file descriptor for the connection.

              In order to elicit more verbose output, use -v.

       zsocket -a [ -tv ] [ -d targetfd ] listenfd
              zsocket -a will accept an  incoming  connection  to  the  socket
              associated with listenfd.  The shell parameter REPLY will be set
              to the file descriptor associated with the inbound connection.

              If -d is specified, its argument will be  taken  as  the  target
              file descriptor for the connection.

              If  -t  is specified, zsocket will return if no incoming connec-
              tion is pending.  Otherwise it will wait for one.

              In order to elicit more verbose output, use -v.


THE ZSH/STAT MODULE

       The zsh/stat module makes available one builtin command:

       stat [ -gnNolLtTrs ] [ -f fd ] [ -H hash ] [ -A array ] [ -F  fmt  ]  [
       +element ] [ file ... ]
              The command acts as a front end to the  stat  system  call  (see
              stat(2)).   If the stat call fails, the appropriate system error
              message printed and status 1 is returned.  The fields of  struct
              stat  give  information about the files provided as arguments to
              the command.  In addition to those available from the stat call,
              an extra element ‘link’ is provided.  These elements are:

              device The number of the device on which the file resides.

              inode  The  unique  number  of  the file on this device (‘inode’
                     number).

              mode   The mode of the file; that is, the file’s type and access
                     permissions.   With  the -s option, this will be returned
                     as a string corresponding to the first column in the dis-
                     play of the ls -l command.

              nlink  The number of hard links to the file.

              uid    The  user  ID  of  the  owner  of  the file.  With the -s
                     option, this is displayed as a user name.

              gid    The group ID of the file.  With the -s  option,  this  is
                     displayed as a group name.

              rdev   The  raw  device number.  This is only useful for special
                     devices.

              size   The size of the file in bytes.

              atime
              mtime
              ctime  The last access, modification and inode change  times  of
                     the  file,  respectively,  as the number of seconds since
                     midnight GMT on 1st January, 1970.  With the  -s  option,
                     these are printed as strings for the local time zone; the
                     format can be altered with the -F option, and with the -g
                     option the times are in GMT.

              blksize
                     The number of bytes in one allocation block on the device
                     on which the file resides.

              block  The number of disk blocks used by the file.

              link   If the file is a link and the -L  option  is  in  effect,
                     this  contains  the name of the file linked to, otherwise
                     it is empty.  Note  that  if  this  element  is  selected
                     (‘‘stat  +link’’)  then  the  -L  option is automatically
                     used.

              A particular element may be selected by including its name  pre-
              ceded  by a ‘+’ in the option list; only one element is allowed.
              The element may be shortened to any unique set of leading  char-
              acters.  Otherwise, all elements will be shown for all files.

              Options:

              -A array
                     Instead  of  displaying  the  results on standard output,
                     assign them to an array,  one  struct  stat  element  per
                     array  element for each file in order.  In this case nei-
                     ther the name of the element nor the name  of  the  files
                     appears  in array unless the -t or -n options were given,
                     respectively.  If -t is given, the element  name  appears
                     as  a  prefix  to the appropriate array element; if -n is
                     given, the file name appears as a separate array  element
                     preceding  all  the others.  Other formatting options are
                     respected.

              -H hash
                     Similar to -A, but instead assign  the  values  to  hash.
                     The keys are the elements listed above.  If the -n option
                     is provided then the name of the file is included in  the
                     hash with key name.

              -f fd  Use  the  file  on  file  descriptor  fd instead of named
                     files; no list of file names is allowed in this case.

              -F fmt Supplies a strftime (see strftime(3)) string for the for-
                     matting  of the time elements.  The -s option is implied.

              -g     Show the time elements in the  GMT  time  zone.   The  -s
                     option is implied.

              -l     List  the  names of the type elements (to standard output
                     or an  array  as  appropriate)  and  return  immediately;
                     options other than -A and arguments are ignored.

              -L     Perform an lstat (see lstat(2)) rather than a stat system
                     call.  In this case, if the file is a  link,  information
                     about  the  link  itself  rather  than the target file is
                     returned.  This option is required to make the link  ele-
                     ment useful.

              -n     Always  show  the names of files.  Usually these are only
                     shown when output is to standard output and there is more
                     than one file in the list.

              -N     Never show the names of files.

              -o     If a raw file mode is printed, show it in octal, which is
                     more useful for human consumption  than  the  default  of
                     decimal.   A  leading  zero will be printed in this case.
                     Note that this does not affect whether a raw or formatted
                     file  mode is shown, which is controlled by the -r and -s
                     options, nor whether a mode is shown at all.

              -r     Print raw data (the default format) alongside string data
                     (the  -s  format); the string data appears in parentheses
                     after the raw data.

              -s     Print mode, uid, gid  and  the  three  time  elements  as
                     strings  instead  of numbers.  In each case the format is
                     like that of ls -l.

              -t     Always show the type names for  the  elements  of  struct
                     stat.   Usually  these  are  only shown when output is to
                     standard  output  and  no  individual  element  has  been
                     selected.

              -T     Never show the type names of the struct stat elements.


THE ZSH/SYSTEM MODULE

       The  zsh/system  module  makes  available  three builtin commands and a
       parameter.



BUILTINS

       syserror [ -e errvar ] [ -p prefix ] [ errno | errname ]
              This command prints out the error message associated with errno,
              a  system error number, followed by a newline to standard error.

              Instead of the error number, a name errname, for example ENOENT,
              may  be  used.   The set of names is the same as the contents of
              the array errnos, see below.

              If the string prefix is given, it is printed  in  front  of  the
              error message, with no intervening space.

              If errvar is supplied, the entire message, without a newline, is
              assigned to the parameter names errvar and nothing is output.

              A return value of  0  indicates  the  message  was  successfully
              printed  (although  it may not be useful if the error number was
              out of the system’s range), a return value  of  1  indicates  an
              error  in  the parameters, and a return value of 2 indicates the
              error name was not recognised (no message is printed for  this).

       sysread [ -c countvar ] [ -i infd ] [ -o outfd ]
         [ -s bufsize ] [ -t timeout ] [ param ]
              Perform  a single system read from file descriptor infd, or zero
              if that is not given.  The result of the read is stored in param
              or REPLY if that is not given.  If countvar is given, the number
              of bytes read is assigned to the parameter named by countvar.

              The maximum number of bytes read is bufsize or 8192 if  that  is
              not  given, however the command returns as soon as any number of
              bytes was successfully read.

              If timeout is given, it specifies a timeout  in  seconds,  which
              may be zero to poll the file descriptor.  This is handled by the
              poll system call if available, otherwise the select system  call
              if available.

              If  outfd  is  given,  an attempt is made to write all the bytes
              just read to the file descriptor outfd.  If this fails,  because
              of a system error other than EINTR or because of an internal zsh
              error during an interrupt, the bytes read but  not  written  are
              stored  in  the parameter named by param if supplied (no default
              is used in this case), and the number  of  bytes  read  but  not
              written  is stored in the parameter named by countvar if that is
              supplied.  If it was successful, countvar contains the full num-
              ber of bytes transferred, as usual, and param is not set.

              The  error EINTR (interrupted system call) is handled internally
              so that shell interrupts are transparent  to  the  caller.   Any
              other error causes a return.

              The possible return values are
              0      At  least  one byte of data was successfully read and, if
                     appropriate, written.

              1      There was an error in  the  parameters  to  the  command.
                     This  is the only error for which a message is printed to
                     standard error.

              2      There was an error on the read, or on polling  the  input
                     file descriptor for a timeout.  The parameter ERRNO gives
                     the error.

              3      Data were successfully read, but there was an error writ-
                     ing  them to outfd.  The parameter ERRNO gives the error.

              4      The attempt to read timed out.  Note this  does  not  set
                     ERRNO as this is not a system error.

              5      No system error occurred, but zero bytes were read.  This
                     usually indicates end of file.  The  parameters  are  set
                     according  to  the  usual  rules;  no  write  to outfd is
                     attempted.

       syswrite [ -c countvar ] [ -o outfd ] data
              The data (a single string of bytes)  are  written  to  the  file
              descriptor  outfd,  or  1  if that is not given, using the write
              system call.  Multiple write operations may be used if the first
              does not write all the data.

              If  countvar  is  given, the number of byte written is stored in
              the parameter named by countvar; this may not be the full length
              of data if an error occurred.

              The  error EINTR (interrupted system call) is handled internally
              by retrying; otherwise an error causes the  command  to  return.
              For  example, if the file descriptor is set to non-blocking out-
              put, an error EAGAIN (on some systems, EWOULDBLOCK)  may  result
              in the command returning early.

              The  return  status  may be 0 for success, 1 for an error in the
              parameters to the command, or 2 for an error on  the  write;  no
              error  message  is  printed  in the last case, but the parameter
              ERRNO will reflect the error that occurred.



PARAMETERS

       errnos A readonly array of the names of errors defined on  the  system.
              These  are typically macros defined in C by including the system
              header file errno.h.  The  index  of  each  name  (assuming  the
              option  KSH_ARRAYS  is  unset)  corresponds to the error number.
              Error numbers num before the last known error which have no name
              are given the name Enum in the array.

              Note that aliases for errors are not handled; only the canonical
              name is used.


THE ZSH/NET/TCP MODULE

       The zsh/net/tcp module makes available one builtin command:

       ztcp [ -acflLtv ] [ -d fd ] [ args ]
              ztcp is implemented as a builtin to allow full use of shell com-
              mand line editing, file I/O, and job control mechanisms.

              If  ztcp  is run with no options, it will output the contents of
              its session table.

              If it is run with only the option -L, it will  output  the  con-
              tents  of  the  session table in a format suitable for automatic
              parsing.  The option is ignored if given with a command to  open
              or  close a session.  The output consists of a set of lines, one
              per session, each containing the following elements separated by
              spaces:

              File descriptor
                     The  file descriptor in use for the connection.  For nor-
                     mal inbound (I) and outbound (O) connections this may  be
                     read and written by the usual shell mechanisms.  However,
                     it should only be close with ‘ztcp -c’.

              Connection type
                     A letter indicating how the session was created:

                      Z      A session created with the zftp command.

                      L      A connection opened for listening with ‘ztcp -l’.

                      I      An inbound connection accepted with ‘ztcp -a’.

                      O      An  outbound  connection  created with ‘ztcp host
                             ...’.


              The local host
                     This is usually set to an  all-zero  IP  address  as  the
                     address of the localhost is irrelevant.

              The local port
                     This  is  likely  to be zero unless the connection is for
                     listening.

              The remote host
                     This is the fully qualified domain name of the  peer,  if
                     available,  else  an  IP  address.   It is an all-zero IP
                     address for a session opened for listening.

              The remote port
                     This is zero for a connection opened for listening.


   Outbound Connections
       ztcp [ -v ] [ -d fd ] host [ port ]
              Open a new TCP connection to host.  If the port is  omitted,  it
              will  default  to  port 23.  The connection will be added to the
              session table and the shell parameter REPLY will be set  to  the
              file descriptor associated with that connection.

              If  -d  is  specified,  its argument will be taken as the target
              file descriptor for the connection.

              In order to elicit more verbose output, use -v.


   Inbound Connections
       ztcp -l [ -v ] [ -d fd ] port
              ztcp -l will open a socket listening on TCP  port.   The  socket
              will be added to the session table and the shell parameter REPLY
              will be set to the file descriptor  associated  with  that  lis-
              tener.

              If  -d  is  specified,  its argument will be taken as the target
              file descriptor for the connection.

              In order to elicit more verbose output, use -v.

       ztcp -a [ -tv ] [ -d targetfd ] listenfd
              ztcp -a will accept an incoming connection to the  port  associ-
              ated with listenfd.  The connection will be added to the session
              table and the shell parameter REPLY will  be  set  to  the  file
              descriptor associated with the inbound connection.

              If  -d  is  specified,  its argument will be taken as the target
              file descriptor for the connection.

              If -t is specified, ztcp will return if no  incoming  connection
              is pending.  Otherwise it will wait for one.

              In order to elicit more verbose output, use -v.


   Closing Connections
       ztcp -cf [ -v ] [ fd ]
       ztcp -c [ -v ] [ fd ]
              ztcp  -c  will  close the socket associated with fd.  The socket
              will be removed from the session table.  If fd is not specified,
              ztcp will close everything in the session table.

              Normally, sockets registered by zftp (see zshmodules(1) ) cannot
              be closed this way.  In order to force such a socket closed, use
              -f.

              In order to elicit more verbose output, use -v.


   Example
       Here  is  how  to create a TCP connection between two instances of zsh.
       We need to pick an unassigned port; here we  use  the  randomly  chosen
       5123.

       On host1,
              zmodload zsh/net/tcp
              ztcp -l 5123
              listenfd=$REPLY
              ztcp -a $listenfd
              fd=$REPLY
       The  second from last command blocks until there is an incoming connec-
       tion.

       Now create a connection from host2 (which may, of course, be  the  same
       machine):
              zmodload zsh/net/tcp
              ztcp host1 5123
              fd=$REPLY

       Now  on  each  host,  $fd contains a file descriptor for talking to the
       other.  For example, on host1:
              print This is a message >&$fd
       and on host2:
              read -r line <&$fd; print -r - $line
       prints ‘This is a message’.

       To tidy up, on host1:
              ztcp -c $listenfd
              ztcp -c $fd
       and on host2
              ztcp -c $fd


THE ZSH/TERMCAP MODULE

       The zsh/termcap module makes available one builtin command:

       echotc cap [ arg ... ]
              Output the termcap value corresponding to  the  capability  cap,
              with optional arguments.

       The zsh/termcap module makes available one parameter:

       termcap
              An associative array that maps termcap capability codes to their
              values.


THE ZSH/TERMINFO MODULE

       The zsh/terminfo module makes available one builtin command:

       echoti cap [ arg ]
              Output the terminfo value corresponding to the  capability  cap,
              instantiated with arg if applicable.

       The zsh/terminfo module makes available one parameter:

       terminfo
              An  associative  array  that  maps  terminfo capability names to
              their values.


THE ZSH/ZFTP MODULE

       The zsh/zftp module makes available one builtin command:

       zftp subcommand [ args ]
              The zsh/zftp module is a client for FTP  (file  transfer  proto-
              col).  It is implemented as a builtin to allow full use of shell
              command line editing, file  I/O,  and  job  control  mechanisms.
              Often, users will access it via shell functions providing a more
              powerful interface; a set is provided with the zsh  distribution
              and is described in zshzftpsys(1).  However, the zftp command is
              entirely usable in its own right.

              All commands consist of the command name zftp  followed  by  the
              name  of a subcommand.  These are listed below.  The return sta-
              tus of each subcommand is supposed to  reflect  the  success  or
              failure of the remote operation.  See a description of the vari-
              able ZFTP_VERBOSE for more information on how responses from the
              server may be printed.


   Subcommands
       open host[:port] [ user [ password [ account ] ] ]
              Open  a  new  FTP  session  to  host, which may be the name of a
              TCP/IP connected host or an IP number in the standard dot  nota-
              tion.   If the argument is in the form host:port, open a connec-
              tion to TCP port port instead of the standard FTP port 21.  This
              may  be the name of a TCP service or a number:  see the descrip-
              tion of ZFTP_PORT below for more information.

              If IPv6 addresses in colon format are used, the host  should  be
              surrounded  by quoted square brackets to distinguish it from the
              port, for example [fe80::203:baff:fe02:8b56].  For consistency
              this is allowed with all forms of host.

              Remaining  arguments  are  passed to the login subcommand.  Note
              that if no arguments beyond host are  supplied,  open  will  not
              automatically  call login.  If no arguments at all are supplied,
              open will use the parameters set by the params subcommand.

              After  a  successful  open,  the  shell   variables   ZFTP_HOST,
              ZFTP_PORT,  ZFTP_IP  and  ZFTP_SYSTEM  are available; see ‘Vari-
              ables’ below.

       login [ name [ password [ account ] ] ]
       user [ name [ password [ account ] ] ]
              Login the user name with parameters password and  account.   Any
              of the parameters can be omitted, and will be read from standard
              input if needed (name is always needed).  If standard input is a
              terminal,  a  prompt  for  each  one will be printed on standard
              error and password will not be echoed.  If any of the parameters
              are not used, a warning message is printed.

              After   a  successful  login,  the  shell  variables  ZFTP_USER,
              ZFTP_ACCOUNT and ZFTP_PWD are available; see ‘Variables’  below.

              This  command may be re-issued when a user is already logged in,
              and the server will first be reinitialized for a new user.

       params [ host [ user [ password [ account ] ] ] ]
       params -
              Store the given parameters for a  later  open  command  with  no
              arguments.   Only those given on the command line will be remem-
              bered.  If no arguments are given, the parameters currently  set
              are  printed,  although  the  password  will appear as a line of
              stars; the return value is one if no parameters were  set,  zero
              otherwise.

              Any  of the parameters may be specified as a ‘?’, which may need
              to be quoted to protect it from shell expansion.  In this  case,
              the  appropriate  parameter  will be read from stdin as with the
              login subcommand, including special handling  of  password.   If
              the  ‘?’ is followed by a string, that is used as the prompt for
              reading the parameter instead of the default message (any neces-
              sary punctuation and whitespace should be included at the end of
              the prompt).  The first letter of the parameter  (only)  may  be
              quoted  with  a ‘\’; hence an argument "\\$word" guarantees that
              the string from the shell parameter $word will be treated liter-
              ally, whether or not it begins with a ‘?’.

              If  instead  a  single ‘-’ is given, the existing parameters, if
              any, are deleted.  In that case, calling open with no  arguments
              will cause an error.

              The  list of parameters is not deleted after a close, however it
              will be deleted if the zsh/zftp module is unloaded.

              For example,

                     zftp params ftp.elsewhere.xx juser ?Password for juser: 

              will store the host ftp.elsewhere.xx and the user juser and then
              prompt  the  user  for the corresponding password with the given
              prompt.

       test   Test the connection; if the server  has  reported  that  it  has
              closed the connection (maybe due to a timeout), return status 2;
              if no connection was open anyway, return status 1;  else  return
              status  0.   The  test subcommand is silent, apart from messages
              printed by the $ZFTP_VERBOSE mechanism, or error messages if the
              connection  closes.  There is no network overhead for this test.

              The test is only supported on systems with either the  select(2)
              or poll(2) system calls; otherwise the message ‘not supported on
              this system’ is printed instead.

              The test subcommand will automatically be called at the start of
              any  other  subcommand for the current session when a connection
              is open.

       cd directory
              Change the remote directory to directory.  Also alters the shell
              variable ZFTP_PWD.

       cdup   Change  the  remote directory to the one higher in the directory
              tree.  Note that cd .. will also work correctly on non-UNIX sys-
              tems.

       dir [ args... ]
              Give  a (verbose) listing of the remote directory.  The args are
              passed directly  to  the  server.  The  command’s  behaviour  is
              implementation  dependent,  but  a  UNIX  server  will typically
              interpret args as arguments to the ls command and with no  argu-
              ments  return  the result of ‘ls -l’. The directory is listed to
              standard output.

       ls [ args ]
              Give a (short) listing of the remote directory.  With  no  args,
              produces a raw list of the files in the directory, one per line.
              Otherwise, up to vagaries of the server implementation,  behaves
              similar to dir.

       type [ type ]
              Change  the  type for the transfer to type, or print the current
              type if type is absent.  The allowed values are ‘A’ (ASCII), ‘I’
              (Image, i.e. binary), or ‘B’ (a synonym for ‘I’).

              The FTP default for a transfer is ASCII.  However, if zftp finds
              that the remote host is a UNIX machine with 8-bit byes, it  will
              automatically  switch  to  using  binary for file transfers upon
              open.  This can subsequently be overridden.

              The transfer type is only passed to the remote host when a  data
              connection  is  established;  this  command  involves no network
              overhead.

       ascii  The same as type A.

       binary The same as type I.

       mode [ S | B ]
              Set the mode type to stream (S) or block (B).   Stream  mode  is
              the default; block mode is not widely supported.

       remote files...
       local [ files... ]
              Print the size and last modification time of the remote or local
              files.  If there is more than one item on the list, the name  of
              the  file  is printed first.  The first number is the file size,
              the second is the last modification time of the file in the for-
              mat  CCYYMMDDhhmmSS  consisting of year, month, date, hour, min-
              utes and seconds in GMT.  Note that this format,  including  the
              length, is guaranteed, so that time strings can be directly com-
              pared via the [[ builtin’s < and > operators, even if  they  are
              too long to be represented as integers.

              Not  all servers support the commands for retrieving this infor-
              mation.  In that case, the remote command will print nothing and
              return status 2, compared with status 1 for a file not found.

              The  local  command  (but  not remote) may be used with no argu-
              ments, in which case the information comes from  examining  file
              descriptor zero.  This is the same file as seen by a put command
              with no further redirection.

       get file [...]
              Retrieve all files from the server, concatenating them and send-
              ing them to standard output.

       put file [...]
              For  each file, read a file from standard input and send that to
              the remote host with the given name.

       append file [...]
              As put, but if the remote file already exists, data is  appended
              to it instead of overwriting it.

       getat file point
       putat file point
       appendat file point
              Versions of get, put and append which will start the transfer at
              the given point in the remote file.  This is useful for  append-
              ing  to an incomplete local file.  However, note that this abil-
              ity is not universally supported by servers (and  is  not  quite
              the behaviour specified by the standard).

       delete file [...]
              Delete the list of files on the server.

       mkdir directory
              Create a new directory directory on the server.

       rmdir directory
              Delete the directory directory  on the server.

       rename old-name new-name
              Rename file old-name to new-name on the server.

       site args...
              Send  a  host-specific command to the server.  You will probably
              only need this if instructed by the server to use it.

       quote args...
              Send the raw FTP command sequence to the server.  You should  be
              familiar  with  the  FTP command set as defined in RFC959 before
              doing this.  Useful commands may include STAT  and  HELP.   Note
              also  the  mechanism for returning messages as described for the
              variable ZFTP_VERBOSE below, in  particular  that  all  messages
              from the control connection are sent to standard error.

       close
       quit   Close the current data connection.  This unsets the shell param-
              eters ZFTP_HOST,  ZFTP_PORT,  ZFTP_IP,  ZFTP_SYSTEM,  ZFTP_USER,
              ZFTP_ACCOUNT, ZFTP_PWD, ZFTP_TYPE and ZFTP_MODE.

       session [ sessname ]
              Allows  multiple  FTP  sessions to be used at once.  The name of
              the session is an arbitrary string of  characters;  the  default
              session  is called ‘default’.  If this command is called without
              an argument, it will list all  the  current  sessions;  with  an
              argument,  it  will either switch to the existing session called
              sessname, or create a new session of that name.

              Each session remembers the status of the connection, the set  of
              connection-specific  shell parameters (the same set as are unset
              when a connection closes, as given in the description of close),
              and  any  user  parameters specified with the params subcommand.
              Changing to a previous session restores those  values;  changing
              to a new session initialises them in the same way as if zftp had
              just been loaded.  The name of the current session is  given  by
              the parameter ZFTP_SESSION.

       rmsession [ sessname ]
              Delete a session; if a name is not given, the current session is
              deleted.  If the current session is deleted, the earliest exist-
              ing  session becomes the new current session, otherwise the cur-
              rent session is not changed.  If the session  being  deleted  is
              the  only  one,  a  new  session called ‘default’ is created and
              becomes the current session; note that this  is  a  new  session
              even  if  the session being deleted is also called ‘default’. It
              is recommended that sessions not  be  deleted  while  background
              commands which use zftp are still active.


   Parameters
       The  following  shell  parameters  are used by zftp.  Currently none of
       them are special.

       ZFTP_TMOUT
              Integer.  The time in seconds to wait for a network operation to
              complete before returning an error.  If this is not set when the
              module is loaded, it will be given  the  default  value  60.   A
              value  of  zero  turns off timeouts.  If a timeout occurs on the
              control connection it will be closed.  Use  a  larger  value  if
              this occurs too frequently.

       ZFTP_IP
              Readonly.  The IP address of the current connection in dot nota-
              tion.

       ZFTP_HOST
              Readonly.  The hostname of the current remote  server.   If  the
              host  was  opened  as  an  IP  number,  ZFTP_HOST  contains that
              instead; this saves the overhead for a name lookup, as  IP  num-
              bers are most commonly used when a nameserver is unavailable.

       ZFTP_PORT
              Readonly.   The  number of the remote TCP port to which the con-
              nection is open (even if the port was originally specified as  a
              named service).  Usually this is the standard FTP port, 21.

              In  the unlikely event that your system does not have the appro-
              priate conversion functions, this appears in network byte order.
              If  your  system is little-endian, the port then consists of two
              swapped bytes and the standard port will be  reported  as  5376.
              In  that  case, numeric ports passed to zftp open will also need
              to be in this format.

       ZFTP_SYSTEM
              Readonly.  The system type string  returned  by  the  server  in
              response to an FTP SYST request.  The most interesting case is a
              string beginning "UNIX Type: L8", which ensures maximum compati-
              bility with a local UNIX host.

       ZFTP_TYPE
              Readonly.   The  type to be used for data transfers , either ‘A’
              or ‘I’.   Use the type subcommand to change this.

       ZFTP_USER
              Readonly.  The username currently logged in, if any.

       ZFTP_ACCOUNT
              Readonly.  The account name of the current user, if  any.   Most
              servers do not require an account name.

       ZFTP_PWD
              Readonly.  The current directory on the server.

       ZFTP_CODE
              Readonly.   The  three digit code of the last FTP reply from the
              server as a string.  This can still be read after the connection
              is  closed, and is not changed when the current session changes.

       ZFTP_REPLY
              Readonly.  The last line of the last reply sent by  the  server.
              This  can  still  be read after the connection is closed, and is
              not changed when the current session changes.

       ZFTP_SESSION
              Readonly.  The name of the current FTP session; see the descrip-
              tion of the session subcommand.

       ZFTP_PREFS
              A   string   of  preferences  for  altering  aspects  of  zftp’s
              behaviour.  Each preference is a single character.  The  follow-
              ing are defined:

              P      Passive:  attempt to make the remote server initiate data
                     transfers.  This is slightly more efficient than sendport
                     mode.   If  the letter S occurs later in the string, zftp
                     will use sendport mode if passive mode is not  available.

              S      Sendport:   initiate  transfers  by the FTP PORT command.
                     If this occurs before any P in the string,  passive  mode
                     will never be attempted.

              D      Dumb:   use  only the bare minimum of FTP commands.  This
                     prevents the  variables  ZFTP_SYSTEM  and  ZFTP_PWD  from
                     being set, and will mean all connections default to ASCII
                     type.  It may prevent ZFTP_SIZE from being set  during  a
                     transfer  if  the  server  does  not send it anyway (many
                     servers do).

              If ZFTP_PREFS is not set when zftp is loaded, it will be set  to
              a default of ‘PS’, i.e. use passive mode if available, otherwise
              fall back to sendport mode.

       ZFTP_VERBOSE
              A string of digits between 0 and 5 inclusive,  specifying  which
              responses  from  the server should be printed.  All responses go
              to standard error.  If any of the numbers 1 to 5 appear  in  the
              string, raw responses from the server with reply codes beginning
              with that digit will be printed to standard  error.   The  first
              digit of the three digit reply code is defined by RFC959 to cor-
              respond to:

              1.     A positive preliminary reply.

              2.     A positive completion reply.

              3.     A positive intermediate reply.

              4.     A transient negative completion reply.

              5.     A permanent negative completion reply.

              It should be noted that, for unknown reasons, the reply ‘Service
              not  available’,  which  forces  termination of a connection, is
              classified as 421, i.e.  ‘transient  negative’,  an  interesting
              interpretation of the word ‘transient’.

              The  code 0 is special:  it indicates that all but the last line
              of multiline replies read from the server  will  be  printed  to
              standard  error  in  a processed format.  By convention, servers
              use this mechanism for sending information for the user to read.
              The  appropriate  reply  code,  if it matches the same response,
              takes priority.

              If ZFTP_VERBOSE is not set when zftp is loaded, it will  be  set
              to  the  default value 450, i.e., messages destined for the user
              and all errors will be printed.  A  null  string  is  valid  and
              specifies that no messages should be printed.


   Functions
       zftp_chpwd
              If this function is set by the user, it is called every time the
              directory changes on the server, including when a user is logged
              in, or when a connection is closed.  In the last case, $ZFTP_PWD
              will be unset; otherwise it will reflect the new directory.

       zftp_progress
              If this function is set by the user, it will be called during  a
              get,  put or append operation each time sufficient data has been
              received from the host.  During a get, the data is sent to stan-
              dard  output,  so it is vital that this function should write to
              standard error or directly to the terminal, not to standard out-
              put.

              When  it  is  called  with a transfer in progress, the following
              additional shell parameters are set:

              ZFTP_FILE
                     The name of the remote file being transferred from or to.

              ZFTP_TRANSFER
                     A G for a get operation and a P for a put operation.

              ZFTP_SIZE
                     The  total  size  of the complete file being transferred:
                     the same as the first value provided by  the  remote  and
                     local  subcommands  for a particular file.  If the server
                     cannot  supply  this  value  for  a  remote  file   being
                     retrieved,  it  will not be set.  If input is from a pipe
                     the value may be incorrect and  correspond  simply  to  a
                     full pipe buffer.

              ZFTP_COUNT
                     The  amount  of data so far transferred; a number between
                     zero and $ZFTP_SIZE, if that  is  set.   This  number  is
                     always available.

              The  function  is initially called with ZFTP_TRANSFER set appro-
              priately and ZFTP_COUNT set to zero.  After the transfer is fin-
              ished,   the   function  will  be  called  one  more  time  with
              ZFTP_TRANSFER set to GF or PF, in case it wishes to tidy up.  It
              is   otherwise  never  called  twice  with  the  same  value  of
              ZFTP_COUNT.

              Sometimes the progress meter may cause disruption.  It is up  to
              the user to decide whether the function should be defined and to
              use unfunction when necessary.


   Problems
       A connection may not be opened in the left hand side of a pipe as  this
       occurs  in  a  subshell  and the file information is not updated in the
       main shell.  In the case of type or mode changes or closing the connec-
       tion  in  a subshell, the information is returned but variables are not
       updated until the next call to zftp.  Other status changes in subshells
       will not be reflected by changes to the variables (but should be other-
       wise harmless).

       Deleting sessions while a zftp command is active in the background  can
       have  unexpected  effects,  even  if  it does not use the session being
       deleted.  This is because all shell subprocesses share  information  on
       the state of all connections, and deleting a session changes the order-
       ing of that information.

       On some operating systems, the control connection is not valid after  a
       fork(),  so  that  operations  in subshells, on the left hand side of a
       pipeline, or in the background are not possible,  as  they  should  be.
       This is presumably a bug in the operating system.


THE ZSH/ZLE MODULE

       The zsh/zle module contains the Zsh Line Editor.  See zshzle(1).


THE ZSH/ZLEPARAMETER MODULE

       The  zsh/zleparameter module defines two special parameters that can be
       used to access internal information of the Zsh Line  Editor  (see  zsh-
       zle(1)).

       keymaps
              This  array contains the names of the keymaps currently defined.

       widgets
              This associative array contains one entry  per  widget  defined.
              The  name  of the widget is the key and the value gives informa-
              tion about the widget. It is either  the  string  ‘builtin’  for
              builtin   widgets,   a   string  of  the  form  ‘user:name’  for
              user-defined widgets, where name is the name of the shell  func-
              tion  implementing  the  widget,  or  it is a string of the form
              ‘completion:type:name’, for completion widgets. In the last case
              type  is  the  name of the builtin widgets the completion widget
              imitates in its behavior and name is the name of the shell func-
              tion implementing the completion widget.


THE ZSH/ZPROF MODULE

       When  loaded, the zsh/zprof causes shell functions to be profiled.  The
       profiling results can be obtained with the zprof builtin  command  made
       available  by this module.  There is no way to turn profiling off other
       than unloading the module.

       zprof [ -c ]
              Without the -c option, zprof lists profiling results to standard
              output.   The  format  is  comparable  to  that of commands like
              gprof.

              At the top there is a summary listing all  functions  that  were
              called  at  least  once.   This  summary is sorted in decreasing
              order of the amount of time spent in each.   The  lines  contain
              the  number  of  the  function  in order, which is used in other
              parts of the list in suffixes of the form ‘[num]’.RE,  then  the
              number  of  calls  made to the function.  The next three columns
              list the time in milliseconds spent  in  the  function  and  its
              descendents, the average time in milliseconds spent in the func-
              tion and its descendents per call and  the  percentage  of  time
              spent  in  all  shell  functions  used  in this function and its
              descendents.  The following three columns give the same informa-
              tion,  but  counting only the time spent in the function itself.
              The final column shows the name of the function.

              After the summary, detailed  information  about  every  function
              that  was  invoked  is listed, sorted in decreasing order of the
              amount of time spent in each function and its descendents.  Each
              of these entries consists of descriptions for the functions that
              called the function described,  the  function  itself,  and  the
              functions  that  were  called  from it.  The description for the
              function itself has the same format as in the summary (and shows
              the same information).  The other lines don’t show the number of
              the function at the beginning  and  have  their  function  named
              indented  to  make it easier to distinguish the line showing the
              function described in the section from the surrounding lines.

              The information shown in this case is almost the same as in  the
              summary,  but only refers to the call hierarchy being displayed.
              For example, for a calling function the column showing the total
              running  time lists the time spent in the described function and
              its descendents only for the times when it was called from  that
              particular  calling  function.  Likewise, for a called function,
              this columns lists the total time spent in the  called  function
              and  its  descendents only for the times when it was called from
              the function described.

              Also in this case, the column showing the number of calls  to  a
              function also shows a slash and then the total number of invoca-
              tions made to the called function.

              As long as the zsh/zprof module is  loaded,  profiling  will  be
              done  and multiple invocations of the zprof builtin command will
              show the times and numbers of calls since the module was loaded.
              With  the  -c  option,  the zprof builtin command will reset its
              internal counters and will not show the listing.  )


THE ZSH/ZPTY MODULE

       The zsh/zpty module offers one builtin:

       zpty [ -e ] [ -b ] name [ arg ... ]
              The  arguments  following  name  are  concatenated  with  spaces
              between,  then  executed  as a command, as if passed to the eval
              builtin.  The command runs under a newly assigned  pseudo-termi-
              nal; this is useful for running commands non-interactively which
              expect an interactive environment.  The name is not part of  the
              command,  but is used to refer to this command in later calls to
              zpty.

              With the -e option, the pseudo-terminal is set up so that  input
              characters are echoed.

              With the -b option, input to and output from the pseudo-terminal
              are made non-blocking.

       zpty -d [ names ... ]
              The second form, with the -d option, is used to delete  commands
              previously  started,  by supplying a list of their names.  If no
              names are given, all commands are deleted.  Deleting  a  command
              causes the HUP signal to be sent to the corresponding process.

       zpty -w [ -n ] name [ strings ... ]
              The  -w option can be used to send the to command name the given
              strings as input (separated by spaces).  If the -n option is not
              given, a newline is added at the end.

              If  no strings are provided, the standard input is copied to the
              pseudo-terminal; this may stop before copying the full input  if
              the pseudo-terminal is non-blocking.

              Note  that the command under the pseudo-terminal sees this input
              as if it were typed, so beware when sending special  tty  driver
              characters such as word-erase, line-kill, and end-of-file.

       zpty -r [ -t ] name [ param [ pattern ] ]
              The  -r  option  can  be  used to read the output of the command
              name.  With only a name argument, the output read is  copied  to
              the  standard  output.  Unless the pseudo-terminal is non-block-
              ing, copying continues until the command under the pseudo-termi-
              nal  exits; when non-blocking, only as much output as is immedi-
              ately available is copied.  The return value is zero if any out-
              put is copied.

              When  also  given a param argument, at most one line is read and
              stored in the parameter named param.  Less than a full line  may
              be  read  if  the  pseudo-terminal  is non-blocking.  The return
              value is zero if at least one character is stored in param.

              If a pattern is given as well, output is read  until  the  whole
              string  read matches the pattern, even in the non-blocking case.
              The return value is zero if the string read matches the pattern,
              or  if  the  command has exited but at least one character could
              still be read.  As of this writing, a maximum of one megabyte of
              output  can  be  consumed  this  way; if a full megabyte is read
              without matching the pattern, the return value is non-zero.

              In all cases, the return value is non-zero if nothing  could  be
              read, and is 2 if this is because the command has finished.

              If  the  -r  option  is  combined with the -t option, zpty tests
              whether output is available before trying to read.  If no output
              is available, zpty immediately returns the value 1.

       zpty -t name
              The  -t option without the -r option can be used to test whether
              the command name is still running.  It returns a zero  value  if
              the command is running and a non-zero value otherwise.

       zpty [ -L ]
              The  last  form, without any arguments, is used to list the com-
              mands currently defined.  If the -L option  is  given,  this  is
              done in the form of calls to the zpty builtin.


THE ZSH/ZSELECT MODULE

       The zsh/zselect module makes available one builtin command:

       zselect [ -rwe -t timeout -a array ] [ fd ... ]
              The  zselect builtin is a front-end to the ‘select’ system call,
              which blocks until a file descriptor is  ready  for  reading  or
              writing,  or  has  an error condition, with an optional timeout.
              If this is not available on your system, the command  prints  an
              error  message and returns status 2 (normal errors return status
              1).  For more information, see your  systems  documentation  for
              select(3).   Note  there is no connection with the shell builtin
              of the same name.

              Arguments  and  options  may  be  intermingled  in  any   order.
              Non-option arguments are file descriptors, which must be decimal
              integers.  By default, file descriptors are  to  be  tested  for
              reading,  i.e.  zselect will return when data is available to be
              read from the file descriptor, or more precisely,  when  a  read
              operation  from the file descriptor will not block.  After a -r,
              -w and -e, the given file descriptors are to be tested for read-
              ing,  writing,  or error conditions.  These options and an arbi-
              trary list of file descriptors may be given in any order.

              (The presence of an ‘error condition’ is not well defined in the
              documentation  for  many  implementations  of  the select system
              call.  According to recent versions of the POSIX  specification,
              it  is really an exception condition, of which the only standard
              example is out-of-band data received on a socket.  So zsh  users
              are unlikely to find the -e option useful.)

              The  option  ‘-t timeout’ specifies a timeout in hundredths of a
              second.  This may be zero, in which case  the  file  descriptors
              will  simply  be polled and zselect will return immediately.  It
              is possible to call zselect  with  no  file  descriptors  and  a
              non-zero  timeout  for  use  as  a finer-grained replacement for
              ‘sleep’; not, however, the return status is always 1 for a time-
              out.

              The  option  ‘-a  array’  indicates  that array should be set to
              indicate the file descriptor(s) which are ready.  If the  option
              is  not  given,  the  array reply will be used for this purpose.
              The array will contain a string similar  to  the  arguments  for
              zselect.  For example,

                     zselect -t 0 -r 0 -w 1

              might return immediately with status 0 and $reply containing ‘-r
              0 -w 1’ to show that both file descriptors  are  ready  for  the
              requested operations.

              The option ‘-A assoc’ indicates that the associative array assoc
              should be set to  indicate  the  file  descriptor(s)  which  are
              ready.   This  option overrides the option -a, nor will reply be
              modified.  The keys of assoc are the file descriptors,  and  the
              corresponding values are any of the characters ‘rwe’ to indicate
              the condition.

              The command returns 0 if some file  descriptors  are  ready  for
              reading.   If  the  operation  timed  out, or a timeout of 0 was
              given and no file descriptors were ready, or there was an error,
              it  returns status 1 and the array will not be set (nor modified
              in any way).  If there was an error in the select operation  the
              appropriate error message is printed.


THE ZSH/ZUTIL MODULE

       The zsh/zutil module only adds some builtins:

       zstyle [ -L ]
       zstyle [ -e | - | -- ] pattern style strings ...
       zstyle -d [ pattern [ styles ... ] ]
       zstyle -g name [ pattern [ style ] ]
       zstyle -abs context style name [ sep ]
       zstyle -Tt context style [ strings ...]
       zstyle -m context style pattern
              This  builtin  command  is  used  to  define  and lookup styles.
              Styles are pairs of names and values, where the  values  consist
              of  any  number  of strings.  They are stored together with pat-
              terns and lookup is done by giving a string,  called  the  ‘con-
              text’, which is compared to the patterns.  The definition stored
              for the first matching pattern will be returned.

              For ordering of comparisons, patterns  are  searched  from  most
              specific  to  least specific, and patterns that are equally spe-
              cific keep the order in which they were defined.  A  pattern  is
              considered  to be more specific than another if it contains more
              components (substrings separated by colons) or if  the  patterns
              for  the  components are more specific, where simple strings are
              considered to be more specific than patterns  and  complex  pat-
              terns are considered to be more specific than the pattern ‘*’.

              The  first form (without arguments) lists the definitions in the
              order zstyle will test them. If the -L option is given,  listing
              is done in the form of calls to zstyle.  Forms with arguments:

              zstyle [ - | -- | -e ] pattern style strings ...
                     Defines  the given style for the pattern with the strings
                     as the value.  If the -e option  is  given,  the  strings
                     will  be  concatenated  (separated  by  spaces)  and  the
                     resulting string will be evaluated (in the same way as it
                     is  done  by  the eval builtin command) when the style is
                     looked up.  In this case the parameter  ‘reply’  must  be
                     assigned  to  set  the strings returned after the evalua-
                     tion.  Before evaluating the value, reply is  unset,  and
                     if  it  is still unset after the evaluation, the style is
                     treated as if it were not set.

              zstyle -d [ pattern [ styles ... ] ]
                     Delete style definitions. Without arguments  all  defini-
                     tions  are  deleted,  with  a pattern all definitions for
                     that pattern are deleted and if  any  styles  are  given,
                     then only those styles are deleted for the pattern.

              zstyle -g name [ pattern [ style ] ]
                     Retrieve a style definition. The name is used as the name
                     of an array in which the results are stored. Without  any
                     further  arguments,  all  patterns  defined are returned.
                     With a pattern the styles defined for  that  pattern  are
                     returned  and  with both a pattern and a style, the value
                     strings of that combination is returned.

              The other forms can be used to look up or test patterns.

              zstyle -s context style name [ sep ]
                     The parameter name is set  to  the  value  of  the  style
                     interpreted  as  a string.  If the value contains several
                     strings they are concatenated with spaces  (or  with  the
                     sep string if that is given) between them.

              zstyle -b context style name
                     The  value  is  stored  in name as a boolean, i.e. as the
                     string ‘yes’ if the value has only one  string  and  that
                     string is equal to one of ‘yes’, ‘true’, ‘on’, or ‘1’. If
                     the value is any  other  string  or  has  more  than  one
                     string, the parameter is set to ‘no’.

              zstyle -a context style name
                     The  value  is  stored  in  name  as an array. If name is
                     declared as an associative array,  the first, third, etc.
                     strings  are  used  as the keys and the other strings are
                     used as the values.

              zstyle -t context style [ strings ...]
              zstyle -T context style [ strings ...]
                     Test the value of  a  style,  i.e.  the  -t  option  only
                     returns  a  status  (sets  $?).   Without any strings the
                     return status is zero if the  style  is  defined  for  at
                     least  one  matching  pattern, has only one string in its
                     value, and that is equal to one of ‘true’, ‘yes’, ‘on’ or
                     ‘1’.  If  any strings are given the status is zero if and
                     only if at least one of the strings is equal to at  least
                     one  of  the  strings  in  the value. If the style is not
                     defined, the status is 2.

                     The -T option tests the values of the style like -t,  but
                     it  returns  zero  (rather  than  2)  if the style is not
                     defined for any matching pattern.

              zstyle -m context style pattern
                     Match a value. Returns status zero if the pattern matches
                     at least one of the strings in the value.

       zformat -f param format specs ...
       zformat -a array sep specs ...
              This  builtin  provides  two  different forms of formatting. The
              first form is selected with the -f option. In this case the for-
              mat string will be modified by replacing sequences starting with
              a percent sign in it with strings from  the  specs.   Each  spec
              should  be  of  the  form  ‘char:string’  which will cause every
              appearance of the sequence ‘%char’ in format to be  replaced  by
              the  string.  The ‘%’ sequence may also contain optional minimum
              and maximum field width specifications between the ‘%’  and  the
              ‘char’  in the form ‘%min.maxc’, i.e. the minimum field width is
              given first and if the maximum field width is used, it has to be
              preceded  by  a dot.  Specifying a minimum field width makes the
              result be padded with spaces to  the  right  if  the  string  is
              shorter  than  the  requested width.  Padding to the left can be
              achieved by giving a negative minimum field width.  If a maximum
              field  width  is  specified,  the string will be truncated after
              that many characters.  After all ‘%’  sequences  for  the  given
              specs have been processed, the resulting string is stored in the
              parameter param.

              The %-escapes also understand ternary expressions  in  the  form
              used  by  prompts.  The % is followed by a ‘(’ and then an ordi-
              nary format specifier character as described above.   There  may
              be a set of digits either before or after the ‘(’; these specify
              a test number, which defaults to  zero.   Negative  numbers  are
              also allowed.  An arbitrary delimiter character follows the for-
              mat specifier, which is followed by a piece of ‘true’ text,  the
              delimiter  character again, a piece of ‘false’ text, and a clos-
              ing parenthesis.  The complete expression (without  the  digits)
              thus  looks like ‘%(X.text1.text2)’, except that the ‘.’ charac-
              ter is arbitrary.  The value given for the format  specifier  in
              the  char:string  expressions  is  evaluated  as  a mathematical
              expression, and compared with the test number.  If they are  the
              same,  text1 is output, else text2 is output.  A parenthesis may
              be escaped in text2 as %).  Either of text1 or text2 may contain
              nested %-escapes.

              For example:

                     zformat -f REPLY "The answer is %3(c.yes.no)." c:3

              outputs  "The answer is ’yes’." to REPLY since the value for the
              format specifier c is 3, agreeing with the digit argument to the
              ternary expression.

              The  second  form, using the -a option, can be used for aligning
              strings.  Here, the specs are of  the  form  ‘left:right’  where
              ‘left’  and  ‘right’  are  arbitrary strings.  These strings are
              modified by replacing the colons by the sep string  and  padding
              the  left  strings  with  spaces  to  the  right so that the sep
              strings in the result (and hence the right strings  after  them)
              are  all  aligned  if  the strings are printed below each other.
              All strings without a colon are left unchanged and  all  strings
              with  an empty right string have the trailing colon removed.  In
              both cases the lengths of the strings are not used to  determine
              how  the other strings are to be aligned.  The resulting strings
              are stored in the array.

       zregexparse
              This implements some internals of the _regex_arguments function.

       zparseopts [ -D ] [ -K ] [ -E ] [ -a array ] [ -A assoc ] specs
              This  builtin  simplifies  the  parsing of options in positional
              parameters, i.e. the set of arguments given by  $*.   Each  spec
              describes  one option and must be of the form ‘opt[=array]’.  If
              an option described by opt is found in the positional parameters
              it is copied into the array specified with the -a option; if the
              optional ‘=array’ is given,  it  is  instead  copied  into  that
              array.

              Note  that  it  is an error to give any spec without an ‘=array’
              unless one of the -a or -A options is used.

              Unless the -E option is given, parsing stops at the first string
              that isn’t described by one of the specs.  Even with -E, parsing
              always stops at a positional parameter equal to ‘-’ or ‘--’.

              The opt description must be one of the following.   Any  of  the
              special  characters can appear in the option name provided it is
              preceded by a backslash.

              name
              name+  The name is the name of the option  without  the  leading
                     ‘-’.   To  specify  a  GNU-style  long option, one of the
                     usual two leading ‘-’ must be included in name; for exam-
                     ple,  a  ‘--file’  option  is  represented  by  a name of
                     ‘-file’.

                     If a ‘+’ appears after name, the option  is  appended  to
                     array each time it is found in the positional parameters;
                     without the ‘+’ only the last occurrence of the option is
                     preserved.

                     If  one of these forms is used, the option takes no argu-
                     ment, so parsing stops if the next  positional  parameter
                     does  not  also  begin  with ‘-’ (unless the -E option is
                     used).

              name:
              name:-
              name:: If one or two colons are given, the option takes an argu-
                     ment;  with one colon, the argument is mandatory and with
                     two colons it is optional.  The argument is  appended  to
                     the array after the option itself.

                     An  optional  argument is put into the same array element
                     as the option name (note that this makes empty strings as
                     arguments  indistinguishable).   A  mandatory argument is
                     added as a separate element unless the ‘:-’ form is used,
                     in  which case the argument is put into the same element.

                     A ‘+’ as described above may appear between the name  and
                     the first colon.

       The options of zparseopts itself are:

       -a array
              As  described  above,  this  names the default array in which to
              store the recognised options.

       -A assoc
              If this is given, the options and their values are also put into
              an associative array with the option names as keys and the argu-
              ments (if any) as the values.

       -D     If this option is given, all options found are removed from  the
              positional parameters of the calling shell or shell function, up
              to but not including any not described by the  specs.   This  is
              similar to using the shift builtin.

       -K     With  this  option,  the  arrays  specified  with  the -a and -A
              options and with the ‘=array’ forms are kept unchanged when none
              of  the  specs  for  them  is  used.   This allows assignment of
              default values to them before calling zparseopts.

       -E     This changes the parsing rules to not stop at the  first  string
              that  isn’t  described  by  one of the specs.  It can be used to
              test for or (if used together with -D) extract options and their
              arguments,  ignoring all other options and arguments that may be
              in the positional parameters.

       For example,

              set -- -a -bx -c y -cz baz -cend
              zparseopts a=foo b:=bar c+:=bar

       will have the effect of

              foo=(-a)
              bar=(-b x -c y -c z)

       The arguments from ‘baz’ on will not be used.

       As an example for the -E option, consider:

              set -- -a x -b y -c z arg1 arg2
              zparseopts -E -D b:=bar

       will have the effect of

              bar=(-b y)
              set -- -a x -c z arg1 arg2

       I.e., the option -b and its arguments are  taken  from  the  positional
       parameters and put into the array bar.
ZSHTCPSYS(1)                                                      ZSHTCPSYS(1)




NAME

       zshtcpsys - zsh tcp system


DESCRIPTION

       A  module  zsh/net/tcp  is  provided to provide network I/O over TCP/IP
       from within the shell; see its description  in  zshmodules(1)  .   This
       manual  page  describes  a  function suite based on the module.  If the
       module is installed, the functions are usually installed  at  the  same
       time,  in  which  case  they  will  be available for autoloading in the
       default function search path.  In addition to the  zsh/net/tcp  module,
       the  zsh/zselect  module  is  used to implement timeouts on read opera-
       tions.  For troubleshooting tips, consult the corresponding advice  for
       the zftp functions described in zshftpsys(1) .

       There  are  functions  corresponding  to the basic I/O operations open,
       close, read and send, named  tcp_open  etc.,  as  well  as  a  function
       tcp_expect  for pattern match analysis of data read as input.  The sys-
       tem makes it easy to receive data from and send data to multiple  named
       sessions  at once.  In addition, it can be linked with the shell’s line
       editor in such a way that input data is automatically shown at the ter-
       minal.   Other  facilities  available  including logging, filtering and
       configurable output prompts.

       To use the system where  it  is  available,  it  should  be  enough  to
       ‘autoload  -U tcp_open’ and run tcp_open as documented below to start a
       session.  The tcp_open function will autoload the remaining  functions.




TCP USER FUNCTIONS

   Basic I/O
       tcp_open [-qz] host port [ sess ]
       tcp_open [-qz] [ -s sess | -l sess,... ] ...
       tcp_open [-qz] [-a fd | -f fd ] [ sess ]
              Open  a new session.  In the first and simplest form, open a TCP
              connection to host host at port port; numeric and symbolic forms
              are understood for both.

              If sess is given, this becomes the name of the session which can
              be used to refer to multiple different TCP connections.  If sess
              is  not  given,  the  function  will invent a numeric name value
              (note this is not the same as the file descriptor to  which  the
              session  is attached).  It is recommended that session names not
              include ‘funny’  characters,  where  funny  characters  are  not
              well-defined  but  certainly  do  not  include  alphanumerics or
              underscores, and certainly do include whitespace.

              In the second case, one or more sessions to be opened are  given
              by  name.   A  single  session  name  is  given  after  -s and a
              comma-separated list after -l; both options may be  repeated  as
              many  times  as  necessary.  The host and port are read from the
              file .ztcp_sessions in the same directory as the user’s zsh ini-
              tialisation files, i.e. usually the home directory, but $ZDOTDIR
              if that is set.  The file consists of lines each giving  a  ses-
              sion  name  and  the  corresponding host and port, in that order
              (note the session name comes  first,  not  last),  separated  by
              whitespace.

              The  third form allows passive and fake TCP connections.  If the
              option -a is used, its argument is a file  descriptor  open  for
              listening for connections.  No function front-end is provided to
              open such a file descriptor, but a call to ‘ztcp -l  port’  will
              create  one  with  the  file  descriptor stored in the parameter
              $REPLY.  The listening port can be closed with ‘ztcp -c fd’.   A
              call  to  ‘tcp_open -a fd’ will block until a remote TCP connec-
              tion is made to port on the local machine.   At  this  point,  a
              session  is  created  in  the usual way and is largely indistin-
              guishable from an active connection  created  with  one  of  the
              first two forms.

              If  the  option  -f  is  used, its argument is a file descriptor
              which is used directly as if it were a TCP  session.   How  well
              the remainder of the TCP function system copes with this depends
              on what actually underlies this file descriptor.  A regular file
              is  likely  to be unusable; a FIFO (pipe) of some sort will work
              better, but note that it is not a good idea  for  two  different
              sessions to attempt to read from the same FIFO at once.

              If  the option -q is given with any of the three forms, tcp_open
              will not print informational messages, although it will  in  any
              case exit with an appropriate status.

              If  the line editor (zle) is in use, which is typically the case
              if the shell is interactive, tcp_open installs a handler  inside
              zle  which will check for new data at the same time as it checks
              for keyboard input.  This is convenient as the shell consumes no
              CPU  time  while waiting; the test is performed by the operating
              system.  Giving the option -z to any of the  forms  of  tcp_open
              prevents  the handler from being installed, so data must be read
              explicitly.  Note, however, this is not necessary for  executing
              complete  sets of send and read commands from a function, as zle
              is not active at this point.  Generally speaking, the handler is
              only  active  when  the  shell is waiting for input at a command
              prompt or in the vared builtin.  The option has no effect if zle
              is not active; ‘[[ -o zle]]’ will test for this.

              The  first  session to be opened becomes the current session and
              subsequent calls to tcp_open do not change it.  The current ses-
              sion  is  stored  in the parameter $TCP_SESS; see below for more
              detail about the parameters used by the system.

       tcp_close [-qn] [ -a | -l sess,... | sess ... ]
              Close the named sessions, or the  current  session  if  none  is
              given,  or all open sessions if -a is given.  The options -l and
              -s are both handled for consistency with tcp_open, although  the
              latter is redundant.

              If  the  session  being  closed is the current one, $TCP_SESS is
              unset, leaving no current session, even if there are other  ses-
              sions still open.

              If  the session was opened with tcp_open -f, the file descriptor
              is closed so long as it is  in  the  range  0  to  9  accessible
              directly  from  the command line.  If the option -n is given, no
              attempt will be made to close file  descriptors  in  this  case.
              The  -n  option  is  not used for genuine ztcp session; the file
              descriptors are always closed with the session.

              If the option -q is given, no  informational  messages  will  be
              printed.

       tcp_read [-bdq] [ -t TO ] [ -T TO ]
           [ -a | -u fd ... | -l sess,... | -s sess ...]
              Perform a read operation on the current session, or on a list of
              sessions if any are given with -u, -l or -s, or  all  open  ses-
              sions  if  the  option  -a  is  given.   Any of the -u, -l or -s
              options may be repeated or mixed together.  The -u option speci-
              fies a file descriptor directly (only those managed by this sys-
              tem are useful), the other two specify sessions as described for
              tcp_open above.

              The  function  checks for new data available on all the sessions
              listed.  Unless the -b option is given, it will not block  wait-
              ing  for  new data.  Any one line of data from any of the avail-
              able sessions will be read, stored in the  parameter  $TCP_LINE,
              and  displayed  to standard output unless $TCP_SILENT contains a
              non-empty string.  When printed to standard  output  the  string
              $TCP_PROMPT  will be shown at the start of the line; the default
              form for this includes the name of the session being read.   See
              below  for  more information on these parameters.  In this mode,
              tcp_read can be called repeatedly  until  it  returns  status  2
              which  indicates  all  pending input from all specified sessions
              has been handled.

              With the option -b, equivalent to an infinite timeout, the func-
              tion  will  block  until a line is available to read from one of
              the  specified  sessions.   However,  only  a  single  line   is
              returned.

              The  option  -d  indicates  that  all  pending  input  should be
              drained.  In this case tcp_read may process  multiple  lines  in
              the  manner  given  above; only the last is stored in $TCP_LINE,
              but the complete set is stored in the array $tcp_lines.  This is
              cleared at the start of each call to tcp_read.

              The options -t and -T specify a timeout in seconds, which may be
              a floating point number for increased  accuracy.   With  -t  the
              timeout  is applied before each line read.  With -T, the timeout
              applies to the overall operation,  possibly  including  multiple
              read  operations  if  the  option  -d  is  present; without this
              option, there is no distinction between -t and -T.

              The function does not print informational messages, but  if  the
              option  -q is given, no error message is printed for a non-exis-
              tent session.

              A return value of 2 indicates a timeout or no data to read.  Any
              other non-zero return value indicates some error condition.

              See tcp_log for how to control where data is sent by tcp_read.

       tcp_send [-nq] [ -s sess | -l sess,... ] data ...
       tcp_send [-nq] -a data ...
              Send  the supplied data strings to all the specified sessions in
              turn.  The underlying operation differs little from a ‘print -r’
              to  the  session’s file descriptor, although it attempts to pre-
              vent the shell from dying  owing  to  a  SIGPIPE  caused  by  an
              attempt to write to a defunct session.

              The  option  -n  prevents tcp_send from putting a newline at the
              end of the data strings.

              The remaining options all behave as for tcp_read.

              The data arguments are not further processed once they have been
              passed to tcp_send; they are simply passed down to print -r.

              If  the  parameter $TCP_OUTPUT is a non-empty string and logging
              is enabled then the data sent to each session will be echoed  to
              the  log  file(s)  with  $TCP_OUTPUT in front where appropriate,
              much in the manner of $TCP_PROMPT.


   Session Management
       tcp_alias [-q] alias=sess ...
       tcp_alias [-q] [ alias ] ...
       tcp_alias -d [-q] alias ...
              This function is not particularly well tested.

              The first form creates an alias for a session  name;  alias  can
              then  be  used  to  refer to the existing session sess.  As many
              aliases may be listed as required.

              The second form lists any aliases specified, or all  aliases  if
              none.

              The  third  form deletes all the aliases listed.  The underlying
              sessions are not affected.

              The option -q suppresses  an  inconsistently  chosen  subset  of
              error messages.

       tcp_log [-asc] [ -n | -N ] [ logfile ]
              With an argument logfile, all future input from tcp_read will be
              logged to the named file.  Unless -a  (append)  is  given,  this
              file  will  first  be  truncated  or  created  empty.   With  no
              arguments, show the current status of logging.

              With the option -s, per-session logging is enabled.  Input  from
              tcp_read  is output to the file logfile.sess.  As the session is
              automatically discriminated by the filename,  the  contents  are
              raw   (no  $TCP_PROMPT).   The  option   -a  applies  as  above.
              Per-session logging and logging of all data in one file are  not
              mutually exclusive.

              The  option -c closes all logging, both complete and per-session
              logs.

              The options -n and -N respectively turn off or restore output of
              data  read  by  tcp_read to standard output; hence ‘tcp_log -cn’
              turns off all output by tcp_read.

              The function is purely a convenient front  end  to  setting  the
              parameters   $TCP_LOG,  $TCP_LOG_SESS,  $TCP_SILENT,  which  are
              described below.

       tcp_rename old new
              Rename session  old  to  session  new.   The  old  name  becomes
              invalid.

       tcp_sess [ sess [ command  ... ] ]
              With  no  arguments,  list  all the open sessions and associated
              file descriptors.  The current session is marked  with  a  star.
              For   use   in   functions,  direct  access  to  the  parameters
              $tcp_by_name, $tcp_by_fd and $TCP_SESS is probably  more  conve-
              nient; see below.

              With  a sess argument, set the current session to sess.  This is
              equivalent to changing $TCP_SESS directly.

              With additional arguments, temporarily set the  current  session
              while  executing  the string command ....  The first argument is
              re-evaluated so as to expand aliases  etc.,  but  the  remaining
              arguments  are  passed  through  as the appear to tcp_sess.  The
              original session is restored when tcp_sess exits.


   Advanced I/O
       tcp_command send-options ... send-arguments ...
              This is a convenient front-end to tcp_send.  All  arguments  are
              passed  to  tcp_send, then the function pauses waiting for data.
              While data is arriving at least every $TCP_TIMEOUT (default 0.3)
              seconds,  data  is handled and printed out according to the cur-
              rent settings.  Status 0 is always returned.

              This is generally only useful for interactive  use,  to  prevent
              the display becoming fragmented by output returned from the con-
              nection.  Within a programme or function it is generally  better
              to handle reading data by a more explicit method.

       tcp_expect [ -q ] [ -p var ] [ -t  to | -T TO]
           [ -a | -s sess ... | -l sess,... ] pattern ...
              Wait  for  input  matching any of the given patterns from any of
              the specified sessions.  Input is ignored until  an  input  line
              matches  one of the given patterns; at this point status zero is
              returned, the matching line is stored in $TCP_LINE, and the full
              set of lines read during the call to tcp_expect is stored in the
              array $tcp_expect_lines.

              Sessions are specified in the same way as tcp_read: the  default
              is  to use the current session, otherwise the sessions specified
              by -a, -s, or -l are used.

              Each pattern is a standard zsh extended-globbing  pattern;  note
              that  it  needs  to be quoted to avoid it being expanded immedi-
              ately by filename generation.  It must match the full  line,  so
              to  match  a substring there must be a ‘*’ at the start and end.
              The line matched  against  includes  the  $TCP_PROMPT  added  by
              tcp_read.   It is possible to include the globbing flags ‘#b’ or
              ‘#m’ in the patterns to make  backreferences  available  in  the
              parameters  $MATCH,  $match,  etc., as described in the base zsh
              documentation on pattern matching.

              Unlike tcp_read, the default behaviour of tcp_expect is to block
              indefinitely  until  the  required  input is found.  This can be
              modified by specifying a timeout with -t or -T;  these  function
              as  in  tcp_read,  specifying  a  per-read  or  overall timeout,
              respectively, in seconds, as an integer or  floating-point  num-
              ber.   As  tcp_read,  the function returns status 2 if a timeout
              occurs.

              The function returns as soon as any one of  the  patterns  given
              match.   If  the  caller  needs  to  know  which of the patterns
              matched, the option -p var can be used; on return, $var  is  set
              to  the  number of the pattern using ordinary zsh indexing, i.e.
              the first is 1, and so on.  Note the absence of a ‘$’  in  front
              of  var.   To  avoid  clashes,  the  parameter cannot begin with
              ‘_expect’.

              The option -q is passed directly down to tcp_read.

              As all input is done via tcp_read, all  the  usual  rules  about
              output of lines read apply.  One exception is that the parameter
              $tcp_lines will  only  reflect  the  line  actually  matched  by
              tcp_expect; use $tcp_expect_lines for the full set of lines read
              during the function call.

       tcp_proxy
              This is a simple-minded function to accept a TCP connection  and
              execute  a  command  with  I/O  redirected  to  the  connection.
              Extreme caution should be taken as there is no security  whatso-
              ever  and  this can leave your computer open to the world.  Ide-
              ally, it should only be used behind a firewall.

              The first argument is a TCP port on which the function will lis-
              ten.

              The remaining arguments give a command and its arguments to exe-
              cute with standard input, standard  output  and  standard  error
              redirected  to  the file descriptor on which the TCP session has
              been accepted.  If no command is given, a new  zsh  is  started.
              This  gives  everyone  on  your  network  direct  access to your
              account, which in many cases will be a bad thing.

              The command is run in the  background,  so  tcp_proxy  can  then
              accept  new connections.  It continues to accept new connections
              until interrupted.

       tcp_spam [-ertv] [ -a | -s  sess | -l sess,... ] cmd ...
              Execute ‘cmd ...’ for each session in turn.  Note this  executes
              the  command and arguments; it does not send the command line as
              data unless the -t (transmit) option is given.

              The sessions may be selected explicitly with the standard -a, -s
              or  -l  options,  or  may  be chosen implicitly.  If none of the
              three options is given  the  rules  are:  first,  if  the  array
              $tcp_spam_list  is  set,  this is taken as the list of sessions,
              otherwise all sessions are taken.  Second, any sessions given in
              the  array  $tcp_no_spam_list  are removed from the list of ses-
              sions.

              Normally, any sessions added by the ‘-a’ flag or when  all  ses-
              sions  are  chosen  implicitly  are spammed in alphabetic order;
              sessions given by the $tcp_spam_list array  or  on  the  command
              line  are  spammed in the order given.  The -r flag reverses the
              order however it was arrived it.

              The -v flag specifies that a $TCP_PROMPT will be  output  before
              each session.  This is output after any modification to TCP_SESS
              by  the  user-defined  tcp_on_spam  function  described   below.
              (Obviously that function is able to generate its own output.)

              If  the  option -e is present, the line given as cmd ... is exe-
              cuted using eval, otherwise it is executed without  any  further
              processing.

       tcp_talk
              This  is  a  fairly  simple-minded attempt to force input to the
              line editor to go straight to the default TCP_SESSION.

              An escape string, $TCP_TALK_ESCAPE,  default  ‘:’,  is  used  to
              allow  access to normal shell operation.  If it is on its own at
              the start of the line, or followed only by whitespace, the  line
              editor  returns  to normal operation.  Otherwise, the string and
              any following whitespace are skipped and the  remainder  of  the
              line executed as shell input without any change of the line edi-
              tor’s operating mode.

              The current implementation is somewhat deficient in terms of use
              of the command history.  For this reason, many users will prefer
              to use some form of alternative approach for sending data easily
              to  the  current  session.  One simple approach is to alias some
              special character (such as ‘%’) to ‘tcp_command --’.

       tcp_wait
              The sole argument is an integer or floating point  number  which
              gives  the seconds to delay.  The shell will do nothing for that
              period except wait for input on  all  TCP  sessions  by  calling
              tcp_read  -a.   This  is similar to the interactive behaviour at
              the command prompt when zle handlers are installed.


   One-shot file transfer
       tcp_point port
       tcp_shoot host port
              This pair of functions provide a simple way to transfer  a  file
              between  two  hosts  within the shell.  Note, however, that bulk
              data transfer is currently done using cat.  tcp_point reads  any
              data arriving at port and sends it to standard output; tcp_shoot
              connects to port on host and  sends  its  standard  input.   Any
              unused  port  may  be used; the standard mechanism for picking a
              port is to think of a random four-digit number above 1024  until
              one works.

              To  transfer  a  file  from  host  woodcock to host springes, on
              springes:

                     tcp_point 8091 >output_file

              and on woodcock:

                     tcp_shoot springes 8091 <input_file

              As these two functions do not require tcp_open to set up  a  TCP
              connection first, they may need to be autoloaded separately.



TCP USER-DEFINED FUNCTIONS

       Certain  functions, if defined by the user, will be called by the func-
       tion system in certain contexts.  This facility depends on  the  module
       zsh/parameter,  which is usually available in interactive shells as the
       completion system depends  on  it.   None  of  the  functions  need  be
       defined; they simply provide convenient hooks when necessary.

       Typically,  these are called after the requested action has been taken,
       so that the various parameters will reflect the new state.

       tcp_on_alias alias fd
              When an alias is defined, this function will be called with  two
              arguments: the name of the alias, and the file descriptor of the
              corresponding session.

       tcp_on_close sess fd
              This is called with the name of a session being closed  and  the
              file  descriptor  which corresponded to that session.  Both will
              be invalid by the time the function is called.

       tcp_on_open sess fd
              This is called after a new session has  been  defined  with  the
              session name and file descriptor as arguments.

       tcp_on_rename oldsess fd newsess
              This  is  called after a session has been renamed with the three
              arguments old session name, file descriptor, new session name.

       tcp_on_spam sess command ...
              This is called once for each session spammed, just before a com-
              mand  is  executed for a session by tcp_spam.  The arguments are
              the session name followed by the command list  to  be  executed.
              If  tcp_spam  was  called  with the option -t, the first command
              will be tcp_send.

              This function is called after $TCP_SESS is set  to  reflect  the
              session  to be spammed, but before any use of it is made.  Hence
              it is possible to alter the value of $TCP_SESS within this func-
              tion.   For  example,  the  session  arguments to tcp_spam could
              include extra information to be stripped off  and  processed  in
              tcp_on_spam.

              If the function sets the parameter $REPLY to ‘done’, the command
              line is not executed; in addition, no prompt is printed for  the
              -v option to tcp_spam.

       tcp_on_unalias alias fd
              This  is  called with the name of an alias and the corresponding
              session’s file descriptor after an alias has been deleted.



TCP UTILITY FUNCTIONS

       The following functions are used by the TCP function  system  but  will
       rarely if ever need to be called directly.

       tcp_fd_handler
              This  is  the  function installed by tcp_open for handling input
              from within the line editor, if that is required.  It is in  the
              format documented for the builtin ‘zle -F’ in zshzle(1) .

              While active, the function sets the parameter TCP_HANDLER_ACTIVE
              to 1.  This allows shell code called internally (for example, by
              setting  tcp_on_read)  to tell if is being called when the shell
              is otherwise idle at the editor prompt.

       tcp_output [ -q ] -P prompt -F fd -S sess
              This function is used for both logging and  handling  output  to
              standard  output,  from  within  tcp_read and (if $TCP_OUTPUT is
              set) tcp_send.

              The prompt to use is specified by -P; the default is  the  empty
              string.  It can contain:
              %c     Expands  to 1 if the session is the current session, oth-
                     erwise  0.   Used  with  ternary   expresions   such   as
                     ‘%(c.-.+)’  to output ‘+’ for the current session and ‘-’
                     otherwise.

              %f     Replaced by the session’s file descriptor.

              %s     Replaced by the session name.

              %%     Replaced by a single ‘%’.

              The option -q suppresses output to standard output, but  not  to
              any log files which are configured.

              The  -S  and -F options are used to pass in the session name and
              file descriptor for possible replacement in the prompt.



TCP USER PARAMETERS

       Parameters follow the usual  convention  that  uppercase  is  used  for
       scalars  and  integers, while lowercase is used for normal and associa-
       tive array.  It is always safe for user code to read these  parameters.
       Some  parameters  may  also be set; these are noted explicitly.  Others
       are included in this group as they are set by the function  system  for
       the  user’s  benefit,  i.e. setting them is typically not useful but is
       benign.

       It is often also useful to make settable parameters local  to  a  func-
       tion.   For example, ‘local TCP_SILENT=1’ specifies that data read dur-
       ing the function call will not be printed to standard  output,  regard-
       less   of   the   setting   outside  the  function.   Likewise,  ‘local
       TCP_SESS=sess’ sets a session for  the  duration  of  a  function,  and
       ‘local  TCP_PROMPT=’  specifies that no prompt is used for input during
       the function.

       tcp_expect_lines
              Array.   The  set  of  lines  read  during  the  last  call   to
              tcp_expect, including the last ($TCP_LINE).

       tcp_filter
              Array. May be set directly.  A set of extended globbing patterns
              which, if matched in tcp_output, will cause the line not  to  be
              printed  to  standard output.  The patterns should be defined as
              described for the arguments to tcp_expect.  Output  of  line  to
              log files is not affected.

       TCP_HANDLER_ACTIVE
              Scalar.  Set to 1 within tcp_fd_handler to indicate to functions
              called recursively that they have been called during  an  editor
              session.  Otherwise unset.

       TCP_LINE
              The last line read by tcp_read, and hence also tcp_expect.

       TCP_LINE_FD
              The   file   descriptor   from   which   $TCP_LINE   was   read.
              ${tcp_by_fd[$TCP_LINE_FD]} will give the  corresponding  session
              name.

       tcp_lines
              Array.  The  set of lines read during the last call to tcp_read,
              including the last ($TCP_LINE).

       TCP_LOG
              May be set directly, although it is also controlled by  tcp_log.
              The  name  of  a  file to which output from all sessions will be
              sent.  The output is proceeded by the usual $TCP_PROMPT.  If  it
              is  not an absolute path name, it will follow the user’s current
              directory.

       TCP_LOG_SESS
              May be set directly, although it is also controlled by  tcp_log.
              The  prefix for a set of files to which output from each session
              separately   will   be    sent;    the    full    filename    is
              ${TCP_LOG_SESS}.sess.   Output to each file is raw; no prompt is
              added.  If it is not an absolute path name, it will  follow  the
              user’s current directory.

       tcp_no_spam_list
              Array.  May be set directly.  See tcp_spam for how this is used.

       TCP_OUTPUT
              May be set directly.  If a non-empty string, any data sent to  a
              session  by  tcp_send  will be logged.  This parameter gives the
              prompt to be used in a file specified by $TCP_LOG but not  in  a
              file  generated  from  $TCP_LOG_SESS.  The prompt string has the
              same format as TCP_PROMPT and the same rules for its use  apply.

       TCP_PROMPT
              May  be  set  directly.   Used  as  the  prefix for data read by
              tcp_read which is printed to standard output or to the log  file
              given  by $TCP_LOG, if any.  Any ‘%s’, ‘%f’ or ‘%%’ occurring in
              the string will be replaced by the name of the session, the ses-
              sion’s  underlying  file  descriptor,  or  a single ‘%’, respec-
              tively.  The expression ‘%c’ expands to 1 if the  session  being
              read  is  the  current  session,  else 0; this is most useful in
              ternary expressions such as ‘%(c.-.+)’ which outputs ‘+’ if  the
              session is the current one, else ‘-’.

       TCP_READ_DEBUG
              May be set directly.  If this has non-zero length, tcp_read will
              give some limited diagnostics about data being read.

       TCP_SECONDS_START
              This value is created and initialised to zero by tcp_open.

              The functions tcp_read and tcp_expect use  the  shell’s  SECONDS
              parameter  for  their own timing purposes.  If that parameter is
              not of floating point type on entry to one of the functions,  it
              will  create  a  local parameter SECONDS which is floating point
              and set the parameter TCP_SECONDS_START to the previous value of
              $SECONDS.   If  the  parameter  is already floating point, it is
              used without a local copy being created and TCP_SECONDS_START is
              not set.  As the global value is zero, the shell elapsed time is
              guaranteed to be the sum of $SECONDS and $TCP_SECONDS_START.

              This can be avoided by setting SECONDS globally  to  a  floating
              point  value  using ‘typeset -F SECONDS’; then the TCP functions
              will never make a local copy and never set TCP_SECONDS_START  to
              a non-zero value.

       TCP_SESS
              May  be set directly.  The current session; must refer to one of
              the sessions established by tcp_open.

       TCP_SILENT
              May be set directly, although it is also controlled by  tcp_log.
              If of non-zero length, data read by tcp_read will not be written
              to standard output, though may still be written to a log file.

       tcp_spam_list
              Array.  May be set directly.  See the description of  the  func-
              tion tcp_spam for how this is used.

       TCP_TALK_ESCAPE
              May  be  set  directly.   See  the  description  of the function
              tcp_talk for how this is used.

       TCP_TIMEOUT
              May be set directly.  Currently this is only used by  the  func-
              tion tcp_command, see above.



TCP USER-DEFINED PARAMETERS

       The following parameters are not set by the function system, but have a
       special effect if set by the user.

       tcp_on_read
              This should be an associative array; if it is not, the behaviour
              is undefined.  Each key is the name of a shell function or other
              command, and the corresponding value is a shell  pattern  (using
              EXTENDED_GLOB).   Every line read from a TCP session directly or
              indirectly  using  tcp_read  (which  includes  lines   read   by
              tcp_expect)  is  compared  against  the  pattern.   If  the line
              matches, the command given in the key is called with  two  argu-
              ments: the name of the session from which the line was read, and
              the line itself.

              If any function called to handle a line returns a non-zero  sta-
              tus,  the  line  is not output.  Thus a tcp_on_read handler con-
              taining only the instruction ‘return 1’ can be used to  suppress
              output  of  particular  lines  (see, however, tcp_filter above).
              However, the line is still stored  in  TCP_LINE  and  tcp_lines;
              this occurs after all tcp_on_read processing.



TCP UTILITY PARAMETERS

       These  parameters  are  controlled  by the function system; they may be
       read directly, but should not usually be set by user code.

       tcp_aliases
              Associative array.  The keys are the names  of  sessions  estab-
              lished  with  tcp_open;  each value is a space-separated list of
              aliases which refer to that session.

       tcp_by_fd
              Associative array.  The keys are session file descriptors;  each
              value is the name of that session.

       tcp_by_name
              Associative  array.   The  keys  are the names of sessions; each
              value is the file descriptor associated with that session.



TCP EXAMPLES

       Here is a trivial example using a remote calculator.

       TO create a calculator server on port 7337 (see the dc manual page  for
       quite how infuriating the underlying command is):

              tcp_proxy 7337 dc

       To connect to this from the same host with a session also named ‘dc’:

              tcp_open localhost 7337 dc

       To send a command to the remote session and wait a short while for out-
       put (assuming dc is the current session):

              tcp_command 2 4 + p

       To close the session:

              tcp_close

       The tcp_proxy needs to be killed to be stopped.   Note  this  will  not
       usually kill any connections which have already been accepted, and also
       that the port is not immediately available for reuse.

       The following chunk of code puts a  list  of  sessions  into  an  xterm
       header, with the current session followed by a star.

              print -n "\033]2;TCP:" ${(k)tcp_by_name:/$TCP_SESS/$TCP_SESS\*} "\a"



TCP BUGS

       The  function  tcp_read  uses the shell’s normal read builtin.  As this
       reads a complete line at once, data arriving without a terminating new-
       line can cause the function to block indefinitely.

       Though  the  function suite works well for interactive use and for data
       arriving in small amounts, the performance when large amounts  of  data
ZSHZFTPSYS(1)                                                    ZSHZFTPSYS(1)



       are being exchanged is likely to be extremely poor.


NAME

       zshzftpsys - zftp function front-end


DESCRIPTION

       This describes the set of shell functions supplied with the source dis-
       tribution as an interface to the zftp builtin command, allowing you  to
       perform  FTP operations from the shell command line or within functions
       or scripts.  The interface is similar to a traditional FTP client (e.g.
       the  ftp command itself, see ftp(1)), but as it is entirely done within
       the shell all the familiar completion, editing and  globbing  features,
       and  so on, are present, and macros are particularly simple to write as
       they are just ordinary shell functions.

       The prerequisite is that the zftp  command,  as  described  in  zshmod-
       ules(1)  ,  must  be  available in the version of zsh installed at your
       site.  If the shell is configured to load new commands at run time,  it
       probably  is:  typing  ‘zmodload zsh/zftp’ will make sure (if that runs
       silently, it has worked).  If this is not the case, it is possible zftp
       was  linked  into the shell anyway: to test this, type ‘which zftp’ and
       if zftp is available you will get the  message  ‘zftp:  shell  built-in
       command’.

       Commands  given  directly with zftp builtin may be interspersed between
       the functions in this suite; in a few cases, using  zftp  directly  may
       cause  some  of  the  status  information stored in shell parameters to
       become invalid.  Note in particular the description  of  the  variables
       $ZFTP_TMOUT, $ZFTP_PREFS and $ZFTP_VERBOSE for zftp.




INSTALLATION

       You  should  make sure all the functions from the Functions/Zftp direc-
       tory of the source distribution are available; they all begin with  the
       two letters ‘zf’.  They may already have been installed on your system;
       otherwise, you will need to find them and  copy  them.   The  directory
       should  appear  as one of the elements of the $fpath array (this should
       already be the case if they were installed), and at least the  function
       zfinit  should  be  autoloaded; it will autoload the rest.  Finally, to
       initialize the use of the system you need to call the zfinit  function.
       The  following  code  in  your .zshrc will arrange for this; assume the
       functions are stored in the directory ~/myfns:

              fpath=(~/myfns $fpath)
              autoload -U zfinit
              zfinit

       Note that zfinit assumes you are using the zmodload method to load  the
       zftp  command.  If it is already built into the shell, change zfinit to
       zfinit -n.  It is helpful (though not essential) if the call to  zfinit
       appears  after  any  code to initialize the new completion system, else
       unnecessary compctl commands will be given.



FUNCTIONS

       The sequence of operations in performing a file transfer is essentially
       the  same  as that in a standard FTP client.  Note that, due to a quirk
       of the shell’s getopts builtin, for those functions that handle options
       you must use ‘--’ rather than ‘-’ to ensure the remaining arguments are
       treated literally (a single ‘-’ is treated as an argument).


   Opening a connection
       zfparams [ host [ user [ password ... ] ] ]
              Set or show the parameters for a future  zfopen  with  no  argu-
              ments.   If  no  arguments are given, the current parameters are
              displayed (the password will be shown as a line  of  asterisks).
              If a host is given, and either the user or password is not, they
              will be prompted for; also, any parameter given as ‘?’  will  be
              prompted  for, and if the ‘?’ is followed by a string, that will
              be used as the prompt.  As zfopen calls zfparams  to  store  the
              parameters, this usually need not be called directly.

              A  single  argument ‘-’ will delete the stored parameters.  This
              will also cause the memory of the last directory (and so on)  on
              the other host to be deleted.

       zfopen [ -1 ] [ host [ user [ password [ account ] ] ] ]
              If  host  is present, open a connection to that host under user-
              name user with password password (and,  on  the  rare  occasions
              when  it is necessary, account account).  If a necessary parame-
              ter is missing or given as ‘?’ it will be prompted for.  If host
              is not present, use a previously stored set of parameters.

              If  the  command  was successful, and the terminal is compatible
              with xterm or is sun-cmd, a summary will  appear  in  the  title
              bar,  giving the local host:directory and the remote host:direc-
              tory; this is handled  by  the  function  zftp_chpwd,  described
              below.

              Normally,  the  host,  user and password are internally recorded
              for later re-opening, either by a zfopen with no  arguments,  or
              automatically (see below).  With the option ‘-1’, no information
              is stored.  Also, if an open command with arguments failed,  the
              parameters  will  not  be  retained (and any previous parameters
              will also be deleted).  A zfopen on its own,  or  a  zfopen  -1,
              never alters the stored parameters.

              Both zfopen and zfanon (but not zfparams) understand URLs of the
              form ftp://host/path... as meaning to connect to the host,  then
              change  directory  to  path  (which  must  be a directory, not a
              file).  The ‘ftp://’ can be omitted; the trailing ‘/’ is  enough
              to  trigger  recognition  of the path.  Note prefixes other than
              ‘ftp:’ are not recognized, and that  all  characters  after  the
              first slash beyond host are significant in path.

       zfanon [ -1 ] host
              Open  a connection host for anonymous FTP.  The username used is
              ‘anonymous’.  The password (which will  be  reported  the  first
              time)  is  generated  as  user@host;  this is then stored in the
              shell parameter $EMAIL_ADDR which can alternatively be set manu-
              ally to a suitable string.


   Directory management
       zfcd [ dir ]
       zfcd -
       zfcd old new
              Change  the  current  directory  on  the remote server:  this is
              implemented to have many of the features of  the  shell  builtin
              cd.

              In the first form with dir present, change to the directory dir.
              The command ‘zfcd ..’ is treated specially, so is guaranteed  to
              work  on  non-UNIX  servers  (note this is handled internally by
              zftp).  If dir is omitted, has the effect of ‘zfcd ~’.

              The second form changes to the directory previously current.

              The third form attempts  to  change  the  current  directory  by
              replacing the first occurrence of the string old with the string
              new in the current directory.

              Note that in this command, and indeed anywhere a remote filename
              is  expected,  the string which on the local host corresponds to
              ‘~’ is converted back to a ‘~’ before being passed to the remote
              machine.   This  is  convenient  because of the way expansion is
              performed on the command line before  zfcd  receives  a  string.
              For  example,  suppose  the  command is ‘zfcd ~/foo’.  The shell
              will   expand   this   to   a   full   path   such   as    ‘zfcd
              /home/user2/pws/foo’.   At  this stage, zfcd recognises the ini-
              tial path as corresponding to ‘~’ and will send the directory to
              the  remote  host  as ~/foo, so that the ‘~’ will be expanded by
              the server to the correct remote host  directory.   Other  named
              directories of the form ‘~name’ are not treated in this fashion.

       zfhere Change directory on the remote server to the  one  corresponding
              to  the current local directory, with special handling of ‘~’ as
              in zfcd.   For  example,  if  the  current  local  directory  is
              ~/foo/bar,  then zfhere performs the effect of ‘zfcd ~/foo/bar’.

       zfdir [ -rfd ] [ - ] [ dir-options ] [ dir ]
              Produce a long directory listing.  The arguments dir-options and
              dir are passed directly to the server and their effect is imple-
              mentation dependent, but specifying a particular  remote  direc-
              tory  dir  is  usually possible.  The output is passed through a
              pager given by the environment variable  $PAGER,  or  ‘more’  if
              that is not set.

              The directory is usually cached for re-use.  In fact, two caches
              are maintained.  One is for use when there is no dir-options  or
              dir,  i.e. a full listing of the current remote directory; it is
              flushed when the current remote directory changes.  The other is
              kept  for  repeated  use  of  zfdir with the same arguments; for
              example, repeated use of ‘zfdir /pub/gnu’ will only require  the
              directory  to  be  retrieved  on the first call.  Alternatively,
              this cache can be re-viewed with the  -r  option.   As  relative
              directories  will  confuse  zfdir,  the -f option can be used to
              force the cache to be flushed before the  directory  is  listed.
              The  option  -d will delete both caches without showing a direc-
              tory listing; it will also delete the cache of file names in the
              current remote directory, if any.

       zfls [ ls-options ] [ dir ]
              List  files  on the remote server.  With no arguments, this will
              produce a simple list of  file  names  for  the  current  remote
              directory.  Any arguments are passed directly to the server.  No
              pager and no caching is used.


   Status commands
       zftype [ type ]
              With no arguments, show the type of data to be transferred, usu-
              ally  ASCII  or  binary.  With an argument, change the type: the
              types ‘A’ or ‘ASCII’ for ASCII data and ‘B’ or ‘BINARY’, ‘I’  or
              ‘IMAGE’ for binary data are understood case-insensitively.

       zfstat [ -v ]
              Show  the  status  of the current or last connection, as well as
              the status of some of zftp’s  status  variables.   With  the  -v
              option,  a  more  verbose  listing  is  produced by querying the
              server for its version of events, too.


   Retrieving files
       The commands for retrieving files all take at  least  two  options.  -G
       suppresses remote filename expansion which would otherwise be performed
       (see below for a more detailed description of that).   -t  attempts  to
       set the modification time of the local file to that of the remote file:
       this requires version 5 of perl, see the description  of  the  function
       zfrtime below for more information.

       zfget [ -Gtc ] file1 ...
              Retrieve  all  the listed files file1 ... one at a time from the
              remote server.  If a file contains  a  ‘/’,  the  full  name  is
              passed  to  the  remote  server,  but the file is stored locally
              under the name given by the  part  after  the  final  ‘/’.   The
              option  -c  (cat) forces all files to be sent as a single stream
              to standard output; in this case the -t option has no effect.

       zfuget [ -Gvst ] file1 ...
              As zfget, but only retrieve  files  where  the  version  on  the
              remote server is newer (has a later modification time), or where
              the local file does not exist.  If the remote file is older  but
              the files have different sizes, or if the sizes are the same but
              the remote file is newer, the  user  will  usually  be  queried.
              With  the  option  -s, the command runs silently and will always
              retrieve the file in either of those two cases.  With the option
              -v, the command prints more information about the files while it
              is working out whether or not to transfer them.

       zfcget [ -Gt ] file1 ...
              As zfget, but if any of the local files exists, and  is  shorter
              than  the corresponding remote file, the command assumes that it
              is the result of a partially completed transfer and attempts  to
              transfer the rest of the file.  This is useful on a poor connec-
              tion which keeps failing.

              Note that this requires a commonly  implemented,  but  non-stan-
              dard,  version of the FTP protocol, so is not guaranteed to work
              on all servers.

       zfgcp [ -Gt ] remote-file local-file
       zfgcp [ -Gt ] rfile1 ... ldir
              This retrieves files  from  the  remote  server  with  arguments
              behaving similarly to the cp command.

              In the first form, copy remote-file from the server to the local
              file local-file.

              In the second form, copy all the remote files  rfile1  ...