Welcome to Linux Knowledge Base and Tutorial
"The place where you learn linux"
International Rescue Committe

 Create an AccountHome | Submit News | Your Account  

Tutorial Menu
Linux Tutorial Home
Table of Contents

· Introduction to Operating Systems
· Linux Basics
· Working with the System
· Shells and Utilities
· Editing Files
· Basic Administration
· The Operating System
· The X Windowing System
· The Computer Itself
· Networking
· System Monitoring
· Solving Problems
· Security
· Installing and Upgrading
· Linux and Windows

Man Pages
Linux Topics
Test Your Knowledge

Site Menu
Site Map
Copyright Info
Terms of Use
Privacy Info
Masthead / Impressum
Your Account

Private Messages

News Archive
Submit News
User Articles
Web Links


The Web

Who's Online
There are currently, 88 guest(s) and 0 member(s) that are online.

You are an Anonymous user. You can register for free by clicking here




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

       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


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


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


       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














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


       Zsh has 3 mailing lists:

              Announcements  about releases, major changes in the
              shell and the  monthly  posting  of  the  Zsh  FAQ.


       NESTED.  All submissions to zsh-announce are automatically
       forwarded to zsh-users.  All submissions to zsh-users  are
       automatically forwarded to zsh-workers.

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

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


       Zsh has a list of Frequently Asked Questions (FAQ),  main­
       tained 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>.


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


       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  `hiero­
       graphic' does not exist).  It can be viewed in its current
       state at http://zsh.sunsite.dk/Guide/.   At  the  time  of
       writing,  chapters  dealing  with  startup files and their
       contents and the new completion  system  were  essentially


       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 spe­
       cial permission.  You can add your own zsh tips  and  con­


              ment  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  appropri­
       ated  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 cor­
       responding 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  sin­
       gle-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  can­
       not  be  stacked  with  any  other options, so for example
       `-x-shwordsplit' is an error, rather  than  being  treated
       like `-x --shwordsplit'.

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

       Option  processing  may  be  finished,  allowing following
       arguments that start with `-' or `+' to be treated as nor­
       mal  arguments, in two ways.  Firstly, a lone `-' (or `+')
       as an argument by itself  ends  option  processing.   Sec­
       ondly, 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 equiva­
       lent 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 per­
       initial `r' (assumed to stand for  `restricted'),  and  if
       that  is  `s'  or `k' it will emulate sh or ksh.  Further­
       more, 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  envi­
       ronment variable and perform emulation based on that.

       In sh and ksh compatibility modes the following parameters
       are not special and not initialized by  the  shell:  ARGC,
       argv,  cdpath,  fignore,  fpath, HISTCHARS, mailpath, MAN­
       PATH, 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/.pro­
       file.   If  the ENV environment variable is set on invoca­
       tion, $ENV is sourced  after  the  profile  scripts.   The
       value  of ENV is subjected to parameter expansion, command
       substitution, and arithmetic expansion before being inter­
       preted  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,
       SH_WORD_SPLIT.      Additionally    the    BSD_ECHO    and
       IGNORE_BRACES options are set if zsh  is  invoked  as  sh.
       PROMPT_SUBST and SINGLE_LINE_ZLE options are set if zsh is
       invoked as ksh.


       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 /
       ·      turning off restricted mode with set +r or unsetopt

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

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


       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/zpro­
       file  and  then $ZDOTDIR/.zprofile.  Then, if the shell is
       interactive, commands are read from  /etc/zshrc  and  then
       $ZDOTDIR/.zshrc.   Finally, if the shell is a login shell,
       /etc/zlogin and $ZDOTDIR/.zlogin are read.

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

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

       As  /etc/zshenv  is  run  for  all instances of zsh, it is
       important that it be kept as small as possible.   In  par­
       ticular,  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 exe­


       A simple command  is  a  sequence  of  optional  parameter
       assignments   followed   by  blank-separated  words,  with
       optional redirections interspersed.  The first word is the
       command  to  be executed, and the remaining words, if any,
       are arguments to the command.  If a command name is given,
       the  parameter  assignments  modify the environment of the
       command when it is executed.  The value of a  simple  com­
       mand  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 sepa­
       rated 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  stan­
       dard  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 sec­

       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 con­
       trol is active, the coprocess can be treated in other than
       input and output as an ordinary background job.

       A  sublist  is  either a single pipeline, or a sequence of
       two or more pipelines separated by `&&' or `||'.   If  two
       pipelines  are  separated  by `&&', the second pipeline is
       executed only  if  the  first  succeeds  (returns  a  zero
       value).   If two pipelines are separated by `||', the sec­
       ond 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,
       list is terminated by `;' or newline, the shell waits  for
       it to finish before executing the next sublist.  If a sub­
       list is terminated by a `&', `&|', or `&!', the shell exe­
       cutes  the last pipeline in it in the background, and does
       not wait for it to finish (note the difference from  other
       shells which execute the whole sublist in the background).
       A backgrounded pipeline returns a status of zero.

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


       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.

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

       exec   The command is executed in the parent shell without

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

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


       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
              execution of the loop the next N words are assigned
              to the corresponding parameters.  If there are more
              names than remaining words, the  remaining  parame­
              ters  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  section  `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  pat­
              terns is the same as that used for filename genera­
              tion.  See the section `Filename  Generation'.   If
              the  list  that  is  executed is terminated with ;&
              rather than ;;, the following  list  is  also  exe­
              cuted.   This continues until either a list is ter­
              minated 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 parame­
              ter name is set to the word corresponding  to  this

       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

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

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


       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

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

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

                     if [[ -o ignorebraces ]] {

              tations on the form of list apply as for the previ­
              ous 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.


       The following words are recognized as reserved words  when
       used  as the first word of a command unless quoted or dis­
       abled 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.


       In  noninteractive  shells,  or in interactive shells with
       the INTERACTIVE_COMMENTS option set, a word beginning with
       the  third  character  of  the histchars parameter (`#' by
       default) causes that word and all the following characters
       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.


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

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

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

              print ''''

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

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


       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 specifi­

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

       < 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  cre­
              Open  file word for writing in append mode as stan­
              dard output.  If the file does not exist,  and  the
              CLOBBER option is unset, this causes an error; oth­
              erwise, the file is created.

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

       <<[-] word
              The  shell  input  is read up to a line that is the
              same as word, or to an end-of-file.   No  parameter
              expansion, command substitution or filename genera­
              tion 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, `\' fol­
              lowed by a newline is removed, and `\' must be used
              to quote the characters `\', `$', ``' and the first
              character of word.

              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.

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

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

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

              ... 1>fname 2>&1

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

       The `|&' command separator described in 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  repre­
       sented by list.  See Process Substitution in zshexpn(1).


       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 speci­
       fied 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

       If the MULTIOS option is set, the word after a redirection
       operator is also subjected to filename  generation  (glob­
       bing).  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.   How­
       ever, 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 dis­
       play the full contents of file1 and file2 (i.e. the origi­
       nal contents of file repeated twice).

       The  reason for this is that the multios are spawned after
       the cat process is forked from the parent  shell,  so  the
       parent shell does not wait for the multios to finish writ­
       ing 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.


       When a simple command consists of one or more  redirection
       operators  and  zero or more parameter assignments, but no
       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.


       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 unsuccessful, the shell prints an error mes­
       sage 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 pro­
       gram.  The shell will execute the specified interpreter on
       operating  systems that do not handle this executable for­
       mat in the kernel.


       Shell functions are defined  with  the  function  reserved
       word or the special syntax `funcname ()'.  Shell functions
       are read  in  and  stored  internally.   Alias  names  are
       resolved  when  the  function is read.  Functions are exe­
       cuted 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 environment of the

       The return builtin is used to return from function  calls.

       Function  identifiers  can  be  listed  with the functions
       builtin.  Functions can be undefined with  the  unfunction

       tions  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 cre­
       ated, as the corresponding information  is  compiled  into
       the latter.

       For  each element in fpath, the shell looks for three pos­
       sible files, the newest of which is used to load the defi­
       nition for the function:

              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 func­
              tion  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.

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

              A file of zsh command text, taken to be the defini­
              tion for function.

       In summary, the order of searching is, first, in the  par­
       ents  of  directories  in  fpath for the newer of either a
       compiled directory or a directory  in  fpath;  second,  if
       more than one of these contains a definition for the func­
       tion that is sought, the leftmost in the fpath is  chosen;
       and  third, within a directory, the newer of either a com­
       piled function or an ordinary function definition is used.

       initialization and then call  the  function  defined,  the
       file  should  contain  initialization  code (which will be
       executed then discarded) in addition to a  complete  func­
       tion  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 initialization  mes­
       sage  on the first call, and the other message on the sec­
       ond 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 following are equivalent:

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


              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 identified by the presence of the comment `#  unde­
       fined'  in  the  body,  because all comments are discarded
       from defined functions.

       To load the definition of an  autoloaded  function  myfunc
       without executing myfunc, use:

              autoload +X myfunc

              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 exe­
              cuted (including expanded aliases) is passed in two
              different forms: the  second  argument  is  a  sin­
              gle-line, size-limited version of the command (with
              things like  function  bodies  elided);  the  third
              argument  contains the full text that is being exe­

              If defined and non-null, this function will be exe­
              cuted  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 SIG­

              Executed after each command.

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

              Executed  whenever  a  command  has a non-zero exit
              status.  However, 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  envi­
       ronment.   Apart  from the difference in calling procedure
       and the fact that the function form appears  in  lists  of
       functions, the forms

              TRAPNAL() {
               # code

              [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 con­
       trol 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 `suspended', and
       print another prompt.  You can then manipulate  the  state
       of this job, putting it in the background with the bg com­
       mand, or run some other commands and then eventually bring
       the  job back into the foreground with the foreground com­
       mand fg.  A ^Z takes effect immediately  and  is  like  an
       interrupt in that pending output and unread input are dis­
       carded 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 suspended.  This (intentionally) does
       not apply if the command is continued  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:

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

       pended  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


       The INT and  QUIT  signals  for  an  invoked  command  are
       ignored  if the command is followed by `&' and the MONITOR
       option is not active.  Otherwise, signals have the  values
       inherited  by the shell from its parent (but see the TRAP­
       NAL special functions in the section `Functions').


       The shell can perform integer and  floating  point  arith­
       metic, 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

       The let builtin command takes  arithmetic  expressions  as
       arguments;  each  is  evaluated separately.  Since many of
       the arithmetic operators, as well as spaces, require quot­
       ing,  an  alternative  form  is  provided: for any command
       which begins with a  `((',  all  the  characters  until  a
       matching  `))'  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 hex­
       adecimal).  The base# may also be omitted, in  which  case
       base  10  is  used.   For backwards compatibility the form
       `[base]n' is also accepted.

              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  output  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  hexadeci­
       mal  and octal, and these formats are always understood on

       When an output base is specified using the `[#base]'  syn­
       tax,  an  appropriate base prefix will be output if neces­
       sary, so that the value output 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 param­
       eter name.

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

       + - ! ~ ++ --
              unary    plus/minus,   logical   NOT,   complement,
       << >>  bitwise shift left, right
       &      bitwise AND
       ^      bitwise XOR
       |      bitwise OR
       **     exponentiation
       * / %  multiplication, division, modulus (remainder)
       + -    addition, subtraction
       < > <= >=
       == !=  equality and inequality
       &&     logical AND
       expressions. The shell currently defines  no  mathematical
       functions  by  default, but the module zsh/mathfunc may be
       loaded with  the  zmodload  builtin  to  provide  standard
       floating point mathematical functions.

       An  expression  of the form `##x' where x is any character
       sequence such as `a', `^A', or `\M-\C-x' gives  the  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 different
       from the expression `$#foo', a standard parameter  substi­
       tution  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

       An  internal  integer  representation of a named parameter
       can be specified 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 sub­
       stitution 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  necessary.   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 with­
       out previously being declared, it will be implicitly typed
       as  integer or float and retain that type either until the
       variables with explicit types.


       A conditional expression is used with the [[ compound com­
       mand  to  test attributes of files and to compare strings.
       Each expression can be constructed from one or more of the
       following unary or binary expressions:

       -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

       -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 character, in which case it is a single let­
              ter option  name.   (See  the  section  `Specifying

       -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 pro­

       -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

       -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

       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

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

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


       Prompt sequences undergo  a  special  form  of  expansion.
       This  type  of  expansion  is  also available using the -P
       option to the print builtin.

       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 defi­
              nition 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-interac­

       %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

       %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 integer  may
              follow the `%' to specify a number of trailing path
              components to show; zero means the  full  path.   A
              negative integer specifies leading components.

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

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

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

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

       %*     Current  time  of  day in 24-hour format, with sec­

       %w     The date in day-dd format.

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

              string is formatted using  the  strftime  function.
              See strftime(3) for more details.  Three additional
              codes are available:  %f  prints  the  day  of  the
              month,  like  %e but without any preceding 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.

              Include a string as a literal escape sequence.  The
              string within the braces should not change the cur­
              sor 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.

              Specifies a ternary expression.  The character fol­
              lowing 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 following:

              !      True if the shell  is  running  with  privi­
              #      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
              /      True if the current  absolute  path  has  at
                     least n elements.
              ~      True   if  the  current  path,  with  prefix
                     replacement, has at least n elements.
              D      True if the month is equal to n  (January  =
              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.
              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 displayed in place of the truncated portion
              of  any  string;  note this does not undergo prompt

              The forms with `<' truncate  at  the  left  of  the
              string,  and  the  forms  with  `>' truncate at the
              right of the string.  For example, if  the  current
              directory  is  `/home/pike',  the prompt `%8<..<%/'
              will expand to `..e/pike'.   In  this  string,  the
              terminating character (`<', `>' or `]'), or in fact
              any character, may be quoted by  a  preceding  `\';
              note  when  using print -P, however, that this must
              be doubled as the string is also subject  to  stan­
              dard  print  processing,  in  addition to any back­
              slashes removed by a  double  quoted  string:   the
              worst case is therefore `print -P "%<\\\\<<..."'.

              If  the string is longer than the specified trunca­
              tion 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)


       zshexpn - zsh expansion and substitution


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

       History Expansion
              This is performed only in interactive shells.

       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  per­
              formed immediately after alias expansion, 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


       History expansion allows you to use  words  from  previous
       command  lines  in  the command line you are typing.  This
       simplifies spelling corrections and the repetition of com­
       plicated commands or arguments.  Immediately before execu­
       tion, 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.

       A history expansion begins with the first character of the
       histchars parameter, which is  `!'  by  default,  and  may
       occur  anywhere on the command 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 Desig­
       nators'); 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  ref­

       By  default,  a history reference with no event designator
       refers to the same event as any preceding  history  refer­
       the  nearest other history reference preceding them on the
       current command line, or to the previous 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, replacing the string foo with bar.  More
       precisely, the sequence  `^foo^bar^'  is  synonymous  with
       `!!:s^foo^bar^',  hence  other  modifiers (see the section
       `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 support is provided by the fc builtin.

   Event Designators
       An event designator is a reference to a command-line entry
       in the history list.  In the list below, remember that the
       initial `!' in each item may be changed to another charac­
       ter by setting the histchars parameter.

       !      Start a history expansion, except when followed  by
              a  blank, newline, `=' or `('.  If followed immedi­
              ately by a word designator (see the  section  `Word
              Designators'),  this forms a history reference 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.

              Refer to the most recent  command  containing  str.
              The  trailing `?' is necessary if this reference is
              to be followed by a modifier  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 `!#'

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

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

       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  sub­
              stitutions.    Works  with  history  expansion  and
              parameter expansion, though for  parameters  it  is
              only useful if the resulting text is to be re-eval­
              uated such as by eval.

       Q      Remove one level of  quotes  from  the  substituted

       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.

       character  strings.   Any  character  can  be  used as the
       delimiter in place of `/'.  A backslash quotes the  delim­
       iter 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  immediately  follows  r;
       the rightmost `?' in a context scan can similarly be omit­
       ted.  Note the same record of the last l and  r  is  main­
       tained across all forms of expansion.

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

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

              Like f, but repeats only n times if the  expression
              expr  evaluates  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.


       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  asyn­
       chronously.  If the system supports the /dev/fd mechanism,
       the command argument is the name of the device file corre­
       sponding  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 con­
       nected to the output of the list process.  For example,

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

       command line, particularly if this is necessary for  secu­
       rity reasons such as when the programme is running setuid.
       In the second case, if the  programme  does  not  actually
       open  the  file,  the  subshell attempting to read from or
       write to the pipe will (in a typical implementation,  dif­
       ferent  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 efficiently written (provided the  MULTIOS  option  is
       set) as:

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

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

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

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

       (note that no MULTIOS are involved), process will  be  run
       asynchronously.  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.


       The character `$' is used to  introduce  parameter  expan­
       sions.   See  zshparam(1) for a description of parameters,
       including arrays, associative arrays, and subscript  nota­
       tion to access individual array elements.

       Note in particular the fact that words of unquoted parame­
       ters 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.

              tuted.  The braces are required if the expansion is
              to  be  followed  by a letter, 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;  excep­
              tions, which only apply if the option KSH_ARRAYS is
              not set, are a single subscript or any colon  modi­
              fiers appearing after the name, or any of the char­
              acters `^', `=', `~', `#' 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.  Oth­
              erwise,  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.

              If name is the name of a set parameter `1' is  sub­
              stituted, otherwise `0' is substituted.

              If  name is set and is non-null then substitute its
              value; otherwise substitute word. If name is  miss­
              ing, substitute 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.

              If name is set and is non-null then substitute  its
              value;  otherwise,  print  word  and  exit from the
              shell.  Interactive shells instead  return  to  the
              prompt.   If  word is omitted, then a standard mes­
              sage is printed.

              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 substitution is not quoted, or if the  `(@)'  flag  or
              If  the  pattern  matches  the  end 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.

              If the pattern matches the value of name, then sub­
              stitute  the  empty string; otherwise, just substi­
              tute 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).

              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  charac­
              ters  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

              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

              Turn on the RC_EXPAND_PARAM option for the  evalua­
              tion  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 pro­
              cessed as described in the  section  `Brace  Expan­
              sion'  below.   If word splitting is also in effect
              the $var[N] may themselves be split into  different
              list elements.

              Perform   word   splitting   using  the  rules  for
              SH_WORD_SPLIT during the evaluation  of  spec,  but
              regardless of whether the parameter appears in dou­
              ble 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

              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.

              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 `!=' opera­
              tors in conditions.

       If a ${...} type parameter expression  or  a  $(...)  type
       command substitution 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  fol­
       lowed  by  a  subscript  expression  as described in Array
       If the opening brace is directly followed  by  an  opening
       parenthesis,  the string up to the matching closing paren­
       thesis will be taken as a list of flags.  In  cases  where
       repeating  a  flag is meaningful, the repetitions need not
       be consecutive; for  example,  `(q%q%q)'  means  the  same
       thing as the more readable `(%%qqq)'.  The following flags
       are supported:

       %      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 sepa­
              rate 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 sorting or
              padding.  The name part may be a subscripted  range
              for  ordinary  arrays;  the  word part must be con­
              verted  to  an  array,   for   example   by   using
              `${(AA)=name=...}'  to  activate  field  splitting,
              when creating an associative array.

       a      With o or O, sort in array index order.  Note  that
              `oa'  is  therefore  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-alphanumerics, not to words that
              result from field splitting.

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

       f      Split the result of the expansion to lines. This is

       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 appropriate. 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  single
              quotes preceded by a $.

       Q      Remove  one  level  of  quotes  from  the resulting

       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 keyword in the string
              describes the main type, it can be one of `scalar',
              `array',  `integer',  `float' or `association'. The
              other keywords describe the type in more detail:

              local  for local parameters

              left   for left justified parameters

                     for right justified parameters with  leading

                     for  right justified parameters with leading

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

              upper  for  parameters  whose value is converted to
                     for special parameters defined by the shell

       u      Expand  only  the  first  occurrence of each unique

       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 subscripts, force  values
              to be substituted even if the subscript form refers
              to indices or keys.

       V      Make any special characters in the resulting  words

       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    expansions    as    in
              `${${(z)foo}[2]}'.  Likewise,  to remove the quotes
              in   the   resulting   words    one    would    do:

       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 delimiters
       must surround each argument.

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

              Join the words of arrays together using string as a
              As  l,  but  pad  the words on the right and insert
              string2 on the right.

              Force   field    splitting    (see    the    option
              SH_WORD_SPLIT)  at the separator string.  Note that
              a string of two or more characters means  all  must
              all match in sequence; this differs from the treat­
              ment of two or more characters in the  IFS  parame­

       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.

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

              The exprth match is  counted  such  that  there  is
              either one or zero matches from each starting posi­
              tion in the string, although for  global  substitu­
              tion  matches overlapping previous replacements 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 forward 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

       Here is a summary of  the  rules  for  substitution;  this
       assumes  that  braces are present around the substitution,
       i.e. ${...}.  Some particular examples  are  given  below.
       Note  that  the Zsh Development Group accepts no responsi­
       bility for any brain damage which  may  occur  during  the
       reading of the following rules.

       1. Nested Substitution
              If  multiple  nested ${...} forms are present, sub­
              stitution is performed from  the  inside  outwards.
              At  each  level,  the substitution 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
              substitution,  just  as  if the nested substitution
              were the outermost.  The flags are  not  propagated
              up to enclosing substitutions; the nested substitu­
              tion 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  sub­
              scripting  is  applied  directly  to the parameter.
              Subscripts are evaluated left to right;  subsequent
              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  num­
              ber 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 substitution 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
              "${${foo[2,4]}[2]}"   (the   nested    substitution
              returns a scalar because of the quotes).

       6. Modifiers
              Any modifiers, as specified by a trailing `#', `%',
              `/' (possibly 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 joining 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 pre­
              sent,  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 command 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

              This  produces the result b.  First, the inner sub­
              stitution "${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.

              This produces the result `bar'.  In this case,  the
              inner  substitution  "${(@)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

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

              produces the words `a', `1 b' and `1'.

              produces `a', `1', `b' and `1'.

              produces `a' and ` b' (note the extra  space).   As
              substitution occurs before either joining or split­
              ting, 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.


       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 substitution 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 out­
       put is eligible for filename generation.


       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 sec­
       order  the  resulting  sequence will also be in decreasing

       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 individ­
       ual  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 normally.

       Note that brace expansion is not part of filename  genera­
       tion  (globbing);  an  expression  such  as */{foo,bar} is
       split into two separate words */foo and */bar before file­
       name  generation  takes  place.   In particular, note that
       this is liable to produce a `no match' error if either  of
       the  two  expressions  does  not match; this is to be con­
       trasted with */(foo|bar), which is  treated  as  a  single
       pattern but otherwise has similar effects.


       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  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 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 system.  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
       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 `=' fol­
       lowing  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  eli­
       gible  for  file  expansion  as  described in the previous
       paragraph.  Quoting the first `=' also inhibits this.


       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;  otherwise
       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

       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 generation 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 char­
              acters 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

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

              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

              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 consequence of the rule that the longest
              possible  match  always succeeds.  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 file­
              name 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

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

       x~y    (Requires EXTENDED_GLOB to be set.)  Match anything
              that  matches  the  pattern x but does not match y.
              already followed 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  occurrences  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 modified 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 `(^(...))'.)

       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 pre­
       ceding unit (i.e. a character, `?', `[...]', `<...>', or a
       parenthesised expression).  As mentioned above, a `/' used
       as a directory separator may not appear  inside  parenthe­
       ses,  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 spe­
       cial; 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

       i      Case  insensitive:   upper or lower case characters
              in the pattern match upper or  lower  case  charac­
              array $mbegin, and the indices of the  end  in  the
              array  $mend,  with the first element 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 refer­

              For example,

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

              prints `string with a'.  Note that the first paren­
              thesis  is  before  the  (#b) and does not create a

              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 substitution,
              such as ${param//pat/repl}, only the data  for  the
              last  match  remains  available.   In  the  case of
              global replacements 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 paren­
              theses  may be necessary to match the complete seg­
              ment: 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

              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 back­
              references 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
              not local to a group. The parameters $MATCH,  $MBE­
              GIN 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,  printing  `vEldt  jynx  grImps wAqf zhO

              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 patterns other than those
              in filename generation (where path segments 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 exam­
              ple  `${array/(#s)A*Z(#e)}'  will  remove only ele­
              ments 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
              in  the  latter case the `(#b)' is useful for back­
              references 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 direc­
       tory 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

       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  characters  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 character).  Similarly, errors are
       counted  separately for non-contiguous strings in the pat­
       tern, so that (ab|cd)ef is two errors from aebf.

       (#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  exam­
       ple,  (#a1)abc(#a0)xyz will not match abcdxyz, because the
       error occurs at the `x',  where  approximation  is  turned

       Entire path segments may be matched approximately, so that
       `(#a1)/foo/d/is/available/at/the/bar' allows one error  in
       any  path segment.  This is much less efficient than with­
       out 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 segments which  are
       known to be correct.

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

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

              ls (*/)#bar


              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 otherwise  identical.
       Neither of these can be combined with other forms of glob­
       bing 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  spec­
       ify 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 paren­
       theses, in this case producing `((^x))'.
       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

       .      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
              tively,  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, indepen­
              dent of the permissions for other users.  The  pat­
              tern `*(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.

              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 status (usually the sta­
              tus  of  the  last  command).   The first character
              after the `e' will be used as a separator and  any­
              thing  up  to  the  next matching separator will be
              taken  as the string; `[', `{', and `<' match  `]',
              `}', and `>', respectively, while any other charac­
              ter 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  cur­
              rently  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

       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

              files  accessed exactly n days ago.  Files accessed
              within the last n days are selected using  a  nega­
              tive  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 sec­
              onds instead of days, respectively.  For  instance,
              `echo *(ah-5)' would echo files accessed within the
              last five hours.

              like the file access qualifier, except that it uses
              the file modification time.

              like the file access qualifier, except that it uses
              the file inode change time.

              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 performed with
              kilobytes, megabytes,  or  blocks  (of  512  bytes)

       ^      negates all qualifiers following it

       -      toggles  between making the qualifiers work on sym­
              bolic links (the default) and the files they  point

       M      sets the MARK_DIRS option for the current pattern

              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, modifi­
              cation, or inode change respectively; if  d,  files
              in  subdirectories  appear before those in the cur­
              rent 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.

              specifies which of the matched filenames should  be
              included  in  the  returned list. The syntax is the
              same as for array subscripts. beg and the  optional
              end  may be mathematical expressions. As in parame­
              ter 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 sub­
       lists matches (they are `or'ed, the qualifiers in the sub­
       lists 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  `Modifiers'  in  the  section  `History
       Expansion').   Note  that each modifier must be introduced
       by a separate `:'.  Note also that the result after  modi­
       fication  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 per­
       formed.  Thus:

              ls *(-/)

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

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

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

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

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



       zshparam - zsh parameters


       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  numeri­
       cally),  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:


       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 Parameters' for addi­
       tional forms of assignment.

       To  refer  to  the  value of a parameter, write `$name' or
       `${name}'.  See Parameter Expansion in zshexpn(1) for com­
       plete details.

       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

              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

   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  expansion  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 expres­
       sions still apply, which affects the way that certain spe­
       cial  characters  must  be  protected from interpretation.
       See Subscript Parsing below for details.

       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:


       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, shift­
       ing the other elements  to  accommodate  the  new  values.
       (This is not supported for associative arrays.)

       This  syntax also works as an argument to the typeset com­

              typeset "name[exp]"=value

       The value may not be a parenthesized list  in  this  case;
       only  single-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

       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

       f      If  the parameter subscripted is a scalar than this
              flag makes subscripting work on  lines  instead  of
              characters,  i.e.  with  elements separated by new­
              lines.  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 element, so that pairs of subscripts  such
              as `$foo[(r)??,3]' and `$foo[(r)??,(r)f*]' are pos­
              sible.  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.   Reverse
              subscripts  may  be  used for assigning to ordinary
              array elements, but not for assigning  to  associa­
              tive arrays.

       R      Like  `r',  but gives the last match.  For associa­
              tive arrays, gives all possible matches.

       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 pat­
              terns,  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 associative array element.  If used  on  another
              type of parameter, this behaves like `r'.

       K      On  an  associative  array  this  is  like  `k' but
              returns all values where  exp  is  matched  by  the
              keys.   On  other  types of parameters this has the
              same effect as `R'.

              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

       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 parame­
       ter  substitutions  that  appear  as part of an arithmetic
       expression in an ordinary subscript.

       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 sub­
       script expressions (or  both!),  so  the  rules  have  two
       important differences.

       The  first  difference is that brackets (`[' and `]') must
       appear as balanced 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
       normally  required;  for  example,  the pattern `[^[]' (to
       match any character other than an open bracket) should  be
       written  `[^\[]' in a reverse-subscript 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  backslash,  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 parenthesis.

       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  char­
       acters  `\"' 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  dou­
       ble-quote  characters,  but the reason for this difference
       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

       A  further  complication  arises  from a way in which sub­
       script 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 associative
       array key, the `e' flag must be used:

              typeset -A aa
              print $aa[(e)*]

       A last detail must be considered when reverse subscripting
       is  performed.   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 sub­
       script, it's necessary to use four backslashes 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 com­
       plete 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  zsh­
       expn(1)) to quote the expanded value.

       Note  that  the `k' and `K' flags are reverse subscripting
       for an ordinary 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

       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  subscript  syntax to
       extract a  substring  from  a  positional  parameter,  the
       expansion  must  be  surrounded  by  braces;  for example,

       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 positional parame­
       ter 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 assignment of the form `n=(value ...)'
       is allowed, and has the effect of shifting all the  values
       at positions greater than n by as many positions as neces­
       sary to accommodate the new values.


       Shell function executions delimit scopes for shell parame­
       ters.   (Parameters  are dynamically scoped.)  The typeset
       builtin, and its alternative 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  parameter  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 out­
       ermost 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 hid­

       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 parameters were never exported has been removed.

       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
              FUNCTION_ARGZERO option is set, this  is  set  tem­
              porarily 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  com­

              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 sufficient privileges, you may change the
              effective group ID of the shell process by  assign­
              ing  to  this parameter.  Also (assuming sufficient
              privileges), you may start a single command with  a
              different  effective  group  ID by `(EGID=gid; com­

       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  privileges),
              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 cur­
              rent  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 functions builtin.

              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  ses­
              sion.  This  parameter  is  exported by default but
              this can be disabled using the typeset builtin.

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

       OLDPWD The  previous  working directory.  This is set when
              the shell initializes and  whenever  the  directory

       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

       PPID <S>
              The process ID of the parent of the shell.

       PWD    The present working directory.  This  is  set  when
              the  shell  initializes  and whenever the directory

       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

              Unlike other special parameters, the  type  of  the
              SECONDS  parameter 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
              floating  point number.  The precision is six deci­
              mal places, although not all places may be  useful.

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

              An array containing the names of the signals.

       TTY    The name of the tty associated with the  shell,  if

       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 process.  If you have  sufficient  privi­
              leges,  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 dif­
              ferent  username  (and  user  ID  and  group ID) by
              `(USERNAME=username; command)'

       VENDOR The vendor, as determined at compile time.

              Expands to the basename  of  the  command  used  to

       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 recreated, and recre­
       ating one of the pair will recreate the other.

       ARGV0  If  exported,  its  value is used as the argv[0] of
              external commands.  Usually used in constructs like
              `ARGV0=emacs nethack'.

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

       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

              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

       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 suf­
              fixes of files to be ignored during  filename  com­
              lexical  analysis  mechanism.   The first character
              signals the start of a history  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.)

              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
              difference  as a cushion for saving duplicated his­
              tory 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.

              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  vari­
              able starting with `LC_'.

       LC_ALL <S>
              This  variable  overrides  the  value of the `LANG'
              variable and the value of any of  the  other  vari­
              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  func­
              tions.   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

       LINES <S>
              The number of  lines  for  this  terminal  session.
              Used  for  printing  select  lists and for the line

              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.

              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.

              The  interval  in  seconds  between  checks for new

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

       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  usually  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 expansion before  being  displayed;
              see the section `Prompt Expansion'.

       PS2 <S>
              The  secondary prompt, printed when the shell needs
              more information to  complete  a  command.   It  is
              expanded  in  the  same way as PS1.  The default is
              `%_> ', which displays any shell constructs or quo­
              tation 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 displays the name of the current shell struc­
              If nonnegative, commands whose  combined  user  and
              system  execution  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  exam­
              ines its value when evaluating certain expressions.
              Some modules also employ  REPLY  for  similar  pur­

       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 dis­
              played on the left.  This does not work if the SIN­
              GLELINEZLE  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 dis­
              played on the left.  This does not work if the SIN­
              GLELINEZLE  option  is  set.  It is expanded in the
              same way as PS2.

              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  presum­
              ably needs spelling correction, and `%r' expands to
              the proposed correction.  All other prompt  escapes
              are also allowed.

       STTY   If  this  parameter  is set in a command's environ­
              ment, the shell runs  the  stty  command  with  the
              value  of  this  parameter as arguments in order to
              set up the terminal before executing  the  command.
              The  modes apply only to the command, and are reset
              when it finishes or is suspended. If the command is
              suspended  and  continued later with the fg or wait
              builtins it will see the modes specified  by  STTY,
              TERM causes zsh to re-initialize 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 ter­
              minal type in order for the new  settings  to  take

              The  format  of  process time reports with the time
              keyword.  The default is `%E real  %U user  %S sys­
              tem   %P  %J'.   Recognizes  the  following  escape

              %%     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 printing 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  issu­
              ing  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.  Otherwise  a  new
              alarm  is scheduled to TMOUT seconds after the last

              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 `%' fol­
              lowed by a line (tty).  Any or all of these  compo­

              %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 dis­
                     play, 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.   Otherwise  they  are
                     treated as ordinary strings.

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

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

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

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

                     Specifies a ternary expression.  The charac­
                     ter following the x is arbitrary;  the  same
                     character  is  used to separate the text for
                     the "true" result from that for the  "false"
                     result.   Both  the  separator and the right
                     parenthesis may be escaped with a backslash.
                     Ternary expressions may be nested.

                     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.

              as described in the zsh/zle module entry in zshmod­
              ules(1),  that  will  be  output  to  the  terminal
              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  prece­
              dence over the NOBEEP option.

              The  directory  to  search  for shell startup files
ZSHOPTIONS(1)                                       ZSHOPTIONS(1)

              (.zshrc, etc), if not $HOME.


       zshoptions - zsh options


       Options are primarily referred to by  name.   These  names
       are  case  insensitive  and  underscores are ignored.  For
       example, `allexport' is equivalent 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 `unse­
       topt beep'.  This inversion can  only  be  done  once,  so
       `nonobeep' is not a synonym for `beep'.  Similarly, `tify'
       is  not  a  synonym  for  `nonotify'  (the  inversion   of

       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 exam­
       ple the string `-f    ' will be treated just as `-f',  but
       the  string `-f i' is an error.  This is because many sys­
       ALIASES <D>
              Expand aliases.

       ALL_EXPORT (-a, ksh: -a)
              All parameters subsequently defined  are  automati­
              cally exported.

              If  unset,  key functions that list completions try
              to return to the last prompt  if  given  a  numeric
              argument.  If  set these functions try to return to
              the last prompt if given no numeric argument.

              If a completion is performed with the cursor within
              a word, and a full completion is inserted, the cur­
              sor 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­

              If this is set, zsh sessions will append their his­
              tory list to the history file,  rather  than  over­
              write it. Thus, multiple parallel zsh sessions will
              all have their history lists added to  the  history
              file, in the order they are killed.

       AUTO_CD (-J)
              If  a command is issued that can't be executed as a
              normal command, and the command is the  name  of  a
              directory,  perform  the  cd command to that direc­

              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

       AUTO_LIST (-9) <D>
              Automatically  list choices on an ambiguous comple­

       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.

              Any parameter that is set to the absolute name of a
              comes  immediately  after the parameter name.  Com­
              pletion in a brace expansion is affected similarly:
              the added character is a `,', which will be removed
              if `}' is typed next.

              If a parameter is completed whose  content  is  the
              name  of  a  directory,  then  add a trailing slash
              instead of a space.

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

              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 com­
              mand (such as a semicolon or an ampersand),  remove
              the slash.

       AUTO_RESUME (-W)
              Treat  single word simple commands without redirec­
              tion as candidates for resumption  of  an  existing

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

       BANG_HIST (+K) <C> <Z>
              Perform   textual   history  expansion,  csh-style,
              treating the character `!' specially.

              In a glob pattern, treat a trailing set  of  paren­
              theses  as a qualifier list, if it contains no `|',
              `(' or (if special) `~' characters.  See  the  sec­
              tion `Filename Generation'.

              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.

              Make  the  echo  builtin  compatible  with  the BSD
              echo(1) command.  This disables backslashed  escape
              sequences  in  echo strings unless the -e option is

              Output hexadecimal numbers in the standard  C  for­
              mat,  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.

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

              When changing to a directory containing a path seg­
              ment `..' which would otherwise be treated as  can­
              celing  the  previous segment 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  directory.   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.

       CHECK_JOBS <Z>
              Report the status of background and suspended  jobs
              before  exiting  a shell with job control; a second
              and  `>>'  to create files.  Otherwise `>!' or `>|'
              must be used to truncate a file, and `>>!' or `>>|'
              to create a file.

              Prevents  aliases  on  the  command line from being
              internally   substituted   before   completion   is
              attempted.   The effect is to make the alias a dis­
              tinct command for completion purposes.

              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.

       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

              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 reference, defaulting
              to the previous command.

              Allow  loop  bodies  to  take  the form `list; end'
              instead of `do list; done'.

              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 `Redi­
              the VI option is unset.   Turning  it  off  has  no
              effect.   The  option  setting is not guaranteed to
              reflect the current keymap.  This  option  is  pro­
              vided for compatibility; bindkey is the recommended

       EQUALS <Z>
              Perform = filename  expansion.   (See  the  section
              `Filename Expansion'.)

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

              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 supplied  to
              the shell at startup.

              Treat  the  `#',  `~' and `^' characters as part of
              patterns for filename generation, etc.  (An initial
              unquoted `~' always produces named directory expan­

              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

              `:<beginning time>:<elapsed seconds>:<command>'.

              If  this  option  is unset, output flow control via
              start/stop characters (usually assigned  to  ^S/^Q)
              is disabled in the shell's editor.

              When  executing  a  shell  function  or  sourcing a
              itly.  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 compati­
              bility; 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 function;
              this  is  the  most  portable  way  to achieve this

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

       GLOB_ASSIGN <C>
              If this option is set, filename  generation  (glob­
              bing) is performed 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 compatibility only:  globbing  is  always
              performed  on  the right hand side of array assign­
              ments 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.

              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   COM­
              PLETE_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.

       GLOB_DOTS (-4)
              Do not require a leading `.' in a  filename  to  be
              matched explicitly.

       GLOB_SUBST <C> <K> <S>
              Treat   any  characters  resulting  from  parameter
              expansion as being eligible for file expansion  and

       HASH_DIRS <D>
              Whenever  a command name is hashed, hash the direc­
              tory containing it, as well as all directories that
              occur  earlier  in the path.  Has no effect if nei­
              ther HASH_CMDS nor CORRECT is set.

       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.

              Add `|' to  output  redirections  in  the  history.
              This  allows  history  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.

              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 HIST­
              SIZE to a larger number than SAVEHIST in  order  to
              give  you some room for the duplicated events, oth­
              erwise  this   option   will   behave   just   like
              HIST_IGNORE_ALL_DUPS once the history fills up with
              unique events.

              When searching for history entries in the line edi­
              tor, do not display duplicates of a line previously
              found, even if the duplicates are not contiguous.

              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 previ­
              ous event).

       HIST_IGNORE_DUPS (-h)
              Do not enter command lines into the history list if
              they are duplicates of the previous event.

              Remove command lines from the history list when the
              first character on the line is a space, or when one
              of the expanded aliases contains a  leading  space.

              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.

              Remove superfluous blanks from  each  command  line
              being added to the history list.

              When  writing  out the history file, older commands
              that duplicate newer ones are omitted.

              Whenever the user enters a line with history expan­
              sion,  don't  execute  the  line directly; instead,
              perform history expansion and reload the line  into
              the editing buffer.

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

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

       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 (normally Control-D) without print­
              ing the normal warning message.   This  works  only
              for normal widgets, not for completion widgets.

              This  options works like APPEND_HISTORY except that
              new history lines are added to the $HISTFILE incre­
              mentally (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.

       INTERACTIVE (-i, ksh: -i)
              This  is  an interactive shell.  This option is set
              upon initialisation if the standard input is a  tty
              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  function  is autoloaded, the corresponding
              file is merely executed, and must define the  func­
              tion  itself.  (By default, the function is defined
              to the contents of the  file.   However,  the  most
              common ksh-style case - of the file containing only
              a simple definition of the  function  -  is  always
              handled in the ksh-compatible manner.)

       KSH_GLOB <K>
              In  pattern  matching, the interpretation of paren­
              theses is affected by a preceding  `@',  `*',  `+',
              `?' or `!'.  See the section `Filename Generation'.

              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,  inte­
              ger,  local  and  readonly, are processed.  Without
              this option, zsh will perform normal word splitting
              after  command and parameter expansion in arguments
              of an assignment; with it, word splitting does  not
              take place in those cases.

              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 noth­
              ing  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  completion,  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.

              If this option is set at the point of return from a
              shell function, all  the  options  (including  this
              one) which were in force upon entry to the function
              are restored.  Otherwise, only this option and  the
              XTRACE  and  PRINT_EXIT_VALUE options are restored.
              Hence if this is explicitly unset by a shell  func­
              tion  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_TRAPS <K>
              If  this  option  is  set when a signal trap is set
              inside a function, 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.

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

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

              All   unquoted   arguments   of   the   form  `any­
              thing=expression' appearing after the command  name
              have  filename expansion (that is, where expression
              has a leading `~' or `=') performed  on  expression
              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

              On an ambiguous completion, instead of listing pos­
              sibilities or beeping, insert the first match imme­
              diately.  Then when completion is requested  again,
              remove the first match and insert the second match,
              etc.  When there are no more matches,  go  back  to
              the  first one again.  reverse-menu-complete may be
              used to loop through the list in the  other  direc­
              tion. This option overrides AUTO_MENU.

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

       MULTIOS <Z>
              Perform implicit tees or cats when  multiple  redi­
              rections  are  attempted (see the section `Redirec­

       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 `='.

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

       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.

              If numeric filenames are matched by a filename gen­
              eration  pattern,  sort  the  filenames numerically
              rather than lexicographically.

              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.

              Start up the line editor in overstrike mode.

       PATH_DIRS (-Q)
              search path.

              When this option is set the command builtin can  be
              used  to execute shell builtin commands.  Parameter
              assignments specified before  shell  functions  and
              special  builtins  are  kept after the command com­
              pletes unless the special builtin is prefixed  with
              the  command  builtin.   Special builtins are ., :,
              break, continue, declare, eval, exit, export, inte­
              ger,  local,  readonly, return, set, shift, source,
              times, trap and unset.

              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

       PRIVILEGED (-p, ksh: -p)
              Turn on privileged mode. This is enabled  automati­
              cally  on  startup if the effective user (group) ID
              is not equal to the real user (group) ID.   Turning
              this option off causes the effective user and group
              IDs to be set to the real user and group IDs.  This
              option  disables  sourcing  user startup files.  If
              zsh is invoked as `sh' or `ksh'  with  this  option
              set,  /etc/suid_profile is sourced (after /etc/pro­
              file 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.

       PROMPT_BANG <K>
              If  set,  `!' is treated specially in prompt expan­
              sion.  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  edi­
              tor knows where the start of the line appears.

              If  set,  `%' is treated specially in prompt expan­
              sion.  See the section `Prompt Expansion'.
              Do  not  print  the  directory stack after pushd or

       PUSHD_TO_HOME (-D)
              Have  pushd  with  no  arguments  act  like  `pushd

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

              Allow the character sequence `''' to signify a sin­
              gle  quote within singly quoted strings.  Note this
              does not apply in quoted strings using  the  format
              $'...',  where  a  backslashed  single quote can be

       RCS (+f) <D>
              After /etc/zshenv is sourced on startup, source the
              .zshenv,   /etc/zprofile,   .zprofile,  /etc/zshrc,
              .zshrc, /etc/zlogin, .zlogin, 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 executing one from being

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

       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   section
              `Restricted Shell'.

       RM_STAR_SILENT (-H) <K> <S>
              Do  not  query  the user before executing `rm *' or
              `rm path/*'.

              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
              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-his­
              tory 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  whenever  you need them
              using `fc -RI'.

              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 expan­
              sion, so  things  like  `~$USERNAME'  and  `~{pfal­
              stad,rc}' will work.

       SH_GLOB <K> <S>
              Disables  the  special meaning of `(', `|', `)' and
              '<' for globbing the result of parameter  and  com­
              mand  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.

       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 explicitly on  the
              command  line,  any  argument  that would otherwise
              have been taken as a file to run  will  instead  be
              treated  as  a  normal  positional parameter.  Note
              that setting or unsetting this option on  the  com­
              mand 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.

       SH_NULLCMD <K> <S>
              Do not use the values of  NULLCMD  and  READNULLCMD
              when  doing  redirections, use `:' instead (see the
              section `Redirection').

              If this option is set the shell tries to  interpret
              single  letter options (which are used with set and
              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.

       SINGLE_LINE_ZLE (-M) <K>
              Use single-line command  line  editing  instead  of

              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 key­
              boards where the return key is too small,  and  the
              backquote key lies annoyingly close to it.

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

              If  this  is  unset, executing any of the `typeset'
              family of commands with no options and  a  list  of
              parameters  that  have no values to be assigned but
              already exist will display the value of the parame­
              ter.  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.

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

       VERBOSE (-v, ksh: -v)
              Print shell input lines as they are read.

       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 guaranteed to
              reflect the current keymap.  This  option  is  pro­
              vided for compatibility; bindkey is the recommended

       XTRACE (-x, ksh: -x)
              Print commands and their arguments as they are exe­
              GLOB_DOTS (bash compatibility)

              HASH_CMDS (bash compatibility)

              APPEND_HISTORY (bash compatibility)

              BANG_HIST (bash compatibility)

       LOG    NO_HIST_NO_FUNCTIONS (ksh compatibility)

              MAIL_WARNING (bash compatibility)

              SINGLE_COMMAND (bash compatibility)

              CHASE_LINKS (ksh and bash compatibility)

              PROMPT_SUBST (bash compatibility)

       STDIN  SHIN_STDIN (ksh compatibility)

              HASH_CMDS (ksh compatibility)


   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
       -Z     ZLE
       -a     ALL_EXPORT
       -e     ERR_EXIT
       -f     NO_RCS
       -g     HIST_IGNORE_SPACE
       -h     HIST_IGNORE_DUPS
       -i     INTERACTIVE
       -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
       -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
       -c     Used  on  the command line to specify a single com­
       -m     Used by setopt for pattern-matching option setting
       -o     Used in all places to  allow  use  of  long  option
ZSHBUILTINS(1)                                     ZSHBUILTINS(1)

              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 parame­
              ters are restored when the file is done  executing.
              The exit status is the exit status of the last com­
              mand 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 [ {+|-}gmrL ] [ 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 expan­
              sion.   If  the -g flag is present, define a global
              alias; global aliases are expanded even if they  do
              not occur in command position.

              For  each  name  with  no value, print the value of
              name, if any.  With no arguments,  print  all  cur­
              rently  defined  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 pat­
              terns  are  printed.  When printing aliases and the
              -g or -r  flags  are  present,  then  restrict  the
              printing  to  global  or  regular  aliases, respec­
              tively.  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

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

              found.   This does not replace any existing defini­
              tion 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

              The flag +X may be combined with either -k or -z to
              make  the  function  be  loaded  using ksh-style or
              zsh-style autoloading, respectively. If neither  is
              given,  the  current  setting  of  the KSH_AUTOLOAD
              options determines how the function is loaded. With
              ksh-style  autoloading,  the  contents  of the file
              will not  be  executed  immediately.  Instead,  the
              function  created  will contain the contents of the
              file plus a call to the function itself appended to
              it,  thus given 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  autoload­

       bg [ job ... ]
       job ... &
              Put  each  specified  job in the background, or the
              current job if none is specified.

              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 lev­
              els 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  zshmod­

       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

              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  con­
              tains  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 zshmod­

       command simple command
              See the section `Precommand Modifiers'.

              See the section `The zsh/computil Module'  in  zsh­

              See the section `The zsh/compctl Module' in zshmod­

              See the section `The zsh/compctl Module' in zshmod­

              See  the  section `The zsh/computil Module' in zsh­

              See the section `The zsh/computil Module'  in  zsh­

              See  the  section `The zsh/computil Module' in zsh­

              See the section `The zsh/computil Module'  in  zsh­

       continue [ n ]
              Resume the next iteration  of  the  enclosing  for,
              while, until, select or repeat loop.  If n is spec­
              ified, break out of n-1 loops and resume at the nth
              enclosing loop.

              Same as typeset.

       dirs [ -c ] [ arg ... ]
       dirs [ -lpv ]
              With no arguments, print the contents of the direc­
              tory stack.  Directories are added  to  this  stack
              with  the pushd command, and removed with the cd or
              popd commands.  If arguments  are  specified,  load
              them  onto  the directory stack, replacing anything
              that was there, and push the current directory onto
              the stack.

              -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

       disable [ -afmr ] 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 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  patterns  (which
              should  be  quoted  to prevent them from undergoing
              filename expansion), and all  hash  table  elements
              from  the  corresponding  hash table matching these
              patterns are disabled.   Disabled  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
              separating each one.  If the -n flag  is  not  pre­
              sent,  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
                     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 zshmod­

       echoti See  the  section `The zsh/terminfo Module' in zsh­

       emulate [ -LR ] {zsh|sh|ksh|csh}
              Set up zsh options to emulate the  specified  shell
              as  much as possible.  csh will never be fully emu­
              lated.  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  zshmisc(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 emulate command and any  setopt  and
              trap  commands  to be local to the immediately sur­
              rounding shell function,  if  any;  normally  these
              options  are  turned  off  in  all  emulation modes
              except ksh.
              disable builtin command.

       eval [ arg ... ]
              Read the arguments as input to the shell  and  exe­
              cute  the  resulting  command  in the current shell

       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  environment  of subsequently executed com­
              mands.  Equivalent to typeset -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 -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  nega­
              tive  number  is  used  as an offset to the current
              history event number.  A string specifies the  most
              recent  event beginning with the given string.  All
              substitutions old=new, if any, are  then  performed
              on the commands.

              If the -l flag is given, the resulting commands are
              listed on standard output.  If the -m flag is  also
              given  the  first  argument  is  taken as a pattern
              (should be quoted)  and  only  the  history  events
              matching this pattern will be shown.  Otherwise the
              editor program ename is invoked on a file  contain­
              ing  these  history 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
              -W' writes the history out to the given  file,  and
              `fc  -A' appends the history 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

       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  per­

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

       getcap See  the  section  `The  zsh/cap Module' in zshmod­

       getln [ -AclneE ] name ...
              Read the top value from the buffer stack and put it
              in  the  shell  parameter name.  Equivalent to read

       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  sin­
              gle  `-' is not considered a valid option argument.
              optstring contains the letters that getopts  recog­
              nizes.   If  a  letter  is  followed by a `:', that
              option  is  expected  to  have  an  argument.   The
              options  can  be  separated  from  the  argument by

              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.

              getopts sets name to `?' and prints an  error  mes­
              sage 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  command 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

              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  immediately.   For
              the command hash table this hashes all the absolute
              directories in the PATH, and for the  named  direc­
              tory  hash table this adds all users' home directo­
              ries.  These two options cannot be  used  with  any

              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

       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 feature 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 num­
              ber  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 descrip­
              tion of arithmetic expressions.  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 current 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.
                     Maximum CPU seconds per process.
                     Maximum data size (including stack) for each
                     Maximum value for a file descriptor.
                     Largest single file allowed.
                     Maximum number of processes.
                     Maximum number of threads per process.
                     Maximum amount of memory locked in RAM.
                     Maximum resident set size.
                     Maximum resident set size.
                     Maximum size of all socket buffers.
                     Maximum stack size for each process.
                     Maximum amount of virtual memory.

              Which   of  these  resource  limits  are  available
              depends on the system.  resource can be abbreviated
              to any unambiguous prefix.

              limit is a number, with an optional scaling factor,
              as follows:

              nh     hours
              nk     kilobytes (default)
              nm     megabytes or minutes
                     minutes and seconds

       local [ {+|-}AEFHLRUZahilprtux [n]] [ name[=value] ] ...
              Same as typeset, except that the options -g, and -f
              are not permitted.  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 current setting of the watch parameter.

       logout [ n ]
              Same as exit, except that it only works in a  login

       print  [  -abcDilmnNoOpPrsz  ]  [ -un ] [ -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' pro­
              duces  a  control character (`\C-@' and `\C-?' give
              the characters NUL and delete), and `\E' is a  syn­
              onym  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

              -b     Recognize  all  the escape sequences defined
                     for the bindkey 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  prefixes  with  ~ expressions, as

              -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 subsequent 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
                     is given.  The -n flag suppresses the trail­
                     ing 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.

              -un    Print the arguments to file descriptor n.

              -z     Push  the  arguments onto the editing buffer
                     stack, separated by spaces.

              If any of `-m', `-o' or `-O' are used  in  combina­
              tion  with  `-f'  and there are no arguments (after
              the removal process in the case of `-m') then noth­
              ing is printed.

       printf format [ arg ... ]
              Print  the arguments according to the format speci­
              fication. Formatting rules are the same as used  in
              C. The same escape sequences as for echo are recog­
              nised in the format. All  C  conversion  specifica­
              tions  ending in one of csdiouxXeEfgGn are handled.
              In addition to this, `%b' can be  used  instead  of
              `%s'  to  cause escape sequences in the argument to
              be recognised and `%q' can be  used  to  quote  the
              argument  in such a way that allows it to be reused
              as shell input. With the numeric format specifiers,
              if  the  corresponding argument starts with a quote
              character, the numeric value of the following char­
              acter  is used as the number to print otherwise the
              argument is evaluated as an arithmetic  expression.
              See  the  section  `Arithmetic  Evaluation'  for  a
              description of arithmetic expressions.  With  `%n',
              the  corresponding  argument is taken as an identi­
              fier 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 recommended
              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  argu­
              ments  are  required  by  the format than have been
              specified, the behaviour is as if zero or an  empty
              in the second form is also the same as for cd.

              The third form of pushd changes directory by rotat­
              ing  the  directory  list.  An argument of the form
              `+n' identifies a stack entry by counting from  the
              left  of the list shown by the dirs command, start­
              ing 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

              If  the  option PUSHD_SILENT is not set, the direc­
              tory stack will be printed after a  pushd  is  per­

              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 sym­
              bolic links.

       r      Same as fc -e -.

       read [ -rszpqAclneE ] [ -t [ num ] ] [ -k [ num ] ]  [  -d
       delim ]
        [ -un ] [ 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  back­
                     slashes in the line don't quote the  follow­
                     ing 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
                     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  pre­

              -E     The  input  read  is printed (echoed) to the
                     standard output.  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.

              -l     These  flags  are  allowed  only  if  called
                     inside a function used for completion (spec­
                     ified with the -K flag to compctl).  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

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

              -un    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
                     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  character.   Use  two  instances  of
                     `read -t -k' if this is not what is  wanted.
                     If  the  first  argument contains a `?', the
                     remainder of this word is used as  a  prompt
                     on standard error when the shell is interac­

              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  com­
              pctl  function,  or as described for -q.  Otherwise
              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.

              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  speci­
              fied  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
              processing;  with a non-zero status, the shell will
              behave as interrupted except that the return status
              of  the  trap  is  retained.  Note that the 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.

              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 argu­
              ments  will  replace  the  initial elements of that
              array; if no name  is  specified,  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  argu­
              ments 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 zshmod­

       setopt [ {+|-}options | {+|-}o option_name ] [ name ... ]
              Set the options for the shell.  All options  speci­
              fied  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.

       suspend [ -f ]
              Suspend the execution of the shell (send it a SIGT­
              STP)  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 compat­
              ibility; 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 pro­
              tect  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 executed after each command.
              If sig is 0 or EXIT and the trap statement is  exe­
              cuted  inside the body of a function, then the com­
              mand 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.

              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 different from those defined  as  `TRAPNAL
              ()  { ... }', as the latter have their own function
              environment (line numbers, local  variables,  etc.)
              while the former use the environment of the command
              in which they were called.  For example,

                     trap 'print $LINENO' DEBUG

              will print the line number of  a  command  executed
              after it has run, while

              or  is  suspended.  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 [ {+|-}AEFHLRUZafghilprtuxm  [n]]  [  name[=value]
       ... ]
       typeset -T [ {+|-}LRUZrux ] SCALAR[=value] array
              Set or display  attributes  and  values  for  shell

              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 remaining 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), regardless of other
              flags and options.  Note that the -h flag on param­
              eters  is  respected;  no  value  will be shown for
              these parameters.

              If the -T option is given, exactly  two  (or  zero)
              name  arguments  must be present.  They represent a
              scalar and an array (in that order)  that  will  be
              tied together in the manner of $PATH and $path.  In
              other words, an array present in the  latter  vari­
              able  appears  as a scalar with the elements of the
              array joined by colons in  the  former.   Only  the
              to  local scope.  Note that this does not necessar­
              ily 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 listing existing parameters, nor
              does the flag +g have any effect except in combina­
              tion 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 display 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

              If the -m flag is  given  the  name  arguments  are
              taken  as  patterns (which should be quoted).  With
              no attribute flags, all  parameters  (or  functions
              with  the  -f flag) with matching names are printed
              (the shell option TYPESET_SILENT  is  not  used  in
              this case).  Note that -m is ignored if no patterns
              are given.  If the +g flag is combined with  -m,  a
              new  local  parameter is created 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, association,
              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 parame­
                     ters; 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 deter­
                     mined by the width of the value of the first
                     assignment.  When the parameter is expanded,
                     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, -u and
                     -U.  The flag -t turns on execution  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 referenced; see
                     the section `Functions'.

              -h     Hide: only  useful  for  special  parameters
                     (those  marked  `<S>'  in  the table in zsh­
                     params(1)), and for  local  parameters  with
                     the same name as a special parameter, though
                     harmless for others.   A  special  parameter
                     with this attribute will not retain its spe­
                     cial effect when  made  local.   Thus  after
                     `typeset  -h  PATH',  a  function containing
                     `typeset PATH' will create an ordinary local
                     parameter  without  the  usual  behaviour of
                     PATH.  Alternatively,  the  local  parameter
                     may  itself  be  given this attribute; hence
                     inside a function `typeset -h PATH'  creates
                     an  ordinary local parameter and the special
                     PATH parameter is not altered  in  any  way.
                     It is also possible to create a local param­
                     eter using `typeset +h special',  where  the
                     local  copy  of special will retain its spe­
                     cial properties regardless of having the  -h
                     attribute.  Global special parameters loaded
                     the zsh/parameter and  zsh/mapfile  modules.
                     Note,  however, that unlike the -h flag this
                     is also useful for non-special parameters.

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

              -E     Use  an  internal  double-precision floating
                     point representation.  On output  the  vari­
                     able  will  be converted to scientific nota­
                     tion.  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  representation.   On output the vari­
                     able will be converted to fixed-point  deci­
                     mal  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

              -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

              -x     Mark for automatic export to the environment
                     of subsequently 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 compatibility with previous versions
                     of zsh.

              -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  writ­
              -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'.

       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 permissions you specify are those
              which are to be allowed (not denied) to  the  users

              Same as unhash -a.

              Same as unhash -f.

       unhash [ -adfm ] 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 aliases.  The -f  option  causes  unhash  to
              remove  shell  functions.   The  -d  options causes
              unhash to remove named directories.  If the -m flag
              is  given  the  arguments  are  taken  as  patterns
              (should be quoted) and all elements of  the  corre­
              sponding  hash  table  with  matching names will be

       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 privileges, the hard resource limit
              for each resource is removed.  The resources of the
              shell process are only changed if the  -s  flag  is
              as  patterns  (should be quoted) and all parameters
              with matching names are unset.  Note that this can­
              not  be  used when unsetting associative array ele­
              ments, as the subscript will be treated as part  of
              the pattern.

              The  -v  flag specifies that name refers to parame­
              ters. 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 spec­
              ified  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 inter­
              preted as glob  patterns),  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  pro­
              cesses  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 hap­

              -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 func­
              tions 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 compiled 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 func­
              tion is autoloaded; see  the  section  `Autoloading
              Functions'  in  zshfunc(1) for a description 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  func­
              tions  into  file.  For -c, the names must be func­
              tions 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 definition files for  those
              functions,  if  found,  are compiled into file.  If
              both -c and -a are given,  names  of  both  defined
              functions  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
              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  func­
              tions  currently  defined  or  marked as autoloaded
              will be written.

              The third form, with the  -t  option,  examines  an
              existing compiled file.  Without further arguments,
              the names of the original 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 argu­
              ments,  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 defini­
              tion 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 autoload­
                     able 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, consequently 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 compiled file.

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

              See the section `The zsh/zutil Module'  in  zshmod­

       zftp   See  the  section  `The zsh/zftp Module' in zshmod­

       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 mod­
              ules.   Loading  of modules while the shell is run­
              ning (`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 modules 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 command is, using $module_path instead
                     of $path.  However, the path search is  per­
                     formed  even when the module name contains a
                     `/', which it usually does.  There is no way
                     to prevent the path search.

              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 sec­
                     ond  and subsequent arguments will be loaded
                     before the module named in the  first  argu­

                     With  -d  and one argument, all dependencies
                     for that module 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  com­

                     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 com­

                     If -b is used together with the  -u  option,
                     it  removes builtins previously defined with
                     -ab.  This is only possible if  the  builtin
                     is  not yet loaded.  -i suppresses the error
                     if the builtin is already removed (or  never

              zmodload -ac [ -IL ]
              zmodload -ac [ -iI ] name [ cond ... ]
              zmodload -uc [ -iI ] cond ...
                     The  -ac option is used to define autoloaded

              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 param­
                     eters 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  corresponding  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 availabil­
                     ity 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 mod­
                     ule  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 listing, if the -L flag was also given,
                     list the definition as a zmodload command to
                     recreate the alias.

                     The existence of aliases for modules is com­
                     pletely  independent  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,
                     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  mod­
                     ule  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 -R modalias ...
                     For each modalias argument that  was  previ­
                     ously defined as a module alias via zmodload
                     -A,  delete  the  alias.   If  any  was  not
                     defined,  an error is caused and the remain­
                     der 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  available the
              builtins  and  other  things  defined  by   modules
              (unless  the  module is autoloaded on these defini­
              tions). This is true even for  systems  that  don't
              support dynamic loading of modules.

              See  the  section `The zsh/zutil Module' in zshmod­

       zprof  See the section `The zsh/zprof Module'  in  zshmod­

       zpty   See  the  section  `The zsh/zpty Module' in zshmod­

              See the section `The zsh/zutil Module'  in  zshmod­

              See the section `The zsh/net/socket Module' in zsh­

       zstyle See the section `The zsh/zutil Module'  in  zshmod­
       active shells) and the shell input is attached to the ter­
       minal, 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 terminal type that can move the cursor  up.
       The  second,  single line mode, is used if TERM is invalid
       or incapable of moving the  cursor  up,  or  if  the  SIN­
       GLE_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 editor.  See Parameters Used By The Shell in zsh­


       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 manip­
       ulate 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

       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',  other­
       wise it will be `emacs'.  bindkey's -e and -v options pro­
       vide a convenient way to override this default choice.

       When the editor starts  up,  it  will  select  the  `main'
       keymap.  If that keymap doesn't exist, it will use `.safe'
       TIMEOUT parameter; its default is 0.4 sec.   There  is  no
       timeout if the prefix string is not itself bound to a com­

       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  replace­
       ments without a real command being read.


       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  cate­
              gories:  keymap selection, operation selection, and
              others.  The keymap selection options are:

              -e     Selects keymap `emacs', and also links it to

              -v     Selects keymap `viins', and also links it to

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

                     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

              -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 beginning with  an  escape  character
                     (probably  cursor keys), but leave the bind­
                     ing for the escape character itself  (proba­

              [ in-string ]
                     List key bindings.  If an in-string is spec­
                     ified,  the  binding  of  that string in the
                     selected keymap  is  displayed.   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 bindings  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, inclu­
       sive, 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 distinct, although they  are
       initialized to the same bindings by `bindkey -m'.

       vared [ -Aache ] [ -p prompt ] [ -r rprompt ] name
              The  value of the parameter name is loaded into the
              edit buffer, and the line editor is invoked.   When
              following  separator  character  or  backslash;  no
              other special handling of backslashes, or any  han­
              dling of quotes, is performed.

              Individual  elements  of existing array or associa­
              tive array parameters may be edited by  using  sub­
              script  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.

       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 concerning ZLE.  Which  operation  it  per­
              forms 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

              -D widget ...
                     invoked from within the editor,  the  speci­
                     fied  shell function is called.  If no func­
                     tion name is specified, it defaults  to  the
                     same name as the widget.  For further infor­
                     mation, see  the  section  Widgets  in  zsh­

              -C widget completion-widget function
                     Create   a  user-defined  completion  widget
                     named widget.  The  completion  widget  will
                     behave  like  the built-in completion-widget
                     whose name is given as completion-widget. To
                     generate the completions, the shell function
                     function will be called.  For further infor­
                     mation, see zshcompwid(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 dis­
                     play-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

                     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

              -K keymap
                     Selects the keymap named keymap.   An  error
                     message  will  be  displayed  if there is no
                     such keymap.

                     This keymap selection affects the  interpre­
                     tation  of  following 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  func­
                     tion)  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 out­
                     put to the terminal, it should call `zle -I'
                     before  doing  so  (see below).  The handler
                     should not attempt to read from  the  termi­
                     nal.   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  handler
                     to be replaced.

                     If  no  handler  is given, but an fd is pre­
                     sent, any handler for that  fd  is  removed.
                     If  there  is  none,  an  error  message  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 exe­

                     An  fd (but not a handler) may optionally be
                     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 connection; we handle that by
                     testing for a failed read.
                             if ztcp pwspc 2811; then
                               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
                                 print -r - $line
                               zle -F $tcpfd handler

              -I     Unusually,  this  option is most useful out­
                     side 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 out­
                     put; 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 following 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 control is returned to the edi­
                     tor; the display will  only  be  invalidated
                     the first time to minimise disruption.

                     With the options  -n  and  -N,  the  current
                     numerical  argument  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 positional parameters;
                     for builtin widgets it is up to  the  widget
                     in  question  what  it does with them.  Cur­
                     rently arguments are  only  handled  by  the
                     incremental-search    commands,   the   his­
                     tory-search-forward and  -backward  and  the
                     corresponding functions prefixed by vi-, and
                     by universal-argument.  No error is  flagged
                     if  the  command does not use the 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 function.

                     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.


       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

       The  standard  widgets built in to ZLE are listed in Stan­
       dard Widgets below.  Other built-in widgets can be defined
       by  other modules (see zshmodules(1)).  Each built-in wid­
       get has two names: its normal canonical name, and the same
       name preceded by a `.'.  The `.' name is special: it can't
       be rebound to a different widget.  This makes  the  widget
       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

       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.

       CURSOR (integer)
              The  offset  of the cursor, within the edit buffer.
              This is in the range 0 to $#BUFFER, and is by defi­
              nition  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; read-only.

       KEYMAP (scalar)
              The   name   of   the  currently  selected  keymap;

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

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

       LASTWIDGET (scalar)
              The name of the  last  widget  that  was  executed;

       LBUFFER (scalar)
              The part of the buffer that lies to the left of the
              cursor position.  If it is assigned to,  only  that
              part  of  the  buffer  is  replaced, and the cursor
              remains  between  the  new  $LBUFFER  and  the  old

       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 new­
              line must be appended explicitly.     The  text  is
              reset  on  each  new  invocation (but not recursive
              invocation) of zle.

       POSTDISPLAY (scalar)
              Text to be displayed after the end of the  editable
              text  buffer.   This does not have to be a complete
              line; to display a complete line, a newline must be


       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,

       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 mod­
       ern terminals, but  in  fact  these  are  not  necessarily
       bound.   In  the  case  of  the  viins keymap, the initial
       escape character of the sequences serves also to return to
       the  vicmd  keymap:  whether this happens is determined by
       the KEYTIMEOUT parameter, see zshparam(1).

       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

       backward-word (ESC-B ESC-b) (unbound) (unbound)
              Move to the beginning of the previous word.

              Move to the beginning of the previous word.

       vi-backward-word (unbound) (b) (unbound)
              Move  to  the  beginning  of  the  previous   word,

       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.

              Move to the beginning of the line, without changing

       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
              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 occurrence 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 edi­
              tor's idea of a word is specified  with  the  WORD­
              CHARS parameter.

              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 argu­

       vi-goto-mark (unbound) (`) (unbound)
              Move to the specified mark.

       vi-goto-mark-line (unbound) (') (unbound)

              Move to the beginning of the line.  If  already  at
              the  beginning  of the buffer, move to the previous
              history line.

              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 his­
              tory 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 his­
              tory list.  Then move to the first non-blank  char­
              acter on the line.

              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.

              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.

              Move to the end of the line.  If already at the end
              of the buffer, move to the next history line.

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

              magic-space just inserts a space.  vi-cmd-mode tog­
              gles between the `main' and  `vicmd'  keymaps;  the
              `main'  keymap  (insert mode) will be selected ini­
              tially.   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

              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  com­
              mand,  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

                     zle history-incremental-search-backward forceps

              will  search  backwards  for  forceps,  leaving the
              minibuffer containing the string `forceps'.

       history-incremental-search-forward  (^S   ^Xs)   (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  begin­
              ning  of  the line.  The functions available in the
              mini-buffer are the same as  for  history-incremen­

              A  restricted set of editing functions is available
              in  the  mini-buffer.   An  interrupt  signal,   as
              defined by the stty setting,  will stop the search.
              The functions available  in  the  mini-buffer  are:
              accept-line,     backward-delete-char,     vi-back­
              ward-delete-char,   backward-kill-word,    vi-back­
              ward-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 char­
              acter  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  bind­
              ings 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  func­
              tions  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  cursor  position.   If  a  positive
              numeric argument is given, insert  that  word  from
              the  end  of  the  previous  history event.  If the
              argument is zero or negative insert that word  from
              the  left (zero inserts the previous command word).
              Repeating  this  command  replaces  the  word  just
              inserted  with the last word from the history event
              prior to the one just used; numeric  arguments  can
              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 pre­
              fix 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  current history line, rather
              than the one remembered after the previous  invoca­
              tions 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  immediately  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

       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.

              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

       vi-add-next (unbound) (a) (unbound)
              Enter  insert  mode  after the current cursor posi­
              tion, 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

              Delete the word behind the cursor.

              Kill  from  the beginning of the line to the cursor

       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 (ESC-^_) (unbound) (unbound)
              Like copy-prev-word, but the word is found by using
              Delete the  character  under  the  cursor,  without
              going past the end of the line.

              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.

              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

       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 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 [])
              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 characters), 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

       vi-quoted-insert (unbound) (unbound) (^Q ^V)
              Display a `^' at the cursor  position,  and  insert
              the next character 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 `''  charac­
              ter  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 remem­
              bered.  If a count is given  to  this  command,  it
              overrides  the  remembered count, and is remembered
              for future uses of this command.   The  cut  buffer
              specification is similarly remembered.

       vi-replace-chars (unbound) (r) (unbound)
              Replace the character under the cursor with a char­
              acter read from the keyboard.

              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 cur­
              sor 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

       yank (^Y) (unbound) (unbound)
              Insert the contents of the kill buffer at the  cur­
              sor 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

       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 com­
              mand is vi-yank, copy the current line.

       vi-yank-whole-line (unbound) (Y) (unbound)
              Copy the current line into the kill buffer.

              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.

       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.

              Inside a widget function, if  passed  an  argument,
              i.e.  `zle  universal-argument  num', the numerical
              argument will be set to num; this is equivalent  to

              In a menu completion, insert the current completion
              into the buffer, and advance to the  next  possible

              Attempt completion on the current word.

       delete-char-or-list (^D) (unbound) (unbound)
              Delete the character under the cursor.  If the cur­
              sor is at the end of the line, list  possible  com­
              pletions for the current word.

              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.

              Attempt shell expansion on the current word  up  to

       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.

              Perform  history  expansion and insert a space into
              the buffer.  This is intended to be bound to space.

              Like  complete-word, except that menu completion is
              used.  See the MENU_COMPLETE option.


       accept-and-hold (ESC-A ESC-a) (unbound) (unbound)
              Push the contents of the buffer on the buffer stack
              and execute it.

              Execute  the  contents  of the buffer.  Then search
              the history list for a line  matching  the  current
              one  and  push  the event following onto the buffer

       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

              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.

              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 func­
              tion.   The   allowed    functions    are:    back­
              ward-delete-char,          vi-backward-delete-char,
              clear-screen,       redisplay,       quoted-insert,
              vi-quoted-insert,    backward-kill-word,   vi-back­
              ward-kill-word,   kill-whole-line,    vi-kill-line,
              Redo  the  last   function   executed   with   exe­

       get-line (ESC-G ESC-g) (unbound) (unbound)
              Pop the top line off the buffer stack and insert it
              at the cursor 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.

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

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

              At  the  top-level  (PS1)  prompt,  equivalent   to
              push-line.   At  a secondary (PS2) prompt, move the
              entire current multiline construct into the  editor
              buffer.   The  latter  is  equivalent to push-input
              followed by get-line.

              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  nor­
              mally  cause  zle to exit (typically an accept-line
              caused by hitting  the  return  key)  is  executed.
              Instead,  control  returns to the user-defined wid­
              get.  The status returned is non-zero if the return
                     zle -A caps-lock save-caps-lock
                     zle -A accept-line caps-lock

                     zle recursive-edit

                     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 capi­
              talised 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.

       send-break (^G ESC-^G) (unbound) (unbound)
              Abort   the  current  editor  function,  e.g.  exe­
              cute-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 cur­
              rent command.  run-help is normally aliased to man.

       vi-set-buffer (unbound) (") (unbound)
              Specify  a  buffer to be used in the following com­
              mand.  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 speci­
              fied  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
              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 modification.

       what-cursor-position (^X=) (unbound) (unbound)
              Print the character under the cursor, its  code  as
              an  octal, decimal and hexadecimal number, the cur­
              rent cursor position within the buffer and the col­
              umn of the cursor in the current line.

              Read  the  name  of an editor command and and print
              the listing of key sequences that invoke the speci­
              fied 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,  continue  the  argument.  Otherwise,
ZSHCOMPWID(1)                                       ZSHCOMPWID(1)

              execute vi-beginning-of-line.


       zshcompwid - zsh completion widgets


       The  shell's  programmable  completion  mechanism  can  be
       manipulated  in two ways; here the low-level features sup­
       porting 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  interest
       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 zshcompctl(1).

       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 widget, in this case  expand-or-com­


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

              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  kshar­
              rays option is not set.

              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 PRE­
              FIX to the end of IPREFIX, for example:


              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.

              below), and the original string was `"foo bar' with
              the  cursor  on  the `bar', this parameter contains
              `"foo '.

              Like QIPREFIX, but containing the suffix.

       SUFFIX Initially this will be set to the part of the  cur­
              rent  word  from the cursor position to the end; it
              may be altered to give  a  common  suffix  for  all
              matches.   It  is  most useful when the option COM­
              PLETE_IN_WORD is set, as otherwise the  whole  word
              on the command line is treated as a prefix.

              This  is an associative array with various keys and
              values that the completion code  uses  to  exchange
              information  with  the completion widget.  The keys

                     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 quoting 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  char­
                     acter.   The  first  character  in the value
                     always corresponds to the innermost  quoting

                     This  will  be set by the completion code to
                     the overall context in which  completion  is
                     attempted. Possible values are:

                             when  completing inside the value of
                             an array  parameter  assignment;  in
                             this  case  the words array contains
                             the words inside the parentheses.

                             when completing the name of a param­
                             eter in a parameter expansion begin­
                             the  words  array  contains only the
                             words inside the conditional expres­

                      math   when  completing  in  a mathematical
                             environment such as a `((...))' con­

                             when completing the name of a param­
                             eter in a parameter expansion begin­
                             ning with $ but not ${.

                             when  completing after a redirection

                             when completing inside  a  parameter

                      value  when   completing  the  value  of  a
                             parameter assignment.

              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.

                     The  string  of  an  exact  match if one was
                     found, otherwise unset.

                     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 com­
                     mand 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  common prefix is
                     to be inserted and the  next  invocation  of
                     the  completion  code may start menu comple­
                     given will  be  inserted  into  the  command
                     line.   Negative 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.

                     When  the completion system inserts an unam­
                     biguous string into the line, there  may  be
                     multiple places where characters 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.

                     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 dis­
                     played.  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  respec­
                     tively would normally cause them to be.

                     If the substring force appears in the value,
                     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.

                     This gives the  number  of  lines  that  are
                     needed  to  display the full list of comple­
                     tions.  Note that  to  calculate  the  total
                     number  of  lines to display you need to add
                     the number of lines needed for  the  command
                     line to this value, this is available as the
                     value of the BUFFERLINES special  parameter.

                     Initially  this  is  set to the value of the
                     LISTMAX parameter.  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.

                     The number of matches generated and accepted
                     by the completion code so far.

                     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.

                     This is set to yes if there is still a valid
                     list of completions from a previous  comple­
                     tion  at  the  time  the  widget is invoked.
                     This will usually be the case if and only if
                     the previous editing operation was a comple­
                     tion widget or one of the builtin completion

                     Normally this is set to menu,  which  speci­
                     fies that menu completion will be used when­
                     ever a set of matches  was  generated  using
                     pattern matching.  If it is set to any other
                     non-empty string by the user and  menu  com­
                     pletion is not selected by other option set­
                     tings, the code will instead insert any com­
                     mon prefix for the generated matches as with
                     normal completion.

                     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  additionally a wildcard `*' is assumed
                     at the cursor position; if it  is  empty  or
                     unset, metacharacters will be treated liter­

                     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  quotation character (i.e. either a sin­
                     gle quote, a double quote, or  a  backtick).
                     Otherwise it is unset.

                     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.

                     The  redirection operator when completing in
                     a redirection position, i.e. one  of  <,  >,

                     This  is  set  to  auto before a function is
                     entered, which forces the special parameters
                     mentioned  above  (words,  CURRENT,  PREFIX,
                     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.

                     This key is read-only and will always be set
                     to the common (unambiguous) prefix the  com­
                     pletion  code  has generated for all matches
                     added so far.

                     This gives the position the cursor would  be
                     placed  at if the common prefix in the unam­
                     biguous 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.

                     This contains all positions where characters
                     in the unambiguous  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  com­
              mand line currently being edited.


       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 ... ]
              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 prefix 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 comple­
              tions, 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 command 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 command 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 com­
                     mand 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
                     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 parenthe­

                     If there  are  fewer  display  strings  than
                     words,  the leftover 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  different name space than groups
                     created with the -J flag.

              -1     If given together with the -V option,  makes
                     only  consecutive 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 cur­
                     rently 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 automati­
                     cally removed if the next character typed is
                     a  blank  or does not insert anything, or if
                     the suffix consists of  only  one  character
                     character typed inserts a lowercase  charac­
                     ter  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 comple­
                     tion accepted, the function remove-func will
                     be  called  after  the next character typed.
                     It is passed the length of the suffix as  an
                     argument  and can use the special parameters
                     available in ordinary  (non-completion)  zle
                     widgets  (see zshzle(1)) to analyse and mod­
                     ify 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

              -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  com­
                     plete  filename  for  testing.   Hence it is
                     only useful if combined with the -f flag, as
                     the tests will not otherwise be performed.

              -F array
                     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. Normally this  is  used
                     in  functions  that  do  the  matching them­

              -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  generated  internally
                     by the completion code are stored. For exam­
                     ple, 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 possible 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
                     the  words  have been added.  An empty match
                     takes up space in  completion  listings  but
                     will never be inserted in the line and can't
                     be selected with  menu  completion  or  menu
                     selection.   This  makes  empty matches only
                     useful to format  completion  lists  and  to
                     make  explanatory string be shown in comple­
                     tion lists (since empty matches can be given
                     display  strings  with  the -d option).  And
                     because all but one empty string would  oth­
                     erwise  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  arguments  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 argu­
              ment) 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

              -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, any­
                     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 parameter 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 decre­
                     mented by begin.

                     If the optional end is given, the  modifica­
                     tion  is done only if the current word posi­
                     tion is also less than or equal to  end.  In
                     this  case,  the  words  from  position  end
                     onwards are  also  removed  from  the  words

                     Both  begin and end may be negative to count
                     backwards from the last element of the words

              -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
                     parameter  (so that the matching word has to
                     be after the  cursor).  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  QISUFFIX  are  modified   to

              compctl builtin  from  within  completion  widgets.
              The  list of matches will be generated as if one of
              the non-widget completion function  (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 definition was found. It is non-zero  if  a
              compctl was found and zero otherwise.

              Note  that  this builtin is defined by the zsh/com­
              pctl module.


       The following additional condition codes  for  use  within
       the  [[  ... ]] construct are available in completion wid­
       gets.  These work on the special 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  spe­
       cial parameters are not modified.

       -prefix [ number ] pattern
              true if the test for the -P option of compset would

       -suffix [ number ] pattern
              true if the test for the -S option of compset would

       -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  pat­
              terns would succeed.


       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  pro­
       duced  by  the  completion  code  (referred to here as the
       trial completions). Note that this is not used if the com­
       mand  line  contains  a glob pattern and the GLOB_COMPLETE
       the string already typed on the command line as the  final
       result of completion, while with a lowercase initial char­
       acter the string on the command line is changed  into  the
       corresponding part of the trial completion.

              Here, lpat is a pattern that matches on the command
              line, corresponding to tpat which  matches  in  the
              trial completion.

              These letters are for patterns that are anchored by
              another pattern 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;  otherwise  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 lanchor, the ranchor only needs to
              match the trial completion string.

              The b and B forms are similar to l and  L  with  an
              empty  anchor, but need to match only the beginning
              of the trial completion or the word on the  command
              line, respectively.

              As l, L, b and B, with the difference that the com­
              mand  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
       For example, to make any  lowercase  letter  on  the  line
       match the corresponding uppercase letter in the trial com­
       pletion, 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 characters up  to  the  next  appearance  of  the
       anchor will be matched. With two stars, substrings matched
       by the anchor can be matched, too.


       The keys of the options association defined by the parame­
       ter  module  are  the  option names in all-lowercase form,
       without underscores, and without 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 cor­
       responding lowercase letters in the words:

              compadd -M 'L:|[nN][oO]= M:_= M:{A-Z}={a-z}' - \

       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 underscore
       anywhere in the command line string, and  the  third  part
       uses  correspondence  classes so that any uppercase letter
       on the line matches the corresponding lowercase letter  in
       the word. The use of the uppercase forms of the specifica­
       tion 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

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

       This makes lowercase letters match their  uppercase  coun­
       terparts.   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 consists 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 different problem to be solved by the
       implementation  of the completion widget.  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 com­
       pletion 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 COMPLETE_IN_WORD is set. In this case
       the completion code would normally try to match trial com­
       pletions 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
       The specifications with both a left and a right anchor are
       useful to complete partial words whose parts are not sepa­
       rated 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 sim­
       ple 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.


       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 command:

              bindkey '^X\t' complete

       After that  the  shell  function  complete-files  will  be
       invoked  after  typing  control-X  and  TAB.  The function
       should then generate the matches, e.g.:

              complete-files () { compadd - * }

       ning  `comp' are to be called directly, while those begin­
       ning `_' are called by the  completion  code.   The  shell
       functions  of  the  second set, which implement completion
       behaviour and may be bound to keystrokes, are referred  to
       as `widgets'.


       If  the  system  was  installed  completely,  it should be
       enough to call the shell function compinit from your  ini­
       tialization  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  usu­
       ally 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 section 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 immediately.  However, if compin­
       stall 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 mentioned 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 direc­
       tories  from fpath.  Then it must be autoloaded (`autoload
       -U  compinstall'  is  recommended).   You  can  abort  the
       installation  any time you are being prompted for informa­
       tion, and your .zshrc will not be altered at all;  changes
       only  take  place right at the end, where you are specifi­
       cally 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  automati­
       cally from your .zshrc.
       expand-or-complete,  compinit  will  rebind  it  to   com­
       plete-word;  this  is necessary to use the correct form of

       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-com­

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

       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 per­
       formed 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, comp­
       dump, 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  comple­
       tion  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  directo­
       ries  use  the  option -i.  This security check is skipped
       entirely when the -C option is given.

       The convention for autoloaded functions used in completion
       is  that  they  start  with an underscore; as already men­
       tioned, the fpath/FPATH parameter must contain the  direc­
       tory  in  which  they  are  stored.   If  zsh was properly
       installed on your system, then  fpath/FPATH  automatically
       contains  the  required directories for the standard func­

       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 sub­
       directory 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 for­
       mat as in the zsh source distribution.

       When  compinit is run, it searches all such files accessi­
       ble 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

              Each  name  may  also be of the form `cmd=service'.
              When completing the command cmd, the function typi­
              cally  behaves  as  if the command (or special con­
              text) service was being  completed  instead.   This
              provides  a  way of altering the behaviour of func­
              tions that can perform many different  completions.
              It is implemented by setting the parameter $service
              when calling the function; the function may  choose
              to  interpret this how it wishes, and simpler func­
              tions will probably ignore it.

              If the #compdef line contains one of the options -p
              or  -P,  the  words  following are taken to be pat­
              terns.  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
              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 func­
              tion 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 argument may be given for  each  wid­
              get-name  style  pair.   However, the entire set of
              three arguments may be repeated  with  a  different
              set of arguments.  Note in particular that the wid­
              get-name must be distinct in each set.  If it  does
              not  begin  with  `_' this will be added.  The wid­
              get-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 spe­
              cially.  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 flag is
              always added implicitly.

       The  #  is  part  of  the  tag  name and no white space is
       allowed after it.  The #compdef tags use the compdef func­
       tion described below; the main difference is that the name
       of the function is supplied implicitly.

       Note also that the functions  for  the  completion  system
       assume that the KSH_AUTOLOAD option is not set.  They can­
       not be loaded if it is set.   To  avoid  having  to  unset
              The  name  of  a  parameter expansion within braces

              The name of a parameter in an assignment,  i.e.  on
              the left hand side of an `='

              A word in command position

              A word inside a condition (`[[...]]')

              Any word for which no other completion is defined

              A word beginning with an equals sign

              This is tried before any other completion function.
              The function called may set the _compskip parameter
              to  one  of various values: all: no further comple­
              tion is attempted; a  string  containing  the  sub­
              string  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 `((...))'

              The name of a parameter expansion (`$...')

              The word after a redirection operator.

              The contents of a parameter subscript.

              After an initial tilde (`~'), but before the  first
              slash in the word.

              On the right hand side of an assignment.

       Default  implementations  are  supplied  for each of these
       contexts.  In most cases the context -context-  is  imple­
       mented  by  a corresponding function _context, for example
       the context `-tilde-' and the function `_tilde').

       case of elements of  an  associative  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 functions 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 function 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.


              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 handled 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>' com­
       plete files matching `*.log'.

       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.

                     compdef '_files -g "*.h"' foo

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

              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 identical, switching between defi­
              nitions of patterns tried initially, patterns tried
              finally, and normal commands and contexts.

              The parameter $_compskip may be set by any function
              defined  for  a pattern context.  If it is set to a
              value containing the substring `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-com­
              plete,         menu-expand-or-complete,         and
              reverse-menu-complete,  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 func­
              tion autoloadable, equivalent to autoload -U  func­

       The  function  compdef  can  be used to associate existing
       completion functions with new commands.  For example,

              compdef _pids foo

       When completion is attempted somewhere on the command line
       the completion system first works out the  context.   This
       takes  account of a number 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  con­
       sisting  of  multiple fields separated by colons, referred
       to simply as `the context' in the remainder of  the  docu­
       mentation.  This is used to look up styles, context-sensi­
       tive 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 dis­
              tinguishes 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  `com­
              pleter'  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 correction, or to modify the behaviour of a
              later  completer.   See  the section `Control Func­
              tions' 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 con­
              tain the name of the command followed  by  a  minus
              sign and the sub-command.  For example, the comple­

       ·      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

       As an example, the context name


       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

       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 sec­
       tion `Bindable Commands' below.

       Styles determine such things as how the matches are gener­
       ated,  similarly  to shell options but with much more con­
       trol.  They can have any number of strings as their value.
       They are defined with the zstyle builtin command (see zsh­

       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
       A more specific example of the use of the verbose style is
       by the completion 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 func­
       tions (see see zshcompwid(1))).  For example:

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

       uses the value `_complete' for the completer style in most
       contexts,  but the value `_complete _approximate' when the
       first word on the command line is `cvs'.  This is probably
       more  conveniently  done  by  specifying the style for two
       different contexts.  This form can be slow and  should  be
       avoided  for  commonly  examined  styles  such as menu and

       Note that the order in which styles are defined  does  not
       matter;  the style mechanism uses the most specific possi­
       ble match for a particular style to determine the  set  of
       values.   More  precisely, strings are preferred over pat­
       terns (for example,  `:completion::complete:foo'  is  more
       specific  than `:completion::complete:*'), and longer pat­
       terns are preferred over shorter patterns.

       Style names like those of tags are arbitrary and depend on
       the  completion function.  However, the following two sec­
       tions list some of the most common tags and styles.

   Standard Tags
       Some of the following are only used when looking  up  par­
       ticular styles and do not refer to a type of match.


              for  keys of associative arrays; used when complet­
              ing inside a subscript to a parameter of this type

              when completing bookmarks (e.g. for  URLs  and  the
              zftp function suite)

              for names of builtin commands

              for single characters in arguments of commands such
              as stty.    Also  used  when  completing  character
              classes after an opening bracket

              for X colormap ids

       colors for color names

              for  names of external commands.  Also used by com­
              plex commands such as  cvs  when  completing  names

              for  contexts  in  arguments  to the zstyle builtin

              used by the _approximate  and  _correct  completers
              for possible corrections

              for cursor names used by X programs

              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

              used when looking up the value of the format  style
              to generate descriptions for types of matches

              for names of device special files

              resulting  from the expansion of a word on the com­
              mand line

              for X server extensions

              for numbers of open file descriptors

       files  the generic file-matching  tag  used  by  functions
              completing filenames

       fonts  for X font names

              for file system types (e.g. for the mount command)

              names  of  functions  --- normally shell functions,
              although  certain  commands  may  understand  other
              kinds of function

              for  filenames  when the name has been generated by
              pattern matching

       groups for names of user groups

              for words from the history

       hosts  for hostnames

              for array indexes

       jobs   for jobs (as listed by the `jobs' builtin)

              for network interfaces

              for names of zsh keymaps

              for names of X keysyms

              for names of system libraries

       limits for system limits

              used to look up the format style for messages

              for names of X modifiers

              for modules (e.g. zsh modules)

              used to look up the users-hosts style

              for  named  directories  (you wouldn't have guessed
              that, would you?)

       names  for all kinds of names

              for USENET groups

              for nicknames of NIS maps

              for command options

              used by the _approximate, _correct and _expand com­
              pleters  when  offering  the  original  string as a

              used to look up the users-hosts style

              for packages (e.g. rpm or  installed  Debian  pack­

              for names of parameters

              for  names  of  directories  found by searching the
              cdpath array when completing arguments  of  cd  and
              related  builtin  commands  (compare local-directo­

       paths  used to look up the values of the expand, ambiguous
              and special-dirs styles

       pods   for perl pods (documentation files)
              the names of processes for killall

              for sequences (e.g. mh sequences)

              for sessions in the zftp function suite

              for signal names

              for strings (e.g. the replacement strings  for  the
              cd builtin command)

       styles for styles used by the zstyle builtin command

              for filename extensions

       tags   for tags (e.g. rpm tags)

              for makefile targets

              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 com­
              pleting URLs

       users  for usernames

       values for one of a set of values in certain lists

              used by _pick_variant to look up the command to run
              when  determining  what  program is installed for a
              particular command name.

              for X visuals

              used to look up the format style for warnings

              for zsh widget names

       be either true or false if the style is not set.

       Some of these styles are tested first for  every  possible
       tag  corresponding 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 ...

              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 oth­
              erwise 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  con­
              tains some more partially typed pathname components
              and  these  match  no  file  under  the   directory

              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.

              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 substitu­
              tion of the form `$(...)' or `${...}'.

              The _prefix completer uses this style as  a  simple
              boolean  value  to  decide  if  a  space  should be
              cases the value  may be a list of  filenames  sepa­
              rated  by  colons, as with PATH and similar parame­
              ters.  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.

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

              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 gener­
              ated.  Its value is a list of names of  completers.
              If  any  of these is the name of the completer that
              generated  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.

              This style defines the path where any  cache  files
              containing  dumped  completion data are stored.  It
              defaults     to     `$ZDOTDIR/.zcompcache',      or
              `$HOME/.zcompcache'  if  $ZDOTDIR  is  not defined.
              The completion cache will not be  used  unless  the
              use-cache style is set.

              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.

              This  style  is  used  in the function for commands
              such as make and  ant  where  calling  the  command
              directly  to generate matches suffers problems such
              as being slow or, as in the case of make can poten­
              tially  causes  actions  in the makefile to be exe­
              cuted. If it is set to `true' the command is called
              called, for example to avoid calling a shell  func­
              tion 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  gen­
              erate 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 gen­
              erate  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.

              This is used by the  function  completing  sub-com­
              mands for the system initialisation scripts (resid­
              ing in /etc/init.d or somewhere not  too  far  away
              from  that).   Its values give the default commands
              to complete for those commands for which  the  com­
              pletion  function isn't able to find them out auto­
              matically.  The default for this style are the  two
              strings `start' and `stop'.

              This  is  used  by  the _expand_alias function when
              invoked as a bindable command.  If it set to `true'
              and the word on the command line is not the name of
              an alias, matching alias names will be completed.

              The strings given as the value of this  style  pro­
              vide  the  names of the completer functions to use.
              The available completer functions 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 completer field of the con­
              text will contain the name of the completer 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
              name  will  be  the  same  in all calls to the com­
              pleter; 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.

              This style is used by the _list completer  function
              to decide if insertion of matches should be delayed
              unconditionally. The default is `true'.

              If this is set to `true',  the  _expand_alias  com­
              pleter and bindable command will try to expand dis­
              abled aliases, too.  The default is `false'.

              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.

              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 consist­
              ing of multiple 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

              If one of its values is the string `suffix', match­
              ing  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 context.  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
              pleting 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.

              This is used by the completion function for parame­
              ter 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 com­
              pleted if parameters of that type are  required  in
              the particular context.  Names for which no type is
              specified will always be completed.

              This is used by the standard function for  complet­
              ing filenames, _files.  If the style is unset up to
              three tags are  offered,  `globbed-files',`directo­
              ries'  and  `all-files',  depending on the types of
              files  expected by the caller of _files.  The first
              two  (`globbed-files'  and  `directories') are nor­
              mally offered together to make it  easier  to  com­
              plete 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 specifi­
              cations separated by spaces.

              The pattern is a pattern that is to be used to gen­
              erate filenames.  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 dis­
              tinguishable from the colon  before  the  tag.   If
              more  than  one pattern is needed, the patterns can
              be given inside braces, separated 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.

                         '*.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  charac­
              ters  `#', `~' and `^' have special meanings in the

              The standard filename completion function uses this
              style without a tag to determine in which order the
              names should be listed; menu completion will  cycle
              through  them in the same order.  The possible val­
              ues 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  modification  time;  `access'  to sort by the
              last access time; and `inode' (or `change') to sort
              by the last inode change time.  If the style is set
              to any other value, or  is  unset,  files  will  be
              sorted  alphabetically  by name.  If the value con­
              tains 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 nor­
              mal 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.

              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

       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  completion  before  it  is  tested for the
              descriptions tag.  Hence different  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 customised by setting this style  for  the  mes­
              sages  tag.  Here, the `%d' is replaced with a mes­
              sage given by the completion function.

              Finally, the format string is looked  up  with  the
              warnings tag, for use when no matches could be gen­
              erated 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

              It is possible  to  use  printf-style  field  width
              specifiers  with `%d' and similar escape sequences.
              This is handled by the zformat builtin command from
              the zsh/zutil module, see zshmodules(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 completer and bindable  command  will
              try to expand global aliases.

              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 command  position
              the  completion  system  generates names of builtin
              and external  commands,  names  of  aliases,  shell

                     zstyle ':completion:*' group-name ''

              All matches for which no group name is defined will
              be put in a group named -default-.

              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 func­

              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  con­
              text  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 possible completions at  all,
              the  tag-order  style  can be modified as described

       hosts  A list of names of hosts that should be  completed.
              If  this  is  not set, hostnames are taken from the
              file `/etc/hosts'.

              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.

              This is tested for each tag valid for  the  current
              completion.   If  it  is set to `true', none of the
              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 multi­
              ple  times  even if the command in question accepts
              the option more than once.

              The style is tested without a tag by  the  function
              completing  pathnames in order to determine whether
              to ignore the names  of  directories  already  men­
              tioned in the current word, or the name of the cur­
              rent 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  con­
                     sidered 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

                     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  com­

              A  list  of patterns; any trial completion matching
              one of the patterns will be excluded from consider­
              ation.   The  _ignored  completer 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 char­
              explicitly  to  `menu')  the name will be converted
              immediately to a set of possible IDs, and menu com­
              pletion 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 converting the name to an
              ID; attempts at  completion  will  be  unsuccessful
              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.

              If this is set to  `true',  the  completion  system
              will insert a TAB character (assuming that was used
              to start completion) instead of performing  comple­
              tion  when  there  is no non-blank character to the
              left of the cursor.  If it is set to `false',  com­
              pletion will be done even there.

              The value may also contain the substrings `pending'
              or `pending=val'.  In this case, the typed  charac­
              ter  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 guaranteed  on  all

              The  default  value  of this style is `true' except
              for completion within vared builtin  command  where
              it is `false'.

              This  is  used  by the _match and _approximate com­
              pleters.  These completers are often used with menu
              completion  since  the  word  typed may bear little
              resemblance to the final completion.   However,  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 com­
              pleter  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.

              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 origi­
              nal; hence any remaining completers may be  called.

              This    is    a   more   flexible   form   of   the
              ALWAYS_LAST_PROMPT option.  If it is true, the com­
              pletion system will try to return the cursor to the
              previous command line after displaying a completion
              list.  It is tested for all tags valid for the cur­
              rent completion, 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 inde­
              pendent of the numeric prefix argument.

       list   This style is used  by  the  _history_complete_word
              bindable command.  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  particu­
              lar  AUTO_LIST.   The  context  always  starts with

              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 section
              `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 everywhere.  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  possible  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

              It is possible  to  use  any  color  specifications
              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

              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.

              If  this  style is set for the default tag, comple­
              tion 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 screen­
              ful 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  per­
              centage  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.

              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.

              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 components
              will  be shown.  Otherwise, completion stops at the
              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/pub­
              lic/toast/stuff,      while     completion    after
              `http://toast/~yousir/' will look for files in  the
              directory ~yousir/public_html.

              If  set,  zsh will assume that mailbox files can be
              found in the directory specified.  It  defaults  to

              This is used by the _match completer.  If it is set
              to only, _match will try to generate matches  with­
              out 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.

              This  style is tested separately for each tag valid
              in the current 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).

              This style can be set to a list of match specifica­
              tions that are  to  be  applied  everywhere.  Match
              specifications are described in the section `Match­
              ing Control' in zshcompwid(1).  The completion sys­
              tem  will  try them one after another for each com­
              pleter selected.  For example, to try first  simple
              completion  and,  if  that  generates  no  matches,
              case-insensitive completion:

                     zstyle ':completion:*' matcher-list '' 'm:{a-zA-Z}={A-Za-z}'

              By default each specification replaces the previous
              one;  however,  if a specification is prefixed with
              +, it is added to the existing list.  Hence  it  is
              possible  to create increasingly general specifica­
              User-defined names, as explained for the  completer
              style,  are  available.   This makes it possible to
              try the same completer more than once with  differ­
              ent  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

                     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 spec­
              ification is applied.  Note  also  that  some  com­
              pleters  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 appre­
              ciable impact on performance.

              This  is used by the _approximate and _correct com­
              pleter functions to determine the maximum number of
              errors  to allow.  The completer will try to gener­
              ate 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 comple­
              tion will be attempted unless a numeric argument is
              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

              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 set­

              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 comple­
              tion 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'  (Typically,  the  value
              `select=long-list'  described  later is more useful
              as it provides control over scrolling.)

              Similarly, with any of the `false'  values  (as  in
              `no=10'), menu completion will not be used if there
              are num or more matches.

              The value of this widget also controls menu  selec­
              tion,  as  implemented  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.

              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  interactive  mode to be entered
              immediately when menu selection is started; see the
              description  of  the zsh/complist module in zshmod­
              ules(1).RE for a description of  interactive  mode.
              Including  the  string  `search'  does the same for
              incremental search mode.  To select backward incre­
              mental  search,  include  the  string `search-back­
              ward'.  )

              muttrc If set, gives the location of the mutt  con­
                     figuration  file.   It  defaults to `~/.mut­

                     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.

                     This  is used by the _oldlist completer.  If
                     it is set to `always', then standard widgets
                     which  perform  listing will retain the cur­
                     rent list of matches, however they were gen­
                     erated;  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 gen­
                     erated  the  list, then the old list will be
                     used even if it was generated  by  a  widget
                     which does not do listing.

                     that  further  completion could produce more
                     matches than on the first attempt.  By using
                     the  _oldlist  completer  and  setting  this
                     style to _match, the list of matches  gener­
                     ated  on  the  first  attempt  will  be used

                     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  uncondi­
                     tionally.   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.

                     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 com­
                     pletion is started if the old list was  gen­
                     erated  by  a  different completion command;
                     this is the behaviour without  the  _oldlist

                     For  example, suppose you type ^Xc to gener­
                     ate a list of corrections, and menu  comple­
                     tion  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.

                     This is used by the _approximate  and  _cor­
                     rect  completers  to  decide if the original
                     string should be added as a possible comple­
                     tion.   Normally, this is done only if there
                             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  loca­
                     tions it will be used as the default.

                     If  set,  specifies the directory containing
                     PINE  mailbox   files.    It   defaults   to

              ports  A  list  of  Internet service names (network
                     ports) to complete.  If  this  is  not  set,
                     service   names  are  taken  from  the  file

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

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

                     The  default value for this style is `true'.

                     This style  is  used  when  completing  path
                     names.  Its value should be a pattern match­
                     ing an initial prefix of the  word  to  com­
                     plete  that  should  be left unchanged under
                     all circumstances.   For  example,  on  some
                     Unices  an initial `//' (double slash) has a
                     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

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

                     This style is used by the _expand_alias com­
                     pleter  and  bindable  command.   If  set to
                     `true' (the default), regular  aliases  will
                     be  expanded  but  only in command position.
                     If it is set  to  `false',  regular  aliases
                     will  never  be  expanded.   If it is set to
                     `always', regular aliases will  be  expanded
                     even if not in command position.

                     If  set  to  false, certain commands will be
                     prevented from making  Internet  connections
                     to   retrieve   remote   information.   This
                     includes the completion for the CVS command.

                     It is not always possible to know if connec­
                     tions are in fact to a remote site, so  some
                     may be prevented unnecessarily.

                     The  _history_complete_word bindable command
                     and  the  _history  completer  use  this  to
                     decide  if  all  duplicate matches should be
                     removed, rather than just consecutive dupli­

                     If  this  is  set  for  the default tag, its
                     value will be displayed during  menu  selec­
                     tion  (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.

                     This style is tested for the default tag and
                     determines how a completion list is scrolled
                     during  a menu selection (see the menu style
                     `true',  entries  for different sections are
                     added separately using tag names of the form
                     `manual.X',  where  X is the section number.
                     When the group-name style is also in effect,
                     pages  from  different  sections will appear
                     separately.  This style is also  used  simi­
                     larly  with  the words style when completing
                     words for the dict command. It allows  words
                     from  different  dictionary  databases to be
                     added  separately.   The  default  for  this
                     style is `false'.

                     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   If set to `true', completing words from  the
                     command  history  sorts the words alphabeti­
                     cally instead of keeping them in  the  order
                     in  which  they  appear in the history (from
                     youngest to oldest).

                     This is also used by the _expand  completer.
                     If  it is set to `true', the expansions gen­
                     erated will always be sorted.  If it is  set
                     to  `menu',  then  the  expansions  are only
                     sorted  when  they  are  offered  as  single
                     strings but not in the string containing all
                     possible expansions.

                     Normally, the completion code will not  pro­
                     duce  the  directory  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=(..)'

                     wrap  around to the opposite end of the his­
                     tory.  If this style is set to `false'  (the
                     default),  _history_complete_word  will loop
                     immediately as in a menu completion.

                     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.

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

                     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 some­
                     thing 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

                     This provides a mechanism  for  sorting  how
                     the  tags  available in a particular context
                     will be used.

                     The  values  for  the  style  are  sets   of
                     space-separated  lists of tags.  The tags in
                     each value will be tried at the  same  time;
                     In addition to tag names, each string in the
                     value may take one of the following forms:

                      -      If  any  value  consists  of  only a
                             hyphen, then only the tags specified
                             in  the  other values are generated.
                             Normally  all  tags  not  explicitly
                             selected are tried last if the spec­
                             ified  tags  fail  to  generate  any
                             matches.   This  means that a single
                             value consisting only  of  a  single
                             hyphen turns off completion.

                     ! tags...
                             A  string  starting with an exclama­
                             tion mark specifies  names  of  tags
                             that are not to be used.  The effect
                             is the same as if all other possible
                             tags   for   the  context  had  been

                     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, supplying different style set­
                             tings  for  each  attempt; see below
                             for an example.

                             As  before,  but  description   will
                             replace the `%d' in the value of the
                             format style instead of the  default
                             description  supplied by the comple­
                             tion  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

                     In  any  of the forms above the tag may be a
                     pattern or  several  patterns  in  the  form
                             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 under­
                     score.  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

                     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 containing multiple
                     characters, and single-letter  options  will
                     be displayed in separate groups with differ­
                     ent descriptions.

                     Another use of patterns is to  try  multiple
                     match specifications one after another.  The
                     matcher-list style offers something similar,
                     but  it  is tested very early in the comple­
                     tion system and hence can't be set for  sin­
                     gle commands nor for more specific contexts.
                     Here is how to try normal completion without
                     any  match specification and, if that gener­
                     ates no matches, try again with  case-insen­
                     sitive  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
                                 if [[ -n $PREFIX$SUFFIX ]]; then
                                   reply=( )
                                   reply=( - )

                     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 completion widgets.  Setting reply to
                     an  empty   array   provides   the   default
                     behaviour  of  trying all tags at once; set­
                     ting 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 function will
                     be used to provide a sensible default behav­
                     ior  that  causes  arguments (whether normal
                     command arguments or arguments  of  options)
                     to be completed before option names for most

              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 directory, the  directory  hierarchy
                     rooted  at  this directory gives the comple­
                     tions.  The top level  directory  should  be
                     the  file  access  method,  such  as `http',
                     `ftp', `bookmark' and so on.  In many  cases
                     the  next  level  of  directories  will be a
                     filename.   The  directory   hierarchy   can
                     descend as deep as necessary.

                     For example,
                     itself  for  more  information  (e.g.  `more

                     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 direc­
                     tory  containing  the  cache  files  can  be
                     changed with the cache-path style.

                     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/compctl  module  is  loaded.    The
                     string   may   also  contain  the  substring
                     `first'  to  use  completions  defined  with
                     `compctl -T', and the substring `default' to
                     use the  completion  defined  with  `compctl

                     Note  that  this  is only intended to smooth
                     the transition from compctl to the new  com­
                     pletion  system  and  may  disappear  in the

                     Note also that the definitions from  compctl
                     will  only  be  used if there is no specific
                     completion function for the command in ques­
                     tion.   For  example, if there is a function
                     _foo to complete arguments  to  the  command
                     foo,  compctl will never be invoked for foo.
                     However, the compctl version will  be  tried
                     if foo only uses default completion.

                     Various parts of the function system use awk
                     to extract words from files or command  out­
                     put 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 frustration.

                     values of the style.

                     It  is  possible to group values for sets of
                     commands which allow a remote login, such as
                     rlogin  and  ssh,  by  using the my-accounts
                     tag.  Similarly, values for sets of commands
                     which usually refer to the accounts of other
                     people, such as  talk  and  finger,  can  be
                     grouped  by  using  the  other-accounts tag.
                     More  ambivalent  commands   may   use   the
                     accounts tag.

                     Like  users-hosts but used for commands like
                     telnet and containing strings  of  the  form

                     If  set, as it is by default, the completion
                     listing is more verbose.  In particular many
                     commands  show  descriptions  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 occa­
                     sions.  If this style is true, the  compari­
                     son is instead performed only on the current
                     word.  Hence if completion is  performed  on
                     another word with the same contents, comple­
                     tion will not be delayed.


       The initialization script compinit redefines all the  wid­
       gets  which perform completion to call the supplied widget
       function _main_complete.  This function acts as a  wrapper
       calling  the so-called `completer' functions that generate
       matches.  If  _main_complete  is  called  with  arguments,
       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 completion  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  com­
       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

              This completer can be used to add a string consist­
              ing 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

              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  completion  yields no possible completions.
              When corrected completions are found, the completer
              will normally start menu completion allowing you to
              cycle through these strings.

              This completer uses the tags corrections and origi­
              nal  when  generating  the possible corrections and
              the original string.  The format style for the for­
              mer  may  contain the additional sequences `%e' and
              `%o' which will be replaced by the number of errors
              accepted to generate the corrections and the origi­
              nal string, respectively.

              The completer progressively increases the number of
              errors  allowed  up  to the limit by the max-errors
              style, hence if a  completion  is  found  with  one
              error,  no  completions  with  two  errors  will be
              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,

                     zstyle -e ':completion:*' completer '
                       if [[ $_last_try != "$HISTNO$BUFFER$CURSOR" ]]; then
                         reply=(_complete _match _prefix)
                         reply=(_ignored _correct _approximate)

              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  com­
              mand  line  hasn't changed since the last time com­
              pletion was tried.  Only  then  are  the  _ignored,
              _correct and _approximate completers called.

              This  completer  generates all possible completions
              in a context-sensitive manner, i.e. using the  set­
              tings  defined  with the compdef function explained
              above and  the  current  settings  of  all  special
              parameters.    This  gives  the  normal  completion

              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
              mentioned  above as possible arguments to the #com­
              pdef tag.

              Before trying to find a  function  for  a  specific
              context,  _complete  checks if the parameter `comp­
              context' 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 ele­
              ments 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 comple­
              tions 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

              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 _approx­
              imate, 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 completion will be, and
              will accept as many errors as given by the  numeric
              argument.   Without  a numeric argument, first cor­
              rection 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  _approxi­
              mate  will  at least generate the corrected strings
              generated by the _correct completer -- and probably

              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 possi­
              It is also possible to call _expand as a  function,
              in  which  case the different modes may be selected
              with options: -s for substitute, -g for glob and -o
              for subst-globs-only.

              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 dis­

              This  function  is also a bindable command, see the
              section `Bindable Commands' below.

              Complete words from the shell's  command   history.
              This   completer   can   be   controlled   by   the
              remove-all-dups, and sort styles as for  the  _his­
              tory_complete_word  bindable  command, see the sec­
              tion `Bindable  Commands'  below  and  the  section
              `Completion System Configuration' above.

              The  ignored-patterns style can be set to a list of
              patterns which are compared against  possible  com­
              pletions;  matching  ones  are  removed.  With this
              completer those matches can be reinstated, 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  completer.   The   sin­
              gle-ignored  style  is  also available as described

       _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 Con­
              figuration' above.

       _match This completer is intended to  be  used  after  the
              _complete  completer.  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 cur­
              sor position and comparing  the  resulting  pattern
              mented  to  show how menu completion can be done in
              shell code.  It should be used as  the  first  com­
              pleter  and  has  the  effect  of making later com­
              pleters perform menu completion.  Note that this is
              independent  of  the  setting  of the MENU_COMPLETE
              option and does not work with the other  menu  com­
              pletion  widgets  such as reverse-menu-complete, or

              This completer controls how the standard completion
              widgets  behave  when  there is an existing list of
              completions which may have been generated by a spe­
              cial completion (i.e. a separately-bound completion
              command).  It allows the ordinary  completion  keys
              to  continue  to  use  the list of completions thus
              generated, instead of producing a new list of ordi­
              nary  contextual  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
              System Configuration' above.

              This  completer  can be used to try completion with
              the suffix (everything after the  cursor)  ignored.
              In  other  words, the suffix 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  completers  only  those  completers  not
              already tried by the  last  invocation  of  _prefix
              will be called.

              For example, consider this global completer style:

                     zstyle ':completion:*' completer \
                         _complete _prefix _correct _prefix:foo

              Here, the _prefix completer tries normal completion
              but ignoring the suffix.  If that doesn't  generate
              any matches, and neither does the call to the _cor­
              rect 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'.
              will be moved to the end of the current word before
              the completion code is called and hence there  will
              be no suffix.

              This  function  provides  compatibility with bash's
              programmable completion system.  When run  it  will
              define  the  functions,  compgen and complete which
              correspond to  the  bash  builtins  with  the  same
              names.   It will then be possible to use completion
              specifications and functions written for bash.


       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.

              This function is used by  two  widgets,  _bash_com­
              plete-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;  `$',  envi­
              ronment  variables;  `@',  host  names;  `/',  file
              names; `~' user names.  In bash, the  binding  pre­
              ceded  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

              This includes the bindings for  `~'  in  case  they
              were  already  bound to something else; the comple­
              tion 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)
              tional  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-com­
              plete alias name.

       _expand_word (^Xe)
              Performs expansion on the current word:  equivalent
              to  the standard expand-word command, but using the
              _expand completer.  Before calling it, the function
              field of the context is set to `expand-word'.

              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
              completion widgets with their own set of style set­
              tings 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

       _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 available.   Succes­
              sive  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  per­
              able  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 argument.

       _complete_debug (^X?)
              This  widget performs ordinary completion, but cap­
              tures in a temporary file a trace of the shell com­
              mands executed by the completion system.  Each com­
              pletion 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 functions called, which in turn
              is determined by the user's own  styles  and  other

       _complete_tag (^Xt)
              This  widget  completes  symbol tags created by the
              etags or ctags programmes (note there is no connec­
              tion with the completion system'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 pre­
              ferred.  You can specify the full path to a TAGS or
              tags  file  by  setting  the parameter $TAGSFILE or
              $tagsfile respectively.  The corresponding  comple­
              tion tags used are etags and vtags, after emacs and
              vi respectively.


       Descriptions follow for utility functions that may be use­
       ful  when  writing completion functions.  If functions are
       _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 automatically  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

              Will complete the strings from the matches  parame­
              ter,  using  compadd  with additional options which
              will  take  precedence  over  those  generated   by

       _alternative [ -C name ] spec ...
              This  function is useful in simple cases where mul­
              tiple tags are available.   Essentially  it  imple­
              ments  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  description
              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

                     _alternative \
                         'users:user:_users' \


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

                     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.

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

                     This   describes   how   arguments  (usually
                     non-option arguments,  those  not  beginning
                     with  -  or +) are to be completed when nei­
                     ther 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
                     message  they  are modified to refer only to
                     the  normal  arguments   covered   by   this

                     The  combination  of  -s with -w allows sin­
                     gle-letter options to be combined in a  sin­
                     gle  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  optspec,  whether or not the option
                     has arguments.

                             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 cur­
                             sor it will not be offered again.

                             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

                             Either of  `-+optname'  and  `+-opt­
                             name'  can  be  used to specify that
                             -optname  and  +optname   are   both

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

                             like either `-fooarg' or `-foo arg'.

                             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 exam­
                             ple `-foo=arg' or `-foo arg'.

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

                             An   explanation   string   may   be
                             appended  to  any  of  the preceding
                             forms of optspec by enclosing it  in
                             brackets,  as  in  `-q[query  opera­

                             The verbose style is used to  decide
                             whether  the explanation strings are
                             displayed with the option in a  com­
                             pletion 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:

                     An  argument  to  the  option;  message  and
                     action  are  treated  as  for ordinary argu­
                     ments.  In the first form, the  argument  is
                     mandatory,  and  in  the  second  form it is

                     wise,  all  the  words up to a word matching
                     the pattern are to be  completed  using  the

                     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 descrip­

       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 command line, the options and argu­
       ments 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  various  other  items that should not be applied
       when the current specification is matched: a  single  star
       (*)  for  the  rest arguments (i.e. a specification of the
       form `*:...'); a colon (:) for  all  normal  (non-option-)
       arguments; and a hyphen (-) for all options.  For example,
       if `(*)' appears before an option and the  option  appears
       on  the  command  line,  the  list  of remaining arguments
       (those shown in the above table beginning with `*:')  will
       not be completed.

       To  aid in reuse of specifications, it is possible to pre­
       cede 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  nor­
       mal.   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  `_argu­
       ments !$^global_options'.

       In  each of the forms above the action determines how com­
       pletions should be generated.  Except for  the  `->string'
              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.

              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  parameters `context', `line' and `opt_args'
              as described below, and does not reset any  changes
              made  to  the special parameters such as PREFIX and
              words.  This gives the calling function the  choice
              of   resetting   these  parameters  or  propagating
              changes in them.

              A function calling _arguments  with  at  least  one
              action   containing  a  `->string'  therefore  must
              declare appropriate local parameters:

                     local context state line

              tents of the argument field of the current  context
              as the new first element in the words special array
              and increment the  value  of  the  CURRENT  special
              parameter.   This  has  the  effect  of inserting a
              dummy word onto the completion command  line  while
              not  changing the point at which completion is tak­
              ing 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 appro­
              priate command name into the range for  the  second
              call to _arguments to be able to parse the line.

              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  com­
              mand.   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 exclud­
       ing  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 backslashes.

       The parameter `context' is set when returning to the call­
       ing  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
       by all the remaining sets.  The first word in every  other
       set provides a name for the set which may appear in exclu­
       sion 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 remain­

       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 completions.  When it contains `-d' or
       an argument, the option `-c' will not be considered.  How­
       ever, after `-a' both sets will still be considered 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 specifications 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)' \

       As the completion code has to parse the command line sepa­
       rately  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 defini­

       The options -S and -A are available to simplify the speci­
       fications for commands with standard option parsing.  With
       -S, no option will be completed after a `--' appearing  on
       its  own  on  the  line;  this  argument will otherwise be
       ignored; hence in the line

       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  compadd  builtin  to  all

       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

       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 cur­
       rent 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 commands.  The command word is called
       with the argument `--help' and  the  output  examined  for
       option  names.   Clearly, it can be dangerous to pass this
       to commands which may  not  support  this  option  as  the
       behaviour of the command is unspecified.

       In addition to options, `_arguments --' will try to deduce
       the types of arguments available for options when the form
       `--opt=val'  is  valid.   It  is  also possible to provide
       hints by examining the help text of the command and adding
       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 message and action are used as for other argu­
       ment specifiers.  For example:

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

       Here,  `yes' and `no' will be completed as the argument of
       options whose description ends in a star; file names  will
       if  the  argument  for an option is optional.  This can be
       specified explicitly by doubling the colon before the mes­

       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 pat­
       terns'  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

              _arguments -- -i \

       will cause completion to ignore the options `--enable-FEA­
       TURE' 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
       completion 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 `let­
       ter' and `A4' will be completed.

       The `-copy' option may appear more than once on  the  com­
       mand line and takes two arguments.  The first is mandatory
       and will be  completed  as  a  filename.   The  second  is
              tifier 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_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  function  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_pro­
              gram,  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 user­
              names.  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
              specification restricts the completions which apply
              to  elements of the style with appropriately match­
              ing 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  example, if there is no `users-hosts-ports' or
              no matching hostname when a host is  required,  the
              function `_hosts' will automatically 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

              All arguments after the  required  field  name  are
              passed  to compadd 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 descrip­
              tions.  Multiple groups separated by -- can be sup­
              plied,   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 followed 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  `comple­
              tion: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 com­
              pletion strings from the first array.  The  comple­
              tion  list  will  retain  the descriptions from the
              first array.  Finally, a set of completion  options
              can appear.

              If  the  option `-o' appears before the first argu­
              ment, 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-hidden, pre­
              the same description will appear  together  in  the

              _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 previ­
              ous one; it is used as a helper function for creat­
              ing  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 corresponding
              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 modified  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 con­
              tain 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 appearance
              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  correspond­
              ing matches.

              The  options  placed in the array name take account

              Note the use of the parameter expl, the hyphen, and
              the  list  of matches.  Almost all calls to compadd
              within the completion system use a similar  format;
              this  ensures  that  user-specified styles are cor­
              rectly passed down to the builtins which  implement
              the internals of completion.

       _dispatch context string ...
              This  sets the current context to context and looks
              for completion functions to handle this context  by
              hunting  through  the list of command names or spe­
              cial 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 fallback.

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

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

              This function is a simple wrapper around the _argu­
              ments  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

       _guard [ options ] pattern descr
              ventions 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:

                     _argument '-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 com­

       _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  com­
              pletions 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  com­
              padd  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  whites­
              pace.   The  possible  completions  are the strings
              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, other­
              wise 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

              The  options  given  after the descr are set in the
              parameter given by name, and hence are to be passed
              to  compadd  or  whatever function 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  han­
              dles   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
                     return ret

              This is the standard function called to handle com­
              pletion  outside  any  special  -context-.   It  is
              called both to complete the command word  and  also
              the  arguments  for a command.  In the second case,
              _normal looks for a  special  completion  for  that
              command,  and  if there is none it uses the comple­
              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.

              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_complete 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 com­
              pletion system.

              This is used to complete the names of shell parame­

              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 pattern
              is probably necessary.

              All  other  arguments  are  passed  to  the compadd

              This function is  used  throughout  the  completion
              system to complete filenames.  It allows completion
              of  partial  paths.   For   example,   the   string
              `/u/i/s/sig'      may      be      completed     to

              The options accepted by both _path_files and _files

              -f     Complete   all   filenames.    This  is  the
                     shown in completion listings.   Here,  paths
                     may  be  the  name  of an array parameter, a
                     literal list of paths enclosed in  parenthe­
                     ses or an absolute pathname.

              -F ignored-files
                     This behaves as for the corresponding option
                     to the compadd  builtin.   It  gives  direct
                     control   over  which  filenames  should  be
                     ignored.  If the option is not present,  the
                     ignored-patterns style is used.

              Both _path_files and _files also accept the follow­
              ing 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  command name requires more than one type of
              handling, either because it has more than one vari­
              ant  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=pat­
              tern;  if the output of `command 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 sta­
              tus 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 com­
              mand run.

       _regex_arguments name spec ...
              This function generates a completion function  name
              which matches the specifications spec ..., a set of
              one fails; in the latter case, the next alternative
              is  tried.  This structure can be repeated to arbi­
              trary 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 (implying the remaining word is the
              one for which completions  are  to  be  generated).
              The  completion target is restricted to the remain­
              ing word and any actions for the corresponding pat­
              terns  are  executed.   In  this  case,  nothing is
              stripped from the command 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]
                     This is a single primitive  component.   The
                     function  tests whether the combined pattern
                     `(#b)((#B)pattern)lookahead*'  matches   the
                     command  line  string.   If  so,  `guard' is
                     evaluated and its return status is  examined
                     to determine 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

              /pattern/+          [%lookahead%]          [-guard]
                     This  is  similar to `/pattern/ ...' but the
                     left part of the command line  string  (i.e.
                     the  part  already  matched by previous pat­
                     terns) is also considered part of  the  com­
                     pletion target.

              /pattern/-          [%lookahead%]          [-guard]
                     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

              ( spec )

       _requested  [  -x  ]  [ -12VJ ] tag [ name descr [ command
       args ... ] ]
              This  function  is  called  to decide whether a tag
              already registered 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 otherwise.
              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
                       ... # test the tags bar and baz in the same way
                       ... # exit loop if matches were generated

              Note  that the test for whether matches were gener­
              ated 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 com­
              pleted 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

                     local expl ret=1
                     _tags foo bar baz
                     while _tags; do
                       _requested foo expl 'description' \
                           compadd foobar foobaz && ret=0
                       (( ret )) || break

              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
              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 com­
              padd builtin used to add the matches.

       _setup tag [ group ]
              This function sets up the special  parameters  used
              by  the completion 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

       _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 parame­
              ters; this function then dumps the values of  those
              parameters  to  a  file.   The  data  can  then  be
              retrieved    quickly    from    that    file    via
              _retrieve_cache, even in different instances of the

              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  function  will  only  attempt  storage  if the
              use-cache style is set, so you can call this  func­
              tion 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
              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 argument field (the fifth) of the context in
              the curcontext parameter 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  (val­
              ues) and their arguments, or lists of such combina­

              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

              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  val­
              ues  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 val­

              All other arguments describe  the  possible  values
              and their arguments 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
                             '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 commas.

              Like  _arguments,  this  function  temporarily adds
              another context name  component  to  the  arguments
              element  (the  fifth)  of the current context while
              executing the action.  Here this name is  just  the
              name  of  the  value for which the argument is com­

              The style verbose is used to decide if the descrip­
              tions  for  the values (but not those for the argu­
              ments) should be printed.

              The associative array val_args is  used  to  report
              values and their arguments; this works similarly to
              the opt_args associative array used by  _arguments.
              Hence  the  function calling _values should declare
              the  local  parameters  state,  line,  context  and

                     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 com­

              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

              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,  includ­
              ing  the loop over both tags and tag labels and the
              generation of matches, is carried out automatically
              by _wanted.

              Hence to offer only one tag and immediately add the
              corresponding 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 com­

              Like _tags this function supports the -C option  to
              give  a  different  name  for  the argument context
              field.  The -x option has the same meaning  as  for


       In  the  source  distribution,  the files are contained in
       various subdirectories of the Completion directory.   They
       may have been installed in the same structure, or into one
       single function directory.  The following 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 documented 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

       Unix   Functions for completing arguments of external com­
              mands and suites of commands.  They may need  modi­
              fying  for your system, although in many cases some
              attempt is made to decide which version of  a  com­
              mand  is  present.  For example, completion for the
              mount command tries to determine the system  it  is
              running  on, while completion for many other utili­


       zshcompctl - zsh programmable completion


       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
       compctl 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 exam­
       ple  be  filenames  (the  most  common case, and hence the
       default), shell variables, or words from a  user-specified


       Completion  of the arguments of a command may be different
       for each command or may use  the  default.   The  behavior
       when  completing the command word itself may also be sepa­
       rately 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 subse­
       quently in the section `Option Flags':

       command ...
              controls  completion  for the named commands, which
              must be listed last on the command line.   If  com­
              pletion  is attempted for a command with a pathname
              containing slashes and no completion definition  is
              found, the search is retried with the last pathname
              component. If the command starts with a =,  comple­
              tion is tried with the pathname of the command.

              Any  of  the command strings may be patterns of the
              name  is  determined  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 completed.  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  argu­
              ments  of  commands not assigned any special behav­
              ior.  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 specific commands.  This
              is especially useful when  combined  with  extended
              completion  (the -x flag, see the section `Extended
              Completion' below).  Using this flag you can define
              default  behavior  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
              contains  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 fol­
              low  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, com­
       specifications  (the  empty string) and, if that generates
       no matches, will try case insensitive completion.


       [ -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  argu­
       ments  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

       -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

       -O     Names of read-only variables.

       -p     Names of parameters used by  the  shell  (including
              special parameters).

       -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 com­
              mand 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 completions 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  paren­
              theses,  in which any delimiter may be escaped with
              a backslash; 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
              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 comple­
              tion 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 his­
              tory is searched and if pattern is the empty string
              all  words  are taken (as with `*').  A typical use

                     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 com­
       pleted, but manipulate the options that do:

       -Q     This instructs the shell not to quote any metachar­
              acters  in  the possible completions.  Normally the
              results of a completion are inserted into the  com­
              mand  line  with  any metacharacters quoted so that
              they are interpreted as normal characters.  This is
              appropriate  for  filenames  and  ordinary strings.
              However, for special effects, such as  inserting  a
              backquoted  expression from a completion array (-k)
              so that the expression will not be evaluated  until
              the  complete line is executed, this option must be

       -P prefix
              The prefix is inserted just  before  the  completed
              string; any initial part already typed will be com­
              pleted and the whole prefix ignored for  completion
              purposes.  For example,

                     compctl -j -P "%" kill

              -/, -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 parenthe­
              sis. 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
              character;  this  the  same  rule  used   for   the
              AUTO_REMOVE_SLASH  option.  The option is most use­
              ful for list separators (comma, colon, etc.).

       -l cmd This option restricts the  range  of  command  line
              words that are considered to be arguments.  If com­
              bined 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 arguments to the cmd sup­
              plied with the option. If the cmd string  is  empty
              the first word in the range is instead taken as the
              command name, and command name completion performed
              on the first word in the range.  For example,

                     compctl -x 'r[-exec,;]' -l '' -- find

              completes arguments between `-exec' and the follow­
              ing `;' (or the end of the command line if there is
              no  such string) as if they were a separate command

       -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 completion code work on
              the parts of the current word that are separated by
              spaces.  These  parts are completed as if they were
              arguments to the given cmd. If  cmd  is  the  empty
              string,  the  first  part is completed as a command
              name, as with -l.

              The  list  provided  by  func-or-var  is  displayed
              instead of the list of completions whenever a list­
              ing  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 con­
              tains 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,  includ­
              ing  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 corre­
              spond, 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 particu­
              lar, 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 explanation  only
              appears  if  completion  was tried and there was no
              unique match, or when listing completions. Explana­
              tion  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
              when  compctl  would  normally stop when one of the
              alternatives generates matches.  It can  be  forced
              to  consider  the next set of completions 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-', compctl will continue
              trying  extended  completions  after  the next `-';
              with `-tx' it  will  attempt  completion  with  the
              default  flags,  in  other  words  those before the

       -J name
              This gives the name of the group the matches should
              be  placed  in.  Groups are listed and sorted sepa­
              rately; likewise, menu completion  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  encoun­
              tered,  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

       The  form  with `+' specifies alternative options. Comple­
       tion is tried with the options before the  first  `+'.  If
       this  produces  no  matches  completion  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.


       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 alterna­
       tive completion using `+'.  Each pattern  is  examined  in
       turn; when a match is found, the corresponding 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

       The elements may be any of the following:

              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

              Like s[string] except that the string  is  part  of
              the completion.

              Matches  if  the word in position index is equal to
              the corresponding string.  Note that the word count
              is made after any alias expansion.

              Like w but using pattern matching instead.

              Matches  if the current word contains string.  Any­
              thing up to and including the indexth occurrence of
              this string will not be considered part of the com­
              pletion, 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 hostnames, though you must make
              the  array yourself) will be completed.  Other com­
              mands such as rcp can be handled similarly.

              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 comple­

              Matches if the total number of words  lies  between
              min and max inclusive.

              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.

              Like r but using pattern matching instead.

              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 completion is
              done in backticks and str starts with a `b'.
              ~/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)


       zshmodules - zsh loadable modules


       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  dynami­
       cally  linked  while the shell is running if the installa­
       tion supports this feature.  The modules that are  bundled
       with the zsh distribution are:

              Builtins  for manipulating POSIX.1e (POSIX.6) capa­
              bility (privilege) sets.

              A builtin that  can  clone  a  running  shell  onto
              another terminal.

              The compctl builtin for controlling completion.

              The basic completion code.

              Completion listing extensions.

              A module with utility builtins needed for the shell
              function based completion system.

              A ZLE function duplicating EMACS' zap-to-char.

              An example of how to write a module.

              Some basic file manipulation commands as  builtins.

              A builtin that provides a timed execution  facility
              within the shell.

              Manipulation of Unix domain sockets

              A  builtin  command  interface  to  the stat system

              Interface to the termcap database.

              Interface to the terminfo database.

              A builtin FTP client.

              The Zsh Line  Editor,  including  the  bindkey  and
              vared builtins.

              Access  to  internals  of  the  Zsh Line Editor via

              A module allowing profiling for shell functions.

              A builtin for starting a command in a pseudo-termi­

              Block and return when file descriptors are ready.

              Some  utility builtins, e.g. the one for supporting
              configuration via styles.

              Manipulation of TCP sockets


       The zsh/cap  module  is  used  for  manipulating  POSIX.1e
       (POSIX.6)  capability  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:



       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 origi­
              nal shell.

              The  return  value  of  the builtin is zero in both
              shells if successful, and non-zero on error.


       The zsh/compctl module makes available  two  builtin  com­
       mands. compctl, is the old, deprecated way to control com­
       pletions for ZLE.  See zshcompctl(1).  The  other  builtin
       command,  compcall  can be used in user-defined completion
       widgets, see zshcompwid(1).


       The zsh/complete module makes  available  several  builtin
       commands which can be used in user-defined completion wid­
       gets, see zshcompwid(1).


       The zsh/complist module offers three extensions to comple­
       tion  listings: the ability to highlight matches in such a
       list, the ability to scroll through long lists and a  dif­
       ferent 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 automatically be loaded if
       it  is  not  linked  in:  on systems with dynamic loading,
       `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 follow­
       ing  strings,  most  of which specify file types for which
       the value will be used.  The  strings  and  their  default

       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 filenames 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
       (`*') followed 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  (`=')  fol­
       lowed by a pattern.  The value given for this pattern 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 prece­
       dence 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 parenthe­
       ses  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  paren­
       theses.       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.

       the  value for the file-type or the last matching specifi­
       cation 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

       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 visi­
       ble 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  zsh­
       contrib(1)).  For example, after loading colors, one could
       use `$colors[red]' to get the code  for  foreground  color
       red  and  `$colors[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 `Completion System
       Configuration' in zshcompsys(1)).

   Scrolling in completion listings
       To enable scrolling through a completion list,  the  LIST­
       PROMPT  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  `number/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 lower­
       case 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 spe­
       cial meaning while scrolling lists:


       As  for  the  ZLS_COLORS and ZLS_COLOURS parameters, LIST­
       PROMPT 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  MENUSELECT  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=...

       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 supports 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
       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 movement 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

              accepts the current match and leaves menu selection

              leaves  menu  selection  and  restores the previous
              contents of the command line

       redisplay, clear-screen
              execute their normal function without leaving  menu

       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

              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 immedi­
              ately 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 other­
              wise 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

       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

              moves  the  mark  to  the last line of the previous
              group of matches

              moves the mark to the first line

              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

              moves the mark to the previous match

              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-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
       using the bindkey builtin command (see zshmodules(1)). For
       example, to make the return key leave menu selection with­
       out accepting the match currently selected one could call

              bindkey -M menuselect '^M' send-break

       after loading the zsh/complist module.


       The zsh/computil module adds several builtin commands that
       are  used  by some of the completion functions in the com­
       pletion 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:

              This is used by the _arguments function to  do  the
              argument  and  command  line parsing.  Like compde­
              scribe 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.

              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 second 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  differ­
              ent  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.

              Used  by  the _path_files function to optimize com­
              nals 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 consecu­
              tive duplicates).

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

              These  implement  the  internals of the tags mecha­

              Like comparguments, but for the _values function.


       The zsh/deltochar module makes  available  two  ZLE  func­

              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

              This  behaves  like delete-to-char, except that the
              final occurrence of the  character  itself  is  not


       The  zsh/example  module  makes available one builtin com­
              lent  to  chown  with  a  user-spec   argument   of

       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
                     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  sepa­
              rator is `.', otherwise there is no separator.

              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 prece­
              dence, if there  is  an  all-numeric  username  (or
              group name).

              The  -R  option causes chown to recursively descend
              into directories, 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 function­
              ality.   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    accidentally    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

       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
              out 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  permis­
              sions  for  the created directories, otherwise mode
              777 modified by the current umask (see umask(2)) is

       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  specified
              directory  that  has  the same last pathname compo­

              By default, the user will be queried before replac­
              ing  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 replac­
              ing 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.   Historical  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

       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.   Typi­
              cally  only  the super-user can actually succeed in
              unlinking directories in this way.  -d takes prece­
              dence over -r.

              By  default, the user will be queried before remov­
              ing 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
              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 com­


       The zsh/mapfile module provides  one  special  associative
       array parameter of the same name.

              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

       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 represents a gain in effi­
       ciency over use of other mechanisms.  Note  in  particular
       shell parameter to be given the special behaviour.


       The  zsh/mathfunc  module  provides  standard mathematical
       functions for use when evaluating  mathematical  formulae.
       The  syntax  agrees with normal 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  functions  behave  as
       noted in the manual page for the corresponding C function,
       except that any arguments out of range for the function in
       question  will  be  detected  by  the  shell  and an error

       The following functions take a single floating point argu­
       ment:  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 func­
       tion 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­

       The following functions take two floating point arguments:
       copysign, fmod, hypot, nextafter.

       The  following take an integer first argument and a float­
       ing point second argument: jn, yn.

       The following take a floating point first argument and  an
       integer second argument: ldexp, scalb.

       The  function  abs does not convert the type of its single
       argument; it returns the absolute value of either a float­
       ing  point  number or an integer.  The functions float and
       int convert their arguments into a floating point or inte­
       ger value (by truncation) respectively.
       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 hexadec­
       imal  digits,  with  no base signifier.  The random number
       sequences for different parameters are completely indepen­
       dent,  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, however, 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  gives  access  to  some of the
       internal hash tables used by the shell  by  defining  some
       special parameters.

              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  set­
              ting  or unsetting the option, respectively. Unset­
              ting a key in this array is like setting it to  the
              value off.

              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]"'

              This associative array gives information about  the
              builtin  commands  currently  enabled. The keys are
              the names of the builtin commands  and  the  values
              are  either  `undefined'  for builtin commands that
              will automatically  be  loaded  from  a  module  if
              invoked  or `defined' for builtin commands that are
              already loaded.

              Like builtins but for disabled builtin commands.

              This array contains the enabled reserved words.

              Like reswords but for disabled reserved words.

              This maps the names of  the  regular  aliases  cur­
              rently enabled to their expansions.

              Like raliases but for disabled regular aliases.

              Like raliases, but for global aliases.

              Like galiases but for disabled global aliases.

              The keys in this associative array are the names of
              the parameters currently defined.  The  values  are
              strings  describing  the  type of the parameter, in
              the same format used by the t parameter  flag,  see
              zshexpn(1)  .   Setting  or  unsetting keys in this
              array is not possible.

              An associative array giving information about  mod­
              ules. 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 pos­

              This associative array  maps  job  numbers  to  the
              directories  from  which the job was started (which
              may not be the current directory of the job).

              This associative array  maps  job  numbers  to  the
              texts  of the command lines that were used to start
              the jobs.

              This associative array gives information about  the
              states  of  the  jobs currently known. The keys are
              the job numbers and the values 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 current 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.

              This associative array  maps  the  names  of  named
              directories to the pathnames they stand for.

              This associative array maps user names to the path­
              names of their home directories.

              This array contains the names of the functions cur­
              rently  being  executed.  The  first element is the
              name of the function using the parameter.


       The zsh/pcre  module  makes  some  commands  available  as

       pcre_compile [ -aimx ] PCRE
              Compiles a perl-compatible regular expression.

              Studies  the  previously-compiled  PCRE  which  may
              result in faster matching.

       pcre_match [ -a arr ] string
              Returns successfully if string matches  the  previ­
              ously-compiled PCRE.

              If the expression captures substrings within paren­
              theses, pcre_match will set  the  array  $match  to


       The zsh/net/socket module makes available one builtin com­

       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 parameter REPLY  will  be  set  to  the  file
              descriptor  associated  with that connection.  Cur­
              rently, only stream connections are supported.

              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 file­
              name.  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  connection is pending.  Otherwise it will
              wait for one.

              In order to elicit more verbose output, use -v.


       The zsh/stat module makes available one builtin command:

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

              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.

              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.

                     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

              A  particular  element may be selected by including
              its name preceded by a `+' in the option list; only
              one  element is allowed.  The element may be short­
              ened to any unique set of leading characters.  Oth­
              erwise, all elements will be shown for all files.
                     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  formatting  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 element useful.

              -n     Always  show  the  names  of files.  Usually
                     these are only shown when output is to stan­
                     dard  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 con­
                     sumption 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) along­
                     side string data (the -s format); the string
                     data  appears  in  parentheses after the raw


       The  zsh/termcap  module  makes available one builtin com­

       echotc cap [ arg ... ]
              Output the termcap value corresponding to the capa­
              bility cap, with optional arguments.

       The zsh/termcap module makes available one parameter:

              An  associative  array that maps termcap capability
              codes to their values.


       The zsh/terminfo module makes available one  builtin  com­

       echoti cap [ arg ]
              Output  the  terminfo  value  corresponding  to the
              capability cap, instantiated with arg  if  applica­

       The zsh/terminfo module makes available one parameter:

              An  associative array that maps terminfo capability
              names to their values.


       The zsh/zftp module makes available one builtin command:

       zftp subcommand [ args ]
              The zsh/zftp module  is  a  client  for  FTP  (file
              transfer protocol).  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  fol­
              lowed  by  the  name  of  a  subcommand.  These are
              listed below.  The return status of each subcommand
              is  supposed  to  reflect the success or failure of
              the remote operation.  See  a  description  of  the
              variable  ZFTP_VERBOSE  for more information on how
              responses from the server may be printed.

       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

              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  remembered.   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  necessary  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 literally,  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.
              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 systems.

       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 arguments
              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 sim­
              ilar 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.
              item on the list, the name of the file  is  printed
              first.  The first number is the file size, the sec­
              ond is the last modification time of  the  file  in
              the   format  CCYYMMDDhhmmSS  consisting  of  year,
              month, date, hour,  minutes  and  seconds  in  GMT.
              Note  that  this  format,  including the length, is
              guaranteed, so that time strings  can  be  directly
              compared  via  the  [[ builtin's < and > operators,
              even if they are too  long  to  be  represented  as

              Not all servers support the commands for retrieving
              this information.  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  arguments,  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

       get file [...]
              Retrieve all files from the  server,  concatenating
              them and sending 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 appending to an incomplete local
              file.  However, note that this ability is not  uni­
              versally 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.
              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.

       quit   Close the current data connection.  This unsets the
              shell parameters ZFTP_HOST,  ZFTP_IP,  ZFTP_SYSTEM,

       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 connec­
              tion, the set of connection-specific shell  parame­
              ters  (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 sub­
              command.  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  cur­
              rent session is deleted.  If the current session is
              deleted, the earliest existing session becomes  the
              new  current session, otherwise the current 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 com­
              mands which use zftp are still active.

       The following shell parameters are  used  by  zftp.   Cur­
       rently none of them are special.

              Integer.  The time in seconds to wait for a network
              ZFTP_HOST contains that  instead;  this  saves  the
              overhead  for a name lookup, as IP numbers are most
              commonly used when a nameserver is unavailable.

              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 compatibility with
              a local UNIX host.

              Readonly.  The type to be used for data transfers ,
              either  `A'  or  `I'.    Use the type subcommand to
              change this.

              Readonly.  The username  currently  logged  in,  if

              Readonly.  The account name of the current user, if
              any.  Most servers do not require an account  name.

              Readonly.  The current directory on the server.

              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.

              Readonly.  The last line of the last reply sent  by
              the  server.  This can still be read after the con­
              nection is closed, and is not changed when the cur­
              rent session changes.

              Readonly.  The name of the current FTP session; see
              the description of the session subcommand.

              A string of preferences  for  altering  aspects  of
              zftp's  behaviour.   Each  preference  is  a single
              character.  The following 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
                     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

              A string of digits between 0 and 5 inclusive, spec­
              ifying 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 begin­
              ning with that digit will be  printed  to  standard
              error.   The  first  digit of the three digit reply
              code is defined by RFC959 to correspond 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 termi­
              nation 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  pro­
              cessed  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., mes­
              sages destined for the user and all errors will  be
              printed.  A null string is valid and specifies that
              no messages should be printed.

              If this function is set by the user, it  is  called
              every  time  the  directory  changes on the server,
              When  it is called with a transfer in progress, the
              following additional shell parameters are set:

                     The name of the  remote  file  being  trans­
                     ferred from or to.

                     A  G  for  a get operation and a P for a put

                     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.

                     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  appropriately  and  ZFTP_COUNT  set  to  zero.
              After  the  transfer is finished, 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 oth­
              erwise never called twice with the  same  value  of

              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 neces­

       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 connection in a subshell, the
       information is returned  but  variables  are  not  updated
       until the next call to zftp.  Other status changes in sub­
       shells will not be reflected by changes to  the  variables
       (but should be otherwise harmless).

       Deleting  sessions  while  a zftp command is active in the
       background can have unexpected effects, even  if  it  does


       The zsh/zleparameter module defines two special parameters
       that can be used to access internal information of the Zsh
       Line Editor (see zshzle(1)).

              This  array  contains the names of the keymaps cur­
              rently defined.

              This associative array contains one entry per  wid­
              get  defined. The name of the widget is the key and
              the value gives information 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
              function implementing the completion widget.


       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 compara­
              ble 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 function 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 information, but  counting  only  the
              time  spent in the function itself.  The final col­
              umn shows the name of the function.
              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  run­
              ning  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  invocations  made  to the called

              As long as the zsh/zprof module is loaded,  profil­
              ing  will  be  done and multiple invocations of the
              zprof builtin command will show the times and  num­
              bers  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 list­
              ing.  )


       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-terminal; 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  com­
              mand 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 pro­
              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  out­
              put  read is copied to the standard output.  Unless
              the pseudo-terminal is non-blocking,  copying  con­
              tinues  until the command under the pseudo-terminal
              exits; when non-blocking, only as much output as is
              immediately  available is copied.  The return value
              is zero if any output 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

              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 com­
              mand  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  pat­
              tern, the return value is non-zero.

              In all cases, the return value is non-zero if noth­
              ing 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  try­
              ing to read.  If no output is available, zpty imme­
              diately 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 commands currently  defined.   If  the  -L
              option  is given, this is done in the form of calls
              to the zpty builtin.


              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. zse­
              lect 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 reading,  writing,
              or  error  conditions.   These options and an arbi­
              trary list of file descriptors may be given in  any

              (The  presence  of an `error condition' is not well
              defined in the documentation for  many  implementa­
              tions  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 hun­
              dredths  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 timeout.

              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 con­
              tain 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 associa­
              tive array assoc should be set to indicate the file
              descriptor(s)  which  are ready.  This option over­
              rides 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

       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 patterns and lookup
              is done by giving a string, called  the  `context',
              which  is compared to the patterns.  The definition
              stored for  the  first  matching  pattern  will  be

              For  ordering of comparisons, patterns are searched
              from most specific to least specific, and  patterns
              that  are  equally specific keep the order in which
              they were defined.  A pattern is considered  to  be
              more specific than another if it contains more com­
              ponents (substrings separated by colons) or if  the
              patterns  for  the  components  are  more specific,
              where simple strings are considered to be more spe­
              cific  than  patterns and complex patterns are con­
              sidered to be more specific than the pattern `*'.

              The first form (without arguments) lists the  defi­
              nitions  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 evaluation.
                     Before evaluating the value, reply is unset,
                     and  if  it is still unset after the evalua­
                     tion, the style is treated as if it were not

              zstyle -d [ pattern [ styles ... ] ]
                     Delete  style definitions. Without arguments
                     all definitions 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 -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 con­
                     catenated  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

              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 for­
              matting. The first form is  selected  with  the  -f
              option. In this case the format string will be mod­
              ified by replacing sequences starting with  a  per­
              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

              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

              This  implements some internals of the _regex_argu­
              ments function.

       zparseopts [ -D ] [ -K ] [ -E ] [ -a array ] [ -A assoc  ]
              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 parame­
              ters 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

              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+  The  name  is the name of the option without
                     next  positional  parameter  does  not  also
                     begin  with  `-'  (unless  the  -E option is

              name:: If one or two colons are given,  the  option
                     takes an argument; with one colon, the argu­
                     ment 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 indis­
                     tinguishable).    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 arguments  (if  any)  as  the

       -D     If  this  option  is  given,  all options found are
              removed from the positional parameters of the call­
              ing  shell or shell function, up to but not includ­
              ing any not described by the specs.  This is  simi­
              lar 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  argu­
              ments,  ignoring  all  other  options and arguments

       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.


       The  zsh/net/tcp  module  makes available one builtin com­

       ztcp [ -acflLtv ] [ -d fd ] [ args ]
              ztcp is implemented as a builtin to allow full  use
              of  shell  command  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 out­
              put the contents 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 ele­
              ments separated by spaces:

              File descriptor
                     The  file  descriptor in use for the connec­
                     tion.  For normal 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 cre­

                      Z      A session created with the zftp com­

                      L      A  connection  opened  for listening
                             with `ztcp -l'.

                      I      An inbound connection accepted  with
                             `ztcp -a'.

              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

   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  connec­
              tion  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 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.

       ztcp -a [ -tv ] [ -d targetfd ] listenfd
              ztcp -a will accept an incoming connection  to  the
              port associated with listenfd.  The connection will
              be added to the session table and the shell parame­
              ter  REPLY will be set to the file descriptor asso­
              ciated 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

              In order to elicit more verbose output, use -v.
              In order to elicit more verbose output, use -v.

       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
              ztcp -a $listenfd
       The second from last command  blocks  until  there  is  an
       incoming connection.

       Now  create a connection from host2 (which may, of course,
       be the same machine):
              zmodload zsh/net/tcp
              ztcp host1 5123

       Now on each host, $fd contains a file descriptor for talk­
       ing 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
ZSHTCPSYS(1)                                         ZSHTCPSYS(1)


       zshtcpsys - zsh tcp system


       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.  The functions will usually  be
       installed  at  the same time as the module if that is pre­
       sent on your system, 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 operations.  For
       enough to `autoload -U tcp_open' and run tcp_open as docu­
       mented  below  to  start a session.  The tcp_open function
       will autoload the remaining 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

              If sess is given, this becomes the name of the ses­
              sion which can be used to refer to multiple differ­
              ent  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 under­
              scores, 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 nec­
              essary.  The host and port are read from  the  file
              .ztcp_sessions  in the same directory as the user's
              zsh initialisation files,  i.e.  usually  the  home
              directory,  but  $ZDOTDIR if that is set.  The file
              consists of lines each giving a  session  name  and
              the  corresponding  host  and  port,  in that order
              (note the session name comes first, not last), sep­
              arated by whitespace.

              The  third form allows passive and fake TCP connec­
              tions.  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 connection 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
              sages,  although  it  will in any case exit with an
              appropriate status.

              If the line editor (zle) is in use, which  it  usu­
              ally  is  if  and only 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 systems.  However, if
              incoming  data  is  only to be read explicitly, the
              option -z to any of the forms of tcp_open  prevents
              the  handler  from  being installed.   Note 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 han­
              dler  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;  subsequent  calls  to  tcp_open  will not
              change this.  The current session 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  consis­
              tency  with tcp_open, although the latter is redun­

              If the session being closed  is  the  current  one,
              $TCP_SESS  is  unset,  leaving  no current session,
              even if there are other sessions 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

              If  the  option  -q is given, no informational mes­
              sages will be printed.

       tcp_read [-bdq] [ -t TO ] [ -T TO ]
           [ -a | -u fd ... | -l sess,... | -s sess ...]
              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 stan­
              dard 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 time­
              out, the function will block until a line is avail­
              able 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  pro­
              cess 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; with­
              out 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-existent 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 prevent the
              shell from dying owing to a SIGPIPE  caused  by  an
              attempt to write to a defunct session.

   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

              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 trun­
              cated  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 log­
              file.sess.  As the session  is  automatically  dis­
              criminated  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

              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.
              rent  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
              current settings.  Status 0 is always returned.

              This is generally only useful for interactive  use,
              to  prevent the display becoming fragmented by out­
              put returned from the connection.   Within  a  pro­
              gramme 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

              Sessions are specified in the same way as tcp_read:
              the default is to use the current  session,  other­
              wise  the  sessions  specified by -a, -s, or -l are

              Each pattern is a  standard  zsh  extended-globbing
              pattern;  note  that it needs to be quoted to avoid
              it being expanded immediately by  filename  genera­
              tion.   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 documen­
              tation on pattern matching.

              Unlike   tcp_read,   the   default   behaviour   of
              tcp_expect  is  to  block  indefinitely  until  the
              ter 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 excep­
              tion  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.

              This is a simple-minded function to  accept  a  TCP
              connection  and  execute  a  command with I/O redi­
              rected to the connection.  Extreme  caution  should
              be  taken  as  there  is no security whatsoever and
              this can leave your computer  open  to  the  world.
              Ideally,  it should only be used behind a firewall.

              The first argument is a TCP port on which the func­
              tion will listen.

              The  remaining  arguments  give  a  command and its
              arguments to execute 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 [-rtv] [ -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, oth­
              erwise all sessions are taken.   Second,  any  ses­
              sions  given  in  the  array  $tcp_no_spam_list are
              removed from the list of sessions.

              Normally, any sessions added by the  `-a'  flag  or
              when all sessions are chosen implicitly are spammed
              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  fol­
              lowed  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 editor's operating mode.

              The current implementation is somewhat deficient in
              terms of use of the command history.  For this rea­
              son,  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_com­
              mand --'.

              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.


       Certain functions, if defined by the user, will be  called
       by the function 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  by  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 ses­

       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.

              lowed 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 function.  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 addi­
              tion, no prompt is printed for  the  -v  option  to

       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.


       The  following functions are used by the TCP function sys­
       tem but will rarely if ever need to be called directly.

              This is the function installed by tcp_open for han­
              dling input from within the line editor, if that is
              required.  It is in the format documented  for  the
              builtin `zle -F' in zshzle(1) .

       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 `%s' which  is
              replaced  by  the  session  name,  or `%f' which is
              replaced by the session's file descriptor; `%%'  is
              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  ses­
              sion name and file descriptor for possible replace­
              ment in the prompt.

       side the function.  Likewise, `local TCP_SESS=sess' sets a
       session for the duration of a function.

              Array.  The set of lines read during the last  call
              to tcp_expect, including the last ($TCP_LINE).

              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.

              The last line read  by  tcp_read,  and  hence  also

              The  file descriptor from which $TCP_LINE was read.
              ${tcp_by_fd[$TCP_LINE_FD]}  will  give  the  corre­
              sponding session name.

              Array.  The  set of lines read during the last call
              to tcp_read, including the last ($TCP_LINE).

              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 pro­
              ceeded  by  the usual $TCP_PROMPT.  If it is not an
              absolute path name, it will follow the user's  cur­
              rent directory.

              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.

              Array.   May be set directly.  See tcp_spam for how
              this is used.

              May be set directly.  If a  non-empty  string,  any
              data  sent to a session by tcp_send will be logged.

              May  be set directly.  If this has non-zero length,
              tcp_read will give some limited  diagnostics  about
              data being read.

              May  be  set  directly.   The current session; must
              refer  to  one  of  the  sessions  established   by

              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.

              Array.  May be set directly.  See  the  description
              of the function tcp_spam for how this is used.

              May  be  set  directly.  See the description of the
              function tcp_talk for how this is used.

              May be set directly.  Currently this is  only  used
              by the function tcp_command, see above.


       These  parameters  are  controlled by the function system;
       they may be read directly, but should not usually  be  set
       by user code.

              Associative  array.  The keys are the names of ses­
              sions established with tcp_open; each  value  is  a
              space-separated list of aliases which refer to that

              Associative  array.   The  keys  are  session  file
              descriptors;  each  value  is the name of that ses­

              Associative array.  The keys are the names of  ses­
              sions; each value is the file descriptor associated
              with that session.


       while for output (assuming dc is the current session):

              tcp_command 2 4 + p

       To close the session:


       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

              print -n "\033]2;TCP:" ${(k)tcp_by_name:/$TCP_SESS/$TCP_SESS\*} "\a"


       The   function  tcp_read  uses  the  shell's  normal  read
       builtin.  As this reads a  complete  line  at  once,  data
       arriving without a terminating newline can cause the func­
       tion 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 are being exchanged  is  likely
ZSHZFTPSYS(1)                                       ZSHZFTPSYS(1)

       to be extremely poor.


       zshzftpsys - zftp function front-end


       This  describes  the  set of shell functions supplied with
       the source  distribution  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 com­
       pletion, 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
       zshmodules(1)  ,  must  be available in the version of zsh


       You  should  make  sure  all  the functions from the Func­
       tions/Zftp directory of the source distribution are avail­
       able;  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 fol­
       lowing  code  in your .zshrc will arrange for this; assume
       the functions are stored in the directory ~/myfns:

              fpath=(~/myfns $fpath)
              autoload -U 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  unnec­
       essary compctl commands will be given.


       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  argu­

   Opening a connection
       zfparams [ host [ user [ password ... ] ] ]
              Set or show the parameters for a future zfopen with
              no arguments.  If no arguments are given, the  cur­
              rent 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.

              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:directory;  this
              is  handled  by  the function zftp_chpwd, described

              Normally, the host, user and  password  are  inter­
              nally  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)  under­
              stand  URLs of the form ftp://host/path... as mean­
              ing 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 parame­
              ter $EMAIL_ADDR which can alternatively be set man­
              ually 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
              path  such  as `zfcd /home/user2/pws/foo'.  At this
              stage, zfcd recognises the initial path  as  corre­
              sponding  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 implementation depen­
              dent, but specifying a particular remote  directory
              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  directory
              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  argu­
              ments,  this  will  produce  a  simple list of file
              names for the current remote directory.  Any  argu­
              ments  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,  usually  ASCII  or  binary.   With an

       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 modifi­
              cation 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

       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 par­
              tially completed transfer and attempts to  transfer
              the  rest  of  the  file.  This is useful on a poor
              connection which keeps failing.

              Note that this requires a commonly implemented, but
              non-standard,  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
              subdirectories, including files beginning with `.'.
              This requires that the  remote  machine  understand
              UNIX  file semantics, since `/' is used as a direc­
              tory separator.

       zfuput [ -vs ] file1 ...
              As zfput, but only send files which are newer  than
              their local equivalents, or if the remote file does
              not exist.  The logic is the same  as  for  zfuget,
              but reversed between local and remote files.

       zfcput file1 ...
              As zfput, but if any remote file already exists and
              is shorter than the local equivalent, assume it  is
              the  result  of an incomplete transfer and send the
              rest of the file to append to  the  existing  part.
              As  the  FTP append command is part of the standard
              set, this is in principle more likely to work  than

       zfpcp local-file remote-file
       zfpcp lfile1 ... rdir
              This  sends  files  to the remote server with argu­
              ments behaving similarly to the cp command.

              With two arguments, copy local-file to  the  server
              as remote-file.

              With  more  than  two arguments, copy all the local
              files lfile1 ... into the existing remote directory
              rdir  retaining  the  same basenames.  This assumes
              UNIX directory semantics.

              A problem arises if you attempt to use zfpcp lfile1
              rdir,  i.e. the second form of copying but with two
              arguments, as the command  has  no  simple  way  of
              knowing  if  rdir  corresponds  to a directory or a
              filename.  It attempts to resolve this  in  various
              ways.   First,  if the rdir argument is `.' or `..'
              or ends in a slash, it is assumed to  be  a  direc­
              tory.   Secondly,  if the operation of copying to a
              remote file in  the  first  form  failed,  and  the
              remote  server sends back the expected failure code
              553 and a reply including the string `Is  a  direc­
              tory', then zfpcp will retry using the second form.

   Closing the connection
              Close the connection.

              With no arguments, zfsession prints the name of the
              current  session;  with  the option -l it lists all
              sessions which currently exist, and with the option
              -v  it  gives  a  verbose list showing the host and
              directory for each session, where the current  ses­
              sion  is marked with an asterisk.  With -o, it will
              switch to the most recent previous session.

              With -d, the given session  (or  else  the  current
              one)  is  removed; everything to do with it is com­
              pletely forgotten.  If it was the only  session,  a
              new  session  called  `default' is created and made
              current.  It is safest not to delete sessions while
              background commands using zftp are active.

       zftransfer sess1:file1 sess2:file2
              Transfer  files between two sessions; no local copy
              is made.  The file is read from the  session  sess1
              as  file1  and  written  to  session  sess2 as file
              file2; file1 and file2 may be relative to the  cur­
              rent  directories  of the session.  Either sess1 or
              sess2 may be omitted (though the  colon  should  be
              retained  if  there  is  a  possibility  of a colon
              appearing in the file name)  and  defaults  to  the
              current  session;  file2  may be omitted or may end
              with a slash, in which case the basename  of  file1
              will  be  added.  The sessions sess1 and sess2 must
              be distinct.

              The operation is performed using pipes,  so  it  is
              required  that  the connections still be valid in a
              subshell, which is not the case under  versions  of
              some  operating systems, presumably due to a system

       The two functions zfmark and zfgoto allow  you  to  `book­
       mark'  the  present location (host, user and directory) of
       the current FTP connection for later use.  The file to  be
       used  for storing and retrieving bookmarks is given by the
       parameter $ZFTP_BMFILE; if not set when  one  of  the  two
       functions is called, it will be set to the file .zfbkmarks
       in the directory where your zsh startup files  live  (usu­
       ally ~).

       zfmark [ bookmark ]
              If  given  an argument, mark the current host, user
              and directory under the name bookmark for later use
              by zfgoto.  If there is no connection open, use the
              values for the last connection  immediately  before
              it  was  closed;  it is an error if there was none.
              user and host parameters match those stored for the
              current session, if any, those will  be  used,  and
              again  no  password is required.  Otherwise a pass­
              word will be prompted for.

              With the option -n, the bookmark is taken to  be  a
              nickname  stored  by the ncftp program in its book­
              mark file, which is assumed  to  be  ~/.ncftp/book­
              marks.   The  function  works  identically in other
              ways.  Note that there is no mechanism  for  adding
              or  modifying  ncftp  bookmarks from the zftp func­

   Other functions
       Mostly, these functions will not be called directly (apart
       from  zfinit),  but  are  described here for completeness.
       You may wish to alter  zftp_chpwd  and  zftp_progress,  in

       zfinit [ -n ]
              As  described above, this is used to initialize the
              zftp function system.  The -n option should be used
              if  the  zftp  command  is  already  built into the

       zfautocheck [ -dn ]
              This function  is  called  to  implement  automatic
              reopening  behaviour,  as  described in more detail
              below.  The options must appear in the first  argu­
              ment;  -n prevents the command from changing to the
              old directory, while -d prevents  it  from  setting
              the variable do_close, which it otherwise does as a
              flag for automatically closing the connection after
              a  transfer.   The  host and directory for the last
              session are stored in the variable  $zflastsession,
              but the internal host/user/password parameters must
              also be correctly set.

       zfcd_match prefix suffix
              This performs matching  for  completion  of  remote
              directory  names.  If the remote server is UNIX, it
              will attempt to persuade the  server  to  list  the
              remote  directory with subdirectories marked, which
              usually works but  is  not  guaranteed.   On  other
              hosts  it  simply  calls zfget_match and hence com­
              pletes all files, not just  directories.   On  some
              systems,  directories  may not even look like file­

       zfget_match prefix suffix
              This performs matching  for  completion  of  remote

       zfrtime lfile rfile [ time ]
              Set the local file lfile to have the same modifica­
              tion time as the remote file rfile, or the explicit
              time time in FTP format CCYYMMDDhhmmSS for the  GMT

              Currently  this  requires perl version 5 to perform
              the conversion from GMT to  local  time.   This  is
              unfortunately  difficult  to  do  using  shell code

              This function is called every time a connection  is
              opened, or closed, or the remote directory changes.
              This version alters the title bar of an  xterm-com­
              patible or sun-cmd terminal emulator to reflect the
              local and remote hostnames and current directories.
              It  works  best  when  combined  with  the function
              chpwd.  In particular, a function of the form

                     chpwd() {
                       if [[ -n $ZFTP_USER ]]; then
                         # usual chpwd e.g put host:directory in title bar

              fits in well.

              This function shows the status of the transfer.  It
              will  not write anything unless the output is going
              to a terminal; however, if you  transfer  files  in
              the   background,  you  should  turn  off  progress
              reports by hand using  `zstyle  ':zftp:*'  progress
              none'.   Note also that if you alter it, any output
              must be to standard error, as standard  output  may
              be a file being received.  The form of the progress
              meter, or whether it is used at all, can be config­
              ured without altering the function, as described in
              the next section.

              This is used to implement caching of files  in  the
              current  directory for each session separately.  It
              is used by zfget_match and zfrglob.


       Various styles are  available  using  the  standard  shell
       name,  as  called  by  the user, is used; calling of lower
       level functions is transparent to the user.  Hence modifi­
       cations  to  the  title bar in zftp_chpwd use the contexts
       :zftp:zfopen, :zftp:zfcd, etc.,  depending  where  it  was
       called from.  The following styles are understood:

              Controls  the way that zftp_progress reports on the
              progress  of  a  transfer.   If  empty,  unset,  or
              `none',  no  progress  report  is  made; if `bar' a
              growing bar of inverse video is shown; if `percent'
              (or  any  other  string,  though this may change in
              future), the percentage of the file transferred  is
              shown.   The  bar  meter requires that the width of
              the terminal be available via the $COLUMNS  parame­
              ter  (normally  this is set automatically).  If the
              size of the file being transferred  is  not  avail­
              able,  bar  and percent meters will simply show the
              number of bytes transferred so far.

              When zfinit is run, if this style  is  not  defined
              for the context :zftp:*, it will be set to `bar'.

       update Specifies the minimum time interval between updates
              of the progress meter in  seconds.   No  update  is
              made  unless  new  data  has  been received, so the
              actual time interval is limited only by $ZFTP_TIME­

              As  described  for progress, zfinit will force this
              to default to 1.

              If set to `1', `yes' or `true', filename generation
              (globbing)  is  performed  on  the  remote  machine
              instead of by zsh itself; see below.

              If set to `1', `yes' or `true', zftp_chpwd will put
              the  remote  host  and  remote  directory  into the
              titlebar of terminal emulators  such  as  xterm  or
              sun-cmd that allow this.

              As  described  for progress, zfinit will force this
              to default to 1.

       chpwd  If set to `1' `yes' or `true', zftp_chpwd will call
              the  function  chpwd  when  a connection is closed.
              This is useful if the remote host details were  put
              into  the terminal title bar by zftp_chpwd and your
              usual chpwd also modifies the title bar.

       list of files for the directory in question, then matching
       these  locally against the pattern supplied.  This has the
       advantage that the full range of zsh patterns  (respecting
       the  setting  of  the  option  EXTENDED_GLOB) can be used.
       However, it means that the directory part  of  a  filename
       will  not  be  expanded and must be given exactly.  If the
       remote server does not support the UNIX  directory  seman­
       tics,  directory  handling is problematic and it is recom­
       mended that globbing  only  be  used  within  the  current
       directory.  The list of files in the current directory, if
       retrieved, will be cached, so that subsequent globs in the
       same  directory  without  an  intervening  zfcd  are  much

       If the remote-glob style (see above) is set,  globbing  is
       instead  performed on the remote host: the server is asked
       for a list of matching files.  This is highly dependent on
       how  the  server  is  implemented,  though  typically UNIX
       servers will provide  support  for  basic  glob  patterns.
       This  may in some cases be faster, as it avoids retrieving
       the entire list of directory contents.

   Automatic and temporary reopening
       As described for the zfopen command, a  subsequent  zfopen
       with  no parameters will reopen the connection to the last
       host (this includes connections made with the zfanon  com­
       mand).   Opened  in this fashion, the connection starts in
       the default remote directory and will  remain  open  until
       explicitly closed.

       Automatic  re-opening  is also available.  If a connection
       is not currently open and a command requiring a connection
       is  given, the last connection is implicitly reopened.  In
       this case the directory which was current when the connec­
       tion  was  closed  again  becomes  the  current  directory
       (unless, of course, the command given changes it).   Auto­
       matic reopening will also take place if the connection was
       close by the remote server for  whatever  reason  (e.g.  a
       timeout).   It is not available if the -1 option to zfopen
       or zfanon was used.

       Furthermore, if the command issued is a file transfer, the
       connection  will be closed after the transfer is finished,
       hence providing a one-shot mode for transfers.  This  does
       not  apply  to directory changing or listing commands; for
       example a zfdir may reopen a connection but will leave  it
       open.   Also,  automatic  closure will only ever happen in
       the  same  command  as  automatic  opening,  i.e  a  zfdir
       directly  followed by a zfget will never close the connec­
       tion automatically.

       return to a previous session, the connection for that ses­
       sion is the one which will be reopened.

       Completion  of  local  and remote files, directories, ses­
       sions  and  bookmarks  is  supported.   The  older,   com­
       pctl-style  completion  is  defined when zfinit is called;
       support for the new widget-based completion system is pro­
       vided  in the function Completion/Zsh/Command/_zftp, which
       should be installed with the other functions of  the  com­
       pletion  system  and  hence should automatically be avail­
ZSHCONTRIB(1)                                       ZSHCONTRIB(1)



       zshcontrib - user contributions to zsh


       The Zsh source distribution includes  a  number  of  items
       contributed  by  the user community.  These are not inher­
       ently a part of the shell, and some may not  be  available
       in  every zsh installation.  The most significant of these
       are documented here.   For  documentation  on  other  con­
       tributed  items such as shell functions, look for comments
       in the function source files.


   Accessing On-Line Help
       The key sequence ESC h is normally bound by ZLE to execute
       the  run-help  widget  (see  zshzle(1)).  This invokes the
       run-help command with the command word  from  the  current
       input  line  as  its argument.  By default, run-help is an
       alias for the man command, so this often  fails  when  the
       command  word  is  a shell builtin or a user-defined func­
       tion.  By redefining the run-help alias, one  can  improve
       the on-line help provided by the shell.

       The  helpfiles utility, found in the Util directory of the
       distribution, is a Perl program that can be used  to  pro­
       cess  the  zsh  manual to produce a separate help file for
       each shell builtin and for many other  shell  features  as
       well.   The autoloadable run-help function, found in Func­
       tions/Misc, searches for these helpfiles and performs sev­
       eral  other tests to produce the most complete help possi­
       ble for the command.

              perl ~/zsh-4.1.1/Util/helpfiles

       Next,  to use the run-help function, you need to add lines
       something like the following to your .zshrc or  equivalent
       startup file:

              unalias run-help
              autoload run-help

       The HELPDIR parameter tells run-help where to look for the
       help files.  If your system already has a help file direc­
       tory  installed, set HELPDIR to the path of that directory

       Note that in order for `autoload run-help'  to  work,  the
       run-help  file  must be in one of the directories named in
       your fpath array (see zshparam(1)).  This  should  already
       be the case if you have a standard zsh installation; if it
       is not, copy  Functions/Misc/run-help  to  an  appropriate

   Recompiling Functions
       If you frequently edit your zsh functions, or periodically
       update your zsh installation to track the latest  develop­
       ments,  you  may  find that function digests compiled with
       the zcompile builtin  are  frequently  out  of  date  with
       respect to the function source files.  This is not usually
       a problem, because zsh always looks for  the  newest  file
       when  loading  a  function,  but it may cause slower shell
       startup and function loading.  Also, if a digest  file  is
       explicitly  used  as  an element of fpath, zsh won't check
       whether any of its source files has changed.

       The  zrecompile  autoloadable  function,  found  in  Func­
       tions/Misc,  can  be  used  to keep function digests up to

       zrecompile [ -qt ] [ name ... ]
       zrecompile [ -qt ] -p args [ -- args ... ]
              This tries to find *.zwc  files  and  automatically
              re-compile  them  if  at  least one of the original
              files is newer than the compiled file.  This  works
              only  if the names stored in the compiled files are
              full paths or are relative to  the  directory  that
              contains the .zwc file.

              In  the first form, each name is the name of a com­
              piled file or a directory  containing  *.zwc  files
              that should be checked.  If no arguments are given,
              the directories and *.zwc files in fpath are  used.
              arated by `--'.  For example:

                     zrecompile -p \
                                -R ~/.zshrc -- \
                                -M ~/.zcompdump -- \
                                ~/zsh/comp.zwc ~/zsh/Completion/*/_*

              This compiles ~/.zshrc into  ~/.zshrc.zwc  if  that
              doesn't  exist or if it is older than ~/.zshrc. The
              compiled file will be marked for reading instead of
              mapping.  The  same  is  done  for ~/.zcompdump and
              ~/.zcompdump.zwc, but this compiled file is  marked
              for  mapping.  The  last  line  re-creates the file
              ~/zsh/comp.zwc if any of  the  files  matching  the
              given pattern is newer than it.

              Without  the  -p option, zrecompile does not create
              function digests that do  not  already  exist,  nor
              does it add new functions to the digest.

       The  following  shell  loop  is an example of a method for
       creating function digests for all functions in your fpath,
       assuming  that  you  have write permission to the directo­

              for ((i=1; i <= $#fpath; ++i)); do
                if [[ $dir == (.|..) || $dir == (.|..)/* ]]; then
                if [[ -w $dir:h && -n $files ]]; then
                  if ( cd $dir:h &&
                       zrecompile -p -U -z $zwc $files ); then

       The -U and -z options are appropriate for functions in the
       default  zsh  installation fpath; you may need to use dif­
       ferent options for your personal function directories.

       Once the digests have been created and your fpath modified
       to  refer to them, you can keep them up to date by running
       zrecompile with no arguments.

   Keyboard Definition
       The large number of possible  combinations  of  keyboards,
       keys  to  determine  characteristics  of your keyboard and
       terminal; zkbd warns you if it finds anything out  of  the
       ordinary,  such  as a Delete key that sends neither ^H nor

       The keystrokes read by zkbd are recorded as  a  definition
       for  an  associative array named key, written to a file in
       the subdirectory .zkbd within either your HOME or  ZDOTDIR
       directory.   The  name  of  the  file is composed from the
       TERM, VENDOR and OSTYPE parameters, joined by hyphens.

       You may read this file into your .zshrc or another startup
       file with the "source" or "." commands, then reference the
       key parameter in bindkey commands, like this:

              source ${ZDOTDIR:-$HOME}/.zkbd/$TERM-$VENDOR-$OSTYPE
              [[ -n ${key[Left]} ]] && bindkey "${key[Left]}" backward-char
              [[ -n ${key[Right]} ]] && bindkey "${key[Right]}" forward-char
              # etc.

       Note that in order for `autoload zkbd' to work,  the  zkdb
       file must be in one of the directories named in your fpath
       array (see zshparam(1)).  This should already be the  case
       if  you  have  a  standard zsh installation; if it is not,
       copy Functions/Misc/zkbd to an appropriate directory.

   Dumping Shell State
       Occasionally you may encounter what appears to be a bug in
       the shell, particularly if you are using a beta version of
       zsh or a development release.  Usually it is sufficient to
       send  a description of the problem to one of the zsh mail­
       ing lists (see zsh(1)),  but  sometimes  one  of  the  zsh
       developers will need to recreate your environment in order
       to track the problem down.

       The script named reporter, found in the Util directory  of
       the  distribution,  is  provided for this purpose.  (It is
       also possible to autoload reporter, but  reporter  is  not
       installed  in  fpath  by  default.)  This script outputs a
       detailed dump of the shell state, in the form  of  another
       script  that  can  be  read with `zsh -f' to recreate that

       To use reporter, read the script into your shell with  the
       `.'  command and redirect the output into a file:

              . ~/zsh-4.1.1/Util/reporter > zsh.report

       You  should  check  the  zsh.report file for any sensitive
       information such as passwords  and  delete  them  by  hand
       before sending the script to the developers.  Also, as the
       As is usual with automated tools, if you create a  startup
       file  with reporter, you should edit the results to remove
       unnecessary commands.  Note that if you're using  the  new
       completion system, you should not dump the functions state
       to your startup files  with  reporter;  use  the  compdump
       function instead (see zshcompsys(1)).

       reporter [ state ... ]
              Print  to  standard  output the indicated subset of
              the current shell state.  The state  arguments  may
              be one or more of:

              all    Output everything listed below.
                     Output alias definitions.
                     Output ZLE key maps and bindings.
                     Output old-style compctl commands.  New com­
                     pletion is covered by functions and zstyles.
                     Output autoloads and function definitions.
              limits Output limit commands.
                     Output setopt commands.
              styles Same as zstyles.
                     Output  shell  parameter  assignments,  plus
                     export commands for  any  environment  vari­
                     Output zstyle commands.

              If the state is omitted, all is assumed.

       With  the  exception of `all', every state can be abbrevi­
       ated by any prefix, even a single letter; thus  a  is  the
       same as aliases, z is the same as zstyles, etc.


       You  should  make  sure  all  the functions from the Func­
       tions/Prompts directory of  the  source  distribution  are
       available; they all begin with the string `prompt_' except
       for the special function`promptinit'.  You also  need  the
       `colors' function from Functions/Misc.  All of these func­
       tions may already have been installed on your  system;  if
       not, you will need to find them and copy them.  The direc­
       tory 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 promptinit should be
       call  to  promptinit  in  order  to start zsh with a theme
       already selected.

       prompt [ -c | -l ]
       prompt [ -p | -h ] [ theme ... ]
       prompt [ -s ] theme [ arg ... ]
              Set or examine the prompt theme.  With  no  options
              and  a  theme argument, the theme with that name is
              set as the current theme.  The available themes are
              determined  at run time; use the -l option to see a
              list.  The special theme `random' selects at random
              one of the available themes and sets your prompt to

              In some cases the theme may be modified by  one  or
              more  arguments,  which  should  be given after the
              theme name.   See  the  help  for  each  theme  for
              descriptions of these arguments.

              Options are:

              -c     Show  the  currently  selected theme and its
                     parameters, if any.
              -l     List all available prompt themes.
              -p     Preview the theme named  by  theme,  or  all
                     themes if no theme is given.
              -h     Show  help  for the theme named by theme, or
                     for the  prompt  function  if  no  theme  is
              -s     Set  theme  as  the  current  theme and save

              Each available theme has a setup function which  is
              called  by  the  prompt  function  to  install that
              theme.  This function may define other functions as
              necessary  to  maintain the prompt, including func­
              tions used to preview the prompt  or  provide  help
              for  its  use.   You  should  not  normally  call a
              theme's setup function directly.


       These functions all  implement  user-defined  ZLE  widgets
       (see zshzle(1)) which can be bound to keystrokes in inter­
       active shells.  To use them, your  .zshrc  should  contain
       lines of the form

              autoload function
              zle -N function

       forward-word-match, backward-word-match
       kill-word-match, backward-kill-word-match
       transpose-words-match, capitalize-word-match
       up-case-word-match, down-case-word-match
       select-word-style, match-word-by-style
              The eight `-match' functions are  drop-in  replace­
              ments  for  the builtin widgets without the suffix.
              By default they behave in a similar way.   However,
              by   the   use   of   styles   and   the   function
              select-word-style, the way words are matched can be

              The simplest way of configuring the functions is to
              use select-word-style, which can either  be  called
              as a normal function with the appropriate argument,
              or invoked  as  a  user-defined  widget  that  will
              prompt for the first character of the word style to
              be used.  The first time it is invoked,  the  eight
              -match  functions  will  automatically  replace the
              builtin versions, so they do not need to be  loaded

              The word styles available are as follows.  Only the
              first character is examined.

              bash   Word characters are alphanumeric  characters

              normal As  in normal shell operation:  word charac­
                     ters are alphanumeric  characters  plus  any
                     characters  present  in  the string given by
                     the parameter $WORDCHARS.

              shell  Words are complete shell command  arguments,
                     possibly  including complete quoted strings,
                     or any tokens special to the shell.

                     Words are any set of characters delimited by

                     Restore  the  default settings; this is usu­
                     ally the same as `normal'.

              More control can be obtained using the zstyle  com­
              mand, as described in zshmodules(1).  Each style is
              looked up in the context :zle:widget  where  widget
              is  the  name  of  the user-defined widget, not the
              name of the function implementing  it,  so  in  the

                     Similar to normal, but  only  the  specified
                     characters,  and not also alphanumerics, are
                     considered word characters.

                     The negation of specified.  The given  char­
                     acters  are  those which will not be consid­
                     ered part of a word.

              shell  Words are obtained by  using  the  syntactic
                     rules  for  generating  shell  command argu­
                     ments.  In addition,  special  tokens  which
                     are never command arguments such as `()' are
                     also treated as words.

                     Words are  whitespace-delimited  strings  of

              The  first three of those styles usually use $WORD­
              CHARS, but the value in the parameter can be  over­
              ridden  by  the  style  word-chars,  which works in
              exactly the same way as $WORDCHARS.   In  addition,
              the style word-class uses character class syntax to
              group  characters   and   takes   precedence   over
              word-chars  if  both are set.  The word-class style
              does not include the surrounding  brackets  of  the
              character  class;  for  example, `-:[:alnum:]' is a
              valid word-class to include all alphanumerics  plus
              the  characters  `-' and `:'.  Be careful including
              `]', `^' and `-' as these are special inside  char­
              acter classes.

              The final style is skip-chars.  This is mostly use­
              ful for transpose-words and similar functions.   If
              set, it gives a count of characters starting at the
              cursor position which will not be  considered  part
              of the word and are treated as space, regardless of
              what they actually are.  For example, if

                     zstyle ':zle:transpose-words' skip-chars 1

              has been set, and transpose-words-match  is  called
              with the cursor on the X of fooXbar, where X can be
              any character, then  the  resulting  expression  is

              The  word  matching  and all the handling of zstyle
              settings is actually implemented  by  the  function
              match-word-by-style.   This  can  be used to create
              of the elements may be an empty string; the calling
              function  should test for this to decide whether it
              can perform its function.

              This   widget   works   like   a   combination   of
              insert-last-word      and     copy-prev-shell-word.
              Repeated invocations of the widget retrieve earlier
              words on the relevant history line.  With a numeric
              argument N, insert the Nth word  from  the  history
              line;  N  may  be negative to count from the end of
              the line.

              If insert-last-word has been used to  retrieve  the
              last  word  on  a  previous  history line, repeated
              invocations will replace  that  word  with  earlier
              words from the same line.

              Otherwise,  the widget applies to words on the line
              currently being edited.  The widget  style  can  be
              set  to  the  name of another widget that should be
              called to retrieve words.  This widget must  accept
              the same three arguments as insert-last-word.

              After inserting an unambiguous string into the com­
              mand line, the new function based completion system
              may know about multiple places in this string where
              characters are missing or differ from at least  one
              of  the  possible  matches.  It will then place the
              cursor on the position it considers to be the  most
              interesting  one, i.e. the one where one can disam­
              biguate between as many matches as possible with as
              little typing as possible.

              This widget allows the cursor to be easily moved to
              the other interesting spots.   It  can  be  invoked
              repeatedly  to cycle between all positions reported
              by the completion system.

              Edit the command line using your visual editor,  as
              in ksh.

                     bindkey -M vicmd v edit-command-line

              This function implements the widgets history-begin­
              ning-search-backward-end     and     history-begin­
              ning-search-forward-end.   These  commands  work by
              first calling the corresponding builtin widget (see
              `History Control' in zshzle(1)) and then moving the
                     bindkey '\e^P' history-beginning-search-backward-end
                     bindkey '\e^N' history-beginning-search-forward-end

       up-line-or-beginning-search, down-line-or-beginning-search
              These widgets are similar to the builtin  functions
              up-line-or-search and down-line-or-search:  if in a
              multiline buffer they move up or  down  within  the
              buffer,  otherwise  they  search for a history line
              matching the start of the current  line.   In  this
              case, however, they search for a line which matches
              the current line up to the current cursor position,
              in  the manner of history-beginning-search-backward
              and -forward, rather than the  first  word  on  the

       incarg Typing the keystrokes for this widget with the cur­
              sor placed on or to the left of an  integer  causes
              that  integer  to  be  incremented  by one.  With a
              numeric prefix argument, the number is  incremented
              by  the  amount of the argument (decremented if the
              prefix argument is negative).  The shell  parameter
              incarg  may  be set to change the default increment
              something other than one.

                     bindkey '^X+' incarg

              This  allows  incremental  completion  of  a  word.
              After  starting  this command, a list of completion
              choices can be  shown  after  every  character  you
              type,  which you can delete with ^H or DEL.  Press­
              ing  return  accepts  the  completion  so  far  and
              returns you to normal editing (that is, the command
              line is not immediately executed).  You can hit TAB
              to  do  normal  completion, ^G to abort back to the
              state when you started, and ^D to list the matches.

              This works only with the new function based comple­
              tion system.

                     bindkey '^Xi' incremental-complete-word

              This function allows you type a file  pattern,  and
              see  the  results  of  the  expansion at each step.
              When you hit return, all  expansions  are  inserted
              into the command line.

                     bindkey '^Xf' insert-files

       narrow-to-region [ -p pre ] [ -P post ]
           [ -S statepm | -R statepm ] [ -n ] [ start end ])
              to replace the text before and  after  the  display
              for  the  duration  of the function; either or both
              may be an empty string.

              If the option -n is also given, pretext or posttext
              will  only  be  inserted if there is text before or
              after the region respectively which  will  be  made

              Two  numeric  arguments  may be given which will be
              used instead of the cursor and mark positions.

              The option -S statepm is used to  narrow  according
              to  the  other  options  while  saving the original
              state in the parameter with name statepm, while the
              option -R statepm is used to restore the state from
              the parameter; note in both cases the name  of  the
              parameter  is  required.  In the second case, other
              options and arguments are  irrelevant.   When  this
              method is used, no recursive-edit is performed; the
              calling widget should call this function  with  the
              option  -S,  perform its own editing on the command
              line or pass control to the user  via  `zle  recur­
              sive-edit', then call this function with the option
              -R.  The argument statepm must be a  suitable  name
              for  an  ordinary parameter, except that parameters
              beginning with the prefix _ntr_  are  reserved  for
              use within narrow-to-region.  Typically the parame­
              ter will be local to the calling function.

              narrow-to-region-invisible is a simple widget which
              calls narrow-to-region with arguments which replace
              any text outside the region with `...'.

              The display is restored (and  the  widget  returns)
              upon  any zle command which would usually cause the
              line to be accepted or  aborted.   Hence  an  addi­
              tional  such command is required to accept or abort
              the current line.

              The return status of both widgets is  zero  if  the
              line was accepted, else non-zero.

              Here  is  a  trivial example of a widget using this
                     local state
                     narrow-to-region -p $'Editing restricted region\n' \
                       -P '' -S state
                     zle recursive-edit
                     narrow-to-region -R state

              needed for this), you should be able to type TAB at
              almost  any point to advance the cursor to the next
              ``interesting'' character position (usually the end
              of the current word, but sometimes somewhere in the
              middle of the word).  And of course as soon as  the
              entire  line  is what you want, you can accept with
              return, without needing to move the cursor  to  the
              end first.

              The  first time predict-on is used, it creates sev­
              eral additional widget functions:

                     Replaces  the  backward-delete-char  widget.
                     You do not need to bind this yourself.
                     Implements  predictive  typing  by replacing
                     the self-insert widget.  You do not need  to
                     bind this yourself.
                     Turns off predictive typing.

              Although you autoload only the predict-on function,
              it is necessary to create  a  keybinding  for  pre­
              dict-off as well.

                     zle -N predict-on
                     zle -N predict-off
                     bindkey '^X^Z' predict-on
                     bindkey '^Z' predict-off

              This  is most useful when called as a function from
              inside a widget, but will work correctly as a  wid­
              get in its own right.  It prompts for a value below
              the current command line;  a  value  may  be  input
              using  all  of the standard zle operations (and not
              merely the restricted set available when executing,
              for example, execute-named-cmd).  The value is then
              returned to the calling function in  the  parameter
              $REPLY  and the editing buffer restored to its pre­
              vious state.  If the read was aborted by a keyboard
              break (typically ^G), the function returns status 1
              and $REPLY is not set.  If an argument is  supplied
              to  the function it is taken as a prompt, otherwise
              `? ' is used.

              One option is available: `-k  num'  specifies  that
              num  characters  are  to be read instead of a whole
              line.  The line editor is not  invoked  recursively
              in  this  case.   Note that unlike the read builtin
              num must be given; there is no default.
              example by defining the widget  using  the  command
              `zle  -N  replace-pattern replace-string', then the
              replacement is done by pattern matching.   All  zsh
              extended  globbing  patterns  can  be  used  in the
              source string; note that unlike filename generation
              the  pattern does not need to match an entire word,
              nor do glob qualifiers have any effect.   In  addi­
              tion,  the replacement string can contain parameter
              or command substitutions.  Furthermore,  a  `&'  in
              the  replacement  string  will be replaced with the
              matched source string, and a backquoted digit  `\N'
              will  be  replaced by the Nth parenthesised expres­
              sion matched.  The form `\{N}' may be used to  pro­
              tect the digit from following digits.

              For example, starting from the line:

                     print This line contains fan and fond

              and invoking replace-pattern with the source string
              `f(?)n' and the replacment string  `c\1r'  produces
              the not very useful line:

                     print This line contains car and cord

              The  range of the replacement string can be limited
              by  using  the  narrow-to-region-invisible  widget.
              One  limitation of the current version is that undo
              will cycle through changes to the  replacement  and
              source   strings  before  undoing  the  replacement

              This function may replace the insert-last-word wid­
              get, like so:

                     zle -N insert-last-word smart-insert-last-word

              With  a numeric prefix, or when passed command line
              arguments in a call from another widget, it behaves
              like  insert-last-word,  except  that words in com­
              ments are ignored when INTERACTIVE_COMMENTS is set.

              Otherwise,  the rightmost ``interesting'' word from
              the previous command is found  and  inserted.   The
              default  definition  of ``interesting'' is that the
              word contains at least  one  alphabetic  character,
              slash,  or backslash.  This definition may be over­
              ridden by use of the match style.  The context used
              to look up the style is the widget name, so usually
              the context is :insert-last-word.  However, you can
              bind this function to different widgets to use dif­
              This style is used by the incremental-complete-word
              widget. Its value should be a pattern, and all keys
              matching this pattern will cause the widget to stop
              incremental completion without the key  having  any
              further  effect.  Like  all styles used directly by
              incremental-complete-word, this style is looked  up
              using the context `:incremental'.

              The  incremental-complete-word  and insert-and-pre­
              dict widgets set up their  top-level  context  name
              before  calling  completion.   This  allows  one to
              define different sets of  completer  functions  for
              normal completion and for these widgets.  For exam­
              ple, to use completion, approximation  and  correc­
              tion  for normal completion, completion and correc­
              tion for incremental completion and only completion
              for prediction one could use:

                     zstyle ':completion:*' completer \
                             _complete _correct _approximate
                     zstyle ':completion:incremental:*' completer \
                             _complete _correct
                     zstyle ':completion:predict:*' completer \

              It  is  a good idea to restrict the completers used
              in prediction, because they  may  be  automatically
              invoked  as  you  type.   The  _list and _menu com­
              pleters should never be used with prediction.   The
              _approximate,  _correct,  _expand,  and _match com­
              pleters may be used, but be  aware  that  they  may
              change  characters  anywhere in the word behind the
              cursor, so you need to  watch  carefully  that  the
              result is what you intended.

       cursor The  insert-and-predict  widget uses this style, in
              the context `:predict', to decide  where  to  place
              the cursor after completion has been tried.  Values

                     The cursor is left where it was when comple­
                     tion  finished,  but  only  if it is after a
                     character equal to the one just inserted  by
                     the user.  If it is after another character,
                     this value is the same as `key'.

              key    The cursor is left after the nth  occurrence
                     of  the  character just inserted, where n is
                     the number of times that character  appeared
                     in the word before completion was attempted.

              The  insert-and-predict  widget  uses this style to
              decide if the completion should be  shown  even  if
              there  is  only  one  possible completion.  This is
              done if the value  of  this  style  is  the  string
              always.   In  this  case  the context is `:predict'
              (not `:completion:predict').

       match  This style is  used  by  smart-insert-last-word  to
              provide a pattern (using full EXTENDED_GLOB syntax)
              that matches an interesting word.  The  context  is
              the     name     of    the    widget    to    which
              smart-insert-last-word is bound (see  above).   The
              default   behavior   of  smart-insert-last-word  is
              equivalent to:

                     zstyle :insert-last-word match '*[[:alpha:]/\\]*'

              However, you might want to include words that  con­
              tain spaces:

                     zstyle :insert-last-word match '*[[:alpha:][:space:]/\\]*'

              Or  include numbers as long as the word is at least
              two characters long:

                     zstyle :insert-last-word match '*([[:digit:]]?|[[:alpha:]/\\])*'

              The above example causes redirections like "2>"  to
              be included.

       prompt The   incremental-complete-word  widget  shows  the
              value of this  style  in  the  status  line  during
              incremental  completion.  The string value may con­
              tain any of the following substrings in the  manner
              of the PS1 and other prompt parameters:

              %c     Replaced  by the name of the completer func­
                     tion that generated the matches (without the
                     leading underscore).

              %l     When  the  list  style  is  set, replaced by
                     `...' if the list of matches is too long  to
                     fit  on  the screen and with an empty string
                     otherwise.  If the list style is `false'  or
                     not set, `%l' is always removed.

              %n     Replaced by the number of matches generated.

              %s     Replaced by `-no match-', `-no prefix-',  or
                     an  empty  string  if there is no completion
                     matching  the  word  on  the  line,  if  the

              for the break-keys style (and uses  the  same  con­
              text:  `:incremental').   However, in this case all
              keys matching the pattern given as its  value  will
              stop  incremental  completion and will then execute
              their usual function.

       toggle This boolean style is used by  predict-on  and  its
              related  widgets in the context `:predict'.  If set
              to one of the standard  `true'  values,  predictive
              typing  is  automatically toggled off in situations
              where it is unlikely to be  useful,  such  as  when
              editing  a  multi-line  buffer or after moving into
              the middle of a line and then deleting a character.
              The  default is to leave prediction turned on until
              an explicit call to predict-off.

              This boolean style is used by  predict-on  and  its
              related  widgets in the context `:predict'.  If set
              to one of the standard `true' values, these widgets
              display a message below the prompt when the predic­
              tive state is toggled.  This is most useful in com­
              bination  with  the toggle style.  The default does
              not display these messages.

       widget This style is similar to  the  command  style:  For
              widget  functions  that  use zle to call other wid­
              gets, this style can sometimes be used to  override
              the  widget  which is called.  The context for this
              style is the name of the calling  widget  (not  the
              name  of the calling function, because one function
              may be bound to multiple widget names).

                     zstyle :copy-earlier-word widget smart-insert-last-word

              Check the documentation for the calling  widget  or
              function  to  determine whether the widget style is


       There are a large number of helpful functions in the Func­
       tions/Misc  directory  of  the zsh distribution.  Most are
       very simple and do not require documentation here,  but  a
       few are worthy of special mention.

       colors This   function   initializes  several  associative
              arrays to map color names to (and  from)  the  ANSI
              standard  eight-color  terminal  codes.   These are
              used by the prompt theme system (see  above).   You
              colors and intensities.

              The associative arrays are:

              colour Map  all  the  color  names to their integer
                     codes, and integer codes to the color names.
                     The  eight  base names map to the foreground
                     color  codes,  as  do  names  prefixed  with
                     `fg-',  such  as  `fg-red'.   Names prefixed
                     with `bg-', such as `bg-blue', refer to  the
                     background  codes.  The reverse mapping from
                     code to color yields  base  name  for  fore­
                     ground  codes  and  the  bg-  form for back­

                     Although it is a misnomer to call them `col­
                     ors',  these arrays also map the other four­
                     teen attributes  from  names  to  codes  and
                     codes to names.

                     Map the eight basic color names to ANSI ter­
                     minal escape sequences that set  the  corre­
                     sponding foreground text properties.  The fg
                     sequences change the color without  changing
                     the eight intensity attributes.

                     Map the eight basic color names to ANSI ter­
                     minal escape sequences that set  the  corre­
                     sponding   background  properties.   The  bg
                     sequences change the color without  changing
                     the eight intensity attributes.

              In  addition, the scalar parameters reset_color and
              bold_color are set to  the  ANSI  terminal  escapes
              that  turn  off  all  attributes  and  turn on bold
              intensity, respectively.

       fned name
              Same as zed -f.  This function does not  appear  in
              the zsh distribution, but can be created by linking
              zed to the name fned  in  some  directory  in  your

       is-at-least needed [ present ]
              Perform  a  greater-than-or-equal-to  comparison of
                     is-at-least 3.1.0 && setopt HIST_REDUCE_BLANKS
                     is-at-least 2.6-17 || print "You can't use is-at-least here."

       nslookup [ arg ... ]
              This  wrapper  function  for  the  nslookup command
              requires the zsh/zpty module  (see  zshmodules(1)).
              It  behaves  exactly  like  the  standard  nslookup
              except  that  it  provides   customizable   prompts
              (including  a  right-side prompt) and completion of
              nslookup commands, host names, etc. (if you use the
              function-based   completion   system).   Completion
              styles may be set with the context prefix `:comple­

              See  also  the  pager,  prompt  and  rprompt styles

              See `Accessing On-Line Help' above.

       tetris Zsh was once accused of not being  as  complete  as
              Emacs, because it lacked a Tetris game.  This func­
              tion was written to refute this vicious slander.

              This function must be used as a ZLE widget:

                     autoload -U tetris
                     zle -N tetris
                     bindkey keys tetris

              To start a game, execute the widget by  typing  the
              keys.   Whatever command line you were editing dis­
              appears temporarily, and your keymap is  also  tem­
              porarily  replaced by the Tetris control keys.  The
              previous editor state is restored when you quit the
              game (by pressing `q') or when you lose.

              If you quit in the middle of a game, the next invo­
              cation of the tetris widget will continue where you
              left off.  If you lost, it will start a new game.

       zcalc [ expression ... ]
              A  reasonably  powerful  calculator  based on zsh's
              arithmetic evaluation facility.  The syntax is sim­
              ilar  to  that of formulae in most programming lan­
              guages; see the section `Arithmetic Evaluation'  in
              zshmisc(1)  for  details.  The mathematical library
              zsh/mathfunc will be loaded if it is available; see
              the  section  `The  zsh/mathfunc Module' in zshmod­
              ules(1).  The mathematical functions correspond  to
              the  raw  system  libraries, so trigonometric func­
              tions are evaluated using radians, and so on.
              the calculator starts.

              The constants PI (3.14159...)  and  E  (2.71828...)
              are  provided.   Parameter  assignment is possible,
              but note that all parameters will be put  into  the
              global namespace.

              An  extra  facility  is  provided  for changing the
              default output base.  Use, for example, `[#16]'  to
              display  hexadecimal  output preceded by an indica­
              tion of the base, or `[##16]' just to  display  the
              raw number in the given base.  Bases themselves are
              always specified in decimal.   `[#]'  restores  the
              normal output format.

              The  output  base can be initialised by passing the
              option `-#base', for example `zcalc -#16' (the  `#'
              may  have  to  be quoted, depending on the globbing
              options set).

              The prompt is configurable via the parameter  ZCAL­
              CPROMPT, which undergoes standard prompt expansion.
              The index of the current entry is stored locally in
              the  first element of the array psvar, which can be
              referred to in ZCALCPROMPT as `%1v'.   The  default
              prompt is `%1v> '.

              See  the  comments  in the function for a few extra

       zed [ -f ] name
              This function uses the ZLE editor to edit a file or
              function.   It  rebinds  the return key to insert a
              line break, and adds bindings  for  `^X^W'  in  the
              emacs keymap and `ZZ' in the vicmd keymap to accept
              (and therefore write, in the case of  a  file)  the
              edited file or function.  Keybindings are otherwise
              the standard ones;  completion  is  available,  and
              styles may be set with the context prefix `:comple­

              Only one name argument  is  recognized  (additional
              arguments are ignored).  If the -f option is given,
              the name is taken to be that of a function; if  the
              function  is  marked  for autoloading, zed searches
              for it in the fpath and loads it.  Note that  func­
              tions  edited  this way are installed into the cur­
              rent shell, but not written back  to  the  autoload

              Without  -f,  name  is the path name of the file to
              edit, which need not exist; it is created on write,
              srcpat  to  corresponding files having names of the
              form given by dest, where srcpat contains parenthe­
              ses  surrounding patterns which will be replaced in
              turn by $1, $2, ... in dest.  For example,

                     zmv '(*).lis' '$1.txt'

              renames `foo.lis' to `foo.txt',  `my.old.stuff.lis'
              to `my.old.stuff.txt', and so on.

              The  pattern  is always treated as an EXTENDED_GLOB
              pattern.  Any file whose name is not changed by the
              substitution  is simply ignored.  Any error (a sub­
              stitution resulted in an empty string, two  substi­
              tutions  gave  the same result, the destination was
              an existing regular file  and  -f  was  not  given)
              causes  the  entire function to abort without doing


              -f     Force overwriting of destination files.  Not
                     currently  passed  down to the mv/cp/ln com­
                     mand due to vagaries of implementations (but
                     you can use -o-f to do that).
              -i     Interactive:  show  each line to be executed
                     and ask the user whether to execute it.  `Y'
                     or  `y'  will execute it, anything else will
                     skip it.  Note that you just  need  to  type
                     one character.
              -n     No  execution:  print what would happen, but
                     don't do it.
              -q     Turn bare glob qualifiers off:  now  assumed
                     by default, so this has no effect.
              -Q     Force  bare  glob qualifiers on.  Don't turn
                     this on unless you are actually  using  glob
                     qualifiers in a pattern.
              -s     Symbolic, passed down to ln; only works with
              -v     Verbose: print each command  as  it's  being
              -w     Pick  out  wildcard parts of the pattern, as
                     described above, and implicitly  add  paren­
                     theses for referring to them.
              -W     Just  like  -w, with the addition of turning
                     wildcards in the  replacement  pattern  into
                     sequential ${1} .. ${N} references.
              -M     Force cp, ln or mv, respectively, regardless
                     of the name of the function.
              -p program
              in Functions/Misc/zmv in the zsh distribution.

              See `Recompiling Functions' above.

       zstyle+ context style value [ + subcontext style value ...
              This makes defining styles a bit simpler by using a
              single  `+'  as  a special token that allows you to
              append a context name to the previously  used  con­
              text name.  Like this:

                     zstyle+ ':foo:bar' style1 value1 \
                           + ':baz'     style2 value2 \
                           + ':frob'    style3 value3

              This defines `style1' with `value1' for the context
              :foo:bar as usual, but  it  also  defines  `style2'
              with  `value2'  for  the  context  :foo:bar:baz and
              `style3' with `value3' for :foo:bar:frob.  Any sub­
              context may be the empty string to re-use the first
              context unchanged.

              The zed function sets this style in context  `:com­
              pletion:zed:*'  to  turn off completion when TAB is
              typed at the beginning of a line.  You may override
              this by setting your own value for this context and

       pager  The nslookup function looks up this  style  in  the
              context  `:nslookup'  to determine the program used
              to display output that does not  fit  on  a  single

              The  nslookup  function  looks up this style in the
              context `:nslookup'  to  set  the  prompt  and  the
              right-side  prompt, respectively.  The usual expan­
              sions for the PS1 and RPS1 parameters may  be  used
ZSHALL(1)                                               ZSHALL(1)

              (see zshmisc(1)).


       IEEE  Standard for information Technology - Portable Oper­
       ating System Interface (POSIX) - Part 2: Shell and  Utili­
       ties, IEEE Inc, 1993, ISBN 1-55937-255-9.

zsh 4.1.1                 June 18, 2003                 ZSHALL(1)



Security Code
Security Code
Type Security Code

Don't have an account yet? You can create one. As a registered user you have some advantages like theme manager, comments configuration and post comments with your name.

Help if you can!

Amazon Wish List

Did You Know?
The Linux Tutorial welcomes your suggestions and ideas.


Tell a Friend About Us

Bookmark and Share

Web site powered by PHP-Nuke

Is this information useful? At the very least you can help by spreading the word to your favorite newsgroups, mailing lists and forums.
All logos and trademarks in this site are property of their respective owner. The comments are property of their posters. Articles are the property of their respective owners. Unless otherwise stated in the body of the article, article content (C) 1994-2013 by James Mohr. All rights reserved. The stylized page/paper, as well as the terms "The Linux Tutorial", "The Linux Server Tutorial", "The Linux Knowledge Base and Tutorial" and "The place where you learn Linux" are service marks of James Mohr. All rights reserved.
The Linux Knowledge Base and Tutorial may contain links to sites on the Internet, which are owned and operated by third parties. The Linux Tutorial is not responsible for the content of any such third-party site. By viewing/utilizing this web site, you have agreed to our disclaimer, terms of use and privacy policy. Use of automated download software ("harvesters") such as wget, httrack, etc. causes the site to quickly exceed its bandwidth limitation and are therefore expressly prohibited. For more details on this, take a look here

PHP-Nuke Copyright © 2004 by Francisco Burzi. This is free software, and you may redistribute it under the GPL. PHP-Nuke comes with absolutely no warranty, for details, see the license.
Page Generation: 1.08 Seconds